diff --git a/gio/gdbusaddress.c b/gio/gdbusaddress.c
index 421b180b8..349e1b73f 100644
--- a/gio/gdbusaddress.c
+++ b/gio/gdbusaddress.c
@@ -1452,15 +1452,16 @@ get_session_address_platform_specific (GError **error)
 
 /**
  * g_dbus_address_get_for_bus_sync:
- * @bus_type: A #GBusType.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
- * @error: Return location for error or %NULL.
+ * @bus_type: a #GBusType
+ * @cancellable: (allow-none): a #GCancellable or %NULL
+ * @error: return location for error or %NULL
  *
  * Synchronously looks up the D-Bus address for the well-known message
  * bus instance specified by @bus_type. This may involve using various
  * platform specific mechanisms.
  *
- * Returns: A valid D-Bus address string for @bus_type or %NULL if @error is set.
+ * Returns: a valid D-Bus address string for @bus_type or %NULL if
+ *     @error is set
  *
  * Since: 2.26
  */
@@ -1594,18 +1595,18 @@ g_dbus_address_get_for_bus_sync (GBusType       bus_type,
 /**
  * g_dbus_address_escape_value:
  * @string: an unescaped string to be included in a D-Bus address
- *  as the value in a key-value pair
+ *     as the value in a key-value pair
  *
  * Escape @string so it can appear in a D-Bus address as the value
  * part of a key-value pair.
  *
- * For instance, if @string is <code>/run/bus-for-:0</code>,
- * this function would return <code>/run/bus-for-%3A0</code>,
+ * For instance, if @string is "/run/bus-for-:0",
+ * this function would return "/run/bus-for-%3A0",
  * which could be used in a D-Bus address like
- * <code>unix:nonce-tcp:host=127.0.0.1,port=42,noncefile=/run/bus-for-%3A0</code>.
+ * "unix:nonce-tcp:host=127.0.0.1,port=42,noncefile=/run/bus-for-%3A0".
  *
  * Returns: (transfer full): a copy of @string with all
- *  non-optionally-escaped bytes escaped
+ *     non-optionally-escaped bytes escaped
  *
  * Since: 2.36
  */
diff --git a/glib/glib-init.c b/glib/glib-init.c
index 875844da3..9ca171f56 100644
--- a/glib/glib-init.c
+++ b/glib/glib-init.c
@@ -81,19 +81,19 @@ debug_key_matches (const gchar *key,
  * commas, or %NULL.
  * @keys: (array length=nkeys): pointer to an array of #GDebugKey which associate
  *     strings with bit flags.
- * @nkeys: the number of #GDebugKey<!-- -->s in the array.
+ * @nkeys: the number of #GDebugKeys in the array.
  *
  * Parses a string containing debugging options
  * into a %guint containing bit flags. This is used
  * within GDK and GTK+ to parse the debug options passed on the
  * command line or through environment variables.
  *
- * If @string is equal to <code>"all"</code>, all flags are set. Any flags
- * specified along with <code>"all"</code> in @string are inverted; thus,
- * <code>"all,foo,bar"</code> or <code>"foo,bar,all"</code> sets all flags
- * except those corresponding to <code>"foo"</code> and <code>"bar"</code>.
+ * If @string is equal to "all", all flags are set. Any flags
+ * specified along with "all" in @string are inverted; thus,
+ * "all,foo,bar" or "foo,bar,all" sets all flags except those
+ * corresponding to "foo" and "bar".
  *
- * If @string is equal to <code>"help"</code>, all the available keys in @keys
+ * If @string is equal to "help", all the available keys in @keys
  * are printed out to standard error.
  *
  * Returns: the combined set of bit flags.
diff --git a/glib/gvariant-parser.c b/glib/gvariant-parser.c
index bcc37b786..401784c7a 100644
--- a/glib/gvariant-parser.c
+++ b/glib/gvariant-parser.c
@@ -2486,7 +2486,10 @@ g_variant_new_parsed_va (const gchar *format,
  *
  * In the example, the variable argument parameters are collected and
  * filled in as if they were part of the original string to produce the
- * result of <code>[('one', 1), ('two', 2), ('three', 3)]</code>.
+ * result of
+ * |[
+ * [('one', 1), ('two', 2), ('three', 3)]
+ * ]|
  *
  * This function is intended only to be used with @format as a string
  * literal.  Any parse error is fatal to the calling process.  If you
diff --git a/glib/gvariant.c b/glib/gvariant.c
index 79849f0f3..69f4f5f86 100644
--- a/glib/gvariant.c
+++ b/glib/gvariant.c
@@ -1195,11 +1195,11 @@ g_variant_get_fixed_array (GVariant *value,
  * @value must be an array with fixed-sized elements.  Numeric types are
  * fixed-size as are tuples containing only other fixed-sized types.
  *
- * @element_size must be the size of a single element in the array.  For
- * example, if calling this function for an array of 32 bit integers,
- * you might say <code>sizeof (gint32)</code>.  This value isn't used
- * except for the purpose of a double-check that the form of the
- * serialised data matches the caller's expectation.
+ * @element_size must be the size of a single element in the array.
+ * For example, if calling this function for an array of 32-bit integers,
+ * you might say sizeof(gint32). This value isn't used except for the purpose
+ * of a double-check that the form of the serialised data matches the caller's
+ * expectation.
  *
  * @n_elements, which must be non-%NULL is set equal to the number of
  * items in the array.
diff --git a/gobject/gsignal.c b/gobject/gsignal.c
index d11206fb3..811502203 100644
--- a/gobject/gsignal.c
+++ b/gobject/gsignal.c
@@ -1370,9 +1370,8 @@ g_signal_query (guint         signal_id,
  * be used, but they cannot be mixed.
  *
  * If 0 is used for @class_offset subclasses cannot override the class handler
- * in their <code>class_init</code> method by doing
- * <code>super_class->signal_handler = my_signal_handler</code>. Instead they
- * will have to use g_signal_override_class_handler().
+ * in their class_init method by doing super_class->signal_handler = my_signal_handler.
+ * Instead they will have to use g_signal_override_class_handler().
  *
  * If c_marshaller is %NULL, g_cclosure_marshal_generic() will be used as
  * the marshaller for this signal.
diff --git a/gobject/gvaluearray.c b/gobject/gvaluearray.c
index 9cf3c1755..2b8d7f22f 100644
--- a/gobject/gvaluearray.c
+++ b/gobject/gvaluearray.c
@@ -295,8 +295,7 @@ g_value_array_insert (GValueArray  *value_array,
  * g_value_array_remove:
  * @value_array: #GValueArray to remove an element from
  * @index_: position of value to remove, which must be less than
- *          <code>value_array-><link
- *          linkend="GValueArray.n-values">n_values</link></code>
+ *     @value_array->n_values
  *
  * Remove the value at position @index_ from @value_array.
  *