docs: Move documentation to inline comments: GtkComboBox

4 files changed, 34 insertions, 464 deletions

diff --git a/docs/reference/gtk/tmpl/.gitignore b/docs/reference/gtk/tmpl/.gitignore
index e21801899e..24fa3ad14d 100644
--- a/docs/reference/gtk/tmpl/.gitignore
+++ b/docs/reference/gtk/tmpl/.gitignore
@@ -7,6 +7,7 @@ gtkbuilder.sgml
 gtkbutton.sgml
 gtkcalendar.sgml
 gtkcelleditable.sgml
+gtkcombobox.sgml
 gtkcomboboxentry.sgml
 gtkeditable.sgml
 gtkentrybuffer.sgml
diff --git a/docs/reference/gtk/tmpl/gtkcombobox.sgml b/docs/reference/gtk/tmpl/gtkcombobox.sgml
deleted file mode 100644
index b4e303f1b2..0000000000
--- a/docs/reference/gtk/tmpl/gtkcombobox.sgml
+++ /dev/null
@@ -1,461 +0,0 @@
-<!-- ##### SECTION Title ##### -->
-GtkComboBox
-
-<!-- ##### SECTION Short_Description ##### -->
-A widget used to choose from a list of items
-
-<!-- ##### SECTION Long_Description ##### -->
-<para>
-A #GtkComboBox is a widget that allows the user to choose from a
-list of valid choices.  The #GtkComboBox displays the selected 
-choice.  When activated, the #GtkComboBox displays a popup 
-which allows the user to make a new choice. The style in which 
-the selected value is displayed, and the style of the popup is
-determined by the current theme. It may be similar to a #GtkOptionMenu,
-or similar to a Windows-style combo box.
-</para>
-
-<para>
-Unlike its predecessors #GtkCombo and #GtkOptionMenu, the #GtkComboBox
-uses the model-view pattern; the list of valid choices is specified in the
-form of a tree model, and the display of the choices can be adapted to
-the data in the model by using cell renderers, as you would in a tree view.
-This is possible since #GtkComboBox implements the #GtkCellLayout interface.
-The tree model holding the valid choices is not restricted to a flat list,
-it can be a real tree, and the popup will reflect the tree structure.
-</para>
-
-<para>
-In addition to the model-view API, #GtkComboBox offers a simple API which 
-is suitable for text-only combo boxes, and hides the complexity of managing
-the data in a model. It consists of the functions gtk_combo_box_new_text(), 
-gtk_combo_box_append_text(), gtk_combo_box_insert_text(), 
-gtk_combo_box_prepend_text(), gtk_combo_box_remove_text() and 
-gtk_combo_box_get_active_text().
-</para>
-
-<!-- ##### SECTION See_Also ##### -->
-<para>
-#GtkComboBoxEntry, #GtkTreeModel, #GtkCellRenderer
-</para>
-
-<!-- ##### SECTION Stability_Level ##### -->
-
-
-<!-- ##### SECTION Image ##### -->
-
-
-<!-- ##### STRUCT GtkComboBox ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### SIGNAL GtkComboBox::changed ##### -->
-<para>
-
-</para>
-
-@combobox: the object which received the signal.
-
-<!-- ##### SIGNAL GtkComboBox::move-active ##### -->
-<para>
-
-</para>
-
-@combobox: the object which received the signal.
-@arg1: 
-
-<!-- ##### SIGNAL GtkComboBox::popdown ##### -->
-<para>
-
-</para>
-
-@combobox: the object which received the signal.
-@Returns: 
-
-<!-- ##### SIGNAL GtkComboBox::popup ##### -->
-<para>
-
-</para>
-
-@combobox: the object which received the signal.
-
-<!-- ##### ARG GtkComboBox:active ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkComboBox:add-tearoffs ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkComboBox:button-sensitivity ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkComboBox:column-span-column ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkComboBox:focus-on-click ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkComboBox:has-frame ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkComboBox:model ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkComboBox:popup-shown ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkComboBox:row-span-column ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkComboBox:tearoff-title ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkComboBox:wrap-width ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkComboBox:appears-as-list ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkComboBox:arrow-size ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkComboBox:shadow-type ##### -->
-<para>
-
-</para>
-
-<!-- ##### FUNCTION gtk_combo_box_new ##### -->
-<para>
-
-</para>
-
-@void: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_combo_box_new_with_model ##### -->
-<para>
-
-</para>
-
-@model: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_combo_box_get_wrap_width ##### -->
-<para>
-
-</para>
-
-@combo_box: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_combo_box_set_wrap_width ##### -->
-<para>
-
-</para>
-
-@combo_box: 
-@width: 
-
-
-<!-- ##### FUNCTION gtk_combo_box_get_row_span_column ##### -->
-<para>
-
-</para>
-
-@combo_box: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_combo_box_set_row_span_column ##### -->
-<para>
-
-</para>
-
-@combo_box: 
-@row_span: 
-
-
-<!-- ##### FUNCTION gtk_combo_box_get_column_span_column ##### -->
-<para>
-
-</para>
-
-@combo_box: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_combo_box_set_column_span_column ##### -->
-<para>
-
-</para>
-
-@combo_box: 
-@column_span: 
-
-
-<!-- ##### FUNCTION gtk_combo_box_get_active ##### -->
-<para>
-
-</para>
-
-@combo_box: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_combo_box_set_active ##### -->
-<para>
-
-</para>
-
-@combo_box: 
-@index_: 
-
-
-<!-- ##### FUNCTION gtk_combo_box_get_active_iter ##### -->
-<para>
-
-</para>
-
-@combo_box: 
-@iter: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_combo_box_set_active_iter ##### -->
-<para>
-
-</para>
-
-@combo_box: 
-@iter: 
-
-
-<!-- ##### FUNCTION gtk_combo_box_get_model ##### -->
-<para>
-
-</para>
-
-@combo_box: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_combo_box_set_model ##### -->
-<para>
-
-</para>
-
-@combo_box: 
-@model: 
-
-
-<!-- ##### FUNCTION gtk_combo_box_new_text ##### -->
-<para>
-
-</para>
-
-@void: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_combo_box_append_text ##### -->
-<para>
-
-</para>
-
-@combo_box: 
-@text: 
-
-
-<!-- ##### FUNCTION gtk_combo_box_insert_text ##### -->
-<para>
-
-</para>
-
-@combo_box: 
-@position: 
-@text: 
-
-
-<!-- ##### FUNCTION gtk_combo_box_prepend_text ##### -->
-<para>
-
-</para>
-
-@combo_box: 
-@text: 
-
-
-<!-- ##### FUNCTION gtk_combo_box_remove_text ##### -->
-<para>
-
-</para>
-
-@combo_box: 
-@position: 
-
-
-<!-- ##### FUNCTION gtk_combo_box_get_active_text ##### -->
-<para>
-
-</para>
-
-@combo_box: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_combo_box_popup_for_device ##### -->
-<para>
-
-</para>
-
-@combo_box: 
-@device: 
-
-
-<!-- ##### FUNCTION gtk_combo_box_popup ##### -->
-<para>
-
-</para>
-
-@combo_box: 
-
-
-<!-- ##### FUNCTION gtk_combo_box_popdown ##### -->
-<para>
-
-</para>
-
-@combo_box: 
-
-
-<!-- ##### FUNCTION gtk_combo_box_get_popup_accessible ##### -->
-<para>
-
-</para>
-
-@combo_box: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_combo_box_get_row_separator_func ##### -->
-<para>
-
-</para>
-
-@combo_box: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_combo_box_set_row_separator_func ##### -->
-<para>
-
-</para>
-
-@combo_box: 
-@func: 
-@data: 
-@destroy: 
-
-
-<!-- ##### FUNCTION gtk_combo_box_set_add_tearoffs ##### -->
-<para>
-
-</para>
-
-@combo_box: 
-@add_tearoffs: 
-
-
-<!-- ##### FUNCTION gtk_combo_box_get_add_tearoffs ##### -->
-<para>
-
-</para>
-
-@combo_box: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_combo_box_set_title ##### -->
-<para>
-
-</para>
-
-@combo_box: 
-@title: 
-
-
-<!-- ##### FUNCTION gtk_combo_box_get_title ##### -->
-<para>
-
-</para>
-
-@combo_box: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_combo_box_set_focus_on_click ##### -->
-<para>
-
-</para>
-
-@combo: 
-@focus_on_click: 
-
-
-<!-- ##### FUNCTION gtk_combo_box_get_focus_on_click ##### -->
-<para>
-
-</para>
-
-@combo: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_combo_box_set_button_sensitivity ##### -->
-<para>
-
-</para>
-
-@combo_box: 
-@sensitivity: 
-
-
-<!-- ##### FUNCTION gtk_combo_box_get_button_sensitivity ##### -->
-<para>
-
-</para>
-
-@combo_box: 
-@Returns: 
-
-
diff --git a/gtk/gtkcombobox.c b/gtk/gtkcombobox.c
index 6076c6ccfd..aeb5e91a36 100644
--- a/gtk/gtkcombobox.c
+++ b/gtk/gtkcombobox.c
@@ -52,6 +52,37 @@
 
 #include "gtktreeprivate.h"
 
