Add comments

sphinx/writers/latex.py

@@ -316,27 +316,44 @@ class ShowUrlsTransform(object):
 
 
 class Table(object):
+    """A table data"""
+
     def __init__(self, node):
         # type: (nodes.table) -> None
         self.header = []                        # type: List[unicode]
         self.body = []                          # type: List[unicode]
-        self.classes = node.get('classes', [])  # type: List[unicode]
-        self.col = 0
-        self.row = 0
         self.colcount = 0
         self.colspec = None                     # type: unicode
         self.colwidths = []                     # type: List[int]
         self.has_problematic = False
         self.has_verbatim = False
         self.caption = None                     # type: List[unicode]
+
+        # current position
+        self.col = 0
+        self.row = 0
+
+        # for internal use
+        self.classes = node.get('classes', [])  # type: List[unicode]
         self.cells = defaultdict(int)           # type: Dict[Tuple[int, int], int]
-        self.cell_id = 0
+                                                # it maps table location to cell_id
+                                                # (cell = rectangular area)
+        self.cell_id = 0                        # last assigned cell_id
 
     def is_longtable(self):
+        """True if and only if table uses longtable environment."""
         # type: () -> bool
         return self.row > 30 or 'longtable' in self.classes
 
     def get_table_type(self):
+        """Returns the LaTeX environment name for the table.
+
+        The class currently supports:
+
+        * longtable
+        * tabular
+        * taburary
+        """
         # type: () -> unicode
         if self.is_longtable():
             return 'longtable'
@@ -350,6 +367,12 @@ class Table(object):
             return 'tabulary'
 
     def get_colspec(self):
+        """Returns a column spec of table.
+
+        This is what LaTeX calls the 'preamble argument' of the used table environment.
+
+        .. note:: the ``\X`` column type specifier is defined in ``sphinx.sty``.
+        """
         # type: () -> unicode
         if self.colspec:
             return self.colspec
@@ -365,6 +388,10 @@ class Table(object):
             return '{|' + ('l|' * self.colcount) + '}\n'
 
     def add_cell(self, height, width):
+        """Adds a new cell to a table.
+
+        It will be located at current position: (``self.row``, ``self.col``).
+        """
         self.cell_id += 1
         for col in range(width):
             for row in range(height):
@@ -372,6 +399,11 @@ class Table(object):
                 self.cells[(self.row + row, self.col + col)] = self.cell_id
 
     def cell(self, row=None, col=None):
+        """Returns a cell object (i.e. rectangular area) containing given position: (``row``, ``col``)
+
+        If no ``row`` or ``col`` are given, the current position; ``self.row`` and
+        ``self.col`` are used to get a cell object by default.
+        """
         try:
             if row is None:
                 row = self.row
@@ -383,6 +415,8 @@ class Table(object):
 
 
 class TableCell(object):
+    """A cell data of tables."""
+
     def __init__(self, table, row, col):
         if table.cells[(row, col)] == 0:
             raise IndexError
@@ -400,6 +434,7 @@ class TableCell(object):
 
     @property
     def width(self):
+        """Returns the cell width."""
         width = 0
         while self.table.cells[(self.row, self.col + width)] == self.cell_id:
             width += 1
@@ -407,6 +442,7 @@ class TableCell(object):
 
     @property
     def height(self):
+        """Returns the cell height."""
         height = 0
         while self.table.cells[(self.row + height, self.col)] == self.cell_id:
             height += 1