Merge branch 'doc-fixes' into 'master'

Update JSON-GLib documentation

See merge request GNOME/json-glib!42

22 files changed, 1022 insertions, 792 deletions

diff --git a/doc/json-glib.toml.in b/doc/json-glib.toml.in
index af43d54..9209538 100644
--- a/doc/json-glib.toml.in
+++ b/doc/json-glib.toml.in
@@ -23,6 +23,7 @@ search_index = true
 [theme]
 name = "basic"
 show_index_summary = true
+show_class_hierarchy = true
 
 [source-location]
 base_url = "https://gitlab.gnome.org/GNOME/json-glib/-/blob/master/"
@@ -33,3 +34,15 @@ content_files = [
   'json-gobject.md',
   'json-gvariant.md',
 ]
+
+[[object]]
+pattern = "DEPRECATED_IN_*"
+hidden = true
+
+[[object]]
+name = "DEPRECATED_FOR"
+hidden = true
+
+[[object]]
+name = "UNAVAILABLE"
+hidden = true
diff --git a/json-glib/json-array.c b/json-glib/json-array.c
index 6e85f55..b242ce7 100644
--- a/json-glib/json-array.c
+++ b/json-glib/json-array.c
@@ -171,7 +171,7 @@ json_array_seal (JsonArray *array)
 
 /**
  * json_array_is_immutable:
- * @array: an array
+ * @array: a JSON array
  *
  * Check whether the given `array` has been marked as immutable by calling
  * [method@Json.Array.seal] on it.
@@ -190,7 +190,7 @@ json_array_is_immutable (JsonArray *array)
 
 /**
  * json_array_get_elements:
- * @array: an array
+ * @array: a JSON array
  *
  * Retrieves all the elements of an array as a list of nodes.
  *
@@ -215,7 +215,7 @@ json_array_get_elements (JsonArray *array)
 
 /**
  * json_array_dup_element:
- * @array: an array
+ * @array: a JSON array
  * @index_: the index of the element to retrieve
  *
  * Retrieves a copy of the element at the given position in the array.
@@ -242,7 +242,7 @@ json_array_dup_element (JsonArray *array,
 
 /**
  * json_array_get_element:
- * @array: a #JsonArray
+ * @array: a JSON array
  * @index_: the index of the element to retrieve
  *
  * Retrieves the element at the given position in the array.
@@ -261,7 +261,7 @@ json_array_get_element (JsonArray *array,
 
 /**
  * json_array_get_int_element:
- * @array: an array
+ * @array: a JSON array
  * @index_: the index of the element to retrieve
  *
  * Conveniently retrieves the integer value of the element at the given
@@ -291,7 +291,7 @@ json_array_get_int_element (JsonArray *array,
 
 /**
  * json_array_get_double_element:
- * @array: an array
+ * @array: a JSON array
  * @index_: the index of the element to retrieve
  *
  * Conveniently retrieves the floating point value of the element at
@@ -321,7 +321,7 @@ json_array_get_double_element (JsonArray *array,
 
 /**
  * json_array_get_boolean_element:
- * @array: an array
+ * @array: a JSON array
  * @index_: the index of the element to retrieve
  *
  * Conveniently retrieves the boolean value of the element at the given
@@ -351,7 +351,7 @@ json_array_get_boolean_element (JsonArray *array,
 
 /**
  * json_array_get_string_element:
- * @array: an array
+ * @array: a JSON array
  * @index_: the index of the element to retrieve
  *
  * Conveniently retrieves the string value of the element at the given
@@ -384,7 +384,7 @@ json_array_get_string_element (JsonArray *array,
 
 /**
  * json_array_get_null_element:
- * @array: an array
+ * @array: a JSON array
  * @index_: the index of the element to retrieve
  *
  * Conveniently checks whether the element at the given position inside the
@@ -422,7 +422,7 @@ json_array_get_null_element (JsonArray *array,
 
 /**
  * json_array_get_array_element:
- * @array: an array
+ * @array: a JSON array
  * @index_: the index of the element to retrieve
  *
  * Conveniently retrieves the array at the given position inside an array.
@@ -454,7 +454,7 @@ json_array_get_array_element (JsonArray *array,
 
 /**
  * json_array_get_object_element:
- * @array: a #JsonArray
+ * @array: a JSON array
  * @index_: the index of the element to retrieve
  *
  * Conveniently retrieves the object at the given position inside an array.
@@ -486,7 +486,7 @@ json_array_get_object_element (JsonArray *array,
 
 /**
  * json_array_get_length:
- * @array: an array
+ * @array: a JSON array
  *
  * Retrieves the length of the given array
  *
@@ -502,7 +502,7 @@ json_array_get_length (JsonArray *array)
 
 /**
  * json_array_add_element:
- * @array: an array
+ * @array: a JSON array
  * @node: (transfer full): the element to add
  *
  * Appends the given `node` inside an array.
@@ -519,7 +519,7 @@ json_array_add_element (JsonArray *array,
 
 /**
  * json_array_add_int_element:
- * @array: an array
+ * @array: a JSON array
  * @value: the integer value to add
  *
  * Conveniently adds the given integer value into an array.
@@ -539,7 +539,7 @@ json_array_add_int_element (JsonArray *array,
 
 /**
  * json_array_add_double_element:
- * @array: an array
+ * @array: a JSON array
  * @value: the floating point value to add
  *
  * Conveniently adds the given floating point value into an array.
@@ -559,7 +559,7 @@ json_array_add_double_element (JsonArray *array,
 
 /**
  * json_array_add_boolean_element:
- * @array: an array
+ * @array: a JSON array
  * @value: the boolean value to add
  *
  * Conveniently adds the given boolean value into an array.
@@ -579,7 +579,7 @@ json_array_add_boolean_element (JsonArray *array,
 
 /**
  * json_array_add_string_element:
- * @array: an array
+ * @array: a JSON array
  * @value: the string value to add
  *
  * Conveniently adds the given string value into an array.
@@ -608,7 +608,7 @@ json_array_add_string_element (JsonArray   *array,
 
 /**
  * json_array_add_null_element:
- * @array: an array
+ * @array: a JSON array
  *
  * Conveniently adds a `null` element into an array
  *
@@ -626,10 +626,10 @@ json_array_add_null_element (JsonArray *array)
 
 /**
  * json_array_add_array_element:
- * @array: an array
+ * @array: a JSON array
  * @value: (nullable) (transfer full): the array to add
  *
- * Conveniently adds an array into an array.
+ * Conveniently adds an array element into an array.
  *
  * If `value` is `NULL`, a `null` element will be added instead.
  *
@@ -660,7 +660,7 @@ json_array_add_array_element (JsonArray *array,
 
 /**
  * json_array_add_object_element:
- * @array: an array
+ * @array: a JSON array
  * @value: (transfer full) (nullable): the object to add
  *
  * Conveniently adds an object into an array.
@@ -694,7 +694,7 @@ json_array_add_object_element (JsonArray  *array,
 
 /**
  * json_array_remove_element:
- * @array: a #JsonArray
+ * @array: a JSON array
  * @index_: the position of the element to be removed
  *
  * Removes the element at the given position inside an array.
@@ -713,7 +713,7 @@ json_array_remove_element (JsonArray *array,
 
 /**
  * json_array_foreach_element:
- * @array: an array
+ * @array: a JSON array
  * @func: (scope call): the function to be called on each element
  * @data: (closure): data to be passed to the function
  *
diff --git a/json-glib/json-builder.c b/json-glib/json-builder.c
index e4170b2..45f6cbe 100644
--- a/json-glib/json-builder.c
+++ b/json-glib/json-builder.c
@@ -27,14 +27,40 @@
  *
  * `JsonBuilder` provides an object for generating a JSON tree.
  *
- * You can generate only one tree with one `JsonBuilder` instance.
- *
  * The root of the JSON tree can be either a [struct@Json.Object] or a [struct@Json.Array].
  * Thus the first call must necessarily be either
  * [method@Json.Builder.begin_object] or [method@Json.Builder.begin_array].
  *
  * For convenience to language bindings, most `JsonBuilder` method return the
  * instance, making it easy to chain function calls.
+ *
+ * ## Using `JsonBuilder`
+ *
+ * ```c
+ * g_autoptr(JsonBuilder) builder = json_builder_new ();
+ *
+ * json_builder_begin_object (builder);
+ *
+ * json_builder_set_member_name (builder, "url");
+ * json_builder_add_string_value (builder, "http://www.gnome.org/img/flash/two-thirty.png");
+ *
+ * json_builder_set_member_name (builder, "size");
+ * json_builder_begin_array (builder);
+ * json_builder_add_int_value (builder, 652);
+ * json_builder_add_int_value (builder, 242);
+ * json_builder_end_array (builder);
+ *
+ * json_builder_end_object (builder);
+ *
+ * g_autoptr(JsonNode) root root = json_builder_get_root (builder);
+ *
+ * g_autoptr(JsonGenerator) gen = json_generator_new ();
+ * json_generator_set_root (gen, root);
+ * g_autofree char *str = json_generator_to_data (gen, NULL);
+ *
+ * // str now contains the following JSON data
+ * // { "url" : "http://www.gnome.org/img/flash/two-thirty.png", "size" : [ 652, 242 ] }
+ * ```
  */
 
 #include "config.h"
@@ -188,8 +214,7 @@ json_builder_class_init (JsonBuilderClass *klass)
   /**
    * JsonBuilder:immutable:
    *
-   * Whether the #JsonNode tree built by the #JsonBuilder should be immutable
-   * when created.
+   * Whether the tree should be immutable when created.
    *
    * Making the output immutable on creation avoids the expense
    * of traversing it to make it immutable later.
@@ -256,7 +281,7 @@ json_builder_new (void)
  * Creates a new, immutable `JsonBuilder` instance.
  *
  * It is equivalent to setting the [property@Json.Builder:immutable] property
- * set to `TRUE`.
+ * set to `TRUE` at construction time.
  *
  * Since: 1.2
  * Returns: (transfer full): the newly create builder instance
@@ -271,7 +296,7 @@ json_builder_new_immutable (void)
  * json_builder_get_root:
  * @builder: a builder
  *
- * Returns the root of the current constructed tree.
+ * Returns the root of the currently constructed tree.
  *
  * if the build is incomplete (ie: if there are any opened objects, or any
  * open object members and array elements) then this function will return
@@ -299,9 +324,9 @@ json_builder_get_root (JsonBuilder *builder)
 
 /**
  * json_builder_reset:
- * @builder: a #JsonBuilder
+ * @builder: a builder
  *
- * Resets the state of the @builder back to its initial state.
+ * Resets the state of the builder back to its initial state.
  */
 void
 json_builder_reset (JsonBuilder *builder)
@@ -313,11 +338,14 @@ json_builder_reset (JsonBuilder *builder)
 
 /**
  * json_builder_begin_object:
- * @builder: a #JsonBuilder
+ * @builder: a builder
+ *
+ * Opens an object inside the given builder.
  *
- * Opens a subobject inside the given builder.
+ * You can add a new member to the object by using [method@Json.Builder.set_member_name],
+ * followed by [method@Json.Builder.add_value].
  *
- * Once you added all members to the object, you must call [method@Json.Builder.end_object].
+ * Once you added all members to the object, you must call [method@Json.Builder.end_object]
  * to close the object.
  *
  * If the builder is in an inconsistent state, this function will return `NULL`.
@@ -368,15 +396,14 @@ json_builder_begin_object (JsonBuilder *builder)
 
 /**
  * json_builder_end_object:
- * @builder: a #JsonBuilder
+ * @builder: a builder
  *
- * Closes the subobject inside the given @builder that was opened by the most
- * recent call to json_builder_begin_object().
+ * Closes the object inside the given builder that was opened by the most
+ * recent call to [method@Json.Builder.begin_object].
  *
- * Cannot be called after json_builder_set_member_name().
+ * This function cannot be called after [method@Json.Builder.set_member_name].
  *
- * Return value: (nullable) (transfer none): the #JsonBuilder, or %NULL if the
- * call was inconsistent
+ * Return value: (nullable) (transfer none): the builder instance
  */
 JsonBuilder *
 json_builder_end_object (JsonBuilder *builder)
@@ -408,16 +435,16 @@ json_builder_end_object (JsonBuilder *builder)
 
 /**
  * json_builder_begin_array:
- * @builder: a #JsonBuilder
+ * @builder: a builder
  *
- * Opens a subarray inside the given @builder. When done adding members to
- * the subarray, json_builder_end_array() must be called.
+ * Opens an array inside the given builder.
  *
- * Can be called for first or only if the call is associated to an object member
- * or an array element.
+ * You can add a new element to the array by using [method@Json.Builder.add_value].
  *
- * Return value: (nullable) (transfer none): the #JsonBuilder, or %NULL if the
- * call was inconsistent
+ * Once you added all elements to the array, you must call
+ * [method@Json.Builder.end_array] to close the array.
+ *
+ * Return value: (nullable) (transfer none): the builder instance
  */
 JsonBuilder *
 json_builder_begin_array (JsonBuilder *builder)
@@ -462,15 +489,14 @@ json_builder_begin_array (JsonBuilder *builder)
 
 /**
  * json_builder_end_array:
- * @builder: a #JsonBuilder
+ * @builder: a builder
  *
- * Closes the subarray inside the given @builder that was opened by the most
- * recent call to json_builder_begin_array().
+ * Closes the array inside the given builder that was opened by the most
+ * recent call to [method@Json.Builder.begin_array].
  *
- * Cannot be called after json_builder_set_member_name().
+ * This function cannot be called after [method@Json.Builder.set_member_name].
  *
- * Return value: (nullable) (transfer none): the #JsonBuilder, or %NULL if the
- * call was inconsistent
+ * Return value: (nullable) (transfer none): the builder instance
  */
 JsonBuilder *
 json_builder_end_array (JsonBuilder *builder)
