[docs] Move documentation to inline comments: GtkAssistant

Signed-off-by: Javier Jardón <jjardon@gnome.org>

3 files changed, 53 insertions, 345 deletions

diff --git a/docs/reference/gtk/tmpl/gtkassistant.sgml b/docs/reference/gtk/tmpl/gtkassistant.sgml
deleted file mode 100644
index ab00eee54..000000000
--- a/docs/reference/gtk/tmpl/gtkassistant.sgml
+++ /dev/null
@@ -1,344 +0,0 @@
-<!-- ##### SECTION Title ##### -->
-GtkAssistant
-
-<!-- ##### SECTION Short_Description ##### -->
-A widget used to guide users through multi-step operations
-
-<!-- ##### SECTION Long_Description ##### -->
-<para>
-A #GtkAssistant is a widget used to represent a generally complex
-operation splitted in several steps, guiding the user through its pages
-and controlling the page flow to collect the necessary data.
-</para>
-<refsect2 id="GtkAssistant-BUILDER-UI"><title>GtkAssistant as GtkBuildable</title>
-<para>
-The GtkAssistant implementation of the GtkBuildable interface exposes the
-@action_area as internal children with the name "action_area".
-</para>
-<para>
-To add pages to an assistant in GtkBuilder, simply add it as a &lt;child&gt;
-to the GtkAssistant object, and set its child properties as necessary.
-</para>
-</refsect2>
-
-<!-- ##### SECTION See_Also ##### -->
-<para>
-
-</para>
-
-<!-- ##### SECTION Stability_Level ##### -->
-
-
-<!-- ##### STRUCT GtkAssistant ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### SIGNAL GtkAssistant::apply ##### -->
-<para>
-
-</para>
-
-@assistant: the object which received the signal.
-
-<!-- ##### SIGNAL GtkAssistant::cancel ##### -->
-<para>
-
-</para>
-
-@assistant: the object which received the signal.
-
-<!-- ##### SIGNAL GtkAssistant::close ##### -->
-<para>
-
-</para>
-
-@assistant: the object which received the signal.
-
-<!-- ##### SIGNAL GtkAssistant::prepare ##### -->
-<para>
-
-</para>
-
-@assistant: the object which received the signal.
-@widget: 
-
-<!-- ##### ARG GtkAssistant:complete ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkAssistant:header-image ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkAssistant:page-type ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkAssistant:sidebar-image ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkAssistant:title ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkAssistant:content-padding ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkAssistant:header-padding ##### -->
-<para>
-
-</para>
-
-<!-- ##### FUNCTION gtk_assistant_new ##### -->
-<para>
-
-</para>
-
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_assistant_get_current_page ##### -->
-<para>
-
-</para>
-
-@assistant: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_assistant_set_current_page ##### -->
-<para>
-
-</para>
-
-@assistant: 
-@page_num: 
-
-
-<!-- ##### FUNCTION gtk_assistant_get_n_pages ##### -->
-<para>
-
-</para>
-
-@assistant: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_assistant_get_nth_page ##### -->
-<para>
-
-</para>
-
-@assistant: 
-@page_num: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_assistant_prepend_page ##### -->
-<para>
-
-</para>
-
-@assistant: 
-@page: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_assistant_append_page ##### -->
-<para>
-
-</para>
-
-@assistant: 
-@page: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_assistant_insert_page ##### -->
-<para>
-
-</para>
-
-@assistant: 
-@page: 
-@position: 
-@Returns: 
-
-
-<!-- ##### USER_FUNCTION GtkAssistantPageFunc ##### -->
-<para>
-A function used by gtk_assistant_set_forward_page_func() to know which
-is the next page given a current one. It's called both for computing the
-next page when the user presses the "forward" button and for handling
-the behavior of the "last" button.
-</para>
-
-@current_page: The page number used to calculate the next page.
-@data: user data.
-@Returns: The next page number.
-
-
-<!-- ##### FUNCTION gtk_assistant_set_forward_page_func ##### -->
-<para>
-
-</para>
-
-@assistant: 
-@page_func: 
-@data: 
-@destroy: 
-
-
-<!-- ##### ENUM GtkAssistantPageType ##### -->
-<para>
-An enum for determining the page role inside the #GtkAssistant. It's used to
-handle buttons sensitivity and visibility.
-</para>
-
-<para>
-Note that an assistant needs to end its page flow with a page of type GTK_ASSISTANT_PAGE_CONFIRM
-or GTK_ASSISTANT_PAGE_SUMMARY to be correct.
-</para>
-
-@GTK_ASSISTANT_PAGE_CONTENT: The page has regular contents.
-@GTK_ASSISTANT_PAGE_INTRO: The page contains an introduction to the assistant task.
-@GTK_ASSISTANT_PAGE_CONFIRM: The page lets the user confirm or deny the changes.
-@GTK_ASSISTANT_PAGE_SUMMARY: The page informs the user of the changes done.
-@GTK_ASSISTANT_PAGE_PROGRESS: Used for tasks that take a long time to complete, blocks the assistant until the page is marked as complete.
-
-<!-- ##### FUNCTION gtk_assistant_set_page_type ##### -->
-<para>
-
-</para>
-
-@assistant: 
-@page: 
-@type: 
-
-
-<!-- ##### FUNCTION gtk_assistant_get_page_type ##### -->
-<para>
-
-</para>
-
-@assistant: 
-@page: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_assistant_set_page_title ##### -->
-<para>
-
-</para>
-
-@assistant: 
-@page: 
-@title: 
-
-
-<!-- ##### FUNCTION gtk_assistant_get_page_title ##### -->
-<para>
-
-</para>
-
-@assistant: 
-@page: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_assistant_set_page_header_image ##### -->
-<para>
-
-</para>
-
-@assistant: 
-@page: 
-@pixbuf: 
-
-
-<!-- ##### FUNCTION gtk_assistant_get_page_header_image ##### -->
-<para>
-
-</para>
-
-@assistant: 
-@page: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_assistant_set_page_side_image ##### -->
-<para>
-
-</para>
-
-@assistant: 
-@page: 
-@pixbuf: 
-
-
-<!-- ##### FUNCTION gtk_assistant_get_page_side_image ##### -->
-<para>
-
-</para>
-
-@assistant: 
-@page: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_assistant_set_page_complete ##### -->
-<para>
-
-</para>
-
-@assistant: 
-@page: 
-@complete: 
-
-
-<!-- ##### FUNCTION gtk_assistant_get_page_complete ##### -->
-<para>
-
-</para>
-
-@assistant: 
-@page: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_assistant_add_action_widget ##### -->
-<para>
-
-</para>
-
-@assistant: 
-@child: 
-
-
-<!-- ##### FUNCTION gtk_assistant_remove_action_widget ##### -->
-<para>
-
-</para>
-
-@assistant: 
-@child: 
-
-
-<!-- ##### FUNCTION gtk_assistant_update_buttons_state ##### -->
-<para>
-
-</para>
-
-@assistant: 
-
-
diff --git a/gtk/gtkassistant.c b/gtk/gtkassistant.c
index 1e2c3ce43..41ecd1311 100644
--- a/gtk/gtkassistant.c
+++ b/gtk/gtkassistant.c
@@ -23,6 +23,28 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:gtkassistant
+ * @Short_description: A widget used to guide users through multi-step operations
+ * @Title: GtkAssistant
+ *
+ * A #GtkAssistant is a widget used to represent a generally complex
+ * operation splitted in several steps, guiding the user through its pages
+ * and controlling the page flow to collect the necessary data.
+ *
+ * <refsect2 id="GtkAssistant-BUILDER-UI">
+ * <title>GtkAssistant as GtkBuildable</title>
+ * <para>
+ * The GtkAssistant implementation of the GtkBuildable interface exposes the
+ * @action_area as internal children with the name "action_area".
+ *
+ * To add pages to an assistant in GtkBuilder, simply add it as a
+ * &lt;child&gt; to the GtkAssistant object, and set its child properties
+ * as necessary.
+ * </para>
+ * </refsect2>
+ */
+
 #include "config.h"
 
 #include <atk/atk.h>
