[gtk+] gtktreeselection: Move documentation to inline comments

[Javier Jardón <jjardon src gnome org>]

commit 8d3b36d534b6b60031166cbfe3aa15dfdd23e1e9
Author: Javier Jardón <jjardon gnome org>
Date:   Fri Oct 22 22:24:36 2010 +0200

    gtktreeselection: Move documentation to inline comments

 docs/reference/gtk/tmpl/.gitignore            |    1 +
 docs/reference/gtk/tmpl/gtktreeselection.sgml |  280 -------------------------
 gtk/gtktreeselection.c                        |   44 ++++
 gtk/gtktreeselection.h                        |   26 +++
 4 files changed, 71 insertions(+), 280 deletions(-)
---
diff --git a/docs/reference/gtk/tmpl/.gitignore b/docs/reference/gtk/tmpl/.gitignore
index 4058528..27b8d69 100644
--- a/docs/reference/gtk/tmpl/.gitignore
+++ b/docs/reference/gtk/tmpl/.gitignore
@@ -50,6 +50,7 @@ gtktoolbar.sgml
 gtktoolitem.sgml
 gtktooltip.sgml
 gtktreednd.sgml
+gtktreeselection.sgml
 gtktreesortable.sgml
 gtktreestore.sgml
 gtktreeviewcolumn.sgml
diff --git a/gtk/gtktreeselection.c b/gtk/gtktreeselection.c
index 000f71e..5ae0866 100644
--- a/gtk/gtktreeselection.c
+++ b/gtk/gtktreeselection.c
@@ -26,6 +26,41 @@
 #include "gtkintl.h"
 
 
+/**
+ * SECTION:gtktreeselection
+ * @Short_description: The selection object for GtkTreeView
+ * @Title: GtkTreeSelection
+ * @See_also: #GtkTreeView, #GtkTreeViewColumn, #GtkTreeDnd, #GtkTreeMode,
+ *   #GtkTreeSortable, #GtkTreeModelSort, #GtkListStore, #GtkTreeStore,
+ *   #GtkCellRenderer, #GtkCellEditable, #GtkCellRendererPixbuf,
+ *   #GtkCellRendererText, #GtkCellRendererToggle
+ *
+ * The #GtkTreeSelection object is a helper object to manage the selection
+ * for a #GtkTreeView widget.  The #GtkTreeSelection object is
+ * automatically created when a new #GtkTreeView widget is created, and
+ * cannot exist independentally of this widget.  The primary reason the
+ * #GtkTreeSelection objects exists is for cleanliness of code and API.
+ * That is, there is no conceptual reason all these functions could not be
+ * methods on the #GtkTreeView widget instead of a separate function.
+ *
+ * The #GtkTreeSelection object is gotten from a #GtkTreeView by calling
+ * gtk_tree_view_get_selection().  It can be manipulated to check the
+ * selection status of the tree, as well as select and deselect individual
+ * rows.  Selection is done completely view side.  As a result, multiple
+ * views of the same model can have completely different selections.
+ * Additionally, you cannot change the selection of a row on the model that
+ * is not currently displayed by the view without expanding its parents
+ * first.
+ *
+ * One of the important things to remember when monitoring the selection of
+ * a view is that the #GtkTreeSelection::changed signal is mostly a hint.
+ * That is,it may only emit one signal when a range of rows is selected.
+ * Additionally, it may on occasion emit a #GtkTreeSelection::changed signal
+ * when nothing has happened (mostly as a result of programmers calling
+ * select_row on an already selected row).
+ */
+
+
 static void gtk_tree_selection_finalize          (GObject               *object);
 static gint gtk_tree_selection_real_select_all   (GtkTreeSelection      *selection);
 static gint gtk_tree_selection_real_unselect_all (GtkTreeSelection      *selection);
@@ -54,6 +89,15 @@ gtk_tree_selection_class_init (GtkTreeSelectionClass *class)
   object_class->finalize = gtk_tree_selection_finalize;
   class->changed = NULL;
 
+  /**
+   * GtkTreeSelection::changed:
+   * @treeselection: the object which received the signal.
+   *
+   * Emitted whenever the selection has (possibly) changed. Please note that
+   * this signal is mostly a hint.  It may only be emitted once when a range
+   * of rows are selected, and it may occasionally be emitted when nothing
+   * has happened.
+   */
   tree_selection_signals[CHANGED] =
     g_signal_new (I_("changed"),
 		  G_OBJECT_CLASS_TYPE (object_class),
diff --git a/gtk/gtktreeselection.h b/gtk/gtktreeselection.h
index 267a2af..38a1f70 100644
--- a/gtk/gtktreeselection.h
+++ b/gtk/gtktreeselection.h
@@ -36,11 +36,37 @@ G_BEGIN_DECLS
 #define GTK_IS_TREE_SELECTION_CLASS(klass)	(G_TYPE_CHECK_CLASS_TYPE ((klass), GTK_TYPE_TREE_SELECTION))
 #define GTK_TREE_SELECTION_GET_CLASS(obj)	(G_TYPE_INSTANCE_GET_CLASS ((obj), GTK_TYPE_TREE_SELECTION, GtkTreeSelectionClass))
 
+/**
+ * GtkTreeSelectionFunc:
+ * @selection: A #GtkTreeSelection
+ * @model: A #GtkTreeModel being viewed
+ * @path: The #GtkTreePath of the row in question
+ * @path_currently_selected: %TRUE, if the path is currently selected
+ * @data: user data
+ *
+ * A function used by gtk_tree_selection_set_select_function() to filter
+ * whether or not a row may be selected.  It is called whenever a row's
+ * state might change.  A return value of %TRUE indicates to @selection
+ * that it is okay to change the selection.
+ *
+ * Returns: %TRUE, if the selection state of the row can be toggled
+ */
 typedef gboolean (* GtkTreeSelectionFunc)    (GtkTreeSelection  *selection,
 					      GtkTreeModel      *model,
 					      GtkTreePath       *path,
                                               gboolean           path_currently_selected,
 					      gpointer           data);
+
+/**
+ * GtkTreeSelectionForeachFunc:
+ * @model: The #GtkTreeModel being viewed
+ * @path: The #GtkTreePath of a selected row
+ * @iter: A #GtkTreeIter pointing to a selected row
+ * @data: user data
+ *
+ * A function used by gtk_tree_selection_selected_foreach() to map all
+ * selected rows.  It will be called on every selected row in the view.
+ */
 typedef void (* GtkTreeSelectionForeachFunc) (GtkTreeModel      *model,
 					      GtkTreePath       *path,
 					      GtkTreeIter       *iter,