+
+/**
+ * SECTION:gtkcombobox
+ * @Short_description: A widget used to choose from a list of items
+ * @Title: GtkComboBox
+ * @See_also: #GtkComboBoxEntry, #GtkTreeModel, #GtkCellRenderer
+ *
+ * A GtkComboBox is a widget that allows the user to choose from a list of
+ * valid choices. The GtkComboBox displays the selected choice. When
+ * activated, the GtkComboBox displays a popup which allows the user to
+ * make a new choice. The style in which the selected value is displayed,
+ * and the style of the popup is determined by the current theme. It may
+ * be similar to a Windows-style combo box.
+ *
+ * The GtkComboBox uses the model-view pattern; the list of valid choices
+ * is specified in the form of a tree model, and the display of the choices
+ * can be adapted to the data in the model by using cell renderers, as you
+ * would in a tree view. This is possible since GtkComboBox implements the
+ * #GtkCellLayout interface. The tree model holding the valid choices is
+ * not restricted to a flat list, it can be a real tree, and the popup will
+ * reflect the tree structure.
+ *
+ * In addition to the model-view API, GtkComboBox offers a simple API which
+ * is suitable for text-only combo boxes, and hides the complexity of
+ * managing the data in a model. It consists of the functions
+ * gtk_combo_box_new_text(), gtk_combo_box_append_text(),
+ * gtk_combo_box_insert_text(), gtk_combo_box_prepend_text(),
+ * gtk_combo_box_remove_text() and gtk_combo_box_get_active_text().
+ */
+
+
 /* WELCOME, to THE house of evil code */
 
 typedef struct _ComboCellInfo ComboCellInfo;
diff --git a/gtk/gtknotebook.c b/gtk/gtknotebook.c
index 95e1325f66..beb19d8179 100644
--- a/gtk/gtknotebook.c
+++ b/gtk/gtknotebook.c
@@ -72,12 +72,11 @@
  * 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>
+ * </para>
  * <example>
  * <title>A UI definition fragment with GtkNotebook</title>
  * <programlisting><![CDATA[