docs: Another round of markup removal

16 files changed, 36 insertions, 48 deletions

diff --git a/gdk/gdkpango.c b/gdk/gdkpango.c
index e3fb0c6477..66615e8178 100644
--- a/gdk/gdkpango.c
+++ b/gdk/gdkpango.c
@@ -52,8 +52,6 @@
  *
  * ## Draw transformed text with Pango and cairo ## {#rotated-example}
  *
- * <!-- Note that this example is basically the same as
- *      demos/gtk-demo/rotated_text.c -->
  * |[<!-- language="C" -->
  * #define RADIUS 100
  * #define N_WORDS 10
@@ -67,9 +65,9 @@
  * int width, height;
  * int i;
  *
- * /<!---->* Set up a transformation matrix so that the user space coordinates for
- *  * where we are drawing are [-RADIUS, RADIUS], [-RADIUS, RADIUS]
- *  * We first center, then change the scale *<!---->/
+ * // Set up a transformation matrix so that the user space coordinates for
+ * // where we are drawing are [-RADIUS, RADIUS], [-RADIUS, RADIUS]
+ * // We first center, then change the scale
  *
  * width = gdk_window_get_width (window);
  * height = gdk_window_get_height (window);
@@ -80,7 +78,7 @@
  *                  radius + (height - 2 * radius) / 2);
  *                  cairo_scale (cr, radius / RADIUS, radius / RADIUS);
  *
- * /<!---->* Create a PangoLayout, set the font and text *<!---->/
+ * // Create a PangoLayout, set the font and text
  * context = gdk_pango_context_get_for_screen (screen);
  * layout = pango_layout_new (context);
  * pango_layout_set_text (layout, "Text", -1);
@@ -88,7 +86,7 @@
  * pango_layout_set_font_description (layout, desc);
  * pango_font_description_free (desc);
  *
