docs: move documentation to inline comments: GtkTreeView

docs/reference/gtk/tmpl/.gitignore

@@ -58,6 +58,7 @@ gtktreemodelfilter.sgml
 gtktreeselection.sgml
 gtktreesortable.sgml
 gtktreestore.sgml
+gtktreeview.sgml
 gtktreeviewcolumn.sgml
 gtktypeutils.sgml
 gtkwindow.sgml

gtk/gtkenums.h

@@ -509,6 +509,15 @@ typedef enum
   GTK_UNIT_MM
 } GtkUnit;
 
+/**
+ * GtkTreeViewGridLines:
+ * @GTK_TREE_VIEW_GRID_LINES_NONE: No grid lines.
+ * @GTK_TREE_VIEW_GRID_LINES_HORIZONTAL: Horizontal grid lines.
+ * @GTK_TREE_VIEW_GRID_LINES_VERTICAL: Vertical grid lines.
+ * @GTK_TREE_VIEW_GRID_LINES_BOTH: Horizontal and vertical grid lines.
+ *
+ * Used to indicate which grid lines to draw in a tree view.
+ */
 typedef enum
 {
   GTK_TREE_VIEW_GRID_LINES_NONE,

gtk/gtktreeview.c

@@ -48,6 +48,90 @@
 #include "gtkprivate.h"
 #include "gtkwidgetprivate.h"
 
+
+/**
+ * SECTION:gtktreeview
+ * @Short_description: A widget for displaying both trees and lists
+ * @Title: GtkTreeView
+ * @See_also: #GtkTreeViewColumn, #GtkTreeSelection, #GtkTreeDnd, #GtkTreeMode,
+ *   #GtkTreeSortable, #GtkTreeModelSort, #GtkListStore, #GtkTreeStore,
+ *   #GtkCellRenderer, #GtkCellEditable, #GtkCellRendererPixbuf,
+ *   #GtkCellRendererText, #GtkCellRendererToggle
+ *
+ * Widget that displays any object that implements the #GtkTreeModel interface.
+ *
+ * Please refer to the <link linkend="TreeWidget">tree widget conceptual
+ * overview</link> for an overview of all the objects and data types related
+ * to the tree widget and how they work together.
+ *
+ * Several different coordinate systems are exposed in the GtkTreeView API.
+ * These are:
+ *
+ * <inlinegraphic fileref="tree-view-coordinates.png" format="PNG"></inlinegraphic>
+ * <variablelist><title>Coordinate systems in GtkTreeView API</title>
+ * <varlistentry><term>Widget coordinates</term>
+ * <listitem>
+ * <para>
+ * Coordinates relative to the widget (usually <literal>widget->window</literal>).
+ * </para>
+ * </listitem>
+ * </varlistentry>
+ * <varlistentry><term>Bin window coordinates</term>
+ * <listitem>
+ * <para>
+ * Coordinates relative to the window that GtkTreeView renders to.
+ * </para>
+ * </listitem>
+ * </varlistentry>
+ * <varlistentry><term>Tree coordinates</term>
+ * <listitem>
+ * <para>
+ * Coordinates relative to the entire scrollable area of GtkTreeView. These
+ * coordinates start at (0, 0) for row 0 of the tree.
+ * </para>
+ * </listitem>
+ * </varlistentry>
+ * </variablelist>
+ *
+ * Several functions are available for converting between the different
+ * coordinate systems.  The most common translations are between widget and bin
+ * window coordinates and between bin window and tree coordinates. For the
+ * former you can use gtk_tree_view_convert_widget_to_bin_window_coords()
+ * (and vice versa), for the latter gtk_tree_view_convert_bin_window_to_tree_coords()
+ * (and vice versa).
+ * <refsect2 id="GtkTreeView-BUILDER-UI">
+ * <title>GtkTreeView as GtkBuildable</title>
+ * The GtkTreeView implementation of the GtkBuildable interface accepts
+ * #GtkTreeViewColumn objects as &lt;child&gt; elements and exposes the
+ * internal #GtkTreeSelection in UI definitions.
+ * <example>
+ * <title>A UI definition fragment with GtkTreeView</title>
+ * <programlisting><![CDATA[
+ * <object class="GtkTreeView" id="treeview">
+ *   <property name="model">liststore1</property>
+ *   <child>
+ *     <object class="GtkTreeViewColumn" id="test-column">
+ *       <property name="title">Test</property>
+ *       <child>
+ *         <object class="GtkCellRendererText" id="test-renderer"/>
+ *         <attributes>
+ *           <attribute name="text">1</attribute>
+ *         </attributes>
+ *       </child>
+ *     </object>
+ *   </child>
+ *   <child internal-child="selection">
+ *     <object class="GtkTreeSelection" id="selection">
+ *       <signal name="changed" handler="on_treeview_selection_changed"/>
+ *     </object>
+ *   </child>
+ * </object>
+ * ]]></programlisting>
+ * </example>
+ * </refsect2>
+ */
+
+
 #define GTK_TREE_VIEW_PRIORITY_VALIDATE (GDK_PRIORITY_REDRAW + 5)
 #define GTK_TREE_VIEW_PRIORITY_SCROLL_SYNC (GTK_TREE_VIEW_PRIORITY_VALIDATE + 2)
 #define GTK_TREE_VIEW_TIME_MS_PER_IDLE 30

gtk/gtktreeview.h

@@ -32,7 +32,15 @@
 
 G_BEGIN_DECLS
 
-
+/**
+ * GtkTreeViewDropPosition:
+ * @GTK_TREE_VIEW_DROP_BEFORE: dropped row is inserted before
+ * @GTK_TREE_VIEW_DROP_AFTER: dropped row is inserted after
+ * @GTK_TREE_VIEW_DROP_INTO_OR_BEFORE: dropped row becomes a child or is inserted before
+ * @GTK_TREE_VIEW_DROP_INTO_OR_AFTER: dropped row becomes a child or is inserted after
+ *
+ * An enum for determining where a dropped row goes.
+ */
 typedef enum
 {
   /* drop before/after this row */
@@ -115,20 +123,78 @@ struct _GtkTreeViewClass
   void (*_gtk_reserved8) (void);
 };
 
-
+/**
+ * GtkTreeViewColumnDropFunc:
+ * @tree_view: A #GtkTreeView
+ * @column: The #GtkTreeViewColumn being dragged
+ * @prev_column: A #GtkTreeViewColumn on one side of @column
+ * @next_column: A #GtkTreeViewColumn on the other side of @column
+ * @data: user data
+ *
+ * Function type for determining whether @column can be dropped in a
+ * particular spot (as determined by @prev_column and @next_column).  In
+ * left to right locales, @prev_column is on the left of the potential drop
+ * spot, and @next_column is on the right.  In right to left mode, this is
+ * reversed.  This function should return %TRUE if the spot is a valid drop
+ * spot.  Please note that returning %TRUE does not actually indicate that
+ * the column drop was made, but is meant only to indicate a possible drop
+ * spot to the user.
+ *
+ * Returns: %TRUE, if @column can be dropped in this spot
+ */
 typedef gboolean (* GtkTreeViewColumnDropFunc) (GtkTreeView             *tree_view,
 						GtkTreeViewColumn       *column,
 						GtkTreeViewColumn       *prev_column,
 						GtkTreeViewColumn       *next_column,
 						gpointer                 data);
+
+/**
+ * GtkTreeViewMappingFunc:
+ * @tree_view: A #GtkTreeView
+ * @path: The path that's expanded
+ * @user_data: user data
+ *
+ * Function used for gtk_tree_view_map_expanded_rows().
+ */
 typedef void     (* GtkTreeViewMappingFunc)    (GtkTreeView             *tree_view,
 						GtkTreePath             *path,
 						gpointer                 user_data);
+
+/**
+ * GtkTreeViewSearchEqualFunc:
+ * @model: the #GtkTreeModel being searched
+ * @column: the search column set by gtk_tree_view_set_search_column()
+ * @key: the key string to compare with
+ * @iter: a #GtkTreeIter pointing the row of @model that should be compared
+ *  with @key.
+ * @search_data: user data from gtk_tree_view_set_search_equal_func()
+ *
+ * A function used for checking whether a row in @model matches
+ * a search key string entered by the user. Note the return value
+ * is reversed from what you would normally expect, though it
+ * has some similarity to strcmp() returning 0 for equal strings.
+ *
+ * Returns: %FALSE if the row matches, %TRUE otherwise.
+ */
 typedef gboolean (*GtkTreeViewSearchEqualFunc) (GtkTreeModel            *model,
 						gint                     column,
 						const gchar             *key,
 						GtkTreeIter             *iter,
 						gpointer                 search_data);
+
+/**
+ * GtkTreeViewRowSeparatorFunc:
+ * @model: the #GtkTreeModel
+ * @iter: a #GtkTreeIter pointing at a row in @model
+ * @data: user data
+ *
+ * Function type for determining whether the row pointed to by @iter should
+ * be rendered as a separator. A common way to implement this is to have a
+ * boolean column in the model, whose values the #GtkTreeViewRowSeparatorFunc
+ * returns.
+ *
+ * Returns: %TRUE if the row is a separator
+ */
 typedef gboolean (*GtkTreeViewRowSeparatorFunc) (GtkTreeModel      *model,
 						 GtkTreeIter       *iter,
 						 gpointer           data);