@@ -502,16 +528,20 @@ json_builder_end_array (JsonBuilder *builder)
 
 /**
  * json_builder_set_member_name:
- * @builder: a #JsonBuilder
+ * @builder: a builder
  * @member_name: the name of the member
  *
- * Set the name of the next member in an object. The next call must add a value,
- * open an object or an array.
+ * Sets the name of the member in an object.
  *
- * Can be called only if the call is associated to an object.
+ * This function must be followed by of these functions:
  *
- * Return value: (nullable) (transfer none): the #JsonBuilder, or %NULL if the
- * call was inconsistent
+ *  - [method@Json.Builder.add_value], to add a scalar value to the member
+ *  - [method@Json.Builder.begin_object], to add an object to the member
+ *  - [method@Json.Builder.begin_array], to add an array to the member
+ *
+ * This function can only be called within an open object.
+ *
+ * Return value: (nullable) (transfer none): the builder instance
  */
 JsonBuilder *
 json_builder_set_member_name (JsonBuilder *builder,
@@ -533,17 +563,18 @@ json_builder_set_member_name (JsonBuilder *builder,
 
 /**
  * json_builder_add_value:
- * @builder: a #JsonBuilder
+ * @builder: a builder
  * @node: (transfer full): the value of the member or element
  *
- * If called after json_builder_set_member_name(), sets @node as member of the
- * most recent opened object, otherwise @node is added as element of the most
- * recent opened array.
+ * Adds a value to the currently open object member or array.
+ *
+ * If called after [method@Json.Builder.set_member_name], sets the given node
+ * as the value of the current member in the open object; otherwise, the node
+ * is appended to the elements of the open array.
  *
- * The builder will take ownership of the #JsonNode.
+ * The builder will take ownership of the node.
  *
- * Return value: (nullable) (transfer none): the #JsonBuilder, or %NULL if the
- * call was inconsistent
+ * Return value: (nullable) (transfer none): the builder instance
  */
 JsonBuilder *
 json_builder_add_value (JsonBuilder *builder,
@@ -583,17 +614,18 @@ json_builder_add_value (JsonBuilder *builder,
 
 /**
  * json_builder_add_int_value:
- * @builder: a #JsonBuilder
+ * @builder: a builder
  * @value: the value of the member or element
  *
- * If called after json_builder_set_member_name(), sets @value as member of the
- * most recent opened object, otherwise @value is added as element of the most
- * recent opened array.
+ * Adds an integer value to the currently open object member or array.
+ *
+ * If called after [method@Json.Builder.set_member_name], sets the given value
+ * as the value of the current member in the open object; otherwise, the value
+ * is appended to the elements of the open array.
  *
- * See also: json_builder_add_value()
+ * See also: [method@Json.Builder.add_value]
  *
- * Return value: (nullable) (transfer none): the #JsonBuilder, or %NULL if the
- * call was inconsistent
+ * Return value: (nullable) (transfer none): the builder instance
  */
 JsonBuilder *
 json_builder_add_int_value (JsonBuilder *builder,
@@ -628,17 +660,18 @@ json_builder_add_int_value (JsonBuilder *builder,
 
 /**
  * json_builder_add_double_value:
- * @builder: a #JsonBuilder
+ * @builder: a builder
  * @value: the value of the member or element
  *
- * If called after json_builder_set_member_name(), sets @value as member of the
- * most recent opened object, otherwise @value is added as element of the most
- * recent opened array.
+ * Adds a floating point value to the currently open object member or array.
+ *
+ * If called after [method@Json.Builder.set_member_name], sets the given value
+ * as the value of the current member in the open object; otherwise, the value
+ * is appended to the elements of the open array.
  *
- * See also: json_builder_add_value()
+ * See also: [method@Json.Builder.add_value]
  *
- * Return value: (nullable) (transfer none): the #JsonBuilder, or %NULL if the
- * call was inconsistent
+ * Return value: (nullable) (transfer none): the builder instance
  */
 JsonBuilder *
 json_builder_add_double_value (JsonBuilder *builder,
@@ -674,17 +707,18 @@ json_builder_add_double_value (JsonBuilder *builder,
 
 /**
  * json_builder_add_boolean_value:
- * @builder: a #JsonBuilder
+ * @builder: a builder
  * @value: the value of the member or element
  *
- * If called after json_builder_set_member_name(), sets @value as member of the
- * most recent opened object, otherwise @value is added as element of the most
- * recent opened array.
+ * Adds a boolean value to the currently open object member or array.
+ *
+ * If called after [method@Json.Builder.set_member_name], sets the given value
+ * as the value of the current member in the open object; otherwise, the value
+ * is appended to the elements of the open array.
  *
- * See also: json_builder_add_value()
+ * See also: [method@Json.Builder.add_value]
  *
- * Return value: (nullable) (transfer none): the #JsonBuilder, or %NULL if the
- * call was inconsistent
+ * Return value: (nullable) (transfer none): the builder instance
  */
 JsonBuilder *
 json_builder_add_boolean_value (JsonBuilder *builder,
@@ -720,17 +754,18 @@ json_builder_add_boolean_value (JsonBuilder *builder,
 
 /**
  * json_builder_add_string_value:
- * @builder: a #JsonBuilder
+ * @builder: a builder
  * @value: the value of the member or element
  *
- * If called after json_builder_set_member_name(), sets @value as member of the
- * most recent opened object, otherwise @value is added as element of the most
- * recent opened array.
+ * Adds a boolean value to the currently open object member or array.
  *
- * See also: json_builder_add_value()
+ * If called after [method@Json.Builder.set_member_name], sets the given value
+ * as the value of the current member in the open object; otherwise, the value
+ * is appended to the elements of the open array.
  *
- * Return value: (nullable) (transfer none): the #JsonBuilder, or %NULL if the
- * call was inconsistent
+ * See also: [method@Json.Builder.add_value]
+ *
+ * Return value: (nullable) (transfer none): the builder instance
  */
 JsonBuilder *
 json_builder_add_string_value (JsonBuilder *builder,
@@ -766,16 +801,17 @@ json_builder_add_string_value (JsonBuilder *builder,
 
 /**
  * json_builder_add_null_value:
- * @builder: a #JsonBuilder
+ * @builder: a builder
  *
- * If called after json_builder_set_member_name(), sets null as member of the
- * most recent opened object, otherwise null is added as element of the most
- * recent opened array.
+ * Adds a null value to the currently open object member or array.
  *
- * See also: json_builder_add_value()
+ * If called after [method@Json.Builder.set_member_name], sets the given value
+ * as the value of the current member in the open object; otherwise, the value
+ * is appended to the elements of the open array.
  *
- * Return value: (nullable) (transfer none): the #JsonBuilder, or %NULL if
- * the call was inconsistent
+ * See also: [method@Json.Builder.add_value]
+ *
+ * Return value: (nullable) (transfer none): the builder instance
  */
 JsonBuilder *
 json_builder_add_null_value (JsonBuilder *builder)
diff --git a/json-glib/json-gboxed.c b/json-glib/json-gboxed.c
index 04fdeea..8b51288 100644
--- a/json-glib/json-gboxed.c
+++ b/json-glib/json-gboxed.c
@@ -90,11 +90,10 @@ lookup_boxed_transform (GSList       *transforms,
  * json_boxed_register_serialize_func: (skip)
  * @gboxed_type: a boxed type
  * @node_type: a node type
- * @serialize_func: serialization function for @boxed_type into
- *   a #JsonNode of type @node_type
+ * @serialize_func: serialization function
  *
- * Registers a serialization function for a #GBoxed of type @gboxed_type
- * to a #JsonNode of type @node_type.
+ * Registers a serialization function for a `GBoxed` of type `gboxed_type`
+ * to a [struct@Json.Node] of type `node_type`.
  *
  * Since: 0.10
  */
@@ -135,11 +134,10 @@ json_boxed_register_serialize_func (GType                  gboxed_type,
  * json_boxed_register_deserialize_func: (skip)
  * @gboxed_type: a boxed type
  * @node_type: a node type
- * @deserialize_func: deserialization function for @boxed_type from
- *   a #JsonNode of type @node_type
+ * @deserialize_func: deserialization function
  *
- * Registers a deserialization function for a #GBoxed of type @gboxed_type
- * from a #JsonNode of type @node_type
+ * Registers a deserialization function for a `GBoxed` of type `gboxed_type`
+ * from a [struct@Json.Node] of type `node_type`.
  *
  * Since: 0.10
  */
@@ -179,17 +177,16 @@ json_boxed_register_deserialize_func (GType                    gboxed_type,
 /**
  * json_boxed_can_serialize:
  * @gboxed_type: a boxed type
- * @node_type: (out) (optional): the #JsonNode type to which the boxed type
+ * @node_type: (out) (optional): the node type to which the boxed type
  *   can be serialized into
  *
- * Checks whether it is possible to serialize a #GBoxed of
- * type @gboxed_type into a #JsonNode.
+ * Checks whether it is possible to serialize a `GBoxed` of
+ * type `gboxed_type` into a [struct@Json.Node].
  *
- * The type of the #JsonNode is placed inside @node_type if the function
- * returns %TRUE and it's undefined otherwise.
+ * The type of the node is placed inside `node_type` if the function
+ * returns `TRUE`, and it's undefined otherwise.
  *
- * Return value: %TRUE if the type can be serialized,
- *   and %FALSE otherwise.
+ * Return value: `TRUE` if the type can be serialized, and `FALSE` otherwise
  *
  * Since: 0.10
  */
@@ -217,12 +214,12 @@ json_boxed_can_serialize (GType         gboxed_type,
 /**
  * json_boxed_can_deserialize:
  * @gboxed_type: a boxed type
- * @node_type: a #JsonNode type
+ * @node_type: a node type
  *
- * Checks whether it is possible to deserialize a #GBoxed of
- * type @gboxed_type from a #JsonNode of type @node_type
+ * Checks whether it is possible to deserialize a `GBoxed` of
+ * type `gboxed_type` from a [struct@Json.Node] of type `node_type`.
  *
- * Return value: %TRUE if the type can be deserialized, %FALSE otherwise
+ * Return value: `TRUE` if the type can be deserialized, and `FALSE` otherwise
  *
  * Since: 0.10
  */
@@ -245,12 +242,13 @@ json_boxed_can_deserialize (GType        gboxed_type,
 /**
  * json_boxed_serialize:
  * @gboxed_type: a boxed type
- * @boxed: a pointer to a #GBoxed of type @gboxed_type
+ * @boxed: a pointer to a boxed of type `gboxed_type`
+ *
+ * Serializes a pointer to a `GBoxed` of the given type into a [struct@Json.Node].
  *
- * Serializes a pointer to a #GBoxed of type @gboxed_type into a #JsonNode
+ * If the serialization is not possible, this function will return `NULL`.
  *
- * Return value: (nullable) (transfer full): a #JsonNode with the serialization of
- *   the boxed type, or %NULL if serialization either failed or was not possible
+ * Return value: (nullable) (transfer full): a node with the serialized boxed type
  *
  * Since: 0.10
  */
@@ -274,13 +272,11 @@ json_boxed_serialize (GType         gboxed_type,
 /**
  * json_boxed_deserialize:
  * @gboxed_type: a boxed type
- * @node: a #JsonNode
+ * @node: a node
  *
- * Deserializes @node into a #GBoxed of @gboxed_type.
+ * Deserializes the given [struct@Json.Node] into a `GBoxed` of the given type.
  *
- * Return value: (transfer full): the newly allocated #GBoxed. Use
- *   g_boxed_free() to release the resources allocated by this
- *   function
+ * Return value: (transfer full): the newly allocated boxed data
  *
  * Since: 0.10
  */
diff --git a/json-glib/json-generator.c b/json-glib/json-generator.c
index 460520f..fc8dcfc 100644
--- a/json-glib/json-generator.c
+++ b/json-glib/json-generator.c
@@ -234,7 +234,7 @@ json_generator_class_init (JsonGeneratorClass *klass)
   /**
    * JsonGenerator:root: (attributes org.gtk.Property.get=json_generator_get_root org.gtk.Property.set=json_generator_set_root)
    *
-   * The root #JsonNode to be used when constructing a JSON data
+   * The root node to be used when constructing a JSON data
    * stream.
    *
    * Since: 0.4
@@ -471,12 +471,12 @@ dump_object (JsonGenerator *generator,
 /**
  * json_generator_new:
  * 
- * Creates a new #JsonGenerator.
+ * 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.
+ * data object model composed by [struct@Json.Node]s.
  *
- * Return value: the newly created #JsonGenerator instance
+ * Return value: the newly created generator instance
  */
 JsonGenerator *
 json_generator_new (void)
@@ -486,13 +486,13 @@ json_generator_new (void)
 
 /**
  * json_generator_to_gstring:
- * @generator: a #JsonGenerator
- * @string: a #GString
+ * @generator: a generator
+ * @string: a string buffer
  *
- * Generates a JSON data stream from @generator and appends it to @string.
+ * Generates a JSON data stream and appends it to the string buffer.
  *
- * Return value: (transfer none): a #GString holding a JSON data stream.
- *   Use g_string_free() to free the allocated resources.
+ * Return value: (transfer none): the passed string, updated with
+ *   the generated JSON data
  *
  * Since: 1.4
  */
@@ -514,7 +514,7 @@ json_generator_to_gstring (JsonGenerator *generator,
 
 /**
  * json_generator_to_data:
- * @generator: a #JsonGenerator
+ * @generator: a generator
  * @length: (out) (optional): return location for the length of the returned
  *   buffer
  *
@@ -542,14 +542,15 @@ json_generator_to_data (JsonGenerator *generator,
 
 /**
  * json_generator_to_file:
- * @generator: a #JsonGenerator
- * @filename: path to the target file
+ * @generator: a generator
+ * @filename: (type filename): the path to the target file
  * @error: return location for a #GError, or %NULL
  *
- * Creates a JSON data stream and puts it inside @filename, overwriting the
- * current file contents.
+ * Creates a JSON data stream and puts it inside `filename`, overwriting
+ * the file's current contents.
  *
- * This operation is atomic.
+ * This operation is atomic, in the sense that the data is written to a
+ * temporary file which is then renamed to the given `filename`.
  *
  * Return value: %TRUE if saving was successful.
  */
@@ -574,12 +575,12 @@ json_generator_to_file (JsonGenerator  *generator,
 
 /**
  * json_generator_to_stream:
- * @generator: a #JsonGenerator
- * @stream: a #GOutputStream
- * @cancellable: (nullable): a #GCancellable
+ * @generator: a generator
+ * @stream: the output stream used to write the JSON data
+ * @cancellable: (nullable): a `GCancellable`
  * @error: return location for a #GError, or %NULL
  *
- * Outputs JSON data and streams it (synchronously) to @stream.
+ * Outputs JSON data and writes it (synchronously) to the given stream.
  *
  * Return value: whether the write operation was successful
  *
@@ -610,13 +611,13 @@ json_generator_to_stream (JsonGenerator  *generator,
 
 /**
  * json_generator_set_root: (attributes org.gtk.Method.set_property=root)
- * @generator: a #JsonGenerator
- * @node: a #JsonNode
+ * @generator: a generator
+ * @node: the root node
  *
- * Sets @node as the root of the JSON data stream to be serialized by
- * the #JsonGenerator.
+ * Sets the root of the JSON data stream to be serialized by
+ * the given generator.
  *
- * The passed @node is copied by the generator object, so it can be
+ * The passed `node` is copied by the generator object, so it can be
  * safely freed after calling this function.
  */
 void
@@ -642,7 +643,7 @@ json_generator_set_root (JsonGenerator *generator,
 
 /**
  * json_generator_get_root: (attributes org.gtk.Method.get_property=root)
- * @generator: a #JsonGenerator
+ * @generator: a generator
  *
  * Retrieves a pointer to the root node set using
  * [method@Json.Generator.set_root].
@@ -661,7 +662,7 @@ json_generator_get_root (JsonGenerator *generator)
 
 /**
  * json_generator_set_pretty: (attributes org.gtk.Method.set_property=pretty)
- * @generator: a #JsonGenerator
+ * @generator: a generator
  * @is_pretty: whether the generated string should be pretty printed
  *
  * Sets whether the generated JSON should be pretty printed.
@@ -694,12 +695,12 @@ json_generator_set_pretty (JsonGenerator *generator,
 
 /**
  * json_generator_get_pretty: (attributes org.gtk.Method.get_property=pretty)
- * @generator: a #JsonGenerator
+ * @generator: a generator
  *
  * Retrieves the value set using [method@Json.Generator.set_pretty].
  *
- * Return value: %TRUE if the generated JSON should be pretty-printed, and
- *   %FALSE otherwise
+ * Return value: `TRUE` if the generated JSON should be pretty-printed, and
+ *   `FALSE` otherwise
  *
  * Since: 0.14
  */
@@ -713,7 +714,7 @@ json_generator_get_pretty (JsonGenerator *generator)
 
 /**
  * json_generator_set_indent: (attributes org.gtk.Method.set_property=indent)
- * @generator: a #JsonGenerator
+ * @generator: a generator
  * @indent_level: the number of repetitions of the indentation character
  *   that should be applied when pretty printing
  *
@@ -741,7 +742,7 @@ json_generator_set_indent (JsonGenerator *generator,
 
 /**
  * json_generator_get_indent: (attributes org.gtk.Method.get_property=indent)
- * @generator: a #JsonGenerator
+ * @generator: a generator
  *
  * Retrieves the value set using [method@Json.Generator.set_indent].
  *
@@ -759,10 +760,10 @@ json_generator_get_indent (JsonGenerator *generator)
 
 /**
  * json_generator_set_indent_char: (attributes org.gtk.Method.set_property=indent-char)
- * @generator: a #JsonGenerator
+ * @generator: a generator
  * @indent_char: a Unicode character to be used when indenting
  *
- * Sets the character to be used when indenting
+ * Sets the character to be used when indenting.
  *
  * Since: 0.14
  */
@@ -786,7 +787,7 @@ json_generator_set_indent_char (JsonGenerator *generator,
 
 /**
  * json_generator_get_indent_char: (attributes org.gtk.Method.get_property=indent-char)
- * @generator: a #JsonGenerator
+ * @generator: a generator
  *
  * Retrieves the value set using [method@Json.Generator.set_indent_char].
  *
diff --git a/json-glib/json-gobject.c b/json-glib/json-gobject.c
index ceee9b5..5b7331c 100644
--- a/json-glib/json-gobject.c
+++ b/json-glib/json-gobject.c
@@ -784,16 +784,14 @@ json_serialize_pspec (const GValue *real_value,
 
 /**
  * json_gobject_deserialize:
- * @gtype: the type of the #GObject to create
- * @node: a #JsonNode of type %JSON_NODE_OBJECT describing the
- *   instance of type @gtype
+ * @gtype: the type of the object to create
+ * @node: a node of type `JSON_NODE_OBJECT` describing the
+ *   object instance for the given type
  *
- * Creates a new #GObject of type @gtype, and constructs it
- * using the members of the passed #JsonObject
+ * Creates a new `GObject` instance of the given type, and constructs it
+ * using the members of the object in the given node.
  *
- * Return value: (transfer full): The newly created #GObject
- *   instance. Use g_object_unref() to free the resources
- *   allocated by this function
+ * Return value: (transfer full): The newly created instance
  *
  * Since: 0.10
  */
@@ -809,15 +807,17 @@ json_gobject_deserialize (GType     gtype,
 
 /**
  * json_gobject_serialize:
- * @gobject: a #GObject
+ * @gobject: the object to serialize
  *
- * Creates a #JsonNode representing the passed #GObject
- * instance. Each member of the returned JSON object will
- * map to a property of the #GObject
+ * Creates a JSON tree representing the passed object instance.
  *
- * Return value: (transfer full): the newly created #JsonNode
- *   of type %JSON_NODE_OBJECT. Use json_node_unref() to free
- *   the resources allocated by this function
+ * Each member of the returned JSON object will map to a property of
+ * the object type.
+ *
+ * The returned JSON tree will be returned as a `JsonNode` with a type
+ * of `JSON_NODE_OBJECT`.
+ *
+ * Return value: (transfer full): the newly created JSON tree
  *
  * Since: 0.10
  */
@@ -836,22 +836,22 @@ json_gobject_serialize (GObject *gobject)
 
 /**
  * json_construct_gobject:
- * @gtype: the #GType of object to construct
+ * @gtype: the type of the object to construct
  * @data: a JSON data stream
  * @length: length of the data stream
  * @error: return location for a #GError, or %NULL
  *
- * Deserializes a JSON data stream and creates the corresponding
- * #GObject class.
+ * Deserializes a JSON data stream and creates an instance of the given
+ * type
  *
- * If @gtype implements the #JsonSerializableIface interface, it will be
- * asked to deserialize all the JSON members into the respective properties;
- * otherwise, the default implementation will be used to translate the
- * compatible JSON native types.
+ * If the given type implements the [iface@Json.Serializable] interface, it
+ * will be asked to deserialize all the JSON members into their respective
+ * properties; otherwise, the default implementation will be used to translate
+ * the compatible JSON native types.
  *
- * **Note**: the JSON data stream must be an object declaration.
+ * **Note**: the JSON data stream must be an object.
  *
- * Return value: (transfer full) (nullable): a #GObject instance of the given type
+ * Return value: (transfer full) (nullable): a new object instance of the given type
  *
  * Since: 0.4
  *
@@ -868,22 +868,22 @@ json_construct_gobject (GType         gtype,
 
 /**
  * json_gobject_from_data:
- * @gtype: the #GType of object to construct
+ * @gtype: the type of the object to construct
  * @data: a JSON data stream
- * @length: length of the data stream, or -1 if it is NUL-terminated
+ * @length: length of the data stream, or -1 if it is `NUL`-terminated
  * @error: return location for a #GError, or %NULL
  *
- * Deserializes a JSON data stream and creates the corresponding
- * #GObject class.
+ * Deserializes a JSON data stream and creates an instance of the
+ * given type.
  *
- * If @gtype implements the #JsonSerializableIface interface, it will be asked
- * to deserialize all the JSON members into the respective properties;
+ * If the type implements the [iface@Json.Serializable] interface, it will
+ * be asked to deserialize all the JSON members into their respective properties;
  * otherwise, the default implementation will be used to translate the
  * compatible JSON native types.
  *
- * Note: the JSON data stream must be an object declaration.
+ * **Note**: the JSON data stream must be an object
  *
- * Return value: (transfer full) (nullable): a #GObject of the given type
+ * Return value: (transfer full) (nullable): a new object instance of the given type
  *
  * Since: 0.10
  */
@@ -936,12 +936,12 @@ json_gobject_from_data (GType         gtype,
 
 /**
  * json_serialize_gobject:
- * @gobject: a #GObject
+ * @gobject: the object to serialize
  * @length: (out) (optional): return value for the length of the buffer
  *
- * Serializes a #GObject into a JSON data stream.
+ * Serializes a `GObject` instance into a JSON data stream.
  *
- * If @gobject implements the #JsonSerializableIface interface, it will be
+ * If the object implements the [iface@Json.Serializable] interface, it will be
  * asked to serizalize all its properties; otherwise, the default
  * implementation will be use to translate the compatible types into JSON
  * native types.
@@ -959,18 +959,18 @@ json_serialize_gobject (GObject *gobject,
 
 /**
  * json_gobject_to_data:
- * @gobject: a #GObject
+ * @gobject: the object to serialize
  * @length: (out) (optional): return value for the length of the buffer
  *
- * Serializes a #GObject into a JSON data stream, iterating recursively
- * over each property.
+ * Serializes a `GObject` instance into a JSON data stream, iterating
+ * recursively over each property.
  *
- * If @gobject implements the #JsonSerializableIface interface, it will
- * be asked to serialize all its properties; otherwise, the default
+ * If the given object implements the [iface@Json.Serializable] interface,
+ * it will be asked to serialize all its properties; otherwise, the default
  * implementation will be use to translate the compatible types into
  * JSON native types.
  *
- * Return value: a JSON data stream representing the passed #GObject
+ * Return value: a JSON data stream representing the given object
  *
  * Since: 0.10
  */
diff --git a/json-glib/json-gobject.h b/json-glib/json-gobject.h
index 47ac125..5fc0c63 100644
--- a/json-glib/json-gobject.h
+++ b/json-glib/json-gobject.h
@@ -38,10 +38,10 @@ typedef struct _JsonSerializableIface   JsonSerializableIface;
 
 /**
  * JsonSerializableIface:
- * @serialize_property: virtual function for serializing a #GObject property
- *   into a #JsonNode
- * @deserialize_property: virtual function for deserializing a #JsonNode
- *   into a #GObject property
+ * @serialize_property: virtual function for serializing an object property
+ *   into JSON
+ * @deserialize_property: virtual function for deserializing JSON
+ *   into an object property
  * @find_property: virtual function for finding a property definition using
  *   its name
  * @list_properties: virtual function for listing the installed property
@@ -49,9 +49,11 @@ 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 instances
- * with properties storing complex data types. The json_serialize_gobject()
- * function will check if the passed #GObject implements this interface,
+ * Interface that allows serializing and deserializing object instances
+ * with properties storing complex data types.
+ *
+ * The [func@Json.gobject_from_data] and [func@Json.gobject_to_data]
+ * functions will check if the passed object type implements this interface,
  * so it can also be used to override the default property serialization
  * sequence.
  */
@@ -127,11 +129,30 @@ gboolean  json_serializable_default_deserialize_property (JsonSerializable *seri
 
 /**
  * JsonBoxedSerializeFunc:
- * @boxed: a #GBoxed
+ * @boxed: a boxed data structure
+ *
+ * Serializes the passed `GBoxed` and stores it inside a `JsonNode`, for instance:
+ *
+ * ```c
+ * static JsonNode *
+ * my_point_serialize (gconstpointer boxed)
+ * {
+ *   const MyPoint *point = boxed;
+ *
+ *   g_autoptr(JsonBuilder) builder = json_builder_new ();
+ *
+ *   json_builder_begin_object (builder);
+ *   json_builder_set_member_name (builder, "x");
+ *   json_builder_add_double_value (builder, point->x);
+ *   json_builder_set_member_name (builder, "y");
+ *   json_builder_add_double_value (builder, point->y);
+ *   json_builder_end_object (builder);
  *
- * Serializes the passed #GBoxed and stores it inside a #JsonNode
+ *   return json_builder_get_root (builder);
+ * }
+ * ```
  *
- * Return value: the newly created #JsonNode
+ * Return value: the newly created JSON node tree representing the boxed data
  *
  * Since: 0.10
  */
@@ -139,11 +160,40 @@ typedef JsonNode *(* JsonBoxedSerializeFunc) (gconstpointer boxed);
 
 /**
  * JsonBoxedDeserializeFunc:
- * @node: a #JsonNode
+ * @node: a node tree representing a boxed data
+ *
+ * Deserializes the contents of the passed `JsonNode` into a `GBoxed`, for instance:
+ *
+ * ```c
+ * static gpointer
+ * my_point_deserialize (JsonNode *node)
+ * {
+ *   double x = 0.0, y = 0.0;
+ *
+ *   if (JSON_NODE_HOLDS_ARRAY (node))
+ *     {
+ *       JsonArray *array = json_node_get_array (node);
+ *
+ *       if (json_array_get_length (array) == 2)
+ *         {
+ *           x = json_array_get_double_element (array, 0);
+ *           y = json_array_get_double_element (array, 1);
+ *         }
+ *     }
+ *   else if (JSON_NODE_HOLDS_OBJECT (node))
+ *     {
+ *       JsonObject *obj = json_node_get_object (node);
+ *
+ *       x = json_object_get_double_member_with_default (obj, "x", 0.0);
+ *       y = json_object_get_double_member_with_default (obj, "y", 0.0);
+ *     }
  *
- * Deserializes the contents of the passed #JsonNode into a #GBoxed
+ *   // my_point_new() is defined elsewhere
+ *   return my_point_new (x, y);
+ * }
+ * ```
  *
- * Return value: the newly created boxed type
+ * Return value: the newly created boxed structure
  *
  * Since: 0.10
  */
diff --git a/json-glib/json-gvariant.c b/json-glib/json-gvariant.c
index 8e693c8..15f03f5 100644
--- a/json-glib/json-gvariant.c
+++ b/json-glib/json-gvariant.c
@@ -1232,9 +1232,9 @@ out:
 
 /**
  * json_gvariant_deserialize:
- * @json_node: A #JsonNode to convert
- * @signature: (nullable): A valid `GVariant` type string
- * @error: A pointer to a #GError
+ * @json_node: the node to convert
+ * @signature: (nullable): a valid `GVariant` type string
+ * @error: (nullable): return location for a #GError, or `NULL`
  *
  * Converts a JSON data structure to a `GVariant`.
  *
diff --git a/json-glib/json-node.c b/json-glib/json-node.c
index 1221e93..2737453 100644
--- a/json-glib/json-node.c
+++ b/json-glib/json-node.c
@@ -41,42 +41,45 @@
  *
  * When parsing a JSON data stream you extract the root node and walk
  * the node tree by retrieving the type of data contained inside the
- * node with the %JSON_NODE_TYPE macro. If the node contains a fundamental
- * type you can retrieve a copy of the #GValue holding it with the
- * json_node_get_value() function, and then use the #GValue API to extract
+ * node with the `JSON_NODE_TYPE` macro. If the node contains a fundamental
+ * type you can retrieve a copy of the `GValue` holding it with the
+ * [method@Json.Node.get_value] function, and then use the `GValue` API to extract
  * the data; if the node contains a complex type you can retrieve the
- * #JsonObject or the #JsonArray using json_node_get_object() or
- * json_node_get_array() respectively, and then retrieve the nodes
+ * [struct@Json.Object] or the [struct@Json.Array] using [method@Json.Node.get_object]
+ * or [method@Json.Node.get_array] respectively, and then retrieve the nodes
  * they contain.
  *
- * A #JsonNode may be marked as immutable using json_node_seal(). This marks the
- * node and all its descendents as read-only, and means that subsequent calls to
- * setter functions (such as json_node_set_array()) on them will abort as a
- * programmer error. By marking a node tree as immutable, it may be referenced
- * in multiple places and its hash value cached for fast lookups, without the
- * possibility of a value deep within the tree changing and affecting hash
- * values. Immutable #JsonNodes may be passed to functions which retain a
- * reference to them without needing to take a copy.
- *
- * #JsonNode supports two types of memory management: alloc/free semantics, and
- * ref/unref semantics. The two may be mixed to a limited extent: nodes may be
- * allocated (which gives them a reference count of 1), referenced one or more
- * times, unreferenced exactly that number of times (using json_node_unref()),
- * then either unreferenced exactly once more or freed (using json_node_free())
- * to destroy them. json_node_free() must not be used when a node might have a
- * reference count not equal to 1. To this end, json-glib uses json_node_copy()
- * and json_node_unref() internally.
+ * A `JsonNode` may be marked as immutable using [method@Json.Node.seal]. This
+ * marks the node and all its descendents as read-only, and means that
+ * subsequent calls to setter functions (such as [method@Json.Node.set_array])
+ * on them will abort as a programmer error. By marking a node tree as
+ * immutable, it may be referenced in multiple places and its hash value cached
+ * for fast lookups, without the possibility of a value deep within the tree
+ * changing and affecting hash values. Immutable nodes may be passed to
+ * functions which retain a reference to them without needing to take a copy.
+ *
+ * A `JsonNode` supports two types of memory management: `malloc`/`free`
+ * semantics, and reference counting semantics. The two may be mixed to a
+ * limited extent: nodes may be allocated (which gives them a reference count
+ * of 1), referenced one or more times, unreferenced exactly that number of
+ * times (using [method@Json.Node.unref]), then either unreferenced exactly
+ * once more or freed (using [method@Json.Node.free]) to destroy them.
+ * The [method@Json.Node.free] function must not be used when a node might
+ * have a reference count not equal to 1. To this end, JSON-GLib uses
+ * [method@Json.Node.copy] and [method@Json.Node.unref] internally.
  */
 
 G_DEFINE_BOXED_TYPE (JsonNode, json_node, json_node_copy, json_node_unref)
 
 /**
  * json_node_get_value_type:
- * @node: a #JsonNode
+ * @node: the node to check
  *
- * Returns the #GType of the payload of the node.
+ * Returns the `GType` of the payload of the node.
  *
- * Return value: a #GType for the payload.
+ * For `JSON_NODE_NULL` nodes, the returned type is `G_TYPE_INVALID`.
+ *
+ * Return value: the type for the payload
  *
  * Since: 0.4
  */
@@ -111,12 +114,11 @@ json_node_get_value_type (JsonNode *node)
 /**
  * json_node_alloc: (constructor)
  *
- * Allocates a new #JsonNode.
+ * Allocates a new, uninitialized node.
  *
- * Use json_node_init() and its variants to initialize the returned value.
+ * Use [method@Json.Node.init] and its variants to initialize the returned value.
  *
- * Return value: (transfer full): the newly allocated #JsonNode. Use
- *   json_node_free() to free the resources allocated by this function
+ * Return value: (transfer full): the newly allocated node
  *
  * Since: 0.16
  */
@@ -163,7 +165,7 @@ json_node_unset (JsonNode *node)
 
 /**
  * json_node_init:
- * @node: the #JsonNode to initialize
+ * @node: the node to initialize
  * @type: the type of JSON node to initialize @node to
  *
  * Initializes a @node to a specific @type.
@@ -171,7 +173,7 @@ json_node_unset (JsonNode *node)
  * If the node has already been initialized once, it will be reset to
  * the given type, and any data contained will be cleared.
  *
- * Return value: (transfer none): the initialized #JsonNode
+ * Return value: (transfer none): the initialized node
  *
  * Since: 0.16
  */
@@ -192,17 +194,17 @@ json_node_init (JsonNode *node,
 
 /**
  * json_node_init_object:
- * @node: the #JsonNode to initialize
- * @object: (allow-none): the #JsonObject to initialize @node with, or %NULL
+ * @node: the node to initialize
+ * @object: (nullable): the JSON object to initialize @node with, or `NULL`
  *
- * Initializes @node to %JSON_NODE_OBJECT and sets @object into it.
+ * Initializes @node to `JSON_NODE_OBJECT` and sets @object into it.
  *
  * This function will take a reference on @object.
  *
  * If the node has already been initialized once, it will be reset to
  * the given type, and any data contained will be cleared.
  *
- * Return value: (transfer none): the initialized #JsonNode
+ * Return value: (transfer none): the initialized node
  *
  * Since: 0.16
  */
@@ -220,17 +222,17 @@ json_node_init_object (JsonNode   *node,
 
 /**
  * json_node_init_array:
- * @node: the #JsonNode to initialize
- * @array: (allow-none): the #JsonArray to initialize @node with, or %NULL
+ * @node: the node to initialize
+ * @array: (nullable): the JSON array to initialize @node with, or `NULL`
  *
- * Initializes @node to %JSON_NODE_ARRAY and sets @array into it.
+ * Initializes @node to `JSON_NODE_ARRAY` and sets @array into it.
  *
  * This function will take a reference on @array.
  *
  * If the node has already been initialized once, it will be reset to
  * the given type, and any data contained will be cleared.
  *
- * Return value: (transfer none): the initialized #JsonNode
+ * Return value: (transfer none): the initialized node
  *
  * Since: 0.16
  */
@@ -248,15 +250,15 @@ json_node_init_array (JsonNode  *node,
 
 /**
  * json_node_init_int:
- * @node: the #JsonNode to initialize
+ * @node: the node to initialize
  * @value: an integer
  *
- * Initializes @node to %JSON_NODE_VALUE and sets @value into it.
+ * Initializes @node to `JSON_NODE_VALUE` and sets @value into it.
  *
  * If the node has already been initialized once, it will be reset to
  * the given type, and any data contained will be cleared.
  *
- * Return value: (transfer none): the initialized #JsonNode
+ * Return value: (transfer none): the initialized node
  *
  * Since: 0.16
  */
@@ -274,15 +276,15 @@ json_node_init_int (JsonNode *node,
 
 /**
  * json_node_init_double:
- * @node: the #JsonNode to initialize
+ * @node: the node to initialize
  * @value: a floating point value
  *
- * Initializes @node to %JSON_NODE_VALUE and sets @value into it.
+ * Initializes @node to `JSON_NODE_VALUE` and sets @value into it.
  *
  * If the node has already been initialized once, it will be reset to
  * the given type, and any data contained will be cleared.
  *
- * Return value: (transfer none): the initialized #JsonNode
+ * Return value: (transfer none): the initialized node
  *
  * Since: 0.16
  */
@@ -300,15 +302,15 @@ json_node_init_double (JsonNode *node,
 
 /**
  * json_node_init_boolean:
- * @node: the #JsonNode to initialize
+ * @node: the node to initialize
  * @value: a boolean value
  *
- * Initializes @node to %JSON_NODE_VALUE and sets @value into it.
+ * Initializes @node to `JSON_NODE_VALUE` and sets @value into it.
  *
  * If the node has already been initialized once, it will be reset to
  * the given type, and any data contained will be cleared.
  *
- * Return value: (transfer none): the initialized #JsonNode
+ * Return value: (transfer none): the initialized node
  *
  * Since: 0.16
  */
@@ -326,15 +328,15 @@ json_node_init_boolean (JsonNode *node,
 
 /**
  * json_node_init_string:
- * @node: the #JsonNode to initialize
- * @value: (allow-none): a string value
+ * @node: the node to initialize
+ * @value: (nullable): a string value
  *
- * Initializes @node to %JSON_NODE_VALUE and sets @value into it.
+ * Initializes @node to `JSON_NODE_VALUE` and sets @value into it.
  *
  * If the node has already been initialized once, it will be reset to
  * the given type, and any data contained will be cleared.
  *
- * Return value: (transfer none): the initialized #JsonNode
+ * Return value: (transfer none): the initialized node
  *
  * Since: 0.16
  */
@@ -352,14 +354,14 @@ json_node_init_string (JsonNode   *node,
 
 /**
  * json_node_init_null:
- * @node: the #JsonNode to initialize
+ * @node: the node to initialize
  *
- * Initializes @node to %JSON_NODE_NULL.
+ * Initializes @node to `JSON_NODE_NULL`.
  *
  * If the node has already been initialized once, it will be reset to
  * the given type, and any data contained will be cleared.
  *
- * Return value: (transfer none): the initialized #JsonNode
+ * Return value: (transfer none): the initialized node
  *
  * Since: 0.16
  */
@@ -373,18 +375,18 @@ json_node_init_null (JsonNode *node)
 
 /**
  * json_node_new: (constructor)
- * @type: a #JsonNodeType
+ * @type: the type of the node to create 
  *
- * Creates a new #JsonNode of @type.
+ * Creates a new node holding the given @type.
  *
- * This is a convenience function for json_node_alloc() and json_node_init(),
- * and it's the equivalent of:
+ * This is a convenience function for [ctor@Json.Node.alloc] and
+ * [method@Json.Node.init], and it's the equivalent of:
  *
  * ```c
    json_node_init (json_node_alloc (), type);
  * ```
  *
- * Return value: (transfer full): the newly created #JsonNode
+ * Return value: (transfer full): the newly created node
  */
 JsonNode *
 json_node_new (JsonNodeType type)
@@ -397,7 +399,7 @@ json_node_new (JsonNodeType type)
 
 /**
  * json_node_copy:
- * @node: a #JsonNode
+ * @node: the node to copy 
  *
  * Copies @node.
  *
@@ -408,7 +410,7 @@ json_node_new (JsonNodeType type)
  * The copy will be immutable if, and only if, @node is immutable. However,
  * there should be no need to copy an immutable node.
  *
- * Return value: (transfer full): the copied #JsonNode
+ * Return value: (transfer full): the copied of the given node
  */
 JsonNode *
 json_node_copy (JsonNode *node)
@@ -457,7 +459,7 @@ json_node_copy (JsonNode *node)
 
 /**
  * json_node_ref:
- * @node: a #JsonNode
+ * @node: the node to reference 
  *
  * Increments the reference count of @node.
  *
@@ -476,7 +478,7 @@ json_node_ref (JsonNode *node)
 
 /**
  * json_node_unref:
- * @node: (transfer full): a #JsonNode
+ * @node: (transfer full): the node to unreference
  *
  * Decrements the reference count of @node.
  *
@@ -499,14 +501,14 @@ json_node_unref (JsonNode *node)
 
 /**
  * json_node_set_object:
- * @node: a #JsonNode initialized to %JSON_NODE_OBJECT
- * @object: (nullable): a #JsonObject
+ * @node: a node initialized to `JSON_NODE_OBJECT`
+ * @object: (nullable): a JSON object
  *
  * Sets @objects inside @node.
  *
  * The reference count of @object is increased.
  *
- * If @object is %NULL, the node’s existing object is cleared.
+ * If @object is `NULL`, the node’s existing object is cleared.
  *
  * It is an error to call this on an immutable node, or on a node which is not
  * an object node.
@@ -530,8 +532,8 @@ json_node_set_object (JsonNode   *node,
 
 /**
  * json_node_take_object:
- * @node: a #JsonNode initialized to %JSON_NODE_OBJECT
- * @object: (transfer full): a #JsonObject
+ * @node: a node initialized to `JSON_NODE_OBJECT`
+ * @object: (transfer full): a JSON object
  *
  * Sets @object inside @node.
  *
@@ -560,14 +562,14 @@ json_node_take_object (JsonNode   *node,
 
 /**
  * json_node_get_object:
- * @node: a #JsonNode
+ * @node: a node holding a JSON object
  *
- * Retrieves the #JsonObject stored inside a #JsonNode.
+ * Retrieves the object stored inside a node.
  *
  * It is a programmer error to call this on a node which doesn’t hold an
- * object value. Use %JSON_NODE_HOLDS_OBJECT first.
+ * object value. Use `JSON_NODE_HOLDS_OBJECT` first.
  *
- * Return value: (transfer none) (nullable): the #JsonObject
+ * Return value: (transfer none) (nullable): the JSON object
  */
 JsonObject *
 json_node_get_object (JsonNode *node)
@@ -580,16 +582,16 @@ json_node_get_object (JsonNode *node)
 
 /**
  * json_node_dup_object:
- * @node: a #JsonNode
+ * @node: a node holding a JSON object
  *
- * Retrieves the #JsonObject inside @node.
+ * Retrieves the object inside @node.
  *
  * The reference count of the returned object is increased.
  *
  * It is a programmer error to call this on a node which doesn’t hold an
- * object value. Use %JSON_NODE_HOLDS_OBJECT first.
+ * object value. Use `JSON_NODE_HOLDS_OBJECT` first.
  *
- * Return value: (transfer full) (nullable): the #JsonObject
+ * Return value: (transfer full) (nullable): the JSON object
  */
 JsonObject *
 json_node_dup_object (JsonNode *node)
@@ -605,15 +607,15 @@ json_node_dup_object (JsonNode *node)
 
 /**
  * json_node_set_array:
- * @node: a #JsonNode initialized to %JSON_NODE_ARRAY
- * @array: a #JsonArray
+ * @node: a node initialized to `JSON_NODE_ARRAY`
+ * @array: a JSON array
  *
  * Sets @array inside @node.
  *
  * The reference count of @array is increased.
  *
  * It is a programmer error to call this on a node which doesn’t hold an
- * array value. Use %JSON_NODE_HOLDS_ARRAY first.
+ * array value. Use `JSON_NODE_HOLDS_ARRAY` first.
  */
 void
 json_node_set_array (JsonNode  *node,
@@ -634,15 +636,15 @@ json_node_set_array (JsonNode  *node,
 
 /**
  * json_node_take_array:
- * @node: a #JsonNode initialized to %JSON_NODE_ARRAY
- * @array: (transfer full): a #JsonArray
+ * @node: a node initialized to `JSON_NODE_ARRAY`
+ * @array: (transfer full): a JSON array
  *
  * Sets @array inside @node.
  *
  * The reference count of @array is not increased.
  *
  * It is a programmer error to call this on a node which doesn’t hold an
- * array value. Use %JSON_NODE_HOLDS_ARRAY first.
+ * array value. Use `JSON_NODE_HOLDS_ARRAY` first.
  */
 void
 json_node_take_array (JsonNode  *node,
@@ -664,14 +666,14 @@ json_node_take_array (JsonNode  *node,
 
 /**
  * json_node_get_array:
- * @node: a #JsonNode
+ * @node: a node holding an array
  *
- * Retrieves the #JsonArray stored inside a #JsonNode.
+ * Retrieves the JSON array stored inside a node.
  *
  * It is a programmer error to call this on a node which doesn’t hold an
- * array value. Use %JSON_NODE_HOLDS_ARRAY first.
+ * array value. Use `JSON_NODE_HOLDS_ARRAY` first.
  *
- * Return value: (transfer none) (nullable): the #JsonArray
+ * Return value: (transfer none) (nullable): the JSON array
  */
 JsonArray *
 json_node_get_array (JsonNode *node)
@@ -684,16 +686,16 @@ json_node_get_array (JsonNode *node)
 
 /**
  * json_node_dup_array:
- * @node: a #JsonNode
+ * @node: a node holding an array
  *
- * Retrieves the #JsonArray inside @node.
+ * Retrieves the JSON array inside @node.
  *
  * The reference count of the returned array is increased.
  *
  * It is a programmer error to call this on a node which doesn’t hold an
- * array value. Use %JSON_NODE_HOLDS_ARRAY first.
+ * array value. Use `JSON_NODE_HOLDS_ARRAY` first.
  *
- * Return value: (transfer full) (nullable): the #JsonArray with its reference
+ * Return value: (transfer full) (nullable): the JSON array with its reference
  *   count increased.
  */
 JsonArray *
@@ -710,15 +712,16 @@ json_node_dup_array (JsonNode *node)
 
 /**
  * json_node_get_value:
- * @node: a #JsonNode
+ * @node: a node
  * @value: (out caller-allocates): return location for an uninitialized value
  *
- * Retrieves a value from a #JsonNode and copies into @value.
+ * Retrieves a value from a node and copies into @value.
  *
- * When done using it, call g_value_unset() on the #GValue.
+ * When done using it, call `g_value_unset()` on the `GValue` to free the
+ * associated resources.
  *
  * It is a programmer error to call this on a node which doesn’t hold a scalar
- * value. Use %JSON_NODE_HOLDS_VALUE first.
+ * value. Use `JSON_NODE_HOLDS_VALUE` first.
  */
 void
 json_node_get_value (JsonNode *node,
@@ -756,12 +759,24 @@ json_node_get_value (JsonNode *node,
 
 /**
  * json_node_set_value:
- * @node: a #JsonNode initialized to %JSON_NODE_VALUE
- * @value: the #GValue to set
+ * @node: a node initialized to `JSON_NODE_VALUE`
+ * @value: the value to set
+ *
+ * Sets a scalar value inside the given node.
+ *
+ * The contents of the given `GValue` are copied into the `JsonNode`.
+ *
+ * The following `GValue` types have a direct mapping to JSON types:
  *
- * Sets @value inside @node.
+ *  - `G_TYPE_INT64`
+ *  - `G_TYPE_DOUBLE`
+ *  - `G_TYPE_BOOLEAN`
+ *  - `G_TYPE_STRING`
  *
- * The passed #GValue is copied into the #JsonNode.
+ * JSON-GLib will also automatically promote the following `GValue` types:
+ *
+ *  - `G_TYPE_INT` to `G_TYPE_INT64`
+ *  - `G_TYPE_FLOAT` to `G_TYPE_DOUBLE`
  *
  * It is an error to call this on an immutable node, or on a node which is not
  * a value node.
@@ -820,9 +835,9 @@ json_node_set_value (JsonNode     *node,
 
 /**
  * json_node_free:
- * @node: a #JsonNode
+ * @node: the node to free
  *
- * Frees the resources allocated by @node.
+ * Frees the resources allocated by the node.
  */
 void
 json_node_free (JsonNode *node)
@@ -842,15 +857,15 @@ json_node_free (JsonNode *node)
 
 /**
  * json_node_seal:
- * @node: a #JsonNode
+ * @node: the node to seal
  *
- * Seals the #JsonNode, making it immutable to further changes.
+ * Seals the given node, making it immutable to further changes.
  *
  * In order to be sealed, the @node must have a type and value set. The value
- * will be recursively sealed — if the node holds an object, that #JsonObject
+ * will be recursively sealed — if the node holds an object, that JSON object
  * will be sealed, etc.
  *
- * If the @node is already immutable, this is a no-op.
+ * If the `node` is already immutable, this is a no-op.
  *
  * Since: 1.2
  */
@@ -887,13 +902,13 @@ json_node_seal (JsonNode *node)
 
 /**
  * json_node_is_immutable:
- * @node: a #JsonNode
+ * @node: the node to check
  *
  * Check whether the given @node has been marked as immutable by calling
- * json_node_seal() on it.
+ * [method@Json.Node.seal] on it.
  *
  * Since: 1.2
- * Returns: %TRUE if the @node is immutable
+ * Returns: `TRUE` if the @node is immutable
  */
 gboolean
 json_node_is_immutable (JsonNode *node)
@@ -905,11 +920,14 @@ json_node_is_immutable (JsonNode *node)
 
 /**
  * json_node_type_name:
- * @node: a #JsonNode
+ * @node: a node
  *
  * Retrieves the user readable name of the data type contained by @node.
  *
- * Return value: (transfer none): a string containing the name of the type.
+ * **Note**: The name is only meant for debugging purposes, and there is no
+ * guarantee the name will stay the same across different versions.
+ *
+ * Return value: (transfer none): a string containing the name of the type
  */
 const gchar *
 json_node_type_name (JsonNode *node)
@@ -958,10 +976,10 @@ json_node_type_get_name (JsonNodeType node_type)
 
 /**
  * json_node_set_parent:
- * @node: a #JsonNode
- * @parent: (transfer none): the parent #JsonNode of @node
+ * @node: the node to change
+ * @parent: (transfer none) (nullable): the parent node
  *
- * Sets the parent #JsonNode of @node.
+ * Sets the parent node for the given `node`.
  *
  * It is an error to call this with an immutable @parent.
  *
@@ -982,11 +1000,11 @@ json_node_set_parent (JsonNode *node,
 
 /**
  * json_node_get_parent:
- * @node: a #JsonNode
+ * @node: the node to query
  *
- * Retrieves the parent #JsonNode of @node.
+ * Retrieves the parent node of the given @node.
  *
- * Return value: (transfer none) (nullable): the parent node, or %NULL if @node
+ * Return value: (transfer none) (nullable): the parent node, or `NULL` if @node
  *   is the root node
  */
 JsonNode *
@@ -999,7 +1017,7 @@ json_node_get_parent (JsonNode *node)
 
 /**
  * json_node_set_string:
- * @node: a #JsonNode initialized to %JSON_NODE_VALUE
+ * @node: a node initialized to `JSON_NODE_VALUE`
  * @value: a string value
  *
  * Sets @value as the string content of the @node, replacing any existing
@@ -1026,10 +1044,11 @@ json_node_set_string (JsonNode    *node,
 
 /**
  * json_node_get_string:
- * @node: a #JsonNode of type %JSON_NODE_VALUE
+ * @node: a node holding a string
  *
- * Gets the string value stored inside a #JsonNode. If the node does not hold a
- * string value, %NULL is returned.
+ * Gets the string value stored inside a node.
+ *
+ * If the node does not hold a string value, `NULL` is returned.
  *
  * Return value: (nullable): a string value.
  */
@@ -1049,11 +1068,11 @@ json_node_get_string (JsonNode *node)
 
 /**
  * json_node_dup_string:
- * @node: a #JsonNode of type %JSON_NODE_VALUE
+ * @node: a node holding a string
  *
- * Gets a copy of the string value stored inside a #JsonNode.
+ * Gets a copy of the string value stored inside a node.
  *
- * If the node does not hold a string value, %NULL is returned.
+ * If the node does not hold a string value, `NULL` is returned.
  *
  * Return value: (transfer full) (nullable): a copy of the string
  *   inside the node
@@ -1068,7 +1087,7 @@ json_node_dup_string (JsonNode *node)
 
 /**
  * json_node_set_int:
- * @node: a #JsonNode of type %JSON_NODE_VALUE
+ * @node: a node initialized to `JSON_NODE_VALUE`
  * @value: an integer value
  *
  * Sets @value as the integer content of the @node, replacing any existing
@@ -1095,16 +1114,16 @@ json_node_set_int (JsonNode *node,
 
 /**
  * json_node_get_int:
- * @node: a #JsonNode of type %JSON_NODE_VALUE
+ * @node: a node holding an integer
  *
- * Gets the integer value stored inside a #JsonNode.
+ * Gets the integer value stored inside a node.
  *
  * If the node holds a double value, its integer component is returned.
  *
- * If the node holds a %FALSE boolean value, `0` is returned; otherwise,
+ * If the node holds a `FALSE` boolean value, `0` is returned; otherwise,
  * a non-zero integer is returned.
  *
- * If the node holds a %JSON_NODE_NULL value or a value of another
+ * If the node holds a `JSON_NODE_NULL` value or a value of another
  * non-integer type, `0` is returned.
  *
  * Return value: an integer value.
@@ -1131,7 +1150,7 @@ json_node_get_int (JsonNode *node)
 
 /**
  * json_node_set_double:
- * @node: a #JsonNode of type %JSON_NODE_VALUE
+ * @node: a node initialized to `JSON_NODE_VALUE`
  * @value: a double value
  *
  * Sets @value as the double content of the @node, replacing any existing
@@ -1158,16 +1177,16 @@ json_node_set_double (JsonNode *node,
 
 /**
  * json_node_get_double:
- * @node: a #JsonNode of type %JSON_NODE_VALUE
+ * @node: a node holding a floating point value
  *
- * Gets the double value stored inside a #JsonNode.
+ * Gets the double value stored inside a node.
  *
  * If the node holds an integer value, it is returned as a double.
  *
- * If the node holds a %FALSE boolean value, `0.0` is returned; otherwise
+ * If the node holds a `FALSE` boolean value, `0.0` is returned; otherwise
  * a non-zero double is returned.
  *
- * If the node holds a %JSON_NODE_NULL value or a value of another
+ * If the node holds a `JSON_NODE_NULL` value or a value of another
  * non-double type, `0.0` is returned.
  *
  * Return value: a double value.
@@ -1194,7 +1213,7 @@ json_node_get_double (JsonNode *node)
 
 /**
  * json_node_set_boolean:
- * @node: a #JsonNode of type %JSON_NODE_VALUE
+ * @node: a node initialized to `JSON_NODE_VALUE`
  * @value: a boolean value
  *
  * Sets @value as the boolean content of the @node, replacing any existing
@@ -1221,15 +1240,15 @@ json_node_set_boolean (JsonNode *node,
 
 /**
  * json_node_get_boolean:
- * @node: a #JsonNode of type %JSON_NODE_VALUE
+ * @node: a node holding a boolean value
  *
- * Gets the boolean value stored inside a #JsonNode.
+ * Gets the boolean value stored inside a node.
  *
- * If the node holds an integer or double value which is zero, %FALSE is
- * returned; otherwise %TRUE is returned.
+ * If the node holds an integer or double value which is zero, `FALSE` is
+ * returned; otherwise `TRUE` is returned.
  *
- * If the node holds a %JSON_NODE_NULL value or a value of another
- * non-boolean type, %FALSE is returned.
+ * If the node holds a `JSON_NODE_NULL` value or a value of another
+ * non-boolean type, `FALSE` is returned.
  *
  * Return value: a boolean value.
  */
@@ -1255,9 +1274,9 @@ json_node_get_boolean (JsonNode *node)
 
 /**
  * json_node_get_node_type:
- * @node: a #JsonNode
+ * @node: the node to check
  *
- * Retrieves the #JsonNodeType of @node
+ * Retrieves the type of a @node.
  *
  * Return value: the type of the node
  *
@@ -1273,14 +1292,14 @@ json_node_get_node_type (JsonNode *node)
 
 /**
  * json_node_is_null:
- * @node: a #JsonNode
+ * @node: the node to check
  *
- * Checks whether @node is a %JSON_NODE_NULL.
+ * Checks whether @node is a `JSON_NODE_NULL`.
  *
- * 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.
+ * A `JSON_NODE_NULL` node is not the same as a `NULL` node; a `JSON_NODE_NULL`
+ * represents a literal `null` value in the JSON tree.
  *
- * Return value: %TRUE if the node is null
+ * Return value: `TRUE` if the node is null
  *
  * Since: 0.8
  */
@@ -1292,7 +1311,7 @@ json_node_is_null (JsonNode *node)
   return node->type == JSON_NODE_NULL;
 }
 
-/**
+/*< private >
  * json_type_is_a:
  * @sub: sub-type
  * @super: super-type
@@ -1306,7 +1325,7 @@ json_node_is_null (JsonNode *node)
  *
  * Reference: http://json-schema.org/latest/json-schema-core.html#rfc.section.3.5
  *
- * Returns: %TRUE if @sub is a sub-type of, or equal to, @super; %FALSE otherwise
+ * Returns: `TRUE` if @sub is a sub-type of, or equal to, @super; `FALSE` otherwise
  * Since: 1.2
  */
 static gboolean
@@ -1357,7 +1376,7 @@ json_string_hash (gconstpointer key)
  *
  * Check whether @a and @b are equal UTF-8 JSON strings.
  *
- * Returns: %TRUE if @a and @b are equal; %FALSE otherwise
+ * Returns: `TRUE` if @a and @b are equal; `FALSE` otherwise
  * Since: 1.2
  */
 gboolean
@@ -1391,12 +1410,12 @@ json_string_compare (gconstpointer  a,
  * json_node_hash:
  * @key: (type JsonNode): a JSON node to hash
  *
- * Calculate a hash value for the given @key (a #JsonNode).
+ * Calculate a hash value for the given @key.
  *
  * The hash is calculated over the node and its value, recursively. If the node
  * is immutable, this is a fast operation; otherwise, it scales proportionally
  * with the size of the node’s value (for example, with the number of members
- * in the #JsonObject if this node contains an object).
+ * in the JSON object if this node contains an object).
  *
  * Returns: hash value for @key
  * Since: 1.2
@@ -1436,13 +1455,13 @@ json_node_hash (gconstpointer key)
  * @a: (type JsonNode): a JSON node
  * @b: (type JsonNode): another JSON node
  *
- * Check whether @a and @b are equal #JsonNodes, meaning they have the same
+ * Check whether @a and @b are equal node, meaning they have the same
  * type and same values (checked recursively).
  *
  * Note that integer values are compared numerically, ignoring type, so a
  * double value 4.0 is equal to the integer value 4.
  *
- * Returns: %TRUE if @a and @b are equal; %FALSE otherwise
+ * Returns: `TRUE` if @a and @b are equal; `FALSE` otherwise
  * Since: 1.2
  */
 gboolean
diff --git a/json-glib/json-object.c b/json-glib/json-object.c
index 3c4c376..b109abd 100644
--- a/json-glib/json-object.c
+++ b/json-glib/json-object.c
@@ -58,7 +58,7 @@ G_DEFINE_BOXED_TYPE (JsonObject, json_object, json_object_ref, json_object_unref
  * 
  * Creates a new object.
  *
- * Return value: (transfer full): the newly created object
+ * Returns: (transfer full): the newly created object
  */
 JsonObject *
 json_object_new (void)
@@ -79,11 +79,11 @@ json_object_new (void)
 
 /**
  * json_object_ref:
- * @object: an object
+ * @object: a JSON object
  *
  * Acquires a reference on the given object.
  *
- * Return value: (transfer none): the given object, with the reference count
+ * Returns: (transfer none): the given object, with the reference count
  *   increased by one.
  */
 JsonObject *
@@ -99,7 +99,7 @@ json_object_ref (JsonObject *object)
 
 /**
  * json_object_unref:
- * @object: an object
+ * @object: a JSON object
  *
  * Releases a reference on the given object.
  *
@@ -124,7 +124,7 @@ json_object_unref (JsonObject *object)
 
 /**
  * json_object_seal:
- * @object: an object
+ * @object: a JSON object
  *
  * Seals the object, making it immutable to further changes.
  *
@@ -158,7 +158,7 @@ json_object_seal (JsonObject *object)
 
 /**
  * json_object_is_immutable:
- * @object: an object
+ * @object: a JSON object
  *
  * Checks whether the given object has been marked as immutable by calling
  * [method@Json.Object.seal] on it.
@@ -205,7 +205,7 @@ object_set_member_internal (JsonObject  *object,
 
 /**
  * json_object_add_member:
- * @object: an object
+ * @object: a JSON object
  * @member_name: the name of the member
  * @node: (transfer full): the value of the member
  *
@@ -238,7 +238,7 @@ json_object_add_member (JsonObject  *object,
 
 /**
  * json_object_set_member:
- * @object: an object
+ * @object: a JSON object
  * @member_name: the name of the member
  * @node: (transfer full): the value of the member
  *
@@ -276,7 +276,7 @@ set_member:
 
 /**
  * json_object_set_int_member:
- * @object: an object
+ * @object: a JSON object
  * @member_name: the name of the member
  * @value: the value of the member
  *
@@ -299,7 +299,7 @@ json_object_set_int_member (JsonObject  *object,
 
 /**
  * json_object_set_double_member:
- * @object: an object
+ * @object: a JSON object
  * @member_name: the name of the member
  * @value: the value of the member
  *
@@ -322,7 +322,7 @@ json_object_set_double_member (JsonObject  *object,
 
 /**
  * json_object_set_boolean_member:
- * @object: an object
+ * @object: a JSON object
  * @member_name: the name of the member
  * @value: the value of the member
  *
@@ -345,7 +345,7 @@ json_object_set_boolean_member (JsonObject  *object,
 
 /**
  * json_object_set_string_member:
- * @object: an object
+ * @object: a JSON object
  * @member_name: the name of the member
  * @value: the value of the member
  *
@@ -377,7 +377,7 @@ json_object_set_string_member (JsonObject  *object,
 
 /**
  * json_object_set_null_member:
- * @object: an object
+ * @object: a JSON object
  * @member_name: the name of the member
  *
  * Convenience function for setting an object member with a `null` value.
@@ -398,7 +398,7 @@ json_object_set_null_member (JsonObject  *object,
 
 /**
  * json_object_set_array_member:
- * @object: an bject
+ * @object: a JSON object
  * @member_name: the name of the member
  * @value: (transfer full): the value of the member
  *
@@ -433,7 +433,7 @@ json_object_set_array_member (JsonObject  *object,
 
 /**
  * json_object_set_object_member:
- * @object: a #JsonObject
+ * @object: a JSON object
  * @member_name: the name of the member
  * @value: (transfer full): the value of the member
  *
@@ -468,14 +468,14 @@ json_object_set_object_member (JsonObject  *object,
 
 /**
  * json_object_get_members:
- * @object: an object
+ * @object: a JSON object
  *
  * Retrieves all the names of the members of an object.
  *
  * You can obtain the value for each member by iterating the returned list
  * and calling [method@Json.Object.get_member].
  *
- * Return value: (element-type utf8) (transfer container) (nullable): the
+ * Returns: (element-type utf8) (transfer container) (nullable): the
  *   member names of the object
  */
 GList *
@@ -497,11 +497,11 @@ json_object_get_members_internal (JsonObject *object)
 
 /**
  * json_object_get_values:
- * @object: an object
+ * @object: a JSON object
  *
  * Retrieves all the values of the members of an object.
  *
- * Return value: (element-type JsonNode) (transfer container) (nullable): the
+ * Returns: (element-type JsonNode) (transfer container) (nullable): the
  *   member values of the object
  */
 GList *
@@ -520,12 +520,12 @@ json_object_get_values (JsonObject *object)
 
 /**
  * json_object_dup_member:
- * @object: an object
+ * @object: a JSON object
  * @member_name: the name of the JSON object member to access
  *
  * Retrieves a copy of the value of the given member inside an object.
  *
- * Return value: (transfer full) (nullable): a copy of the value for the
+ * Returns: (transfer full) (nullable): a copy of the value for the
  *   requested object member
  *
  * Since: 0.6
@@ -555,12 +555,12 @@ object_get_member_internal (JsonObject  *object,
 
 /**
  * json_object_get_member:
- * @object: an object
+ * @object: a JSON object
  * @member_name: the name of the JSON object member to access
  *
  * Retrieves the value of the given member inside an object.
  *
- * Return value: (transfer none) (nullable): the value for the
+ * Returns: (transfer none) (nullable): the value for the
  *   requested object member
  */
 JsonNode *
@@ -615,17 +615,17 @@ json_object_get_ ##type_name## _member_with_default (JsonObject *object, \
 
 /**
  * json_object_get_int_member:
- * @object: a #JsonObject
- * @member_name: the name of the @object member
+ * @object: a JSON object
+ * @member_name: the name of the object member
  *
  * Convenience function that retrieves the integer value
  * stored in @member_name of @object. It is an error to specify a
  * @member_name which does not exist.
  *
- * See also: json_object_get_int_member_with_default(),
- * json_object_get_member() and json_object_has_member()
+ * See also: [method@Json.Object.get_int_member_with_default],
+ *   [method@Json.Object.get_member], [method@Json.Object.has_member]
  *
- * Return value: the integer value of the object's member
+ * Returns: the integer value of the object's member
  *
  * Since: 0.8
  */
@@ -633,8 +633,8 @@ JSON_OBJECT_GET (gint64, int)
 
 /**
  * json_object_get_int_member_with_default:
- * @object: a #JsonObject
- * @member_name: the name of the @object member
+ * @object: a JSON object
+ * @member_name: the name of the object member
  * @default_value: the value to return if @member_name is not valid
  *
  * Convenience function that retrieves the integer value
@@ -652,17 +652,17 @@ JSON_OBJECT_GET_DEFAULT (gint64, int)
 
 /**
  * json_object_get_double_member:
- * @object: a #JsonObject
+ * @object: a JSON object
  * @member_name: the name of the member
  *
  * Convenience function that retrieves the floating point value
  * stored in @member_name of @object. It is an error to specify a
  * @member_name which does not exist.
  *
- * See also: json_object_get_double_member_with_default(),
- * json_object_get_member() and json_object_has_member()
+ * See also: [method@Json.Object.get_double_member_with_default],
+ *   [method@Json.Object.get_member], [method@Json.Object.has_member]
  *
- * Return value: the floating point value of the object's member
+ * Returns: the floating point value of the object's member
  *
  * Since: 0.8
  */
@@ -670,7 +670,7 @@ JSON_OBJECT_GET (gdouble, double)
 
 /**
  * json_object_get_double_member_with_default:
- * @object: a #JsonObject
+ * @object: a JSON object
  * @member_name: the name of the @object member
  * @default_value: the value to return if @member_name is not valid
  *
@@ -689,17 +689,17 @@ JSON_OBJECT_GET_DEFAULT (double, double)
 
 /**
  * json_object_get_boolean_member:
- * @object: a #JsonObject
+ * @object: a JSON object
  * @member_name: the name of the member
  *
  * Convenience function that retrieves the boolean value
  * stored in @member_name of @object. It is an error to specify a
  * @member_name which does not exist.
  *
- * See also: json_object_get_boolean_member_with_default(),
- * json_object_get_member() and json_object_has_member()
+ * See also: [method@Json.Object.get_boolean_member_with_default],
+ *   [method@Json.Object.get_member], [method@Json.Object.has_member]
  *
- * Return value: the boolean value of the object's member
+ * Returns: the boolean value of the object's member
  *
  * Since: 0.8
  */
@@ -707,7 +707,7 @@ JSON_OBJECT_GET (gboolean, boolean)
 
 /**
  * json_object_get_boolean_member_with_default:
- * @object: a #JsonObject
+ * @object: a JSON object
  * @member_name: the name of the @object member
  * @default_value: the value to return if @member_name is not valid
  *
@@ -726,17 +726,17 @@ JSON_OBJECT_GET_DEFAULT (gboolean, boolean)
 
 /**
  * json_object_get_string_member:
- * @object: a #JsonObject
+ * @object: a JSON object
  * @member_name: the name of the member
  *
  * Convenience function that retrieves the string value
  * stored in @member_name of @object. It is an error to specify a
  * @member_name that does not exist.
  *
- * See also: json_object_get_string_member_with_default(),
- * json_object_get_member() and json_object_has_member()
+ * See also: [method@Json.Object.get_string_member_with_default],
+ *   [method@Json.Object.get_member], [method@Json.Object.has_member]
  *
- * Return value: the string value of the object's member
+ * Returns: the string value of the object's member
  *
  * Since: 0.8
  */
@@ -744,7 +744,7 @@ JSON_OBJECT_GET (const gchar *, string)
 
 /**
  * json_object_get_string_member_with_default:
- * @object: a #JsonObject
+ * @object: a JSON object
  * @member_name: the name of the @object member
  * @default_value: the value to return if @member_name is not valid
  *
@@ -763,16 +763,16 @@ JSON_OBJECT_GET_DEFAULT (const char *, string)
 
 /**
  * json_object_get_null_member:
- * @object: a #JsonObject
+ * @object: a JSON object
  * @member_name: the name of the member
  *
  * Convenience function that checks whether the value
  * stored in @member_name of @object is null. It is an error to
  * specify a @member_name which does not exist.
  *
- * See also: json_object_get_member() and json_object_has_member()
+ * See also: [method@Json.Object.get_member], [method@Json.Object.has_member]
  *
- * Return value: %TRUE if the value is null
+ * Returns: `TRUE` if the value is `null`
  *
  * Since: 0.8
  */
@@ -802,16 +802,18 @@ json_object_get_null_member (JsonObject  *object,
 
 /**
  * json_object_get_array_member:
- * @object: a #JsonObject
+ * @object: a JSON object
  * @member_name: the name of the member
  *
  * Convenience function that retrieves the array
  * stored in @member_name of @object. It is an error to specify a
  * @member_name which does not exist.
  *
- * See also: json_object_get_member() and json_object_has_member()
+ * If @member_name contains `null`, then this function will return `NULL`.
  *
- * Return value: (transfer none): the array inside the object's member
+ * See also: [method@Json.Object.get_member], [method@Json.Object.has_member]
+ *
+ * Returns: (transfer none) (nullable): the array inside the object's member
  *
  * Since: 0.8
  */
@@ -836,17 +838,18 @@ json_object_get_array_member (JsonObject  *object,
 
 /**
  * json_object_get_object_member:
- * @object: a #JsonObject
+ * @object: a JSON object
  * @member_name: the name of the member
  *
  * Convenience function that retrieves the object
  * stored in @member_name of @object. It is an error to specify a @member_name
  * which does not exist.
  *
- * See also: json_object_get_member() and json_object_has_member()
+ * If @member_name contains `null`, then this function will return `NULL`.
+ *
+ * See also: [method@Json.Object.get_member], [method@Json.Object.has_member]
  *
- * Return value: (transfer none) (nullable): the object inside the object’s
- *    member, or %NULL if the value for the member is `null`
+ * Returns: (transfer none) (nullable): the object inside the object's member
  *
  * Since: 0.8
  */
@@ -871,12 +874,12 @@ json_object_get_object_member (JsonObject  *object,
 
 /**
  * json_object_has_member:
- * @object: a #JsonObject
+ * @object: a JSON object
  * @member_name: the name of a JSON object member
  *
  * Checks whether @object has a member named @member_name.
  *
- * Return value: %TRUE if the JSON object has the requested member
+ * Returns: `TRUE` if the JSON object has the requested member
  */
 gboolean
 json_object_has_member (JsonObject *object,
@@ -890,11 +893,11 @@ json_object_has_member (JsonObject *object,
 
 /**
  * json_object_get_size:
- * @object: a #JsonObject
+ * @object: a JSON object
  *
- * Retrieves the number of members of a #JsonObject.
+ * Retrieves the number of members of a JSON object.
  *
- * Return value: the number of members
+ * Returns: the number of members
  */
 guint
 json_object_get_size (JsonObject *object)
@@ -906,7 +909,7 @@ json_object_get_size (JsonObject *object)
 
 /**
  * json_object_remove_member:
- * @object: a #JsonObject
+ * @object: a JSON object
  * @member_name: the name of the member to remove
  *
  * Removes @member_name from @object, freeing its allocated resources.
@@ -936,18 +939,18 @@ json_object_remove_member (JsonObject  *object,
 
 /**
  * json_object_foreach_member:
- * @object: a #JsonObject
+ * @object: a JSON object
  * @func: (scope call): the function to be called on each member
  * @data: (closure): data to be passed to the function
  *
  * Iterates over all members of @object and calls @func on
  * each one of them.
  *
- * It is safe to change the value of a #JsonNode of the @object
- * from within the iterator @func, but it is not safe to add or
- * remove members from the @object.
+ * It is safe to change the value of a member of the oobject
+ * from within the iterator function, but it is not safe to add or
+ * remove members from the object.
  *
- * The order in which the @object members are iterated is the
+ * The order in which the object members are iterated is the
  * insertion order.
  *
  * Since: 0.8
@@ -980,7 +983,7 @@ json_object_foreach_member (JsonObject        *object,
  * json_object_hash:
  * @key: (type JsonObject): a JSON object to hash
  *
- * Calculate a hash value for the given @key (a #JsonObject).
+ * Calculate a hash value for the given @key (a JSON object).
  *
  * The hash is calculated over the object and all its members, recursively. If
  * the object is immutable, this is a fast operation; otherwise, it scales
@@ -1018,10 +1021,10 @@ json_object_hash (gconstpointer key)
  * @a: (type JsonObject): a JSON object
  * @b: (type JsonObject): another JSON object
  *
- * Check whether @a and @b are equal #JsonObjects, meaning they have the same
+ * Check whether @a and @b are equal objects, meaning they have the same
  * set of members, and the values of corresponding members are equal.
  *
- * Returns: %TRUE if @a and @b are equal; %FALSE otherwise
+ * Returns: `TRUE` if @a and @b are equal, and `FALSE` otherwise
  * Since: 1.2
  */
 gboolean
@@ -1074,8 +1077,8 @@ json_object_equal (gconstpointer  a,
 
 /**
  * json_object_iter_init:
- * @iter: an uninitialised #JsonObjectIter
- * @object: the #JsonObject to iterate over
+ * @iter: an uninitialised JSON object iterator
+ * @object: the JSON object to iterate over
  *
  * Initialises the @iter and associate it with @object.
  *
@@ -1114,20 +1117,20 @@ json_object_iter_init (JsonObjectIter  *iter,
 
 /**
  * json_object_iter_next:
- * @iter: a #JsonObjectIter
+ * @iter: a JSON object iterator
  * @member_name: (out callee-allocates) (transfer none) (optional): return
  *    location for the member name, or %NULL to ignore
  * @member_node: (out callee-allocates) (transfer none) (optional): return
  *    location for the member value, or %NULL to ignore
  *
- * Advances @iter and retrieves the next member in the object.
+ * Advances the iterator and retrieves the next member in the object.
  *
- * If the end of the object is reached, %FALSE is returned and @member_name
+ * If the end of the object is reached, `FALSE` is returned and @member_name
  * and @member_node are set to invalid values. After that point, the @iter
  * is invalid.
  *
  * The order in which members are returned by the iterator is undefined. The
- * iterator is invalidated if its #JsonObject is modified during iteration.
+ * iterator is invalidated if the object is modified during iteration.
  *
  * You must use this function with an iterator initialized with
  * [method@Json.ObjectIter.init]; using this function with an iterator
@@ -1136,8 +1139,8 @@ json_object_iter_init (JsonObjectIter  *iter,
  *
  * See also: [method@Json.ObjectIter.next_ordered]
  *
- * Returns: %TRUE if @member_name and @member_node are valid; %FALSE if the end
- *   of the object has been reached
+ * Returns: `TRUE` if @member_name and @member_node are valid; `FALSE` if
+ *   there are no more members
  *
  * Since: 1.2
  */
@@ -1159,8 +1162,8 @@ json_object_iter_next (JsonObjectIter  *iter,
 
 /**
  * json_object_iter_init_ordered:
- * @iter: an uninitialised #JsonObjectIter
- * @object: the #JsonObject to iterate over
+ * @iter: an uninitialised iterator
+ * @object: the JSON object to iterate over
  *
  * Initialises the @iter and associate it with @object.
  *
@@ -1198,15 +1201,15 @@ json_object_iter_init_ordered (JsonObjectIter  *iter,
 
 /**
  * json_object_iter_next_ordered:
- * @iter: a #JsonObjectIter
+ * @iter: an ordered JSON object iterator
  * @member_name: (out callee-allocates) (transfer none) (optional): return
  *    location for the member name, or %NULL to ignore
  * @member_node: (out callee-allocates) (transfer none) (optional): return
  *    location for the member value, or %NULL to ignore
  *
- * Advances @iter and retrieves the next member in the object.
+ * Advances the iterator and retrieves the next member in the object.
  *
- * If the end of the object is reached, %FALSE is returned and @member_name and
+ * If the end of the object is reached, `FALSE` is returned and @member_name and
  * @member_node are set to invalid values. After that point, the @iter is invalid.
  *
  * The order in which members are returned by the iterator is the same order in
@@ -1219,7 +1222,7 @@ json_object_iter_init_ordered (JsonObjectIter  *iter,
  *
  * See also: [method@Json.ObjectIter.next]
  *
- * Returns: %TRUE if @member_name and @member_node are valid; %FALSE if the end
+ * Returns: `TRUE `if @member_name and @member_node are valid; `FALSE` if the end
  *    of the object has been reached
  *
  * Since: 1.6
diff --git a/json-glib/json-parser.c b/json-glib/json-parser.c
index c5ea47b..c5e58f4 100644
--- a/json-glib/json-parser.c
+++ b/json-glib/json-parser.c
@@ -27,8 +27,42 @@
 /**
  * JsonParser:
  *
- * #JsonParser provides an object for parsing a JSON data stream, either
+ * `JsonParser` provides an object for parsing a JSON data stream, either
  * inside a file or inside a static buffer.
+ *
+ * ## Using `JsonParser`
+ *
+ * The `JsonParser` API is fairly simple:
+ *
+ * ```c
+ * gboolean
+ * parse_json (const char *filename)
+ * {
+ *   g_autoptr(JsonParser) parser = json_parser_new ();
+ *   g_autoptr(GError) error = NULL
+ *
+ *   json_parser_load_from_file (parser, filename, &error);
+ *   if (error != NULL)
+ *     {
+ *       g_critical ("Unable to parse '%s': %s", filename, error->message);
+ *       return FALSE;
+ *     }
+ *
+ *   g_autoptr(JsonNode) root = json_parser_get_root (parser);
+ *
+ *   // manipulate the object tree from the root node
+ *
+ *   return TRUE
+ * }
+ * ```
+ *
+ * By default, the entire process of loading the data and parsing it is
+ * synchronous; the [method@Json.Parser.load_from_stream_async()] API will
+ * load the data asynchronously, but parse it in the main context as the
+ * signals of the parser must be emitted in the same thread. If you do
+ * not use signals, and you wish to also parse the JSON data without blocking,
+ * you should use a `GTask` and the synchronous `JsonParser` API inside the
+ * task itself.
  */
 
 #include "config.h"
@@ -197,7 +231,7 @@ json_parser_class_init (JsonParserClass *klass)
   /**
    * JsonParser:immutable:
    *
-   * Whether the #JsonNode tree built by the #JsonParser should be immutable
+   * Whether the tree built by the parser should be immutable
    * when created.
    *
    * Making the output immutable on creation avoids the expense
@@ -216,10 +250,9 @@ json_parser_class_init (JsonParserClass *klass)
 
   /**
    * JsonParser::parse-start:
-   * @parser: the #JsonParser that received the signal
+   * @parser: the parser that emitted the signal
    * 
-   * The ::parse-start signal is emitted when the parser began parsing
-   * a JSON data stream.
+   * This signal is emitted when a parser starts parsing a JSON data stream.
    */
   parser_signals[PARSE_START] =
     g_signal_new ("parse-start",
@@ -231,10 +264,10 @@ json_parser_class_init (JsonParserClass *klass)
                   G_TYPE_NONE, 0);
   /**
    * JsonParser::parse-end:
-   * @parser: the #JsonParser that received the signal
+   * @parser: the parser that emitted the signal
    *
-   * The ::parse-end signal is emitted when the parser successfully
-   * finished parsing a JSON data stream
+   * This signal is emitted when a parser successfully finished parsing a
+   * JSON data stream
    */
   parser_signals[PARSE_END] =
     g_signal_new ("parse-end",
@@ -245,10 +278,9 @@ json_parser_class_init (JsonParserClass *klass)
                   G_TYPE_NONE, 0);
   /**
    * JsonParser::object-start:
-   * @parser: the #JsonParser that received the signal
+   * @parser: the parser that emitted the signal
    *
-   * The ::object-start signal is emitted each time the #JsonParser
-   * starts parsing a #JsonObject.
+   * This signal is emitted each time a parser starts parsing a JSON object.
    */
   parser_signals[OBJECT_START] =
     g_signal_new ("object-start",
@@ -259,14 +291,12 @@ json_parser_class_init (JsonParserClass *klass)
                   G_TYPE_NONE, 0);
   /**
    * JsonParser::object-member:
-   * @parser: the #JsonParser that received the signal
-   * @object: a #JsonObject
+   * @parser: the parser that emitted the signal
+   * @object: the JSON object being parsed
    * @member_name: the name of the newly parsed member
    *
-   * The ::object-member signal is emitted each time the #JsonParser
-   * has successfully parsed a single member of a #JsonObject.
-   *
-   * The object and member are passed to the signal handlers.
+   * The `::object-member` signal is emitted each time a parser
+   * has successfully parsed a single member of a JSON object
    */
   parser_signals[OBJECT_MEMBER] =
     g_signal_new ("object-member",
@@ -279,11 +309,11 @@ json_parser_class_init (JsonParserClass *klass)
                   G_TYPE_STRING);
   /**
    * JsonParser::object-end:
-   * @parser: the #JsonParser that received the signal
-   * @object: the parsed #JsonObject
+   * @parser: the parser that emitted the signal
+   * @object: the parsed JSON object
    *
-   * The ::object-end signal is emitted each time the #JsonParser
-   * has successfully parsed an entire #JsonObject.
+   * The `::object-end` signal is emitted each time a parser
+   * has successfully parsed an entire JSON object.
    */
   parser_signals[OBJECT_END] =
     g_signal_new ("object-end",
@@ -295,10 +325,10 @@ json_parser_class_init (JsonParserClass *klass)
                   JSON_TYPE_OBJECT);
   /**
    * JsonParser::array-start:
-   * @parser: the #JsonParser that received the signal
+   * @parser: the parser that emitted the signal
    *
-   * The ::array-start signal is emitted each time the #JsonParser
-   * starts parsing a #JsonArray
+   * The `::array-start` signal is emitted each time a parser
+   * starts parsing a JSON array.
    */
   parser_signals[ARRAY_START] =
     g_signal_new ("array-start",
@@ -309,14 +339,12 @@ json_parser_class_init (JsonParserClass *klass)
                   G_TYPE_NONE, 0);
   /**
    * JsonParser::array-element:
-   * @parser: the #JsonParser that received the signal
-   * @array: a #JsonArray
-   * @index_: the index of the newly parsed element
-   *
-   * The ::array-element signal is emitted each time the #JsonParser
-   * has successfully parsed a single element of a #JsonArray.
+   * @parser: the parser that emitted the signal
+   * @array: a JSON array
+   * @index_: the index of the newly parsed array element
    *
-   * The array and element index are passed to the signal handlers.
+   * The `::array-element` signal is emitted each time a parser
+   * has successfully parsed a single element of a JSON array.
    */
   parser_signals[ARRAY_ELEMENT] =
     g_signal_new ("array-element",
@@ -329,11 +357,11 @@ json_parser_class_init (JsonParserClass *klass)
                   G_TYPE_INT);
   /**
    * JsonParser::array-end:
-   * @parser: the #JsonParser that received the signal
-   * @array: the parsed #JsonArray
+   * @parser: the parser that emitted the signal
+   * @array: the parsed JSON array
    *
-   * The ::array-end signal is emitted each time the #JsonParser
-   * has successfully parsed an entire #JsonArray
+   * The `::array-end` signal is emitted each time a parser
+   * has successfully parsed an entire JSON array.
    */
   parser_signals[ARRAY_END] =
     g_signal_new ("array-end",
@@ -345,10 +373,10 @@ json_parser_class_init (JsonParserClass *klass)
                   JSON_TYPE_ARRAY);
   /**
    * JsonParser::error:
-   * @parser: the parser instance that received the signal
-   * @error: a pointer to the #GError
+   * @parser: the parser that emitted the signal
+   * @error: the error
    *
-   * The ::error signal is emitted each time a #JsonParser encounters
+   * The `::error` signal is emitted each time a parser encounters
    * an error in a JSON stream.
    */
   parser_signals[ERROR] =
@@ -950,7 +978,7 @@ json_scanner_create (JsonParser *parser)
  * You can use the `JsonParser` to load a JSON stream from either a file or a
  * buffer and then walk the hierarchy using the data types API.
  *
- * Return value: (transfer full): the newly created parser
+ * Returns: (transfer full): the newly created parser
  */
 JsonParser *
 json_parser_new (void)
@@ -961,11 +989,11 @@ json_parser_new (void)
 /**
  * json_parser_new_immutable:
  *
- * Creates a new #JsonParser instance with its #JsonParser:immutable property
- * set to %TRUE to create immutable output trees.
+ * Creates a new parser instance with its [property@Json.Parser:immutable]
+ * property set to `TRUE` to create immutable output trees.
  *
  * Since: 1.2
- * Returns: (transfer full): a new #JsonParser
+ * Returns: (transfer full): the newly created parser 
  */
 JsonParser *
 json_parser_new_immutable (void)
@@ -1098,11 +1126,11 @@ json_parser_load (JsonParser   *parser,
 
 /**
  * json_parser_load_from_file:
- * @parser: a #JsonParser
- * @filename: the path for the file to parse
+ * @parser: a parser
+ * @filename: (type filename): the path for the file to parse
  * @error: return location for a #GError
  *
- * Loads a JSON stream from the content of @filename and parses it.
+ * Loads a JSON stream from the content of `filename` and parses it.
  *
  * If the file is large or shared between processes,
  * [method@Json.Parser.load_from_mapped_file] may be a more efficient
@@ -1110,7 +1138,7 @@ json_parser_load (JsonParser   *parser,
  *
  * See also: [method@Json.Parser.load_from_data]
  *
- * Return value: %TRUE if the file was successfully loaded and parsed.
+ * Returns: `TRUE` if the file was successfully loaded and parsed.
  */
 gboolean
 json_parser_load_from_file (JsonParser   *parser,
@@ -1153,8 +1181,8 @@ json_parser_load_from_file (JsonParser   *parser,
 
 /**
  * json_parser_load_from_mapped_file:
- * @parser: a #JsonParser
- * @filename: the path for the file to parse
+ * @parser: a parser
+ * @filename: (type filename): the path for the file to parse
  * @error: return location for a #GError
  *
  * Loads a JSON stream from the content of `filename` and parses it.
@@ -1165,7 +1193,7 @@ json_parser_load_from_file (JsonParser   *parser,
  *
  * If mapping or reading the file fails, a `G_FILE_ERROR` will be returned.
  *
- * Return value: %TRUE if the file was successfully loaded and parsed.
+ * Returns: `TRUE` if the file was successfully loaded and parsed.
  * Since: 1.6
  */
 gboolean
@@ -1209,9 +1237,9 @@ json_parser_load_from_mapped_file (JsonParser   *parser,
 
 /**
  * json_parser_load_from_data:
- * @parser: a #JsonParser
+ * @parser: a parser
  * @data: the buffer to parse
- * @length: the length of the buffer, or -1
+ * @length: the length of the buffer, or -1 if it is `NUL` terminated
  * @error: return location for a #GError
  *
  * Loads a JSON stream from a buffer and parses it.
@@ -1219,7 +1247,7 @@ json_parser_load_from_mapped_file (JsonParser   *parser,
  * You can call this function multiple times with the same parser, but the
  * contents of the parser will be destroyed each time.
  *
- * Return value: %TRUE if the buffer was succesfully parsed
+ * Returns: `TRUE` if the buffer was succesfully parsed
  */
 gboolean
 json_parser_load_from_data (JsonParser   *parser,
@@ -1255,7 +1283,7 @@ json_parser_load_from_data (JsonParser   *parser,
 
 /**
  * json_parser_get_root:
- * @parser: a #JsonParser
+ * @parser: a parser
  *
  * Retrieves the top level node from the parsed JSON stream.
  *
@@ -1263,7 +1291,7 @@ json_parser_load_from_data (JsonParser   *parser,
  * will be `NULL`. It will also be `NULL` if it has been stolen using
  * [method@Json.Parser.steal_root].
  *
- * Return value: (transfer none) (nullable): the root node.
+ * Returns: (transfer none) (nullable): the root node.
  */
 JsonNode *
 json_parser_get_root (JsonParser *parser)
@@ -1280,7 +1308,7 @@ json_parser_get_root (JsonParser *parser)
 
 /**
  * json_parser_steal_root:
- * @parser: a #JsonParser
+ * @parser: a parser
  *
  * Steals the top level node from the parsed JSON stream.
  *
@@ -1308,7 +1336,7 @@ json_parser_steal_root (JsonParser *parser)
 
 /**
  * json_parser_get_current_line:
- * @parser: a #JsonParser
+ * @parser: a parser
  *
  * Retrieves the line currently parsed, starting from 1.
  *
@@ -1316,7 +1344,7 @@ json_parser_steal_root (JsonParser *parser)
  * function from outside the signal handlers emitted by the parser will
  * yield 0.
  *
- * Return value: the currently parsed line, or 0.
+ * Returns: the currently parsed line, or 0.
  */
 guint
 json_parser_get_current_line (JsonParser *parser)
@@ -1331,7 +1359,7 @@ json_parser_get_current_line (JsonParser *parser)
 
 /**
  * json_parser_get_current_pos:
- * @parser: a #JsonParser
+ * @parser: a parser
  *
  * Retrieves the current position inside the current line, starting
  * from 0.
@@ -1340,7 +1368,7 @@ json_parser_get_current_line (JsonParser *parser)
  * function from outside the signal handlers emitted by the parser will
  * yield 0.
  *
- * Return value: the position in the current line, or 0.
+ * Returns: the position in the current line, or 0.
  */
 guint
 json_parser_get_current_pos (JsonParser *parser)
@@ -1355,7 +1383,7 @@ json_parser_get_current_pos (JsonParser *parser)
 
 /**
  * json_parser_has_assignment:
- * @parser: a #JsonParser
+ * @parser: a parser
  * @variable_name: (out) (optional) (transfer none): the variable name
  *
  * A JSON data stream might sometimes contain an assignment, like:
@@ -1371,7 +1399,7 @@ json_parser_get_current_pos (JsonParser *parser)
  * existence of the assignment in the data stream and the variable name
  * used.
  *
- * Return value: %TRUE if there was an assignment, %FALSE otherwise
+ * Returns: `TRUE` if there was an assignment, and `FALSE` otherwise
  *
  * Since: 0.4
  */
@@ -1395,20 +1423,20 @@ json_parser_has_assignment (JsonParser  *parser,
 
 /**
  * json_parser_load_from_stream:
- * @parser: a #JsonParser
- * @stream: an open #GInputStream
+ * @parser: a parser
+ * @stream: the input stream with the JSON data
  * @cancellable: (nullable): a #GCancellable
  * @error: the return location for a #GError
  *
  * Loads the contents of an input stream and parses them.
  *
- * If @cancellable is not %NULL, then the operation can be cancelled by
- * triggering the @cancellable object from another thread. If the
- * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be set
- * on the passed @error.
+ * If `cancellable` is not `NULL`, then the operation can be cancelled by
+ * triggering the cancellable object from another thread. If the
+ * operation was cancelled, `G_IO_ERROR_CANCELLED` will be set
+ * on the given `error`.
  *
- * Return value: %TRUE if the data stream was successfully read and
- *   parsed, and %FALSE otherwise
+ * Returns: `TRUE` if the data stream was successfully read and
+ *   parsed, and `FALSE` otherwise
  *
  * Since: 0.12
  */
@@ -1486,15 +1514,15 @@ load_data_free (gpointer data_)
 
 /**
  * json_parser_load_from_stream_finish:
- * @parser: a #JsonParser
- * @result: a #GAsyncResult
+ * @parser: a parser
+ * @result: the result of the asynchronous operation
  * @error: the return location for a #GError
  *
  * Finishes an asynchronous stream loading started with
  * [method@Json.Parser.load_from_stream_async].
  *
- * Return value: %TRUE if the content of the stream was successfully retrieves
- *   and parsed, and %FALSE otherwise
+ * Returns: `TRUE` if the content of the stream was successfully retrieved
+ *   and parsed, and `FALSE` otherwise
  *
  * Since: 0.12
  */
@@ -1514,7 +1542,7 @@ json_parser_load_from_stream_finish (JsonParser    *parser,
       LoadData *data = g_task_get_task_data (G_TASK (result));
       GError *internal_error = NULL;
 
-      /* We need to do this inside the finis() function because JsonParser will emit
+      /* We need to do this inside the finish() function because JsonParser will emit
        * signals, and we need to ensure that the signals are emitted in the right
        * context; it's easier to do that if we just rely on the async callback being
        * called in the right context, even if it means making the finish() function
@@ -1562,13 +1590,13 @@ read_from_stream (GTask *task,
 
 /**
  * json_parser_load_from_stream_async:
- * @parser: a #JsonParser
- * @stream: a #GInputStream
+ * @parser: a parser
+ * @stream: the input stream with the JSON data
  * @cancellable: (nullable): a #GCancellable
  * @callback: (scope async): the function to call when the request is satisfied
  * @user_data: the data to pass to @callback
  *
- * Asynchronously reads the contents of @stream.
+ * Asynchronously reads the contents of a stream.
  *
  * For more details, see [method@Json.Parser.load_from_stream], which is the
  * synchronous version of this call.
diff --git a/json-glib/json-parser.h b/json-glib/json-parser.h
index 44efb29..33c4699 100644
--- a/json-glib/json-parser.h
+++ b/json-glib/json-parser.h
@@ -40,6 +40,11 @@ G_BEGIN_DECLS
 #define JSON_IS_PARSER_CLASS(klass)     (G_TYPE_CHECK_CLASS_TYPE ((klass), JSON_TYPE_PARSER))
 #define JSON_PARSER_GET_CLASS(obj)      (G_TYPE_INSTANCE_GET_CLASS ((obj), JSON_TYPE_PARSER, JsonParserClass))
 
+/**
+ * JSON_PARSER_ERROR:
+ *
+ * Error domain for `JsonParser`.
+ */
 #define JSON_PARSER_ERROR               (json_parser_error_quark ())
 
 typedef struct _JsonParser              JsonParser;
@@ -57,7 +62,7 @@ typedef struct _JsonParserClass         JsonParserClass;
  * @JSON_PARSER_ERROR_INVALID_DATA: invalid data (Since: 0.18)
  * @JSON_PARSER_ERROR_UNKNOWN: unknown error
  *
- * Error enumeration for #JsonParser
+ * Error codes for `JSON_PARSER_ERROR`.
  *
  * This enumeration can be extended at later date
  */
diff --git a/json-glib/json-path.c b/json-glib/json-path.c
index 8151376..86fe97f 100644
--- a/json-glib/json-path.c
+++ b/json-glib/json-path.c
@@ -30,11 +30,11 @@
  * XPath specification for XML, the syntax follows the ECMAScript origins of
  * JSON.
  *
- * Once a #JsonPath instance has been created, it has to compile a JSONPath
+ * Once a `JsonPath` instance has been created, it has to compile a JSONPath
  * expression using [method@Json.Path.compile] before being able to match it to
- * a JSON tree; the same #JsonPath instance can be used to match multiple JSON
+ * a JSON tree; the same `JsonPath` instance can be used to match multiple JSON
  * trees. It it also possible to compile a new JSONPath expression using the
- * same #JsonPath instance; the previous expression will be discarded only if
+ * same `JsonPath` instance; the previous expression will be discarded only if
  * the compilation of the new expression is successful.
  *
  * The simple convenience function [func@Json.Path.query] can be used for
@@ -95,7 +95,7 @@
  *
  * ## Example of JSONPath matches
  *
- * The following example shows some of the results of using #JsonPath
+ * The following example shows some of the results of using `JsonPath`
  * on a JSON tree. We use the following JSON description of a bookstore:
  *
  * ```json
@@ -117,31 +117,32 @@
  * }
  * ```
  *
- * We can parse the JSON using #JsonParser:
+ * We can parse the JSON using [class@Json.Parser]:
  *
  * ```c
- *   JsonParser *parser = json_parser_new ();
- *   json_parser_load_from_data (parser, json_data, -1, NULL);
+ * JsonParser *parser = json_parser_new ();
+ * json_parser_load_from_data (parser, json_data, -1, NULL);
  * ```
  *
  * If we run the following code:
  *
  * ```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));
+ * 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
+ * The `result` node 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:
+ * [class@Json.Generator] to convert the `result` node to a string
+ * and print it:
  *
  * ```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);
+ * 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:
@@ -264,13 +265,12 @@ json_path_init (JsonPath *self)
 /**
  * json_path_new:
  *
- * Creates a new #JsonPath instance.
+ * Creates a new `JsonPath` instance.
  *
- * Once created, the #JsonPath object should be used with json_path_compile()
- * and json_path_match().
+ * Once created, the `JsonPath` object should be used with
+ * [method@Json.Path.compile] and [method@Json.Path.match].
  *
- * Return value: (transfer full): the newly created #JsonPath instance. Use
- *   g_object_unref() to free the allocated resources when done
+ * Return value: (transfer full): the newly created path
  *
  * Since: 0.14
  */
@@ -347,17 +347,17 @@ json_path_foreach_print (gpointer data,
 
 /**
  * json_path_compile:
- * @path: a #JsonPath
+ * @path: a path
  * @expression: a JSONPath expression
  * @error: return location for a #GError, or %NULL
  *
- * Validates and decomposes @expression.
+ * Validates and decomposes the given expression.
  *
- * A JSONPath expression must be compiled before calling json_path_match().
+ * A JSONPath expression must be compiled before calling
+ * [method@Json.Path.match].
  *
- * Return value: %TRUE on success; on error, @error will be set with
- *   the %JSON_PATH_ERROR domain and a code from the #JsonPathError
- *   enumeration, and %FALSE will be returned
+ * Return value: `TRUE` if the compilation was successful, and `FALSE`
+ *   otherwise
  *
  * Since: 0.14
  */
@@ -924,18 +924,16 @@ walk_path_node (GList      *path,
 
 /**
  * json_path_match:
- * @path: a compiled #JsonPath
- * @root: a #JsonNode
+ * @path: a compiled path
+ * @root: the root node of the JSON data to match
  *
- * Matches the JSON tree pointed by @root using the expression compiled
- * into the #JsonPath.
+ * Matches the JSON tree pointed by `root` using the expression compiled
+ * into the `JsonPath`.
  *
- * The matching #JsonNodes will be copied into a #JsonArray and
- * returned wrapped in a #JsonNode.
+ * The nodes matching the expression will be copied into an array.
  *
- * Return value: (transfer full): a newly-created #JsonNode of type
- *   %JSON_NODE_ARRAY containing an array of matching #JsonNodes.
- *   Use json_node_unref() when done
+ * Return value: (transfer full): a newly-created node of type
+ *   `JSON_NODE_ARRAY` containing the array of matching nodes
  *
  * Since: 0.14
  */
@@ -968,14 +966,13 @@ json_path_match (JsonPath *path,
  *
  * Queries a JSON tree using a JSONPath expression.
  *
- * This function is a simple wrapper around json_path_new(),
- * json_path_compile() and json_path_match(). It implicitly
- * creates a #JsonPath instance, compiles @expression and
- * matches it against the JSON tree pointed by @root.
+ * This function is a simple wrapper around [ctor@Json.Path.new],
+ * [method@Json.Path.compile], and [method@Json.Path.match]. It implicitly
+ * creates a `JsonPath` instance, compiles the given expression and 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 #JsonNodes.
- *   Use json_node_unref() when done
+ * Return value: (transfer full): a newly-created node of type
+ *   `JSON_NODE_ARRAY` containing the array of matching nodes
  *
  * Since: 0.14
  */
diff --git a/json-glib/json-path.h b/json-glib/json-path.h
index 9d47a2e..d9a29d9 100644
--- a/json-glib/json-path.h
+++ b/json-glib/json-path.h
@@ -38,7 +38,7 @@ G_BEGIN_DECLS
 /**
  * JSON_PATH_ERROR:
  *
- * Error domain for #JsonPath errors
+ * Error domain for `JsonPath`.
  *
  * Since: 0.14
  */
@@ -48,7 +48,9 @@ G_BEGIN_DECLS
  * JsonPathError:
  * @JSON_PATH_ERROR_INVALID_QUERY: Invalid query
  *
- * Error code enumeration for the %JSON_PATH_ERROR domain.
+ * Error codes for `JSON_PATH_ERROR`.
+ *
+ * This enumeration can be extended at later date
  *
  * Since: 0.14
  */
diff --git a/json-glib/json-reader.c b/json-glib/json-reader.c
index f550b00..cc10cc8 100644
--- a/json-glib/json-reader.c
+++ b/json-glib/json-reader.c
@@ -27,6 +27,32 @@
  *
  * It is similar, in spirit, to the XML Reader API.
  *
+ * ## Using `JsonReader`
+ *
+ * ```c
+ * g_autoptr(JsonParser) parser = json_parser_new ();
+ *
+ * // str is defined elsewhere
+ * json_parser_load_from_data (parser, str, -1, NULL);
+ *
+ * g_autoptr(JsonReader) reader = json_reader_new (json_parser_get_root (parser));
+ *
+ * json_reader_read_member (reader, "url");
+ *   const char *url = json_reader_get_string_value (reader);
+ *   json_reader_end_member (reader);
+ *
+ * json_reader_read_member (reader, "size");
+ *   json_reader_read_element (reader, 0);
+ *     int width = json_reader_get_int_value (reader);
+ *     json_reader_end_element (reader);
+ *   json_reader_read_element (reader, 1);
+ *     int height = json_reader_get_int_value (reader);
+ *     json_reader_end_element (reader);
+ *   json_reader_end_member (reader);
+ * ```
+ *
+ * ## Error handling
+ *
  * In case of error, `JsonReader` will be set in an error state; all subsequent
  * calls will simply be ignored until a function that resets the error state is
  * called, e.g.:
@@ -165,9 +191,9 @@ json_reader_class_init (JsonReaderClass *klass)
   GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
 
   /**
-   * JsonReader:root:
+   * JsonReader:root: (attributes org.gtk.Property.set=json_reader_set_root)
    *
-   * The root of the JSON tree that the #JsonReader should read.
+   * The root of the JSON tree that the reader should read.
    *
    * Since: 0.12
    */
@@ -195,14 +221,14 @@ json_reader_init (JsonReader *self)
 
 /**
  * json_reader_new:
- * @node: (allow-none): a #JsonNode, or %NULL
+ * @node: (nullable): the root node
  *
- * Creates a new #JsonReader.
+ * Creates a new reader.
  *
- * You can use this object to read the contents of the JSON tree starting from @node.
+ * You can use this object to read the contents of the JSON tree starting
+ * from the given node.
  *
- * Return value: the newly created #JsonReader. Use g_object_unref() to
- *   release the allocated resources when done
+ * Return value: the newly created reader
  *
  * Since: 0.12
  */
@@ -214,7 +240,7 @@ json_reader_new (JsonNode *node)
 
 /*
  * json_reader_unset_error:
- * @reader: a #JsonReader
+ * @reader: a reader
  *
  * Unsets the error state of @reader, if set
  *
@@ -232,15 +258,13 @@ json_reader_unset_error (JsonReader *reader)
 }
 
 /**
- * json_reader_set_root:
- * @reader: a #JsonReader
- * @root: (nullable): a #JsonNode
- *
- * Sets the root #JsonNode to be read by @reader.
+ * json_reader_set_root: (attributes org.gtk.Method.set_property=root)
+ * @reader: a reader
+ * @root: (nullable): the root node
  *
- * The @reader will take a copy of @root
+ * Sets the root node of the JSON tree to be read by @reader.
  *
- * If another #JsonNode is currently set as root, it will be replaced.
+ * The reader will take a copy of the node.
  *
  * Since: 0.12
  */
@@ -276,16 +300,16 @@ json_reader_set_root (JsonReader *reader,
 }
 
 /*
- * json_reader_ser_error:
- * @reader: a #JsonReader
- * @error_code: the #JsonReaderError code for the error
+ * json_reader_set_error:
+ * @reader: a reader
+ * @error_code: the [error@Json.ReaderError] code for the error
  * @error_fmt: format string
- * @Varargs: list of arguments for the @error_fmt string
+ * @Varargs: list of arguments for the `error_fmt` string
  *
- * Sets the error state of @reader using the given error code
+ * Sets the error state of the reader using the given error code
  * and string.
  *
- * Return value: %FALSE, to be used to return immediately from
+ * Return value: `FALSE`, to be used to return immediately from
  *   the caller function
  */
 G_GNUC_PRINTF (3, 4)
@@ -317,12 +341,11 @@ json_reader_set_error (JsonReader      *reader,
 
 /**
  * json_reader_get_error:
- * @reader: a #JsonReader
+ * @reader: a reader
  *
- * Retrieves the #GError currently set on @reader, if the #JsonReader
- * is in error state.
+ * Retrieves the error currently set on the reader.
  *
- * Return value: (nullable) (transfer none): the pointer to the error, or %NULL
+ * Return value: (nullable) (transfer none): the current error
  *
  * Since: 0.12
  */
@@ -336,12 +359,11 @@ json_reader_get_error (JsonReader *reader)
 
 /**
  * json_reader_is_array:
- * @reader: a #JsonReader
+ * @reader: a reader
  *
- * Checks whether the @reader is currently on an array.
+ * Checks whether the reader is currently on an array.
  *
- * Return value: %TRUE if the #JsonReader is on an array, and %FALSE
- *   otherwise
+ * Return value: `TRUE` if the reader is on an array
  *
  * Since: 0.12
  */
@@ -359,12 +381,11 @@ json_reader_is_array (JsonReader *reader)
 
 /**
  * json_reader_is_object:
- * @reader: a #JsonReader
+ * @reader: a reader
  *
- * Checks whether the @reader is currently on an object.
+ * Checks whether the reader is currently on an object.
  *
- * Return value: %TRUE if the #JsonReader is on an object, and %FALSE
- *   otherwise
+ * Return value: `TRUE` if the reader is on an object
  *
  * Since: 0.12
  */
@@ -382,12 +403,11 @@ json_reader_is_object (JsonReader *reader)
 
 /**
  * json_reader_is_value:
- * @reader: a #JsonReader
+ * @reader: a reader
  *
- * Checks whether the @reader is currently on a value.
+ * Checks whether the reader is currently on a value.
  *
- * Return value: %TRUE if the #JsonReader is on a value, and %FALSE
- *   otherwise
+ * Return value: `TRUE` if the reader is on a value
  *
  * Since: 0.12
  */
@@ -406,24 +426,27 @@ json_reader_is_value (JsonReader *reader)
 
 /**
  * json_reader_read_element:
- * @reader: a #JsonReader
+ * @reader: a reader
  * @index_: the index of the element
  *
- * Advances the cursor of @reader to the element @index_ of the array
- * or the object at the current position.
+ * Advances the cursor of the reader to the element of the array or
+ * the member of the object at the given position.
  *
- * You can use the json_reader_get_value* family of functions to retrieve
- * the value of the element; for instance:
+ * You can use [method@Json.Reader.get_value] and its wrapper functions to
+ * retrieve the value of the element; for instance, the following code will
+ * read the first element of the array at the current cursor position:
  *
  * ```c
  * json_reader_read_element (reader, 0);
  * int_value = json_reader_get_int_value (reader);
  * ```
  *
- * After reading the value, json_reader_end_element() should be called to
- * reposition the cursor inside the #JsonReader, e.g.:
+ * After reading the value, you should call [method@Json.Reader.end_element]
+ * to reposition the cursor inside the reader, e.g.:
  *
  * ```c
+ * const char *str_value = NULL;
+ *
  * json_reader_read_element (reader, 1);
  * str_value = json_reader_get_string_value (reader);
  * json_reader_end_element (reader);
@@ -433,25 +456,31 @@ json_reader_is_value (JsonReader *reader)
  * json_reader_end_element (reader);
  * ```
  *
- * If @reader is not currently on an array or an object, or if the @index_ is
- * bigger than the size of the array or the object, the #JsonReader will be
- * put in an error state until json_reader_end_element() is called. This means
- * that if used conditionally, json_reader_end_element() must be called on both
- * code paths:
+ * If the reader is not currently on an array or an object, or if the index is
+ * bigger than the size of the array or the object, the reader will be
+ * put in an error state until [method@Json.Reader.end_element] is called. This
+ * means that, if used conditionally, [method@Json.Reader.end_element] must be
+ * called on all branches:
  *
  * ```c
  * if (!json_reader_read_element (reader, 1))
  *   {
+ *     g_propagate_error (error, json_reader_get_error (reader));
  *     json_reader_end_element (reader);
- *     g_set_error (error, …);
  *     return FALSE;
  *   }
+ * else
+ *   {
+ *     const char *str_value = json_reader_get_string_value (reader);
+ *     json_reader_end_element (reader);
  *
- * str_value = json_reader_get_string_value (reader);
- * json_reader_end_element (reader);
+ *     // use str_value
+ *
+ *     return TRUE;
+ *   }
  * ```c
  *
- * Return value: %TRUE on success, and %FALSE otherwise
+ * Return value: `TRUE` on success, and `FALSE` otherwise
  *
  * Since: 0.12
  */
@@ -525,12 +554,12 @@ json_reader_read_element (JsonReader *reader,
 
 /**
  * json_reader_end_element:
- * @reader: a #JsonReader
+ * @reader: a reader
  *
  * Moves the cursor back to the previous node after being positioned
  * inside an array.
  *
- * This function resets the error state of @reader, if any was set.
+ * This function resets the error state of the reader, if any was set.
  *
  * Since: 0.12
  */
@@ -561,13 +590,14 @@ json_reader_end_element (JsonReader *reader)
 
 /**
  * json_reader_count_elements:
- * @reader: a #JsonReader
+ * @reader: a reader
  *
- * Counts the elements of the current position, if @reader is
+ * Counts the elements of the current position, if the reader is
  * positioned on an array.
  *
- * Return value: the number of elements, or -1. In case of failure
- *   the #JsonReader is set in an error state
+ * In case of failure, the reader is set to an error state.
+ *
+ * Return value: the number of elements, or -1.
  *
  * Since: 0.12
  */
@@ -600,22 +630,22 @@ json_reader_count_elements (JsonReader *reader)
 
 /**
  * json_reader_read_member:
- * @reader: a #JsonReader
+ * @reader: a reader
  * @member_name: the name of the member to read
  *
- * Advances the cursor of @reader to the @member_name of the object at the
- * current position.
+ * Advances the cursor of the reader to the `member_name` of the object at
+ * the current position.
  *
- * You can use the json_reader_get_value* family of functions to retrieve
- * the value of the member; for instance:
+ * You can use [method@Json.Reader.get_value] and its wrapper functions to
+ * retrieve the value of the member; for instance:
  *
  * ```c
  * json_reader_read_member (reader, "width");
  * width = json_reader_get_int_value (reader);
  * ```
  *
- * After reading the value, json_reader_end_member() should be called to
- * reposition the cursor inside the #JsonReader, e.g.:
+ * After reading the value, `json_reader_end_member()` should be called to
+ * reposition the cursor inside the reader, e.g.:
  *
  * ```c
  * json_reader_read_member (reader, "author");
@@ -627,24 +657,30 @@ json_reader_count_elements (JsonReader *reader)
  * json_reader_end_member (reader);
  * ```
  *
- * If @reader is not currently on an object, or if the @member_name is not
- * defined in the object, the #JsonReader will be put in an error state until
- * json_reader_end_member() is called. This means that if used conditionally,
- * json_reader_end_member() must be called on both code paths:
+ * If the reader is not currently on an object, or if the `member_name` is not
+ * defined in the object, the reader will be put in an error state until
+ * [method@Json.Reader.end_member] is called. This means that if used
+ * conditionally, [method@Json.Reader.end_member] must be called on all branches:
  *
  * ```c
  * if (!json_reader_read_member (reader, "title"))
  *   {
+ *     g_propagate_error (error, json_reader_get_error (reader));
  *     json_reader_end_member (reader);
- *     g_set_error (error, …);
  *     return FALSE;
  *   }
+ * else
+ *   {
+ *     const char *str_value = json_reader_get_string_value (reader);
+ *     json_reader_end_member (reader);
  *
- * str_value = json_reader_get_string_value (reader);
- * json_reader_end_member (reader);
+ *     // use str_value
+ *
+ *     return TRUE;
+ *   }
  * ```
  *
- * Return value: %TRUE on success, and %FALSE otherwise
+ * Return value: `TRUE` on success, and `FALSE` otherwise
  *
  * Since: 0.12
  */
@@ -686,12 +722,12 @@ json_reader_read_member (JsonReader  *reader,
 
 /**
  * json_reader_end_member:
- * @reader: a #JsonReader
+ * @reader: a reader
  *
  * Moves the cursor back to the previous node after being positioned
  * inside an object.
  *
- * This function resets the error state of @reader, if any was set.
+ * This function resets the error state of the reader, if any was set.
  *
  * Since: 0.12
  */
@@ -721,14 +757,15 @@ json_reader_end_member (JsonReader *reader)
 
 /**
  * json_reader_list_members:
- * @reader: a #JsonReader
+ * @reader: a reader
  *
- * Retrieves a list of member names from the current position, if @reader
+ * Retrieves a list of member names from the current position, if the reader
  * is positioned on an object.
  *
- * Return value: (transfer full): a newly allocated, %NULL-terminated
- *   array of strings holding the members name. Use g_strfreev() when
- *   done.
+ * In case of failure, the reader is set to an error state.
+ *
+ * Return value: (transfer full) (array zero-terminated=1): the members of
+ *   the object
  *
  * Since: 0.14
  */
@@ -775,13 +812,14 @@ json_reader_list_members (JsonReader *reader)
 
 /**
  * json_reader_count_members:
- * @reader: a #JsonReader
+ * @reader: a reader
  *
- * Counts the members of the current position, if @reader is
+ * Counts the members of the current position, if the reader is
  * positioned on an object.
  *
- * Return value: the number of members, or -1. In case of failure
- *   the #JsonReader is set in an error state
+ * In case of failure, the reader is set to an error state.
+ *
+ * Return value: the number of members, or -1
  *
  * Since: 0.12
  */
@@ -814,9 +852,12 @@ json_reader_count_members (JsonReader *reader)
 
 /**
  * json_reader_get_value:
- * @reader: a #JsonReader
+ * @reader: a reader
+ *
+ * Retrieves the value node at the current position of the reader.
  *
- * Retrieves the #JsonNode of the current position of @reader.
+ * If the current position does not contain a scalar value, the reader
+ * is set to an error state.
  *
  * Return value: (nullable) (transfer none): the current value node
  *
@@ -852,9 +893,11 @@ json_reader_get_value (JsonReader *reader)
 
 /**
  * json_reader_get_int_value:
- * @reader: a #JsonReader
+ * @reader: a reader
  *
- * Retrieves the integer value of the current position of @reader.
+ * Retrieves the integer value of the current position of the reader.
+ *
+ * See also: [method@Json.Reader.get_value]
  *
  * Return value: the integer value
  *
@@ -890,9 +933,11 @@ json_reader_get_int_value (JsonReader *reader)
 
 /**
  * json_reader_get_double_value:
- * @reader: a #JsonReader
+ * @reader: a reader
+ *
+ * Retrieves the floating point value of the current position of the reader.
  *
- * Retrieves the floating point value of the current position of @reader.
+ * See also: [method@Json.Reader.get_value]
  *
  * Return value: the floating point value
  *
@@ -928,9 +973,11 @@ json_reader_get_double_value (JsonReader *reader)
 
 /**
  * json_reader_get_string_value:
- * @reader: a #JsonReader
+ * @reader: a reader
  *
- * Retrieves the string value of the current position of @reader.
+ * Retrieves the string value of the current position of the reader.
+ *
+ * See also: [method@Json.Reader.get_value]
  *
  * Return value: the string value
  *
@@ -973,9 +1020,11 @@ json_reader_get_string_value (JsonReader *reader)
 
 /**
  * json_reader_get_boolean_value:
- * @reader: a #JsonReader
+ * @reader: a reader
+ *
+ * Retrieves the boolean value of the current position of the reader.
  *
- * Retrieves the boolean value of the current position of @reader.
+ * See also: [method@Json.Reader.get_value]
  *
  * Return value: the boolean value
  *
@@ -1011,11 +1060,13 @@ json_reader_get_boolean_value (JsonReader *reader)
 
 /**
  * json_reader_get_null_value:
- * @reader: a #JsonReader
+ * @reader: a reader
  *
- * Checks whether the value of the current position of @reader is `null`.
+ * Checks whether the value of the current position of the reader is `null`.
  *
- * Return value: %TRUE if `null` is set, and %FALSE otherwise
+ * See also: [method@Json.Reader.get_value]
+ *
+ * Return value: `TRUE` if `null` is set, and `FALSE` otherwise
  *
  * Since: 0.12
  */
@@ -1037,10 +1088,12 @@ json_reader_get_null_value (JsonReader *reader)
 
 /**
  * json_reader_get_member_name:
- * @reader: a #JsonReader
+ * @reader: a reader
  *
  * Retrieves the name of the current member.
  *
+ * In case of failure, the reader is set to an error state.
+ *
  * Return value: (nullable) (transfer none): the name of the member
  *
  * Since: 0.14
diff --git a/json-glib/json-reader.h b/json-glib/json-reader.h
index 9376a5d..105e88c 100644
--- a/json-glib/json-reader.h
+++ b/json-glib/json-reader.h
@@ -41,7 +41,7 @@ G_BEGIN_DECLS
 /**
  * JSON_READER_ERROR:
  *
- * Error domain for #JsonReader errors
+ * Error domain for `JsonReader`.
  *
  * Since: 0.12
  */
@@ -63,7 +63,9 @@ typedef struct _JsonReaderClass         JsonReaderClass;
  * @JSON_READER_ERROR_INVALID_TYPE: The node at the current position does not
  *   hold a value of the desired type
  *
- * Error codes enumeration for #JsonReader errors
+ * Error codes for `JSON_READER_ERROR`.
+ *
+ * This enumeration can be extended at later date
  *
  * Since: 0.12
  */
diff --git a/json-glib/json-serializable.c b/json-glib/json-serializable.c
index 3cdd757..de6c1c4 100644
--- a/json-glib/json-serializable.c
+++ b/json-glib/json-serializable.c
@@ -39,15 +39,15 @@
 
 /**
  * json_serializable_serialize_property:
- * @serializable: a #JsonSerializable object
- * @property_name: the name of the property
- * @value: the value of the property
- * @pspec: a #GParamSpec
+ * @serializable: a serializable object
+ * @property_name: the name of the property to serialize
+ * @value: the value of the property to serialize
+ * @pspec: a property description
  *
- * Asks a #JsonSerializable implementation to serialize a #GObject
- * property into a #JsonNode object.
+ * Asks a `JsonSerializable` implementation to serialize an object
+ * property into a JSON node.
  *
- * Return value: a #JsonNode containing the serialized property
+ * Return value: (transfer full): a node containing the serialized property
  */
 JsonNode *
 json_serializable_serialize_property (JsonSerializable *serializable,
@@ -69,22 +69,24 @@ json_serializable_serialize_property (JsonSerializable *serializable,
 
 /**
  * json_serializable_deserialize_property:
- * @serializable: a #JsonSerializable
- * @property_name: the name of the property
- * @value: (out): a pointer to an uninitialized #GValue
- * @pspec: a #GParamSpec
- * @property_node: a #JsonNode containing the serialized property
+ * @serializable: a serializable object
+ * @property_name: the name of the property to serialize
+ * @value: (out): a pointer to an uninitialized value
+ * @pspec: a property description
+ * @property_node: the JSON node containing the serialized property
  *
- * Asks a #JsonSerializable implementation to deserialize the
- * property contained inside @property_node into @value.
+ * Asks a `JsonSerializable` implementation to deserialize the
+ * property contained inside `property_node` and place its value
+ * into `value`.
  *
- * The @value can be:
+ * The `value` can be:
  *
- * - an empty #GValue initialized by %G_VALUE_INIT, which will be automatically
- *   initialized with the expected type of the property (since JSON-GLib 1.6)
- * - a #GValue initialized with the expected type of the property
+ * - an empty `GValue` initialized by `G_VALUE_INIT`, which will be automatically
+ *   initialized with the expected type of the property by using the given
+ *   property description (since JSON-GLib 1.6)
+ * - a `GValue` initialized with the expected type of the property
  *
- * Return value: %TRUE if the property was successfully deserialized.
+ * Returns: `TRUE` if the property was successfully deserialized
  */
 gboolean
 json_serializable_deserialize_property (JsonSerializable *serializable,
@@ -183,14 +185,14 @@ json_serializable_default_init (JsonSerializableInterface *iface)
   iface->get_property = json_serializable_real_get_property;
 }
 
-G_DEFINE_INTERFACE (JsonSerializable, json_serializable, G_TYPE_OBJECT);
+G_DEFINE_INTERFACE (JsonSerializable, json_serializable, G_TYPE_OBJECT)
 
 /**
  * json_serializable_default_serialize_property:
- * @serializable: a #JsonSerializable object
- * @property_name: the name of the property
- * @value: the value of the property
- * @pspec: a #GParamSpec
+ * @serializable: a serializable object
+ * @property_name: the name of the property to serialize
+ * @value: the value of the property to serialize
+ * @pspec: a property description
  *
  * Calls the default implementation of the [vfunc@Json.Serializable.serialize_property]
  * virtual function.
@@ -200,17 +202,20 @@ G_DEFINE_INTERFACE (JsonSerializable, json_serializable, G_TYPE_OBJECT);
  * default implementation through `g_type_default_interface_peek()`:
  *
  * ```c
- *   JsonSerializable *iface;
- *   JsonNode *node;
+ * JsonSerializable *iface;
+ * JsonNode *node;
  *
- *   iface = g_type_default_interface_peek (JSON_TYPE_SERIALIZABLE);
- *   node = iface->serialize_property (serializable, property_name,
- *                                     value,
- *                                     pspec);
+ * iface = g_type_default_interface_peek (JSON_TYPE_SERIALIZABLE);
+ * node = iface->serialize_property (serializable, property_name,
+ *                                   value,
+ *                                   pspec);
  * ```
  *
- * Return value: (transfer full) (nullable): a #JsonNode containing the
- *   serialized property, or %NULL if it should be omitted.
+ * This function will return `NULL` if the property could not be
+ * serialized.
+ *
+ * Returns: (transfer full) (nullable): a node containing the
+ *   serialized property
  *
  * Since: 0.10
  */
@@ -232,11 +237,11 @@ json_serializable_default_serialize_property (JsonSerializable *serializable,
 
 /**
  * json_serializable_default_deserialize_property:
- * @serializable: a #JsonSerializable
- * @property_name: the name of the property
- * @value: a pointer to an uninitialized #GValue
- * @pspec: a #GParamSpec
- * @property_node: a #JsonNode containing the serialized property
+ * @serializable: a serializable object
+ * @property_name: the name of the property to deserialize
+ * @value: a pointer to an uninitialized value
+ * @pspec: a property description
+ * @property_node: the JSON node containing the serialized property
  *
  * Calls the default implementation of the [vfunc@Json.Serializable.deserialize_property]
  * virtual function.
@@ -246,17 +251,17 @@ json_serializable_default_serialize_property (JsonSerializable *serializable,
  * default implementation through `g_type_default_interface_peek()`:
  *
  * ```c
- *   JsonSerializable *iface;
- *   gboolean res;
- *
- *   iface = g_type_default_interface_peek (JSON_TYPE_SERIALIZABLE);
- *   res = iface->deserialize_property (serializable, property_name,
- *                                      value,
- *                                      pspec,
- *                                      property_node);
+ * JsonSerializable *iface;
+ * gboolean res;
+ *
+ * iface = g_type_default_interface_peek (JSON_TYPE_SERIALIZABLE);
+ * res = iface->deserialize_property (serializable, property_name,
+ *                                    value,
+ *                                    pspec,
+ *                                    property_node);
  * ```
  *
- * Return value: %TRUE if the property was successfully deserialized.
+ * Return value: `TRUE` if the property was successfully deserialized
  *
  * Since: 0.10
  */
@@ -281,14 +286,14 @@ json_serializable_default_deserialize_property (JsonSerializable *serializable,
 
 /**
  * json_serializable_find_property:
- * @serializable: a #JsonSerializable
+ * @serializable: a serializable object
  * @name: the name of the property
  *
  * Calls the [vfunc@Json.Serializable.find_property] implementation on
- * the @serializable instance. *
+ * the `JsonSerializable` instance, which will return the property
+ * description for the given name.
  *
- * Return value: (nullable) (transfer none): the #GParamSpec for the property
- *   or %NULL if no property was found
+ * Return value: (nullable) (transfer none): the property description
  *
  * Since: 0.14
  */
@@ -304,15 +309,15 @@ json_serializable_find_property (JsonSerializable *serializable,
 
 /**
  * json_serializable_list_properties:
- * @serializable: a #JsonSerializable
- * @n_pspecs: (out): return location for the length of the array
- *   of #GParamSpec returned by the function
+ * @serializable: a serializable object
+ * @n_pspecs: (out): return location for the length of the returned array
  *
  * Calls the [vfunc@Json.Serializable.list_properties] implementation on
- * the @serializable instance.
+ * the `JsonSerializable` instance, which will return the list of serializable
+ * properties.
  *
- * Return value: (array length=n_pspecs) (transfer container): an array
- *   of #GParamSpec
+ * Return value: (array length=n_pspecs) (transfer container): the serializable
+ *   properties of the object
  *
  * Since: 0.14
  */
@@ -327,12 +332,13 @@ json_serializable_list_properties (JsonSerializable *serializable,
 
 /**
  * json_serializable_set_property:
- * @serializable: a #JsonSerializable
- * @pspec: a #GParamSpec
+ * @serializable: a serializable object
+ * @pspec: a property description
  * @value: the property value to set
  *
  * Calls the [vfunc@Json.Serializable.set_property] implementation
- * on the @serializable instance.
+ * on the `JsonSerializable` instance, which will set the property
+ * with the given value.
  *
  * Since: 0.14
  */
@@ -352,12 +358,13 @@ json_serializable_set_property (JsonSerializable *serializable,
 
 /**
  * json_serializable_get_property:
- * @serializable: a #JsonSerializable
- * @pspec: a #GParamSpec
+ * @serializable: a serializable object
+ * @pspec: a property description
  * @value: (out): return location for the property value
  *
  * Calls the [vfunc@Json.Serializable.get_property] implementation
- * on the @serializable instance.
+ * on the `JsonSerializable` instance, which will get the value of
+ * the given property.
  *
  * Since: 0.14
  */
diff --git a/json-glib/json-types.h b/json-glib/json-types.h
index 52f3346..3468257 100644
--- a/json-glib/json-types.h
+++ b/json-glib/json-types.h
@@ -35,18 +35,18 @@ G_BEGIN_DECLS
 
 /**
  * JSON_NODE_TYPE:
- * @node: a #JsonNode
+ * @node: (type Json.Node): the [struct@Json.Node] to check
  *
- * Evaluates to the #JsonNodeType contained by @node
+ * Evaluates to the [enum@Json.NodeType] value contained by the node.
  */
 #define JSON_NODE_TYPE(node)    (json_node_get_node_type ((node)))
 
 /**
  * JSON_NODE_HOLDS:
- * @node: a #JsonNode
- * @t: a #JsonNodeType
+ * @node: (type Json.Node): the [struct@Json.Node] to check
+ * @t: (type Json.NodeType): the desired [enum@Json.NodeType]
  *
- * Evaluates to %TRUE if the @node holds type @t
+ * Evaluates to `TRUE` if the node holds the given type.
  *
  * Since: 0.10
  */
@@ -54,9 +54,9 @@ G_BEGIN_DECLS
 
 /**
  * JSON_NODE_HOLDS_VALUE:
- * @node: a #JsonNode
+ * @node: (type Json.Node): the [struct@Json.Node] to check
  *
- * Evaluates to %TRUE if @node holds a %JSON_NODE_VALUE
+ * Evaluates to `TRUE` if the node holds a scalar value.
  *
  * Since: 0.10
  */
@@ -64,9 +64,9 @@ G_BEGIN_DECLS
 
 /**
  * JSON_NODE_HOLDS_OBJECT:
- * @node: a #JsonNode
+ * @node: (type Json.Node): the [struct@Json.Node] to check
  *
- * Evaluates to %TRUE if @node holds a %JSON_NODE_OBJECT
+ * Evaluates to `TRUE` if the node holds a JSON object.
  *
  * Since: 0.10
  */
@@ -74,9 +74,9 @@ G_BEGIN_DECLS
 
 /**
  * JSON_NODE_HOLDS_ARRAY:
- * @node: a #JsonNode
+ * @node: (type Json.Node): the [struct@Json.Node] to check
  *
- * Evaluates to %TRUE if @node holds a %JSON_NODE_ARRAY
+ * Evaluates to `TRUE` if the node holds a JSON array.
  *
  * Since: 0.10
  */
@@ -84,9 +84,9 @@ G_BEGIN_DECLS
 
 /**
  * JSON_NODE_HOLDS_NULL:
- * @node: a #JsonNode
+ * @node: (type Json.Node): the [struct@Json.Node] to check
  *
- * Evaluates to %TRUE if @node holds a %JSON_NODE_NULL
+ * Evaluates to `TRUE` if the node holds `null`.
  *
  * Since: 0.10
  */
@@ -102,12 +102,12 @@ typedef struct _JsonArray       JsonArray;
 
 /**
  * JsonNodeType:
- * @JSON_NODE_OBJECT: The node contains a #JsonObject
- * @JSON_NODE_ARRAY: The node contains a #JsonArray
+ * @JSON_NODE_OBJECT: The node contains a JSON object
+ * @JSON_NODE_ARRAY: The node contains a JSON array
  * @JSON_NODE_VALUE: The node contains a fundamental type
  * @JSON_NODE_NULL: Special type, for nodes containing null
  *
- * Indicates the content of a #JsonNode.
+ * Indicates the content of a node.
  */
 typedef enum {
   JSON_NODE_OBJECT,
@@ -118,9 +118,9 @@ typedef enum {
 
 /**
  * JsonObjectForeach:
- * @object: the iterated #JsonObject
+ * @object: the iterated JSON object
  * @member_name: the name of the member
- * @member_node: a #JsonNode containing the @member_name value
+ * @member_node: the value of the member
  * @user_data: data passed to the function
  *
  * The function to be passed to [method@Json.Object.foreach_member].
@@ -139,9 +139,9 @@ typedef void (* JsonObjectForeach) (JsonObject  *object,
 
 /**
  * JsonArrayForeach:
- * @array: the iterated #JsonArray
+ * @array: the iterated JSON array
  * @index_: the index of the element
- * @element_node: a #JsonNode containing the value at @index_
+ * @element_node: the value of the element at the given @index_
  * @user_data: data passed to the function
  *
  * The function to be passed to [method@Json.Array.foreach_element].
@@ -408,12 +408,12 @@ gboolean              json_object_equal              (gconstpointer a,
 /**
  * JsonObjectIter:
  *
- * An iterator object used to iterate over the members of a #JsonObject.
+ * An iterator object used to iterate over the members of a JSON object.
  *
  * `JsonObjectIter` must be allocated on the stack and initialised using
  * [method@Json.ObjectIter.init] or [method@Json.ObjectIter.init_ordered].
  *
- * The iterator is invalidated if its `JsonObject` is modified during
+ * The iterator is invalidated if the object is modified during
  * iteration.
  *
  * All the fields in the `JsonObjectIter` structure are private and should
diff --git a/json-glib/json-utils.c b/json-glib/json-utils.c
index dda4602..72c78e5 100644
--- a/json-glib/json-utils.c
+++ b/json-glib/json-utils.c
@@ -28,13 +28,12 @@
  * @str: a valid UTF-8 string containing JSON data
  * @error: return location for a #GError
  *
- * Parses the string in @str and returns a #JsonNode representing
- * the JSON tree.
+ * Parses the given string and returns the corresponding JSON tree.
  *
- * If @str is empty, this function will return %NULL.
+ * If the string is empty, this function will return `NULL`.
  *
- * In case of parsing error, this function returns %NULL and sets
- * @error appropriately.
+ * In case of parsing error, this function returns `NULL` and sets
+ * the error appropriately.
  *
  * Returns: (transfer full) (nullable): the root node of the JSON tree
  *
@@ -65,11 +64,11 @@ json_from_string (const char  *str,
 
 /**
  * json_to_string:
- * @node: a #JsonNode
+ * @node: a JSON tree
  * @pretty: whether the output should be prettyfied for printing
  *
  * Generates a stringified JSON representation of the contents of
- * the passed @node.
+ * the given `node`.
  *
  * Returns: (transfer full): the string representation of the node
  *
diff --git a/json-glib/json-value.c b/json-glib/json-value.c
index 1b6f971..77ce864 100644
--- a/json-glib/json-value.c
+++ b/json-glib/json-value.c
@@ -167,15 +167,13 @@ json_value_free (JsonValue *value)
     }
 }
 
-/**
+/*< private >
  * json_value_seal:
- * @value: a #JsonValue
+ * @value: a JSON scalar value
  *
- * Seals the #JsonValue, making it immutable to further changes.
+ * Seals the value, making it immutable to further changes.
  *
- * If the @value is already immutable, this is a no-op.
- *
- * Since: 1.2
+ * If the value is already immutable, this is a no-op.
  */
 void
 json_value_seal (JsonValue *value)
diff --git a/json-glib/json-version-macros.h b/json-glib/json-version-macros.h
index c1c269c..75ac770 100644
--- a/json-glib/json-version-macros.h
+++ b/json-glib/json-version-macros.h
@@ -41,12 +41,32 @@
 #endif
 
 /* XXX: Each new cycle should add a new version symbol here */
+/**
+ * JSON_VERSION_1_0:
+ *
+ * The encoded representation of JSON-GLib version "1.0".
+ */
 #define JSON_VERSION_1_0        (G_ENCODE_VERSION (1, 0))
 
+/**
+ * JSON_VERSION_1_2:
+ *
+ * The encoded representation of JSON-GLib version "1.2".
+ */
 #define JSON_VERSION_1_2        (G_ENCODE_VERSION (1, 2))
 
+/**
+ * JSON_VERSION_1_4:
+ *
+ * The encoded representation of JSON-GLib version "1.4".
+ */
 #define JSON_VERSION_1_4        (G_ENCODE_VERSION (1, 4))
 
+/**
+ * JSON_VERSION_1_6:
+ *
+ * The encoded representation of JSON-GLib version "1.6".
+ */
 #define JSON_VERSION_1_6        (G_ENCODE_VERSION (1, 6))
 
 /* evaluates to the current stable version; for development cycles,
@@ -73,9 +93,10 @@
  * JSON_VERSION_MIN_REQUIRED:
  *
  * A macro that should be defined by the user prior to including
- * the gdk.h header.
- * The definition should be one of the predefined JSON version
- * macros: %JSON_VERSION_1_0, %JSON_VERSION_1_2,...
+ * the `json-glib/json-glib.h` header.
+ *
+ * The definition should be one of the predefined JSON-GLib version
+ * macros: `JSON_VERSION_1_0`, `JSON_VERSION_1_2`, ...
  *
  * This macro defines the lower bound for the JSON-GLib API to use.
  *
@@ -93,10 +114,10 @@
  * JSON_VERSION_MAX_ALLOWED:
  *
  * A macro that should be defined by the user prior to including
- * the json-glib.h header.
+ * the `json-glib/json-glib.h` header.
 
  * The definition should be one of the predefined JSON-GLib version
- * macros: %JSON_VERSION_1_0, %JSON_VERSION_1_2,...
+ * macros: `JSON_VERSION_1_0`, `JSON_VERSION_1_2`, ...
  *
  * This macro defines the upper bound for the JSON API-GLib to use.
  *
diff --git a/json-glib/json-version.h.in b/json-glib/json-version.h.in
index 8fe3a5b..3bd3490 100644
--- a/json-glib/json-version.h.in
+++ b/json-glib/json-version.h.in
@@ -31,35 +31,35 @@
 /**
  * JSON_MAJOR_VERSION:
  *
- * Json major version component (e.g. 1 if %JSON_VERSION is 1.2.3)
+ * Json major version component (e.g. 1 if `JSON_VERSION` is "1.2.3")
  */
 #define JSON_MAJOR_VERSION              (@JSON_MAJOR_VERSION@)
 
 /**
  * JSON_MINOR_VERSION:
  *
- * Json minor version component (e.g. 2 if %JSON_VERSION is 1.2.3)
+ * Json minor version component (e.g. 2 if `JSON_VERSION` is "1.2.3")
  */
 #define JSON_MINOR_VERSION              (@JSON_MINOR_VERSION@)
 
 /**
  * JSON_MICRO_VERSION:
  *
- * Json micro version component (e.g. 3 if %JSON_VERSION is 1.2.3)
+ * Json micro version component (e.g. 3 if `JSON_VERSION` is "1.2.3")
  */
 #define JSON_MICRO_VERSION              (@JSON_MICRO_VERSION@)
 
 /**
  * JSON_VERSION
  *
- * Json version.
+ * The version of JSON-GLib.
  */
 #define JSON_VERSION                    (@JSON_VERSION@)
 
 /**
  * JSON_VERSION_S:
  *
- * JSON-GLib version, encoded as a string, useful for printing and
+ * The version of JSON-GLib, encoded as a string, useful for printing and
  * concatenation.
  */
 #define JSON_VERSION_S                  "@JSON_VERSION@"
@@ -70,7 +70,7 @@
 /**
  * JSON_VERSION_HEX:
  *
- * JSON-GLib version, encoded as an hexadecimal number, useful for
+ * The version of JSON-GLib, encoded as an hexadecimal number, useful for
  * integer comparisons.
  */
 #define JSON_VERSION_HEX \
@@ -82,8 +82,8 @@
  * @minor: required minor version
  * @micro: required micro version
  *
- * Compile-time version checking. Evaluates to %TRUE if the version
- * of Json is greater than the required one.
+ * Compile-time version checking. Evaluates to `TRUE` if the version
+ * of JSON-GLib is greater than the required one.
  */
 #define JSON_CHECK_VERSION(major,minor,micro)   \
         (JSON_MAJOR_VERSION > (major) || \