[gtk+/grid-widget] Add some comments

[Matthias Clasen <matthiasc src gnome org>]

commit 66726295f7978aba3b12202729d81eefa605b1c4
Author: Matthias Clasen <mclasen redhat com>
Date:   Sun Oct 10 02:37:59 2010 -0400

    Add some comments

 gtk/gtkgrid.c |   50 +++++++++++++++++++++++++++++++++++---------------
 1 files changed, 35 insertions(+), 15 deletions(-)
---
diff --git a/gtk/gtkgrid.c b/gtk/gtkgrid.c
index 1782e12..e5d03fb 100644
--- a/gtk/gtkgrid.c
+++ b/gtk/gtkgrid.c
@@ -589,6 +589,9 @@ gtk_grid_request_init (GtkGrid        *grid,
     }
 }
 
+/* sums allocations for lines spanned by child and
+ * the spacing between those lines
+ */
 static gint
 compute_allocation_for_span (GtkGrid        *grid,
                              GtkOrientation  orientation,
@@ -645,7 +648,10 @@ compute_request_for_child (GtkGrid        *grid,
     }
 }
 
-/* set requisition to max of non-spanning children */
+/* set requisition to max of non-spanning children.
+ * if contextual is TRUE, requires allocations of
+ * lines in the opposite orientation to be set.
+ */
 static void
 gtk_grid_request_non_spanning (GtkGrid        *grid,
                                GtkOrientation  orientation,
@@ -713,7 +719,10 @@ gtk_grid_request_homogeneous (GtkGrid        *grid,
     }
 }
 
-/* deal with spanning children */
+/* deals with spanning children.
+ * requires expand fields of lines to be set for
+ * non-spanning children.
+ */
 static void
 gtk_grid_request_spanning (GtkGrid        *grid,
                            GtkOrientation  orientation,
@@ -906,6 +915,9 @@ gtk_grid_compute_expand (GtkGrid        *grid,
     *expand_lines = expand;
 }
 
+/* sums the minimum and natural fields of lines and
+ * the spacing between lines
+ */
 static void
 gtk_grid_request_sum (GtkGrid        *grid,
                       GtkOrientation  orientation,
@@ -938,30 +950,28 @@ gtk_grid_request_sum (GtkGrid        *grid,
     *natural = nat;
 }
 
+/* computes minimum and natural fields of lines.
+ * when contextual is TRUE, requires allocation of
+ * lines in the opposite orientation to be set.
+ */
 static void
 gtk_grid_request_lines (GtkGrid        *grid,
                         GtkOrientation  orientation,
-                        gboolean        for_size)
+                        gboolean        contextual)
 {
   gtk_grid_ensure_lines (grid, orientation);
 
   gtk_grid_request_init (grid, orientation);
-  gtk_grid_request_non_spanning (grid, orientation, for_size);
+  gtk_grid_request_non_spanning (grid, orientation, contextual);
   gtk_grid_request_homogeneous (grid, orientation);
-  gtk_grid_request_spanning (grid, orientation, for_size);
+  gtk_grid_request_spanning (grid, orientation, contextual);
   gtk_grid_request_homogeneous (grid, orientation);
 }
 
-static void
-gtk_grid_get_size (GtkGrid        *grid,
-                   GtkOrientation  orientation,
-                   gint           *minimum,
-                   gint           *natural)
-{
-  gtk_grid_request_lines (grid, orientation, FALSE);
-  gtk_grid_request_sum (grid, orientation, minimum, natural);
-}
-
+/* requires that the minimum and natural fields of lines
+ * have been set, computes the allocation field of lines
+ * by distributing total_size among lines
+ */
 static void
 gtk_grid_allocate_lines (GtkGrid        *grid,
                          GtkOrientation  orientation,
@@ -1061,6 +1071,16 @@ gtk_grid_allocate_lines (GtkGrid        *grid,
 }
 
 static void
+gtk_grid_get_size (GtkGrid        *grid,
+                   GtkOrientation  orientation,
+                   gint           *minimum,
+                   gint           *natural)
+{
+  gtk_grid_request_lines (grid, orientation, FALSE);
+  gtk_grid_request_sum (grid, orientation, minimum, natural);
+}
+
+static void
 gtk_grid_get_size_for_orientation (GtkGrid        *grid,
                                    GtkOrientation  orientation,
                                    gint            size,