[gtk/ebassi/gidocgen: 360/500] sorter: Convert docs

[Emmanuele Bassi <ebassi src gnome org>]

commit 5bdcd66117a9f008e6dfea6db97a59098bc663b4
Author: Matthias Clasen <mclasen redhat com>
Date:   Sun Feb 28 13:10:56 2021 -0500

    sorter: Convert docs

 gtk/gtksorter.c | 102 +++++++++++++++++++++++++++++++-------------------------
 gtk/gtksorter.h |   4 +--
 2 files changed, 58 insertions(+), 48 deletions(-)
---
diff --git a/gtk/gtksorter.c b/gtk/gtksorter.c
index d6c38dd54a..afd24c13f3 100644
--- a/gtk/gtksorter.c
+++ b/gtk/gtksorter.c
@@ -25,27 +25,28 @@
 #include "gtktypebuiltins.h"
 
 /**
- * SECTION:gtksorter
- * @title: GtkSorter
- * @Short_description: Sorting items
- * @See_also: #GtkSortListModel
+ * GtkSorter:
  *
- * #GtkSorter is the way to describe sorting criteria.
- * Its primary user is #GtkSortListModel.
+ * `GtkSorter` is an object to describe sorting criteria.
  *
- * The model will use a sorter to determine the order in which its items should appear
- * by calling gtk_sorter_compare() for pairs of items.
+ * Its primary user is [class@Gtk.SortListModel]
  *
- * Sorters may change their sorting behavior through their lifetime. In that case,
- * they will emit the #GtkSorter::changed signal to notify that the sort order is
- * no longer valid and should be updated by calling gtk_sorter_compare() again.
+ * The model will use a sorter to determine the order in which
+ * its items should appear by calling [method@Gtk.Sorter.compare]
+ * for pairs of items.
  *
- * GTK provides various pre-made sorter implementations for common sorting operations.
- * #GtkColumnView has built-in support for sorting lists via the #GtkColumnViewColumn:sorter
- * property, where the user can change the sorting by clicking on list headers.
+ * Sorters may change their sorting behavior through their lifetime.
+ * In that case, they will emit the [signal@Gtk.Sorter::changed] signal
+ * to notify that the sort order is no longer valid and should be updated
+ * by calling gtk_sorter_compare() again.
  *
- * Of course, in particular for large lists, it is also possible to subclass #GtkSorter
- * and provide one's own sorter.
+ * GTK provides various pre-made sorter implementations for common sorting
+ * operations. [class@Gtk.ColumnView] has built-in support for sorting lists
+ * via the [property@Gtk.ColumnViewColumn:sorter] property, where the user can
+ * change the sorting by clicking on list headers.
+ *
+ * Of course, in particular for large lists, it is also possible to subclass
+ * `GtkSorter` and provide one's own sorter.
  */
 
 typedef struct _GtkSorterPrivate GtkSorterPrivate;
@@ -113,14 +114,16 @@ gtk_sorter_class_init (GtkSorterClass *class)
    * @self: The #GtkSorter
    * @change: how the sorter changed
    *
-   * This signal is emitted whenever the sorter changed. Users of the sorter
-   * should then update the sort order again via gtk_sorter_compare().
+   * Emitted whenever the sorter changed.
+   *
+   * Users of the sorter should then update the sort order
+   * again via gtk_sorter_compare().
    *
-   * #GtkSortListModel handles this signal automatically.
+   * [class@Gtk.SortListModel] handles this signal automatically.
    *
    * Depending on the @change parameter, it may be possible to update
