[gtk/ebassi/gidocgen: 272/481] notebook: Convert docs




commit 332e370937702fd56cd8264d280b502d8e5ddc1e
Author: Matthias Clasen <mclasen redhat com>
Date:   Sat Feb 27 18:20:56 2021 -0500

    notebook: Convert docs

 gtk/gtknotebook.c | 461 +++++++++++++++++++++++++++++++++---------------------
 gtk/gtknotebook.h |   9 +-
 2 files changed, 287 insertions(+), 183 deletions(-)
---
diff --git a/gtk/gtknotebook.c b/gtk/gtknotebook.c
index ed712517b4..3e65f125c8 100644
--- a/gtk/gtknotebook.c
+++ b/gtk/gtknotebook.c
@@ -59,24 +59,24 @@
 #include <math.h>
 
 /**
- * SECTION:gtknotebook
- * @Short_description: A tabbed notebook container
- * @Title: GtkNotebook
+ * GtkNotebook:
  *
- * The #GtkNotebook widget is a layout container whose children are
- * pages that can be switched between using tab labels along one edge.
+ * `GtkNotebook` is a container whose children are pages switched
+ * between using tabs.
  *
- * There are many configuration options for GtkNotebook. Among other
- * things, you can choose on which edge the tabs appear
- * (see gtk_notebook_set_tab_pos()), whether, if there are too many
- * tabs to fit the notebook should be made bigger or scrolling
- * arrows added (see gtk_notebook_set_scrollable()), and whether there
- * will be a popup menu allowing the users to switch pages.
- * (see gtk_notebook_popup_enable(), gtk_notebook_popup_disable())
+ * ![An example GtkNotebook](notebook.png)
+ *
+ * There are many configuration options for `GtkNotebook`. Among
+ * other things, you can choose on which edge the tabs appear
+ * (see [method@Gtk.Notebook.set_tab_pos]), whether, if there are
+ * too many tabs to fit the notebook should be made bigger or scrolling
+ * arrows added (see [method@Gtk.Notebook.set_scrollable]), and whether
+ * there will be a popup menu allowing the users to switch pages.
+ * (see [method@Gtk.Notebook.popup_enable]).
  *
  * # GtkNotebook as GtkBuildable
- * 
- * The GtkNotebook implementation of the #GtkBuildable interface
+ *
+ * The `GtkNotebook` implementation of the `GtkBuildable` interface
  * supports placing children into tabs by specifying “tab” as the
  * “type” attribute of a <child> element. Note that the content
  * of the tab must be created before the tab can be filled.
@@ -87,8 +87,9 @@
  * "action-start" or “action-end” as the “type” attribute of the
  * <child> element.
  *
- * An example of a UI definition fragment with GtkNotebook:
- * |[
+ * An example of a UI definition fragment with `GtkNotebook`:
+ *
+ * ```xml
  * <object class="GtkNotebook">
  *   <child>
  *     <object class="GtkLabel" id="notebook-content">
@@ -101,11 +102,11 @@
  *     </object>
  *   </child>
  * </object>
- * ]|
+ * ```
  *
  * # CSS nodes
  *
- * |[<!-- language="plain" -->
+ * ```
  * notebook
  * ├── header.top
  * │   ├── [<action widget>]
@@ -123,9 +124,9 @@
  *     ├── <child>
  *     ┊
  *     ╰── <child>
- * ]|
+ * ```
  *
- * GtkNotebook has a main CSS node with name `notebook`, a subnode
+ * `GtkNotebook` has a main CSS node with name `notebook`, a subnode
  * with name `header` and below that a subnode with name `tabs` which
  * contains one subnode per tab with name `tab`.
  *
@@ -134,7 +135,7 @@
  * name `arrow` are placed as first and last child of the `tabs` node.
  *
  * The main node gets the `.frame` style class when the notebook
- * has a border (see gtk_notebook_set_show_border()).
+ * has a border (see [method@Gtk.Notebook.set_show_border]).
  *
  * The header node gets one of the style class `.top`, `.bottom`,
  * `.left` or `.right`, depending on where the tabs are placed. For
@@ -146,7 +147,7 @@
  *
  * # Accessibility
  *
- * GtkNotebook uses the following roles:
+ * `GtkNotebook` uses the following roles:
  *
  *  - %GTK_ACCESSIBLE_ROLE_GROUP for the notebook widget
  *  - %GTK_ACCESSIBLE_ROLE_TAB_LIST for the list of tabs
@@ -154,6 +155,11 @@
  *  - %GTK_ACCESSIBLE_ROLE_TAB_PANEL for each page
  */
 
+/**
+ * GtkNotebookPage:
+ *
+ * `GtkNotebookPage` is an auxiliary object used by `GtkNotebook`.
+ */
 
 #define SCROLL_DELAY_FACTOR   5
 #define SCROLL_THRESHOLD      12
@@ -569,6 +575,11 @@ gtk_notebook_page_class_init (GtkNotebookPageClass *class)
   object_class->get_property = gtk_notebook_page_get_property;
   object_class->set_property = gtk_notebook_page_set_property;
 
+  /**
+   * GtkNotebookPage:child: (attributes org.gtk.Property.get=gtk_notebook_page_get_child)
+   *
+   * The child for this page.
+   */
   g_object_class_install_property (object_class,
                                    CHILD_PROP_CHILD,
                                    g_param_spec_object ("child",
@@ -576,6 +587,12 @@ gtk_notebook_page_class_init (GtkNotebookPageClass *class)
                                                         P_("The child for this page"),
                                                         GTK_TYPE_WIDGET,
                                                         GTK_PARAM_READWRITE|G_PARAM_CONSTRUCT_ONLY));