- * /<!---->* Draw the layout N_WORDS times in a circle *<!---->/
+ * // Draw the layout N_WORDS times in a circle
  * for (i = 0; i < N_WORDS; i++)
  *   {
  *     double red, green, blue;
@@ -96,7 +94,7 @@
  *
  *     cairo_save (cr);
  *
- *     /<!---->* Gradient from red at angle == 60 to blue at angle == 300 *<!---->/
+ *     // Gradient from red at angle == 60 to blue at angle == 300
  *     red = (1 + cos (angle - 60)) / 2;
  *     green = 0;
  *     blue = 1 - red;
@@ -104,7 +102,7 @@
  *     cairo_set_source_rgb (cr, red, green, blue);
  *     cairo_rotate (cr, angle);
  *
- *     /<!---->* Inform Pango to re-layout the text with the new transformation matrix *<!---->/
+ *     // Inform Pango to re-layout the text with the new transformation matrix
  *     pango_cairo_update_layout (cr, layout);
  *
  *     pango_layout_get_size (layout, &width, &height);
diff --git a/gtk/deprecated/gtkaction.c b/gtk/deprecated/gtkaction.c
index 44e7f3c019..03ed26e02c 100644
--- a/gtk/deprecated/gtkaction.c
+++ b/gtk/deprecated/gtkaction.c
@@ -1356,7 +1356,7 @@ gtk_action_get_is_important (GtkAction *action)
  * @action: a #GtkAction
  * @always_show: %TRUE if menuitem proxies should always show their image
  *
- * Sets whether @action<!-- -->’s menu item proxies will ignore the
+ * Sets whether @action's menu item proxies will ignore the
  * #GtkSettings:gtk-menu-images setting and always show their image, if available.
  *
  * Use this if the menu item would be useless or hard to use
@@ -1391,7 +1391,7 @@ gtk_action_set_always_show_image (GtkAction *action,
  * gtk_action_get_always_show_image:
  * @action: a #GtkAction
  *
- * Returns whether @action<!-- -->’s menu item proxies will always
+ * Returns whether @action's menu item proxies will always
  * show their image, if available.
  *
  * Returns: %TRUE if the menu item proxies will always show their image
diff --git a/gtk/deprecated/gtkactiongroup.c b/gtk/deprecated/gtkactiongroup.c
index 113b3ee1da..737dbf1951 100644
--- a/gtk/deprecated/gtkactiongroup.c
+++ b/gtk/deprecated/gtkactiongroup.c
@@ -1477,7 +1477,7 @@ gtk_action_group_add_radio_actions_full (GtkActionGroup            *action_group
  *   destroyed and when the translation function is changed again
  *
  * Sets a function to be used for translating the @label and @tooltip of 
- * #GtkActionEntry<!-- -->s added by gtk_action_group_add_actions().
+ * #GtkActionEntrys added by gtk_action_group_add_actions().
  *
  * If you’re using gettext(), it is enough to set the translation domain
  * with gtk_action_group_set_translation_domain().
@@ -1524,7 +1524,7 @@ dgettext_swapped (const gchar *msgid,
  * calls, or %NULL to use the domain set with textdomain()
  * 
  * Sets the translation domain and uses g_dgettext() for translating the 
- * @label and @tooltip of #GtkActionEntry<!-- -->s added by 
+ * @label and @tooltip of #GtkActionEntrys added by 
  * gtk_action_group_add_actions().
  *
  * If you’re not using gettext() for localization, see 
diff --git a/gtk/deprecated/gtkiconfactory.c b/gtk/deprecated/gtkiconfactory.c
index 0bb8d4d87d..55e5d554b8 100644
--- a/gtk/deprecated/gtkiconfactory.c
+++ b/gtk/deprecated/gtkiconfactory.c
@@ -252,11 +252,11 @@ gtk_icon_factory_finalize (GObject *object)
  * gtk_icon_factory_new:
  *
  * Creates a new #GtkIconFactory. An icon factory manages a collection
- * of #GtkIconSet<!-- -->s; a #GtkIconSet manages a set of variants of a
+ * of #GtkIconSets; a #GtkIconSet manages a set of variants of a
  * particular icon (i.e. a #GtkIconSet contains variants for different
  * sizes and widget states). Icons in an icon factory are named by a
  * stock ID, which is a simple string identifying the icon. Each
- * #GtkStyle has a list of #GtkIconFactory<!-- -->s derived from the current
+ * #GtkStyle has a list of #GtkIconFactorys derived from the current
  * theme; those icon factories are consulted first when searching for
  * an icon. If the theme doesn’t set a particular icon, GTK+ looks for
  * the icon in a list of default icon factories, maintained by
@@ -2149,7 +2149,7 @@ gtk_icon_source_get_icon_name (const GtkIconSource *source)
  * In addition, if a filename source is in use, this
  * function in some cases will return the pixbuf from
  * loaded from the filename. This is, for example, true
- * for the GtkIconSource passed to the #GtkStyle render_icon(<!-- -->)
+ * for the GtkIconSource passed to the #GtkStyle render_icon()
  * virtual function. The reference count on the pixbuf is
  * not incremented.
  *
diff --git a/gtk/deprecated/gtkradioaction.c b/gtk/deprecated/gtkradioaction.c
index b4c724e45a..7ee120fe3a 100644
--- a/gtk/deprecated/gtkradioaction.c
+++ b/gtk/deprecated/gtkradioaction.c
@@ -164,7 +164,7 @@ gtk_radio_action_class_init (GtkRadioActionClass *klass)
   /**
    * GtkRadioAction::changed:
    * @action: the action on which the signal is emitted
-   * @current: the member of @action<!-- -->s group which has just been activated
+   * @current: the member of @action's group which has just been activated
    *
    * The ::changed signal is emitted on every member of a radio group when the
    * active member is changed. The signal gets emitted after the ::activate signals
diff --git a/gtk/deprecated/gtkrc.c b/gtk/deprecated/gtkrc.c
index 7239527194..8d12517011 100644
--- a/gtk/deprecated/gtkrc.c
+++ b/gtk/deprecated/gtkrc.c
@@ -462,7 +462,7 @@
  * the range 0-65535 or floats in the range 0.0-1.0.
  *
  * Since 2.10, colors can also be specified by refering to a symbolic color, as
- * follows: `@<!-- -->color-name`, or by using expressions to combine
+ * follows: `@color-name`, or by using expressions to combine
  * colors. The following expressions are currently supported:
  *
  * * mix (factor, color1, color2)
@@ -494,7 +494,7 @@
  * |[
  *  mix (0.5, "red", "blue")
  *  shade (1.5, mix (0.3, "#0abbc0", { 0.3, 0.5, 0.9 }))
- *  lighter (@<!-- -->foreground)
+ *  lighter (@foreground)
  * ]|
  *
  * In a `stock` definition, icon sources are specified as a
diff --git a/gtk/deprecated/gtkuimanager.c b/gtk/deprecated/gtkuimanager.c
index b8ecb8ab95..772d65377f 100644
--- a/gtk/deprecated/gtkuimanager.c
+++ b/gtk/deprecated/gtkuimanager.c
@@ -2225,7 +2225,7 @@ remove_ui (GNode   *node,
  * @manager: a #GtkUIManager object
  * @merge_id: a merge id as returned by gtk_ui_manager_add_ui_from_string()
  * 
- * Unmerges the part of @manager<!-- -->s content identified by @merge_id.
+ * Unmerges the part of @manager's content identified by @merge_id.
  *
  * Since: 2.4
  *
diff --git a/gtk/gtkbuildable.h b/gtk/gtkbuildable.h
index 46ec63f0cc..9652a5edf4 100644
--- a/gtk/gtkbuildable.h
+++ b/gtk/gtkbuildable.h
@@ -58,15 +58,15 @@ typedef struct _GtkBuildableIface GtkBuildableIface;
  *  is created.
  * @construct_child: Constructs a child of a buildable that has been
  *  specified as “constructor” in the UI definition. #GtkUIManager implements
- *  this to reference to a widget created in a &lt;ui&gt; tag which is outside
+ *  this to reference to a widget created in a <ui> tag which is outside
  *  of the normal GtkBuilder UI definition hierarchy.  A reference to the
  *  constructed object is returned and becomes owned by the caller.
  * @custom_tag_start: Implement this if the buildable needs to parse
- *  content below &lt;child&gt;. To handle an element, the implementation
+ *  content below <child>. To handle an element, the implementation
  *  must fill in the @parser and @user_data and return %TRUE.
  *  #GtkWidget implements this to parse keyboard accelerators specified
- *  in &lt;accelerator&gt; elements. #GtkContainer implements it to map
- *  properties defined via &lt;packing&gt; elements to child properties.
+ *  in <accelerator> elements. #GtkContainer implements it to map
+ *  properties defined via <packing> elements to child properties.
  *  Note that @user_data must be freed in @custom_tag_end or @custom_finished.
  * @custom_tag_end: Called for the end tag of each custom element that is
  *  handled by the buildable (see @custom_tag_start).
diff --git a/gtk/gtkbutton.c b/gtk/gtkbutton.c
index 4c17f90bb0..aff698e3a8 100644
--- a/gtk/gtkbutton.c
+++ b/gtk/gtkbutton.c
@@ -1474,8 +1474,6 @@ gtk_button_leave (GtkButton *button)
  * Sets the relief style of the edges of the given #GtkButton widget.
  * Three styles exist, GTK_RELIEF_NORMAL, GTK_RELIEF_HALF, GTK_RELIEF_NONE.
  * The default style is, as one can guess, GTK_RELIEF_NORMAL.
- *
- * <!-- FIXME: put pictures of each style -->
  */
 void
 gtk_button_set_relief (GtkButton *button,
diff --git a/gtk/gtkcellarea.h b/gtk/gtkcellarea.h
index ed73d99da0..eaa63732a7 100644
--- a/gtk/gtkcellarea.h
+++ b/gtk/gtkcellarea.h
@@ -46,13 +46,13 @@ typedef struct _GtkCellAreaContext       GtkCellAreaContext;
 
 /**
  * GTK_CELL_AREA_WARN_INVALID_CELL_PROPERTY_ID:
- * @object: the #GObject on which set_cell_property(<!-- -->) or get_cell_property(<!-- -->)
+ * @object: the #GObject on which set_cell_property() or get_cell_property()
  *     was called
  * @property_id: the numeric id of the property
  * @pspec: the #GParamSpec of the property
  *
  * This macro should be used to emit a standard warning about unexpected
- * properties in set_cell_property(<!-- -->) and get_cell_property(<!-- -->) implementations.
+ * properties in set_cell_property() and get_cell_property() implementations.
  */
 #define GTK_CELL_AREA_WARN_INVALID_CELL_PROPERTY_ID(object, property_id, pspec) \
   G_OBJECT_WARN_INVALID_PSPEC ((object), "cell property id", (property_id), (pspec))
diff --git a/gtk/gtkcontainer.h b/gtk/gtkcontainer.h
index ebc5b570fa..6572306903 100644
--- a/gtk/gtkcontainer.h
+++ b/gtk/gtkcontainer.h
@@ -253,13 +253,13 @@ void gtk_container_child_notify (GtkContainer *container,
 
 /**
  * GTK_CONTAINER_WARN_INVALID_CHILD_PROPERTY_ID:
- * @object: the #GObject on which set_child_property(<!-- -->) or get_child_property(<!-- -->)
+ * @object: the #GObject on which set_child_property() or get_child_property()
  *  was called
  * @property_id: the numeric id of the property
  * @pspec: the #GParamSpec of the property
  *
  * This macro should be used to emit a standard warning about unexpected
- * properties in set_child_property(<!-- -->) and get_child_property(<!-- -->) implementations.
+ * properties in set_child_property() and get_child_property() implementations.
  */
 #define GTK_CONTAINER_WARN_INVALID_CHILD_PROPERTY_ID(object, property_id, pspec) \
     G_OBJECT_WARN_INVALID_PSPEC ((object), "child property", (property_id), (pspec))
diff --git a/gtk/gtkentrycompletion.h b/gtk/gtkentrycompletion.h
index fd49aecdda..69f74c8629 100644
--- a/gtk/gtkentrycompletion.h
+++ b/gtk/gtkentrycompletion.h
@@ -54,7 +54,7 @@ typedef struct _GtkEntryCompletionPrivate     GtkEntryCompletionPrivate;
  * Note that @key is normalized and case-folded (see g_utf8_normalize()
  * and g_utf8_casefold()). If this is not appropriate, match functions
  * have access to the unmodified key via
- * `gtk_entry_get_text (GTK_ENTRY (gtk_entry_completion_get_entry (<!-- -->)))`.
+ * `gtk_entry_get_text (GTK_ENTRY (gtk_entry_completion_get_entry ()))`.
  *
  * Returns: %TRUE if @iter should be displayed as a possible completion
  *     for @key
diff --git a/gtk/gtkmenu.c b/gtk/gtkmenu.c
index acebe7626c..63bc72d713 100644
--- a/gtk/gtkmenu.c
+++ b/gtk/gtkmenu.c
@@ -46,7 +46,7 @@
  * ## Connecting the popup signal handler.
  *
  * |[<!-- language="C" -->
- *   /<!---->* connect our handler which will popup the menu *<!---->/
+ *   // connect our handler which will popup the menu
  *   g_signal_connect_swapped (window, "button_press_event",
  *	G_CALLBACK (my_popup_handler), menu);
  * ]|
@@ -64,9 +64,8 @@
  *   g_return_val_if_fail (GTK_IS_MENU (widget), FALSE);
  *   g_return_val_if_fail (event != NULL, FALSE);
  *
- *   /<!---->* The "widget" is the menu that was supplied when 
- *    * g_signal_connect_swapped() was called.
- *    *<!---->/
+ *   // The "widget" is the menu that was supplied when 
+ *   // g_signal_connect_swapped() was called.
  *   menu = GTK_MENU (widget);
  *
  *   if (event->type == GDK_BUTTON_PRESS)
diff --git a/gtk/gtkmodules.h b/gtk/gtkmodules.h
index fbc575c222..29409b7041 100644
--- a/gtk/gtkmodules.h
+++ b/gtk/gtkmodules.h
@@ -32,9 +32,8 @@ G_BEGIN_DECLS
  * @argc: (allow-none): GTK+ always passes %NULL for this argument
  * @argv: (allow-none) (array length=argc): GTK+ always passes %NULL for this argument
  *
- * Each GTK+ module must have a function gtk_module_init(<!-- -->)
- * with this prototype. This function is called after loading
- * the module.
+ * Each GTK+ module must have a function gtk_module_init() with this prototype.
+ * This function is called after loading the module.
  */
 typedef void     (*GtkModuleInitFunc)        (gint        *argc,
                                               gchar      ***argv);
@@ -43,9 +42,8 @@ typedef void     (*GtkModuleInitFunc)        (gint        *argc,
  * GtkModuleDisplayInitFunc:
  * @display: an open #GdkDisplay
  *
- * A multihead-aware GTK+ module may have a gtk_module_display_init(<!-- -->)
- * function with this prototype. GTK+ calls this function for each
- * opened display.
+ * A multihead-aware GTK+ module may have a gtk_module_display_init() function
+ * with this prototype. GTK+ calls this function for each opened display.
  *
  * Since: 2.2
  */
diff --git a/gtk/gtkprintsettings.c b/gtk/gtkprintsettings.c
index 160af5b3fc..f2cf860184 100644
--- a/gtk/gtkprintsettings.c
+++ b/gtk/gtkprintsettings.c
@@ -45,12 +45,9 @@
  * document. The predefined keys try to use shared values as much as possible
  * so that moving such a document between systems still works.
  *
- * <!-- TODO example of getting, storing and setting settings -->
- *
  * Printing support was added in GTK+ 2.10.
  */
 
-
 typedef struct _GtkPrintSettingsClass GtkPrintSettingsClass;
 
 #define GTK_IS_PRINT_SETTINGS_CLASS(klass)  (G_TYPE_CHECK_CLASS_TYPE ((klass), GTK_TYPE_PRINT_SETTINGS))
@@ -1568,7 +1565,6 @@ gtk_print_settings_set_default_source (GtkPrintSettings *settings,
  * Gets the value of %GTK_PRINT_SETTINGS_MEDIA_TYPE.
  *
  * The set of media types is defined in PWG 5101.1-2002 PWG.
- * <!-- FIXME link here -->
  * 
  * Returns: the media type
  *
@@ -1588,7 +1584,6 @@ gtk_print_settings_get_media_type (GtkPrintSettings *settings)
  * Sets the value of %GTK_PRINT_SETTINGS_MEDIA_TYPE.
  * 
  * The set of media types is defined in PWG 5101.1-2002 PWG.
- * <!-- FIXME link here -->
  *
  * Since: 2.10
  */
diff --git a/gtk/gtkstylecontext.h b/gtk/gtkstylecontext.h
index c188604fa5..1bab4394d6 100644
--- a/gtk/gtkstylecontext.h
+++ b/gtk/gtkstylecontext.h
@@ -101,7 +101,7 @@ struct _GtkStyleContextClass
  * padding/border/margin series.
  *
  * gtk_render_frame() uses this property to find out the frame line width,
- * so #GtkWidget<!-- -->s rendering frames may need to add up this padding when
+ * so #GtkWidgets rendering frames may need to add up this padding when
  * requesting size
  */
 #define GTK_STYLE_PROPERTY_BORDER_WIDTH "border-width"
@@ -111,7 +111,7 @@ struct _GtkStyleContextClass
  *
  * A property holding the rendered element’s margin as a #GtkBorder. The
  * margin is defined as the spacing between the border of the element
- * and its surrounding elements. It is external to #GtkWidget<!-- -->s's
+ * and its surrounding elements. It is external to #GtkWidget's
  * size allocations, and the most external spacing property of the
  * padding/border/margin series.
  */