[gtk+] Docs: Remove all entities and turn off sgml mode



commit 7f6a964c47ad2f9dcf6a00044d938840ce8f01f2
Author: Matthias Clasen <mclasen redhat com>
Date:   Sun Feb 9 17:24:06 2014 -0500

    Docs: Remove all entities and turn off sgml mode
    
    With all element markup gone, it is time to turn off
    sgml mode, and get rid of entities as well.

 docs/reference/gdk/Makefile.am   |    2 +-
 docs/reference/gtk/Makefile.am   |    2 +-
 gdk/gdkcolor.c                   |   18 ++++-----
 gdk/gdkdevice.c                  |    4 +-
 gdk/gdkdevicemanager.c           |    2 +-
 gdk/gdkdisplay.c                 |    4 +-
 gdk/gdkkeys.c                    |   28 ++++++-------
 gdk/gdkrgba.c                    |    4 +-
 gdk/gdkscreen.c                  |    4 +-
 gdk/wayland/gdkdisplay-wayland.c |    7 +--
 gdk/x11/gdkmain-x11.c            |    7 +--
 gtk/deprecated/gtkactiongroup.c  |   32 ++++++--------
 gtk/deprecated/gtkiconfactory.c  |    5 +-
 gtk/deprecated/gtkrc.c           |   81 ++++++++++++++++---------------------
 gtk/deprecated/gtkrecentaction.c |    4 +-
 gtk/deprecated/gtkuimanager.c    |   29 +++++++------
 gtk/gtkaboutdialog.c             |   10 ++--
 gtk/gtkaccelgroup.c              |   23 +++++------
 gtk/gtkaccellabel.c              |   16 ++++---
 gtk/gtkaccelmap.c                |    4 +-
 gtk/gtkapplication.c             |    5 +-
 gtk/gtkapplicationwindow.c       |   21 ++++------
 gtk/gtkbindings.c                |   29 ++++++-------
 gtk/gtkbuildable.c               |    2 +-
 gtk/gtkbuilder.c                 |   82 ++++++++++++++++++-------------------
 gtk/gtkcelllayout.c              |   21 +++++-----
 gtk/gtkcombobox.c                |    4 +-
 gtk/gtkcomboboxtext.c            |   13 +++---
 gtk/gtkcontainer.c               |    7 +--
 gtk/gtkcsscustomproperty.c       |    2 +-
 gtk/gtkcssprovider.c             |   22 +++++-----
 gtk/gtkdialog.c                  |   10 ++--
 gtk/gtkdnd-quartz.c              |    2 +-
 gtk/gtkdnd.c                     |    8 ++--
 gtk/gtkdrawingarea.c             |    2 +-
 gtk/gtkexpander.c                |    9 ++--
 gtk/gtkfilechooser.c             |    2 +-
 gtk/gtkfilechooserbutton.c       |    2 +-
 gtk/gtkfilefilter.c              |    9 ++--
 gtk/gtkframe.c                   |    9 ++--
 gtk/gtkicontheme.c               |   10 ++--
 gtk/gtkiconview.c                |    4 +-
 gtk/gtkimage.c                   |   14 +++---
 gtk/gtkinfobar.c                 |    8 ++--
 gtk/gtklabel.c                   |   25 ++++++------
 gtk/gtkliststore.c               |   27 ++++++-------
 gtk/gtkmenu.c                    |    6 +-
 gtk/gtkmenubutton.c              |    1 +
 gtk/gtkmenuitem.c                |    6 +-
 gtk/gtkmenutoolbutton.c          |    4 +-
 gtk/gtkmessagedialog.c           |    2 +-
 gtk/gtknotebook.c                |    8 ++--
 gtk/gtkoverlay.c                 |    2 +-
 gtk/gtkpagesetup.c               |    2 +-
 gtk/gtkprinter.c                 |    6 +-
 gtk/gtkprintsettings.c           |    4 +-
 gtk/gtkradiobutton.c             |    2 +-
 gtk/gtkrecentfilter.c            |   12 +++---
 gtk/gtkrecentmanager.c           |    2 +-
 gtk/gtkscale.c                   |   14 +++---
 gtk/gtkselection.c               |    8 ++--
 gtk/gtksettings.c                |    6 +-
 gtk/gtkshow.c                    |    2 +-
 gtk/gtksizegroup.c               |   11 ++---
 gtk/gtksizerequest.c             |   10 ++--
 gtk/gtksocket.c                  |    2 +-
 gtk/gtkstylecontext.c            |    6 +-
 gtk/gtktextbufferrichtext.c      |    8 ++--
 gtk/gtktexttagtable.c            |    4 +-
 gtk/gtkthemingengine.c           |    2 +-
 gtk/gtktogglebutton.c            |    4 +-
 gtk/gtktoolbar.c                 |    8 ++--
 gtk/gtktoolbutton.c              |    2 +-
 gtk/gtktoolitem.c                |    6 +-
 gtk/gtktoolitemgroup.c           |    2 +-
 gtk/gtktoolpalette.c             |   10 ++--
 gtk/gtktreemodel.c               |    8 ++--
 gtk/gtktreemodelfilter.c         |    2 +-
 gtk/gtktreemodelsort.c           |   28 ++++++------
 gtk/gtktreeselection.c           |    2 +-
 gtk/gtktreestore.c               |    6 +-
 gtk/gtktreeview.c                |   10 ++--
 gtk/gtkwidget.c                  |   65 +++++++++++++++---------------
 gtk/gtkwidget.h                  |    2 +
 gtk/gtkwidgetpath.c              |    6 +-
 gtk/gtkwindow.c                  |   13 +++---
 86 files changed, 452 insertions(+), 487 deletions(-)
---
diff --git a/docs/reference/gdk/Makefile.am b/docs/reference/gdk/Makefile.am
index 7aefc4d..f19ae8c 100644
--- a/docs/reference/gdk/Makefile.am
+++ b/docs/reference/gdk/Makefile.am
@@ -48,7 +48,7 @@ AM_CPPFLAGS =                         \
 GTKDOC_LIBS = $(top_builddir)/gdk/libgdk-3.la $(GDK_DEP_LIBS)
 
 # Extra options to supply to gtkdoc-mkdb
-MKDB_OPTIONS=--sgml-mode --output-format=xml --name-space=gdk
+MKDB_OPTIONS=--output-format=xml --name-space=gdk
 
 # Extra SGML files that are included by DOC_MAIN_SGML_FILE
 content_files =                \
diff --git a/docs/reference/gtk/Makefile.am b/docs/reference/gtk/Makefile.am
index e66e20f..d5e0c32 100644
--- a/docs/reference/gtk/Makefile.am
+++ b/docs/reference/gtk/Makefile.am
@@ -126,7 +126,7 @@ GTKDOC_LIBS = \
 
 
 # Extra options to supply to gtkdoc-mkdb
-MKDB_OPTIONS=--sgml-mode --output-format=xml --name-space=gtk
+MKDB_OPTIONS=--output-format=xml --name-space=gtk
 
 # Extra SGML files that are included by $(DOC_MAIN_SGML_FILE)
 content_files =                                        \