-   * the sort order without a full resorting. Refer to the #GtkSorterChange
-   * documentation for details.
+   * the sort order without a full resorting. Refer to the
+   * [enum@Gtk.SorterChange] documentation for details.
    */
   signals[CHANGED] =
     g_signal_new (I_("changed"),
@@ -143,7 +146,7 @@ gtk_sorter_init (GtkSorter *self)
 
 /**
  * gtk_sorter_compare:
- * @self: a #GtkSorter
+ * @self: a `GtkSorter`
  * @item1: (type GObject) (transfer none): first item to compare
  * @item2: (type GObject) (transfer none): second item to compare
  *
@@ -151,13 +154,14 @@ gtk_sorter_init (GtkSorter *self)
  * by the sorter.
  *
  * Sorters implement a partial order:
+ *
  * * It is reflexive, ie a = a
  * * It is antisymmetric, ie if a < b and b < a, then a = b
  * * It is transitive, ie given any 3 items with a ≤ b and b ≤ c,
  *   then a ≤ c
- * 
- * The sorter  may signal it conforms to additional constraints
- * via the return value of gtk_sorter_get_order().
+ *
+ * The sorter may signal it conforms to additional constraints
+ * via the return value of [method@Gtk.Sorter.get_order].
  *
  * Returns: %GTK_ORDERING_EQUAL if @item1 == @item2,
  *     %GTK_ORDERING_SMALLER if @item1 < @item2,
@@ -193,15 +197,17 @@ gtk_sorter_compare (GtkSorter *self,
 
 /**
  * gtk_sorter_get_order:
- * @self: a #GtkSorter
+ * @self: a `GtkSorter`
+ *
+ * Gets the order that @self conforms to.
  *
- * Gets the order that @self conforms to. See #GtkSorterOrder for details
+ * See [enum@Gtk.SorterOrder] for details
  * of the possible return values.
  *
  * This function is intended to allow optimizations.
  *
  * Returns: The order
- **/
+ */
 GtkSorterOrder
 gtk_sorter_get_order (GtkSorter *self)
 {
@@ -272,19 +278,20 @@ static const GtkSortKeysClass GTK_DEFAULT_SORT_KEYS_CLASS =
 
 /*<private>
  * gtk_sorter_get_keys:
- * @self: a #GtkSorter
+ * @self: a `GtkSorter`
  *
- * Gets a #GtkSortKeys that can be used as an alternative to
+ * Gets a `GtkSortKeys` that can be used as an alternative to
  * @self for faster sorting.
  *
- * The sort keys can change every time #GtkSorter::changed is emitted.
- * When the keys change, you should redo all comparisons with the new
- * keys.  
- * When gtk_sort_keys_is_compatible() for the old and new keys returns
- * %TRUE, you can reuse keys you generated previously.
+ * The sort keys can change every time [signal@Gtk.Sorter::changed]
+ * is emitted. When the keys change, you should redo all comparisons
+ * with the new keys.
+ *
+ * When [method@Gtk.SortKeys.is_compatible] for the old and new keys
+ * returns %TRUE, you can reuse keys you generated previously.
  *
  * Returns: (transfer full): the sort keys to sort with
- **/
+ */
 GtkSortKeys *
 gtk_sorter_get_keys (GtkSorter *self)
 {
@@ -304,19 +311,21 @@ gtk_sorter_get_keys (GtkSorter *self)
 
 /**
  * gtk_sorter_changed:
- * @self: a #GtkSorter
+ * @self: a `GtkSorter`
  * @change: How the sorter changed
  *
- * Emits the #GtkSorter::changed signal to notify all users of the sorter
- * that it has changed. Users of the sorter should then update the sort
- * order via gtk_sorter_compare().
+ * Emits the [signal@Gtk.Sorter::changed] signal to notify all users
+ * of the sorter that it has changed.
+ *
+ * Users of the sorter should then update the sort order via
+ * gtk_sorter_compare().
  *
  * Depending on the @change parameter, it may be possible to update
- * the sort order without a full resorting. Refer to the #GtkSorterChange
- * documentation for details.
+ * the sort order without a full resorting. Refer to the
+ * [enum@Gtk.SorterChange] documentation for details.
  *
- * This function is intended for implementors of #GtkSorter subclasses and
- * should not be called from other functions.
+ * This function is intended for implementors of `GtkSorter`
+ * subclasses and should not be called from other functions.
  */
 void
 gtk_sorter_changed (GtkSorter       *self,
@@ -328,12 +337,13 @@ gtk_sorter_changed (GtkSorter       *self,
 }
 
 /*<private>
- * gtk_sorter_changed_with_keys
- * @self: a #GtkSorter
+ * gtk_sorter_changed_with_keys:
+ * @self: a `GtkSorter`
  * @change: How the sorter changed
  * @keys: (not nullable) (transfer full): New keys to use
  *
  * Updates the sorter's keys to @keys and then calls gtk_sorter_changed().
+ *
  * If you do not want to update the keys, call that function instead.
  *
  * This function should also be called in your_sorter_init() to initialize
diff --git a/gtk/gtksorter.h b/gtk/gtksorter.h
index 108c3cb8c9..b90cac1381 100644
--- a/gtk/gtksorter.h
+++ b/gtk/gtksorter.h
@@ -38,7 +38,7 @@ G_BEGIN_DECLS
  *     return %GTK_ORDERING_EQUAL if an item is compared with itself. Two
  *     different items will never cause this value to be returned.
  *
- * Describes the type of order that a #GtkSorter may describe.
+ * Describes the type of order that a `GtkSorter` may produce.
  */
 typedef enum {
   GTK_SORTER_ORDER_PARTIAL,
@@ -79,7 +79,7 @@ G_DECLARE_DERIVABLE_TYPE (GtkSorter, gtk_sorter, GTK, SORTER, GObject)
  * @get_order: Get the #GtkSorderOrder that applies to the current sorter.
  *     If unimplemented, it returns %GTK_SORTER_ORDER_PARTIAL.
  *
- * The virtual table for #GtkSorter.
+ * The virtual table for `GtkSorter`.
  */
 struct _GtkSorterClass
 {