diff --git a/gio/gasyncresult.c b/gio/gasyncresult.c
index 1be90bf3b..0c18b0b40 100644
--- a/gio/gasyncresult.c
+++ b/gio/gasyncresult.c
@@ -102,14 +102,15 @@
  * always called, even in the case of a cancelled operation. On cancellation
  * the result is a %G_IO_ERROR_CANCELLED error.
  *
- * <para id="io-priority">
+ * ## I/O Priority # {#io-priority}
+ *
  * Many I/O-related asynchronous operations have a priority parameter,
  * which is used in certain cases to determine the order in which
  * operations are executed. They are not used to determine system-wide
  * I/O scheduling. Priorities are integers, with lower numbers indicating
  * higher priority. It is recommended to choose priorities between
  * %G_PRIORITY_LOW and %G_PRIORITY_HIGH, with %G_PRIORITY_DEFAULT
- * as a default.</para>
+ * as a default.
  */
 
 typedef GAsyncResultIface GAsyncResultInterface;
diff --git a/gio/gfile.c b/gio/gfile.c
index 75b3e5826..f70bddf2f 100644
--- a/gio/gfile.c
+++ b/gio/gfile.c
@@ -137,7 +137,8 @@
  * <member>g_file_eject_mountable_with_operation() to eject a mountable file.</member>
  * </simplelist>
  *
- * <para id="gfile-etag">
+ * ## Entity Tags # {#gfile-etag}
+ *
  * One notable feature of #GFiles are entity tags, or "etags" for
  * short. Entity tags are somewhat like a more abstract version of the
  * traditional mtime, and can be used to quickly determine if the file
@@ -145,8 +146,7 @@
  * HTTP 1.1 
  * [specification](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html)
  * for HTTP Etag headers, which are a very similar concept.
- * </para>
- **/
+ */
 
 static void               g_file_real_query_info_async            (GFile                  *file,
                                                                    const char             *attributes,
diff --git a/gio/gvolume.c b/gio/gvolume.c
index 87830233d..5e3266c3d 100644
--- a/gio/gvolume.c
+++ b/gio/gvolume.c
@@ -57,7 +57,8 @@
  * successfully.  If an @error is present when g_volume_mount_finish()
  * is called, then it will be filled with any error information.
  *
- * <para id="volume-identifier">
+ * ## Volume Identifiers # {#volume-identifier}
+ *
  * It is sometimes necessary to directly access the underlying
  * operating system object behind a volume (e.g. for passing a volume
  * to an application via the commandline). For this purpose, GIO
@@ -67,7 +68,7 @@
  * strings as names for the different kinds of identifiers:
  * #G_VOLUME_IDENTIFIER_KIND_HAL_UDI, #G_VOLUME_IDENTIFIER_KIND_LABEL, etc.
  * Use g_volume_get_identifier() to obtain an identifier for a volume.
- * </para>
+ *
  *
  * Note that #G_VOLUME_IDENTIFIER_KIND_HAL_UDI will only be available
  * when the gvfs hal volume monitor is in use. Other volume monitors
diff --git a/glib/gstrfuncs.c b/glib/gstrfuncs.c
index bebb2cbbc..877cb4dd4 100644
--- a/glib/gstrfuncs.c
+++ b/glib/gstrfuncs.c
@@ -70,7 +70,8 @@
  * explicitly include `&lt;glib/gprintf.h&gt;` in order to use the GLib
  * printf() functions.
  *
- * <para id="string-precision">
+ * ## String precision pitfalls # {#string-precision}
+ *
  * While you may use the printf() functions to format UTF-8 strings,
  * notice that the precision of a &percnt;Ns parameter is interpreted
  * as the number of bytes, not characters to print. On top of that,
@@ -83,7 +84,6 @@
  * certain number of columns, then &percnt;Ns is not a correct solution
  * anyway, since it fails to take wide characters (see g_unichar_iswide())
  * into account.
- * </para>
  */
 
 /**
diff --git a/gobject/gobject.c b/gobject/gobject.c
index 2a8831377..f2f9fe72f 100644
--- a/gobject/gobject.c
+++ b/gobject/gobject.c
@@ -46,7 +46,8 @@
  * support.  Signals are described in detail in <xref
  * linkend="gobject-Signals"/>.
  *
- * <para id="floating-ref">
+ * ## Floating references # {#floating-ref}
+ *
  * GInitiallyUnowned is derived from GObject. The only difference between
  * the two is that the initial reference of a GInitiallyUnowned is flagged
  * as a "floating" reference. This means that it is not specifically
@@ -78,7 +79,6 @@
  * language bindings that provide automated reference and memory ownership
  * maintenance (such as smart pointers or garbage collection) should not
  * expose floating references in their API.
- * </para>
  *
  * Some object implementations may need to save an objects floating state
  * across certain code portions (an example is #GtkMenu), to achieve this,
diff --git a/gobject/gparam.c b/gobject/gparam.c
index bdf90f8fe..80a553ba3 100644
--- a/gobject/gparam.c
+++ b/gobject/gparam.c
@@ -39,13 +39,13 @@
  * #GParamSpec is an object structure that encapsulates the metadata
  * required to specify parameters, such as e.g. #GObject properties.
  *
- * <para id="canonical-parameter-name">
- * Parameter names need to start with a letter (a-z or A-Z). Subsequent
- * characters can be letters, numbers or a '-'.
+ * ## Parameter names # {#canonical-parameter-names}
+ *
+ * Parameter names need to start with a letter (a-z or A-Z).
+ * Subsequent characters can be letters, numbers or a '-'.
  * All other characters are replaced by a '-' during construction.
- * The result of this replacement is called the canonical name of the
- * parameter.
- * </para>
+ * The result of this replacement is called the canonical name of
+ * the parameter.
  */