[gtk/ebassi/gidocgen: 437/501] selectionmodel: Convert docs

[Emmanuele Bassi <ebassi src gnome org>]

commit 3304076a4d1cf9b473c0c7260ed4648d291faaf2
Author: Matthias Clasen <mclasen redhat com>
Date:   Mon Mar 1 01:51:02 2021 -0500

    selectionmodel: Convert docs

 gtk/gtkselectionmodel.c | 140 ++++++++++++++++++++++++------------------------
 1 file changed, 71 insertions(+), 69 deletions(-)
---
diff --git a/gtk/gtkselectionmodel.c b/gtk/gtkselectionmodel.c
index 1a70694fc5..91de4f8f4f 100644
--- a/gtk/gtkselectionmodel.c
+++ b/gtk/gtkselectionmodel.c
@@ -26,35 +26,33 @@
 #include "gtkmarshalers.h"
 
 /**
- * SECTION:gtkselectionmodel
- * @Title: GtkSelectionModel
- * @Short_description: An extension of the list model interface that handles selections
- * @See_also: #GListModel, #GtkSingleSelection
+ * GtkSelectionModel:
  *
- * #GtkSelectionModel is an interface that extends the #GListModel interface by
- * adding support for selections. This support is then used by widgets using list
- * models to add the ability to select and unselect various items.
+ * `GtkSelectionModel` is an interface that add support for selection to list models.
+ *
+ * This support is then used by widgets using list models to add the ability
+ * to select and unselect various items.
  *
  * GTK provides default implementations of the most common selection modes such
- * as #GtkSingleSelection, so you will only need to implement this interface if
- * you want detailed control about how selections should be handled.
+ * as [class@Gtk.SingleSelection], so you will only need to implement this
+ * interface if you want detailed control about how selections should be handled.
  *
- * A #GtkSelectionModel supports a single boolean per item indicating if an item
- * is selected or not. This can be queried via gtk_selection_model_is_selected().
+ * A `GtkSelectionModel` supports a single boolean per item indicating if an item is
+ * selected or not. This can be queried via [method@Gtk.SelectionModel.is_selected].
  * When the selected state of one or more items changes, the model will emit the
- * #GtkSelectionModel::selection-changed signal by calling the
- * gtk_selection_model_selection_changed() function. The positions given in that
- * signal may have their selection state changed, though that is not a requirement.
- * If new items added to the model via the #GListModel::items-changed signal are
- * selected or not is up to the implementation.
- *
- * Note that items added via #GListModel::items-changed may already be selected
- * and no #GtkSelectionModel::selection-changed will be emitted for them. So to
+ * [signal@Gtk.SelectionModel::selection-changed] signal by calling the
+ * [method@Gtk.SelectionModel.selection_changed] function. The positions given
+ * in that signal may have their selection state changed, though that is not a
+ * requirement. If new items added to the model via the ::items-changed signal
+ * are selected or not is up to the implementation.
+ *
+ * Note that items added via ::items-changed may already be selected and no
+ * [Gtk.SelectionModel::selection-changed] will be emitted for them. So to
  * track which items are selected, it is necessary to listen to both signals.
  *
  * Additionally, the interface can expose functionality to select and unselect
  * items. If these functions are implemented, GTK's list widgets will allow users
- * to select and unselect items. However, #GtkSelectionModels are free to only
+ * to select and unselect items. However, `GtkSelectionModel`s are free to only
  * implement them partially or not at all. In that case the widgets will not
  * support the unimplemented operations.
  *
@@ -244,17 +242,16 @@ gtk_selection_model_default_init (GtkSelectionModelInterface *iface)
 
   /**
    * GtkSelectionModel::selection-changed
-   * @model: a #GtkSelectionModel
+   * @model: a `GtkSelectionModel`
    * @position: The first item that may have changed
    * @n_items: number of items with changes
    *
    * Emitted when the selection state of some of the items in @model changes.
    *
-   * Note that this signal does not specify the new selection state of the items,
-   * they need to be queried manually.
-   * It is also not necessary for a model to change the selection state of any of
-   * the items in the selection model, though it would be rather useless to emit
-   * such a signal.
+   * Note that this signal does not specify the new selection state of the
+   * items, they need to be queried manually. It is also not necessary for
+   * a model to change the selection state of any of the items in the selection
+   * model, though it would be rather useless to emit such a signal.
    */
   signals[SELECTION_CHANGED] =
     g_signal_new ("selection-changed",
@@ -271,13 +268,13 @@ gtk_selection_model_default_init (GtkSelectionModelInterface *iface)
 
 /**
  * gtk_selection_model_is_selected:
- * @model: a #GtkSelectionModel
+ * @model: a `GtkSelectionModel`
  * @position: the position of the item to query
  *
  * Checks if the given item is selected.
  *
  * Returns: %TRUE if the item is selected
- **/
+ */
 gboolean
 gtk_selection_model_is_selected (GtkSelectionModel *model,
                                  guint              position)
@@ -292,18 +289,18 @@ gtk_selection_model_is_selected (GtkSelectionModel *model,
 
 /**
  * gtk_selection_model_get_selection:
- * @model: a #GtkSelectionModel
+ * @model: a `GtkSelectionModel`
  *
  * Gets the set containing all currently selected items in the model.
  *
  * This function may be slow, so if you are only interested in single item,
- * consider using gtk_selection_model_is_selected() or if you are only
- * interested in a few consider gtk_selection_model_get_selection_in_range().
+ * consider using [method@Gtk.SelectionModel.is_selected] or if you are only
+ * interested in a few, consider [method@Gtk.SelectionModel.get_selection_in_range].
  *
- * Returns: (transfer full): a #GtkBitset containing all the values currently
- *     selected in @model. If no items are selected, the bitset is empty.
- *     The bitset must not be modified.
- **/
+ * Returns: (transfer full): a `GtkBitset` containing all the values currently
+ *   selected in @model. If no items are selected, the bitset is empty.
+ *   The bitset must not be modified.
+ */
 GtkBitset *
 gtk_selection_model_get_selection (GtkSelectionModel *model)
 {
@@ -314,22 +311,22 @@ gtk_selection_model_get_selection (GtkSelectionModel *model)
 
 /**
  * gtk_selection_model_get_selection_in_range:
- * @model: a #GtkSelectionModel
+ * @model: a `GtkSelectionModel`
  * @position: start of the queired range
  * @n_items: number of items in the queried range
  *
- * Gets a set containing a set where the values in the range `[position,
- * position + n_items)` match the selected state of the items in that range.
- * All values outside that range are undefined.
+ * Gets the set of selected items in a range.
  *
- * This function is an optimization for gtk_selection_model_get_selection() when
- * you are only interested in part of the model's selected state. A common use
- * case is in response to the #GtkSelectionModel::selection-changed signal.
+ * This function is an optimization for
+ * [method@Gtk.SelectionModel.get_selection] when you are only
+ * interested in part of the model's selected state. A common use
+ * case is in response to the [signal@Gtk.SelectionModel::selection-changed]
+ * signal.
  *
- * Returns: A #GtkBitset that matches the selection state for the given state
- *     with all other values being undefined.
- *     The bitset must not be modified.
- **/
+ * Returns: A `GtkBitset` that matches the selection state
+ *   for the given range with all other values being undefined.
+ *   The bitset must not be modified.
+ */
 GtkBitset *
 gtk_selection_model_get_selection_in_range (GtkSelectionModel *model,
                                             guint              position,
@@ -348,14 +345,14 @@ gtk_selection_model_get_selection_in_range (GtkSelectionModel *model,
 
 /**
  * gtk_selection_model_select_item:
- * @model: a #GtkSelectionModel
+ * @model: a `GtkSelectionModel`
  * @position: the position of the item to select
  * @unselect_rest: whether previously selected items should be unselected
  *
  * Requests to select an item in the model.
  *
  * Returns: %TRUE if this action was supported and no fallback should be
- *     tried. This does not mean the item was selected.
+ *   tried. This does not mean the item was selected.
  */
 gboolean
 gtk_selection_model_select_item (GtkSelectionModel *model,
@@ -372,7 +369,7 @@ gtk_selection_model_select_item (GtkSelectionModel *model,
 
 /**
  * gtk_selection_model_unselect_item:
- * @model: a #GtkSelectionModel
+ * @model: a `GtkSelectionModel`
  * @position: the position of the item to unselect
  *
  * Requests to unselect an item in the model.
@@ -394,7 +391,7 @@ gtk_selection_model_unselect_item (GtkSelectionModel *model,
 
 /**
  * gtk_selection_model_select_range:
- * @model: a #GtkSelectionModel
+ * @model: a `GtkSelectionModel`
  * @position: the first item to select
  * @n_items: the number of items to select
  * @unselect_rest: whether previously selected items should be unselected
@@ -420,7 +417,7 @@ gtk_selection_model_select_range (GtkSelectionModel *model,
 
 /**
  * gtk_selection_model_unselect_range:
- * @model: a #GtkSelectionModel
+ * @model: a `GtkSelectionModel`
  * @position: the first item to unselect
  * @n_items: the number of items to unselect
  *
@@ -444,7 +441,7 @@ gtk_selection_model_unselect_range (GtkSelectionModel *model,
 
 /**
  * gtk_selection_model_select_all:
- * @model: a #GtkSelectionModel
+ * @model: a `GtkSelectionModel`
  *
  * Requests to select all items in the model.
  *
@@ -464,7 +461,7 @@ gtk_selection_model_select_all (GtkSelectionModel *model)
 
 /**
  * gtk_selection_model_unselect_all:
- * @model: a #GtkSelectionModel
+ * @model: a `GtkSelectionModel`
  *
  * Requests to unselect all items in the model.
  *
@@ -484,22 +481,24 @@ gtk_selection_model_unselect_all (GtkSelectionModel *model)
 
 /**
  * gtk_selection_model_set_selection:
- * @model: a #GtkSelectionModel
+ * @model: a `GtkSelectionModel`
  * @selected: bitmask specifying if items should be selected or
  *     unselected
  * @mask: bitmask specifying which items should be updated
  *
+ * Make selection changes.
+ *
  * This is the most advanced selection updating method that allows
- * the most fine-grained control over selection changes.
- * If you can, you should try the simpler versions, as implementations
- * are more likely to implement support for those.
+ * the most fine-grained control over selection changes. If you can,
+ * you should try the simpler versions, as implementations are more
+ * likely to implement support for those.
  *
- * Requests that the selection state of all positions set in @mask be
- * updated to the respective value in the @selected bitmask.
+ * Requests that the selection state of all positions set in @mask
+ * be updated to the respective value in the @selected bitmask.
  *
  * In pseudocode, it would look something like this:
  *
- * |[<!-- language="C" -->
+ * ```c
  * for (i = 0; i < n_items; i++)
  *   {
  *     // don't change values not in the mask
@@ -512,16 +511,19 @@ gtk_selection_model_unselect_all (GtkSelectionModel *model)
  *       unselect_item (i);
  *   }
  *
- * gtk_selection_model_selection_changed (model, first_changed_item, n_changed_items);
- * ]|
+ * gtk_selection_model_selection_changed (model,
+ *                                        first_changed_item,
+ *                                        n_changed_items);
+ * ```
  *
- * @mask and @selected must not be modified. They may refer to the same bitset,
- * which would mean that every item in the set should be selected.
+ * @mask and @selected must not be modified. They may refer to the
+ * same bitset, which would mean that every item in the set should
+ * be selected.
  *
  * Returns: %TRUE if this action was supported and no fallback should be
  *     tried. This does not mean that all items were updated according
  *     to the inputs.
- **/
+ */
 gboolean
 gtk_selection_model_set_selection (GtkSelectionModel *model,
                                    GtkBitset         *selected,
@@ -539,13 +541,14 @@ gtk_selection_model_set_selection (GtkSelectionModel *model,
 
 /**
  * gtk_selection_model_selection_changed:
- * @model: a #GtkSelectionModel
+ * @model: a `GtkSelectionModel`
  * @position: the first changed item
  * @n_items: the number of changed items
  *
- * Helper function for implementations of #GtkSelectionModel.
+ * Helper function for implementations of `GtkSelectionModel`.
+ *
  * Call this when a the selection changes to emit the
- * #GtkSelectionModel::selection-changed signal.
+ * [signal@Gtk.SelectionModel::selection-changed] signal.
  */
 void
 gtk_selection_model_selection_changed (GtkSelectionModel *model,
@@ -558,4 +561,3 @@ gtk_selection_model_selection_changed (GtkSelectionModel *model,
 
   g_signal_emit (model, signals[SELECTION_CHANGED], 0, position, n_items);
 }
-