docs: Move documentation to inline comments: GtkNotebook

4 files changed, 71 insertions, 710 deletions

diff --git a/docs/reference/gtk/tmpl/.gitignore b/docs/reference/gtk/tmpl/.gitignore
index 622da335ed..e21801899e 100644
--- a/docs/reference/gtk/tmpl/.gitignore
+++ b/docs/reference/gtk/tmpl/.gitignore
@@ -16,6 +16,7 @@ gtkimcontextsimple.sgml
 gtkimmulticontext.sgml
 gtklinkbutton.sgml
 gtkmessagedialog.sgml
+gtknotebook.sgml
 gtkobject.sgml
 gtkorientable.sgml
 gtkpagesetupunixdialog.sgml
diff --git a/docs/reference/gtk/tmpl/gtknotebook.sgml b/docs/reference/gtk/tmpl/gtknotebook.sgml
deleted file mode 100644
index 25035b1cab..0000000000
--- a/docs/reference/gtk/tmpl/gtknotebook.sgml
+++ /dev/null
@@ -1,709 +0,0 @@
-<!-- ##### SECTION Title ##### -->
-GtkNotebook
-
-<!-- ##### SECTION Short_Description ##### -->
-A tabbed notebook container
-
-<!-- ##### SECTION Long_Description ##### -->
-<para>
-The #GtkNotebook widget is a #GtkContainer whose children are pages that
-can be switched between using tab labels along one edge.
-</para>
-<para>
-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())
-</para>
-
-<refsect2 id="GtkNotebook-BUILDER-UI">
-<title>GtkNotebook as GtkBuildable</title>
-<para>
-The GtkNoteboopk implementation of the GtkBuildable interface
-supports placing children into tabs by specifying "tab" as the
-"type" attribute of a &lt;child&gt; element. Note that the content
-of the tab must be created before the tab can be filled.
-A tab child can be specified without specifying a &lt;child&gt;
-type attribute.
-</para>
-<para>
-To add a child widget in the notebooks action area, specify
-"action-start" or "action-end" as the "type" attribute of the &lt;child&gt;
-element.
-</para>
-<example>
-<title>A UI definition fragment with GtkNotebook</title>
-<programlisting><![CDATA[
-<object class="GtkNotebook">
-  <child>
-    <object class="GtkLabel" id="notebook-content">
-      <property name="label">Content</property>
-    </object>
-  </child>
-  <child type="tab">
-    <object class="GtkLabel" id="notebook-tab">
-      <property name="label">Tab</property>
-    </object>
-  </child>
-</object>
-]]></programlisting>
-</example>
-</refsect2>
-
-<!-- ##### SECTION See_Also ##### -->
-<para>
-<variablelist>
-<varlistentry>
-<term>#GtkContainer</term>
-<listitem><para>For functions that apply to every #GtkContainer</para></listitem>
-</varlistentry>
-</variablelist>
-</para>
-
-<!-- ##### SECTION Stability_Level ##### -->
-
-
-<!-- ##### SECTION Image ##### -->
-
-
-<!-- ##### STRUCT GtkNotebook ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### SIGNAL GtkNotebook::change-current-page ##### -->
-<para>
-
-</para>
-
-@notebook: the object which received the signal.
-@arg1: 
-@Returns: 
-
-<!-- ##### SIGNAL GtkNotebook::create-window ##### -->
-<para>
-
-</para>
-
-@notebook: the object which received the signal.
-@widget: 
-@arg1: 
-@arg2: 
-@Returns: 
-
-<!-- ##### SIGNAL GtkNotebook::focus-tab ##### -->
-<para>
-
-</para>
-
-@notebook: the object which received the signal.
-@arg1: 
-@Returns: 
-
-<!-- ##### SIGNAL GtkNotebook::move-focus-out ##### -->
-<para>
-
-</para>
-
-@notebook: the object which received the signal.
-@arg1: 
-
-<!-- ##### SIGNAL GtkNotebook::page-added ##### -->
-<para>
-
-</para>
-
-@notebook: the object which received the signal.
-@widget: 
-@arg1: 
-
-<!-- ##### SIGNAL GtkNotebook::page-removed ##### -->
-<para>
-
-</para>
-
-@notebook: the object which received the signal.
-@widget: 
-@arg1: 
-
-<!-- ##### SIGNAL GtkNotebook::page-reordered ##### -->
-<para>
-
-</para>
-
-@notebook: the object which received the signal.
-@widget: 
-@arg1: 
-
-<!-- ##### SIGNAL GtkNotebook::reorder-tab ##### -->
-<para>
-
-</para>
-
-@notebook: the object which received the signal.
-@arg1: 
-@Param3: 
-@Returns: 
-
-<!-- ##### SIGNAL GtkNotebook::select-page ##### -->
-<para>
-
-</para>
-
-@notebook: the object which received the signal.
-@arg1: 
-@Returns: 
-
-<!-- ##### SIGNAL GtkNotebook::switch-page ##### -->
-<para>
-Emitted when the user or a function changes the current page.
-</para>
-
-@notebook: the object which received the signal.
-@page: the new current page
-@page_num: the index of the page
-
-<!-- ##### ARG GtkNotebook:enable-popup ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkNotebook:group ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkNotebook:page ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkNotebook:scrollable ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkNotebook:show-border ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkNotebook:show-tabs ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkNotebook:tab-pos ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkNotebook:detachable ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkNotebook:menu-label ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkNotebook:position ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkNotebook:reorderable ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkNotebook:tab-expand ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkNotebook:tab-fill ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkNotebook:tab-label ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkNotebook:tab-pack ##### -->
-<para>
- Deprecated: 2.20: The tab packing functionality of children should not
- be used anymore and support will be removed in the future.
-</para>
-
-<!-- ##### ARG GtkNotebook:arrow-spacing ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkNotebook:has-backward-stepper ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkNotebook:has-forward-stepper ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkNotebook:has-secondary-backward-stepper ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkNotebook:has-secondary-forward-stepper ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkNotebook:tab-curvature ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkNotebook:tab-overlap ##### -->
-<para>
-
-</para>
-
-<!-- ##### FUNCTION gtk_notebook_new ##### -->
-<para>
-</para>
-
-@void: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_notebook_append_page ##### -->
-<para>
-</para>
-
-@notebook: 
-@child: 
-@tab_label: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_notebook_append_page_menu ##### -->
-<para>
-</para>
-
-@notebook: 
-@child: 
-@tab_label: 
-@menu_label: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_notebook_prepend_page ##### -->
-<para>
-</para>
-
-@notebook: 
-@child: the
-@tab_label: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_notebook_prepend_page_menu ##### -->
-<para>
-</para>
-
-@notebook: 
-@child: 
-@tab_label: 
-@menu_label: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_notebook_insert_page ##### -->
-<para>
-</para>
-
-@notebook: 
-@child: 
-@tab_label: 
-@position: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_notebook_insert_page_menu ##### -->
-<para>
-</para>
-
-@notebook: 
-@child: 
-@tab_label: 
-@menu_label: 
-@position: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_notebook_remove_page ##### -->
-<para>
-</para>
-
-@notebook: 
-@page_num: 
-
-
-<!-- ##### FUNCTION gtk_notebook_page_num ##### -->
-<para>
-</para>
-
-@notebook: 
-@child: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_notebook_next_page ##### -->
-<para>
-</para>
-
-@notebook: 
-
-
-<!-- ##### FUNCTION gtk_notebook_prev_page ##### -->
-<para>
-</para>
-
-@notebook: 
-
-
-<!-- ##### FUNCTION gtk_notebook_reorder_child ##### -->
-<para>
-</para>
-
-@notebook: 
-@child: 
-@position: 
-
-
-<!-- ##### FUNCTION gtk_notebook_set_tab_pos ##### -->
-<para>
-</para>
-
-@notebook: the notebook widget
-@pos: the position
-
-
-<!-- ##### FUNCTION gtk_notebook_set_show_tabs ##### -->
-<para>
-</para>
-
-@notebook: 
-@show_tabs: 
-
-
-<!-- ##### FUNCTION gtk_notebook_set_show_border ##### -->
-<para>
-</para>
-
-@notebook: 
-@show_border: 
-
-
-<!-- ##### FUNCTION gtk_notebook_set_scrollable ##### -->
-<para>
-</para>
-
-@notebook: 
-@scrollable: 
-
-
-<!-- ##### FUNCTION gtk_notebook_popup_enable ##### -->
-<para>
-</para>
-
-@notebook: 
-
-
-<!-- ##### FUNCTION gtk_notebook_popup_disable ##### -->
-<para>
-</para>
-
-@notebook: 
-
-
-<!-- ##### FUNCTION gtk_notebook_get_current_page ##### -->
-<para>
-</para>
-
-@notebook: the notebook widget
-@Returns: the page number
-
-
-<!-- ##### FUNCTION gtk_notebook_get_menu_label ##### -->
-<para>
-</para>
-
-@notebook: 
-@child: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_notebook_get_nth_page ##### -->
-<para>
-</para>
-
-@notebook: 
-@page_num: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_notebook_get_n_pages ##### -->
-<para>
-
-</para>
-
-@notebook: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_notebook_get_tab_label ##### -->
-<para>
-</para>
-
-@notebook: 
-@child: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_notebook_set_menu_label ##### -->
-<para>
-</para>
-
-@notebook: 
-@child: 
-@menu_label: 
-
-
-<!-- ##### FUNCTION gtk_notebook_set_menu_label_text ##### -->
-<para>
-</para>
-
-@notebook: 
-@child: 
-@menu_text: 
-
-
-<!-- ##### FUNCTION gtk_notebook_set_tab_label ##### -->
-<para>
-</para>
-
-@notebook: 
-@child: 
-@tab_label: 
-
-
-<!-- ##### FUNCTION gtk_notebook_set_tab_label_text ##### -->
-<para>
-</para>
-
-@notebook: 
-@child: 
-@tab_text: 
-
-
-<!-- ##### FUNCTION gtk_notebook_set_tab_reorderable ##### -->
-<para>
-
-</para>
-
-@notebook: 
-@child: 
-@reorderable: 
-
-
-<!-- ##### FUNCTION gtk_notebook_set_tab_detachable ##### -->
-<para>
-
-</para>
-
-@notebook: 
-@child: 
-@detachable: 
-
-
-<!-- ##### FUNCTION gtk_notebook_get_menu_label_text ##### -->
-<para>
-
-</para>
-
-@notebook: 
-@child: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_notebook_get_scrollable ##### -->
-<para>
-
-</para>
-
-@notebook: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_notebook_get_show_border ##### -->
-<para>
-
-</para>
-
-@notebook: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_notebook_get_show_tabs ##### -->
-<para>
-
-</para>
-
-@notebook: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_notebook_get_tab_label_text ##### -->
-<para>
-
-</para>
-
-@notebook: 
-@child: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_notebook_get_tab_pos ##### -->
-<para>
-
-</para>
-
-@notebook: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_notebook_get_tab_reorderable ##### -->
-<para>
-
-</para>
-
-@notebook: 
-@child: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_notebook_get_tab_detachable ##### -->
-<para>
-
-</para>
-
-@notebook: 
-@child: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_notebook_get_tab_hborder ##### -->
-<para>
-
-</para>
-
-@notebook: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_notebook_get_tab_vborder ##### -->
-<para>
-
-</para>
-
-@notebook: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_notebook_set_current_page ##### -->
-<para>
-
-</para>
-
-@notebook: 
-@page_num: 
-
-
-<!-- ##### FUNCTION gtk_notebook_set_group ##### -->
-<para>
-
-</para>
-
-@notebook: 
-@group: 
-
-
-<!-- ##### FUNCTION gtk_notebook_get_group ##### -->
-<para>
-
-</para>
-
-@notebook: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_notebook_set_action_widget ##### -->
-<para>
-
-</para>
-
-@notebook: 
-@widget: 
-@pack_type: 
-
-
-<!-- ##### FUNCTION gtk_notebook_get_action_widget ##### -->
-<para>
-
-</para>
-
-@notebook: 
-@pack_type: 
-@Returns: 
-
-
-<!-- ##### USER_FUNCTION GtkNotebookWindowCreationFunc ##### -->
-<para>
-A function used by GtkNotebook when a detachable tab is dropped
-in the root window, it's used to create a window containing a notebook
-where the tab will be attached. This function will also be responsible
-of moving/resizing the window and adding the necessary properties to
-the notebook (i.e.: group-id).
-
-If the function returns %NULL, the drag will be cancelled.
-</para>
-
-@source: The source #GtkNotebook of the drag operation
-@page: the child #GtkWidget affected
-@x: the X coordinate where the drop happens
-@y: the Y coordinate where the drop happens
-@data: user data
-@Returns: The created #GtkNotebook where the tab will be attached, or NULL to cancel the drag
-
-
-<!-- ##### FUNCTION gtk_notebook_set_window_creation_hook ##### -->
-<para>
-
-</para>
-
-@func: 
-@data: 
-@destroy: 
-
-
diff --git a/gtk/gtknotebook.c b/gtk/gtknotebook.c
index 6bc6b1f9b7..58b6a4d370 100644
--- a/gtk/gtknotebook.c
+++ b/gtk/gtknotebook.c
@@ -45,6 +45,60 @@
 #include "gtkdnd.h"
 #include "gtkbuildable.h"
 
