docs: fully break lines in examples

Try to do a better job of keeping example content
from being too wide. It is often rendered as <pre>
text so the only time we can wrap it is in the source.

It is best to full break lines at all punctuation and
to try to keep the width under 70 chars or so.

25 files changed, 353 insertions, 223 deletions

diff --git a/gtk/gtkaboutdialog.c b/gtk/gtkaboutdialog.c
index e909503877..869ea4dd0e 100644
--- a/gtk/gtkaboutdialog.c
+++ b/gtk/gtkaboutdialog.c
@@ -1654,7 +1654,8 @@ gtk_about_dialog_get_translator_credits (GtkAboutDialog *about)
  * Using gettext(), a simple way to achieve that is to mark the
  * string for translation:
  * |[<!-- language="C" -->
- *  gtk_about_dialog_set_translator_credits (about, _("translator-credits"));
+ *  gtk_about_dialog_set_translator_credits (about,
+ *                                           _("translator-credits"));
  * ]|
  * It is a good idea to use the customary msgid “translator-credits” for this
  * purpose, since translators will already know the purpose of that msgid, and
diff --git a/gtk/gtkaccelgroup.h b/gtk/gtkaccelgroup.h
index 698e7429ca..25b85cd1dd 100644
--- a/gtk/gtkaccelgroup.h
+++ b/gtk/gtkaccelgroup.h
@@ -56,8 +56,8 @@ G_BEGIN_DECLS
  */
 typedef enum
 {
-  GTK_ACCEL_VISIBLE        = 1 << 0,	/* display in GtkAccelLabel? */
-  GTK_ACCEL_LOCKED         = 1 << 1,	/* is it removable? */
+  GTK_ACCEL_VISIBLE        = 1 << 0,
+  GTK_ACCEL_LOCKED         = 1 << 1,
   GTK_ACCEL_MASK           = 0x07
 } GtkAccelFlags;
 
diff --git a/gtk/gtkactionable.c b/gtk/gtkactionable.c
index 12f8758284..e6b7cf9c22 100644
--- a/gtk/gtkactionable.c
+++ b/gtk/gtkactionable.c
@@ -56,7 +56,7 @@
  * @get_action_name: virtual pointer for gtk_actionable_get_action_name()
  * @set_action_name: virtual pointer for gtk_actionable_set_action_name()
  * @get_action_target_value: virtual pointer for gtk_actionable_get_action_target_value()
- * @set_action_target_value: virtual pointer for gtk_actionable_set_action_target_value
+ * @set_action_target_value: virtual pointer for gtk_actionable_set_action_target_value()
  *
  * The interface vtable for #GtkActionable.
  **/
diff --git a/gtk/gtkapplicationwindow.c b/gtk/gtkapplicationwindow.c
index 67da6bede6..1ea52f7fab 100644
--- a/gtk/gtkapplicationwindow.c
+++ b/gtk/gtkapplicationwindow.c
@@ -93,8 +93,11 @@
  *     "    </submenu>"
  *     "  </menu>"
  *     "</interface>");
+ *
+ * menubar = G_MENU_MODEL (gtk_builder_get_object (builder,
+ *                                                 "menubar"));
  * gtk_application_set_menubar (G_APPLICATION (app),
- *                              G_MENU_MODEL (gtk_builder_get_object (builder, "menubar")));
+ *                              menubar);
  * g_object_unref (builder);
  *
  * ...
diff --git a/gtk/gtkcontainer.c b/gtk/gtkcontainer.c
index 797eb6fc0d..c65a828504 100644
--- a/gtk/gtkcontainer.c
+++ b/gtk/gtkcontainer.c
@@ -109,21 +109,30 @@
  *
  * |[<!-- language="C" -->
  * static void
- * foo_container_get_preferred_height (GtkWidget *widget, gint *min_height, gint *nat_height)
+ * foo_container_get_preferred_height (GtkWidget *widget,
+ *                                     gint *min_height,
+ *                                     gint *nat_height)
  * {
  *    if (i_am_in_height_for_width_mode)
  *      {
  *        gint min_width;
  *
- *        GTK_WIDGET_GET_CLASS (widget)->get_preferred_width (widget, &min_width, NULL);
- *        GTK_WIDGET_GET_CLASS (widget)->get_preferred_height_for_width (widget, min_width,
- *                                                                       min_height, nat_height);
+ *        GTK_WIDGET_GET_CLASS (widget)->get_preferred_width (widget,
+ *                                                            &min_width,
+ *                                                            NULL);
+ *        GTK_WIDGET_GET_CLASS (widget)->get_preferred_height_for_width
+ *                                                           (widget,
+ *                                                            min_width,
+ *                                                            min_height,
+ *                                                            nat_height);
  *      }
  *    else
  *      {
- *        ... many containers support both request modes, execute the real width-for-height
- *        request here by returning the collective heights of all widgets that are
- *        stacked vertically (or whatever is appropriate for this container) ...
+ *        ... many containers support both request modes, execute the
+ *        real width-for-height request here by returning the
+ *        collective heights of all widgets that are stacked
+ *        vertically (or whatever is appropriate for this container)
+ *        ...
  *      }
  * }
  * ]|
@@ -133,17 +142,22 @@
  *
  * |[<!-- language="C" -->
  * static void
- * foo_container_get_preferred_width_for_height (GtkWidget *widget, gint for_height,
- *                                               gint *min_width, gint *nat_width)
+ * foo_container_get_preferred_width_for_height (GtkWidget *widget,
+ *                                               gint for_height,
+ *                                               gint *min_width,
+ *                                               gint *nat_width)
  * {
  *    if (i_am_in_height_for_width_mode)
  *      {
- *        GTK_WIDGET_GET_CLASS (widget)->get_preferred_width (widget, min_width, nat_width);
+ *        GTK_WIDGET_GET_CLASS (widget)->get_preferred_width (widget,
+ *                                                            min_width,
+ *                                                            nat_width);
  *      }
  *    else
  *      {
- *        ... execute the real width-for-height request here based on the required width
- *        of the children collectively if the container were to be allocated the said height ...
+ *        ... execute the real width-for-height request here based on
+ *        the required width of the children collectively if the
+ *        container were to be allocated the said height ...
  *      }
  * }
  * ]|
