Add commments to grid code, plus a small bit of code cleanup. b=306911 r+sr=bzbarsky

layout/xul/base/src/grid/nsGrid.h

@@ -52,6 +52,9 @@ class nsGridCell;
 
 //#define DEBUG_grid 1
 
+/**
+ * The grid data structure, i.e., the grid cellmap.
+ */
 class nsGrid
 {
 public:

layout/xul/base/src/grid/nsGridLayout2.cpp

@@ -65,7 +65,16 @@ nsGridLayout2::nsGridLayout2(nsIPresShell* aPresShell):nsStackLayout()
 NS_IMETHODIMP
 nsGridLayout2::Layout(nsIBox* aBox, nsBoxLayoutState& aBoxLayoutState)
 {
+  // XXX This should be set a better way!
   mGrid.SetBox(aBox);
+#ifdef DEBUG
+  {
+    nsCOMPtr<nsIBoxLayout> lm;
+    aBox->GetLayoutManager(getter_AddRefs(lm));
+    NS_ASSERTION(lm == this, "setting incorrect box");
+  }
+#endif
+
   nsresult rv = nsStackLayout::Layout(aBox, aBoxLayoutState);
 #ifdef DEBUG_grid
   mGrid.PrintCellMap();
@@ -76,7 +85,16 @@ nsGridLayout2::Layout(nsIBox* aBox, nsBoxLayoutState& aBoxLayoutState)
 NS_IMETHODIMP
 nsGridLayout2::GetGrid(nsIBox* aBox, nsGrid** aGrid, PRInt32* aIndex, nsGridRowLayout* aRequestor)
 {
+  // XXX This should be set a better way!
   mGrid.SetBox(aBox);
+#ifdef DEBUG
+  {
+    nsCOMPtr<nsIBoxLayout> lm;
+    aBox->GetLayoutManager(getter_AddRefs(lm));
+    NS_ASSERTION(lm == this, "setting incorrect box");
+  }
+#endif
+
   *aGrid = &mGrid;
   return NS_OK;
 }

layout/xul/base/src/grid/nsGridLayout2.h

@@ -52,6 +52,9 @@ class nsGridRow;
 class nsBoxLayoutState;
 class nsGridCell;
 
+/**
+ * The nsIBoxLayout implementation for a grid.
+ */
 class nsGridLayout2 : public nsStackLayout, 
                       public nsIGridPart
 {

layout/xul/base/src/grid/nsGridRow.h

@@ -50,6 +50,9 @@
 class nsGridLayout2;
 class nsBoxLayoutState;
 
+/**
+ * The row (or column) data structure in the grid cellmap.
+ */
 class nsGridRow
 {
 public:

layout/xul/base/src/grid/nsGridRowGroupFrame.h

@@ -48,6 +48,11 @@
 
 #include "nsBoxFrame.h"
 
+/**
+ * A frame representing a grid row (or column) group, which is an
+ * element that is a child of a grid and contains all the rows (or
+ * all the columns).
+ */
 class nsGridRowGroupFrame : public nsBoxFrame
 {
 public:

layout/xul/base/src/grid/nsGridRowGroupLayout.h

@@ -47,6 +47,9 @@
 
 #include "nsGridRowLayout.h"
 
+/**
+ * The nsIBoxLayout implementation for nsGridRowGroupFrame.
+ */
 class nsGridRowGroupLayout : public nsGridRowLayout
 {
 public:

layout/xul/base/src/grid/nsGridRowLayout.cpp

@@ -82,10 +82,8 @@ nsGridRowLayout::GetParentGridPart(nsIBox* aBox, nsIBox** aParentBox, nsIGridPar
 {
   // go up and find our parent gridRow. Skip and non gridRow
   // parents.
-  nsCOMPtr<nsIBoxLayout> layout;
-  nsCOMPtr<nsIGridPart> parentGridRow;
-  nsresult rv = NS_OK;
   *aParentGridPart = nsnull;
+  *aParentBox = nsnull;
   
   // walk up through any scrollboxes
   aBox = nsGrid::GetScrollBox(aBox);
@@ -96,18 +94,15 @@ nsGridRowLayout::GetParentGridPart(nsIBox* aBox, nsIBox** aParentBox, nsIGridPar
 
   if (aBox)
   {
+      nsCOMPtr<nsIBoxLayout> layout;
       aBox->GetLayoutManager(getter_AddRefs(layout));
-      parentGridRow = do_QueryInterface(layout);
-      *aParentGridPart = parentGridRow.get();
+      nsCOMPtr<nsIGridPart> parentGridRow = do_QueryInterface(layout);
+      parentGridRow.swap(*aParentGridPart);
       *aParentBox = aBox;
-      NS_IF_ADDREF(*aParentGridPart);
       return NS_OK;
   }
 
-  *aParentGridPart = nsnull;
-  *aParentBox = nsnull;
-  
-  return rv;
+  return NS_OK;
 }
 
 

layout/xul/base/src/grid/nsGridRowLayout.h

@@ -53,6 +53,11 @@ class nsBoxLayoutState;
 class nsIPresShell;
 class nsGrid;
 
+/**
+ * A common base class for nsGridRowLeafLayout (the nsIBoxLayout object
+ * for a grid row or column) and nsGridRowGroupLayout (the nsIBoxLayout
+ * object for a grid row group or column group).
+ */
 class nsGridRowLayout : public nsSprocketLayout,
                         public nsIGridPart
 {

layout/xul/base/src/grid/nsGridRowLeafFrame.h

@@ -48,6 +48,11 @@
 
 #include "nsBoxFrame.h"
 
+/**
+ * A frame representing a grid row (or column).  Grid row (and column)
+ * elements are the children of row group (or column group) elements,
+ * and their children are placed one to a cell.
+ */
 class nsGridRowLeafFrame : public nsBoxFrame
 {
 public:

layout/xul/base/src/grid/nsGridRowLeafLayout.cpp

@@ -69,13 +69,6 @@ nsGridRowLeafLayout::~nsGridRowLeafLayout()
 {
 }
 
-NS_IMETHODIMP
-nsGridRowLeafLayout::CastToGridRowLeaf(nsGridRowLeafLayout** aGridRowLeaf)
-{
-  *aGridRowLeaf = this;
-  return NS_OK;
-}
-
 NS_IMETHODIMP
 nsGridRowLeafLayout::GetPrefSize(nsIBox* aBox, nsBoxLayoutState& aState, nsSize& aSize)
 {

layout/xul/base/src/grid/nsGridRowLeafLayout.h

@@ -48,6 +48,9 @@
 #include "nsGridRowLayout.h"
 #include "nsCOMPtr.h"
 
+/**
+ * The nsIBoxLayout implementation for nsGridRowLeafFrame.
+ */
 class nsGridRowLeafLayout : public nsGridRowLayout
 {
 public:
@@ -57,7 +60,6 @@ public:
   NS_IMETHOD GetPrefSize(nsIBox* aBox, nsBoxLayoutState& aBoxLayoutState, nsSize& aSize);
   NS_IMETHOD GetMinSize(nsIBox* aBox, nsBoxLayoutState& aBoxLayoutState, nsSize& aSize);
   NS_IMETHOD GetMaxSize(nsIBox* aBox, nsBoxLayoutState& aBoxLayoutState, nsSize& aSize);
-  NS_IMETHOD CastToGridRowLeaf(nsGridRowLeafLayout** aGridRowLeaf);
   NS_IMETHOD ChildBecameDirty(nsIBox* aBox, nsBoxLayoutState& aState, nsIBox* aChild);
   NS_IMETHOD BecameDirty(nsIBox* aBox, nsBoxLayoutState& aState);
   NS_IMETHOD ChildAddedOrRemoved(nsIBox* aBox, nsBoxLayoutState& aState);

layout/xul/base/src/grid/nsIGridPart.h

@@ -51,6 +51,10 @@ class nsGridLayout2;
 // {AF0C1603-06C3-11d4-BA07-001083023C1E}
 #define NS_IMONUMENT_IID { 0xaf0c1603, 0x6c3, 0x11d4, { 0xba, 0x7, 0x0, 0x10, 0x83, 0x2, 0x3c, 0x1e } }
 
+/**
+ * An additional interface implemented by nsIBoxLayout implementations
+ * for parts of a grid (excluding cells, which are not special).
+ */
 class nsIGridPart : public nsISupports {
 
 public:
@@ -59,8 +63,37 @@ public:
 
   NS_IMETHOD CastToRowGroupLayout(nsGridRowGroupLayout** aRowGroup)=0;
   NS_IMETHOD CastToGridLayout(nsGridLayout2** aGrid)=0;
+
+  /**
+   * @param aBox [IN] The other half of the |this| parameter, i.e., the box
+   *                  whose layout manager is |this|.
+   * @param aList [OUT] The grid of which aBox (a row, row group, or grid)
+   *                    is a part.
+   * @param aIndex [INOUT] For callers not setting aRequestor, the value
+   *                       pointed to by aIndex is incremented by the index
+   *                       of the row (aBox) within its row group; if aBox
+   *                       is not a row/column, it is untouched.
+   *                       The implementation does this by doing the aIndex
+   *                       incrementing in the call to the parent row group
+   *                       when aRequestor is non-null.
+   * @param aRequestor [IN] Non-null if and only if this is a recursive
+   *                   call from the GetGrid method on a child grid part,
+   *                   in which case it is a pointer to that grid part.
+   *                   (This may only be non-null for row groups and
+   *                   grids.)
+   */
   NS_IMETHOD GetGrid(nsIBox* aBox, nsGrid** aList, PRInt32* aIndex, nsGridRowLayout* aRequestor=nsnull)=0;
+
+  /**
+   * @param aBox [IN] The other half of the |this| parameter, i.e., the box
+   *                  whose layout manager is |this|.
+   * @param aParentBox [OUT] The box representing the next level up in
+   *                   the grid (i.e., row group for a row, grid for a
+   *                   row group).
+   * @param aParentGridRow [OUT] The layout manager for aParentBox.
+   */
   NS_IMETHOD GetParentGridPart(nsIBox* aBox, nsIBox** aParentBox, nsIGridPart** aParentGridRow)=0;
+
   NS_IMETHOD CountRowsColumns(nsIBox* aBox, PRInt32& aRowCount, PRInt32& aComputedColumnCount)=0;
   NS_IMETHOD DirtyRows(nsIBox* aBox, nsBoxLayoutState& aState)=0;
   NS_IMETHOD BuildRows(nsIBox* aBox, nsGridRow* aRows, PRInt32* aCount)=0;