gtktreeselection: Move documentation to inline comments

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),