diff --git a/gtk/gtkdialog.c b/gtk/gtkdialog.c
index ed8bc082a9..806f8ed9d7 100644
--- a/gtk/gtkdialog.c
+++ b/gtk/gtkdialog.c
@@ -100,32 +100,36 @@
  *
  * An example for simple GtkDialog usage:
  * |[<!-- language="C" -->
- * /&ast; Function to open a dialog box displaying the message provided. &ast;/
+ * /&ast; Function to open a dialog box with a message &ast;/
  * void
- * quick_message (gchar *message)
+ * quick_message (GtkWindow *parent, gchar *message)
  * {
- *    GtkWidget *dialog, *label, *content_area;
- *
- *    /&ast; Create the widgets &ast;/
- *    dialog = gtk_dialog_new_with_buttons ("Message",
- *                                          main_application_window,
- *                                          GTK_DIALOG_DESTROY_WITH_PARENT,
- *                                          _("_OK"),
- *                                          GTK_RESPONSE_NONE,
- *                                          NULL);
- *    content_area = gtk_dialog_get_content_area (GTK_DIALOG (dialog));
- *    label = gtk_label_new (message);
- *
- *    /&ast; Ensure that the dialog box is destroyed when the user responds &ast;/
- *    g_signal_connect_swapped (dialog,
- *                              "response",
- *                              G_CALLBACK (gtk_widget_destroy),
- *                              dialog);
- *
- *    /&ast; Add the label, and show everything we’ve added to the dialog &ast;/
- *
- *    gtk_container_add (GTK_CONTAINER (content_area), label);
- *    gtk_widget_show_all (dialog);
+ *  GtkWidget *dialog, *label, *content_area;
+ *  GtkDialogFlags flags;
+ *
+ *  /&ast; Create the widgets &ast;/
+ *  flags = GTK_DIALOG_DESTROY_WITH_PARENT;
+ *  dialog = gtk_dialog_new_with_buttons ("Message",
+ *                                        parent,
+ *                                        flags,
+ *                                        _("_OK"),
+ *                                        GTK_RESPONSE_NONE,
+ *                                        NULL);
+ *  content_area = gtk_dialog_get_content_area (GTK_DIALOG (dialog));
+ *  label = gtk_label_new (message);
+ *
+ *  /&ast; Ensure that the dialog box is destroyed when the user
+ *  responds &ast;/
+ *
+ *  g_signal_connect_swapped (dialog,
+ *                            "response",
+ *                            G_CALLBACK (gtk_widget_destroy),
+ *                            dialog);
+ *
+ *  /&ast; Add the label, and show everything we’ve added &ast;/
+ *
+ *  gtk_container_add (GTK_CONTAINER (content_area), label);
+ *  gtk_widget_show_all (dialog);
  * }
  * ]|
  *
