[gtk+/gtk-3-4] iconview: Add documentation abour different sizes

[Benjamin Otte <otte src gnome org>]

commit a1c8c8af85f55af3017f084175acd5f35c016f30
Author: Benjamin Otte <otte redhat com>
Date:   Wed Jun 13 04:20:06 2012 +0200

    iconview: Add documentation abour different sizes
    
    Did I mention I hate code that has different kinds of "boxes" or
    coordinate systems but no clear way to distinguish them?
    It's all ints here...
    
    https://bugzilla.gnome.org/show_bug.cgi?id=677809

 gtk/gtkiconview.c |   25 +++++++++++++++++++++++++
 1 files changed, 25 insertions(+), 0 deletions(-)
---
diff --git a/gtk/gtkiconview.c b/gtk/gtkiconview.c
index 55c7d80..df40fb6 100644
--- a/gtk/gtkiconview.c
+++ b/gtk/gtkiconview.c
@@ -1393,6 +1393,31 @@ adjust_wrap_width (GtkIconView *icon_view)
     }
 }
 
+/* General notes about layout
+ *
+ * The icon view is layouted like this:
+ *
+ * +----------+  s  +----------+
+ * | padding  |  p  | padding  |
+ * | +------+ |  a  | +------+ |
+ * | | cell | |  c  | | cell | |
+ * | +------+ |  i  | +------+ |
+ * |          |  n  |          |
+ * +----------+  g  +----------+
+ *
+ * In size request and allocation code, there are 3 sizes that are used:
+ * * cell size
+ *   This is the size returned by gtk_cell_area_get_preferred_foo(). In places
+ *   where code is interacting with the cell area and renderers this is useful.
+ * * padded size
+ *   This is the cell size plus the item padding on each side.
+ * * spaced size
+ *   This is the padded size plus the spacing. This is what's used for most
+ *   calculations because it can (ab)use the following formula:
+ *   iconview_size = 2 * margin + n_items * spaced_size - spacing
+ * So when reading this code and fixing my bugs where I confuse these two, be
+ * aware of this distinction.
+ */
 static void
 cell_area_get_preferred_size (GtkIconView        *icon_view,
                               GtkCellAreaContext *context,