[gtksourceview/wip/gutter] Gutter: improve doc

[Sébastien Wilmet <swilmet src gnome org>]

commit eb2be2034abd6cfea0cc6c4d2a446975f9a84eda
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Wed Sep 4 17:01:26 2013 +0200

    Gutter: improve doc

 gtksourceview/gtksourcegutterrenderer.c |   68 ++++++++++++++++++++++++------
 1 files changed, 54 insertions(+), 14 deletions(-)
---
diff --git a/gtksourceview/gtksourcegutterrenderer.c b/gtksourceview/gtksourcegutterrenderer.c
index c080b0e..bc25ae1 100644
--- a/gtksourceview/gtksourcegutterrenderer.c
+++ b/gtksourceview/gtksourcegutterrenderer.c
@@ -25,6 +25,42 @@
 #include "gtksourceview-typebuiltins.h"
 #include "gtksourceview-i18n.h"
 
+/**
+ * SECTION:gutterrenderer
+ * @Short_description: Gutter cell renderer
+ * @Title: GtkSourceGutterRenderer
+ * @See_also: #GtkSourceGutter
+ *
+ * A #GtkSourceGutterRenderer represents a column in a #GtkSourceGutter. The
+ * column contains one cell for each visible line of the #GtkTextBuffer. Due to
+ * text wrapping, a cell can thus span multiple lines of the #GtkTextView. In
+ * this case, #GtkSourceGutterRendererAlignmentMode controls the alignment of
+ * the cell.
+ *
+ * The gutter renderer must announce its #GtkSourceGutterRenderer:size. The
+ * height is determined by the text view height. The width must be determined by
+ * the gutter renderer. The width generally takes into account the entire text
+ * buffer. For instance, to display the line numbers, if the buffer contains 100
+ * lines, the gutter renderer will always set its width such as three digits can
+ * be printed, even if only the first 20 lines are shown. Another strategy is to
+ * take into account only the visible lines.  In this case, only two digits are
+ * necessary to display the line numbers of the first 20 lines. To take another
+ * example, the gutter renderer for #GtkSourceMark<-- -->s doesn't need to take
+ * into account the text buffer to announce its width. It only depends on the
+ * icons size displayed in the gutter column.
+ *
+ * An horizontal and vertical padding can be added with
+ * gtk_source_gutter_renderer_set_padding().  The total width of a gutter
+ * renderer is its size (#GtkSourceGutterRenderer:size) plus two times the
+ * horizontal padding (#GtkSourceGutterRenderer:xpad).
+ *
+ * When the available size to render a cell is greater than the required size to
+ * render the cell contents, the cell contents can be aligned horizontally and
+ * vertically with gtk_source_gutter_renderer_set_alignment().
+ *
+ * The cells rendering occurs in three phases:
+ */
+
 enum
 {
        ACTIVATE,
@@ -473,9 +509,8 @@ gtk_source_gutter_renderer_class_init (GtkSourceGutterRendererClass *klass)
        /**
         * GtkSourceGutterRenderer:xpad:
         *
-        * The x-padding of the renderer.
-        *
-        **/
+        * The left and right padding of the renderer.
+        */
        g_object_class_install_property (object_class,
                                         PROP_XPAD,
                                         g_param_spec_int ("xpad",
@@ -489,9 +524,8 @@ gtk_source_gutter_renderer_class_init (GtkSourceGutterRendererClass *klass)
        /**
         * GtkSourceGutterRenderer:ypad:
         *
-        * The y-padding of the renderer.
-        *
-        **/
+        * The top and bottom padding of the renderer.
+        */
        g_object_class_install_property (object_class,
                                         PROP_YPAD,
                                         g_param_spec_int ("ypad",
@@ -505,9 +539,10 @@ gtk_source_gutter_renderer_class_init (GtkSourceGutterRendererClass *klass)
        /**
         * GtkSourceGutterRenderer:xalign:
         *
-        * The x-alignment of the renderer.
-        *
-        **/
+        * The horizontal alignment of the renderer. Set to 0 for a left
+        * alignment. 1 for a right alignment. And 0.5 for centering the cells.
+        * A value lower than 0 doesn't modify the alignment.
+        */
        g_object_class_install_property (object_class,
                                         PROP_XALIGN,
                                         g_param_spec_float ("xalign",
@@ -521,9 +556,10 @@ gtk_source_gutter_renderer_class_init (GtkSourceGutterRendererClass *klass)
        /**
         * GtkSourceGutterRenderer:yalign:
         *
-        * The y-alignment of the renderer.
-        *
-        **/
+        * The vertical alignment of the renderer. Set to 0 for a top
+        * alignment. 1 for a bottom alignment. And 0.5 for centering the cells.
+        * A value lower than 0 doesn't modify the alignment.
+        */
        g_object_class_install_property (object_class,
                                         PROP_YALIGN,
                                         g_param_spec_float ("yalign",
@@ -1047,7 +1083,8 @@ gtk_source_gutter_renderer_get_visible (GtkSourceGutterRenderer *renderer)
  * -1, which means the values will not be changed (this allows changing only
  * one of the values).
  *
- **/
+ * @xpad is the left and right padding. @ypad is the top and bottom padding.
+ */
 void
 gtk_source_gutter_renderer_set_padding (GtkSourceGutterRenderer *renderer,
                                         gint                     xpad,
@@ -1096,7 +1133,10 @@ gtk_source_gutter_renderer_get_padding (GtkSourceGutterRenderer *renderer,
  * -1, which means the values will not be changed (this allows changing only
  * one of the values).
  *
- **/
+ * @xalign is the horizontal alignment. Set to 0 for a left alignment. 1 for a
+ * right alignment. And 0.5 for centering the cells. @yalign is the vertical
+ * alignment. Set to 0 for a top alignment. 1 for a bottom alignment.
+ */
 void
 gtk_source_gutter_renderer_set_alignment (GtkSourceGutterRenderer *renderer,
                                           gfloat                   xalign,