diff --git a/gdk/gdkcolor.c b/gdk/gdkcolor.c
index e93c82a..c121593 100644
--- a/gdk/gdkcolor.c
+++ b/gdk/gdkcolor.c
@@ -131,13 +131,12 @@ G_DEFINE_BOXED_TYPE (GdkColor, gdk_color,
  * @red, @green, and @blue fields of a #GdkColor.
  *
  * The string can either one of a large set of standard names
- * (taken from the X11 `rgb.txt` file), or
- * it can be a hex value in the form “&num;rgb” “&num;rrggbb”
- * “&num;rrrgggbbb” or “&num;rrrrggggbbbb” where “r”, “g” and
- * “b” are hex digits of the red, green, and blue components
- * of the color, respectively. (White in the four forms is
- * “&num;fff”, “&num;ffffff”, “&num;fffffffff” and
- * “&num;ffffffffffff”).
+ * (taken from the X11 `rgb.txt` file), or it can be a hexadecimal
+ * value in the form “\#rgb” “\#rrggbb”, “\#rrrgggbbb” or
+ * “\#rrrrggggbbbb” where “r”, “g” and “b” are hex digits of
+ * the red, green, and blue components of the color, respectively.
+ * (White in the four forms is “\#fff”, “\#ffffff”, “\#fffffffff”
+ * and “\#ffffffffffff”).
  *
  * Return value: %TRUE if the parsing succeeded
  */
@@ -163,9 +162,8 @@ gdk_color_parse (const gchar *spec,
  * gdk_color_to_string:
  * @color: a #GdkColor
  *
- * Returns a textual specification of @color in the hexadecimal form
- * `&num;rrrrggggbbbb`, where `r`,
- * `g` and `b` are hex digits
+ * Returns a textual specification of @color in the hexadecimal
+ * form `\#rrrrggggbbbb`, where `r`, `g` and `b` are hex digits
  * representing the red, green and blue components respectively.
  *
  * The returned string can be parsed by gdk_color_parse().
diff --git a/gdk/gdkdevice.c b/gdk/gdkdevice.c
index 1660923..653a0aa 100644
--- a/gdk/gdkdevice.c
+++ b/gdk/gdkdevice.c
@@ -1084,11 +1084,11 @@ gdk_device_get_n_axes (GdkDevice *device)
  * gdk_device_list_axes:
  * @device: a pointer #GdkDevice
  *
- * Returns a #GList of #GdkAtom<!-- -->s, containing the labels for
+ * Returns a #GList of #GdkAtoms, containing the labels for
  * the axes that @device currently has.
  *
  * Returns: (transfer container) (element-type GdkAtom):
- *     A #GList of #GdkAtom<!-- -->s, free with g_list_free().
+ *     A #GList of #GdkAtoms, free with g_list_free().
  *
  * Since: 3.0
  **/
diff --git a/gdk/gdkdevicemanager.c b/gdk/gdkdevicemanager.c
index e9f9679..a056b7a 100644
--- a/gdk/gdkdevicemanager.c
+++ b/gdk/gdkdevicemanager.c
@@ -307,7 +307,7 @@ gdk_device_manager_get_display (GdkDeviceManager *device_manager)
  * @device_manager.
  *
  * Returns: (transfer container) (element-type Gdk.Device): a list of 
- *          #GdkDevice<!-- -->s. The returned list must be
+ *          #GdkDevices. The returned list must be
  *          freed with g_list_free (). The list elements are owned by
  *          GTK+ and must not be freed or unreffed.
  *
diff --git a/gdk/gdkdisplay.c b/gdk/gdkdisplay.c
index 2fd423f..6896197 100644
--- a/gdk/gdkdisplay.c
+++ b/gdk/gdkdisplay.c
@@ -2110,12 +2110,12 @@ static GQueue gdk_error_traps = G_QUEUE_INIT;
  * ## Trapping an X error
  *
  * |[<!-- language="C" -->
- * gdk_error_trap_push (<!-- -->);
+ * gdk_error_trap_push ();
  *
  *  // ... Call the X function which may cause an error here ...
  *
  *
- * if (gdk_error_trap_pop (<!-- -->))
+ * if (gdk_error_trap_pop ())
  *  {
  *    // ... Handle the error here ...
  *  }
diff --git a/gdk/gdkkeys.c b/gdk/gdkkeys.c
index 63e92bf..468241f 100644
--- a/gdk/gdkkeys.c
+++ b/gdk/gdkkeys.c
@@ -495,12 +495,10 @@ gdk_keymap_lookup_key (GdkKeymap          *keymap,
  * @state. For convenience, #GdkEventKey already contains the translated
  * keyval, so this function isn’t as useful as you might think.
  *
- * @consumed_modifiers gives modifiers that should be masked out
- * from @state when comparing this key press to a hot key. For
- * instance, on a US keyboard, the `plus`
- * symbol is shifted, so when comparing a key press to a
- * `&lt;Control&gt;plus` accelerator &lt;Shift&gt; should
- * be masked out.
+ * @consumed_modifiers gives modifiers that should be masked outfrom @state
+ * when comparing this key press to a hot key. For instance, on a US keyboard,
+ * the `plus` symbol is shifted, so when comparing a key press to a
+ * `<Control>plus` accelerator `<Shift>` should be masked out.
  *
  * |[<!-- language="C" -->
  * /&ast; We want to ignore irrelevant modifiers like ScrollLock &ast;/;
@@ -525,16 +523,14 @@ gdk_keymap_lookup_key (GdkKeymap          *keymap,
  * ]|
  *
  * However, this did not work if multi-modifier combinations were
- * used in the keymap, since, for instance, `&lt;Control&gt;`
- * would be masked out even if only `&lt;Control&gt;&lt;Alt&gt;`
- * was used in the keymap. To support this usage as well as well as
- * possible, all single modifier combinations
- * that could affect the key for any combination of modifiers will
- * be returned in @consumed_modifiers; multi-modifier combinations
- * are returned only when actually found in @state. When you store
- * accelerators, you should always store them with consumed modifiers
- * removed. Store `&lt;Control&gt;plus`,
- * not `&lt;Control&gt;&lt;Shift&gt;plus`,
+ * used in the keymap, since, for instance, `<Control>` would be
+ * masked out even if only `<Control><Alt>` was used in the keymap.
+ * To support this usage as well as well as possible, all single
+ * modifier combinations that could affect the key for any combination
+ * of modifiers will be returned in @consumed_modifiers; multi-modifier
+ * combinations are returned only when actually found in @state. When
+ * you store accelerators, you should always store them with consumed
+ * modifiers removed. Store `<Control>plus`, not `<Control><Shift>plus`,
  *
  * Return value: %TRUE if there was a keyval bound to the keycode/state/group
  **/
diff --git a/gdk/gdkrgba.c b/gdk/gdkrgba.c
index d48472e..5f65d15 100644
--- a/gdk/gdkrgba.c
+++ b/gdk/gdkrgba.c
@@ -142,8 +142,8 @@ parse_rgb_value (const gchar  *str,
  *
  * The string can be either one of:
  * - A standard name (Taken from the X11 rgb.txt file).
- * - A hex value in the form “&num;rgb” “&num;rrggbb” “&num;rrrgggbbb”
- *   or “&num;rrrrggggbbbb”
+ * - A hexadecimal value in the form “\#rgb”, “\#rrggbb”,
+ *   “\#rrrgggbbb” or ”\#rrrrggggbbbb”
  * - A RGB color in the form “rgb(r,g,b)” (In this case the color will
  *   have full opacity)
  * - A RGBA color in the form “rgba(r,g,b,a)”
diff --git a/gdk/gdkscreen.c b/gdk/gdkscreen.c
index 2e25af7..fef85cd 100644
--- a/gdk/gdkscreen.c
+++ b/gdk/gdkscreen.c
@@ -1020,7 +1020,7 @@ gdk_screen_get_active_window (GdkScreen *screen)
  * gdk_screen_get_window_stack:
  * @screen: a #GdkScreen
  *
- * Returns a #GList of #GdkWindow<!-- -->s representing the current
+ * Returns a #GList of #GdkWindows representing the current
  * window stack.
  *
  * On X11, this is done by inspecting the _NET_CLIENT_LIST_STACKING
@@ -1037,7 +1037,7 @@ gdk_screen_get_active_window (GdkScreen *screen)
  * its windows unrefed using g_object_unref() when no longer needed.
  *
  * Return value: (transfer full) (element-type GdkWindow):
- *     a list of #GdkWindow<!-- -->s for the current window stack,
+ *     a list of #GdkWindows for the current window stack,
  *               or %NULL.
  *
  * Since: 2.10
diff --git a/gdk/wayland/gdkdisplay-wayland.c b/gdk/wayland/gdkdisplay-wayland.c
index 4859877..c1af8b2 100644
--- a/gdk/wayland/gdkdisplay-wayland.c
+++ b/gdk/wayland/gdkdisplay-wayland.c
@@ -40,10 +40,9 @@
  * @Title: Wayland Interaction
  *
  * The functions in this section are specific to the GDK Wayland backend.
- * To use them, you need to include the `&lt;gdk/gdkwayland.h&gt;`
- * header and use the Wayland-specific pkg-config files to build your
- * application (either `gdk-wayland-3.0` or
- * `gtk+-wayland-3.0`).
+ * To use them, you need to include the `<gdk/gdkwayland.h>` header and use
+ * the Wayland-specific pkg-config files to build your application (either
+ * `gdk-wayland-3.0` or `gtk+-wayland-3.0`).
  *
  * To make your code compile with other GDK backends, guard backend-specific
  * calls by an ifdef as follows. Since GDK may be built with multiple
diff --git a/gdk/x11/gdkmain-x11.c b/gdk/x11/gdkmain-x11.c
index 6447eb1..5f51d1e 100644
--- a/gdk/x11/gdkmain-x11.c
+++ b/gdk/x11/gdkmain-x11.c
@@ -52,10 +52,9 @@
  * @Title: X Window System Interaction
  *
  * The functions in this section are specific to the GDK X11 backend.
- * To use them, you need to include the `&lt;gdk/gdkx.h&gt;`
- * header and use the X11-specific pkg-config files to build your
- * application (either `gdk-x11-3.0` or
- * `gtk+-x11-3.0`).
+ * To use them, you need to include the `<gdk/gdkx.h>` header and use
+ * the X11-specific pkg-config files to build your application (either
+ * `gdk-x11-3.0` or `gtk+-x11-3.0`).
  *
  * To make your code compile with other GDK backends, guard backend-specific
  * calls by an ifdef as follows. Since GDK may be built with multiple
diff --git a/gtk/deprecated/gtkactiongroup.c b/gtk/deprecated/gtkactiongroup.c
index e68f6d5..44bc6d5 100644
--- a/gtk/deprecated/gtkactiongroup.c
+++ b/gtk/deprecated/gtkactiongroup.c
@@ -48,24 +48,23 @@
  *
  * Accelerators are handled by the GTK+ accelerator map. All actions are
  * assigned an accelerator path (which normally has the form
- * `&lt;Actions&gt;/group-name/action-name`)
- * and a shortcut is associated with this accelerator path. All menuitems
- * and toolitems take on this accelerator path. The GTK+ accelerator map
- * code makes sure that the correct shortcut is displayed next to the menu
- * item.
+ * `<Actions>/group-name/action-name`) and a shortcut is associated with
+ * this accelerator path. All menuitems and toolitems take on this accelerator
+ * path. The GTK+ accelerator map code makes sure that the correct shortcut
+ * is displayed next to the menu item.
  *
  * # GtkActionGroup as GtkBuildable # {#GtkActionGroup-BUILDER-UI}
  *
  * The #GtkActionGroup implementation of the #GtkBuildable interface accepts
- * #GtkAction objects as &lt;child&gt; elements in UI definitions.
+ * #GtkAction objects as <child> elements in UI definitions.
  *
  * Note that it is probably more common to define actions and action groups
  * in the code, since they are directly related to what the code can do.
  *
  * The GtkActionGroup implementation of the GtkBuildable interface supports
- * a custom &lt;accelerator&gt; element, which has attributes named key and
- * modifiers and allows to specify accelerators. This is similar to the
- * &lt;accelerator&gt; element of #GtkWidget, the main difference is that
+ * a custom <accelerator> element, which has attributes named “key“ and
+ * “modifiers“ and allows to specify accelerators. This is similar to the
+ * <accelerator> element of #GtkWidget, the main difference is that
  * it doesn’t allow you to specify a signal.
  *
  * ## A #GtkDialog UI definition fragment. ##
@@ -964,8 +963,7 @@ gtk_action_group_add_action (GtkActionGroup *action_group,
  * If @accelerator is %NULL, attempts to use the accelerator associated 
  * with the stock_id of the action. 
  *
- * Accel paths are set to
- * `&lt;Actions&gt;/group-name/action-name`.
+ * Accel paths are set to `<Actions>/group-name/action-name`.
  *
  * Since: 2.4
  *
@@ -1108,9 +1106,8 @@ gtk_action_group_list_actions (GtkActionGroup *action_group)
  * This is a convenience function to create a number of actions and add them 
  * to the action group.
  *
- * The “activate” signals of the actions are connected to the callbacks and
- * their accel paths are set to 
- * `&lt;Actions&gt;/group-name/action-name`.  
+ * The “activate” signals of the actions are connected to the callbacks
+ * and their accel paths are set to `<Actions>/group-name/action-name`.  
  * 
  * Since: 2.4
  *
@@ -1243,9 +1240,8 @@ gtk_action_group_add_actions_full (GtkActionGroup       *action_group,
  * This is a convenience function to create a number of toggle actions and add them 
  * to the action group.
  *
- * The “activate” signals of the actions are connected to the callbacks and
- * their accel paths are set to 
- * `&lt;Actions&gt;/group-name/action-name`.  
+ * The “activate” signals of the actions are connected to the callbacks
+ * and their accel paths are set to `<Actions>/group-name/action-name`.  
  * 
  * Since: 2.4
  *
@@ -1365,7 +1361,7 @@ gtk_action_group_add_toggle_actions_full (GtkActionGroup             *action_gro
  *
  * The “changed” signal of the first radio action is connected to the 
  * @on_change callback and the accel paths of the actions are set to 
- * `&lt;Actions&gt;/group-name/action-name`.  
+ * `<Actions>/group-name/action-name`.  
  * 
  * Since: 2.4
  *
diff --git a/gtk/deprecated/gtkiconfactory.c b/gtk/deprecated/gtkiconfactory.c
index ba5199a..4ee94c7 100644
--- a/gtk/deprecated/gtkiconfactory.c
+++ b/gtk/deprecated/gtkiconfactory.c
@@ -72,9 +72,8 @@
  *
  * # GtkIconFactory as GtkBuildable # {#GtkIconFactory-BUILDER-UI}
  *
- * GtkIconFactory supports a custom &lt;sources&gt; element, which can contain
- * multiple &lt;source&gt; elements.
- * The following attributes are allowed:
+ * GtkIconFactory supports a custom <sources> element, which can contain
+ * multiple <source> elements. The following attributes are allowed:
  *
  * - stock-id
  *
diff --git a/gtk/deprecated/gtkrc.c b/gtk/deprecated/gtkrc.c
index bb05861..4e7a0b7 100644
--- a/gtk/deprecated/gtkrc.c
+++ b/gtk/deprecated/gtkrc.c
@@ -134,18 +134,18 @@
  * the class name of the widget, while for the class path, the class name is
  * always used.
  *
- * Since GTK+ 2.10, `widget_class` paths can also contain
- * `&lt;classname&gt;` substrings, which are matching
- * the class with the given name and any derived classes. For instance,
+ * Since GTK+ 2.10, `widget_class` paths can also contain <classname>
+ * substrings, which are matching the class with the given name and any
+ * derived classes. For instance,
  * |[
- * widget_class "*&lt;GtkMenuItem&gt;.GtkLabel" style "my-style"
+ * widget_class "*<GtkMenuItem>.GtkLabel" style "my-style"
  * ]|
  * will match #GtkLabel widgets which are contained in any kind of menu item.
  *
- * So, if you have a #GtkEntry named `"myentry"`, inside of a
- * horizontal box in a window named `"mywindow"`, then the
- * widget path is: `"mywindow.GtkHBox.myentry"`
- * while the class path is: `"GtkWindow.GtkHBox.GtkEntry"`.
+ * So, if you have a #GtkEntry named `"myentry"`, inside of a horizontal
+ * box in a window named `"mywindow"`, then the widget path is:
+ * `"mywindow.GtkHBox.myentry"` while the class path is:
+ * `"GtkWindow.GtkHBox.GtkEntry"`.
  *
  * Matching against class is a little different. The pattern match is done
  * against all class names in the widgets class hierarchy (not the layout
@@ -372,12 +372,11 @@
  * * `bg_pixmap[state] =
  *       pixmap`
  *
- *          Sets a background pixmap to be used in place of
- *          the `bg` color (or for #GtkText,
- *          in place of the `base` color. The special
- *          value `"&lt;parent&gt;"` may be used to indicate that the widget should
+ *          Sets a background pixmap to be used in place of the `bg` color
+ *          (or for #GtkText, in place of the `base` color. The special
+ *          value `"<parent>"` may be used to indicate that the widget should
  *          use the same background pixmap as its parent. The special value
- *          `"&lt;none&gt;"` may be used to indicate no background pixmap.
+ *          `"<none>"` may be used to indicate no background pixmap.
 
  * * `font = font`
  *
@@ -578,54 +577,46 @@
  * }
  * ]|
  *
- * `key` is a string consisting of a
- * series of modifiers followed by the name of a key. The
- * modifiers can be:
+ * `key` is a string consisting of a series of modifiers followed by
+ * the name of a key. The modifiers can be:
  *
- * - `&lt;alt&gt;`
+ * - `<alt>`
  *
- * - `&lt;ctl&gt;`
+ * - `<ctl>`
  *
- * - `&lt;control&gt;`
+ * - `<control>`
  *
- * - `&lt;meta&gt;`
+ * - `<meta>`
  *
- * - `&lt;hyper&gt;`
+ * - `<hyper>`
  *
- * - `&lt;super&gt;`
+ * - `<super>`
  *
- * - `&lt;mod1&gt;`
+ * - `<mod1>`
  *
- * - `&lt;mod2&gt;`
+ * - `<mod2>`
  *
- * - `&lt;mod3&gt;`
+ * - `<mod3>`
  *
- * - `&lt;mod4&gt;`
+ * - `<mod4>`
  *
- * - `&lt;mod5&gt;`
+ * - `<mod5>`
  *
- * - `&lt;release&gt;`
+ * - `<release>`
  *
- * - `&lt;shft&gt;`
+ * - `<shft>`
  *
- * - `&lt;shift&gt;`
+ * - `<shift>`
  *
- * `&lt;shft&gt;` is an alias for
- * `&lt;shift&gt;`,
- * `&lt;ctl&gt;` is an alias for
- * `&lt;control&gt;`,
- *  and
- * `&lt;alt&gt;` is an alias for
- * `&lt;mod1&gt;`.
+ * `<shft>` is an alias for `<shift>`, `<ctl>` is an alias for
+ * `<control>`, and `<alt>` is an alias for `<mod1>`.
  *
- * The action that is bound to the key is a sequence
- * of signal names (strings) followed by parameters for
- * each signal. The signals must be action signals.
- * (See g_signal_new()). Each parameter can be
- * a float, integer, string, or unquoted string
- * representing an enumeration value. The types of
- * the parameters specified must match the types of the
- * parameters of the signal.
+ * The action that is bound to the key is a sequence of signal names
+ * (strings) followed by parameters for each signal. The signals must
+ * be action signals. (See g_signal_new()). Each parameter can be a
+ * float, integer, string, or unquoted string representing an enumeration
+ * value. The types of the parameters specified must match the types of
+ * the parameters of the signal.
  *
  * Binding sets are connected to widgets in the same manner as styles,
  * with one difference: Binding sets override other binding sets first
diff --git a/gtk/deprecated/gtkrecentaction.c b/gtk/deprecated/gtkrecentaction.c
index f61dfa9..d021e34 100644
--- a/gtk/deprecated/gtkrecentaction.c
+++ b/gtk/deprecated/gtkrecentaction.c
@@ -41,9 +41,9 @@
  * #GtkRecentChooserMenu.
  *
  * To construct a submenu showing recently used files, use a #GtkRecentAction
- * as the action for a &lt;menuitem&gt;. To construct a menu toolbutton showing
+ * as the action for a <menuitem>. To construct a menu toolbutton showing
  * the recently used files in the popup menu, use a #GtkRecentAction as the
- * action for a &lt;toolitem&gt; element.
+ * action for a <toolitem> element.
  */
 
 
diff --git a/gtk/deprecated/gtkuimanager.c b/gtk/deprecated/gtkuimanager.c
index 69f89e3..9ae6c78 100644
--- a/gtk/deprecated/gtkuimanager.c
+++ b/gtk/deprecated/gtkuimanager.c
@@ -205,10 +205,10 @@
  *
  * # Accelerators #
  *
- * Every action has an accelerator path. Accelerators are installed together with
- * menuitem proxies, but they can also be explicitly added with &lt;accelerator&gt;
- * elements in the UI definition. This makes it possible to have accelerators for
- * actions even if they have no visible proxies.
+ * Every action has an accelerator path. Accelerators are installed together
+ * with menuitem proxies, but they can also be explicitly added with
+ * <accelerator> elements in the UI definition. This makes it possible to
+ * have accelerators for actions even if they have no visible proxies.
  *
  * # Smart Separators # {#Smart-Separators}
  *
@@ -240,10 +240,10 @@
  * # GtkUIManager as GtkBuildable # {#GtkUIManager-BUILDER-UI}
  *
  * The GtkUIManager implementation of the GtkBuildable interface accepts
- * GtkActionGroup objects as &lt;child&gt; elements in UI definitions.
+ * GtkActionGroup objects as <child> elements in UI definitions.
  *
  * A GtkUIManager UI definition as described above can be embedded in
- * an GtkUIManager &lt;object&gt; element in a GtkBuilder UI definition.
+ * an GtkUIManager <object> element in a GtkBuilder UI definition.
  *
  * The widgets that are constructed by a GtkUIManager can be embedded in
  * other parts of the constructed user interface with the help of the
@@ -1093,19 +1093,20 @@ gtk_ui_manager_get_accel_group (GtkUIManager *manager)
  * Looks up a widget by following a path. 
  * The path consists of the names specified in the XML description of the UI. 
  * separated by “/”. Elements which don’t have a name or action attribute in 
- * the XML (e.g. &lt;popup&gt;) can be addressed by their XML element name 
+ * the XML (e.g. <popup>) can be addressed by their XML element name 
  * (e.g. "popup"). The root element ("/ui") can be omitted in the path.
  *
- * Note that the widget found by following a path that ends in a &lt;menu&gt;
- * element is the menuitem to which the menu is attached, not the menu itmanager.
+ * Note that the widget found by following a path that ends in a <menu>;
+ * element is the menuitem to which the menu is attached, not the menu it
+ * manages.
  *
  * Also note that the widgets constructed by a ui manager are not tied to 
  * the lifecycle of the ui manager. If you add the widgets returned by this 
  * function to some container or explicitly ref them, they will survive the
  * destruction of the ui manager.
  *
- * Return value: (transfer none): the widget found by following the path, or %NULL if no widget
- *   was found.
+ * Return value: (transfer none): the widget found by following the path,
+ *     or %NULL if no widget was found
  *
  * Since: 2.4
  *
@@ -1932,9 +1933,9 @@ add_ui_from_string (GtkUIManager *manager,
  * @length: the length of @buffer (may be -1 if @buffer is nul-terminated)
  * @error: return location for an error
  * 
- * Parses a string containing a [UI definition][XML-UI] and 
- * merges it with the current contents of @manager. An enclosing &lt;ui&gt; 
- * element is added if it is missing.
+ * Parses a string containing a [UI definition][XML-UI] and merges it with
+ * the current contents of @manager. An enclosing <ui> element is added if
+ * it is missing.
  * 
  * Return value: The merge id for the merged UI. The merge id can be used
  *   to unmerge the UI with gtk_ui_manager_remove_ui(). If an error occurred,
diff --git a/gtk/gtkaboutdialog.c b/gtk/gtkaboutdialog.c
index 19b7277..e909503 100644
--- a/gtk/gtkaboutdialog.c
+++ b/gtk/gtkaboutdialog.c
@@ -79,11 +79,11 @@
  * use the function gtk_show_about_dialog() which constructs and shows a dialog
  * and keeps it around so that it can be shown again.
  *
- * Note that GTK+ sets a default title of `_("About &percnt;s")`
- * on the dialog window (where &percnt;s is replaced by the name of the
- * application, but in order to ensure proper translation of the title,
- * applications should set the title property explicitly when constructing
- * a GtkAboutDialog, as shown in the following example:
+ * Note that GTK+ sets a default title of `_("About \%s")` on the dialog
+ * window (where \%s is replaced by the name of the application, but in
+ * order to ensure proper translation of the title, applications should
+ * set the title property explicitly when constructing a GtkAboutDialog,
+ * as shown in the following example:
  * |[<!-- language="C" -->
  * gtk_show_about_dialog (NULL,
  *                        "program-name", "ExampleCode",
diff --git a/gtk/gtkaccelgroup.c b/gtk/gtkaccelgroup.c
index baa74b4..7eaf8a9 100644
--- a/gtk/gtkaccelgroup.c
+++ b/gtk/gtkaccelgroup.c
@@ -1441,15 +1441,15 @@ out:
  * @accelerator_mods: (out) (allow-none): return location for accelerator
  *     modifier mask, %NULL
  *
- * Parses a string representing an accelerator. The
- * format looks like “&lt;Control&gt;a” or “&lt;Shift&gt;&lt;Alt&gt;F1”
- * or “&lt;Release&gt;z” (the last one is for key release).
+ * Parses a string representing an accelerator. The format looks like
+ * “<Control>a” or “<Shift><Alt>F1” or “<Release>z” (the last one is
+ * for key release).
  *
- * The parser is fairly liberal and allows lower or upper case,
- * and also abbreviations such as “&lt;Ctl&gt;” and “&lt;Ctrl&gt;”.
- * Key names are parsed using gdk_keyval_from_name(). For character
- * keys the name is not the symbol, but the lowercase name, e.g. one
- * would use “&lt;Ctrl&gt;minus” instead of “&lt;Ctrl&gt;-”.
+ * The parser is fairly liberal and allows lower or upper case, and also
+ * abbreviations such as “<Ctl>” and “<Ctrl>”. Key names are parsed using
+ * gdk_keyval_from_name(). For character keys the name is not the symbol,
+ * but the lowercase name, e.g. one would use “<Ctrl>minus” instead of
+ * “<Ctrl>-”.
  *
  * If the parse fails, @accelerator_key and @accelerator_mods will
  * be set to 0 (zero).
@@ -1509,10 +1509,9 @@ gtk_accelerator_name_with_keycode (GdkDisplay      *display,
  * @accelerator_key: accelerator keyval
  * @accelerator_mods: accelerator modifier mask
  *
- * Converts an accelerator keyval and modifier mask
- * into a string parseable by gtk_accelerator_parse().
- * For example, if you pass in #GDK_KEY_q and #GDK_CONTROL_MASK,
- * this function returns “&lt;Control&gt;q”.
+ * Converts an accelerator keyval and modifier mask into a string
+ * parseable by gtk_accelerator_parse(). For example, if you pass in
+ * #GDK_KEY_q and #GDK_CONTROL_MASK, this function returns “<Control>q”.
  *
  * If you need to display accelerators in the user interface,
  * see gtk_accelerator_get_label().
diff --git a/gtk/gtkaccellabel.c b/gtk/gtkaccellabel.c
index 71a53a2..462aeac 100644
--- a/gtk/gtkaccellabel.c
+++ b/gtk/gtkaccellabel.c
@@ -72,19 +72,21 @@
  *   GtkWidget *save_item;
  *   GtkAccelGroup *accel_group;
  *
- *   /<!---->* Create a GtkAccelGroup and add it to the window. *<!---->/
- *   accel_group = gtk_accel_group_new (<!-- -->);
+ *   /&ast; Create a GtkAccelGroup and add it to the window. &ast;/
+ *   accel_group = gtk_accel_group_new ();
  *   gtk_window_add_accel_group (GTK_WINDOW (window), accel_group);
  *
- *   /<!---->* Create the menu item using the convenience function. *<!---->/
+ *   /&ast; Create the menu item using the convenience function. &ast;/
  *   save_item = gtk_menu_item_new_with_label ("Save");
  *   gtk_widget_show (save_item);
  *   gtk_container_add (GTK_CONTAINER (menu), save_item);
  *
- *   /<!---->* Now add the accelerator to the GtkMenuItem. Note that since we called
- *      gtk_menu_item_new_with_label(<!-- -->) to create the GtkMenuItem the
- *      GtkAccelLabel is automatically set up to display the GtkMenuItem
- *      accelerators. We just need to make sure we use GTK_ACCEL_VISIBLE here. *<!---->/
+ *   /&ast; Now add the accelerator to the GtkMenuItem. Note that since we
+ *    &ast; called gtk_menu_item_new_with_label() to create the GtkMenuItem
+ *    &ast; the GtkAccelLabel is automatically set up to display the
+ *    &ast; GtkMenuItem accelerators. We just need to make sure we use
+ *    &ast; GTK_ACCEL_VISIBLE here.
+ *    &ast;/
  *   gtk_widget_add_accelerator (save_item, "activate", accel_group,
  *                               GDK_KEY_s, GDK_CONTROL_MASK, GTK_ACCEL_VISIBLE);
  * ]|
diff --git a/gtk/gtkaccelmap.c b/gtk/gtkaccelmap.c
index de6d54a..0cfef38 100644
--- a/gtk/gtkaccelmap.c
+++ b/gtk/gtkaccelmap.c
@@ -54,7 +54,7 @@
  * - accelerator modifiers
  *
  * The accelerator path must consist of
- * “&lt;WINDOWTYPE&gt;/Category1/Category2/.../Action”, where WINDOWTYPE
+ * “<WINDOWTYPE>/Category1/Category2/.../Action”, where WINDOWTYPE
  * should be a unique application-specific identifier that corresponds
  * to the kind of window the accelerator is being used in, e.g.
  * “Gimp-Image”, “Abiword-Document” or “Gnumeric-Settings”.
@@ -62,7 +62,7 @@
  * the action the accelerator triggers, i.e. for accelerators on menu
  * items, choose the item’s menu path, e.g. “File/Save As”,
  * “Image/View/Zoom” or “Edit/Select All”. So a full valid accelerator
- * path may look like: “&lt;Gimp-Toolbox&gt;/File/Dialogs/Tool Options...”.
+ * path may look like: “<Gimp-Toolbox>/File/Dialogs/Tool Options...”.
  *
  * All accelerators are stored inside one global #GtkAccelMap that can
  * be obtained using gtk_accel_map_get(). See
diff --git a/gtk/gtkapplication.c b/gtk/gtkapplication.c
index 8fb8030..a40883b 100644
--- a/gtk/gtkapplication.c
+++ b/gtk/gtkapplication.c
@@ -1073,9 +1073,8 @@ gtk_application_update_accels (GtkApplication *application)
  * to be activated when the key combination specificed by @accelerator
  * is pressed.
  *
- * @accelerator must be a string that can be parsed by
- * gtk_accelerator_parse(), e.g. "&lt;Primary&gt;q" or
- * “&lt;Control&gt;&lt;Alt&gt;p”.
+ * @accelerator must be a string that can be parsed by gtk_accelerator_parse(),
+ * e.g. "<Primary>q" or “<Control><Alt>p”.
  *
  * @action_name must be the name of an action as it would be used
  * in the app menu, i.e. actions that have been added to the application
diff --git a/gtk/gtkapplicationwindow.c b/gtk/gtkapplicationwindow.c
index d740121..67da6be 100644
--- a/gtk/gtkapplicationwindow.c
+++ b/gtk/gtkapplicationwindow.c
@@ -107,20 +107,17 @@
  * [A simple example](https://git.gnome.org/browse/gtk+/tree/examples/sunny.c)
  *
  * The XML format understood by #GtkBuilder for #GMenuModel consists
- * of a toplevel `&lt;menu&gt;` element, which contains
- * one or more `&lt;item&gt;` elements. Each
- * `&lt;item&gt;` element contains
- * `&lt;attribute&gt;` and `&lt;link&gt;`
- * elements with a mandatory name attribute.
- * `&lt;link&gt;` elements have the same content
- * model as `&lt;menu&gt;`.
+ * of a toplevel `<menu>` element, which contains one or more `<item>`
+ * elements. Each `<item>` element contains `<attribute>` and `<link>`
+ * elements with a mandatory name attribute. `<link>` elements have the
+ * same content model as `<menu>`.
  *
  * Attribute values can be translated using gettext, like other #GtkBuilder
- * content. `&lt;attribute&gt;` elements can be marked for
- * translation with a `translatable="yes"` attribute.
- * It is also possible to specify message context and translator comments,
- * using the context and comments attributes. To make use of this, the
- * #GtkBuilder must have been given the gettext domain to use.
+ * content. `<attribute>` elements can be marked for translation with a
+ * `translatable="yes"` attribute. It is also possible to specify message
+ * context and translator comments,using the context and comments attributes.
+ * To make use of this, the #GtkBuilder must have been given the gettext
+ * domain to use.
  */
 
 typedef GSimpleActionGroupClass GtkApplicationWindowActionsClass;
diff --git a/gtk/gtkbindings.c b/gtk/gtkbindings.c
index 18a17f5..1741bc1 100644
--- a/gtk/gtkbindings.c
+++ b/gtk/gtkbindings.c
@@ -104,15 +104,15 @@
  * ]|
  *
  * The above example will not have the desired effect of causing
- * “&lt;Control&gt;Right” and “&lt;Control&gt;Left” key presses to
- * be ignored by GTK+. Instead, it just causes any existing bindings
- * from the bindings set “MoveCursor3” to be deleted, so when
- * “&lt;Control&gt;Right” or “&lt;Control&gt;Left” are pressed, no
- * binding for these keys is found in binding set “MoveCursor3”.
- * GTK+ will thus continue to search for matching key bindings, and
- * will eventually lookup and find the default GTK+ bindings for
- * entries which implement word movement. To keep GTK+ from activating
- * its default bindings, the “unbind” keyword can be used like this:
+ * “<Control>Right” and “<Control>Left” key presses to be ignored by GTK+.
+ * Instead, it just causes any existing bindings from the bindings set
+ * “MoveCursor3” to be deleted, so when “<Control>Right” or
+ * “<Control>Left” are pressed, no binding for these keys is found in
+ * binding set “MoveCursor3”. GTK+ will thus continue to search for
+ * matching key bindings, and will eventually lookup and find the default
+ * GTK+ bindings for entries which implement word movement. To keep GTK+
+ * from activating its default bindings, the “unbind” keyword can be used
+ * like this:
  *
  * |[
  * @binding-set MoveCursor3
@@ -126,12 +126,11 @@
  * }
  * ]|
  *
- * Now, GTK+ will find a match when looking up “&lt;Control&gt;Right”
- * and “&lt;Control&gt;Left” key presses before it resorts to its default
- * bindings, and the match instructs it to abort (“unbind”) the search,
- * so the key presses are not consumed by this widget. As usual, further
- * processing of the key presses, e.g. by an entry’s parent widget, is
- * now possible.
+ * Now, GTK+ will find a match when looking up “<Control>Right” and
+ * “<Control>Left” key presses before it resorts to its default bindings,
+ * and the match instructs it to abort (“unbind”) the search, so the key
+ * presses are not consumed by this widget. As usual, further processing
+ * of the key presses, e.g. by an entry’s parent widget, is now possible.
  */
 
 /* --- defines --- */
diff --git a/gtk/gtkbuildable.c b/gtk/gtkbuildable.c
index 6aff915..d16e008 100644
--- a/gtk/gtkbuildable.c
+++ b/gtk/gtkbuildable.c
@@ -236,7 +236,7 @@ gtk_buildable_construct_child (GtkBuildable *buildable,
  * @data: (out): return location for user data that will be passed in 
  *   to parser functions
  *
- * This is called for each unknown element under &lt;child&gt;.
+ * This is called for each unknown element under <child>.
  * 
  * Returns: %TRUE if a object has a custom implementation, %FALSE
  *          if it doesn't.
diff --git a/gtk/gtkbuilder.c b/gtk/gtkbuilder.c
index ea5fd76..3efe9e9 100644
--- a/gtk/gtkbuilder.c
+++ b/gtk/gtkbuilder.c
@@ -71,33 +71,32 @@
  *
  * [RELAX NG Compact Syntax](https://git.gnome.org/browse/gtk+/tree/gtk/gtkbuilder.rnc)
  *
- * The toplevel element is &lt;interface&gt;. It optionally takes a
- * “domain” attribute, which will make the builder look for translated
- * strings using dgettext() in the domain specified. This can also be
- * done by calling gtk_builder_set_translation_domain() on the builder.
- * Objects are described by &lt;object&gt; elements, which can contain
- * &lt;property&gt; elements to set properties, &lt;signal&gt; elements
- * which connect signals to handlers, and &lt;child&gt; elements, which
- * describe child objects (most often widgets inside a container, but
- * also e.g. actions in an action group, or columns in a tree model).
- * A &lt;child&gt; element contains an &lt;object&gt; element which
- * describes the child object. The target toolkit version(s) are
- * described by &lt;requires&gt; elements, the “lib” attribute specifies
- * the widget library in question (currently the only supported value 
- * s “gtk+”) and the “version” attribute specifies the target version
- * in the form “&lt;major&gt;.&lt;minor&gt;”. The builder will error
+ * The toplevel element is <interface>. It optionally takes a “domain”
+ * attribute, which will make the builder look for translated strings
+ * using dgettext() in the domain specified. This can also be done by
+ * calling gtk_builder_set_translation_domain() on the builder.
+ * Objects are described by <object> elements, which can contain
+ * <property> elements to set properties, <signal> elements which
+ * connect signals to handlers, and <child> elements, which describe
+ * child objects (most often widgets inside a container, but also e.g.
+ * actions in an action group, or columns in a tree model). A <child>
+ * element contains an <object> element which describes the child object.
+ * The target toolkit version(s) are described by <requires> elements,
+ * the “lib” attribute specifies the widget library in question (currently
+ * the only supported value is “gtk+”) and the “version” attribute specifies
+ * the target version in the form “<major>.<minor>”. The builder will error
  * out if the version requirements are not met.
  *
- * Typically, the specific kind of object represented by an &lt;object&gt;
- * element is specified by the “class” attribute. If the type has not been
- * loaded yet, GTK+ tries to find the get_type() function from the
- * class name by applying heuristics. This works in most cases, but
- * if necessary, it is possible to specify the name of the
- * get_type() function explictly with the "type-func" attribute.
- * As a special case, GtkBuilder allows to use an object that has been
- * constructed by a #GtkUIManager in another part of the UI definition
- * by specifying the id of the #GtkUIManager in the “constructor”
- * attribute and the name of the object in the “id” attribute.
+ * Typically, the specific kind of object represented by an <object>
+ * element is specified by the “class” attribute. If the type has not
+ * been loaded yet, GTK+ tries to find the get_type() function from the
+ * class name by applying heuristics. This works in most cases, but if
+ * necessary, it is possible to specify the name of the get_type() function
+ * explictly with the "type-func" attribute. As a special case, GtkBuilder
+ * allows to use an object that has been constructed by a #GtkUIManager in
+ * another part of the UI definition by specifying the id of the #GtkUIManager
+ * in the “constructor” attribute and the name of the object in the “id”
+ * attribute.
  *
  * Objects may be given a name with the “id” attribute, which allows the
  * application to retrieve them from the builder with gtk_builder_get_object().
@@ -106,8 +105,8 @@
  * with ___ (3 underscores) for its own purposes.
  *
  * Setting properties of objects is pretty straightforward with the
- * &lt;property&gt; element: the “name” attribute specifies the name
- * of the property, and the content of the element specifies the value.
+ * <property> element: the “name” attribute specifies the name of the
+ * property, and the content of the element specifies the value.
  * If the “translatable” attribute is set to a true value, GTK+ uses
  * gettext() (or dgettext() if the builder has a translation domain set)
  * to find a translation for the value. This happens before the value
@@ -135,11 +134,11 @@
  * object has to be constructed before it can be used as the value of
  * a construct-only property.
  *
- * Signal handlers are set up with the &lt;signal&gt; element. The
- * “name” attribute specifies the name of the signal, and the “handler”
- * attribute specifies the function to connect to the signal. By default,
- * GTK+ tries to find the handler using g_module_symbol(), but this can
- * be changed by passing a custom #GtkBuilderConnectFunc to
+ * Signal handlers are set up with the <signal> element. The “name”
+ * attribute specifies the name of the signal, and the “handler” attribute
+ * specifies the function to connect to the signal. By default, GTK+ tries
+ * to find the handler using g_module_symbol(), but this can be changed by
+ * passing a custom #GtkBuilderConnectFunc to
  * gtk_builder_connect_signals_full(). The remaining attributes, “after”,
  * “swapped” and “object”, have the same meaning as the corresponding
  * parameters of the g_signal_connect_object() or
@@ -151,13 +150,13 @@
  * been constructed by GTK+ as part of a composite widget, to set
  * properties on them or to add further children (e.g. the @vbox of
  * a #GtkDialog). This can be achieved by setting the “internal-child”
- * propery of the &lt;child&gt; element to a true value. Note that
- * GtkBuilder still requires an &lt;object&gt; element for the internal
- * child, even if it has already been constructed.
+ * propery of the <child> element to a true value. Note that GtkBuilder
+ * still requires an <object> element for the internal child, even if it
+ * has already been constructed.
  *
  * A number of widgets have different places where a child can be added
  * (e.g. tabs vs. page content in notebooks). This can be reflected in
- * a UI definition by specifying the “type” attribute on a &lt;child&gt;.
+ * a UI definition by specifying the “type” attribute on a <child>
  * The possible values for the “type” attribute are described in the
  * sections describing the widget-specific portions of UI definitions.
  *
@@ -189,16 +188,15 @@
  *
  * Beyond this general structure, several object classes define their
  * own XML DTD fragments for filling in the ANY placeholders in the DTD
- * above. Note that a custom element in a &lt;child&gt; element gets
- * parsed by the custom tag handler of the parent object, while a custom
- * element in an &lt;object&gt; element gets parsed by the custom tag
- * handler of the object.
+ * above. Note that a custom element in a <child> element gets parsed by
+ * the custom tag handler of the parent object, while a custom element in
+ * an <object> element gets parsed by the custom tag handler of the object.
  *
  * These XML fragments are explained in the documentation of the
  * respective objects.
  *
- * Additionally, since 3.10 a special &lt;template&gt; tag has been
- * added to the format allowing one to define a widget class’s components.
+ * Additionally, since 3.10 a special <template> tag has been added
+ * to the format allowing one to define a widget class’s components.
  */
 
 #include "config.h"
diff --git a/gtk/gtkcelllayout.c b/gtk/gtkcelllayout.c
index 0f678ce..8aa89c4 100644
--- a/gtk/gtkcelllayout.c
+++ b/gtk/gtkcelllayout.c
@@ -39,11 +39,11 @@
  * Implementations of GtkCellLayout which also implement the GtkBuildable
  * interface (#GtkCellView, #GtkIconView, #GtkComboBox,
  * #GtkEntryCompletion, #GtkTreeViewColumn) accept GtkCellRenderer objects
- * as &lt;child&gt; elements in UI definitions. They support a custom
- * &lt;attributes&gt; element for their children, which can contain
- * multiple &lt;attribute&gt; elements. Each &lt;attribute&gt; element has
- * a name attribute which specifies a property of the cell renderer; the
- * content of the element is the attribute value.
+ * as <child> elements in UI definitions. They support a custom <attributes>
+ * element for their children, which can contain multiple <attribute>
+ * elements. Each <attribute> element has a name attribute which specifies
+ * a property of the cell renderer; the content of the element is the
+ * attribute value.
  *
  * This is an example of a UI definition fragment specifying attributes:
  * |[
@@ -57,12 +57,11 @@
  * </object>
  * ]|
  *
- * Furthermore for implementations of GtkCellLayout that use a
- * #GtkCellArea to lay out cells (all GtkCellLayouts in GTK+ use
- * a GtkCellArea) [cell properties][cell-properties]
- * can also be defined in the format by specifying the custom
- * &lt;cell-packing&gt; attribute which can contain multiple
- * &lt;property&gt; elements defined in the normal way.
+ * Furthermore for implementations of GtkCellLayout that use a #GtkCellArea
+ * to lay out cells (all GtkCellLayouts in GTK+ use a GtkCellArea)
+ * [cell properties][cell-properties] can also be defined in the format by
+ * specifying the custom <cell-packing> attribute which can contain multiple
+ * <property> elements defined in the normal way.
  *
  * Here is a UI definition fragment specifying cell properties:
  *
diff --git a/gtk/gtkcombobox.c b/gtk/gtkcombobox.c
index 752b435..cd5dca9 100644
--- a/gtk/gtkcombobox.c
+++ b/gtk/gtkcombobox.c
@@ -640,7 +640,7 @@ gtk_combo_box_class_init (GtkComboBoxClass *klass)
    *                       THE_DOUBLE_VALUE_COLUMN, &value,
    *                       -1);
    *
-   *   return g_strdup_printf ("&percnt;g", value);
+   *   return g_strdup_printf ("%g", value);
    * }
    * ]|
    *
@@ -2379,7 +2379,7 @@ gtk_combo_box_popup (GtkComboBox *combo_box)
  *
  * Pops up the menu or dropdown list of @combo_box, the popup window
  * will be grabbed so only @device and its associated pointer/keyboard
- * are the only #GdkDevice<!-- -->s able to send events to it.
+ * are the only #GdkDevices able to send events to it.
  *
  * Since: 3.0
  **/
diff --git a/gtk/gtkcomboboxtext.c b/gtk/gtkcomboboxtext.c
index f3d120b..f07a186 100644
--- a/gtk/gtkcomboboxtext.c
+++ b/gtk/gtkcomboboxtext.c
@@ -54,14 +54,13 @@
  *
  * # GtkComboBoxText as GtkBuildable
  *
- * The GtkComboBoxText implementation of the GtkBuildable interface
- * supports adding items directly using the &lt;items&gt; element
- * and specifying &lt;item&gt; elements for each item. Each &lt;item&gt;
- * element can specify the “id” corresponding to the appended text and
- * also supports the regular translation attributes “translatable”,
- * “context” and “comments”.
- *
- * Here is a a UI definition fragment specifying GtkComboBoxText items:
+ * The GtkComboBoxText implementation of the GtkBuildable interface supports
+ * adding items directly using the <items> element and specifying <item>
+ * elements for each item. Each <item> element can specify the “id”
+ * corresponding to the appended text and also supports the regular
+ * translation attributes “translatable”, “context” and “comments”.
+ *
+ * Here is a UI definition fragment specifying GtkComboBoxText items:
  * |[
  * <object class="GtkComboBoxText">
  *   <items>
diff --git a/gtk/gtkcontainer.c b/gtk/gtkcontainer.c
index b0a761b..6837c48 100644
--- a/gtk/gtkcontainer.c
+++ b/gtk/gtkcontainer.c
@@ -202,10 +202,9 @@
  *
  * # GtkContainer as GtkBuildable
  *
- * The GtkContainer implementation of the GtkBuildable interface
- * supports a &lt;packing&gt; element for children, which can
- * contain multiple &lt;property&gt; elements that specify
- * child properties for the child.
+ * The GtkContainer implementation of the GtkBuildable interface supports
+ * a <packing> element for children, which can contain multiple <property>
+ * elements that specify child properties for the child.
  * 
  * An example of child properties in UI definitions:
  * |[
diff --git a/gtk/gtkcsscustomproperty.c b/gtk/gtkcsscustomproperty.c
index 457e1f8..69274dc 100644
--- a/gtk/gtkcsscustomproperty.c
+++ b/gtk/gtkcsscustomproperty.c
@@ -193,7 +193,7 @@ gtk_css_custom_property_create_initial_value (GParamSpec *pspec)
  * Engines must ensure property registration happens exactly once,
  * usually GTK+ deals with theming engines as singletons, so this
  * should be guaranteed to happen once, but bear this in mind
- * when creating #GtkThemeEngine<!-- -->s yourself.
+ * when creating #GtkThemeEngines yourself.
  *
  * In order to make use of the custom registered properties in
  * the CSS file, make sure the engine is loaded first by specifying
diff --git a/gtk/gtkcssprovider.c b/gtk/gtkcssprovider.c
index c0a592d..fe9be91 100644
--- a/gtk/gtkcssprovider.c
+++ b/gtk/gtkcssprovider.c
@@ -96,14 +96,14 @@
  * Selectors work very similar to the way they do in CSS, with widget class
  * names taking the role of element names, and widget names taking the role
  * of IDs. When used in a selector, widget names must be prefixed with a
- * '&num;' character. The “*” character represents the so-called universal
+ * '#' character. The “*” character represents the so-called universal
  * selector, which matches any widget.
  *
  * To express more complicated situations, selectors can be combined in
  * various ways:
  * - To require that a widget satisfies several conditions,
  *   combine several selectors into one by concatenating them. E.g.
- *   `GtkButton&num;button1` matches a GtkButton widget
+ *   `GtkButton\#button1` matches a GtkButton widget
  *   with the name button1.
  * - To only match a widget when it occurs inside some other
  *   widget, write the two selectors after each other, separated by whitespace.
@@ -267,18 +267,18 @@
  * whose selectors more closely match a widget path will take precedence
  * over the others.
  *
- * # &commat; Rules
+ * # @ Rules
  *
- * GTK+’s CSS supports the &commat;import rule, in order to load another
+ * GTK+’s CSS supports the \ import rule, in order to load another
  * CSS style sheet in addition to the currently parsed one.
  *
- * An example for using the &commat;import rule:
+ * An example for using the \ import rule:
  * |[
  * @import url ("path/to/common.css");
  * ]|
  * 
  * In order to extend key bindings affecting different widgets, GTK+
- * supports the &commat;binding-set rule to parse a set of bind/unbind
+ * supports the \ binding-set rule to parse a set of bind/unbind
  * directives, see #GtkBindingSet for the supported syntax. Note that
  * the binding sets defined in this way must be associated with rule sets
  * by setting the gtk-key-bindings style property.
@@ -288,7 +288,7 @@
  * according to the current key theme, which is defined by the
  * #GtkSettings:gtk-key-theme-name setting.
  *
- * An example for using the &commat;binding rule:
+ * An example for using the \ binding rule:
  * |[
  * @binding-set binding-set1 {
  *   bind "<alt>Left" { "move-cursor" (visual-positions, -3, 0) };
@@ -306,7 +306,7 @@
  * }
  * ]|
  *
- * GTK+ also supports an additional &commat;define-color rule, in order
+ * GTK+ also supports an additional \ define-color rule, in order
  * to define a color name which may be used instead of color numeric
  * representations. Also see the #GtkSettings:gtk-color-scheme setting
  * for a way to override the values of these named colors.
@@ -367,7 +367,7 @@
  *   color: rgb(128, 10, 54, 0.5);
  * ]|
  *
- * ## &num;xxyyzz
+ * ## \#xxyyzz
  *
  * An opaque color.
  *
@@ -380,9 +380,9 @@
  *   border-color: #ffff0000cccc;
  * ]|
  *
- * ## &commat;name
+ * ## \ name
  *
- * Reference to a color that has been defined with &commat;define-color
+ * Reference to a color that has been defined with \ define-color
  *
  * |[
  *   color: @bg_color;
diff --git a/gtk/gtkdialog.c b/gtk/gtkdialog.c
index 6b0cc75..ed8bc08 100644
--- a/gtk/gtkdialog.c
+++ b/gtk/gtkdialog.c
@@ -135,10 +135,10 @@
  * @vbox and @action_area as internal children with the names “vbox” and
  * “action_area”.
  *
- * GtkDialog supports a custom &lt;action-widgets&gt; element, which
- * can contain multiple &lt;action-widget&gt; elements. The “response”
- * attribute specifies a numeric response, and the content of the element
- * is the id of widget (which should be a child of the dialogs @action_area).
+ * GtkDialog supports a custom <action-widgets> element, which can contain
+ * multiple <action-widget> elements. The “response” attribute specifies a
+ * numeric response, and the content of the element is the id of widget
+ * (which should be a child of the dialogs @action_area).
  *
  * An example of a #GtkDialog UI definition fragment:
  * |[
@@ -1477,7 +1477,7 @@ gtk_dialog_set_alternative_button_order_valist (GtkDialog *dialog,
  * [GNOME Human Interface Guidelines](http://library.gnome.org/devel/hig-book/stable/)
  * with the affirmative button at the far
  * right, and the cancel button left of it. But the builtin GTK+ dialogs
- * and #GtkMessageDialog<!-- -->s do provide an alternative button order,
+ * and #GtkMessageDialogs do provide an alternative button order,
  * which is more suitable on some platforms, e.g. Windows.
  *
  * Use this function after adding all the buttons to your dialog, as the
diff --git a/gtk/gtkdnd-quartz.c b/gtk/gtkdnd-quartz.c
index 8f48e60..9967ef7 100644
--- a/gtk/gtkdnd-quartz.c
+++ b/gtk/gtkdnd-quartz.c
@@ -487,7 +487,7 @@ gtk_drag_dest_site_destroy (gpointer data)
  * gtk_drag_dest_set: (method)
  * @widget: a #GtkWidget
  * @flags: which types of default drag behavior to use
- * @targets: (allow-none) (array length=n_targets): a pointer to an array of #GtkTargetEntry<!-- -->s
+ * @targets: (allow-none) (array length=n_targets): a pointer to an array of #GtkTargetEntrys
  *     indicating the drop types that this @widget will accept, or %NULL.
  *     Later you can access the list with gtk_drag_dest_get_target_list()
  *     and gtk_drag_dest_find_target().
diff --git a/gtk/gtkdnd.c b/gtk/gtkdnd.c
index c5fa0d7..29eb74d 100644
--- a/gtk/gtkdnd.c
+++ b/gtk/gtkdnd.c
@@ -1347,10 +1347,10 @@ gtk_drag_dest_set_internal (GtkWidget       *widget,
  * gtk_drag_dest_set: (method)
  * @widget: a #GtkWidget
  * @flags: which types of default drag behavior to use
- * @targets: (allow-none) (array length=n_targets): a pointer to an array of #GtkTargetEntry<!-- -->s
- *     indicating the drop types that this @widget will accept, or %NULL.
- *     Later you can access the list with gtk_drag_dest_get_target_list()
- *     and gtk_drag_dest_find_target().
+ * @targets: (allow-none) (array length=n_targets): a pointer to an array of
+ *     #GtkTargetEntrys indicating the drop types that this @widget will
+ *     accept, or %NULL. Later you can access the list with
+ *     gtk_drag_dest_get_target_list() and gtk_drag_dest_find_target().
  * @n_targets: the number of entries in @targets
  * @actions: a bitmask of possible actions for a drop onto this @widget.
  *
diff --git a/gtk/gtkdrawingarea.c b/gtk/gtkdrawingarea.c
index c72193b..6901216 100644
--- a/gtk/gtkdrawingarea.c
+++ b/gtk/gtkdrawingarea.c
@@ -86,7 +86,7 @@
  *  return FALSE;
  * }
  * [...]
- *   GtkWidget &ast;drawing_area = gtk_drawing_area_new (<!-- -->);
+ *   GtkWidget &ast;drawing_area = gtk_drawing_area_new ();
  *   gtk_widget_set_size_request (drawing_area, 100, 100);
  *   g_signal_connect (G_OBJECT (drawing_area), "draw",
  *                     G_CALLBACK (draw_callback), NULL);
diff --git a/gtk/gtkexpander.c b/gtk/gtkexpander.c
index 3240559..82363e2 100644
--- a/gtk/gtkexpander.c
+++ b/gtk/gtkexpander.c
@@ -71,11 +71,10 @@
  *
  * # GtkExpander as GtkBuildable
  *
- * The GtkExpander implementation of the GtkBuildable interface
- * supports placing a child in the label position by specifying
- * “label” as the “type” attribute of a &lt;child&gt; element.
- * A normal content child can be specified without specifying
- * a &lt;child&gt; type attribute.
+ * The GtkExpander implementation of the GtkBuildable interface supports
+ * placing a child in the label position by specifying “label” as the
+ * “type” attribute of a <child> element. A normal content child can be
+ * specified without specifying a <child> type attribute.
  *
  * An example of a UI definition fragment with GtkExpander:
  * |[
diff --git a/gtk/gtkfilechooser.c b/gtk/gtkfilechooser.c
index 0037358..dd49ed1 100644
--- a/gtk/gtkfilechooser.c
+++ b/gtk/gtkfilechooser.c
@@ -99,7 +99,7 @@
  *
  *   ...
  *
- *   preview = gtk_image_new (<!-- -->);
+ *   preview = gtk_image_new ();
  *
  *   gtk_file_chooser_set_preview_widget (my_file_chooser, preview);
  *   g_signal_connect (my_file_chooser, "update-preview",
diff --git a/gtk/gtkfilechooserbutton.c b/gtk/gtkfilechooserbutton.c
index 2da0e38..525a54e 100644
--- a/gtk/gtkfilechooserbutton.c
+++ b/gtk/gtkfilechooserbutton.c
@@ -83,7 +83,7 @@
  * }
  * ]|
  *
- * The #GtkFileChooserButton supports the #GtkFileChooserAction<!-- -->s
+ * The #GtkFileChooserButton supports the #GtkFileChooserActions
  * %GTK_FILE_CHOOSER_ACTION_OPEN and %GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER.
  *
  * > The #GtkFileChooserButton will ellipsize the label, and will thus
diff --git a/gtk/gtkfilefilter.c b/gtk/gtkfilefilter.c
index 9d6d4cf..7311e10 100644
--- a/gtk/gtkfilefilter.c
+++ b/gtk/gtkfilefilter.c
@@ -41,11 +41,10 @@
  * # GtkFileFilter as GtkBuildable
  *
  * The GtkFileFilter implementation of the GtkBuildable interface
- * supports adding rules using the &lt;mime-types&gt;, &lt;patterns&gt;
- * and &lt;applications&gt; elements and listing the rules within.
- * Specifying a &lt;mime-type&gt; or &lt;pattern&gt; is the same
- * as calling gtk_recent_filter_add_mime_type()
- * or gtk_recent_filter_add_pattern().
+ * supports adding rules using the <mime-types>, <patterns> and
+ * <applications> elements and listing the rules within. Specifying
+ * a <mime-type> or <pattern> has the same effect as as calling
+ * gtk_recent_filter_add_mime_type() or gtk_recent_filter_add_pattern().
  *
  * An example of a UI definition fragment specifying GtkFileFilter
  * rules:
diff --git a/gtk/gtkframe.c b/gtk/gtkframe.c
index 8ffb783..98b4a75 100644
--- a/gtk/gtkframe.c
+++ b/gtk/gtkframe.c
@@ -47,11 +47,10 @@
  *
  * # GtkFrame as GtkBuildable
  *
- * The GtkFrame implementation of the GtkBuildable interface
- * supports placing a child in the label position by specifying
- * “label” as the “type” attribute of a &lt;child&gt; element.
- * A normal content child can be specified without specifying
- * a &lt;child&gt; type attribute.
+ * The GtkFrame implementation of the GtkBuildable interface supports
+ * placing a child in the label position by specifying “label” as the
+ * “type” attribute of a <child> element. A normal content child can
+ * be specified without specifying a <child> type attribute.
  *
  * An example of a UI definition fragment with GtkFrame:
  * |[
diff --git a/gtk/gtkicontheme.c b/gtk/gtkicontheme.c
index 4b0ee84..73173b1 100644
--- a/gtk/gtkicontheme.c
+++ b/gtk/gtkicontheme.c
@@ -120,18 +120,18 @@
  *
  * icon_theme = gtk_icon_theme_get_default ();
  * pixbuf = gtk_icon_theme_load_icon (icon_theme,
- *                                    "my-icon-name", // icon name
- *                                    48, // size
- *                                    0,  // flags
+ *                                    "my-icon-name", /&ast; icon name &ast;/
+ *                                    48, /&ast; icon size &ast;/
+ *                                    0,  /&ast; flags &ast;/
  *                                    &error);
  * if (!pixbuf)
  *   {
- *     g_warning ("Couldn’t load icon: &percnt;s", error->message);
+ *     g_warning ("Couldn’t load icon: %s", error->message);
  *     g_error_free (error);
  *   }
  * else
  *   {
- *     // Use the pixbuf
+ *     /&ast; Use the pixbuf &ast;/
  *     g_object_unref (pixbuf);
  *   }
  * ]|
diff --git a/gtk/gtkiconview.c b/gtk/gtkiconview.c
index e331d26..3ad9259 100644
--- a/gtk/gtkiconview.c
+++ b/gtk/gtkiconview.c
@@ -4772,7 +4772,7 @@ gtk_icon_view_set_tooltip_query_cb (GtkWidget  *widget,
  * @icon_view will connect a #GtkWidget::query-tooltip signal handler.
  *
  * Note that the signal handler sets the text with gtk_tooltip_set_markup(),
- * so &amp;, &lt;, etc have to be escaped in the text.
+ * so &, <, etc have to be escaped in the text.
  *
  * Since: 2.12
  */
@@ -5452,7 +5452,7 @@ gtk_icon_view_unselect_path (GtkIconView *icon_view,
  *
  * Creates a list of paths of all selected items. Additionally, if you are
  * planning on modifying the model after calling this function, you may
- * want to convert the returned list into a list of #GtkTreeRowReference<!-- -->s.
+ * want to convert the returned list into a list of #GtkTreeRowReferences.
  * To do this, you can use gtk_tree_row_reference_new().
  *
  * To free the return value, use:
diff --git a/gtk/gtkimage.c b/gtk/gtkimage.c
index efbdb52..2932062 100644
--- a/gtk/gtkimage.c
+++ b/gtk/gtkimage.c
@@ -83,14 +83,14 @@
  *                          GdkEventButton *event,
  *                          gpointer        data)
  *   {
- *     g_print ("Event box clicked at coordinates &percnt;f,&percnt;f\n",
+ *     g_print ("Event box clicked at coordinates %f,%f\n",
  *              event->x, event->y);
  *
- *     /<!---->* Returning TRUE means we handled the event, so the signal
- *      * emission should be stopped (don’t call any further
- *      * callbacks that may be connected). Return FALSE
- *      * to continue invoking callbacks.
- *      *<!---->/
+ *     /&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;/
  *     return TRUE;
  *   }
  *
@@ -102,7 +102,7 @@
  *
  *     image = gtk_image_new_from_file ("myfile.png");
  *
- *     event_box = gtk_event_box_new (<!-- -->);
+ *     event_box = gtk_event_box_new ();
  *
  *     gtk_container_add (GTK_CONTAINER (event_box), image);
  *
diff --git a/gtk/gtkinfobar.c b/gtk/gtkinfobar.c
index d29a3e0..c0e756f 100644
--- a/gtk/gtkinfobar.c
+++ b/gtk/gtkinfobar.c
@@ -104,10 +104,10 @@
  * the content area and action area as internal children with the names
  * “content_area” and “action_area”.
  *
- * GtkInfoBar supports a custom &lt;action-widgets&gt; element, which
- * can contain multiple &lt;action-widget&gt; elements. The “response”
- * attribute specifies a numeric response, and the content of the element
- * is the id of widget (which should be a child of the dialogs @action_area).
+ * GtkInfoBar supports a custom <action-widgets> element, which can contain
+ * multiple <action-widget> elements. The “response” attribute specifies a
+ * numeric response, and the content of the element is the id of widget
+ * (which should be a child of the dialogs @action_area).
  */
 
 enum
diff --git a/gtk/gtklabel.c b/gtk/gtklabel.c
index 900a783..827bea3 100644
--- a/gtk/gtklabel.c
+++ b/gtk/gtklabel.c
@@ -70,9 +70,10 @@
  * # GtkLabel as GtkBuildable
  *
  * The GtkLabel implementation of the GtkBuildable interface supports a
- * custom &lt;attributes&gt; element, which supports any number of &lt;attribute&gt;
- * elements. the &lt;attribute&gt; element has attributes named name, value,
- * start and end and allows you to specify #PangoAttribute values for this label.
+ * custom <attributes> element, which supports any number of <attribute>
+ * elements. The <attribute> element has attributes named “name“, “value“,
+ * “start“ and “end“ and allows you to specify #PangoAttribute values for
+ * this label.
  *
  * An example of a UI definition fragment specifying Pango attributes:
  * |[
@@ -147,9 +148,9 @@
  * tags in the Pango manual.)
  *
  * The markup passed to gtk_label_set_markup() must be valid; for example,
- * literal &lt;, &gt; and &amp; characters must be escaped as \&lt;,
- * \gt;, and \&amp;. If you pass text obtained from the user, file,
- * or a network to gtk_label_set_markup(), you’ll want to escape it with
+ * literal <, > and & characters must be escaped as &lt;, &gt;, and &amp;.
+ * If you pass text obtained from the user, file, or a network to
+ * gtk_label_set_markup(), you’ll want to escape it with
  * g_markup_escape_text() or g_markup_printf_escaped().
  *
  * Markup strings are just a convenient way to set the #PangoAttrList on
@@ -198,10 +199,10 @@
  * # Links
  *
  * Since 2.18, GTK+ supports markup for clickable hyperlinks in addition
- * to regular Pango markup. The markup for links is borrowed from HTML, using the
- * `&lt;a&gt;` with href and title attributes. GTK+ renders links similar to the
- * way they appear in web browsers, with colored, underlined text. The title
- * attribute is displayed as a tooltip on the link.
+ * to regular Pango markup. The markup for links is borrowed from HTML,
+ * using the `<a>` with “href“ and “title“ attributes. GTK+ renders links
+ * similar to the way they appear in web browsers, with colored, underlined
+ * text. The “title“ attribute is displayed as a tooltip on the link.
  *
  * An example looks like this:
  *
@@ -2598,11 +2599,11 @@ gtk_label_set_markup_internal (GtkLabel    *label,
  * [Pango text markup language][PangoMarkupFormat], setting the
  * label’s text and attribute list based on the parse results. If the @str is
  * external data, you may need to escape it with g_markup_escape_text() or
- * g_markup_printf_escaped()<!-- -->:
+ * g_markup_printf_escaped():
  * |[<!-- language="C" -->
  * char *markup;
  *
- * markup = g_markup_printf_escaped ("&lt;span style=\"italic\"&gt;&percnt;s&lt;/span&gt;", str);
+ * markup = g_markup_printf_escaped ("<span style=\"italic\">\%s</span>", str);
  * gtk_label_set_markup (GTK_LABEL (label), markup);
  * g_free (markup);
  * ]|
diff --git a/gtk/gtkliststore.c b/gtk/gtkliststore.c
index 837c5ca..039d74d 100644
--- a/gtk/gtkliststore.c
+++ b/gtk/gtkliststore.c
@@ -111,7 +111,7 @@
  * a tail pointer prior to GTK+ 2.6.  As a result, it was fast at data
  * insertion and deletion, and not fast at random data access.  The
  * #GtkListStore sets the #GTK_TREE_MODEL_ITERS_PERSIST flag, which means
- * that #GtkTreeIter<!-- -->s can be cached while the row exists.  Thus, if
+ * that #GtkTreeIters can be cached while the row exists.  Thus, if
  * access to a particular row is needed often and your code is expected to
  * run on older versions of GTK+, it is worth keeping the iter around.
  *
@@ -135,22 +135,19 @@
  * # GtkListStore as GtkBuildable
  *
  * The GtkListStore implementation of the GtkBuildable interface allows
- * to specify the model columns with a &lt;columns&gt; element that may
- * contain multiple &lt;column&gt; elements, each specifying one model
- * column. The “type” attribute specifies the data type for the column.
+ * to specify the model columns with a <columns> element that may contain
+ * multiple <column> elements, each specifying one model column. The “type”
+ * attribute specifies the data type for the column.
  *
  * Additionally, it is possible to specify content for the list store
- * in the UI definition, with the &lt;data&gt; element. It can contain
- * multiple &lt;row&gt; elements, each specifying to content for one
- * row of the list model. Inside a &lt;row&gt;, the &lt;col&gt; elements
- * specify the content for individual cells.
- *
- * Note that it is probably more common to define your models
- * in the code, and one might consider it a layering violation
- * to specify the content of a list store in a UI definition,
- * data, not presentation,
- * and common wisdom is to separate the two, as far as possible.
- * <!-- FIXME a bit inconclusive -->
+ * in the UI definition, with the <data> element. It can contain multiple
+ * <row> elements, each specifying to content for one row of the list model.
+ * Inside a <row>, the <col> elements specify the content for individual cells.
+ *
+ * Note that it is probably more common to define your models in the code,
+ * and one might consider it a layering violation to specify the content of
+ * a list store in a UI definition, data, not presentation, and common wisdom
+ * is to separate the two, as far as possible.
  *
  * An example of a UI Definition fragment for a list store:
  * |[<!-- language="C" -->
diff --git a/gtk/gtkmenu.c b/gtk/gtkmenu.c
index 72e736b..bb0e5d6 100644
--- a/gtk/gtkmenu.c
+++ b/gtk/gtkmenu.c
@@ -2035,9 +2035,9 @@ gtk_menu_real_can_activate_accel (GtkWidget *widget,
  * purpose, automatically gets an accel path assigned.
  *
  * For example, a menu containing menu items “New” and “Exit”, will, after
- * `gtk_menu_set_accel_path (menu, "&lt;Gnumeric-Sheet&gt;/File");`
- * has been called, assign its items the accel paths:
- * `"&lt;Gnumeric-Sheet&gt;/File/New"` and `"&lt;Gnumeric-Sheet&gt;/File/Exit"`.
+ * `gtk_menu_set_accel_path (menu, "<Gnumeric-Sheet>/File");` has been
+ * called, assign its items the accel paths: `"<Gnumeric-Sheet>/File/New"`
+ * and `"<Gnumeric-Sheet>/File/Exit"`.
  *
  * Assigning accel paths to menu items then enables the user to change
  * their accelerators at runtime. More details about accelerator paths
diff --git a/gtk/gtkmenubutton.c b/gtk/gtkmenubutton.c
index c79cebe..b18c456 100644
--- a/gtk/gtkmenubutton.c
+++ b/gtk/gtkmenubutton.c
@@ -610,6 +610,7 @@ gtk_menu_button_init (GtkMenuButton *menu_button)
   priv = gtk_menu_button_get_instance_private (menu_button);
   menu_button->priv = priv;
   priv->arrow_type = GTK_ARROW_DOWN;
+  priv->use_popover = TRUE;
 
   add_arrow (menu_button);
 
diff --git a/gtk/gtkmenuitem.c b/gtk/gtkmenuitem.c
index 69fa4cb..a4bb561 100644
--- a/gtk/gtkmenuitem.c
+++ b/gtk/gtkmenuitem.c
@@ -73,9 +73,9 @@
  *
  * # GtkMenuItem as GtkBuildable
  *
- * The GtkMenuItem implementation of the #GtkBuildable interface
- * supports adding a submenu by specifying “submenu” as the “type”
- * attribute of a &lt;child&gt; element.
+ * The GtkMenuItem implementation of the #GtkBuildable interface supports
+ * adding a submenu by specifying “submenu” as the “type” attribute of
+ * a <child> element.
  *
  * An example of UI definition fragment with submenus:
  * |[
diff --git a/gtk/gtkmenutoolbutton.c b/gtk/gtkmenutoolbutton.c
index cb71576..3385e13 100644
--- a/gtk/gtkmenutoolbutton.c
+++ b/gtk/gtkmenutoolbutton.c
@@ -51,8 +51,8 @@
  * # GtkMenuToolButton as GtkBuildable
  *
  * The GtkMenuToolButton implementation of the GtkBuildable interface
- * supports adding a menu by specifying “menu” as the “type”
- * attribute of a &lt;child&gt; element.
+ * supports adding a menu by specifying “menu” as the “type” attribute
+ * of a <child> element.
  *
  * An example for a UI definition fragment with menus:
  * |[
diff --git a/gtk/gtkmessagedialog.c b/gtk/gtkmessagedialog.c
index 65c49d8..5d42123 100644
--- a/gtk/gtkmessagedialog.c
+++ b/gtk/gtkmessagedialog.c
@@ -799,7 +799,7 @@ 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, "&percnt;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 bf3c20e..6ca07a7 100644
--- a/gtk/gtknotebook.c
+++ b/gtk/gtknotebook.c
@@ -68,14 +68,14 @@
  * 
  * The GtkNotebook implementation of the #GtkBuildable interface
  * supports placing children into tabs by specifying “tab” as the
- * “type” attribute of a &lt;child&gt; element. Note that the content
+ * “type” attribute of a <child> element. Note that the content
  * of the tab must be created before the tab can be filled.
- * A tab child can be specified without specifying a &lt;child&gt;
+ * A tab child can be specified without specifying a <child>
  * type attribute.
  *
  * To add a child widget in the notebooks action area, specify
- * "action-start" or “action-end” as the “type” attribute of the &lt;child&gt;
- * element.
+ * "action-start" or “action-end” as the “type” attribute of the
+ * <child> element.
  *
  * An example of a UI definition fragment with GtkNotebook:
  * |[
diff --git a/gtk/gtkoverlay.c b/gtk/gtkoverlay.c
index 3b1ac19..c77b7cc 100644
--- a/gtk/gtkoverlay.c
+++ b/gtk/gtkoverlay.c
@@ -50,7 +50,7 @@
  *
  * The GtkOverlay implementation of the GtkBuildable interface
  * supports placing a child as an overlay by specifying “overlay” as
- * the “type” attribute of a `&lt;child&gt;` element.
+ * the “type” attribute of a `<child>` element.
  */
 
 struct _GtkOverlayPrivate
diff --git a/gtk/gtkpagesetup.c b/gtk/gtkpagesetup.c
index 83ec00f..59bae8d 100644
--- a/gtk/gtkpagesetup.c
+++ b/gtk/gtkpagesetup.c
@@ -59,7 +59,7 @@
  *   GtkPageSetup *new_page_setup;
  *
  *   if (settings == NULL)
- *     settings = gtk_print_settings_new (<!-- -->);
+ *     settings = gtk_print_settings_new ();
  *
  *   new_page_setup = gtk_print_run_page_setup_dialog (GTK_WINDOW (main_window),
  *                                                     page_setup, settings);
diff --git a/gtk/gtkprinter.c b/gtk/gtkprinter.c
index c78328d..53bc953 100644
--- a/gtk/gtkprinter.c
+++ b/gtk/gtkprinter.c
@@ -1050,8 +1050,8 @@ gtk_printer_get_capabilities (GtkPrinter *printer)
  *
  * Compares two printers.
  * 
- * Return value: 0 if the printer match, a negative value if @a &lt; @b, 
- *   or a positive value if @a &gt; @b
+ * Return value: 0 if the printer match, a negative value if @a < @b, 
+ *   or a positive value if @a > @b
  *
  * Since: 2.10
  */
@@ -1218,7 +1218,7 @@ list_printers_init (PrinterList     *printer_list,
  * @wait: if %TRUE, wait in a recursive mainloop until
  *    all printers are enumerated; otherwise return early
  *
- * Calls a function for all #GtkPrinter<!-- -->s. 
+ * Calls a function for all #GtkPrinters. 
  * If @func returns %TRUE, the enumeration is stopped.
  *
  * Since: 2.10
diff --git a/gtk/gtkprintsettings.c b/gtk/gtkprintsettings.c
index 4579e8b..39d3a83 100644
--- a/gtk/gtkprintsettings.c
+++ b/gtk/gtkprintsettings.c
@@ -1435,7 +1435,7 @@ gtk_print_settings_set_print_pages (GtkPrintSettings *settings,
  * Gets the value of %GTK_PRINT_SETTINGS_PAGE_RANGES.
  *
  * Return value: (array length=num_ranges) (transfer full): an array
- *     of #GtkPageRange<!-- -->s.  Use g_free() to free the array when
+ *     of #GtkPageRanges.  Use g_free() to free the array when
  *     it is no longer needed.
  *
  * Since: 2.10
@@ -1493,7 +1493,7 @@ gtk_print_settings_get_page_ranges (GtkPrintSettings *settings,
 /**
  * gtk_print_settings_set_page_ranges:
  * @settings: a #GtkPrintSettings
- * @page_ranges: (array length=num_ranges): an array of #GtkPageRange<!-- -->s
+ * @page_ranges: (array length=num_ranges): an array of #GtkPageRanges
  * @num_ranges: the length of @page_ranges
  * 
  * Sets the value of %GTK_PRINT_SETTINGS_PAGE_RANGES.
diff --git a/gtk/gtkradiobutton.c b/gtk/gtkradiobutton.c
index e4e14cc..a80175c 100644
--- a/gtk/gtkradiobutton.c
+++ b/gtk/gtkradiobutton.c
@@ -80,7 +80,7 @@
  *
  *    /&ast; Create a radio button with a GtkEntry widget &ast;/
  *    radio1 = gtk_radio_button_new (NULL);
- *    entry = gtk_entry_new (<!-- -->);
+ *    entry = gtk_entry_new ();
  *    gtk_container_add (GTK_CONTAINER (radio1), entry);
  *
  *
diff --git a/gtk/gtkrecentfilter.c b/gtk/gtkrecentfilter.c
index ea6066d..e7f2bdc 100644
--- a/gtk/gtkrecentfilter.c
+++ b/gtk/gtkrecentfilter.c
@@ -32,7 +32,7 @@
  * types; e.g. a filter for text/plain also matches a file with mime
  * type application/rtf, since application/rtf is a subclass of text/plain.
  * Note that #GtkRecentFilter allows wildcards for the subtype of a
- * mime type, so you can e.g. filter for image/<!-- -->*.
+ * mime type, so you can e.g. filter for image/&ast;.
  *
  * Normally, filters are used by adding them to a #GtkRecentChooser,
  * see gtk_recent_chooser_add_filter(), but it is also possible to
@@ -43,11 +43,11 @@
  * ## GtkRecentFilter as GtkBuildable
  *
  * The GtkRecentFilter implementation of the GtkBuildable interface
- * supports adding rules using the &lt;mime-types&gt;, &lt;patterns&gt; and
- * &lt;applications&gt; elements and listing the rules within. Specifying
- * a &lt;mime-type&gt;, &lt;pattern&gt; or &lt;application&gt; is the same
- * as calling gtk_recent_filter_add_mime_type(), gtk_recent_filter_add_pattern()
- * or gtk_recent_filter_add_application().
+ * supports adding rules using the <mime-types>, <patterns> and
+ * <applications> elements and listing the rules within. Specifying
+ * a <mime-type>, <pattern> or <application> has the same effect as
+ * calling gtk_recent_filter_add_mime_type(),
+ * gtk_recent_filter_add_pattern() or gtk_recent_filter_add_application().
  *
  * An example of a UI definition fragment specifying GtkRecentFilter rules:
  * |[
diff --git a/gtk/gtkrecentmanager.c b/gtk/gtkrecentmanager.c
index 2268c57..caa48ad 100644
--- a/gtk/gtkrecentmanager.c
+++ b/gtk/gtkrecentmanager.c
@@ -73,7 +73,7 @@
  * ]|
  *
  * In order to retrieve the list of recently used files, you can use
- * gtk_recent_manager_get_items(), which returns a list of #GtkRecentInfo-struct<!-- -->s.
+ * gtk_recent_manager_get_items(), which returns a list of #GtkRecentInfo-structs.
  *
  * A #GtkRecentManager is the model used to populate the contents of
  * one, or more #GtkRecentChooser implementations.
diff --git a/gtk/gtkscale.c b/gtk/gtkscale.c
index 44ecabb..5a6acab 100644
--- a/gtk/gtkscale.c
+++ b/gtk/gtkscale.c
@@ -63,11 +63,11 @@
  *
  * # GtkScale as GtkBuildable
  *
- * GtkScale supports a custom &lt;marks&gt; element, which
- * can contain multiple &lt;mark&gt; elements. The “value” and “position”
- * attributes have the same meaning as gtk_scale_add_mark() parameters of the
- * same name. If the element is not empty, its content is taken as the markup
- * to show at the mark. It can be translated with the usual "translatable and
+ * GtkScale supports a custom <marks> element, which can contain multiple
+ * <mark> elements. The “value” and “position” attributes have the same
+ * meaning as gtk_scale_add_mark() parameters of the same name. If the
+ * element is not empty, its content is taken as the markup to show at
+ * the mark. It can be translated with the usual ”translatable” and
  * “context” attributes.
  */
 
@@ -280,13 +280,13 @@ gtk_scale_class_init (GtkScaleClass *class)
    * @value. That string will then be used to display the scale's value.
    *
    * Here's an example signal handler which displays a value 1.0 as
-   * with "--&gt;1.0&lt;--".
+   * with "-->1.0<--".
    * |[<!-- language="C" -->
    * static gchar*
    * format_value_callback (GtkScale *scale,
    *                        gdouble   value)
    * {
-   *   return g_strdup_printf ("--&gt;&percnt;0.*g&lt;--",
+   *   return g_strdup_printf ("-->\%0.*g<--",
    *                           gtk_scale_get_digits (scale), value);
    *  }
    * ]|
diff --git a/gtk/gtkselection.c b/gtk/gtkselection.c
index e5032f7..925d5ff 100644
--- a/gtk/gtkselection.c
+++ b/gtk/gtkselection.c
@@ -1895,7 +1895,7 @@ gtk_selection_data_get_targets (const GtkSelectionData  *selection_data,
 
 /**
  * gtk_targets_include_text:
- * @targets: (array length=n_targets): an array of #GdkAtom<!-- -->s
+ * @targets: (array length=n_targets): an array of #GdkAtoms
  * @n_targets: the length of @targets
  * 
  * Determines if any of the targets in @targets can be used to
@@ -1940,7 +1940,7 @@ gtk_targets_include_text (GdkAtom *targets,
 
 /**
  * gtk_targets_include_rich_text:
- * @targets: (array length=n_targets): an array of #GdkAtom<!-- -->s
+ * @targets: (array length=n_targets): an array of #GdkAtoms
  * @n_targets: the length of @targets
  * @buffer: a #GtkTextBuffer
  *
@@ -2058,7 +2058,7 @@ gtk_selection_data_targets_include_rich_text (const GtkSelectionData *selection_
 
 /**
  * gtk_targets_include_image:
- * @targets: (array length=n_targets): an array of #GdkAtom<!-- -->s
+ * @targets: (array length=n_targets): an array of #GdkAtoms
  * @n_targets: the length of @targets
  * @writable: whether to accept only targets for which GTK+ knows
  *   how to convert a pixbuf into the format
@@ -2140,7 +2140,7 @@ gtk_selection_data_targets_include_image (const GtkSelectionData *selection_data
 
 /**
  * gtk_targets_include_uri:
- * @targets: (array length=n_targets): an array of #GdkAtom<!-- -->s
+ * @targets: (array length=n_targets): an array of #GdkAtoms
  * @n_targets: the length of @targets
  * 
  * Determines if any of the targets in @targets can be used to
diff --git a/gtk/gtksettings.c b/gtk/gtksettings.c
index 8d93f76..d2daf83 100644
--- a/gtk/gtksettings.c
+++ b/gtk/gtksettings.c
@@ -923,7 +923,7 @@ gtk_settings_class_init (GtkSettingsClass *class)
    * GtkSettings:color-hash:
    *
    * Holds a hash table representation of the #GtkSettings:gtk-color-scheme
-   * setting, mapping color names to #GdkColor<!-- -->s.
+   * setting, mapping color names to #GdkColors.
    *
    * Since: 2.10
    *
@@ -976,8 +976,8 @@ gtk_settings_class_init (GtkSettingsClass *class)
    * GtkSettings:gtk-print-preview-command:
    *
    * A command to run for displaying the print preview. The command
-   * should contain a `&percnt;f` placeholder, which will get replaced by
-   * the path to the pdf file. The command may also contain a `&percnt;s`
+   * should contain a `\%f` placeholder, which will get replaced by
+   * the path to the pdf file. The command may also contain a `\%s`
    * placeholder, which will get replaced by the path to a file
    * containing the print settings in the format produced by
    * gtk_print_settings_to_file().
diff --git a/gtk/gtkshow.c b/gtk/gtkshow.c
index 0bfb9cb..34ae80f 100644
--- a/gtk/gtkshow.c
+++ b/gtk/gtkshow.c
@@ -39,7 +39,7 @@
  * Typical examples are
  * - `file:///home/gnome/pict.jpg`
  * - `http://www.gnome.org`
- * - `mailto:me&commat;gnome.org`
+ * - `mailto:me\ gnome org`
  * Ideally the timestamp is taken from the event triggering
  * the gtk_show_uri() call. If timestamp is not known you can take
  * %GDK_CURRENT_TIME.
diff --git a/gtk/gtksizegroup.c b/gtk/gtksizegroup.c
index da85ab8..9519ae9 100644
--- a/gtk/gtksizegroup.c
+++ b/gtk/gtksizegroup.c
@@ -84,12 +84,11 @@
  *
  * # GtkSizeGroup as GtkBuildable
  *
- * Size groups can be specified in a UI definition by placing an
- * &lt;object&gt; element with `class="GtkSizeGroup"`
- * somewhere in the UI definition. The widgets that belong to the
- * size group are specified by a &lt;widgets&gt; element that may
- * contain multiple &lt;widget&gt; elements, one for each member
- * of the size group. The name attribute gives the id of the widget.
+ * Size groups can be specified in a UI definition by placing an <object>
+ * element with `class="GtkSizeGroup"` somewhere in the UI definition. The
+ * widgets that belong to the size group are specified by a <widgets> element
+ * that may contain multiple <widget> elements, one for each member of the
+ * size group. The ”name” attribute gives the id of the widget.
  *
  * An example of a UI definition fragment with GtkSizeGroup:
  * |[
diff --git a/gtk/gtksizerequest.c b/gtk/gtksizerequest.c
index 7ac4fa0..ef3bb0c 100644
--- a/gtk/gtksizerequest.c
+++ b/gtk/gtksizerequest.c
@@ -472,7 +472,7 @@ gtk_widget_get_request_mode (GtkWidget *widget)
  *
  * The returned request will be modified by the
  * GtkWidgetClass::adjust_size_request virtual method and by any
- * #GtkSizeGroup<!-- -->s that have been applied. That is, the returned request
+ * #GtkSizeGroups that have been applied. That is, the returned request
  * is the one that should be used for layout, not necessarily the one
  * returned by the widget itself.
  *
@@ -507,7 +507,7 @@ gtk_widget_get_preferred_width (GtkWidget *widget,
  *
  * The returned request will be modified by the
  * GtkWidgetClass::adjust_size_request virtual method and by any
- * #GtkSizeGroup<!-- -->s that have been applied. That is, the returned request
+ * #GtkSizeGroups that have been applied. That is, the returned request
  * is the one that should be used for layout, not necessarily the one
  * returned by the widget itself.
  *
@@ -543,7 +543,7 @@ gtk_widget_get_preferred_height (GtkWidget *widget,
  *
  * The returned request will be modified by the
  * GtkWidgetClass::adjust_size_request virtual method and by any
- * #GtkSizeGroup<!-- -->s that have been applied. That is, the returned request
+ * #GtkSizeGroups that have been applied. That is, the returned request
  * is the one that should be used for layout, not necessarily the one
  * returned by the widget itself.
  *
@@ -579,7 +579,7 @@ gtk_widget_get_preferred_width_for_height (GtkWidget *widget,
  *
  * The returned request will be modified by the
  * GtkWidgetClass::adjust_size_request virtual method and by any
- * #GtkSizeGroup<!-- -->s that have been applied. That is, the returned request
+ * #GtkSizeGroups that have been applied. That is, the returned request
  * is the one that should be used for layout, not necessarily the one
  * returned by the widget itself.
  *
@@ -618,7 +618,7 @@ gtk_widget_get_preferred_height_for_width (GtkWidget *widget,
  *
  * The returned request will be modified by the
  * GtkWidgetClass::adjust_size_request and GtkWidgetClass::adjust_baseline_request virtual methods
- * and by any #GtkSizeGroup<!-- -->s that have been applied. That is, the returned request
+ * and by any #GtkSizeGroups that have been applied. That is, the returned request
  * is the one that should be used for layout, not necessarily the one
  * returned by the widget itself.
  *
diff --git a/gtk/gtksocket.c b/gtk/gtksocket.c
index 0bd7bc6..1ffc94e 100644
--- a/gtk/gtksocket.c
+++ b/gtk/gtksocket.c
@@ -71,7 +71,7 @@
  * ## Obtaining the window ID of a socket.
  *
  * |[<!-- language="C" -->
- * GtkWidget *socket = gtk_socket_new (<!-- -->);
+ * GtkWidget *socket = gtk_socket_new ();
  * gtk_widget_show (socket);
  * gtk_container_add (GTK_CONTAINER (parent), socket);
  *
diff --git a/gtk/gtkstylecontext.c b/gtk/gtkstylecontext.c
index 6901d60..a42b197 100644
--- a/gtk/gtkstylecontext.c
+++ b/gtk/gtkstylecontext.c
@@ -197,7 +197,7 @@
  *
  * # Custom styling in UI libraries and applications
  *
- * If you are developing a library with custom #GtkWidget<!-- -->s that
+ * If you are developing a library with custom #GtkWidgets that
  * render differently than standard components, you may need to add a
  * #GtkStyleProvider yourself with the %GTK_STYLE_PROVIDER_PRIORITY_FALLBACK
  * priority, either a #GtkCssProvider or a custom object implementing the
@@ -1025,7 +1025,7 @@ gtk_style_context_queue_invalidate_internal (GtkStyleContext *context,
  *
  * This function is only useful when using the theming layer
  * separated from GTK+, if you are using #GtkStyleContext to
- * theme #GtkWidget<!-- -->s, use gtk_widget_get_style_context()
+ * theme #GtkWidgets, use gtk_widget_get_style_context()
  * in order to get a style context ready to theme the widget.
  *
  * Returns: A newly created #GtkStyleContext.
@@ -4260,7 +4260,7 @@ gtk_render_extension (GtkStyleContext *context,
  * @height: rectangle height
  *
  * Renders a handle (as in #GtkHandleBox, #GtkPaned and
- * #GtkWindow<!-- -->’s resize grip), in the rectangle
+ * #GtkWindow’s resize grip), in the rectangle
  * determined by @x, @y, @width, @height.
  *
  * Handles rendered for the paned and grip classes:
diff --git a/gtk/gtktextbufferrichtext.c b/gtk/gtktextbufferrichtext.c
index cd4e87a..160dd82 100644
--- a/gtk/gtktextbufferrichtext.c
+++ b/gtk/gtktextbufferrichtext.c
@@ -407,7 +407,7 @@ gtk_text_buffer_deserialize_get_can_create_tags (GtkTextBuffer *buffer,
  * gtk_text_buffer_register_serialize_tagset()
  *
  * Return value: (array length=n_formats) (transfer container): an array of
- *               #GdkAtom<!-- -->s representing the registered formats.
+ *               #GdkAtoms representing the registered formats.
  *
  * Since: 2.10
  **/
@@ -435,7 +435,7 @@ gtk_text_buffer_get_serialize_formats (GtkTextBuffer *buffer,
  * gtk_text_buffer_register_deserialize_tagset()
  *
  * Return value: (array length=n_formats) (transfer container): an array of
- *               #GdkAtom<!-- -->s representing the registered formats.
+ *               #GdkAtoms representing the registered formats.
  *
  * Since: 2.10
  **/
@@ -465,7 +465,7 @@ gtk_text_buffer_get_deserialize_formats (GtkTextBuffer *buffer,
  * This function serializes the portion of text between @start
  * and @end in the rich text format represented by @format.
  *
- * @format<!-- -->s to be used must be registered using
+ * @formats to be used must be registered using
  * gtk_text_buffer_register_serialize_format() or
  * gtk_text_buffer_register_serialize_tagset() beforehand.
  *
@@ -526,7 +526,7 @@ gtk_text_buffer_serialize (GtkTextBuffer     *register_buffer,
  * This function deserializes rich text in format @format and inserts
  * it at @iter.
  *
- * @format<!-- -->s to be used must be registered using
+ * @formats to be used must be registered using
  * gtk_text_buffer_register_deserialize_format() or
  * gtk_text_buffer_register_deserialize_tagset() beforehand.
  *
diff --git a/gtk/gtktexttagtable.c b/gtk/gtktexttagtable.c
index 9ac3150..b69df05 100644
--- a/gtk/gtktexttagtable.c
+++ b/gtk/gtktexttagtable.c
@@ -48,8 +48,8 @@
  * # GtkTextTagTables as GtkBuildable
  *
  * The GtkTextTagTable implementation of the GtkBuildable interface
- * supports adding tags by specifying “tag” as the “type”
- * attribute of a &lt;child&gt; element.
+ * supports adding tags by specifying “tag” as the “type” attribute
+ * of a <child> element.
  *
  * An example of a UI definition fragment specifying tags:
  * |[
diff --git a/gtk/gtkthemingengine.c b/gtk/gtkthemingengine.c
index 2fff490..1abe9e8 100644
--- a/gtk/gtkthemingengine.c
+++ b/gtk/gtkthemingengine.c
@@ -58,7 +58,7 @@
  * theming engine would be created as an .so library, and installed in
  * $(gtk-modules-dir)/theming-engines/.
  *
- * #GtkThemingEngine<!-- -->s have limited access to the object they are
+ * #GtkThemingEngines have limited access to the object they are
  * rendering, the #GtkThemingEngine API has read-only accessors to the
  * style information contained in the rendered object’s #GtkStyleContext.
  */
diff --git a/gtk/gtktogglebutton.c b/gtk/gtktogglebutton.c
index 785cf22..de12f53 100644
--- a/gtk/gtktogglebutton.c
+++ b/gtk/gtktogglebutton.c
@@ -64,10 +64,10 @@
  * void make_toggles (void) {
  *    GtkWidget *dialog, *toggle1, *toggle2;
  *
- *    dialog = gtk_dialog_new (<!-- -->);
+ *    dialog = gtk_dialog_new ();
  *    toggle1 = gtk_toggle_button_new_with_label ("Hi, i’m a toggle button.");
  *
- *    // Makes this toggle button invisible
+ *    /&ast; Makes this toggle button invisible &ast;/
  *    gtk_toggle_button_set_mode (GTK_TOGGLE_BUTTON (toggle1), TRUE);
  *
  *    g_signal_connect (toggle1, "toggled",
diff --git a/gtk/gtktoolbar.c b/gtk/gtktoolbar.c
index 6e3a52d..e71ab7f 100644
--- a/gtk/gtktoolbar.c
+++ b/gtk/gtktoolbar.c
@@ -2888,11 +2888,11 @@ gtk_toolbar_get_n_items (GtkToolbar *toolbar)
  * @toolbar: a #GtkToolbar
  * @n: A position on the toolbar
  *
- * Returns the @n<!-- -->'th item on @toolbar, or %NULL if the
- * toolbar does not contain an @n<!-- -->'th item.
+ * Returns the @n'th item on @toolbar, or %NULL if the
+ * toolbar does not contain an @n'th item.
  *
- * Return value: (transfer none): The @n<!-- -->'th #GtkToolItem on @toolbar,
- *     or %NULL if there isn’t an @n<!-- -->'th item.
+ * Return value: (transfer none): The @n'th #GtkToolItem on @toolbar,
+ *     or %NULL if there isn’t an @n'th item.
  *
  * Since: 2.4
  **/
diff --git a/gtk/gtktoolbutton.c b/gtk/gtktoolbutton.c
index ed7fb46..0b5046f 100644
--- a/gtk/gtktoolbutton.c
+++ b/gtk/gtktoolbutton.c
@@ -42,7 +42,7 @@
  * @See_also: #GtkToolbar, #GtkMenuToolButton, #GtkToggleToolButton,
  *   #GtkRadioToolButton, #GtkSeparatorToolItem
  *
- * #GtkToolButton<!-- -->s are #GtkToolItems containing buttons.
+ * #GtkToolButtons are #GtkToolItems containing buttons.
  *
  * Use gtk_tool_button_new() to create a new #GtkToolButton.
  *
diff --git a/gtk/gtktoolitem.c b/gtk/gtktoolitem.c
index 5b39f82..f3b2841 100644
--- a/gtk/gtktoolitem.c
+++ b/gtk/gtktoolitem.c
@@ -39,7 +39,7 @@
  * @Title: GtkToolItem
  * @see_also: #GtkToolbar, #GtkToolButton, #GtkSeparatorToolItem
  *
- * #GtkToolItem<!-- -->s are widgets that can appear on a toolbar. To
+ * #GtkToolItems are widgets that can appear on a toolbar. To
  * create a toolbar item that contain something else than a button, use
  * gtk_tool_item_new(). Use gtk_container_add() to add a child
  * widget to the tool item.
@@ -1292,11 +1292,11 @@ gtk_tool_item_retrieve_proxy_menu_item (GtkToolItem *tool_item)
  *
  * Custom subclasses of #GtkToolItem should use this function to
  * update their menu item when the #GtkToolItem changes. That the
- * @menu_item_id<!-- -->s must match ensures that a #GtkToolItem
+ * @menu_item_ids must match ensures that a #GtkToolItem
  * will not inadvertently change a menu item that they did not create.
  *
  * Return value: (transfer none): The #GtkMenuItem passed to
- *     gtk_tool_item_set_proxy_menu_item(), if the @menu_item_id<!-- -->s
+ *     gtk_tool_item_set_proxy_menu_item(), if the @menu_item_ids
  *     match.
  *
  * Since: 2.4
diff --git a/gtk/gtktoolitemgroup.c b/gtk/gtktoolitemgroup.c
index 3485fa1..365403f 100644
--- a/gtk/gtktoolitemgroup.c
+++ b/gtk/gtktoolitemgroup.c
@@ -45,7 +45,7 @@
  * @Title: GtkToolItemGroup
  *
  * A #GtkToolItemGroup is used together with #GtkToolPalette to add
- * #GtkToolItem<!-- -->s to a palette like container with different
+ * #GtkToolItems to a palette like container with different
  * categories and drag and drop support.
  *
  * Since: 2.20
diff --git a/gtk/gtktoolpalette.c b/gtk/gtktoolpalette.c
index e6f9f6b..385557e 100644
--- a/gtk/gtktoolpalette.c
+++ b/gtk/gtktoolpalette.c
@@ -43,12 +43,12 @@
  * @Short_description: A tool palette with categories
  * @Title: GtkToolPalette
  *
- * A #GtkToolPalette allows you to add #GtkToolItem<!-- -->s to a palette-like
+ * A #GtkToolPalette allows you to add #GtkToolItems to a palette-like
  * container with different categories and drag and drop support.
  *
  * A #GtkToolPalette is created with a call to gtk_tool_palette_new().
  *
- * #GtkToolItem<!-- -->s cannot be added directly to a #GtkToolPalette - 
+ * #GtkToolItems cannot be added directly to a #GtkToolPalette - 
  * instead they are added to a #GtkToolItemGroup which can than be added
  * to a #GtkToolPalette. To add a #GtkToolItemGroup to a #GtkToolPalette,
  * use gtk_container_add().
@@ -86,14 +86,14 @@
  *   GtkWidget *palette;
  *   GtkWidget *item;
  *
- *   /<!-- -->* Get the dragged item *<!-- -->/
+ *   /&ast; Get the dragged item &ast;/
  *   palette = gtk_widget_get_ancestor (gtk_drag_get_source_widget (context),
  *                                      GTK_TYPE_TOOL_PALETTE);
  *   if (palette != NULL)
  *     item = gtk_tool_palette_get_drag_item (GTK_TOOL_PALETTE (palette),
  *                                            selection);
  *
- *   /<!-- -->* Do something with item *<!-- -->/
+ *   /&ast; Do something with item &ast;/
  * }
  *
  * GtkWidget *target, palette;
@@ -1624,7 +1624,7 @@ gtk_tool_palette_set_drag_source (GtkToolPalette            *palette,
  *     on that widget
  * @targets: the #GtkToolPaletteDragTargets which the widget
  *     should support
- * @actions: the #GdkDragAction<!-- -->s which the widget should suppport
+ * @actions: the #GdkDragActions which the widget should suppport
  *
  * Sets @palette as drag source (see gtk_tool_palette_set_drag_source())
  * and sets @widget as a drag destination for drags from @palette.
diff --git a/gtk/gtktreemodel.c b/gtk/gtktreemodel.c
index f228982..f556440 100644
--- a/gtk/gtktreemodel.c
+++ b/gtk/gtktreemodel.c
@@ -184,7 +184,7 @@
  *                        -1);
  *
  *    /&ast; Do something with the data &ast;/
- *    g_print ("Row &percnt;d: (&percnt;s,&percnt;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);
  *
  *    row_count++;
@@ -1593,10 +1593,10 @@ gtk_tree_model_iter_n_children (GtkTreeModel *tree_model,
  * The first index is 0. If @n is too big, or @parent has no children,
  * @iter is set to an invalid iterator and %FALSE is returned. @parent
  * will remain a valid node after this function has been called. As a
- * special case, if @parent is %NULL, then the @n<!-- -->th root node
+ * special case, if @parent is %NULL, then the @n-th root node
  * is set.
  *
- * Return value: %TRUE, if @parent has an @n<!-- -->th child
+ * Return value: %TRUE, if @parent has an @n-th child
  */
 gboolean
 gtk_tree_model_iter_nth_child (GtkTreeModel *tree_model,
@@ -1728,7 +1728,7 @@ gtk_tree_model_unref_node (GtkTreeModel *tree_model,
  * each column number followed by a place to store the value being
  * retrieved.  The list is terminated by a -1. For example, to get a
  * value from column 0 with type %G_TYPE_STRING, you would
- * write: `gtk_tree_model_get (model, iter, 0, &amp;place_string_here, -1)`,
+ * write: `gtk_tree_model_get (model, iter, 0, &place_string_here, -1)`,
  * where `place_string_here` is a #gchararray
  * to be filled with the string.
  *
diff --git a/gtk/gtktreemodelfilter.c b/gtk/gtktreemodelfilter.c
index d248b09..17d945a 100644
--- a/gtk/gtktreemodelfilter.c
+++ b/gtk/gtktreemodelfilter.c
@@ -3866,7 +3866,7 @@ gtk_tree_model_filter_set_visible_func (GtkTreeModelFilter            *filter,
  * gtk_tree_model_filter_set_modify_func:
  * @filter: A #GtkTreeModelFilter.
  * @n_columns: The number of columns in the filter model.
- * @types: (array length=n_columns): The #GType<!-- -->s of the columns.
+ * @types: (array length=n_columns): The #GTypes of the columns.
  * @func: A #GtkTreeModelFilterModifyFunc
  * @data: (allow-none): User data to pass to the modify function, or %NULL.
  * @destroy: (allow-none): Destroy notifier of @data, or %NULL.
diff --git a/gtk/gtktreemodelsort.c b/gtk/gtktreemodelsort.c
index 2324df8..05373ac 100644
--- a/gtk/gtktreemodelsort.c
+++ b/gtk/gtktreemodelsort.c
@@ -45,7 +45,7 @@
  * The use of this is best demonstrated through an example.  In the
  * following sample code we create two #GtkTreeView widgets each with a
  * view of the same data.  As the model is wrapped here by a
- * #GtkTreeModelSort, the two #GtkTreeView<!-- -->s can each sort their
+ * #GtkTreeModelSort, the two #GtkTreeViews can each sort their
  * view of the data without affecting the other.  By contrast, if we
  * simply put the same model in each widget, then sorting the first would
  * sort the second.
@@ -60,18 +60,18 @@
  *   GtkTreeModel *sort_model2;
  *   GtkTreeModel *child_model;
  *
- *   // get the child model
+ *   /&ast; get the child model &ast;/
  *   child_model = get_my_model ();
  *
- *   // Create the first tree
+ *   /&ast; Create the first tree &ast;/
  *   sort_model1 = gtk_tree_model_sort_new_with_model (child_model);
  *   tree_view1 = gtk_tree_view_new_with_model (sort_model1);
  *
- *   // Create the second tree
+ *   /&ast; Create the second tree &ast;/
  *   sort_model2 = gtk_tree_model_sort_new_with_model (child_model);
  *   tree_view2 = gtk_tree_view_new_with_model (sort_model2);
  *
- *   // Now we can sort the two models independently
+ *   /&ast; Now we can sort the two models independently &ast;/
  *   gtk_tree_sortable_set_sort_column_id (GTK_TREE_SORTABLE (sort_model1),
  *                                         COLUMN_1, GTK_SORT_ASCENDING);
  *   gtk_tree_sortable_set_sort_column_id (GTK_TREE_SORTABLE (sort_model2),
@@ -98,15 +98,15 @@
  *   char *some_data = NULL;
  *   char *modified_data;
  *
- *   // Get the current selected row and the model.
+ *   /&ast; Get the current selected row and the model. &ast;/
  *   if (! gtk_tree_selection_get_selected (selection,
  *                                          &sort_model,
  *                                          &sort_iter))
  *     return;
  *
- *   /<!---->* Look up the current value on the selected row and get a new value
- *    * to change it to.
- *    *<!---->/
+ *   /&ast; Look up the current value on the selected row and get
+ *    &ast; a new value to change it to.
+ *    &ast;/
  *   gtk_tree_model_get (GTK_TREE_MODEL (sort_model), &sort_iter,
  *                       COLUMN_1, &some_data,
  *                       -1);
@@ -114,15 +114,15 @@
  *   modified_data = change_the_data (some_data);
  *   g_free (some_data);
  *
- *   // Get an iterator on the child model, instead of the sort model.
+ *   /&ast; Get an iterator on the child model, instead of the sort model. &ast;/
  *   gtk_tree_model_sort_convert_iter_to_child_iter (GTK_TREE_MODEL_SORT (sort_model),
  *                                                   &child_iter,
  *                                                   &sort_iter);
  *
- *   /<!---->* Get the child model and change the value of the row.  In this
- *    * example, the child model is a GtkListStore.  It could be any other
- *    * type of model, though.
- *    *<!---->/
+ *   /&ast; Get the child model and change the value of the row. In this
+ *    &ast; example, the child model is a GtkListStore. It could be any other
+ *    &ast; type of model, though.
+ *    &ast;/
  *   child_model = gtk_tree_model_sort_get_model (GTK_TREE_MODEL_SORT (sort_model));
  *   gtk_list_store_set (GTK_LIST_STORE (child_model), &child_iter,
  *                       COLUMN_1, &modified_data,
diff --git a/gtk/gtktreeselection.c b/gtk/gtktreeselection.c
index 3a5bb98..99c9823 100644
--- a/gtk/gtktreeselection.c
+++ b/gtk/gtktreeselection.c
@@ -538,7 +538,7 @@ gtk_tree_selection_get_selected (GtkTreeSelection  *selection,
  *
  * Creates a list of path of all selected rows. Additionally, if you are
  * planning on modifying the model after calling this function, you may
- * want to convert the returned list into a list of #GtkTreeRowReference<!-- -->s.
+ * want to convert the returned list into a list of #GtkTreeRowReferences.
  * To do this, you can use gtk_tree_row_reference_new().
  *
  * To free the return value, use:
diff --git a/gtk/gtktreestore.c b/gtk/gtktreestore.c
index 95f7765..2fbc6a6 100644
--- a/gtk/gtktreestore.c
+++ b/gtk/gtktreestore.c
@@ -44,9 +44,9 @@
  * # GtkTreeStore as GtkBuildable
  *
  * The GtkTreeStore implementation of the #GtkBuildable interface allows
- * to specify the model columns with a &lt;columns&gt; element that may
- * contain multiple &lt;column&gt; elements, each specifying one model
- * column. The “type” attribute specifies the data type for the column.
+ * to specify the model columns with a <columns> element that may contain
+ * multiple <column> elements, each specifying one model column. The “type”
+ * attribute specifies the data type for the column.
  *
  * An example of a UI Definition fragment for a tree store:
  * |[
diff --git a/gtk/gtktreeview.c b/gtk/gtktreeview.c
index a3117e7..7bf95e7 100644
--- a/gtk/gtktreeview.c
+++ b/gtk/gtktreeview.c
@@ -99,8 +99,8 @@
  * # GtkTreeView as GtkBuildable
  *
  * The GtkTreeView implementation of the GtkBuildable interface accepts
- * #GtkTreeViewColumn objects as &lt;child&gt; elements and exposes the
- * internal #GtkTreeSelection in UI definitions.
+ * #GtkTreeViewColumn objects as <child> elements and exposes the internal
+ * #GtkTreeSelection in UI definitions.
  *
  * An example of a UI definition fragment with GtkTreeView:
  * |[
@@ -13355,7 +13355,7 @@ gtk_tree_view_get_bin_window (GtkTreeView *tree_view)
  * (please see gtk_tree_view_get_bin_window()).
  * That is, @x and @y are relative to an events coordinates. @x and @y must
  * come from an event on the @tree_view only where `event->window ==
- * gtk_tree_view_get_bin_window (<!-- -->)`. It is primarily for
+ * gtk_tree_view_get_bin_window ()`. It is primarily for
  * things like popup menus. If @path is non-%NULL, then it will be filled
  * with the #GtkTreePath at that point.  This path should be freed with
  * gtk_tree_path_free().  If @column is non-%NULL, then it will be filled
@@ -13994,7 +13994,7 @@ gtk_tree_view_get_visible_range (GtkTreeView  *tree_view,
  *
  * The @x and @y coordinate that are provided must be relative to bin_window
  * coordinates.  That is, @x and @y must come from an event on @tree_view
- * where `event->window == gtk_tree_view_get_bin_window (<!-- -->)`.
+ * where `event->window == gtk_tree_view_get_bin_window ()`.
  *
  * For converting widget coordinates (eg. the ones you get from
  * GtkWidget::query-tooltip), please see
@@ -16366,7 +16366,7 @@ gtk_tree_view_set_tooltip_query_cb (GtkWidget  *widget,
  * @tree_view will connect a #GtkWidget::query-tooltip signal handler.
  *
  * Note that the signal handler sets the text with gtk_tooltip_set_markup(),
- * so &amp;, &lt;, etc have to be escaped in the text.
+ * so &, <, etc have to be escaped in the text.
  *
  * Since: 2.12
  */
diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index 0807ce1..248bb43 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -258,8 +258,8 @@
  * # GtkWidget as GtkBuildable
  *
  * The GtkWidget implementation of the GtkBuildable interface supports a
- * custom &lt;accelerator&gt; element, which has attributes named key,
- * modifiers and signal and allows to specify accelerators.
+ * custom <accelerator> element, which has attributes named ”key”, ”modifiers”
+ * and ”signal” and allows to specify accelerators.
  *
  * An example of a UI definition fragment specifying an accelerator:
  * |[
@@ -268,10 +268,10 @@
  * </object>
  * ]|
  *
- * In addition to accelerators, #GtkWidget also support a
- * custom &lt;accessible&gt; element, which supports actions and relations.
- * Properties on the accessible implementation of an object can be set by accessing the
- * internal child “accessible” of a #GtkWidget.
+ * In addition to accelerators, GtkWidget also support a custom <accessible>
+ * element, which supports actions and relations. Properties on the accessible
+ * implementation of an object can be set by accessing the internal child
+ * “accessible” of a #GtkWidget.
  *
  * An example of a UI definition fragment specifying an accessible:
  * |[
@@ -292,7 +292,7 @@
  * ]|
  *
  * Finally, GtkWidget allows style information such as style classes to
- * be associated with widgets, using the custom &lt;style&gt; element:
+ * be associated with widgets, using the custom <style> element:
  * |[
  * <object class="GtkButton" id="button1">
  *   <style>
@@ -315,25 +315,25 @@
  * The interface description semantics expected in composite template descriptions
  * is slightly different from regulare #GtkBuilder XML.
  *
- * Unlike regular interface descriptions, gtk_widget_class_set_template() will expect a
- * &lt;template&gt; tag as a direct child of the toplevel &lt;interface&gt;
- * tag. The &lt;template&gt; tag must specify the “class” attribute which
- * must be the type name of the widget. Optionally, the “parent” attribute
- * may be specified to specify the direct parent type of the widget type, this
- * is ignored by the GtkBuilder but required for Glade to introspect what kind
+ * Unlike regular interface descriptions, gtk_widget_class_set_template() will
+ * expect a <template> tag as a direct child of the toplevel <interface>
+ * tag. The <template> tag must specify the “class” attribute which must be
+ * the type name of the widget. Optionally, the “parent” attribute may be
+ * specified to specify the direct parent type of the widget type, this is
+ * ignored by the GtkBuilder but required for Glade to introspect what kind
  * of properties and internal children exist for a given type when the actual
  * type does not exist.
  *
- * The XML which is contained inside the &lt;template&gt; tag behaves as if
- * it were added to the &lt;object&gt; tag defining @widget itself. You may set
- * properties on @widget by inserting &lt;property&gt; tags into the &lt;template&gt; 
- * tag, and also add &lt;child&gt; tags to add children and extend @widget in the
- * normal way you would with &lt;object&gt; tags.
+ * The XML which is contained inside the <template> tag behaves as if it were
+ * added to the <object> tag defining @widget itself. You may set properties
+ * on @widget by inserting <property> tags into the <template> tag, and also
+ * add <child> tags to add children and extend @widget in the normal way you
+ * would with <object> tags.
  *
- * Additionally, &lt;object&gt; tags can also be added before and
- * after the initial &lt;template&gt; tag in the normal way, allowing
- * one to define auxilary objects which might be referenced by other
- * widgets declared as children of the &lt;template&gt; tag.
+ * Additionally, <object> tags can also be added before and after the initial
+ * <template> tag in the normal way, allowing one to define auxilary objects
+ * which might be referenced by other widgets declared as children of the
+ * <template> tag.
  *
  * An example of a GtkBuilder Template Definition:
  * |[
@@ -2285,7 +2285,7 @@ G_GNUC_END_IGNORE_DEPRECATIONS
    * @widget: the object on which the signal is emitted
    *
    * The ::composited-changed signal is emitted when the composited
-   * status of @widget<!-- -->s screen changes.
+   * status of @widgets screen changes.
    * See gdk_screen_is_composited().
    */
   widget_signals[COMPOSITED_CHANGED] =
@@ -4066,7 +4066,7 @@ gtk_widget_freeze_child_notify (GtkWidget *widget)
  * gtk_widget_child_notify:
  * @widget: a #GtkWidget
  * @child_property: the name of a child property installed on the
- *                  class of @widget<!-- -->’s parent
+ *                  class of @widget’s parent
  *
  * Emits a #GtkWidget::child-notify signal for the
  * [child property][child-properties] @child_property
@@ -8105,11 +8105,10 @@ gtk_widget_device_is_shadowed (GtkWidget *widget,
  * same page as the docs for #GtkStyleContext).
  *
  * Note that the CSS syntax has certain special characters to delimit
- * and represent elements in a selector (period, &num;, &gt;, &ast;...),
- * so using these will make your widget impossible to match by name.
- * Any combination of alphanumeric symbols, dashes and underscores will
- * suffice.
- **/
+ * and represent elements in a selector (period, #, >, *...), so using
+ * these will make your widget impossible to match by name. Any combination
+ * of alphanumeric symbols, dashes and underscores will suffice.
+ */
 void
 gtk_widget_set_name (GtkWidget  *widget,
                     const gchar *name)
@@ -9054,7 +9053,7 @@ _gtk_widget_get_modifier_properties (GtkWidget *widget)
  *
  * This function does not act recursively. Setting the color of a
  * container does not affect its children. Note that some widgets that
- * you may not think of as containers, for instance #GtkButton<!-- -->s,
+ * you may not think of as containers, for instance #GtkButtons,
  * are actually containers.
  *
  * This API is mostly meant as a quick way for applications to
@@ -9437,7 +9436,7 @@ reset_style_recurse (GtkWidget *widget, gpointer data)
  * @widget: a #GtkWidget
  *
  * Updates the style context of @widget and all descendents
- * by updating its widget path. #GtkContainer<!-- -->s may want
+ * by updating its widget path. #GtkContainers may want
  * to use this on a child when reordering it in a way that a different
  * style might apply to it. See also gtk_container_get_path_for_child().
  *
@@ -10755,7 +10754,7 @@ gtk_widget_add_device_events (GtkWidget    *widget,
  * `gtk_widget_get_ancestor (widget, GTK_TYPE_WINDOW)`
  * would return
  * %NULL if @widget wasn’t inside a toplevel window, and if the
- * window was inside a #GtkWindow<!-- -->-derived widget which was in turn
+ * window was inside a #GtkWindow-derived widget which was in turn
  * inside the toplevel #GtkWindow. While the second case may
  * seem unlikely, it actually happens when a #GtkPlug is embedded
  * inside a #GtkSocket within the same application.
@@ -15140,7 +15139,7 @@ gtk_widget_get_support_multidevice (GtkWidget *widget)
  *
  * Enables or disables multiple pointer awareness. If this setting is %TRUE,
  * @widget will start receiving multiple, per device enter/leave events. Note
- * that if custom #GdkWindow<!-- -->s are created in #GtkWidget::realize,
+ * that if custom #GdkWindows are created in #GtkWidget::realize,
  * gdk_window_set_support_multidevice() will have to be called manually on them.
  *
  * Since: 3.0
diff --git a/gtk/gtkwidget.h b/gtk/gtkwidget.h
index 2291b44..bf47657 100644
--- a/gtk/gtkwidget.h
+++ b/gtk/gtkwidget.h
@@ -135,6 +135,8 @@ struct _GtkWidget
 {
   GInitiallyUnowned parent_instance;
 
+  /*< private >*/
+
   GtkWidgetPrivate *priv;
 };
 
diff --git a/gtk/gtkwidgetpath.c b/gtk/gtkwidgetpath.c
index b5c74b7..ca324d9 100644
--- a/gtk/gtkwidgetpath.c
+++ b/gtk/gtkwidgetpath.c
@@ -636,7 +636,7 @@ gtk_widget_path_iter_set_name (GtkWidgetPath *path,
  * @qname: widget name as a #GQuark
  *
  * See gtk_widget_path_iter_has_name(). This is a version
- * that operates on #GQuark<!-- -->s.
+ * that operates on #GQuarks.
  *
  * Returns: %TRUE if the widget at @pos has this name
  *
@@ -890,7 +890,7 @@ gtk_widget_path_iter_list_classes (const GtkWidgetPath *path,
  * @qname: class name as a #GQuark
  *
  * See gtk_widget_path_iter_has_class(). This is a version that operates
- * with GQuark<!-- -->s.
+ * with GQuarks.
  *
  * Returns: %TRUE if the widget at @pos has the class defined.
  *
@@ -1131,7 +1131,7 @@ gtk_widget_path_iter_list_regions (const GtkWidgetPath *path,
  * @flags: (out): return location for the region flags
  *
  * See gtk_widget_path_iter_has_region(). This is a version that operates
- * with GQuark<!-- -->s.
+ * with GQuarks.
  *
  * Returns: %TRUE if the widget at @pos has the region defined.
  *
diff --git a/gtk/gtkwindow.c b/gtk/gtkwindow.c
index fcc98c2..24f8215 100644
--- a/gtk/gtkwindow.c
+++ b/gtk/gtkwindow.c
@@ -92,10 +92,9 @@
  * # GtkWindow as GtkBuildable
  *
  * The GtkWindow implementation of the GtkBuildable interface supports a
- * custom `&lt;accel-groups&gt;` element, which supports
- * any number of `&lt;group&gt;` elements representing the
- * #GtkAccelGroup objects you want to add to your window (synonymous with
- * gtk_window_add_accel_group().
+ * custom <accel-groups> element, which supports any number of <group>
+ * elements representing the #GtkAccelGroup objects you want to add to
+ * your window (synonymous with gtk_window_add_accel_group().
  *
  * An example of a UI definition fragment with accel groups:
  * |[
@@ -110,9 +109,9 @@
  * <object class="GtkAccelGroup" id="accelgroup1"/>
  * ]|
  * 
- * The GtkWindow implementation of the GtkBuildable interface
- * supports setting a child as the titlebar by specifying “titlebar” as
- * the “type” attribute of a `&lt;child&gt;` element.
+ * The GtkWindow implementation of the GtkBuildable interface supports
+ * setting a child as the titlebar by specifying “titlebar” as the “type”
+ * attribute of a <child> element.
  */
 
 #define MNEMONICS_DELAY 300 /* ms */


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]