[gtk+/dialogs] Add more documentation

[Matthias Clasen <matthiasc src gnome org>]

commit f3177d17565d808ed534e90c33c11678313478b3
Author: Matthias Clasen <mclasen redhat com>
Date:   Wed Jan 15 16:00:07 2014 -0500

    Add more documentation

 gtk/gtkdialog.c   |   15 ++++++++++-----
 gtk/gtksettings.c |   14 +++++++++++++-
 2 files changed, 23 insertions(+), 6 deletions(-)
---
diff --git a/gtk/gtkdialog.c b/gtk/gtkdialog.c
index 42981ad..ebdb51d 100644
--- a/gtk/gtkdialog.c
+++ b/gtk/gtkdialog.c
@@ -1721,10 +1721,13 @@ gtk_dialog_buildable_custom_finished (GtkBuildable *buildable,
  *
  * Returns the action area of @dialog.
  *
- * Returns: (transfer none): the action area.
+ * Returns: (transfer none): the action area
  *
  * Since: 2.14
- **/
+ *
+ * Deprecated:3.12: Direct access to the action area
+ *   is discouraged; use gtk_dialog_add_button(), etc.
+ */
 GtkWidget *
 gtk_dialog_get_action_area (GtkDialog *dialog)
 {
@@ -1737,12 +1740,14 @@ gtk_dialog_get_action_area (GtkDialog *dialog)
  * gtk_dialog_get_header_bar:
  * @dialog: a #GtkDialog
  *
- * Returns the header bar of @dialog.
+ * Returns the header bar of @dialog. Note that the
+ * headerbar is only used by the dialog if the
+ * #GtkDialog::use-header-bar property is %TRUE.
  *
- * Returns: (transfer none): the header bar.
+ * Returns: (transfer none): the header bar
  *
  * Since: 3.12
- **/
+ */
 GtkWidget *
 gtk_dialog_get_header_bar (GtkDialog *dialog)
 {
diff --git a/gtk/gtksettings.c b/gtk/gtksettings.c
index 3b0ba1f..4bf0e9b 100644
--- a/gtk/gtksettings.c
+++ b/gtk/gtksettings.c
@@ -1576,10 +1576,22 @@ gtk_settings_class_init (GtkSettingsClass *class)
                                              NULL);
   g_assert (result == PROP_DECORATION_LAYOUT);
 
+  /**
+   * GtkSettings:gtk-dialogs-use-header:
+   *
+   * Whether builtin GTK+ dialogs such as the file chooser, the
+   * color chooser or the font chooser will use a header bar at
+   * the top to show action widgets, or an action area at the bottom.
+   *
+   * This setting does not affect custom dialogs using GtkDialog
+   * directly, or message dialogs.
+   *
+   * Since: 3.12
+   */
   result = settings_install_property_parser (class,
                                              g_param_spec_boolean ("gtk-dialogs-use-header",
                                                                    P_("Dialogs use header bar"),
-                                                                   P_("Whether GTK+ dialogs should use a 
header bar instead of an action area."),
+                                                                   P_("Whether builtin GTK+ dialogs should 
use a header bar instead of an action area."),
                                                                    FALSE,
                                                                    GTK_PARAM_READWRITE),
                                              NULL);