[gtk/wip/baedert/for-master] Fix and improve various code samples

[Timm Bäder <baedert src gnome org>]

commit 41b458fba7800ad56c906f80c66a3f1b3f716ba8
Author: Timm Bäder <mail baedert org>
Date:   Sat Aug 1 20:00:13 2020 +0200

    Fix and improve various code samples

 gtk/gtkdialog.c            |  2 +-
 gtk/gtkdrawingarea.c       | 15 +++++++++------
 gtk/gtkeditable.c          |  2 +-
 gtk/gtkfilechooser.c       | 31 ++++++++++++++++++++-----------
 gtk/gtkfilechooserbutton.c |  2 +-
 gtk/gtkfilechoosernative.c | 12 +++++-------
 6 files changed, 37 insertions(+), 27 deletions(-)
---
diff --git a/gtk/gtkdialog.c b/gtk/gtkdialog.c
index 9c1f05436e..82b3504199 100644
--- a/gtk/gtkdialog.c
+++ b/gtk/gtkdialog.c
@@ -730,7 +730,7 @@ gtk_dialog_new_empty (const char      *title,
  *
  * Here’s a simple example:
  * |[<!-- language="C" -->
- *  GtkWidget *main_app_window; // Window the dialog should show up on
+ *  GtkWindow *main_app_window; // Window the dialog should show up on
  *  GtkWidget *dialog;
  *  GtkDialogFlags flags = GTK_DIALOG_MODAL | GTK_DIALOG_DESTROY_WITH_PARENT;
  *  dialog = gtk_dialog_new_with_buttons ("My dialog",
diff --git a/gtk/gtkdrawingarea.c b/gtk/gtkdrawingarea.c
index 7306869910..65c7198d3c 100644
--- a/gtk/gtkdrawingarea.c
+++ b/gtk/gtkdrawingarea.c
@@ -85,10 +85,12 @@ static guint signals[LAST_SIGNAL] = { 0, };
  * ## Simple GtkDrawingArea usage
  *
  * |[<!-- language="C" -->
- * void
- * draw_function (GtkDrawingArea *area, cairo_t *cr,
- *                int width, int height,
- *                gpointer data)
+ * static void
+ * draw_function (GtkDrawingArea *area,
+ *                cairo_t        *cr,
+ *                int             width,
+ *                int             height,
+ *                gpointer        data)
  * {
  *   GdkRGBA color;
  *   GtkStyleContext *context;
@@ -107,7 +109,8 @@ static guint signals[LAST_SIGNAL] = { 0, };
  *   cairo_fill (cr);
  * }
  *
- * void main (int argc, char **argv)
+ * int
+ * main (int argc, char **argv)
  * {
  *   gtk_init ();
  *
@@ -117,7 +120,7 @@ static guint signals[LAST_SIGNAL] = { 0, };
  *   gtk_drawing_area_set_draw_func (GTK_DRAWING_AREA (area),
  *                                   draw_function,
  *                                   NULL, NULL);
- *
+ *   return 0;
  * }
  * ]|
  *
diff --git a/gtk/gtkeditable.c b/gtk/gtkeditable.c
index ea6d48b0c2..af0325f80f 100644
--- a/gtk/gtkeditable.c
+++ b/gtk/gtkeditable.c
@@ -40,7 +40,7 @@
  * ## Forcing entry to uppercase.
  *
  * |[<!-- language="C" -->
- * #include <ctype.h>;
+ * #include <ctype.h>
  *
  * void
  * insert_text_handler (GtkEditable *editable,
diff --git a/gtk/gtkfilechooser.c b/gtk/gtkfilechooser.c
index f05b053f01..da188eb4f7 100644
--- a/gtk/gtkfilechooser.c
+++ b/gtk/gtkfilechooser.c
@@ -482,17 +482,26 @@ gtk_file_chooser_get_files (GtkFileChooser *chooser)
  * file and is saving it for the first time, do not call this function.
  * Instead, use something similar to this:
  * |[<!-- language="C" -->
- * if (document_is_new)
- *   {
- *     // the user just created a new document
- *     gtk_file_chooser_set_current_folder (chooser, default_file_for_saving);
- *     gtk_file_chooser_set_current_name (chooser, "Untitled document");
- *   }
- * else
- *   {
- *     // the user edited an existing document
- *     gtk_file_chooser_set_file (chooser, existing_file);
- *   }
+ * static void
+ * prepare_file_chooser (GtkFileChooser *chooser,
+ *                       GFile          *existing_file)
+ * {
+ *   gboolean document_is_new = (existing_file == NULL);
+ *
+ *   if (document_is_new)
+ *     {
+ *       GFile *default_file_for_saving = g_file_new_for_path ("./out.txt");
+ *       // the user just created a new document
+ *       gtk_file_chooser_set_current_folder (chooser, default_file_for_saving, NULL);
+ *       gtk_file_chooser_set_current_name (chooser, "Untitled document");
+ *       g_object_unref (default_file_for_saving);
+ *     }
+ *   else
+ *     {
+ *       // the user edited an existing document
+ *       gtk_file_chooser_set_file (chooser, existing_file, NULL);
+ *     }
+ * }
  * ]|
  *
  * Returns: Not useful.
diff --git a/gtk/gtkfilechooserbutton.c b/gtk/gtkfilechooserbutton.c
index a530cb5909..f57c8f2a92 100644
--- a/gtk/gtkfilechooserbutton.c
+++ b/gtk/gtkfilechooserbutton.c
@@ -84,7 +84,7 @@
  *
  *   button = gtk_file_chooser_button_new (_("Select a file"),
  *                                         GTK_FILE_CHOOSER_ACTION_OPEN);
- *   gtk_file_chooser_set_current_folder (GTK_FILE_CHOOSER (button), cwd);
+ *   gtk_file_chooser_set_current_folder (GTK_FILE_CHOOSER (button), cwd, NULL);
  *   g_object_unref (cwd);
  * }
  * ]|
diff --git a/gtk/gtkfilechoosernative.c b/gtk/gtkfilechoosernative.c
index 7e050da9d7..08512ee079 100644
--- a/gtk/gtkfilechoosernative.c
+++ b/gtk/gtkfilechoosernative.c
@@ -68,7 +68,7 @@
  *
  * |[<!-- language="C" -->
  * static void
- * on_response (GtkNativeDialog *dialog,
+ * on_response (GtkNativeDialog *native,
  *              int              response)
  * {
  *   if (response == GTK_RESPONSE_ACCEPT)
@@ -102,12 +102,12 @@
  *
  * |[<!-- language="C" -->
  * static void
- * on_response (GtkNativeDialog *dialog,
+ * on_response (GtkNativeDialog *native,
  *              int              response)
  * {
  *   if (response == GTK_RESPONSE_ACCEPT)
  *     {
- *       GtkFileChooser *chooser = GTK_FILE_CHOOSER (dialog);
+ *       GtkFileChooser *chooser = GTK_FILE_CHOOSER (native);
  *       GFile *file = gtk_file_chooser_get_file (chooser);
  *
  *       save_to_file (file);
@@ -131,11 +131,9 @@
  *   chooser = GTK_FILE_CHOOSER (native);
  *
  *   if (user_edited_a_new_document)
- *     gtk_file_chooser_set_current_name (chooser,
- *                                      _("Untitled document"));
+ *     gtk_file_chooser_set_current_name (chooser, _("Untitled document"));
  *   else
- *     gtk_file_chooser_set_filename (chooser,
- *                                    existing_filename);
+ *     gtk_file_chooser_set_file (chooser, existing_file, NULL);
  *
  *   g_signal_connect (native, "response", G_CALLBACK (on_response), NULL);
  *   gtk_native_dialog_show (GTK_NATIVE_DIALOG (native));