docs: Port to MarkDown

Drop the DocBook documentation, and move everything to the MarkDown
format used by modern gtk-doc.

15 files changed, 181 insertions, 248 deletions

diff --git a/json-glib/json-array.c b/json-glib/json-array.c
index 9108a72..1639426 100644
--- a/json-glib/json-array.c
+++ b/json-glib/json-array.c
@@ -32,7 +32,7 @@
  * @short_description: a JSON array representation
  *
  * #JsonArray is the representation of the array type inside JSON. It contains
- * #JsonNode<!-- -->s, which may contain fundamental types, other arrays or
+ * #JsonNode elements, which may contain fundamental types, other arrays or
  * objects.
  *
  * Since arrays can be expensive, they are reference counted. You can control
@@ -139,7 +139,7 @@ json_array_unref (JsonArray *array)
  * json_array_get_elements:
  * @array: a #JsonArray
  *
- * Gets the elements of a #JsonArray as a list of #JsonNode<!-- -->s.
+ * Gets the elements of a #JsonArray as a list of #JsonNode instances.
  *
  * Return value: (element-type JsonNode) (transfer container): a #GList
  *   containing the elements of the array. The contents of the list are
diff --git a/json-glib/json-builder.c b/json-glib/json-builder.c
index c190b12..b75b3c2 100644
--- a/json-glib/json-builder.c
+++ b/json-glib/json-builder.c
@@ -171,7 +171,7 @@ json_builder_is_valid_add_mode (JsonBuilder *builder)
  * json_builder_new:
  *
  * Creates a new #JsonBuilder. You can use this object to generate a
- * JSON tree and obtain the root #JsonNode<!-- -->s.
+ * JSON tree and obtain the root #JsonNode.
  *
  * Return value: the newly created #JsonBuilder instance
  */
diff --git a/json-glib/json-builder.h b/json-glib/json-builder.h
index 093f67c..361c64a 100644
--- a/json-glib/json-builder.h
+++ b/json-glib/json-builder.h
@@ -45,8 +45,8 @@ typedef struct _JsonBuilderClass      JsonBuilderClass;
 /**
  * JsonBuilder:
  *
- * The <structname>JsonBuilder</structname> structure contains only
- * private data and shouls be accessed using the provided API
+ * The `JsonBuilder` structure contains only private data and should be
+ * accessed using the provided API
  *
  * Since: 0.12
  */
@@ -61,8 +61,7 @@ struct _JsonBuilder
 /**
  * JsonBuilderClass:
  *
- * The <structname>JsonBuilder</structname> structure contains only
- * private data
+ * The `JsonBuilderClass` structure contains only private data
  *
  * Since: 0.12
  */
diff --git a/json-glib/json-gboxed.c b/json-glib/json-gboxed.c
index 8f21f75..0caac04 100644
--- a/json-glib/json-gboxed.c
+++ b/json-glib/json-gboxed.c
@@ -32,7 +32,7 @@
  * When registering a #GBoxed type you should also register the
  * corresponding transformation functions, e.g.:
  *
