Start adding some documentation to LayoutTable

Source/core/layout/LayoutTable.h

Index: Source/core/layout/LayoutTable.h
diff --git a/Source/core/layout/LayoutTable.h b/Source/core/layout/LayoutTable.h
index 442af625c8ff3e2608f901d6024818bbc8a289f2..6e81d049adab89ba17e3eaf9825c9c7fc14f2bec 100644
--- a/Source/core/layout/LayoutTable.h
+++ b/Source/core/layout/LayoutTable.h
@@ -41,6 +41,15 @@ class TableLayoutAlgorithm;
 
 enum SkipEmptySectionsValue { DoNotSkipEmptySections, SkipEmptySections };
 
+// LayoutTable is the LayoutObject associated with <table>.

[mstensho (USE GERRIT), 2015/09/04 13:06:53]

I'd prefer to say something about CSS rather than HTML.

[Julien - ping for review, 2015/09/04 14:36:16]

Makes sense changed to:

// LayoutTable is the LayoutObject associated with display: table.

+//
+// LayoutTable is the master coordinator for determining the overall table
+// structure. The reason is that LayoutTableSection has a local views over

[mstensho (USE GERRIT), 2015/09/04 13:06:53]

"... is that LayoutTableSection children have a local view ..." ?

[Julien - ping for review, 2015/09/04 14:36:16]

Done!

+// what its structure is but doesn't account for other LayoutTableSection.
+// Thus LayoutTable helps keep consistency across LayoutTableSection.
+// See e.g. m_column below.
+//
+// TODO(jchaffraix): Explain more of the class structure.
 class CORE_EXPORT LayoutTable final : public LayoutBlock {
 public:
     explicit LayoutTable(Element*);
@@ -323,6 +332,26 @@ private:
     void recalcCollapsedBordersIfNeeded();
 
     mutable Vector<int> m_columnPos;
+
+    // This Vector holds the columns sizes over the entire table.

[mstensho (USE GERRIT), 2015/09/04 13:06:53]

More like column *count*.

This member had so far escaped my attention, and now I'm sad. But I suppose it
kind of makes sense if someone (man or machine) goes <td
colspan="7734894168798477"> for no reason.

Very good to have this documented!

[Julien - ping for review, 2015/09/04 14:36:16]

Updated.
FYI the colspan is capped at 8k in HTMLTableCellElement so it's not as bad as it
sounds. I have added a comment about it being also a defensive pattern (with the
previous caveats):

// Note that this is also a defensive pattern as <td colspan="6666666666">
// only allocates a single entry in this Vector. This argument is weak
// though as we cap colspans in HTMLTableCellElement.

+    //
+    // To save memory at the expense of massive code complexity, the code tries
+    // to coalesce columns. This means that we try to the wider column grouping
+    // seen over the LayoutTableSections.
+    //
+    // The following example would have 2 ColumnStruct [ 3, 2 ]:
+    // <table>
+    //   <tr>
+    //     <td colspan="3"></td>
+    //     <td colspan="2"></td>
+    //   </tr>
+    // </table>
+    //
+    // Columns can be split if we add a row with a different colspan structure.
+    // See splitColumn and appendColumn for operations over |m_columns|.
+    //
+    // See colToEffCol for converting an absolute column index into an
+    // index into |m_columns|.
     mutable Vector<ColumnStruct> m_columns;
     mutable Vector<LayoutTableCaption*> m_captions;
     mutable Vector<LayoutTableCol*> m_columnLayoutObjects;
@@ -331,6 +360,17 @@ private:
     mutable LayoutTableSection* m_foot;
     mutable LayoutTableSection* m_firstBody;
 
+    // The layout algorithm used by this table.
+    //
+    // CSS 2.1 defines 2 types of table layouts toggled with 'table-layout':
+    // fixed (TableLayoutAlgorithmFixed) and auto (TableLayoutAlgorithmAuto).
+    // See http://www.w3.org/TR/CSS21/tables.html#width-layout.
+    //
+    // The layout algorithm is delegated to TableLayoutAlgorithm. This enables
+    // changing 'table-layout' without having to reattach the <table>.
+    //
+    // As the algorithm is dependent on the style, this field is nullptr before
+    // the first style is applied in styleDidChange().
     OwnPtr<TableLayoutAlgorithm> m_tableLayout;
 
     // A sorted list of all unique border values that we want to paint.