@@ -237,7 +259,7 @@ gtk_assistant_class_init (GtkAssistantClass *class)
 
   /**
    * GtkAssistant::apply:
-   * @assistant: the @GtkAssistant
+   * @assistant: the #GtkAssistant
    *
    * The ::apply signal is emitted when the apply button is clicked. The default
    * behavior of the #GtkAssistant is to switch to the page after the current
diff --git a/gtk/gtkassistant.h b/gtk/gtkassistant.h
index b39afef43..5f26325bf 100644
--- a/gtk/gtkassistant.h
+++ b/gtk/gtkassistant.h
@@ -41,6 +41,24 @@ G_BEGIN_DECLS
 #define GTK_IS_ASSISTANT_CLASS(c)  (G_TYPE_CHECK_CLASS_TYPE    ((c), GTK_TYPE_ASSISTANT))
 #define GTK_ASSISTANT_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS  ((o), GTK_TYPE_ASSISTANT, GtkAssistantClass))
 
+/**
+ * GtkAssistantPageType:
+ * @GTK_ASSISTANT_PAGE_CONTENT: The page has regular contents.
+ * @GTK_ASSISTANT_PAGE_INTRO: The page contains an introduction to the
+ *  assistant task.
+ * @GTK_ASSISTANT_PAGE_CONFIRM: The page lets the user confirm or deny the
+ *  changes.
+ * @GTK_ASSISTANT_PAGE_SUMMARY: The page informs the user of the changes
+ *  done.
+ * @GTK_ASSISTANT_PAGE_PROGRESS: Used for tasks that take a long time to
+ *  complete, blocks the assistant until the page is marked as complete.
+ *
+ * An enum for determining the page role inside the #GtkAssistant. It's
+ * used to handle buttons sensitivity and visibility.
+ *
+ * Note that an assistant needs to end its page flow with a page of type
+ * %GTK_ASSISTANT_PAGE_CONFIRM or %GTK_ASSISTANT_PAGE_SUMMARY to be correct.
+ */
 typedef enum
 {
   GTK_ASSISTANT_PAGE_CONTENT,
@@ -86,6 +104,18 @@ struct _GtkAssistantClass
   void (*_gtk_reserved5) (void);
 };
 
+/**
+ * GtkAssistantPageFunc:
+ * @current_page: The page number used to calculate the next page.
+ * @data: user data.
+ *
+ * A function used by gtk_assistant_set_forward_page_func() to know which
+ * is the next page given a current one. It's called both for computing the
+ * next page when the user presses the "forward" button and for handling
+ * the behavior of the "last" button.
+ *
+ * Returns: The next page number.
+ */
 typedef gint (*GtkAssistantPageFunc) (gint current_page, gpointer data);
 
 GType                 gtk_assistant_get_type              (void) G_GNUC_CONST;