@@ -860,14 +864,16 @@ gtk_dialog_new_empty (const gchar     *title,
  *
  * Here’s a simple example:
  * |[<!-- language="C" -->
- *  GtkWidget *dialog = gtk_dialog_new_with_buttons ("My dialog",
- *                                                   main_app_window,
- *                                                   GTK_DIALOG_MODAL | GTK_DIALOG_DESTROY_WITH_PARENT,
- *                                                   _("_OK"),
- *                                                   GTK_RESPONSE_ACCEPT,
- *                                                   _("_Cancel"),
- *                                                   GTK_RESPONSE_REJECT,
- *                                                   NULL);
+ *  GtkWidget *dialog;
+ *  GtkDialogFlags flags = GTK_DIALOG_MODAL | GTK_DIALOG_DESTROY_WITH_PARENT;
+ *  dialog = gtk_dialog_new_with_buttons ("My dialog",
+ *                                        main_app_window,
+ *                                        flags,
+ *                                        _("_OK"),
+ *                                        GTK_RESPONSE_ACCEPT,
+ *                                        _("_Cancel"),
+ *                                        GTK_RESPONSE_REJECT,
+ *                                        NULL);
  * ]|
  *
  * Return value: a new #GtkDialog
diff --git a/gtk/gtkdnd.h b/gtk/gtkdnd.h
index c7060da857..de328dbccf 100644
--- a/gtk/gtkdnd.h
+++ b/gtk/gtkdnd.h
@@ -60,9 +60,9 @@ G_BEGIN_DECLS
  * of the user for a drag destination site.
  */
 typedef enum {
-  GTK_DEST_DEFAULT_MOTION     = 1 << 0, /* respond to "drag_motion" */
-  GTK_DEST_DEFAULT_HIGHLIGHT  = 1 << 1, /* auto-highlight */
-  GTK_DEST_DEFAULT_DROP       = 1 << 2, /* respond to "drag_drop" */
+  GTK_DEST_DEFAULT_MOTION     = 1 << 0,
+  GTK_DEST_DEFAULT_HIGHLIGHT  = 1 << 1,
+  GTK_DEST_DEFAULT_DROP       = 1 << 2,
   GTK_DEST_DEFAULT_ALL        = 0x07
 } GtkDestDefaults;
 
diff --git a/gtk/gtkentry.c b/gtk/gtkentry.c
index 48a0be3afe..a79ccd0a3d 100644
--- a/gtk/gtkentry.c
+++ b/gtk/gtkentry.c
@@ -7737,7 +7737,9 @@ gtk_entry_get_overwrite_mode (GtkEntry *entry)
  * This is equivalent to:
  *
  * |[<!-- language="C" -->
- * gtk_entry_buffer_get_text (gtk_entry_get_buffer (entry));
+ * GtkEntryBuffer *buffer;
+ * buffer = gtk_entry_get_buffer (entry);
+ * gtk_entry_buffer_get_text (buffer);
  * ]|
  *
  * Return value: a pointer to the contents of the widget as a
@@ -7759,7 +7761,7 @@ gtk_entry_get_text (GtkEntry *entry)
  * @max: the maximum length of the entry, or 0 for no maximum.
  *   (other than the maximum length of entries.) The value passed in will
  *   be clamped to the range 0-65536.
- * 
+ *
  * Sets the maximum allowed length of the contents of the widget. If
  * the current contents are longer than the given length, then they
  * will be truncated to fit.
@@ -7767,7 +7769,9 @@ gtk_entry_get_text (GtkEntry *entry)
  * This is equivalent to:
  *
  * |[<!-- language="C" -->
- * gtk_entry_buffer_set_max_length (gtk_entry_get_buffer (entry), max);
+ * GtkEntryBuffer *buffer;
+ * buffer = gtk_entry_get_buffer (entry);
+ * gtk_entry_buffer_set_max_length (buffer, max);
  * ]|
  **/
 void
@@ -7788,7 +7792,9 @@ gtk_entry_set_max_length (GtkEntry     *entry,
  * This is equivalent to:
  *
  * |[<!-- language="C" -->
- * gtk_entry_buffer_get_max_length (gtk_entry_get_buffer (entry));
+ * GtkEntryBuffer *buffer;
+ * buffer = gtk_entry_get_buffer (entry);
+ * gtk_entry_buffer_get_max_length (buffer);
  * ]|
  *
  * Return value: the maximum allowed number of characters
@@ -7812,7 +7818,9 @@ gtk_entry_get_max_length (GtkEntry *entry)
  * This is equivalent to:
  *
  * |[<!-- language="C" -->
- * gtk_entry_buffer_get_length (gtk_entry_get_buffer (entry));
+ * GtkEntryBuffer *buffer;
+ * buffer = gtk_entry_get_buffer (entry);
+ * gtk_entry_buffer_get_length (buffer);
  * ]|
  *
  * Return value: the current number of characters
diff --git a/gtk/gtkenums.h b/gtk/gtkenums.h
index 6cba7d345e..48414b82bc 100644
--- a/gtk/gtkenums.h
+++ b/gtk/gtkenums.h
@@ -200,15 +200,13 @@ typedef enum
 typedef enum
 {
   GTK_DELETE_CHARS,
-  GTK_DELETE_WORD_ENDS,           /* delete only the portion of the word to the
-                                   * left/right of cursor if we're in the middle
-                                   * of a word */
+  GTK_DELETE_WORD_ENDS,
   GTK_DELETE_WORDS,
   GTK_DELETE_DISPLAY_LINES,
   GTK_DELETE_DISPLAY_LINE_ENDS,
-  GTK_DELETE_PARAGRAPH_ENDS,      /* like C-k in Emacs (or its reverse) */
-  GTK_DELETE_PARAGRAPHS,          /* C-k in pico, kill whole line */
-  GTK_DELETE_WHITESPACE           /* M-\ in Emacs */
+  GTK_DELETE_PARAGRAPH_ENDS,
+  GTK_DELETE_PARAGRAPHS,
+  GTK_DELETE_WHITESPACE
 } GtkDeleteType;
 
 /* Focus movement types */
diff --git a/gtk/gtkfilechooserdialog.c b/gtk/gtkfilechooserdialog.c
index 771f38e007..70eea814a9 100644
--- a/gtk/gtkfilechooserdialog.c
+++ b/gtk/gtkfilechooserdialog.c
@@ -59,19 +59,24 @@
  *
  * |[
  * GtkWidget *dialog;
+ * GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_OPEN;
+ * gint res;
  *
  * dialog = gtk_file_chooser_dialog_new ("Open File",
  *                                       parent_window,
- *                                       GTK_FILE_CHOOSER_ACTION_OPEN,
- *                                       _("_Cancel"), GTK_RESPONSE_CANCEL,
- *                                       _("_Open"), GTK_RESPONSE_ACCEPT,
+ *                                       action,
+ *                                       _("_Cancel"),
+ *                                       GTK_RESPONSE_CANCEL,
+ *                                       _("_Open"),
+ *                                       GTK_RESPONSE_ACCEPT,
  *                                       NULL);
  *
- * if (gtk_dialog_run (GTK_DIALOG (dialog)) == GTK_RESPONSE_ACCEPT)
+ * res = gtk_dialog_run (GTK_DIALOG (dialog));
+ * if (res == GTK_RESPONSE_ACCEPT)
  *   {
  *     char *filename;
- *
- *     filename = gtk_file_chooser_get_filename (GTK_FILE_CHOOSER (dialog));
+ *     GtkFileChooser *chooser = GTK_FILE_CHOOSER (dialog);
+ *     filename = gtk_file_chooser_get_filename (chooser);
  *     open_file (filename);
  *     g_free (filename);
  *   }
@@ -83,25 +88,35 @@
  *
  * |[
  * GtkWidget *dialog;
+ * GtkFileChooser *chooser;
+ * GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_SAVE;
+ * gint res;
  *
  * dialog = gtk_file_chooser_dialog_new ("Save File",
  *                                       parent_window,
- *                                       GTK_FILE_CHOOSER_ACTION_SAVE,
- *                                       _("_Cancel"), GTK_RESPONSE_CANCEL,
- *                                       _("_Save"), GTK_RESPONSE_ACCEPT,
+ *                                       action,
+ *                                       _("_Cancel"),
+ *                                       GTK_RESPONSE_CANCEL,
+ *                                       _("_Save"),
+ *                                       GTK_RESPONSE_ACCEPT,
  *                                       NULL);
- * gtk_file_chooser_set_do_overwrite_confirmation (GTK_FILE_CHOOSER (dialog), TRUE);
+ * chooser = GTK_FILE_CHOOSER (dialog);
+ *
+ * gtk_file_chooser_set_do_overwrite_confirmation (chooser, TRUE);
  *
  * if (user_edited_a_new_document)
- *   gtk_file_chooser_set_current_name (GTK_FILE_CHOOSER (dialog), "Untitled document");
+ *   gtk_file_chooser_set_current_name (chooser,
+ *                                      _("Untitled document"));
  * else
- *   gtk_file_chooser_set_filename (GTK_FILE_CHOOSER (dialog), filename_for_existing_document);
+ *   gtk_file_chooser_set_filename (chooser,
+ *                                  existing_filename);
  *
- * if (gtk_dialog_run (GTK_DIALOG (dialog)) == GTK_RESPONSE_ACCEPT)
+ * res = gtk_dialog_run (GTK_DIALOG (dialog));
+ * if (res == GTK_RESPONSE_ACCEPT)
  *   {
  *     char *filename;
  *
- *     filename = gtk_file_chooser_get_filename (GTK_FILE_CHOOSER (dialog));
+ *     filename = gtk_file_chooser_get_filename (chooser);
  *     save_to_file (filename);
  *     g_free (filename);
  *   }
@@ -143,12 +158,15 @@
  *
  * |[
  * GtkWidget *dialog;
+ * GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_OPEN;
  *
  * dialog = gtk_file_chooser_dialog_new ("Open File",
  *                                       parent_window,
- *                                       GTK_FILE_CHOOSER_ACTION_OPEN,
- *                                       _("_Cancel"), GTK_RESPONSE_CANCEL,
- *                                       _("_Open"), GTK_RESPONSE_ACCEPT,
+ *                                       action,
+ *                                       _("_Cancel"),
+ *                                       GTK_RESPONSE_CANCEL,
+ *                                       _("_Open"),
+ *                                       GTK_RESPONSE_ACCEPT,
  *                                       NULL);
  * ]|
  *
diff --git a/gtk/gtkframe.h b/gtk/gtkframe.h
index 0237da9709..8d3ed78da3 100644
--- a/gtk/gtkframe.h
+++ b/gtk/gtkframe.h
@@ -66,7 +66,8 @@ struct _GtkFrameClass
 
   /*< public >*/
 
-  void (*compute_child_allocation) (GtkFrame *frame, GtkAllocation *allocation);
+  void (*compute_child_allocation) (GtkFrame *frame,
+                                    GtkAllocation *allocation);
 
   /*< private >*/
 
diff --git a/gtk/gtkimage.c b/gtk/gtkimage.c
index 2932062c9e..ffa4ceabef 100644
--- a/gtk/gtkimage.c
+++ b/gtk/gtkimage.c
@@ -86,10 +86,11 @@
  *     g_print ("Event box clicked at coordinates %f,%f\n",
  *              event->x, event->y);
  *
- *     /&ast; Returning TRUE means we handled the event, so the signal
- *      &ast; emission should be stopped (don’t call any further
- *      &ast; callbacks that may be connected). Return FALSE
- *      &ast; to continue invoking callbacks.
+ *     /&ast; Returning TRUE means we handled the event,
+ *      &ast; so the signal emission should be stopped
+ *      &ast; (don’t call any further callbacks that
+ *      &ast; may be connected). Return FALSE to
+ *      &ast; continue invoking callbacks.
  *      &ast;/
  *     return TRUE;
  *   }
diff --git a/gtk/gtkinfobar.c b/gtk/gtkinfobar.c
index c0e756f193..1b485bcb47 100644
--- a/gtk/gtkinfobar.c
+++ b/gtk/gtkinfobar.c
@@ -75,27 +75,36 @@
  * A simple example for using a GtkInfoBar:
  * |[<!-- language="C" -->
  * /&ast; set up info bar &ast;/
- * info_bar = gtk_info_bar_new ();
- * gtk_widget_set_no_show_all (info_bar, TRUE);
+ * GtkWidget *widget;
+ * GtkInfoBar *bar;
+ *
+ * widget = gtk_info_bar_new ();
+ * bar = GTK_INFO_BAR (bar);
+ *
+ * gtk_widget_set_no_show_all (widget, TRUE);
  * message_label = gtk_label_new ("");
  * gtk_widget_show (message_label);
- * content_area = gtk_info_bar_get_content_area (GTK_INFO_BAR (info_bar));
- * gtk_container_add (GTK_CONTAINER (content_area), message_label);
- * gtk_info_bar_add_button (GTK_INFO_BAR (info_bar),
- *                          _("_OK"), GTK_RESPONSE_OK);
- * g_signal_connect (info_bar, "response",
- *                   G_CALLBACK (gtk_widget_hide), NULL);
+ * content_area = gtk_info_bar_get_content_area (bar);
+ * gtk_container_add (GTK_CONTAINER (content_area),
+ *                    message_label);
+ * gtk_info_bar_add_button (bar,
+ *                          _("_OK"),
+ *                          GTK_RESPONSE_OK);
+ * g_signal_connect (bar,
+ *                   "response",
+ *                   G_CALLBACK (gtk_widget_hide),
+ *                   NULL);
  * gtk_grid_attach (GTK_GRID (grid),
- *                  info_bar,
+ *                  widget,
  *                  0, 2, 1, 1);
  *
  * /&ast; ... &ast;/
  *
  * /&ast; show an error message &ast;/
- * gtk_label_set_text (GTK_LABEL (message_label), error_message);
- * gtk_info_bar_set_message_type (GTK_INFO_BAR (info_bar),
+ * gtk_label_set_text (GTK_LABEL (message_label), message);
+ * gtk_info_bar_set_message_type (bar,
  *                                GTK_MESSAGE_ERROR);
- * gtk_widget_show (info_bar);
+ * gtk_widget_show (bar);
  * ]|
  *
  * # GtkInfoBar as GtkBuildable
diff --git a/gtk/gtklabel.c b/gtk/gtklabel.c
index 827bea3fdf..10f6c8cae0 100644
--- a/gtk/gtklabel.c
+++ b/gtk/gtklabel.c
@@ -207,7 +207,11 @@
  * An example looks like this:
  *
  * |[<!-- language="C" -->
- * gtk_label_set_markup (label, "Go to the <a href=\"http://www.gtk.org title="&lt;i&gt;Our&lt;/i&gt; website\">GTK+ website</a> for more...");
+ * const gchar *text =
+ * "Go to the"
+ * "<a href=\"http://www.gtk.org title="&lt;i&gt;Our&lt;/i&gt; website\">"
+ * "GTK+ website</a> for more...";
+ * gtk_label_set_markup (label, text);
  * ]|
  *
  * It is possible to implement custom handling for links and their tooltips with
@@ -2601,9 +2605,10 @@ gtk_label_set_markup_internal (GtkLabel    *label,
  * external data, you may need to escape it with g_markup_escape_text() or
  * g_markup_printf_escaped():
  * |[<!-- language="C" -->
+ * const char *format = "<span style=\"italic\">\%s</span>";
  * char *markup;
  *
- * markup = g_markup_printf_escaped ("<span style=\"italic\">\%s</span>", str);
+ * markup = g_markup_printf_escaped (format, str);
  * gtk_label_set_markup (GTK_LABEL (label), markup);
  * g_free (markup);
  * ]|
diff --git a/gtk/gtklevelbar.c b/gtk/gtklevelbar.c
index ce9118a526..c7c143619f 100644
--- a/gtk/gtklevelbar.c
+++ b/gtk/gtklevelbar.c
@@ -40,19 +40,25 @@
  * static GtkWidget *
  * create_level_bar (void)
  * {
- *   GtkWidget *level_bar;
+ *   GtkWidget *widget;
+ *   GtkLevelBar *bar;
  *
- *   level_bar = gtk_level_bar_new ();
+ *   widget = gtk_level_bar_new ();
+ *   bar = GTK_LEVEL_BAR (widget);
  *
- *   /<!---->* This changes the value of the default low offset *<!---->/
- *   gtk_level_bar_add_offset_value (GTK_LEVEL_BAR (level_bar),
- *                                   GTK_LEVEL_BAR_OFFSET_LOW, 0.10);
+ *   /<!---->* This changes the value of the default low offset
+ *   *<!---->/
+ *
+ *   gtk_level_bar_add_offset_value (bar,
+ *                                   GTK_LEVEL_BAR_OFFSET_LOW,
+ *                                   0.10);
  *
  *   /<!---->* This adds a new offset to the bar; the application will
- *    * be able to change its color by using the following selector,
- *    * either by adding it to its CSS file or using
- *    * gtk_css_provider_load_from_data() and gtk_style_context_add_provider()
- *    *
+ *    be able to change its color by using the following selector,
+ *    either by adding it to its CSS file or using
+ *    gtk_css_provider_load_from_data() and
+ *    gtk_style_context_add_provider()
+ *
  *    * .level-bar.fill-block.level-my-offset {
  *    *   background-color: green;
  *    *   border-style: solid;
@@ -60,10 +66,10 @@
  *    *   border-style: 1px;
  *    * }
  *    *<!---->/
- *   gtk_level_bar_add_offset_value (GTK_LEVEL_BAR (level_bar),
- *                                   "my-offset", 0.60);
  *
- *   return level_bar;
+ *   gtk_level_bar_add_offset_value (bar, "my-offset", 0.60);
+ *
+ *   return widget;
  * }
  * ]|
  *
diff --git a/gtk/gtkliststore.c b/gtk/gtkliststore.c
index 039d74d267..204fcbc448 100644
--- a/gtk/gtkliststore.c
+++ b/gtk/gtkliststore.c
@@ -87,8 +87,8 @@
  *                           COLUMN_BOOLEAN,  FALSE,
  *                           -1);
  *
- *       /&ast; As the store will keep a copy of the string internally,
- *        &ast; we free some_data.
+ *       /&ast; As the store will keep a copy of
+ *        &ast; the string internally, we free some_data.
  *        &ast;/
  *       g_free (some_data);
  *     }
diff --git a/gtk/gtkmain.c b/gtk/gtkmain.c
index 82037e107f..c37d900dc2 100644
--- a/gtk/gtkmain.c
+++ b/gtk/gtkmain.c
@@ -59,7 +59,8 @@
  * int
  * main (int argc, char **argv)
  * {
- *   /&ast; Initialize i18n support with bindtextdomain(), etc. &ast;/
+ *   /&ast; Initialize i18n support with
+ *    bindtextdomain(), etc. &ast;/
  *   ...
  *
  *   /&ast; Initialize the widget set &ast;/
@@ -74,7 +75,8 @@
  *   /&ast; Show the application window &ast;/
  *   gtk_widget_show_all (mainwin);
  *
- *   /&ast; Enter the main event loop, and wait for user interaction &ast;/
+ *   /&ast; Enter the main event loop, and
+ *    wait for user interaction &ast;/
  *   gtk_main ();
  *
  *   /&ast; The user lost interest &ast;/
@@ -1811,18 +1813,23 @@ gtk_main_do_event (GdkEvent *event)
  * main (int argc, char **argv)
  * {
  *   GtkWidget *win, *but;
+ *   const char *text = "Close yourself. I mean it!";
  *
  *   gtk_init (&argc, &argv);
  *
  *   win = gtk_window_new (GTK_WINDOW_TOPLEVEL);
- *   g_signal_connect (win, "delete-event",
- *                     G_CALLBACK (gtk_true), NULL);
+ *   g_signal_connect (win,
+ *                     "delete-event",
+ *                     G_CALLBACK (gtk_true),
+ *                     NULL);
  *   g_signal_connect (win, "destroy",
- *                     G_CALLBACK (gtk_main_quit), NULL);
+ *                     G_CALLBACK (gtk_main_quit),
+ *                     NULL);
  *
- *   but = gtk_button_new_with_label ("Close yourself. I mean it!");
+ *   but = gtk_button_new_with_label (text);
  *   g_signal_connect_swapped (but, "clicked",
- *                             G_CALLBACK (gtk_object_destroy), win);
+ *                             G_CALLBACK (gtk_object_destroy),
+ *                             win);
  *   gtk_container_add (GTK_CONTAINER (win), but);
  *
  *   gtk_widget_show_all (win);
diff --git a/gtk/gtkmessagedialog.c b/gtk/gtkmessagedialog.c
index 5d42123a2d..fb0374ce91 100644
--- a/gtk/gtkmessagedialog.c
+++ b/gtk/gtkmessagedialog.c
@@ -60,12 +60,14 @@
  *
  * An example for using a modal dialog:
  * |[<!-- language="C" -->
- *  dialog = gtk_message_dialog_new (main_application_window,
- *                                   GTK_DIALOG_DESTROY_WITH_PARENT,
+ *  GtkDialogFlags flags = GTK_DIALOG_DESTROY_WITH_PARENT;
+ *  dialog = gtk_message_dialog_new (parent_window,
+ *                                   flags,
  *                                   GTK_MESSAGE_ERROR,
  *                                   GTK_BUTTONS_CLOSE,
- *                                   "Error loading file '%s': %s",
- *                                   filename, g_strerror (errno));
+ *                                   "Error reading “%s”: %s",
+ *                                   filename,
+ *                                   g_strerror (errno));
  *  gtk_dialog_run (GTK_DIALOG (dialog));
  *  gtk_widget_destroy (dialog);
  * ]|
@@ -74,14 +76,18 @@
  *
  * An example for a non-modal dialog:
  * |[<!-- language="C" -->
- *  dialog = gtk_message_dialog_new (main_application_window,
- *                                   GTK_DIALOG_DESTROY_WITH_PARENT,
+ *  GtkDialogFlags flags = GTK_DIALOG_DESTROY_WITH_PARENT;
+ *  dialog = gtk_message_dialog_new (parent_window,
+ *                                   flags,
  *                                   GTK_MESSAGE_ERROR,
  *                                   GTK_BUTTONS_CLOSE,
- *                                   "Error loading file '%s': %s",
- *                                   filename, g_strerror (errno));
+ *                                   "Error reading “%s”: %s",
+ *                                   filename,
+ *                                   g_strerror (errno));
+ *
+ *  /&ast; Destroy the dialog when the user responds to it
+ *  (e.g. clicks a button) &ast;/
  *
- *  /&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);
@@ -608,8 +614,9 @@ gtk_message_dialog_new (GtkWindow     *parent,
  * argument.
  * |[<!-- language="C" -->
  *  GtkWidget *dialog;
- *  dialog = gtk_message_dialog_new (main_application_window,
- *                                   GTK_DIALOG_DESTROY_WITH_PARENT,
+ *  GtkDialogFlags flags = GTK_DIALOG_DESTROY_WITH_PARENT;
+ *  dialog = gtk_message_dialog_new (parent_window,
+ *                                   flags,
  *                                   GTK_MESSAGE_ERROR,
  *                                   GTK_BUTTONS_CLOSE,
  *                                   NULL);
@@ -799,7 +806,8 @@ gtk_message_dialog_format_secondary_text (GtkMessageDialog *message_dialog,
  * gchar *msg;
  *
  * msg = g_markup_printf_escaped (message_format, ...);
- * gtk_message_dialog_format_secondary_markup (message_dialog, "%s", msg);
+ * gtk_message_dialog_format_secondary_markup (message_dialog,
+ *                                             "%s", msg);
  * g_free (msg);
  * ]|
  *
diff --git a/gtk/gtknotebook.c b/gtk/gtknotebook.c
index 6ca07a77ec..2debf9ead5 100644
--- a/gtk/gtknotebook.c
+++ b/gtk/gtknotebook.c
@@ -8397,23 +8397,25 @@ gtk_notebook_get_tab_detachable (GtkNotebook *notebook,
  * widget that corresponds to the dropped tab.
  * |[<!-- language="C" -->
  *  static void
- *  on_drop_zone_drag_data_received (GtkWidget        *widget,
- *                                   GdkDragContext   *context,
- *                                   gint              x,
- *                                   gint              y,
- *                                   GtkSelectionData *selection_data,
- *                                   guint             info,
- *                                   guint             time,
- *                                   gpointer          user_data)
+ *  on_drag_data_received (GtkWidget        *widget,
+ *                         GdkDragContext   *context,
+ *                         gint              x,
+ *                         gint              y,
+ *                         GtkSelectionData *data,
+ *                         guint             info,
+ *                         guint             time,
+ *                         gpointer          user_data)
  *  {
  *    GtkWidget *notebook;
  *    GtkWidget **child;
+ *    GtkContainer *container;
  *
  *    notebook = gtk_drag_get_source_widget (context);
- *    child = (void*) gtk_selection_data_get_data (selection_data);
+ *    child = (void*) gtk_selection_data_get_data (data);
  *
  *    process_widget (*child);
- *    gtk_container_remove (GTK_CONTAINER (notebook), *child);
+ *    container = GTK_CONTAINER (notebook);
+ *    gtk_container_remove (container, *child);
  *  }
  * ]|
  *
diff --git a/gtk/gtkrecentchooserdialog.c b/gtk/gtkrecentchooserdialog.c
index 8a5b98f61e..00382f3aea 100644
--- a/gtk/gtkrecentchooserdialog.c
+++ b/gtk/gtkrecentchooserdialog.c
@@ -51,18 +51,23 @@
  *
  * |[<!-- language="C" -->
  * GtkWidget *dialog;
+ * gint res;
  *
  * dialog = gtk_recent_chooser_dialog_new ("Recent Documents",
  *                                         parent_window,
- *                                         _("_Cancel"), GTK_RESPONSE_CANCEL,
- *                                         _("_Open"), GTK_RESPONSE_ACCEPT,
+ *                                         _("_Cancel"),
+ *                                         GTK_RESPONSE_CANCEL,
+ *                                         _("_Open"),
+ *                                         GTK_RESPONSE_ACCEPT,
  *                                         NULL);
  *
- * if (gtk_dialog_run (GTK_DIALOG (dialog)) == GTK_RESPONSE_ACCEPT)
+ * res = gtk_dialog_run (GTK_DIALOG (dialog));
+ * if (res == GTK_RESPONSE_ACCEPT)
  *   {
  *     GtkRecentInfo *info;
+ *     GtkRecentChooser *chooser = GTK_RECENT_CHOOSER (dialog);
  *
- *     info = gtk_recent_chooser_get_current_item (GTK_RECENT_CHOOSER (dialog));
+ *     info = gtk_recent_chooser_get_current_item (chooser);
  *     open_file (gtk_recent_info_get_uri (info));
  *     gtk_recent_info_unref (info);
  *   }
diff --git a/gtk/gtksearchbar.c b/gtk/gtksearchbar.c
index 2e9c8ac6fa..23f76cc3fc 100644
--- a/gtk/gtksearchbar.c
+++ b/gtk/gtksearchbar.c
@@ -165,15 +165,18 @@ preedit_changed_cb (GtkEntry  *entry,
  *
  * |[<!-- language="C" -->
  * static gboolean
- * window_key_press_event_cb (GtkWidget *widget,
- *                            GdkEvent  *event,
- *                            gpointer   user_data)
+ * on_key_press_event (GtkWidget *widget,
+ *                     GdkEvent  *event,
+ *                     gpointer   user_data)
  * {
- *   return gtk_search_bar_handle_event (GTK_SEARCH_BAR (user_data), event);
+ *   GtkSearchBar *bar = GTK_SEARCH_BAR (user_data);
+ *   return gtk_search_bar_handle_event (bar, event);
  * }
  *
- * g_signal_connect (window, "key-press-event",
- *                   G_CALLBACK (window_key_press_event_cb), search_bar);
+ * g_signal_connect (window,
+ *                  "key-press-event",
+ *                   G_CALLBACK (on_key_press_event),
+ *                   search_bar);
  * ]|
  *
  * Return value: %GDK_EVENT_STOP if the key press event resulted
diff --git a/gtk/gtktogglebutton.c b/gtk/gtktogglebutton.c
index de12f53560..31c84be324 100644
--- a/gtk/gtktogglebutton.c
+++ b/gtk/gtktogglebutton.c
@@ -63,23 +63,33 @@
  * |[<!-- language="C" -->
  * void make_toggles (void) {
  *    GtkWidget *dialog, *toggle1, *toggle2;
+ *    GtkWidget *content_area;
+ *    const char *text;
  *
- *    dialog = gtk_dialog_new ();
- *    toggle1 = gtk_toggle_button_new_with_label ("Hi, i’m a toggle button.");
+ *    dialog = gtk_dialog_new (text);
+ *    content_area = gtk_dialog_get_content_area ();
+ *
+ *    text = "Hi, i’m a toggle button.";
+ *    toggle1 = gtk_toggle_button_new_with_label (text);
  *
  *    /&ast; Makes this toggle button invisible &ast;/
- *    gtk_toggle_button_set_mode (GTK_TOGGLE_BUTTON (toggle1), TRUE);
+ *    gtk_toggle_button_set_mode (GTK_TOGGLE_BUTTON (toggle1),
+ *                                TRUE);
  *
  *    g_signal_connect (toggle1, "toggled",
- *                      G_CALLBACK (output_state), NULL);
- *    gtk_box_pack_start (GTK_BOX (GTK_DIALOG (dialog)->action_area),
+ *                      G_CALLBACK (output_state),
+ *                      NULL);
+ *    gtk_box_pack_start (GTK_BOX (content_area),
  *                        toggle1, FALSE, FALSE, 2);
  *
- *    toggle2 = gtk_toggle_button_new_with_label ("Hi, i’m another toggle button.");
- *    gtk_toggle_button_set_mode (GTK_TOGGLE_BUTTON (toggle2), FALSE);
+ *    text = "Hi, i’m a toggle button.";
+ *    toggle2 = gtk_toggle_button_new_with_label (text);
+ *    gtk_toggle_button_set_mode (GTK_TOGGLE_BUTTON (toggle2),
+ *                                FALSE);
  *    g_signal_connect (toggle2, "toggled",
- *                      G_CALLBACK (output_state), NULL);
- *    gtk_box_pack_start (GTK_BOX (GTK_DIALOG (dialog)->action_area),
+ *                      G_CALLBACK (output_state),
+ *                      NULL);
+ *    gtk_box_pack_start (GTK_BOX (content_area),
  *                        toggle2, FALSE, FALSE, 2);
  *
  *    gtk_widget_show_all (dialog);
diff --git a/gtk/gtktreemodel.c b/gtk/gtktreemodel.c
index f556440950..3ee9cab003 100644
--- a/gtk/gtktreemodel.c
+++ b/gtk/gtktreemodel.c
@@ -116,13 +116,16 @@
  * ## Acquiring a #GtkTreeIter-struct
  *
  * |[<!-- language="C" -->
- *  /&ast; Three ways of getting the iter pointing to the location &ast;/
+ *  /&ast; Three ways of getting the iter pointing to the
+ *   location &ast;/
  * GtkTreePath *path;
  * GtkTreeIter iter;
  * GtkTreeIter parent_iter;
  *
  * /&ast; get the iterator from a string &ast;/
- * gtk_tree_model_get_iter_from_string (model, &iter, "3:2:5");
+ * gtk_tree_model_get_iter_from_string (model,
+ *                                      &iter,
+ *                                      "3:2:5");
  *
  * /&ast; get the iterator from a path &ast;/
  * path = gtk_tree_path_new_from_string ("3:2:5");
@@ -130,11 +133,14 @@
  * gtk_tree_path_free (path);
  *
  * /&ast; walk the tree to find the iterator &ast;/
- * gtk_tree_model_iter_nth_child (model, &iter, NULL, 3);
+ * gtk_tree_model_iter_nth_child (model, &iter,
+ *                                NULL, 3);
  * parent_iter = iter;
- * gtk_tree_model_iter_nth_child (model, &iter, &parent_iter, 2);
+ * gtk_tree_model_iter_nth_child (model, &iter,
+ *                                &parent_iter, 2);
  * parent_iter = iter;
- * gtk_tree_model_iter_nth_child (model, &iter, &parent_iter, 5);
+ * gtk_tree_model_iter_nth_child (model, &iter,
+ *                                &parent_iter, 5);
  * ]|
  *
  * This second example shows a quick way of iterating through a list
@@ -161,22 +167,26 @@
  * gint row_count = 0;
  *
  * /&ast; make a new list_store &ast;/
- * list_store = gtk_list_store_new (N_COLUMNS, G_TYPE_STRING, G_TYPE_INT);
+ * list_store = gtk_list_store_new (N_COLUMNS,
+ *                                  G_TYPE_STRING,
+ *                                  G_TYPE_INT);
  *
  * /&ast; Fill the list store with data &ast;/
  * populate_model (list_store);
  *
- * /&ast; Get the first iter in the list, check it is valid and walk
- *  &ast; through the list, reading each row. &ast;/
- * for (valid = gtk_tree_model_get_iter_first (list_store, &iter);
- *      valid;
- *      valid = gtk_tree_model_iter_next (list_store, &iter))
+ * /&ast; Get the first iter in the list, check it is
+ *  valid and walk through the list, reading each row.
+ * &ast;/
+ *
+ * valid = gtk_tree_model_get_iter_first (list_store,
+ *                                        &iter);
+ * while (valid)
  *  {
  *    gchar *str_data;
  *    gint   int_data;
  *
- *    /&ast; Make sure you terminate calls to gtk_tree_model_get()
- *     &ast; with a “-1” value
+ *    /&ast; Make sure you terminate calls to
+ *     &ast; gtk_tree_model_get() with a “-1” value
  *     &ast;/
  *    gtk_tree_model_get (list_store, &iter,
  *                        STRING_COLUMN, &str_data,
@@ -184,9 +194,12 @@
  *                        -1);
  *
  *    /&ast; Do something with the data &ast;/
- *    g_print ("Row %d: (%s,%d)\n", row_count, str_data, int_data);
+ *    g_print ("Row %d: (%s,%d)\n",
+ *             row_count, str_data, int_data);
  *    g_free (str_data);
  *
+ *    valid = gtk_tree_model_iter_next (list_store,
+ *                                      &iter);
  *    row_count++;
  *  }
  * ]|
diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index a5844b5c79..838e4ca8b3 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -156,20 +156,28 @@
  *
  * |[<!-- language="C" -->
  * static void
- * foo_widget_get_preferred_height (GtkWidget *widget, gint *min_height, gint *nat_height)
+ * foo_widget_get_preferred_height (GtkWidget *widget,
+ *                                  gint *min_height,
+ *                                  gint *nat_height)
  * {
  *    if (i_am_in_height_for_width_mode)
  *      {
  *        gint min_width;
  *
- *        GTK_WIDGET_GET_CLASS (widget)->get_preferred_width (widget, &min_width, NULL);
- *        GTK_WIDGET_GET_CLASS (widget)->get_preferred_height_for_width (widget, min_width,
- *                                                                      min_height, nat_height);
+ *        GTK_WIDGET_GET_CLASS (widget)->get_preferred_width (widget,
+ *                                                            &min_width,
+ *                                                            NULL);
+ *        GTK_WIDGET_GET_CLASS (widget)->get_preferred_height_for_width
+ *                                                           (widget,
+ *                                                            min_width,
+ *                                                            min_height,
+ *                                                            nat_height);
  *      }
  *    else
  *      {
- *         ... some widgets do both. For instance, if a GtkLabel is rotated to 90 degrees
- *         it will return the minimum and natural height for the rotated label here.
+ *         ... some widgets do both. For instance, if a GtkLabel is
+ *         rotated to 90 degrees it will return the minimum and
+ *         natural height for the rotated label here.
  *      }
  * }
  * ]|
@@ -178,18 +186,22 @@
  * the minimum and natural width:
  * |[<!-- language="C" -->
  * static void
- * foo_widget_get_preferred_width_for_height (GtkWidget *widget, gint for_height,
- *                                            gint *min_width, gint *nat_width)
+ * foo_widget_get_preferred_width_for_height (GtkWidget *widget,
+ *                                            gint for_height,
+ *                                            gint *min_width,
+ *                                            gint *nat_width)
  * {
  *    if (i_am_in_height_for_width_mode)
  *      {
- *        GTK_WIDGET_GET_CLASS (widget)->get_preferred_width (widget, min_width, nat_width);
+ *        GTK_WIDGET_GET_CLASS (widget)->get_preferred_width (widget,
+ *                                                            min_width,
+ *                                                            nat_width);
  *      }
  *    else
  *      {
- *         ... again if a widget is sometimes operating in width-for-height mode
- *         (like a rotated GtkLabel) it can go ahead and do its real width for
- *         height calculation here.
+ *         ... again if a widget is sometimes operating in
+ *         width-for-height mode (like a rotated GtkLabel) it can go
+ *         ahead and do its real width for height calculation here.
  *      }
  * }
  * ]|
@@ -201,8 +213,9 @@
  * be careful to call its virtual methods directly, like this:
  *
  * |[<!-- language="C" -->
- * GTK_WIDGET_GET_CLASS(widget)-&gt;get_preferred_width (widget),
- *                                  &min, &natural);
+ * GTK_WIDGET_GET_CLASS(widget)->get_preferred_width (widget,
+ *                                                    &min,
+ *                                                    &natural);
  * ]|
  *
  * It will not work to use the wrapper functions, such as
@@ -2952,7 +2965,8 @@ G_GNUC_END_IGNORE_DEPRECATIONS
    *     gdk_drag_status (context, 0, time);
    *   else
    *    {
-   *      private_data->pending_status = gdk_drag_context_get_suggested_action (context);
+   *      private_data->pending_status
+   *         = gdk_drag_context_get_suggested_action (context);
    *      gtk_drag_get_data (widget, context, target, time);
    *    }
    *
@@ -2974,16 +2988,18 @@ G_GNUC_END_IGNORE_DEPRECATIONS
    *    {
    *      private_data->suggested_action = 0;
    *
-   *      /&ast; We are getting this data due to a request in drag_motion,
-   *       * rather than due to a request in drag_drop, so we are just
-   *       * supposed to call gdk_drag_status(), not actually paste in
-   *       * the data.
-   *       &ast;/
+   *      /&ast; We are getting this data due to a request in
+   *      drag_motion, rather than due to a request in drag_drop,
+   *      so we are just supposed to call gdk_drag_status(), not
+   *      actually paste in the data. &ast;/
+   *
    *      str = gtk_selection_data_get_text (selection_data);
    *      if (!data_is_acceptable (str))
    *        gdk_drag_status (context, 0, time);
    *      else
-   *        gdk_drag_status (context, private_data->suggested_action, time);
+   *        gdk_drag_status (context,
+   *                         private_data->suggested_action,
+   *                         time);
    *    }
    *   else
    *    {
@@ -11097,17 +11113,6 @@ gtk_widget_get_composite_name (GtkWidget *widget)
  * see gtk_container_foreach() vs. gtk_container_forall()), but e.g. GUI
  * builders might want to treat them in a different way.
  *
- * Here is a simple example:
- * |[<!-- language="C" -->
- *   gtk_widget_push_composite_child ();
- *   scrolled_window->hscrollbar = gtk_scrollbar_new (GTK_ORIENTATION_HORIZONTAL, hadjustment);
- *   gtk_widget_set_composite_name (scrolled_window->hscrollbar, "hscrollbar");
- *   gtk_widget_pop_composite_child ();
- *   gtk_widget_set_parent (scrolled_window->hscrollbar,
- *                          GTK_WIDGET (scrolled_window));
- *   g_object_ref (scrolled_window->hscrollbar);
- * ]|
- *
  * Deprecated: 3.10: This API never really worked well and was mostly unused, now
  * we have a more complete mechanism for composite children, see gtk_widget_class_set_template().
  **/
diff --git a/gtk/gtkwindow.c b/gtk/gtkwindow.c
index 24f82158c4..7d28635d73 100644
--- a/gtk/gtkwindow.c
+++ b/gtk/gtkwindow.c
@@ -11367,7 +11367,7 @@ gtk_XParseGeometry (const char   *string,
  * gtk_window_parse_geometry:
  * @window: a #GtkWindow
  * @geometry: geometry string
- * 
+ *
  * Parses a standard X Window System geometry string - see the
  * manual page for X (type “man X”) for details on this.
  * gtk_window_parse_geometry() does work on all GTK+ ports
@@ -11390,46 +11390,53 @@ gtk_XParseGeometry (const char   *string,
  * on the window.
  * |[<!-- language="C" -->
  * #include <gtk/gtk.h>
- *    
+ *
  * static void
  * fill_with_content (GtkWidget *vbox)
  * {
  *   /&ast; fill with content... &ast;/
  * }
- *    
+ *
  * int
  * main (int argc, char *argv[])
  * {
  *   GtkWidget *window, *vbox;
  *   GdkGeometry size_hints = {
- *     100, 50, 0, 0, 100, 50, 10, 10, 0.0, 0.0, GDK_GRAVITY_NORTH_WEST  
+ *     100, 50, 0, 0, 100, 50, 10,
+ *     10, 0.0, 0.0, GDK_GRAVITY_NORTH_WEST
  *   };
- *    
+ *
  *   gtk_init (&argc, &argv);
- *   
+ *
  *   window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
- *   vbox = gtk_box_new (GTK_ORIENTATION_VERTICAL, FALSE, 0);
- *   
+ *   vbox = gtk_box_new (GTK_ORIENTATION_VERTICAL,
+ *                       FALSE, 0);
+ *
  *   gtk_container_add (GTK_CONTAINER (window), vbox);
  *   fill_with_content (vbox);
  *   gtk_widget_show_all (vbox);
- *   
+ *
  *   gtk_window_set_geometry_hints (GTK_WINDOW (window),
  * 	  			    window,
  * 				    &size_hints,
- * 				    GDK_HINT_MIN_SIZE | 
- * 				    GDK_HINT_BASE_SIZE | 
+ * 				    GDK_HINT_MIN_SIZE |
+ * 				    GDK_HINT_BASE_SIZE |
  * 				    GDK_HINT_RESIZE_INC);
- *   
+ *
  *   if (argc > 1)
  *     {
- *       if (!gtk_window_parse_geometry (GTK_WINDOW (window), argv[1]))
- *         fprintf (stderr, "Failed to parse “%s”\n", argv[1]);
+ *       gboolean res;
+ *       res = gtk_window_parse_geometry (GTK_WINDOW (window),
+ *                                        argv[1]);
+ *       if (! res)
+ *         fprintf (stderr,
+ *                  "Failed to parse “%s”\n",
+ *                  argv[1]);
  *     }
- *    
+ *
  *   gtk_widget_show_all (window);
  *   gtk_main ();
- *    
+ *
  *   return 0;
  * }
  * ]|