GNOME.org
 

[gtk/doc-links: 6/6] docs: Tweak documentation for list widgets


commit 20c1fb0a0a826e6ee85e333662b3c1178fe71542
Author: Matthias Clasen <mclasen redhat com>
Date:   Mon Aug 3 18:41:36 2020 -0400

    docs: Tweak documentation for list widgets
    
    Fix numerous cases of : vs :: for signal references,
    add some more details here and there.

 docs/reference/gtk/gtk4-sections.txt |  2 +-
 gtk/gtkcolumnviewcolumn.c            | 10 ++++++
 gtk/gtkdirectorylist.c               | 14 ++++----
 gtk/gtkdropdown.c                    |  6 ++--
 gtk/gtkmultiselection.c              |  2 +-
 gtk/gtknoselection.c                 |  2 +-
 gtk/gtkselectionmodel.c              | 62 ++++++++++++++++++------------------
 gtk/gtksignallistitemfactory.c       | 12 +++----
 gtk/gtksingleselection.c             | 26 ++++++++-------
 gtk/gtkstringlist.c                  |  4 +--
 10 files changed, 77 insertions(+), 63 deletions(-)
---
diff --git a/docs/reference/gtk/gtk4-sections.txt b/docs/reference/gtk/gtk4-sections.txt
index c6ef42f3e8..0efe0d7da7 100644
--- a/docs/reference/gtk/gtk4-sections.txt
+++ b/docs/reference/gtk/gtk4-sections.txt
@@ -431,7 +431,7 @@ gtk_single_selection_get_type
 
 <SECTION>
 <FILE>gtkmultiselection</FILE>
-<TITLE>GtkMultiSeledction</TITLE>
+<TITLE>GtkMultiSelection</TITLE>
 GtkMultiSelection
 gtk_multi_selection_new
 gtk_multi_selection_get_model
diff --git a/gtk/gtkcolumnviewcolumn.c b/gtk/gtkcolumnviewcolumn.c
index c0aaf631bb..3ee4b84123 100644
--- a/gtk/gtkcolumnviewcolumn.c
+++ b/gtk/gtkcolumnviewcolumn.c
@@ -42,6 +42,13 @@
  * @see_also: #GtkColumnView
  *
  * GtkColumnViewColumn represents the columns being added to #GtkColumnView.
+ *
+ * Columns have a title, and can optionally have a header menu set
+ * with gtk_column_view_column_set_header_menu().
+ *
+ * A sorter can be associated with a column using
+ * gtk_column_view_column_set_sorter(), to let users influence sorting by
+ * clicking on the column header.
  */
 
 struct _GtkColumnViewColumn
@@ -756,6 +763,9 @@ gtk_column_view_column_remove_from_sorter (GtkColumnViewColumn *self)
  *
  * This sorter can be made active by clicking on the column
  * header, or by calling gtk_column_view_sort_by_column().
