[gtk+] Move documentation to inline comments: GtkMessageDialog

[Javier Jardón <jjardon src gnome org>]

commit 95fd5011c2e7251f424e583237023a937e47303c
Author: Javier Jardón <jjardon gnome org>
Date:   Fri Dec 18 05:00:56 2009 +0100

    Move documentation to inline comments: GtkMessageDialog
    
    Also, add a note about GTK_BUTTONS_OK, GTK_BUTTONS_YES_NO
    and GTK_BUTTONS_OK_CANCEL are discouraged by the GNOME HIG.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=597865

 docs/reference/gtk/tmpl/.gitignore            |    1 +
 docs/reference/gtk/tmpl/gtkmessagedialog.sgml |  213 -------------------------
 gtk/gtkenums.h                                |   10 ++
 gtk/gtkmessagedialog.c                        |   47 ++++++
 gtk/gtkmessagedialog.h                        |   37 ++++-
 5 files changed, 86 insertions(+), 222 deletions(-)
---
diff --git a/docs/reference/gtk/tmpl/.gitignore b/docs/reference/gtk/tmpl/.gitignore
new file mode 100644
index 0000000..1f9678b
--- /dev/null
+++ b/docs/reference/gtk/tmpl/.gitignore
@@ -0,0 +1 @@
+gtkmessagedialog.sgml
diff --git a/gtk/gtkenums.h b/gtk/gtkenums.h
index b8b5e33..7c577c7 100644
--- a/gtk/gtkenums.h
+++ b/gtk/gtkenums.h
@@ -208,6 +208,16 @@ typedef enum
   GTK_MENU_DIR_PREV
 } GtkMenuDirectionType;
 
