From 1fb5824e1ef1640d4bdb943402f9afac56d49159 Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Mon, 22 Feb 2021 19:08:24 +0000 Subject: [PATCH] treemodel: Update the description format Also add a description for GtkTreePath. --- gtk/gtktreemodel.c | 27 ++++++++++++++++----------- 1 file changed, 16 insertions(+), 11 deletions(-) diff --git a/gtk/gtktreemodel.c b/gtk/gtktreemodel.c index 0eef6a6474..a330643f45 100644 --- a/gtk/gtktreemodel.c +++ b/gtk/gtktreemodel.c @@ -63,20 +63,20 @@ * Models are accessed on a node/column level of granularity. One can * query for the value of a model at a certain node and a certain * column on that node. There are two structures used to reference a - * particular node in a model. They are the #GtkTreePath-struct and - * the #GtkTreeIter-struct (“iter” is short for iterator). Most of the - * interface consists of operations on a #GtkTreeIter-struct. + * particular node in a model. They are the [struct@Gtk.TreePath] and + * the [struct@Gtk.TreeIter] (“iter” is short for iterator). Most of the + * interface consists of operations on a [struct@Gtk.TreeIter]. * * A path is essentially a potential node. It is a location on a model * that may or may not actually correspond to a node on a specific - * model. The #GtkTreePath-struct can be converted into either an + * model. A [struct@Gtk.TreePath] can be converted into either an * array of unsigned integers or a string. The string form is a list * of numbers separated by a colon. Each number refers to the offset * at that level. Thus, the path `0` refers to the root * node and the path `2:4` refers to the fifth child of * the third node. * - * By contrast, a #GtkTreeIter-struct is a reference to a specific node on + * By contrast, a [struct@Gtk.TreeIter] is a reference to a specific node on * a specific model. It is a generic struct with an integer and three * generic pointers. These are filled in by the model in a model-specific * way. One can convert a path to an iterator by calling @@ -113,9 +113,9 @@ * easier, the second is much more common, as you often get paths from * callbacks. * - * ## Acquiring a #GtkTreeIter-struct + * ## Acquiring a `GtkTreeIter` * - * |[ + * ```c * // Three ways of getting the iter pointing to the location * GtkTreePath *path; * GtkTreeIter iter; @@ -140,7 +140,7 @@ * parent_iter = iter; * gtk_tree_model_iter_nth_child (model, &iter, * &parent_iter, 5); - * ]| + * ``` * * This second example shows a quick way of iterating through a list * and getting a string and an integer from each row. The @@ -148,9 +148,9 @@ * shown, as it is specific to the #GtkListStore. For information on * how to write such a function, see the #GtkListStore documentation. * - * ## Reading data from a #GtkTreeModel + * ## Reading data from a `GtkTreeModel` * - * |[ + * ```c * enum * { * STRING_COLUMN, @@ -198,7 +198,7 @@ * &iter); * row_count++; * } - * ]| + * ``` * * The #GtkTreeModel interface contains two methods for reference * counting: gtk_tree_model_ref_node() and gtk_tree_model_unref_node(). @@ -252,6 +252,11 @@ enum { static guint tree_model_signals[LAST_SIGNAL] = { 0 }; +/** + * GtkTreePath: + * + * An opaque structure representing a path to a row in a model. + */ struct _GtkTreePath { int depth; /* Number of elements */