+
+/**
+ * SECTION:gtknotebook
+ * @Short_description: A tabbed notebook container
+ * @Title: GtkNotebook
+ * @See_also: #GtkContainer
+ *
+ * The #GtkNotebook widget is a #GtkContainer whose children are pages that
+ * can be switched between using tab labels along one edge.
+ *
+ * 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())
+ *
+ * <refsect2 id="GtkNotebook-BUILDER-UI">
+ * <title>GtkNotebook as GtkBuildable</title>
+ * <para>
+ * The GtkNotebook implementation of the #GtkBuildable interface
+ * supports placing children into tabs by specifying "tab" as the
+ * "type" attribute of a &lt;child&gt; element. Note that the content
+ * of the tab must be created before the tab can be filled.
+ * A tab child can be specified without specifying a &lt;child&gt;
+ * type attribute.
+ * </para>
+ * <para>
+ * To add a child widget in the notebooks action area, specify
+ * "action-start" or "action-end" as the "type" attribute of the &lt;child&gt;
+ * element.
+ * <para>
+ * <example>
+ * <title>A UI definition fragment with GtkNotebook</title>
+ * <programlisting><![CDATA[
+ * <object class="GtkNotebook">
+ *   <child>
+ *     <object class="GtkLabel" id="notebook-content">
+ *       <property name="label">Content</property>
+ *     </object>
+ *   </child>
+ *   <child type="tab">
+ *     <object class="GtkLabel" id="notebook-tab">
+ *       <property name="label">Tab</property>
+ *     </object>
+ *   </child>
+ * </object>
+ * ]]></programlisting>
+ * </example>
+ * </refsect2>
+ */
+
+
 #define SCROLL_DELAY_FACTOR   5
 #define SCROLL_THRESHOLD      12
 #define DND_THRESHOLD_MULTIPLIER 4
