[gtk+] Improve docs about GtkStyleContext padding/border/margin

[Milan Bouchet-Valat <milanbv src gnome org>]

commit 44da5a0094603b5a07527456e90c211d5936ecd7
Author: Milan Bouchet-Valat <nalimilan club fr>
Date:   Sat Jan 8 18:11:59 2011 +0100

    Improve docs about GtkStyleContext padding/border/margin
    
    GTK_STYLE_PROPERTY_BORDER_WIDTH is of style GtkBorder, not gint.
    
    Also make it clearer what the definition and ordering of these 3
    properties is. Reorder them in the header to be more logical.

 gtk/gtkstylecontext.c |    3 +++
 gtk/gtkstylecontext.h |   31 ++++++++++++++++++++-----------
 2 files changed, 23 insertions(+), 11 deletions(-)
---
diff --git a/gtk/gtkstylecontext.c b/gtk/gtkstylecontext.c
index 326364c..9d9cdb2 100644
--- a/gtk/gtkstylecontext.c
+++ b/gtk/gtkstylecontext.c
@@ -3421,6 +3421,7 @@ gtk_style_context_get_border_color (GtkStyleContext *context,
  * @border: (out): return value for the border settings
  *
  * Gets the border for a given state as a #GtkBorder.
+ * See %GTK_STYLE_PROPERTY_BORDER_WIDTH.
  *
  * Since: 3.0
  **/
@@ -3460,6 +3461,7 @@ gtk_style_context_get_border (GtkStyleContext *context,
  * @padding: (out): return value for the padding settings
  *
  * Gets the padding for a given state as a #GtkBorder.
+ * See %GTK_STYLE_PROPERTY_PADDING.
  *
  * Since: 3.0
  **/
@@ -3499,6 +3501,7 @@ gtk_style_context_get_padding (GtkStyleContext *context,
  * @margin: (out): return value for the margin settings
  *
  * Gets the margin for a given state as a #GtkBorder.
+ * See %GTK_STYLE_PROPERTY_MARGIN.
  *
  * Since: 3.0
  **/
diff --git a/gtk/gtkstylecontext.h b/gtk/gtkstylecontext.h
index 291b8a7..a2ab473 100644
--- a/gtk/gtkstylecontext.h
+++ b/gtk/gtkstylecontext.h
@@ -79,31 +79,40 @@ struct _GtkStyleContextClass
 #define GTK_STYLE_PROPERTY_FONT "font"
 
 /**
- * GTK_STYLE_PROPERTY_MARGIN:
- *
- * A property holding the rendered element's margin as a #GtkBorder. The
- * margin is defined as the spacing between the border of the element
- * and its surrounding elements.
- */
-#define GTK_STYLE_PROPERTY_MARGIN "margin"
-
-/**
  * GTK_STYLE_PROPERTY_PADDING:
  *
  * A property holding the rendered element's padding as a #GtkBorder. The
  * padding is defined as the spacing between the inner part of the element border
- * and its child.
+ * and its child. It's the innermost spacing property of the padding/border/margin
+ * series.
  */
 #define GTK_STYLE_PROPERTY_PADDING "padding"
 
 /**
  * GTK_STYLE_PROPERTY_BORDER_WIDTH:
  *
- * A property holding the rendered element's border width in pixels as a #gint.
+ * A property holding the rendered element's border width in pixels as
+ * a #GtkBorder. The border is the intermediary spacing property of the
+ * padding/border/margin series.
+ *
+ * gtk_render_frame() uses this property to find out the frame line width,
+ * so #GtkWidget<!-- -->s rendering frames may need to add up this padding when
+ * requesting size
  */
 #define GTK_STYLE_PROPERTY_BORDER_WIDTH "border-width"
 
 /**
+ * GTK_STYLE_PROPERTY_MARGIN:
+ *
+ * A property holding the rendered element's margin as a #GtkBorder. The
+ * margin is defined as the spacing between the border of the element
+ * and its surrounding elements. It is external to #GtkWidget<!-- -->s's
+ * size allocations, and the most external spacing property of the
+ * padding/border/margin series.
+ */
+#define GTK_STYLE_PROPERTY_MARGIN "margin"
+
+/**
  * GTK_STYLE_PROPERTY_BORDER_RADIUS:
  *
  * A property holding the rendered element's border radius in pixels as a #gint.