+
+  /**
+   * GtkNotebookPage:tab:
+   *
+   * The tab widget for tihs page.
+   */
   g_object_class_install_property (object_class,
                                    CHILD_PROP_TAB,
                                    g_param_spec_object ("tab",
@@ -583,6 +600,12 @@ gtk_notebook_page_class_init (GtkNotebookPageClass *class)
                                                         P_("The tab widget for this page"),
                                                         GTK_TYPE_WIDGET,
                                                         GTK_PARAM_READWRITE|G_PARAM_CONSTRUCT_ONLY));
+
+  /**
+   * GtkNotebookPage:menu:
+   *
+   * The label widget displayed in the childs menu entry.
+   */
   g_object_class_install_property (object_class,
                                    CHILD_PROP_MENU,
                                    g_param_spec_object ("menu",
@@ -590,6 +613,12 @@ gtk_notebook_page_class_init (GtkNotebookPageClass *class)
                                                         P_("The label widget displayed in the child’s menu 
entry"),
                                                         GTK_TYPE_WIDGET,
                                                         GTK_PARAM_READWRITE|G_PARAM_CONSTRUCT_ONLY));
+
+  /**
+   * GtkNotebookPage:tab-label:
+   *
+   * The text of the tab widget.
+   */
   g_object_class_install_property (object_class,
                                    CHILD_PROP_TAB_LABEL,
                                    g_param_spec_string ("tab-label",
@@ -597,6 +626,12 @@ gtk_notebook_page_class_init (GtkNotebookPageClass *class)
                                                         P_("The text of the tab widget"),
                                                         NULL,
                                                          GTK_PARAM_READWRITE));
+
+  /**
+   * GtkNotebookPage:menu-label:
+   *
+   * The text of the menu widget.
+   */
   g_object_class_install_property (object_class,
                                    CHILD_PROP_MENU_LABEL,
                                    g_param_spec_string ("menu-label",
@@ -604,6 +639,12 @@ gtk_notebook_page_class_init (GtkNotebookPageClass *class)
                                                         P_("The text of the menu widget"),
                                                         NULL,
                                                          GTK_PARAM_READWRITE));
+
+  /**
+   * GtkNotebookPage:position:
+   *
+   * The index of the child in the parent.
+   */
   g_object_class_install_property (object_class,
                                    CHILD_PROP_POSITION,
                                    g_param_spec_int ("position",
@@ -611,6 +652,12 @@ gtk_notebook_page_class_init (GtkNotebookPageClass *class)
                                                      P_("The index of the child in the parent"),
                                                      -1, G_MAXINT, 0,
                                                      GTK_PARAM_READWRITE));
+
+  /**
+   * GtkNotebookPage:tab-expand:
+   *
+   * Whether to expand the childs tab.
+   */
   g_object_class_install_property (object_class,
                                    CHILD_PROP_TAB_EXPAND,
                                    g_param_spec_boolean ("tab-expand",
@@ -618,6 +665,12 @@ gtk_notebook_page_class_init (GtkNotebookPageClass *class)
                                                          P_("Whether to expand the child’s tab"),
                                                          FALSE,
                                                          GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY));
+
+  /**
+   * GtkNotebookPage:tab-fill:
+   *
+   * Whether the childs tab should fill the allocated area.
+   */
   g_object_class_install_property (object_class,
                                    CHILD_PROP_TAB_FILL,
                                    g_param_spec_boolean ("tab-fill",
@@ -625,6 +678,12 @@ gtk_notebook_page_class_init (GtkNotebookPageClass *class)
                                                          P_("Whether the child’s tab should fill the 
allocated area"),
                                                          TRUE,
                                                          GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY));
+
+  /**
+   * GtkNotebookPage:reorderable:
+   *
+   * Whether the tab is reorderable by user action.
+   */
   g_object_class_install_property (object_class,
                                    CHILD_PROP_REORDERABLE,
                                    g_param_spec_boolean ("reorderable",
@@ -632,6 +691,12 @@ gtk_notebook_page_class_init (GtkNotebookPageClass *class)
                                                          P_("Whether the tab is reorderable by user action"),
                                                          FALSE,
                                                          GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY));
+
+  /**
+   * GtkNotebookPage:detachable:
+   *
+   * Whether the tab is detachable.
+   */
   g_object_class_install_property (object_class,
                                    CHILD_PROP_DETACHABLE,
                                    g_param_spec_boolean ("detachable",
@@ -1051,6 +1116,11 @@ gtk_notebook_class_init (GtkNotebookClass *class)
   class->reorder_tab = gtk_notebook_reorder_tab;
   class->create_window = gtk_notebook_create_window;
 
+  /**
+   * GtkNotebook:page: (attributes org.gtk.Property.get=gtk_notebook_get_current_page 
org.gtk.Property.set=gtk_notebook_set_current_page)
+   *
+   * The index of the current page.
+   */
   properties[PROP_PAGE] =
       g_param_spec_int ("page",
                         P_("Page"),
@@ -1059,6 +1129,11 @@ gtk_notebook_class_init (GtkNotebookClass *class)
                         -1,
                         GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
 
+  /**
+   * GtkNotebook:tab-pos: (attributes org.gtk.Property.get=gtk_notebook_get_tab_pos 
org.gtk.Property.set=gtk_notebook_set_tab_pos)
+   *
+   * Which side of the notebook holds the tabs.
+   */
   properties[PROP_TAB_POS] =
       g_param_spec_enum ("tab-pos",
                          P_("Tab Position"),
@@ -1067,6 +1142,11 @@ gtk_notebook_class_init (GtkNotebookClass *class)
                          GTK_POS_TOP,
                          GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
 
+  /**
+   * GtkNotebook:show-tabs: (attributes org.gtk.Property.get=gtk_notebook_get_show_tabs 
org.gtk.Property.set=gtk_notebook_set_show_tabs)
+   *
+   * Whether tabs should be shown.
+   */
   properties[PROP_SHOW_TABS] =
       g_param_spec_boolean ("show-tabs",
                             P_("Show Tabs"),
@@ -1074,6 +1154,11 @@ gtk_notebook_class_init (GtkNotebookClass *class)
                             TRUE,
                             GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
 
+  /**
+   * GtkNotebook:show-border: (attributes org.gtk.Property.get=gtk_notebook_get_show_border 
org.gtk.Property.set=gtk_notebook_set_show_border)
+   *
+   * Whether the border should be shown.
+   */
   properties[PROP_SHOW_BORDER] =
       g_param_spec_boolean ("show-border",
                             P_("Show Border"),
@@ -1081,6 +1166,11 @@ gtk_notebook_class_init (GtkNotebookClass *class)
                             TRUE,
                             GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
 
+  /**
+   * GtkNotebook:scrollable: (attributes org.gtk.Property.get=gtk_notebook_get_scrollable 
org.gtk.Property.set=gtk_notebook_set_scrollable)
+   *
+   * If %TRUE, scroll arrows are added if there are too many pages to fit.
+   */
   properties[PROP_SCROLLABLE] =
       g_param_spec_boolean ("scrollable",
                             P_("Scrollable"),
@@ -1088,6 +1178,11 @@ gtk_notebook_class_init (GtkNotebookClass *class)
                             FALSE,
                             GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
 
+  /**
+   * GtkNotebook:enable-popup:
+   *
+   * If %TRUE, pressing the right mouse button on the notebook shows a page switching menu.
+   */
   properties[PROP_ENABLE_POPUP] =
       g_param_spec_boolean ("enable-popup",
                             P_("Enable Popup"),
@@ -1096,7 +1191,7 @@ gtk_notebook_class_init (GtkNotebookClass *class)
                             GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
 
   /**
-   * GtkNotebook:group-name:
+   * GtkNotebook:group-name: (attributes org.gtk.Property.get=gtk_notebook_get_group_name 
org.gtk.Property.set=gtk_notebook_set_group_name)
    *
    * Group name for tab drag and drop.
    */
@@ -1107,6 +1202,11 @@ gtk_notebook_class_init (GtkNotebookClass *class)
                            NULL,
                            GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
 
+  /**
+   * GtkNotebook:pages: (attributes org.gtk.Property.get=gtk_notebook_get_pages)
+   *
+   * A selection model with the pages.
+   */
   properties[PROP_PAGES] = 
       g_param_spec_object ("pages",
                            P_("Pages"),
@@ -1197,7 +1297,7 @@ gtk_notebook_class_init (GtkNotebookClass *class)
                               _gtk_marshal_BOOLEAN__ENUM_BOOLEANv);
   /**
    * GtkNotebook::page-reordered:
-   * @notebook: the #GtkNotebook
+   * @notebook: the `GtkNotebook`
    * @child: the child #GtkWidget affected
    * @page_num: the new page number for @child
    *
@@ -1219,7 +1319,7 @@ gtk_notebook_class_init (GtkNotebookClass *class)
                               _gtk_marshal_VOID__OBJECT_UINTv);
   /**
    * GtkNotebook::page-removed:
-   * @notebook: the #GtkNotebook
+   * @notebook: the `GtkNotebook`
    * @child: the child #GtkWidget affected
    * @page_num: the @child page number
    *
@@ -1241,7 +1341,7 @@ gtk_notebook_class_init (GtkNotebookClass *class)
                               _gtk_marshal_VOID__OBJECT_UINTv);
   /**
    * GtkNotebook::page-added:
-   * @notebook: the #GtkNotebook
+   * @notebook: the `GtkNotebook`
    * @child: the child #GtkWidget affected
    * @page_num: the new page number for @child
    *
@@ -1264,7 +1364,7 @@ gtk_notebook_class_init (GtkNotebookClass *class)
 
   /**
    * GtkNotebook::create-window:
-   * @notebook: the #GtkNotebook emitting the signal
+   * @notebook: the `GtkNotebook` emitting the signal
    * @page: the tab of @notebook that is being detached
    *
    * The ::create-window signal is emitted when a detachable
@@ -1274,9 +1374,9 @@ gtk_notebook_class_init (GtkNotebookClass *class)
    * a notebook where the tab will be attached. It is also
    * responsible for moving/resizing the window and adding the
    * necessary properties to the notebook (e.g. the
-   * #GtkNotebook:group-name ).
+   * `GtkNotebook`:group-name ).
    *
-   * Returns: (transfer none): a #GtkNotebook that @page should be
+   * Returns: (transfer none): a `GtkNotebook` that @page should be
    *     added to, or %NULL.
    */
   notebook_signals[CREATE_WINDOW] =
@@ -1783,9 +1883,9 @@ gtk_notebook_reorder_tab (GtkNotebook      *notebook,
 /**
  * gtk_notebook_new:
  *
- * Creates a new #GtkNotebook widget with no pages.
+ * Creates a new `GtkNotebook` widget with no pages.
 
- * Returns: the newly created #GtkNotebook
+ * Returns: the newly created `GtkNotebook`
  */
 GtkWidget*
 gtk_notebook_new (void)
@@ -3323,12 +3423,12 @@ gtk_notebook_drag_drop (GtkDropTarget *dest,
 
 /**
  * gtk_notebook_detach_tab:
- * @notebook: a #GtkNotebook
+ * @notebook: a `GtkNotebook`
  * @child: a child
  *
  * Removes the child from the notebook.
  *
- * This function is very similar to gtk_notebook_remove_page(),
+ * This function is very similar to [method@Gtk.Notebook.remove_page],
  * but additionally informs the notebook that the removal
  * is happening as part of a tab DND operation, which should
  * not be cancelled.
@@ -5572,9 +5672,9 @@ gtk_notebook_menu_label_unparent (GtkWidget *widget)
  */
 /**
  * gtk_notebook_append_page:
- * @notebook: a #GtkNotebook
- * @child: the #GtkWidget to use as the contents of the page
- * @tab_label: (allow-none): the #GtkWidget to be used as the label
+ * @notebook: a `GtkNotebook`
+ * @child: the `GtkWidget` to use as the contents of the page
+ * @tab_label: (allow-none): the `GtkWidget` to be used as the label
  *     for the page, or %NULL to use the default label, “page N”
  *
  * Appends a page to @notebook.
@@ -5596,15 +5696,15 @@ gtk_notebook_append_page (GtkNotebook *notebook,
 
 /**
  * gtk_notebook_append_page_menu:
- * @notebook: a #GtkNotebook
- * @child: the #GtkWidget to use as the contents of the page
- * @tab_label: (allow-none): the #GtkWidget to be used as the label
+ * @notebook: a `GtkNotebook`
+ * @child: the `GtkWidget` to use as the contents of the page
+ * @tab_label: (allow-none): the `GtkWidget` to be used as the label
  *     for the page, or %NULL to use the default label, “page N”
  * @menu_label: (allow-none): the widget to use as a label for the
  *     page-switch menu, if that is enabled. If %NULL, and @tab_label
  *     is a #GtkLabel or %NULL, then the menu label will be a newly
  *     created label with the same text as @tab_label; if @tab_label
- *     is not a #GtkLabel, @menu_label must be specified if the
+ *     is not a `GtkLabel`, @menu_label must be specified if the
  *     page-switch menu is to be used.
  *
  * Appends a page to @notebook, specifying the widget to use as the
@@ -5629,8 +5729,8 @@ gtk_notebook_append_page_menu (GtkNotebook *notebook,
 
 /**
  * gtk_notebook_prepend_page:
- * @notebook: a #GtkNotebook
- * @child: the #GtkWidget to use as the contents of the page
+ * @notebook: a `GtkNotebook`
+ * @child: the `GtkWidget` to use as the contents of the page
  * @tab_label: (allow-none): the #GtkWidget to be used as the label
  *     for the page, or %NULL to use the default label, “page N”
  *
@@ -5653,9 +5753,9 @@ gtk_notebook_prepend_page (GtkNotebook *notebook,
 
 /**
  * gtk_notebook_prepend_page_menu:
- * @notebook: a #GtkNotebook
- * @child: the #GtkWidget to use as the contents of the page
- * @tab_label: (allow-none): the #GtkWidget to be used as the label
+ * @notebook: a `GtkNotebook`
+ * @child: the `GtkWidget` to use as the contents of the page
+ * @tab_label: (allow-none): the `GtkWidget` to be used as the label
  *     for the page, or %NULL to use the default label, “page N”
  * @menu_label: (allow-none): the widget to use as a label for the
  *     page-switch menu, if that is enabled. If %NULL, and @tab_label
@@ -5686,9 +5786,9 @@ gtk_notebook_prepend_page_menu (GtkNotebook *notebook,
 
 /**
  * gtk_notebook_insert_page:
- * @notebook: a #GtkNotebook
- * @child: the #GtkWidget to use as the contents of the page
- * @tab_label: (allow-none): the #GtkWidget to be used as the label
+ * @notebook: a `GtkNotebook`
+ * @child: the `GtkWidget` to use as the contents of the page
+ * @tab_label: (allow-none): the `GtkWidget` to be used as the label
  *     for the page, or %NULL to use the default label, “page N”
  * @position: the index (starting at 0) at which to insert the page,
  *     or -1 to append the page after all other pages
@@ -5743,9 +5843,9 @@ gtk_notebook_mnemonic_activate_switch_page (GtkWidget *child,
 
 /**
  * gtk_notebook_insert_page_menu:
- * @notebook: a #GtkNotebook
- * @child: the #GtkWidget to use as the contents of the page
- * @tab_label: (allow-none): the #GtkWidget to be used as the label
+ * @notebook: a `GtkNotebook`
+ * @child: the `GtkWidget` to use as the contents of the page
+ * @tab_label: (allow-none): the `GtkWidget` to be used as the label
  *     for the page, or %NULL to use the default label, “page N”
  * @menu_label: (allow-none): the widget to use as a label for the
  *     page-switch menu, if that is enabled. If %NULL, and @tab_label
@@ -5783,7 +5883,7 @@ gtk_notebook_insert_page_menu (GtkNotebook *notebook,
 
 /**
  * gtk_notebook_remove_page:
- * @notebook: a #GtkNotebook
+ * @notebook: a `GtkNotebook`
  * @page_num: the index of a notebook page, starting
  *     from 0. If -1, the last page will be removed.
  *
@@ -5814,9 +5914,10 @@ gtk_notebook_remove_page (GtkNotebook *notebook,
  * gtk_notebook_next_page
  * gtk_notebook_prev_page
  */
+
 /**
- * gtk_notebook_get_current_page:
- * @notebook: a #GtkNotebook
+ * gtk_notebook_get_current_page: (attributes org.gtk.Method.get_property=page)
+ * @notebook: a `GtkNotebook`
  *
  * Returns the page number of the current page.
  *
@@ -5837,7 +5938,7 @@ gtk_notebook_get_current_page (GtkNotebook *notebook)
 
 /**
  * gtk_notebook_get_nth_page:
- * @notebook: a #GtkNotebook
+ * @notebook: a `GtkNotebook`
  * @page_num: the index of a page in the notebook, or -1
  *     to get the last page
  *
@@ -5871,7 +5972,7 @@ gtk_notebook_get_nth_page (GtkNotebook *notebook,
 
 /**
  * gtk_notebook_get_n_pages:
- * @notebook: a #GtkNotebook
+ * @notebook: a `GtkNotebook`
  *
  * Gets the number of pages in a notebook.
  *
@@ -5887,8 +5988,8 @@ gtk_notebook_get_n_pages (GtkNotebook *notebook)
 
 /**
  * gtk_notebook_page_num:
- * @notebook: a #GtkNotebook
- * @child: a #GtkWidget
+ * @notebook: a `GtkNotebook`
+ * @child: a `GtkWidget`
  *
  * Finds the index of the page which contains the given child
  * widget.
@@ -5922,8 +6023,8 @@ gtk_notebook_page_num (GtkNotebook      *notebook,
 }
 
 /**
- * gtk_notebook_set_current_page:
- * @notebook: a #GtkNotebook
+ * gtk_notebook_set_current_page: (attributes org.gtk.Method.set_property=page)
+ * @notebook: a `GtkNotebook`
  * @page_num: index of the page to switch to, starting from 0.
  *     If negative, the last page will be used. If greater
  *     than the number of pages in the notebook, nothing
@@ -5954,10 +6055,11 @@ gtk_notebook_set_current_page (GtkNotebook *notebook,
 
 /**
  * gtk_notebook_next_page:
- * @notebook: a #GtkNotebook
+ * @notebook: a `GtkNotebook`
+ *
+ * Switches to the next page.
  *
- * Switches to the next page. Nothing happens if the current page is
- * the last page.
+ * Nothing happens if the current page is the last page.
  */
 void
 gtk_notebook_next_page (GtkNotebook *notebook)
@@ -5979,10 +6081,11 @@ gtk_notebook_next_page (GtkNotebook *notebook)
 
 /**
  * gtk_notebook_prev_page:
- * @notebook: a #GtkNotebook
+ * @notebook: a `GtkNotebook`
  *
- * Switches to the previous page. Nothing happens if the current page
- * is the first page.
+ * Switches to the previous page.
+ *
+ * Nothing happens if the current page is the first page.
  */
 void
 gtk_notebook_prev_page (GtkNotebook *notebook)
@@ -6014,13 +6117,13 @@ gtk_notebook_prev_page (GtkNotebook *notebook)
  * gtk_notebook_get_scrollable
  */
 /**
- * gtk_notebook_set_show_border:
- * @notebook: a #GtkNotebook
+ * gtk_notebook_set_show_border: (attributes org.gtk.Method.set_property=show-border)
+ * @notebook: a `GtkNotebook`
  * @show_border: %TRUE if a bevel should be drawn around the notebook
  *
  * Sets whether a bevel will be drawn around the notebook pages.
+ *
  * This only has a visual effect when the tabs are not shown.
- * See gtk_notebook_set_show_tabs().
  */
 void
 gtk_notebook_set_show_border (GtkNotebook *notebook,
@@ -6042,11 +6145,10 @@ gtk_notebook_set_show_border (GtkNotebook *notebook,
 }
 
 /**
- * gtk_notebook_get_show_border:
- * @notebook: a #GtkNotebook
+ * gtk_notebook_get_show_border: (attributes org.gtk.Method.get_property=show-border)
+ * @notebook: a `GtkNotebook`
  *
  * Returns whether a bevel will be drawn around the notebook pages.
- * See gtk_notebook_set_show_border().
  *
  * Returns: %TRUE if the bevel is drawn
  */
@@ -6059,8 +6161,8 @@ gtk_notebook_get_show_border (GtkNotebook *notebook)
 }
 
 /**
- * gtk_notebook_set_show_tabs:
- * @notebook: a #GtkNotebook
+ * gtk_notebook_set_show_tabs: (attributes org.gtk.Method.set_property=show-tabs)
+ * @notebook: a `GtkNotebook`
  * @show_tabs: %TRUE if the tabs should be shown
  *
  * Sets whether to show the tabs for the notebook or not.
@@ -6119,11 +6221,10 @@ gtk_notebook_set_show_tabs (GtkNotebook *notebook,
 }
 
 /**
- * gtk_notebook_get_show_tabs:
- * @notebook: a #GtkNotebook
+ * gtk_notebook_get_show_tabs: (attributes org.gtk.Method.get_property=show-tabs)
+ * @notebook: a `GtkNotebook`
  *
  * Returns whether the tabs of the notebook are shown.
- * See gtk_notebook_set_show_tabs().
  *
  * Returns: %TRUE if the tabs are shown
  */
@@ -6221,12 +6322,11 @@ gtk_notebook_update_tab_pos (GtkNotebook *notebook)
 }
 
 /**
- * gtk_notebook_set_tab_pos:
- * @notebook: a #GtkNotebook.
+ * gtk_notebook_set_tab_pos: (attributes org.gtk.Method.set_property=tab-pos)
+ * @notebook: a `GtkNotebook`.
  * @pos: the edge to draw the tabs at
  *
- * Sets the edge at which the tabs for switching pages in the
- * notebook are drawn.
+ * Sets the edge at which the tabs are drawn.
  */
 void
 gtk_notebook_set_tab_pos (GtkNotebook     *notebook,
@@ -6246,11 +6346,10 @@ gtk_notebook_set_tab_pos (GtkNotebook     *notebook,
 }
 
 /**
- * gtk_notebook_get_tab_pos:
- * @notebook: a #GtkNotebook
+ * gtk_notebook_get_tab_pos: (attributes org.gtk.Method.get_property=tab-pos)
+ * @notebook: a `GtkNotebook`
  *
- * Gets the edge at which the tabs for switching pages in the
- * notebook are drawn.
+ * Gets the edge at which the tabs are drawn.
  *
  * Returns: the edge at which the tabs are drawn
  */
@@ -6263,8 +6362,8 @@ gtk_notebook_get_tab_pos (GtkNotebook *notebook)
 }
 
 /**
- * gtk_notebook_set_scrollable:
- * @notebook: a #GtkNotebook
+ * gtk_notebook_set_scrollable: (attributes org.gtk.Method.set_property=scrollable)
+ * @notebook: a `GtkNotebook`
  * @scrollable: %TRUE if scroll arrows should be added
  *
  * Sets whether the tab label area will have arrows for
@@ -6292,11 +6391,10 @@ gtk_notebook_set_scrollable (GtkNotebook *notebook,
 }
 
 /**
- * gtk_notebook_get_scrollable:
- * @notebook: a #GtkNotebook
+ * gtk_notebook_get_scrollable: (attributes or.gtk.Method.get_property=scrollable)
+ * @notebook: a `GtkNotebook`
  *
  * Returns whether the tab label area has arrows for scrolling.
- * See gtk_notebook_set_scrollable().
  *
  * Returns: %TRUE if arrows for scrolling are present
  */
@@ -6318,11 +6416,12 @@ gtk_notebook_get_scrollable (GtkNotebook *notebook)
 
 /**
  * gtk_notebook_popup_enable:
- * @notebook: a #GtkNotebook
+ * @notebook: a `GtkNotebook`
+ *
+ * Enables the popup menu.
  *
- * Enables the popup menu: if the user clicks with the right
- * mouse button on the tab labels, a menu with all the pages
- * will be popped up.
+ * If the user clicks with the right mouse button on the tab labels,
+ * a menu with all the pages will be popped up.
  */
 void
 gtk_notebook_popup_enable (GtkNotebook *notebook)
@@ -6353,7 +6452,7 @@ gtk_notebook_popup_enable (GtkNotebook *notebook)
 
 /**
  * gtk_notebook_popup_disable:
- * @notebook: a #GtkNotebook
+ * @notebook: a `GtkNotebook`
  *
  * Disables the popup menu.
  */
@@ -6393,10 +6492,11 @@ gtk_notebook_popup_disable (GtkNotebook *notebook)
 
 /**
  * gtk_notebook_get_tab_label:
- * @notebook: a #GtkNotebook
+ * @notebook: a `GtkNotebook`
  * @child: the page
  *
  * Returns the tab label widget for the page @child.
+ *
  * %NULL is returned if @child is not in @notebook or
  * if no tab label has specifically been set for @child.
  *
@@ -6423,12 +6523,13 @@ gtk_notebook_get_tab_label (GtkNotebook *notebook,
 
 /**
  * gtk_notebook_set_tab_label:
- * @notebook: a #GtkNotebook
+ * @notebook: a `GtkNotebook`
  * @child: the page
  * @tab_label: (allow-none): the tab label widget to use, or %NULL
  *     for default tab label
  *
  * Changes the tab label for @child.
+ *
  * If %NULL is specified for @tab_label, then the page will
  * have the label “page N”.
  */
@@ -6501,7 +6602,7 @@ gtk_notebook_set_tab_label (GtkNotebook *notebook,
 
 /**
  * gtk_notebook_set_tab_label_text:
- * @notebook: a #GtkNotebook
+ * @notebook: a `GtkNotebook`
  * @child: the page
  * @tab_text: the label text
  *
@@ -6524,15 +6625,15 @@ gtk_notebook_set_tab_label_text (GtkNotebook *notebook,
 
 /**
  * gtk_notebook_get_tab_label_text:
- * @notebook: a #GtkNotebook
+ * @notebook: a `GtkNotebook`
  * @child: a widget contained in a page of @notebook
  *
  * Retrieves the text of the tab label for the page containing
  * @child.
  *
- * Returns: (nullable): the text of the tab label, or %NULL if the tab label
- * widget is not a #GtkLabel. The string is owned by the widget and must not be
- * freed.
+ * Returns: (nullable): the text of the tab label, or %NULL if
+ *   the tab label idget is not a `GtkLabel`. The string is owned
+ *   by the widget and must not be freed.
  */
 const char *
 gtk_notebook_get_tab_label_text (GtkNotebook *notebook,
@@ -6553,14 +6654,14 @@ gtk_notebook_get_tab_label_text (GtkNotebook *notebook,
 
 /**
  * gtk_notebook_get_menu_label:
- * @notebook: a #GtkNotebook
+ * @notebook: a `GtkNotebook`
  * @child: a widget contained in a page of @notebook
  *
  * Retrieves the menu label widget of the page containing @child.
  *
- * Returns: (nullable) (transfer none): the menu label, or %NULL if the
- * notebook page does not have a menu label other than the default (the tab
- * label).
+ * Returns: (nullable) (transfer none): the menu label, or %NULL
+ *   if the notebook page does not have a menu label other than
+ *   the default (the tab label).
  */
 GtkWidget*
 gtk_notebook_get_menu_label (GtkNotebook *notebook,
@@ -6582,7 +6683,7 @@ gtk_notebook_get_menu_label (GtkNotebook *notebook,
 
 /**
  * gtk_notebook_set_menu_label:
- * @notebook: a #GtkNotebook
+ * @notebook: a `GtkNotebook`
  * @child: the child widget
  * @menu_label: (allow-none): the menu label, or %NULL for default
  *
@@ -6627,7 +6728,7 @@ gtk_notebook_set_menu_label (GtkNotebook *notebook,
 
 /**
  * gtk_notebook_set_menu_label_text:
- * @notebook: a #GtkNotebook
+ * @notebook: a `GtkNotebook`
  * @child: the child widget
  * @menu_text: the label text
  *
@@ -6653,16 +6754,16 @@ gtk_notebook_set_menu_label_text (GtkNotebook *notebook,
 
 /**
  * gtk_notebook_get_menu_label_text:
- * @notebook: a #GtkNotebook
+ * @notebook: a `GtkNotebook`
  * @child: the child widget of a page of the notebook.
  *
  * Retrieves the text of the menu label for the page containing
  * @child.
  *
- * Returns: (nullable): the text of the tab label, or %NULL if the widget does
- * not have a menu label other than the default menu label, or the menu label
- * widget is not a #GtkLabel. The string is owned by the widget and must not be
- * freed.
+ * Returns: (nullable): the text of the tab label, or %NULL if
+ *   the widget does not have a menu label other than the default
+ *   menu label, or the menu label widget is not a `GtkLabel`.
+ *   The string is owned by the widget and must not be freed.
  */
 const char *
 gtk_notebook_get_menu_label_text (GtkNotebook *notebook,
@@ -6712,14 +6813,15 @@ gtk_notebook_child_reordered (GtkNotebook     *notebook,
 
 /**
  * gtk_notebook_reorder_child:
- * @notebook: a #GtkNotebook
+ * @notebook: a `GtkNotebook`
  * @child: the child to move
  * @position: the new position, or -1 to move to the end
  *
  * Reorders the page containing @child, so that it appears in position
- * @position. If @position is greater than or equal to the number of
- * children in the list or negative, @child will be moved to the end
- * of the list.
+ * @position.
+ *
+ * If @position is greater than or equal to the number of children in
+ * the list or negative, @child will be moved to the end of the list.
  */
 void
 gtk_notebook_reorder_child (GtkNotebook *notebook,
@@ -6776,8 +6878,8 @@ gtk_notebook_reorder_child (GtkNotebook *notebook,
 }
 
 /**
- * gtk_notebook_set_group_name:
- * @notebook: a #GtkNotebook
+ * gtk_notebook_set_group_name: (attributes org.gtk.Method.set_property=group-name)
+ * @notebook: a `GtkNotebook`
  * @group_name: (allow-none): the name of the notebook group,
  *     or %NULL to unset it
  *
@@ -6806,12 +6908,13 @@ gtk_notebook_set_group_name (GtkNotebook *notebook,
 }
 
 /**
- * gtk_notebook_get_group_name:
- * @notebook: a #GtkNotebook
+ * gtk_notebook_get_group_name: (attributes org.gtk.Method.get_property=group-name)
+ * @notebook: a `GtkNotebook`
  *
  * Gets the current group name for @notebook.
  *
- * Returns: (nullable) (transfer none): the group name, or %NULL if none is set
+ * Returns: (nullable) (transfer none): the group name,
+ *   or %NULL if none is set
  */
 const char *
 gtk_notebook_get_group_name (GtkNotebook *notebook)
@@ -6823,8 +6926,8 @@ gtk_notebook_get_group_name (GtkNotebook *notebook)
 
 /**
  * gtk_notebook_get_tab_reorderable:
- * @notebook: a #GtkNotebook
- * @child: a child #GtkWidget
+ * @notebook: a `GtkNotebook`
+ * @child: a child `GtkWidget`
  *
  * Gets whether the tab can be reordered via drag and drop or not.
  *
@@ -6847,8 +6950,8 @@ gtk_notebook_get_tab_reorderable (GtkNotebook *notebook,
 
 /**
  * gtk_notebook_set_tab_reorderable:
- * @notebook: a #GtkNotebook
- * @child: a child #GtkWidget
+ * @notebook: a `GtkNotebook`
+ * @child: a child `GtkWidget`
  * @reorderable: whether the tab is reorderable or not
  *
  * Sets whether the notebook tab can be reordered
@@ -6885,8 +6988,8 @@ gtk_notebook_set_tab_reorderable (GtkNotebook *notebook,
 
 /**
  * gtk_notebook_get_tab_detachable:
- * @notebook: a #GtkNotebook
- * @child: a child #GtkWidget
+ * @notebook: a `GtkNotebook`
+ * @child: a child `GtkWidget`
  *
  * Returns whether the tab contents can be detached from @notebook.
  *
@@ -6909,15 +7012,15 @@ gtk_notebook_get_tab_detachable (GtkNotebook *notebook,
 
 /**
  * gtk_notebook_set_tab_detachable:
- * @notebook: a #GtkNotebook
- * @child: a child #GtkWidget
+ * @notebook: a `GtkNotebook`
+ * @child: a child `GtkWidget`
  * @detachable: whether the tab is detachable or not
  *
  * Sets whether the tab can be detached from @notebook to another
  * notebook or widget.
  *
- * Note that 2 notebooks must share a common group identificator
- * (see gtk_notebook_set_group_name()) to allow automatic tabs
+ * Note that two notebooks must share a common group identificator
+ * (see [method@Gtk.Notebook.set_group_name]) to allow automatic tabs
  * interchange between them.
  *
  * If you want a widget to interact with a notebook through DnD
@@ -6926,34 +7029,34 @@ gtk_notebook_get_tab_detachable (GtkNotebook *notebook,
  * will fill the selection with a GtkWidget** pointing to the child
  * widget that corresponds to the dropped tab.
  *
- * Note that you should use gtk_notebook_detach_tab() instead of
- * gtk_notebook_remove_page() if you want to remove the tab from
- * the source notebook as part of accepting a drop. Otherwise,
- * the source notebook will think that the dragged tab was
- * removed from underneath the ongoing drag operation, and
- * will initiate a drag cancel animation.
+ * Note that you should use [method@Gtk.Notebook.detach_tab] instead
+ * of [method@Gtk.Notebook.remove_page] if you want to remove the tab
+ * from the source notebook as part of accepting a drop. Otherwise,
+ * the source notebook will think that the dragged tab was removed
+ * from underneath the ongoing drag operation, and will initiate a
+ * drag cancel animation.
  *
- * |[<!-- language="C" -->
- *  static void
- *  on_drag_data_received (GtkWidget        *widget,
- *                         GdkDrop          *drop,
- *                         GtkSelectionData *data,
- *                         guint             time,
- *                         gpointer          user_data)
- *  {
- *    GtkDrag *drag;
- *    GtkWidget *notebook;
- *    GtkWidget **child;
+ * ```c
+ * static void
+ * on_drag_data_received (GtkWidget        *widget,
+ *                        GdkDrop          *drop,
+ *                        GtkSelectionData *data,
+ *                        guint             time,
+ *                        gpointer          user_data)
+ * {
+ *   GtkDrag *drag;
+ *   GtkWidget *notebook;
+ *   GtkWidget **child;
  *
- *    drag = gtk_drop_get_drag (drop);
- *    notebook = g_object_get_data (drag, "gtk-notebook-drag-origin");
- *    child = (void*) gtk_selection_data_get_data (data);
+ *   drag = gtk_drop_get_drag (drop);
+ *   notebook = g_object_get_data (drag, "gtk-notebook-drag-origin");
+ *   child = (void*) gtk_selection_data_get_data (data);
  *
- *    // process_widget (*child);
+ *   // process_widget (*child);
  *
- *    gtk_notebook_detach_tab (GTK_NOTEBOOK (notebook), *child);
- *  }
- * ]|
+ *   gtk_notebook_detach_tab (GTK_NOTEBOOK (notebook), *child);
+ * }
+ * ```
  *
  * If you want a notebook to accept drags from other widgets,
  * you will have to set your own DnD code to do it.
@@ -6984,13 +7087,16 @@ gtk_notebook_set_tab_detachable (GtkNotebook *notebook,
 
 /**
  * gtk_notebook_get_action_widget:
- * @notebook: a #GtkNotebook
+ * @notebook: a `GtkNotebook`
  * @pack_type: pack type of the action widget to receive
  *
- * Gets one of the action widgets. See gtk_notebook_set_action_widget().
+ * Gets one of the action widgets.
+ *
+ * See [method@Gtk.Notebook.set_action_widget].
  *
- * Returns: (nullable) (transfer none): The action widget with the given
- * @pack_type or %NULL when this action widget has not been set
+ * Returns: (nullable) (transfer none): The action widget
+ *   with the given @pack_type or %NULL when this action
+ *   widget has not been set
  */
 GtkWidget*
 gtk_notebook_get_action_widget (GtkNotebook *notebook,
@@ -7003,13 +7109,15 @@ gtk_notebook_get_action_widget (GtkNotebook *notebook,
 
 /**
  * gtk_notebook_set_action_widget:
- * @notebook: a #GtkNotebook
+ * @notebook: a `GtkNotebook`
  * @widget: a #GtkWidget
  * @pack_type: pack type of the action widget
  *
- * Sets @widget as one of the action widgets. Depending on the pack type
- * the widget will be placed before or after the tabs. You can use
- * a #GtkBox if you need to pack more than one widget on the same side.
+ * Sets @widget as one of the action widgets.
+ *
+ * Depending on the pack type the widget will be placed before
+ * or after the tabs. You can use a `GtkBox` if you need to pack
+ * more than one widget on the same side.
  */
 void
 gtk_notebook_set_action_widget (GtkNotebook *notebook,
@@ -7040,12 +7148,12 @@ gtk_notebook_set_action_widget (GtkNotebook *notebook,
 
 /**
  * gtk_notebook_get_page:
- * @notebook: a #GtkNotebook
+ * @notebook: a `GtkNotebook`
  * @child: a child of @notebook
  *
- * Returns the #GtkNotebookPage for @child.
+ * Returns the `GtkNotebookPage` for @child.
  *
- * Returns: (transfer none): the #GtkNotebookPage for @child
+ * Returns: (transfer none): the `GtkNotebookPage` for @child
  */
 GtkNotebookPage *
 gtk_notebook_get_page (GtkNotebook *notebook,
@@ -7065,8 +7173,8 @@ gtk_notebook_get_page (GtkNotebook *notebook,
 }
 
 /**
- * gtk_notebook_page_get_child:
- * @page: a #GtkNotebookPage
+ * gtk_notebook_page_get_child: (attributes org.gtk.Method.get_property=child)
+ * @page: a `GtkNotebookPage`
  *
  * Returns the notebook child to which @page belongs.
  *
@@ -7151,14 +7259,17 @@ gtk_notebook_pages_new (GtkNotebook *notebook)
 }
 
 /**
- * gtk_notebook_get_pages:
- * @notebook: a #GtkNotebook
+ * gtk_notebook_get_pages: (attributes org.gtk.Method.get_property=pages)
+ * @notebook: a `GtkNotebook`
  *
- * Returns a #GListModel that contains the pages of the notebook,
- * and can be used to keep an up-to-date view.
- * 
+ * Returns a `GListModel` that contains the pages of the notebook.
+ *
+ * This can be used to keep an up-to-date view. The model also
+ * implements [iface@Gtk.SelectionModel] and can be used to track
+ * and modify the visible page.
+
  * Returns: (transfer full) (attributes element-type=GtkNotebookPage): a
- *   #GListModel for the notebook's children
+ *   `GListModel` for the notebook's children
  */
 GListModel *
 gtk_notebook_get_pages (GtkNotebook *notebook)
diff --git a/gtk/gtknotebook.h b/gtk/gtknotebook.h
index d219f78c42..73139d6580 100644
--- a/gtk/gtknotebook.h
+++ b/gtk/gtknotebook.h
@@ -44,13 +44,6 @@ G_BEGIN_DECLS
 #define GTK_NOTEBOOK_PAGE(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), GTK_TYPE_NOTEBOOK_PAGE, GtkNotebookPage))
 #define GTK_IS_NOTEBOOK_PAGE(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GTK_TYPE_NOTEBOOK_PAGE))
 
-/**
- * GtkNotebookPage:
- *
- * A page in the #GtkNotebook.
- *
- * The `GtkNotebookPage` structure only contains private data.
- */
 typedef struct _GtkNotebookPage GtkNotebookPage;
 
 /**
@@ -58,7 +51,7 @@ typedef struct _GtkNotebookPage GtkNotebookPage;
  * @GTK_NOTEBOOK_TAB_FIRST: the first tab in the notebook
  * @GTK_NOTEBOOK_TAB_LAST: the last tab in the notebook
  *
- * The parameter used in the action signals of #GtkNotebook.
+ * The parameter used in the action signals of `GtkNotebook`.
  */
 typedef enum
 {


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]