[gtksourceview/wip/gutter: 3/4] Gutter: improve documentation

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

commit 185a42608e3c2350634925ffbcbfb14679395c47
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Tue Sep 3 13:20:18 2013 +0200

    Gutter: improve documentation
    
    The FIXMEs will be fixed progressively, as I better understand the code.

 gtksourceview/gtksourcegutter.c |   29 +++++++++++++++++++----------
 1 files changed, 19 insertions(+), 10 deletions(-)
---
diff --git a/gtksourceview/gtksourcegutter.c b/gtksourceview/gtksourcegutter.c
index 6585b83..13f548b 100644
--- a/gtksourceview/gtksourcegutter.c
+++ b/gtksourceview/gtksourcegutter.c
@@ -33,13 +33,15 @@
  * SECTION:gutter
  * @Short_description: Gutter object for #GtkSourceView
  * @Title: GtkSourceGutter
- * @See_also:#GtkSourceView
+ * @See_also: #GtkSourceView, #GtkSourceMark
  *
- * The #GtkSourceGutter object represents the left and right gutters of the text
- * view. It is used by #GtkSourceView to draw the line numbers and category
- * marks that might be present on a line. By packing additional #GtkSourceGutterRenderer
- * objects in the gutter, you can extend the gutter with your own custom
- * drawings.
+ * The #GtkSourceGutter object represents the left or right gutter of the text
+ * view. It is used by #GtkSourceView to draw the line numbers and
+ * #GtkSourceMark<!-- -->s that might be present on a line. By packing
+ * additional #GtkSourceGutterRenderer objects in the gutter, you can extend the
+ * gutter with your own custom drawings.
+ *
+ * To get a #GtkSourceGutter, use the gtk_source_view_get_gutter() function.
  *
  * The gutter works very much the same way as cells rendered in a #GtkTreeView.
  * The concept is similar, with the exception that the gutter does not have an
@@ -47,8 +49,8 @@
  * #GTK_SOURCE_VIEW_GUTTER_POSITION_LINES (-30) and the marks renderer is at
  * #GTK_SOURCE_VIEW_GUTTER_POSITION_MARKS (-20). You can use these values to
  * position custom renderers accordingly.
- *
  */
+/* FIXME: document whether a lower position means more on the left. */
 
 /* Properties */
 enum
@@ -538,7 +540,7 @@ gtk_source_gutter_class_init (GtkSourceGutterClass *klass)
        /**
         * GtkSourceGutter:view:
         *
-        * The #GtkSourceView of the gutter
+        * The #GtkSourceView of the gutter.
         */
        g_object_class_install_property (object_class,
                                         PROP_VIEW,
@@ -554,7 +556,7 @@ gtk_source_gutter_class_init (GtkSourceGutterClass *klass)
        /**
         * GtkSourceGutter:window-type:
         *
-        * The text window type on which the window is placed
+        * The text window type on which the window is placed.
         */
        g_object_class_install_property (object_class,
                                         PROP_WINDOW_TYPE,
@@ -565,6 +567,7 @@ gtk_source_gutter_class_init (GtkSourceGutterClass *klass)
                                                            0,
                                                            G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
 
+       /* FIXME: document the property */
        g_object_class_install_property (object_class,
                                         PROP_XPAD,
                                         g_param_spec_int ("xpad",
@@ -575,7 +578,7 @@ gtk_source_gutter_class_init (GtkSourceGutterClass *klass)
                                                           0,
                                                           G_PARAM_READWRITE | G_PARAM_CONSTRUCT));
 
-
+       /* FIXME: document the property */
        g_object_class_install_property (object_class,
                                         PROP_YPAD,
                                         g_param_spec_int ("ypad",
@@ -649,6 +652,7 @@ gtk_source_gutter_new (GtkSourceView     *view,
  *
  * Since: 2.8
  */
+/* FIXME: document why this function is useful. */
 GdkWindow *
 gtk_source_gutter_get_window (GtkSourceGutter *gutter)
 {
@@ -1582,6 +1586,7 @@ on_view_style_updated (GtkSourceView   *view,
        gtk_source_gutter_queue_draw (gutter);
 }
 
+/* FIXME: document this function. */
 void
 gtk_source_gutter_set_padding (GtkSourceGutter *gutter,
                                gint             xpad,
@@ -1595,6 +1600,7 @@ gtk_source_gutter_set_padding (GtkSourceGutter *gutter,
        }
 }
 
+/* FIXME: document this function. */
 void
 gtk_source_gutter_get_padding (GtkSourceGutter *gutter,
                                gint            *xpad,
@@ -1623,6 +1629,9 @@ gtk_source_gutter_get_padding (GtkSourceGutter *gutter,
  *
  * Returns: (transfer none): the renderer at (x, y) or %NULL.
  */
+/* FIXME: to insert a renderer in a gutter, only one position is needed. Here to
+ * retrieve a renderer, two positions are needed? Document why.
+ */
 GtkSourceGutterRenderer *
 gtk_source_gutter_get_renderer_at_pos (GtkSourceGutter *gutter,
                                        gint             x,