+ *
+ * See gtk_column_view_get_sorter() for the necessary steps
+ * for setting up customizable sorting for #GtkColumnView.
  */
 void
 gtk_column_view_column_set_sorter (GtkColumnViewColumn *self,
diff --git a/gtk/gtkdirectorylist.c b/gtk/gtkdirectorylist.c
index feb3ed044c..5ec5c94b0d 100644
--- a/gtk/gtkdirectorylist.c
+++ b/gtk/gtkdirectorylist.c
@@ -34,21 +34,22 @@
  * It presents a #GListModel and fills it asynchronously with the #GFileInfos
  * returned from that function.
  *
- * Enumeration will start automatically when a the GtkDirectoryList:file property
+ * Enumeration will start automatically when a the #GtkDirectoryList:file property
  * is set.
  *
- * While the #GtkDirectoryList is being filled, the GtkDirectoryList:loading
+ * While the #GtkDirectoryList is being filled, the #GtkDirectoryList:loading
  * property will be set to %TRUE. You can listen to that property if you want
  * to show information like a #GtkSpinner or a "Loading..." text.
- * If loading fails at any point, the GtkDirectoryList:error property will be set
- * to give more indication about the failure.
+ *
+ * If loading fails at any point, the #GtkDirectoryList:error property will be
+ * set to give more indication about the failure.
  *
  * The #GFileInfos returned from a #GtkDirectoryList have the "standard::file"
  * attribute set to the #GFile they refer to. This way you can get at the file
  * that is referred to in the same way you would via g_file_enumerator_get_child().
  * This means you do not need access to the #GtkDirectoryList but can access
- * the #GFile directly from the #GFileInfo when operating with a #GtkListView or
- * similar.
+ * the #GFile directly from the #GFileInfo when operating with a #GtkListView
+ * or similar.
  */
 
 /* random number that everyone else seems to use, too */
@@ -817,6 +818,7 @@ gtk_directory_list_get_io_priority (GtkDirectoryList *self)
  *
  * Returns %TRUE if the children enumeration is currently in
  * progress.
+ *
  * Files will be added to @self from time to time while loading is
  * going on. The order in which are added is undefined and may change
  * inbetween runs.
diff --git a/gtk/gtkdropdown.c b/gtk/gtkdropdown.c
index 1ddf89448b..bb8c763d6c 100644
--- a/gtk/gtkdropdown.c
+++ b/gtk/gtkdropdown.c
@@ -58,13 +58,11 @@
  *
  * The options are given to GtkDropDown in the form of #GListModel,
  * and how the individual options are represented is determined by
- * a #GtkListItemFactory. The default factory displays simple strings,
- * and expects to obtain these from the model by evaluating an expression
- * that has to be provided via gtk_drop_down_set_expression().
+ * a #GtkListItemFactory. The default factory displays simple strings.
  *
  * GtkDropDown knows how to obtain strings from the items in a
  * #GtkStringList; for other models, you have to provide an expression
- * to find the strings.
+ * to find the strings via gtk_drop_down_set_expression().
  *
  * GtkDropDown can optionally allow search in the popup, which is
  * useful if the list of options is long. To enable the search entry,
diff --git a/gtk/gtkmultiselection.c b/gtk/gtkmultiselection.c
index c6e3474cb9..70ee6ea8bb 100644
--- a/gtk/gtkmultiselection.c
+++ b/gtk/gtkmultiselection.c
@@ -347,7 +347,7 @@ gtk_multi_selection_class_init (GtkMultiSelectionClass *klass)
   gobject_class->dispose = gtk_multi_selection_dispose;
 
   /**
-   * GtkMultiSelection:model
+   * GtkMultiSelection:model:
    *
    * The list managed by this selection
    */
diff --git a/gtk/gtknoselection.c b/gtk/gtknoselection.c
index 597eb4af31..1e9331bee2 100644
--- a/gtk/gtknoselection.c
+++ b/gtk/gtknoselection.c
@@ -31,7 +31,7 @@
  * @Title: GtkNoSelection
  * @see_also: #GtkSelectionModel
  *
- * GtkNoSelection is an implementation of the #GtkSelectionModel interface 
+ * GtkNoSelection is an implementation of the #GtkSelectionModel interface
  * that does not allow selecting anything.
  *
  * This model is meant to be used as a simple wrapper to #GListModels when a
diff --git a/gtk/gtkselectionmodel.c b/gtk/gtkselectionmodel.c
index 0a60d7310d..f14676b912 100644
--- a/gtk/gtkselectionmodel.c
+++ b/gtk/gtkselectionmodel.c
@@ -31,40 +31,40 @@
  * @Short_description: An extension of the list model interface that handles selections
  * @See_also: #GListModel, #GtkSingleSelection
  *
- * #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 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.
  *
- * GTK provides default implementations of the mode 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.
+ * 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.
  *
- * 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(). When the selected
- * state of one or more items changes, the model will emit the
+ * 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().
+ * 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.
+ * 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
  * 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 implement them
- * partially or not at all. In that case the widgets will not support the unimplemented
- * operations.
+ * 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
+ * implement them partially or not at all. In that case the widgets will not
+ * support the unimplemented operations.
  *
- * When selecting or unselecting is supported by a model, the return values of the
- * selection functions do NOT indicate if selection or unselection happened. They are
- * only meant to indicate complete failure, like when this mode of selecting is not
- * supported by the model.
+ * When selecting or unselecting is supported by a model, the return values of
+ * the selection functions do *not* indicate if selection or unselection happened.
+ * They are only meant to indicate complete failure, like when this mode of
+ * selecting is not supported by the model.
  *
- * Selections may happen asynchronously, so the only reliable way to find out when an
- * item was selected is to listen to the signals that indicate selection.
+ * Selections may happen asynchronously, so the only reliable way to find out
+ * when an item was selected is to listen to the signals that indicate selection.
  */
 
 G_DEFINE_INTERFACE (GtkSelectionModel, gtk_selection_model, G_TYPE_LIST_MODEL)
@@ -251,7 +251,7 @@ gtk_selection_model_default_init (GtkSelectionModelInterface *iface)
    * 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.  
+   * 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.
@@ -318,13 +318,13 @@ gtk_selection_model_get_selection (GtkSelectionModel *model)
  * @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.
+ * 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.
  *
  * 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 :selection-changed signal.
+ * case is in response to the #GtkSelectionModel::selection-changed signal.
  *
  * Returns: A #GtkBitset that matches the selection state for the given state
  *     with all other values being undefined.
@@ -495,7 +495,7 @@ gtk_selection_model_unselect_all (GtkSelectionModel *model)
  * are more likely to implement support for those.
  *
  * Requests that the selection state of all positions set in @mask be
- * updated to the respecitve value in the @selected bitmask.  
+ * updated to the respecitve value in the @selected bitmask.
  *
  * In pseudocode, it would look something like this:
  *
@@ -544,8 +544,8 @@ gtk_selection_model_set_selection (GtkSelectionModel *model,
  * @n_items: the number of changed items
  *
  * Helper function for implementations of #GtkSelectionModel.
- * Call this when a the selection changes to emit the ::selection-changed
- * signal.
+ * Call this when a the selection changes to emit the
+ * #GtkSelectionModel::selection-changed signal.
  */
 void
 gtk_selection_model_selection_changed (GtkSelectionModel *model,
diff --git a/gtk/gtksignallistitemfactory.c b/gtk/gtksignallistitemfactory.c
index c1c8ada1f6..d728abf84f 100644
--- a/gtk/gtksignallistitemfactory.c
+++ b/gtk/gtksignallistitemfactory.c
@@ -163,7 +163,7 @@ gtk_signal_list_item_factory_class_init (GtkSignalListItemFactoryClass *klass)
    * The ::setup signal is emitted when a new listitem has been created and
    * needs to be setup for use. It is the first signal emitted for every listitem.
    *
-   * The GtkSignalListItemFactory::teardown signal is the opposite of this signal
+   * The #GtkSignalListItemFactory::teardown signal is the opposite of this signal
    * and can be used to undo everything done in this signal.
    */
   signals[SETUP] =
@@ -184,13 +184,13 @@ gtk_signal_list_item_factory_class_init (GtkSignalListItemFactoryClass *klass)
    * @self: The #GtkSignalListItemFactory
    * @listitem: The #GtkListItem to bind
    *
-   * The ::bind signal is emitted when a new GtkListItem:item has been set
+   * The ::bind signal is emitted when a new #GtkListItem:item has been set
    * on the @listitem and should be bound for use.
    *
    * After this signal was emitted, the listitem might be shown in a #GtkListView
    * or other list widget.
    *
-   * The GtkSignalListItemFactory::unbind signal is the opposite of this signal
+   * The #GtkSignalListItemFactory::unbind signal is the opposite of this signal
    * and can be used to undo everything done in this signal.
    */
   signals[BIND] =
@@ -212,9 +212,9 @@ gtk_signal_list_item_factory_class_init (GtkSignalListItemFactoryClass *klass)
    * @listitem: The #GtkListItem to unbind
    *
    * The ::unbind signal is emitted when a listitem has been removed from use
-   * in a list widget and its new GtkListItem:item is about to be unset.
+   * in a list widget and its new #GtkListItem:item is about to be unset.
    *
-   * This signal is the opposite of the GtkSignalListItemFactory::bind signal
+   * This signal is the opposite of the #GtkSignalListItemFactory::bind signal
    * and should be used to undo everything done in that signal.
    */
   signals[UNBIND] =
@@ -238,7 +238,7 @@ gtk_signal_list_item_factory_class_init (GtkSignalListItemFactoryClass *klass)
    * The ::teardown signal is emitted when a listitem is about to be destroyed.
    * It is the last signal ever emitted for this @listitem.
    *
-   * This signal is the opposite of the GtkSignalListItemFactory::setup signal
+   * This signal is the opposite of the #GtkSignalListItemFactory::setup signal
    * and should be used to undo everything done in that signal.
    */
   signals[TEARDOWN] =
diff --git a/gtk/gtksingleselection.c b/gtk/gtksingleselection.c
index 8c23d3c303..e072594d6a 100644
--- a/gtk/gtksingleselection.c
+++ b/gtk/gtksingleselection.c
@@ -36,8 +36,8 @@
  * used by list widgets in GTK.
  *
  * Note that the selection is *persistent* -- if the selected item is removed
- * and re-added in the same ::items-changed emission, it stays selected. In
- * particular, this means that changing the sort order of an underlying sort
+ * and re-added in the same #GListModel::items-changed emission, it stays selected.
+ * In particular, this means that changing the sort order of an underlying sort
  * model will preserve the selection.
  */
 struct _GtkSingleSelection
@@ -570,11 +570,13 @@ gtk_single_selection_get_selected (GtkSingleSelection *self)
  * @self: a #GtkSingleSelection
  * @position: the item to select or #GTK_INVALID_LIST_POSITION
  *
- * Selects the item at the given position. If the list does not have an item at
- * @position or #GTK_INVALID_LIST_POSITION is given, the behavior depends on the
- * value of the GtkSingleSelection:autoselect property: If it is set, no change
- * will occur and the old item will stay selected. If it is unset, the selection
- * will be unset and no item will be selected.
+ * Selects the item at the given position.
+ *
+ * If the list does not have an item at @position or
+ * #GTK_INVALID_LIST_POSITION is given, the behavior depends on the
+ * value of the #GtkSingleSelection:autoselect property: If it is set,
+ * no change will occur and the old item will stay selected. If it is
+ * unset, the selection will be unset and no item will be selected.
  **/
 void
 gtk_single_selection_set_selected (GtkSingleSelection *self,
@@ -618,8 +620,10 @@ gtk_single_selection_set_selected (GtkSingleSelection *self,
 /**
  * gtk_single_selection_get_selected_item:
  * @self: a #GtkSingleSelection
- * 
- * Gets the selected item. If no item is selected, %NULL is returned.
+ *
+ * Gets the selected item.
+ *
+ * If no item is selected, %NULL is returned.
  *
  * Returns: (transfer none): The selected item
  */
@@ -703,9 +707,9 @@ gtk_single_selection_get_can_unselect (GtkSingleSelection *self)
  * If %TRUE, unselecting the current item via
  * gtk_selection_model_unselect_item() is supported.
  *
- * Note that setting GtkSingleSelection:autoselect will cause the
+ * Note that setting #GtkSingleSelection:autoselect will cause the
  * unselecting to not work, so it practically makes no sense to set
- * both at the same time the same time..
+ * both at the same time the same time.
  **/
 void
 gtk_single_selection_set_can_unselect (GtkSingleSelection *self,
diff --git a/gtk/gtkstringlist.c b/gtk/gtkstringlist.c
index daf1731372..5c04301c70 100644
--- a/gtk/gtkstringlist.c
+++ b/gtk/gtkstringlist.c
@@ -466,11 +466,11 @@ gtk_string_list_new (const char * const *strings)
  * Changes @self by removing @n_removals strings and adding @additions
  * to it.
  *
- * This function is more efficient than gtk_string_list_insert() and
+ * This function is more efficient than gtk_string_list_append() and
  * gtk_string_list_remove(), because it only emits
  * #GListModel::items-changed once for the change.
  *
- * This function takes a ref on each item in @additions.
+ * This function copies the strings in @additions.
  *
  * The parameters @position and @n_removals must be correct (ie:
  * @position + @n_removals must be less than or equal to the length
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]