- * |[
+ * |[<!-- language="C" -->
  *   GType
  *   my_struct_get_type (void)
  *   {
diff --git a/json-glib/json-generator.c b/json-glib/json-generator.c
index c5caa64..276f3a6 100644
--- a/json-glib/json-generator.c
+++ b/json-glib/json-generator.c
@@ -547,7 +547,7 @@ dump_object (JsonGenerator *generator,
  * 
  * Creates a new #JsonGenerator. You can use this object to generate a
  * JSON data stream starting from a data object model composed by
- * #JsonNode<!-- -->s.
+ * #JsonNodes.
  *
  * Return value: the newly created #JsonGenerator instance
  */
@@ -686,8 +686,8 @@ json_generator_to_stream (JsonGenerator  *generator,
  * Sets @node as the root of the JSON data stream to be serialized by
  * the #JsonGenerator.
  *
- * <note>The node is copied by the generator object, so it can be safely
- * freed after calling this function.</note>
+ * The passed @node is copied by the generator object, so it can be
+ * safely freed after calling this function.
  */
 void
 json_generator_set_root (JsonGenerator *generator,
@@ -695,6 +695,9 @@ json_generator_set_root (JsonGenerator *generator,
 {
   g_return_if_fail (JSON_IS_GENERATOR (generator));
 
+  if (generator->priv->root == node)
+    return;
+
   if (generator->priv->root != NULL)
     {
       json_node_free (generator->priv->root);
diff --git a/json-glib/json-gobject.c b/json-glib/json-gobject.c
index 8b89fb5..0ab79c1 100644
--- a/json-glib/json-gobject.c
+++ b/json-glib/json-gobject.c
@@ -21,8 +21,8 @@
  * SECTION:json-gobject
  * @short_description: Serialize and deserialize GObjects
  *
- * JSON-GLib provides API for serializing and deserializing #GObject<!-- -->s
- * to and from JSON data streams.
+ * JSON-GLib provides API for serializing and deserializing #GObject
+ * instances to and from JSON data streams.
  *
  * Simple #GObject classes can be (de)serialized into JSON objects, if the
  * properties have compatible types with the native JSON types (integers,
diff --git a/json-glib/json-gobject.h b/json-glib/json-gobject.h
index c19c457..dc1fac6 100644
--- a/json-glib/json-gobject.h
+++ b/json-glib/json-gobject.h
@@ -50,7 +50,7 @@ typedef struct _JsonSerializableIface   JsonSerializableIface;
  * @set_property: virtual function for setting a property
  * @get_property: virtual function for getting a property
  *
- * Interface that allows serializing and deserializing #GObject<!-- -->s
+ * Interface that allows serializing and deserializing #GObject instances
  * with properties storing complex data types. The json_serialize_gobject()
  * function will check if the passed #GObject implements this interface,
  * so it can also be used to override the default property serialization
diff --git a/json-glib/json-gvariant.c b/json-glib/json-gvariant.c
index 41b6f43..99e6d64 100644
--- a/json-glib/json-gvariant.c
+++ b/json-glib/json-gvariant.c
@@ -51,49 +51,29 @@
  * JSON, a #GVariant type string (signature) should be provided to these
  * methods in order to obtain a correct, type-contrained result.
  * If no signature is provided, conversion can still be done, but the
- * resulting #GVariant value will be "guessed" from the JSON data types,
- * according to the following table:
+ * resulting #GVariant value will be "guessed" from the JSON data types
+ * using the following rules:
  *
- * <table frame='all'><title>Default JSON to GVariant conversion (without signature constrains)</title>
- *  <tgroup cols='2' align='left' colsep='1' rowsep='1'>
- *   <thead>
- *     <row>
- *       <entry>JSON</entry>
- *       <entry>GVariant</entry>
- *     </row>
- *   </thead>
- *   <tfoot>
- *    <row>
- *     <entry>string</entry>
- *     <entry>string (s)</entry>
- *    </row>
- *    <row>
- *     <entry>int64</entry>
- *     <entry>int64 (x)</entry>
- *    </row>
- *    <row>
- *     <entry>boolean</entry>
- *     <entry>boolean (b)</entry>
- *    </row>
- *    <row>
- *     <entry>double</entry>
- *     <entry>double (d)</entry>
- *    </row>
- *    <row>
- *     <entry>array</entry>
- *     <entry>array of variants (av)</entry>
- *    </row>
- *    <row>
- *     <entry>object</entry>
- *     <entry>dictionary of string-variant (a{sv})</entry>
- *    </row>
- *    <row>
- *     <entry>null</entry>
- *     <entry>maybe variant (mv)</entry>
- *    </row>
- *   </tfoot>
- *  </tgroup>
- * </table>
+ * ## Strings
+ * JSON strings map to GVariant `(s)`.
+ *
+ * ## Integers
+ * JSON integers map to GVariant int64 `(x)`.
+ *
+ * ## Booleans
+ * JSON booleans map to GVariant boolean `(b)`.
+ *
+ * ## Numbers
+ * JSON numbers map to GVariant double `(d)`.
+ *
+ * ## Arrays
+ * JSON arrays map to GVariant arrays of variants `(av)`.
+ *
+ * ## Objects
+ * JSON objects map to GVariant dictionaries of string to variants `(a{sv})`.
+ *
+ * ## Null values
+ * JSON null values map to GVariant maybe variants `(mv)`.
  */
 
 /* custom extension to the GVariantClass enumeration to differentiate
diff --git a/json-glib/json-node.c b/json-glib/json-node.c
index e5a66a7..fd89716 100644
--- a/json-glib/json-node.c
+++ b/json-glib/json-node.c
@@ -342,7 +342,7 @@ json_node_init_null (JsonNode *node)
 }
 
 /**
- * json_node_new:
+ * json_node_new: (constructor)
  * @type: a #JsonNodeType
  *
  * Creates a new #JsonNode of @type.
@@ -350,11 +350,11 @@ json_node_init_null (JsonNode *node)
  * This is a convenience function for json_node_alloc() and json_node_init(),
  * and it's the equivalent of:
  *
- * |[
- *   return json_node_init (json_node_alloc (), type);
+ * |[<!-- language="C" -->
+     json_node_init (json_node_alloc (), type);
  * ]|
  *
- * Return value: the newly created #JsonNode
+ * Return value: (transfer full): the newly created #JsonNode
  */
 JsonNode *
 json_node_new (JsonNodeType type)
@@ -1022,9 +1022,10 @@ json_node_get_node_type (JsonNode *node)
  * json_node_is_null:
  * @node: a #JsonNode
  *
- * Checks whether @node is a %JSON_NODE_NULL
+ * Checks whether @node is a %JSON_NODE_NULL.
  *
- * <note>A null node is not the same as a %NULL #JsonNode</note>
+ * A %JSON_NODE_NULL node is not the same as a %NULL #JsonNode; a
+ * %JSON_NODE_NULL represents a 'null' value in the JSON tree.
  *
  * Return value: %TRUE if the node is null
  *
diff --git a/json-glib/json-object.c b/json-glib/json-object.c
index 95d2e86..d134421 100644
--- a/json-glib/json-object.c
+++ b/json-glib/json-object.c
@@ -35,9 +35,10 @@
  * SECTION:json-object
  * @short_description: a JSON object representation
  *
- * #JsonObject is the representation of the object type inside JSON. It contains
- * #JsonNode<!-- -->s, which may contain fundamental types, arrays or other
- * objects. Each member of an object is accessed using its name.
+ * #JsonObject is the representation of the object type inside JSON. It
+ * contains #JsonNodes, which may contain fundamental types, arrays or other
+ * objects; each node inside an object, or "member", is accessed using a
+ * unique string, or "name".
  *
  * Since objects can be expensive, they are reference counted. You can control
  * the lifetime of a #JsonObject using json_object_ref() and json_object_unref().
@@ -449,7 +450,7 @@ json_object_get_members (JsonObject *object)
  * Retrieves all the values of the members of a #JsonObject.
  *
  * Return value: (element-type JsonNode) (transfer container): a #GList of
- *   #JsonNode<!-- -->s. The content of the list is owned by the #JsonObject
+ *   #JsonNodes. The content of the list is owned by the #JsonObject
  *   and should never be modified or freed. When you have finished using the
  *   returned list, use g_list_free() to free the resources it has allocated.
  */
diff --git a/json-glib/json-path.c b/json-glib/json-path.c
index f829433..e212f87 100644
--- a/json-glib/json-path.c
+++ b/json-glib/json-path.c
@@ -40,162 +40,114 @@
  * The simple convenience function json_path_query() can be used for one-off
  * matching.
  *
- * <refsect2 id="json-path-syntax">
- *   <title>Syntax of the JSONPath expressions</title>
- *   <para>A JSONPath expression is composed by path indices and operators.
- *   Each path index can either be a member name or an element index inside
- *   a JSON tree. A JSONPath expression must start with the '$' operator; each
- *   path index is separated using either the dot notation or the bracket
- *   notation, e.g.:</para>
- *   |[
- *     /&ast; dot notation &ast;/
- *     $.store.book[0].title
- *     /&ast; bracket notation &ast;/
- *     $['store']['book'][0]['title']
- *   ]|
- *   <para>The available operators are:</para>
- *   <table frame='all' id="json-path-operators">
- *     <title>Operators</title>
- *     <tgroup cols='4'>
- *       <colspec name='operator'/>
- *       <colspec name='description'/>
- *       <colspec name='example'/>
- *       <colspec name='results'/>
- *       <thead>
- *         <row>
- *           <entry>Operator</entry>
- *           <entry>Description</entry>
- *           <entry>Example</entry>
- *           <entry>Results</entry>
- *         </row>
- *       </thead>
- *       <tbody>
- *         <row>
- *           <entry>$</entry>
- *           <entry>The root node</entry>
- *           <entry>$</entry>
- *           <entry>The whole document</entry>
- *         </row>
- *         <row>
- *           <entry>. or []</entry>
- *           <entry>The child member or element</entry>
- *           <entry>$.store.book</entry>
- *           <entry>The contents of the book member of the store object</entry>
- *         </row>
- *         <row>
- *           <entry>..</entry>
- *           <entry>Recursive descent</entry>
- *           <entry>$..author</entry>
- *           <entry>The content of the author member in every object</entry>
- *         </row>
- *         <row>
- *           <entry>*</entry>
- *           <entry>Wildcard</entry>
- *           <entry>$.store.book[*].author</entry>
- *           <entry>The content of the author member of any object of the
- *           array contained in the book member of the store object</entry>
- *         </row>
- *         <row>
- *           <entry>[]</entry>
- *           <entry>Subscript</entry>
- *           <entry>$.store.book[0]</entry>
- *           <entry>The first element of the array contained in the book
- *           member of the store object</entry>
- *         </row>
- *         <row>
- *           <entry>[,]</entry>
- *           <entry>Set</entry>
- *           <entry>$.store.book[0,1]</entry>
- *           <entry>The first two elements of the array contained in the
- *           book member of the store object</entry>
- *         </row>
- *         <row>
- *           <entry>[start:end:step]</entry>
- *           <entry>Slice</entry>
- *           <entry>$.store.book[:2]</entry>
- *           <entry>The first two elements of the array contained in the
- *           book member of the store object; the start and step are omitted
- *           and implied to be 0 and 1, respectively</entry>
- *         </row>
- *       </tbody>
- *     </tgroup>
- *   </table>
- *   <para>More information about JSONPath is available on Stefan Gössner's
- *   <ulink url="http://goessner.net/articles/JsonPath/">website</ulink>.</para>
- * </refsect2>
+ * ## Syntax of the JSONPath expressions ##
  *
- * <example id="json-path-example">
- *   <title>Example of JsonPath usage</title>
- *   <para>The following example shows some of the results of using #JsonPath
- *   on a JSON tree. We use the following JSON description of a
- *   bookstore:</para>
- * <programlisting><![CDATA[
-{ "store": {
-    "book": [
-      { "category": "reference",
-        "author": "Nigel Rees",
-        "title": "Sayings of the Century",
-        "price": "8.95"
-      },
-      { "category": "fiction",
-        "author": "Evelyn Waugh",
-        "title": "Sword of Honour",
-        "price": "12.99"
-      },
-      { "category": "fiction",
-        "author": "Herman Melville",
-        "title": "Moby Dick",
-        "isbn": "0-553-21311-3",
-        "price": "8.99"
-      },
-      { "category": "fiction",
-        "author": "J. R. R. Tolkien",
-        "title": "The Lord of the Rings",
-        "isbn": "0-395-19395-8",
-        "price": "22.99"
-      }
-    ],
-    "bicycle": {
-      "color": "red",
-      "price": "19.95"
-    }
-  }
-}
-]]></programlisting>
- *   <para>We can parse the JSON using #JsonParser:</para>
- *   <programlisting>
- * JsonParser *parser = json_parser_new ();
- * json_parser_load_from_data (parser, json_data, -1, NULL);
- *   </programlisting>
- *   <para>If we run the following code:</para>
- *   <programlisting>
- * JsonNode *result;
- * JsonPath *path = json_path_new ();
- * json_path_compile (path, "$.store..author", NULL);
- * result = json_path_match (path, json_parser_get_root (parser));
- *   </programlisting>
- *   <para>The <emphasis>result</emphasis> #JsonNode will contain an array
- *   with all values of the <emphasis>author</emphasis> member of the objects
- *   in the JSON tree. If we use a #JsonGenerator to convert the #JsonNode
- *   to a string and print it:</para>
- *   <programlisting>
- * JsonGenerator *generator = json_generator_new ();
- * char *str;
- * json_generator_set_pretty (generator, TRUE);
- * json_generator_set_root (generator, result);
- * str = json_generator_to_data (generator, NULL);
- * g_print ("Results: %s\n", str);
- *   </programlisting>
- *   <para>The output will be:</para>
- *   <programlisting><![CDATA[
-[
-  "Nigel Rees",
-  "Evelyn Waugh",
-  "Herman Melville",
-  "J. R. R. Tolkien"
-]
-]]></programlisting>
- * </example>
+ * A JSONPath expression is composed by path indices and operators.
+ * Each path index can either be a member name or an element index inside
+ * a JSON tree. A JSONPath expression must start with the '$' operator; each
+ * path index is separated using either the dot notation or the bracket
+ * notation, e.g.:
+ *
+ * |[
+ *   // dot notation
+ *   $.store.book[0].title
+ *
+ *   // bracket notation
+ *   $['store']['book'][0]['title']
+ * ]|
+ *
+ * The available operators are:
+ *
+ * * Root node
+ *   The '$' character represents the root node of the JSON tree, and
+ *   matches the entire document.
+ *
+ * * Child nodes can either be matched using '.' or '[]'. For instance,
+ *   both `$.store.book` and `$['store']['book'] match the contents of
+ *   the book member of the store object.
+ *
+ * * Child nodes can be reached without specifying the whole tree structure
+ *   through the recursive descent operator, or '..'. For instance,
+ *   `$..author` matches all author member in every object.
+ *
+ * * Child nodes can grouped through the wildcard operator, or '*'. For
+ *   instance, `$.store.book[*].author` matches all author members of any
+ *   object element contained in the book array of the store object.
+ *
+ * * Element nodes can be accessed using their index (starting from zero)
+ *   in the subscript operator '[]'. For instance, `$.store.book[0]` matches
+ *   the first element of the book array of the store object.
+ *
+ * * Subsets of element nodes can be accessed using the set notation
+ *   operator '[start,end]'. For instance, `$.store.book[0,2]` matches the
+ *   first, second, and third elements of the book array of the store
+ *   object.
+ *
+ * * Slices of element nodes can be accessed using the slice notation
+ *   operation '[start:end:step]'. If start is omitted, the starting index
+ *   of the slice is implied to be zero; if end is omitted, the ending index
+ *   of the slice is implied to be the length of the array; if step is
+ *   omitted, the step of the slice is implied to be 1. For instance,
+ *   `$.store.book[:2]` matches the first two elements of the book array
+ *   of the store object.
+ *
+ * More information about JSONPath is available on Stefan Gössner's
+ * [JSONPath website](http://goessner.net/articles/JsonPath/).
+ *
+ * ## Example of JSONPath matches
+ * The following example shows some of the results of using #JsonPath
+ * on a JSON tree. We use the following JSON description of a bookstore:
+ * |[
+ *   { "store": {
+ *       "book": [
+ *         { "category": "reference", "author": "Nigel Rees",
+ *           "title": "Sayings of the Century", "price": "8.95"  },
+ *         { "category": "fiction", "author": "Evelyn Waugh",
+ *           "title": "Sword of Honour", "price": "12.99" },
+ *         { "category": "fiction", "author": "Herman Melville",
+ *           "title": "Moby Dick", "isbn": "0-553-21311-3",
+ *           "price": "8.99" },
+ *         { "category": "fiction", "author": "J. R. R. Tolkien",
+ *           "title": "The Lord of the Rings", "isbn": "0-395-19395-8",
+ *           "price": "22.99" }
+ *       ],
+ *       "bicycle": { "color": "red", "price": "19.95" }
+ *     }
+ *   }
+ * ]|
+ *
+ * We can parse the JSON using #JsonParser:
+ *
+ * |[<!-- language="C" -->
+ *   JsonParser *parser = json_parser_new ();
+ *   json_parser_load_from_data (parser, json_data, -1, NULL);
+ * ]|
+ *
+ * If we run the following code:
+ *
+ * |[<!-- language="C" -->
+ *   JsonNode *result;
+ *   JsonPath *path = json_path_new ();
+ *   json_path_compile (path, "$.store..author", NULL);
+ *   result = json_path_match (path, json_parser_get_root (parser));
+ * ]|
+ *
+ * The result #JsonNode will contain an array with all values of the
+ * author member of the objects in the JSON tree. If we use a
+ * #JsonGenerator to convert the #JsonNode to a string and print it:
+ *
+ * |[<!-- language="C" -->
+ *   JsonGenerator *generator = json_generator_new ();
+ *   json_generator_set_root (generator, result);
+ *   char *str = json_generator_to_data (generator, NULL);
+ *   g_print ("Results: %s\n", str);
+ * ]|
+ *
+ * The output will be:
+ *
+ * |[
+ *   ["Nigel Rees","Evelyn Waugh","Herman Melville","J. R. R. Tolkien"]
+ * ]|
  *
  * #JsonPath is available since JSON-GLib 0.14
  */
@@ -981,11 +933,11 @@ walk_path_node (GList      *path,
  * Matches the JSON tree pointed by @root using the expression compiled
  * into the #JsonPath.
  *
- * The matching #JsonNode<!-- -->s will be copied into a #JsonArray and
+ * The matching #JsonNodes will be copied into a #JsonArray and
  * returned wrapped in a #JsonNode.
  *
  * Return value: (transfer full): a newly-created #JsonNode of type
- *   %JSON_NODE_ARRAY containing an array of matching #JsonNode<!-- -->s.
+ *   %JSON_NODE_ARRAY containing an array of matching #JsonNodes.
  *   Use json_node_free() when done
  *
  * Since: 0.14
@@ -1025,7 +977,7 @@ json_path_match (JsonPath *path,
  * matches it against the JSON tree pointed by @root.
  *
  * Return value: (transfer full): a newly-created #JsonNode of type
- *   %JSON_NODE_ARRAY containing an array of matching #JsonNode<!-- -->s.
+ *   %JSON_NODE_ARRAY containing an array of matching #JsonNodes.
  *   Use json_node_free() when done
  *
  * Since: 0.14
diff --git a/json-glib/json-path.h b/json-glib/json-path.h
index 6a30932..272c298 100644
--- a/json-glib/json-path.h
+++ b/json-glib/json-path.h
@@ -59,9 +59,8 @@ typedef enum {
 /**
  * JsonPath:
  *
- * The <structname>JsonPath</structname> structure is an opaque object
- * whose members cannot be directly accessed except through the provided
- * API.
+ * The `JsonPath` structure is an opaque object whose members cannot be
+ * directly accessed except through the provided API.
  *
  * Since: 0.14
  */
@@ -70,8 +69,8 @@ typedef struct _JsonPath        JsonPath;
 /**
  * JsonPathClass:
  *
- * The <structname>JsonPathClass</structname> structure is an opaque
- * object class whose members cannot be directly accessed.
+ * The `JsonPathClass` structure is an opaque object class whose members
+ * cannot be directly accessed.
  *
  * Since: 0.14
  */
diff --git a/json-glib/json-reader.c b/json-glib/json-reader.c
index 16a50e7..eea2866 100644
--- a/json-glib/json-reader.c
+++ b/json-glib/json-reader.c
@@ -33,27 +33,24 @@
  * called, e.g.:
  *
  * |[
- * /&ast; ask for the 7th element; if the element does not exist, the
- *  &ast; reader will be put in an error state
- *  &ast;/
+ * // ask for the 7th element; if the element does not exist, the
+ * // reader will be put in an error state
  * json_reader_read_element (reader, 6);
  *
- * /&ast; in case of error, this will return NULL, otherwise it will
- *  &ast; return the value of the element
- *  &ast;/
+ * // in case of error, this will return NULL, otherwise it will
+ * // return the value of the element
  * str = json_reader_get_string_value (value);
  *
- * /&ast; this function resets the error state if any was set &ast;/
+ * // this function resets the error state if any was set
  * json_reader_end_element (reader);
  * ]|
  *
  * If you want to detect the error state as soon as possible, you can use
  * json_reader_get_error():
  *
- * |[
- * /&ast; like the example above, but in this case we print out the
- *  &ast; error immediately
- *  &ast;/
+ * |[<!-- language="C" -->
+ * // like the example above, but in this case we print out the
+ * // error immediately
  * if (!json_reader_read_element (reader, 6))
  *   {
  *     const GError *error = json_reader_get_error (reader);
diff --git a/json-glib/json-reader.h b/json-glib/json-reader.h
index 14c7cad..37002f0 100644
--- a/json-glib/json-reader.h
+++ b/json-glib/json-reader.h
@@ -80,8 +80,8 @@ typedef enum {
 /**
  * JsonReader:
  *
- * The <structname>JsonReader</structname> structure contains only
- * private data and should only be accessed using the provided API
+ * The `JsonReader` structure contains only private data and should
+ * be accessed using the provided API
  *
  * Since: 0.12
  */
@@ -96,8 +96,7 @@ struct _JsonReader
 /**
  * JsonReaderClass:
  *
- * The <structname>JsonReaderClass</structname> structure contains only
- * private data
+ * The `JsonReaderClass` structure contains only private data
  *
  * Since: 0.12
  */
diff --git a/json-glib/json-serializable.c b/json-glib/json-serializable.c
index e49ccb1..5567b47 100644
--- a/json-glib/json-serializable.c
+++ b/json-glib/json-serializable.c
@@ -184,12 +184,14 @@ G_DEFINE_INTERFACE (JsonSerializable, json_serializable, G_TYPE_OBJECT);
  * @pspec: a #GParamSpec
  *
  * Calls the default implementation of the #JsonSerializable
- * serialize_property() virtual function
+ * #JsonSerializableIface.serialize_property() virtual function.
  *
  * This function can be used inside a custom implementation
- * of the serialize_property() virtual function in lieu of:
+ * of the #JsonSerializableIface.serialize_property() virtual
+ * function in lieu of calling the default implementation
+ * through g_type_default_interface_peek():
  *
- * |[
+ * |[<!-- language="C" -->
  *   JsonSerializable *iface;
  *   JsonNode *node;
  *
@@ -234,7 +236,7 @@ json_serializable_default_serialize_property (JsonSerializable *serializable,
  * This function can be used inside a custom implementation
  * of the deserialize_property() virtual function in lieu of:
  *
- * |[
+ * |[<!-- language="C" -->
  *   JsonSerializable *iface;
  *   gboolean res;
  *