@@ -685,6 +739,13 @@ gtk_notebook_class_init (GtkNotebookClass *class)
 								    P_("Whether the child's tab should fill the allocated area"),
 								    TRUE,
 								    GTK_PARAM_READWRITE));
+
+  /**
+   * GtkNotebook:tab-pack:
+   *
+   *  Deprecated: 2.20: The tab packing functionality of children should not
+   *  be used anymore and support will be removed in the future.
+   */
   gtk_container_class_install_child_property (container_class,
 					      CHILD_PROP_TAB_PACK,
 					      g_param_spec_enum ("tab-pack", 
@@ -819,6 +880,14 @@ gtk_notebook_class_init (GtkNotebookClass *class)
                                                              0,
                                                              GTK_PARAM_READABLE));
 
+  /**
+   * GtkNotebook::switch-page:
+   * @notebook: the object which received the signal.
+   * @page: the new current page
+   * @page_num: the index of the page
+   *
+   * Emitted when the user or a function changes the current page.
+   */
   notebook_signals[SWITCH_PAGE] =
     g_signal_new (I_("switch-page"),
 		  G_TYPE_FROM_CLASS (gobject_class),
diff --git a/gtk/gtknotebook.h b/gtk/gtknotebook.h
index 553a4840d9..ef862dc8ed 100644
--- a/gtk/gtknotebook.h
+++ b/gtk/gtknotebook.h
@@ -58,9 +58,9 @@ typedef struct _GtkNotebookClass         GtkNotebookClass;
 
 struct _GtkNotebook
 {
+  /* <private> */
   GtkContainer container;
 
-  /* <private> */
   GtkNotebookPrivate *priv;
 };