+/**
+ * GtkMessageType:
+ * @GTK_MESSAGE_INFO: Informational message
+ * @GTK_MESSAGE_WARNING: Nonfatal warning message
+ * @GTK_MESSAGE_QUESTION: Question requiring a choice
+ * @GTK_MESSAGE_ERROR: Fatal error message
+ * @GTK_MESSAGE_OTHER: None of the above, doesn't get an icon
+ *
+ * The type of message being displayed in the dialog.
+ */
 typedef enum
 {
   GTK_MESSAGE_INFO,
diff --git a/gtk/gtkmessagedialog.c b/gtk/gtkmessagedialog.c
index 71a4098..18adeea 100644
--- a/gtk/gtkmessagedialog.c
+++ b/gtk/gtkmessagedialog.c
@@ -40,6 +40,53 @@
 #include "gtkprivate.h"
 #include "gtkalias.h"
 
+/**
+ * SECTION:gtkmessagedialog
+ * @Short_description: A convenient message window
+ * @Title: GtkMessageDialog
+ * @See_also:#GtkDialog
+ *
+ * #GtkMessageDialog presents a dialog with an image representing the type of
+ * message (Error, Question, etc.) alongside some message text. It's simply a
+ * convenience widget; you could construct the equivalent of #GtkMessageDialog
+ * from #GtkDialog without too much effort, but #GtkMessageDialog saves typing.
+ *
+ * The easiest way to do a modal message dialog is to use gtk_dialog_run(), though
+ * you can also pass in the %GTK_DIALOG_MODAL flag, gtk_dialog_run() automatically
+ * makes the dialog modal and waits for the user to respond to it. gtk_dialog_run()
+ * returns when any dialog button is clicked.
+ * <example>
+ * <title>A modal dialog.</title>
+ * <programlisting>
+ *  dialog = gtk_message_dialog_new (main_application_window,
+ *                                   GTK_DIALOG_DESTROY_WITH_PARENT,
+ *                                   GTK_MESSAGE_ERROR,
+ *                                   GTK_BUTTONS_CLOSE,
+ *                                   "Error loading file '&percnt;s': &percnt;s",
+ *                                   filename, g_strerror (errno));
+ *  gtk_dialog_run (GTK_DIALOG (dialog));
+ *  gtk_widget_destroy (dialog);
+ * </programlisting>
+ * </example>
+ * You might do a non-modal #GtkMessageDialog as follows:
+ * <example>
+ * <title>A non-modal dialog.</title>
+ * <programlisting>
+ *  dialog = gtk_message_dialog_new (main_application_window,
+ *                                   GTK_DIALOG_DESTROY_WITH_PARENT,
+ *                                   GTK_MESSAGE_ERROR,
+ *                                   GTK_BUTTONS_CLOSE,
+ *                                   "Error loading file '&percnt;s': &percnt;s",
+ *                                   filename, g_strerror (errno));
+ *
+ *  /&ast; Destroy the dialog when the user responds to it (e.g. clicks a button) &ast;/
+ *  g_signal_connect_swapped (dialog, "response",
+ *                            G_CALLBACK (gtk_widget_destroy),
+ *                            dialog);
+ * </programlisting>
+ * </example>
+ */
+
 #define GTK_MESSAGE_DIALOG_GET_PRIVATE(obj) (G_TYPE_INSTANCE_GET_PRIVATE ((obj), GTK_TYPE_MESSAGE_DIALOG, GtkMessageDialogPrivate))
 
 typedef struct _GtkMessageDialogPrivate GtkMessageDialogPrivate;
diff --git a/gtk/gtkmessagedialog.h b/gtk/gtkmessagedialog.h
index 1bb1ec5..c46c7b3 100644
--- a/gtk/gtkmessagedialog.h
+++ b/gtk/gtkmessagedialog.h
@@ -36,15 +36,6 @@
 
 G_BEGIN_DECLS
 
-typedef enum
-{
-  GTK_BUTTONS_NONE,
-  GTK_BUTTONS_OK,
-  GTK_BUTTONS_CLOSE,
-  GTK_BUTTONS_CANCEL,
-  GTK_BUTTONS_YES_NO,
-  GTK_BUTTONS_OK_CANCEL
-} GtkButtonsType;
 
 #define GTK_TYPE_MESSAGE_DIALOG                  (gtk_message_dialog_get_type ())
 #define GTK_MESSAGE_DIALOG(obj)                  (G_TYPE_CHECK_INSTANCE_CAST ((obj), GTK_TYPE_MESSAGE_DIALOG, GtkMessageDialog))
@@ -77,6 +68,34 @@ struct _GtkMessageDialogClass
   void (*_gtk_reserved4) (void);
 };
 
+/**
+ * GtkButtonsType:
+ * @GTK_BUTTONS_NONE: no buttons at all
+ * @GTK_BUTTONS_OK: an OK button
+ * @GTK_BUTTONS_CLOSE: a Close button
+ * @GTK_BUTTONS_CANCEL: a Cancel button
+ * @GTK_BUTTONS_YES_NO: Yes and No buttons
+ * @GTK_BUTTONS_OK_CANCEL: OK and Cancel buttons
+ *
+ * Prebuilt sets of buttons for the dialog. If
+ * none of these choices are appropriate, simply use %GTK_BUTTONS_NONE
+ * then call gtk_dialog_add_buttons().
+ * <note>
+ *  Please note that %GTK_BUTTONS_OK, %GTK_BUTTONS_YES_NO
+ *  and %GTK_BUTTONS_OK_CANCEL are discouraged by the
+ *  <ulink url="http://library.gnome.org/devel/hig-book/stable/";>GNOME HIG</ulink>.
+ * </note>
+ */
+typedef enum
+{
+  GTK_BUTTONS_NONE,
+  GTK_BUTTONS_OK,
+  GTK_BUTTONS_CLOSE,
+  GTK_BUTTONS_CANCEL,
+  GTK_BUTTONS_YES_NO,
+  GTK_BUTTONS_OK_CANCEL
+} GtkButtonsType;
+
 GType      gtk_message_dialog_get_type (void) G_GNUC_CONST;
 
 GtkWidget* gtk_message_dialog_new      (GtkWindow      *parent,