[json-glib/gidocgen: 2/8] docs: Initial, rough port away from gtk-doc
- From: Emmanuele Bassi <ebassi src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [json-glib/gidocgen: 2/8] docs: Initial, rough port away from gtk-doc
- Date: Tue, 8 Jun 2021 15:55:26 +0000 (UTC)
commit 7a60ca2ae319c018afb3e1ae2beedb5450ce9c88
Author: Emmanuele Bassi <ebassi gnome org>
Date: Tue Jun 8 16:08:50 2021 +0100
docs: Initial, rough port away from gtk-doc
Drop `SECTION` blurbs.
Use gi-docgen syntax for internal links.
Use summary lines for gi-docgen indices.
Use Markdown syntax for code fragments.
json-glib/json-array.c | 259 +++++++++++++++++++++---------------------
json-glib/json-builder.c | 61 +++++-----
json-glib/json-builder.h | 15 ---
json-glib/json-gboxed.c | 63 ++--------
json-glib/json-generator.c | 85 +++++++-------
json-glib/json-generator.h | 11 --
json-glib/json-gobject.c | 61 +++++-----
json-glib/json-gvariant.c | 109 +++++++-----------
json-glib/json-node.c | 198 +++++++++++++++++++-------------
json-glib/json-object.c | 239 +++++++++++++++++++-------------------
json-glib/json-parser.c | 124 ++++++++++----------
json-glib/json-parser.h | 8 +-
json-glib/json-path.c | 96 ++++++++--------
json-glib/json-path.h | 17 ---
json-glib/json-reader.c | 101 ++++++++--------
json-glib/json-reader.h | 15 ---
json-glib/json-serializable.c | 52 +++++----
json-glib/json-types.h | 52 ++++-----
json-glib/json-utils.c | 16 +--
json-glib/json-version.h.in | 8 --
20 files changed, 731 insertions(+), 859 deletions(-)
---
diff --git a/json-glib/json-array.c b/json-glib/json-array.c
index 4834cdc..6e85f55 100644
--- a/json-glib/json-array.c
+++ b/json-glib/json-array.c
@@ -26,20 +26,24 @@
#include "json-types-private.h"
/**
- * SECTION:json-array
- * @short_description: a JSON array representation
+ * JsonArray:
*
- * #JsonArray is the representation of the array type inside JSON. It contains
- * #JsonNode elements, which may contain fundamental types, other arrays or
- * objects.
+ * `JsonArray` is the representation of the array type inside JSON.
*
- * Since arrays can be expensive, they are reference counted. You can control
- * the lifetime of a #JsonArray using json_array_ref() and json_array_unref().
+ * A `JsonArray` contains [struct Json Node] elements, which may contain
+ * fundamental types, other arrays or objects.
*
- * To append an element, use json_array_add_element().
- * To extract an element at a given index, use json_array_get_element().
- * To retrieve the entire array in list form, use json_array_get_elements().
- * To retrieve the length of the array, use json_array_get_length().
+ * Since arrays can be arbitrarily big, copying them can be expensive; for
+ * this reason, they are reference counted. You can control the lifetime of
+ * a `JsonArray` using [method Json Array ref] and [method@Json.Array.unref].
+ *
+ * To append an element, use [method@Json.Array.add_element].
+ *
+ * To extract an element at a given index, use [method@Json.Array.get_element].
+ *
+ * To retrieve the entire array in list form, use [method@Json.Array.get_elements].
+ *
+ * To retrieve the length of the array, use [method@Json.Array.get_length].
*/
G_DEFINE_BOXED_TYPE (JsonArray, json_array, json_array_ref, json_array_unref);
@@ -47,9 +51,9 @@ G_DEFINE_BOXED_TYPE (JsonArray, json_array, json_array_ref, json_array_unref);
/**
* json_array_new: (constructor)
*
- * Creates a new #JsonArray.
+ * Creates a new array.
*
- * Return value: (transfer full): the newly created #JsonArray
+ * Return value: (transfer full): the newly created array
*/
JsonArray *
json_array_new (void)
@@ -68,9 +72,9 @@ json_array_new (void)
* json_array_sized_new: (constructor)
* @n_elements: number of slots to pre-allocate
*
- * Creates a new #JsonArray with @n_elements slots already allocated.
+ * Creates a new array with `n_elements` slots already allocated.
*
- * Return value: (transfer full): the newly created #JsonArray
+ * Return value: (transfer full): the newly created array
*/
JsonArray *
json_array_sized_new (guint n_elements)
@@ -87,12 +91,12 @@ json_array_sized_new (guint n_elements)
/**
* json_array_ref:
- * @array: a #JsonArray
+ * @array: the array to reference
*
- * Increase by one the reference count of a #JsonArray.
+ * Acquires a reference on the given array.
*
- * Return value: (transfer none): the passed #JsonArray, with the reference count
- * increased by one.
+ * Return value: (transfer none): the passed array, with the reference count
+ * increased by one
*/
JsonArray *
json_array_ref (JsonArray *array)
@@ -107,10 +111,11 @@ json_array_ref (JsonArray *array)
/**
* json_array_unref:
- * @array: a #JsonArray
+ * @array: the array to unreference
+ *
+ * Releases a reference on the given array.
*
- * Decreases by one the reference count of a #JsonArray. If the
- * reference count reaches zero, the array is destroyed and all
+ * If the reference count reaches zero, the array is destroyed and all
* its allocated resources are freed.
*/
void
@@ -135,12 +140,13 @@ json_array_unref (JsonArray *array)
/**
* json_array_seal:
- * @array: a #JsonArray
+ * @array: the array to seal
*
- * Seals the #JsonArray, making it immutable to further changes. This will
- * recursively seal all elements in the array too.
+ * Seals the given array, making it immutable to further changes.
*
- * If the @array is already immutable, this is a no-op.
+ * This function will recursively seal all elements in the array too.
+ *
+ * If the `array` is already immutable, this is a no-op.
*
* Since: 1.2
*/
@@ -165,13 +171,13 @@ json_array_seal (JsonArray *array)
/**
* json_array_is_immutable:
- * @array: a #JsonArray
+ * @array: an array
*
- * Check whether the given @array has been marked as immutable by calling
- * json_array_seal() on it.
+ * Check whether the given `array` has been marked as immutable by calling
+ * [method Json Array seal] on it.
*
* Since: 1.2
- * Returns: %TRUE if the @array is immutable
+ * Returns: %TRUE if the array is immutable
*/
gboolean
json_array_is_immutable (JsonArray *array)
@@ -184,14 +190,12 @@ json_array_is_immutable (JsonArray *array)
/**
* json_array_get_elements:
- * @array: a #JsonArray
+ * @array: an array
*
- * Gets the elements of a #JsonArray as a list of #JsonNode instances.
+ * Retrieves all the elements of an array as a list of nodes.
*
- * Return value: (element-type JsonNode) (transfer container): a #GList
- * containing the elements of the array. The contents of the list are
- * owned by the array and should never be modified or freed. Use
- * g_list_free() on the returned list when done using it
+ * Return value: (element-type JsonNode) (transfer container) (nullable): the elements
+ * of the array
*/
GList *
json_array_get_elements (JsonArray *array)
@@ -211,14 +215,12 @@ json_array_get_elements (JsonArray *array)
/**
* json_array_dup_element:
- * @array: a #JsonArray
+ * @array: an array
* @index_: the index of the element to retrieve
*
- * Retrieves a copy of the #JsonNode containing the value of the
- * element at @index_ inside a #JsonArray
+ * Retrieves a copy of the element at the given position in the array.
*
- * Return value: (transfer full): a copy of the #JsonNode at the requested
- * index. Use json_node_unref() when done.
+ * Return value: (transfer full): a copy of the element at the given position
*
* Since: 0.6
*/
@@ -242,11 +244,10 @@ json_array_dup_element (JsonArray *array,
* json_array_get_element:
* @array: a #JsonArray
* @index_: the index of the element to retrieve
- *
- * Retrieves the #JsonNode containing the value of the element at @index_
- * inside a #JsonArray.
*
- * Return value: (transfer none): a pointer to the #JsonNode at the requested index
+ * Retrieves the element at the given position in the array.
+ *
+ * Return value: (transfer none): the element at the given position
*/
JsonNode *
json_array_get_element (JsonArray *array,
@@ -260,13 +261,13 @@ json_array_get_element (JsonArray *array,
/**
* json_array_get_int_element:
- * @array: a #JsonArray
+ * @array: an array
* @index_: the index of the element to retrieve
*
- * Conveniently retrieves the integer value of the element at @index_
- * inside @array
+ * Conveniently retrieves the integer value of the element at the given
+ * position inside an array.
*
- * See also: json_array_get_element(), json_node_get_int()
+ * See also: [method@Json.Array.get_element], [method Json Node.get_int]
*
* Return value: the integer value
*
@@ -290,13 +291,13 @@ json_array_get_int_element (JsonArray *array,
/**
* json_array_get_double_element:
- * @array: a #JsonArray
+ * @array: an array
* @index_: the index of the element to retrieve
*
* Conveniently retrieves the floating point value of the element at
- * @index_ inside @array
+ * the given position inside an array.
*
- * See also: json_array_get_element(), json_node_get_double()
+ * See also: [method@Json.Array.get_element], [method Json Node.get_double]
*
* Return value: the floating point value
*
@@ -320,15 +321,15 @@ json_array_get_double_element (JsonArray *array,
/**
* json_array_get_boolean_element:
- * @array: a #JsonArray
+ * @array: an array
* @index_: the index of the element to retrieve
*
- * Conveniently retrieves the boolean value of the element at @index_
- * inside @array
+ * Conveniently retrieves the boolean value of the element at the given
+ * position inside an array.
*
- * See also: json_array_get_element(), json_node_get_boolean()
+ * See also: [method@Json.Array.get_element], [method Json Node.get_boolean]
*
- * Return value: the integer value
+ * Return value: the boolean value
*
* Since: 0.8
*/
@@ -350,16 +351,15 @@ json_array_get_boolean_element (JsonArray *array,
/**
* json_array_get_string_element:
- * @array: a #JsonArray
+ * @array: an array
* @index_: the index of the element to retrieve
*
- * Conveniently retrieves the string value of the element at @index_
- * inside @array
+ * Conveniently retrieves the string value of the element at the given
+ * position inside an array.
*
- * See also: json_array_get_element(), json_node_get_string()
+ * See also: [method@Json.Array.get_element], [method Json Node.get_string]
*
- * Return value: the string value; the returned string is owned by
- * the #JsonArray and should not be modified or freed
+ * Return value: (transfer none): the string value
*
* Since: 0.8
*/
@@ -384,14 +384,15 @@ json_array_get_string_element (JsonArray *array,
/**
* json_array_get_null_element:
- * @array: a #JsonArray
+ * @array: an array
* @index_: the index of the element to retrieve
*
- * Conveniently retrieves whether the element at @index_ is set to null
+ * Conveniently checks whether the element at the given position inside the
+ * array contains a `null` value.
*
- * See also: json_array_get_element(), JSON_NODE_TYPE(), %JSON_NODE_NULL
+ * See also: [method@Json.Array.get_element], [method Json Node.is_null]
*
- * Return value: %TRUE if the element is null
+ * Return value: `TRUE` if the element is `null`
*
* Since: 0.8
*/
@@ -421,13 +422,12 @@ json_array_get_null_element (JsonArray *array,
/**
* json_array_get_array_element:
- * @array: a #JsonArray
+ * @array: an array
* @index_: the index of the element to retrieve
*
- * Conveniently retrieves the array from the element at @index_
- * inside @array
+ * Conveniently retrieves the array at the given position inside an array.
*
- * See also: json_array_get_element(), json_node_get_array()
+ * See also: [method@Json.Array.get_element], [method Json Node.get_array]
*
* Return value: (transfer none): the array
*
@@ -457,10 +457,9 @@ json_array_get_array_element (JsonArray *array,
* @array: a #JsonArray
* @index_: the index of the element to retrieve
*
- * Conveniently retrieves the object from the element at @index_
- * inside @array
+ * Conveniently retrieves the object at the given position inside an array.
*
- * See also: json_array_get_element(), json_node_get_object()
+ * See also: [method@Json.Array.get_element], [method Json Node.get_object]
*
* Return value: (transfer none): the object
*
@@ -487,9 +486,9 @@ json_array_get_object_element (JsonArray *array,
/**
* json_array_get_length:
- * @array: a #JsonArray
+ * @array: an array
*
- * Retrieves the length of a #JsonArray
+ * Retrieves the length of the given array
*
* Return value: the length of the array
*/
@@ -503,11 +502,10 @@ json_array_get_length (JsonArray *array)
/**
* json_array_add_element:
- * @array: a #JsonArray
- * @node: (transfer full): a #JsonNode
+ * @array: an array
+ * @node: (transfer full): the element to add
*
- * Appends @node inside @array. The array will take ownership of the
- * #JsonNode.
+ * Appends the given `node` inside an array.
*/
void
json_array_add_element (JsonArray *array,
@@ -521,12 +519,12 @@ json_array_add_element (JsonArray *array,
/**
* json_array_add_int_element:
- * @array: a #JsonArray
- * @value: an integer value
+ * @array: an array
+ * @value: the integer value to add
*
- * Conveniently adds an integer @value into @array
+ * Conveniently adds the given integer value into an array.
*
- * See also: json_array_add_element(), json_node_set_int()
+ * See also: [method@Json.Array.add_element], [method Json Node.set_int]
*
* Since: 0.8
*/
@@ -541,12 +539,12 @@ json_array_add_int_element (JsonArray *array,
/**
* json_array_add_double_element:
- * @array: a #JsonArray
- * @value: a floating point value
+ * @array: an array
+ * @value: the floating point value to add
*
- * Conveniently adds a floating point @value into @array
+ * Conveniently adds the given floating point value into an array.
*
- * See also: json_array_add_element(), json_node_set_double()
+ * See also: [method@Json.Array.add_element], [method Json Node.set_double]
*
* Since: 0.8
*/
@@ -561,12 +559,12 @@ json_array_add_double_element (JsonArray *array,
/**
* json_array_add_boolean_element:
- * @array: a #JsonArray
- * @value: a boolean value
+ * @array: an array
+ * @value: the boolean value to add
*
- * Conveniently adds a boolean @value into @array
+ * Conveniently adds the given boolean value into an array.
*
- * See also: json_array_add_element(), json_node_set_boolean()
+ * See also: [method@Json.Array.add_element], [method Json Node.set_boolean]
*
* Since: 0.8
*/
@@ -581,12 +579,12 @@ json_array_add_boolean_element (JsonArray *array,
/**
* json_array_add_string_element:
- * @array: a #JsonArray
- * @value: a string value
+ * @array: an array
+ * @value: the string value to add
*
- * Conveniently adds a string @value into @array
+ * Conveniently adds the given string value into an array.
*
- * See also: json_array_add_element(), json_node_set_string()
+ * See also: [method@Json.Array.add_element], [method Json Node.set_string]
*
* Since: 0.8
*/
@@ -610,11 +608,11 @@ json_array_add_string_element (JsonArray *array,
/**
* json_array_add_null_element:
- * @array: a #JsonArray
+ * @array: an array
*
- * Conveniently adds a null element into @array
+ * Conveniently adds a `null` element into an array
*
- * See also: json_array_add_element(), %JSON_NODE_NULL
+ * See also: [method@Json.Array.add_element], `JSON_NODE_NULL`
*
* Since: 0.8
*/
@@ -628,13 +626,14 @@ json_array_add_null_element (JsonArray *array)
/**
* json_array_add_array_element:
- * @array: a #JsonArray
- * @value: (allow-none) (transfer full): a #JsonArray
+ * @array: an array
+ * @value: (nullable) (transfer full): the array to add
+ *
+ * Conveniently adds an array into an array.
*
- * Conveniently adds an array into @array. The @array takes ownership
- * of the newly added #JsonArray
+ * If `value` is `NULL`, a `null` element will be added instead.
*
- * See also: json_array_add_element(), json_node_take_array()
+ * See also: [method@Json.Array.add_element], [method Json Node.take_array]
*
* Since: 0.8
*/
@@ -661,13 +660,14 @@ json_array_add_array_element (JsonArray *array,
/**
* json_array_add_object_element:
- * @array: a #JsonArray
- * @value: (transfer full): a #JsonObject
+ * @array: an array
+ * @value: (transfer full) (nullable): the object to add
*
- * Conveniently adds an object into @array. The @array takes ownership
- * of the newly added #JsonObject
+ * Conveniently adds an object into an array.
*
- * See also: json_array_add_element(), json_node_take_object()
+ * If `value` is `NULL`, a `null` element will be added instead.
+ *
+ * See also: [method@Json.Array.add_element], [method Json Node.take_object]
*
* Since: 0.8
*/
@@ -697,8 +697,9 @@ json_array_add_object_element (JsonArray *array,
* @array: a #JsonArray
* @index_: the position of the element to be removed
*
- * Removes the #JsonNode inside @array at @index_ freeing its allocated
- * resources.
+ * Removes the element at the given position inside an array.
+ *
+ * This function will release the reference held on the element.
*/
void
json_array_remove_element (JsonArray *array,
@@ -712,16 +713,16 @@ json_array_remove_element (JsonArray *array,
/**
* json_array_foreach_element:
- * @array: a #JsonArray
+ * @array: an array
* @func: (scope call): the function to be called on each element
* @data: (closure): data to be passed to the function
*
- * Iterates over all elements of @array and calls @func on
+ * Iterates over all elements of an array, and calls a function on
* each one of them.
*
- * It is safe to change the value of a #JsonNode of the @array
- * from within the iterator @func, but it is not safe to add or
- * remove elements from the @array.
+ * It is safe to change the value of an element of the array while
+ * iterating over it, but it is not safe to add or remove elements
+ * from the array.
*
* Since: 0.8
*/
@@ -747,15 +748,16 @@ json_array_foreach_element (JsonArray *array,
/**
* json_array_hash:
- * @key: (type JsonArray): a JSON array to hash
+ * @key: (type JsonArray) (not nullable): a JSON array to hash
+ *
+ * Calculates a hash value for the given `key`.
*
- * Calculate a hash value for the given @key (a #JsonArray).
+ * The hash is calculated over the array and all its elements, recursively.
*
- * The hash is calculated over the array and all its elements, recursively. If
- * the array is immutable, this is a fast operation; otherwise, it scales
+ * If the array is immutable, this is a fast operation; otherwise, it scales
* proportionally with the length of the array.
*
- * Returns: hash value for @key
+ * Returns: hash value for the key
* Since: 1.2
*/
guint
@@ -785,14 +787,17 @@ json_array_hash (gconstpointer key)
/**
* json_array_equal:
- * @a: (type JsonArray): a JSON array
- * @b: (type JsonArray): another JSON array
+ * @a: (type JsonArray) (not nullable): a JSON array
+ * @b: (type JsonArray) (not nullable): another JSON array
+ *
+ * Check whether two arrays are equal.
+ *
+ * Equality is defined as:
*
- * Check whether @a and @b are equal #JsonArrays, meaning they have the same
- * number of elements, and the values of elements in corresponding positions
- * are equal.
+ * - the array have the same number of elements
+ * - the values of elements in corresponding positions are equal
*
- * Returns: %TRUE if @a and @b are equal; %FALSE otherwise
+ * Returns: `TRUE` if the arrays are equal, and `FALSE` otherwise
* Since: 1.2
*/
gboolean
diff --git a/json-glib/json-builder.c b/json-glib/json-builder.c
index 0a7f536..e4170b2 100644
--- a/json-glib/json-builder.c
+++ b/json-glib/json-builder.c
@@ -23,20 +23,18 @@
*/
/**
- * SECTION:json-builder
- * @Title: JsonBuilder
- * @short_description: Generates JSON trees
- * @See_Also: JsonGenerator
+ * JsonBuilder:
*
- * #JsonBuilder provides an object for generating a JSON tree.
- * You can generate only one tree with one #JsonBuilder instance.
+ * `JsonBuilder` provides an object for generating a JSON tree.
*
- * The root of the JSON tree can be either a #JsonObject or a #JsonArray.
+ * 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
- * json_builder_begin_object() or json_builder_begin_array().
+ * [method@Json.Builder.begin_object] or [method@Json.Builder.begin_array].
*
- * For convenience to language bindings, #JsonBuilder returns itself from
- * most of functions, making it easy to chain function calls.
+ * For convenience to language bindings, most `JsonBuilder` method return the
+ * instance, making it easy to chain function calls.
*/
#include "config.h"
@@ -191,7 +189,9 @@ json_builder_class_init (JsonBuilderClass *klass)
* JsonBuilder:immutable:
*
* Whether the #JsonNode tree built by the #JsonBuilder should be immutable
- * when created. Making the output immutable on creation avoids the expense
+ * when created.
+ *
+ * Making the output immutable on creation avoids the expense
* of traversing it to make it immutable later.
*
* Since: 1.2
@@ -238,10 +238,11 @@ json_builder_is_valid_add_mode (JsonBuilder *builder)
/**
* json_builder_new:
*
- * Creates a new #JsonBuilder. You can use this object to generate a
- * JSON tree and obtain the root #JsonNode.
+ * Creates a new `JsonBuilder`.
+ *
+ * You can use this object to generate a JSON tree and obtain the root node.
*
- * Return value: the newly created #JsonBuilder instance
+ * Return value: the newly created builder instance
*/
JsonBuilder *
json_builder_new (void)
@@ -252,11 +253,13 @@ json_builder_new (void)
/**
* json_builder_new_immutable: (constructor)
*
- * Creates a new #JsonBuilder instance with its #JsonBuilder:immutable property
- * set to %TRUE to create immutable output trees.
+ * Creates a new, immutable `JsonBuilder` instance.
+ *
+ * It is equivalent to setting the [property@Json.Builder:immutable] property
+ * set to `TRUE`.
*
* Since: 1.2
- * Returns: (transfer full): a new #JsonBuilder
+ * Returns: (transfer full): the newly create builder instance
*/
JsonBuilder *
json_builder_new_immutable (void)
@@ -266,13 +269,15 @@ json_builder_new_immutable (void)
/**
* json_builder_get_root:
- * @builder: a #JsonBuilder
+ * @builder: a builder
+ *
+ * Returns the root of the current constructed tree.
*
- * Returns the root of the current constructed tree, if the build is complete
- * (ie: all opened objects, object members and arrays are being closed).
+ * 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
+ * `NULL`.
*
- * Return value: (nullable) (transfer full): the #JsonNode, or %NULL if the
- * build is not complete. Free the returned value with json_node_unref().
+ * Return value: (nullable) (transfer full): the root node
*/
JsonNode *
json_builder_get_root (JsonBuilder *builder)
@@ -310,14 +315,14 @@ json_builder_reset (JsonBuilder *builder)
* json_builder_begin_object:
* @builder: a #JsonBuilder
*
- * Opens a subobject inside the given @builder. When done adding members to
- * the subobject, json_builder_end_object() must be called.
+ * Opens a subobject inside the given builder.
*
- * Can be called for first or only if the call is associated to an object member
- * or an array element.
+ * Once you added all members to the object, you must call [method@Json.Builder.end_object].
+ * to close the object.
*
- * Return value: (nullable) (transfer none): the #JsonBuilder, or %NULL if the
- * call was inconsistent
+ * If the builder is in an inconsistent state, this function will return `NULL`.
+ *
+ * Return value: (nullable) (transfer none): the builder instance
*/
JsonBuilder *
json_builder_begin_object (JsonBuilder *builder)
diff --git a/json-glib/json-builder.h b/json-glib/json-builder.h
index b35230e..9cc016c 100644
--- a/json-glib/json-builder.h
+++ b/json-glib/json-builder.h
@@ -42,14 +42,6 @@ typedef struct _JsonBuilder JsonBuilder;
typedef struct _JsonBuilderPrivate JsonBuilderPrivate;
typedef struct _JsonBuilderClass JsonBuilderClass;
-/**
- * JsonBuilder:
- *
- * The `JsonBuilder` structure contains only private data and should be
- * accessed using the provided API
- *
- * Since: 0.12
- */
struct _JsonBuilder
{
/*< private >*/
@@ -58,13 +50,6 @@ struct _JsonBuilder
JsonBuilderPrivate *priv;
};
-/**
- * JsonBuilderClass:
- *
- * The `JsonBuilderClass` structure contains only private data
- *
- * Since: 0.12
- */
struct _JsonBuilderClass
{
/*< private >*/
diff --git a/json-glib/json-gboxed.c b/json-glib/json-gboxed.c
index f274e6d..04fdeea 100644
--- a/json-glib/json-gboxed.c
+++ b/json-glib/json-gboxed.c
@@ -19,53 +19,6 @@
* Emmanuele Bassi <ebassi linux intel com>
*/
-/**
- * SECTION:json-gboxed
- * @short_description: Serialize and deserialize GBoxed types
- *
- * GLib's #GBoxed type is a generic wrapper for arbitrary C structures.
- *
- * JSON-GLib allows serialization and deserialization of a #GBoxed type
- * by registering functions mapping a #JsonNodeType to a specific
- * #GType.
- *
- * When registering a #GBoxed type you should also register the
- * corresponding transformation functions, e.g.:
- *
- * |[<!-- language="C" -->
- * GType
- * my_struct_get_type (void)
- * {
- * static GType boxed_type = 0;
- *
- * if (boxed_type == 0)
- * {
- * boxed_type =
- * g_boxed_type_register_static (g_intern_static_string ("MyStruct"),
- * (GBoxedCopyFunc) my_struct_copy,
- * (GBoxedFreeFunc) my_struct_free);
- *
- * json_boxed_register_serialize_func (boxed_type, JSON_NODE_OBJECT,
- * my_struct_serialize);
- * json_boxed_register_deserialize_func (boxed_type, JSON_NODE_OBJECT,
- * my_struct_deserialize);
- * }
- *
- * return boxed_type;
- * }
- * ]|
- *
- * The serialization function will be invoked by json_boxed_serialize():
- * it will be passed a pointer to the C structure and it must return a
- * #JsonNode. The deserialization function will be invoked by
- * json_boxed_deserialize(): it will be passed a #JsonNode for the
- * declared type and it must return a newly allocated C structure.
- *
- * It is possible to check whether a #GBoxed type can be deserialized
- * from a specific #JsonNodeType, and whether a #GBoxed can be serialized
- * and to which specific #JsonNodeType.
- */
-
#include "config.h"
#include <string.h>
@@ -141,7 +94,7 @@ lookup_boxed_transform (GSList *transforms,
* a #JsonNode of type @node_type
*
* Registers a serialization function for a #GBoxed of type @gboxed_type
- * to a #JsonNode of type @node_type
+ * to a #JsonNode of type @node_type.
*
* Since: 0.10
*/
@@ -226,12 +179,13 @@ json_boxed_register_deserialize_func (GType gboxed_type,
/**
* json_boxed_can_serialize:
* @gboxed_type: a boxed type
- * @node_type: (out): the #JsonNode type to which the boxed type can be
- * serialized into
+ * @node_type: (out) (optional): the #JsonNode 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. The type of the
- * #JsonNode is placed inside @node_type if the function
+ * type @gboxed_type into a #JsonNode.
+ *
+ * The type of the #JsonNode is placed inside @node_type if the function
* returns %TRUE and it's undefined otherwise.
*
* Return value: %TRUE if the type can be serialized,
@@ -293,8 +247,7 @@ json_boxed_can_deserialize (GType gboxed_type,
* @gboxed_type: a boxed type
* @boxed: a pointer to a #GBoxed of type @gboxed_type
*
- * Serializes @boxed, a pointer to a #GBoxed of type @gboxed_type,
- * into a #JsonNode
+ * Serializes a pointer to a #GBoxed of type @gboxed_type into a #JsonNode
*
* Return value: (nullable) (transfer full): a #JsonNode with the serialization of
* the boxed type, or %NULL if serialization either failed or was not possible
@@ -323,7 +276,7 @@ json_boxed_serialize (GType gboxed_type,
* @gboxed_type: a boxed type
* @node: a #JsonNode
*
- * Deserializes @node into a #GBoxed of @gboxed_type
+ * Deserializes @node into a #GBoxed of @gboxed_type.
*
* Return value: (transfer full): the newly allocated #GBoxed. Use
* g_boxed_free() to release the resources allocated by this
diff --git a/json-glib/json-generator.c b/json-glib/json-generator.c
index 4ccf320..dc67c78 100644
--- a/json-glib/json-generator.c
+++ b/json-glib/json-generator.c
@@ -22,11 +22,11 @@
*/
/**
- * SECTION:json-generator
- * @short_description: Generates JSON data streams
+ * JsonGenerator:
*
- * #JsonGenerator provides an object for generating a JSON data stream and
- * put it into a buffer or a file.
+ * `JsonGenerator` provides an object for generating a JSON data stream
+ * from a tree of [struct Json Node] instances, and put it into a buffer
+ * or a file.
*/
#include "config.h"
@@ -203,11 +203,13 @@ json_generator_class_init (JsonGeneratorClass *klass)
GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
/**
- * JsonGenerator:pretty:
+ * JsonGenerator:pretty: (attributes org.gtk.Property.get=json_generator_get_pretty
org.gtk.Property.set=json_generator_set_pretty)
*
* Whether the output should be "pretty-printed", with indentation and
- * newlines. The indentation level can be controlled by using the
- * JsonGenerator:indent property
+ * newlines.
+ *
+ * The indentation level can be controlled by using the
+ * [property@Json.Generator:indent] property.
*/
generator_props[PROP_PRETTY] =
g_param_spec_boolean ("pretty",
@@ -217,7 +219,7 @@ json_generator_class_init (JsonGeneratorClass *klass)
G_PARAM_READWRITE);
/**
- * JsonGenerator:indent:
+ * JsonGenerator:indent: (attributes org.gtk.Property.get=json_generator_get_indent
org.gtk.Property.set=json_generator_set_indent)
*
* Number of spaces to be used to indent when pretty printing.
*/
@@ -230,7 +232,7 @@ json_generator_class_init (JsonGeneratorClass *klass)
G_PARAM_READWRITE);
/**
- * JsonGenerator:root:
+ * 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
* stream.
@@ -245,7 +247,7 @@ json_generator_class_init (JsonGeneratorClass *klass)
G_PARAM_READWRITE);
/**
- * JsonGenerator:indent-char:
+ * JsonGenerator:indent-char: (attributes org.gtk.Property.get=json_generator_get_indent_char
org.gtk.Property.set=json_generator_set_indent_char)
*
* The character that should be used when indenting in pretty print.
*
@@ -469,9 +471,10 @@ dump_object (JsonGenerator *generator,
/**
* json_generator_new:
*
- * Creates a new #JsonGenerator. You can use this object to generate a
- * JSON data stream starting from a data object model composed by
- * #JsonNodes.
+ * 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.
*
* Return value: the newly created #JsonGenerator instance
*/
@@ -486,8 +489,7 @@ json_generator_new (void)
* @generator: a #JsonGenerator
* @string: a #GString
*
- * Generates a JSON data stream from @generator
- * and appends it to @string.
+ * Generates a JSON data stream from @generator and appends it to @string.
*
* Return value: (transfer none): a #GString holding a JSON data stream.
* Use g_string_free() to free the allocated resources.
@@ -513,14 +515,13 @@ json_generator_to_gstring (JsonGenerator *generator,
/**
* json_generator_to_data:
* @generator: a #JsonGenerator
- * @length: (out): return location for the length of the returned
- * buffer, or %NULL
+ * @length: (out) (optional): return location for the length of the returned
+ * buffer
*
* Generates a JSON data stream from @generator and returns it as a
* buffer.
*
- * Return value: a newly allocated buffer holding a JSON data stream.
- * Use g_free() to free the allocated resources.
+ * Return value: (transfer full): a newly allocated string holding a JSON data stream
*/
gchar *
json_generator_to_data (JsonGenerator *generator,
@@ -546,7 +547,9 @@ json_generator_to_data (JsonGenerator *generator,
* @error: return location for a #GError, or %NULL
*
* Creates a JSON data stream and puts it inside @filename, overwriting the
- * current file contents. This operation is atomic.
+ * current file contents.
+ *
+ * This operation is atomic.
*
* Return value: %TRUE if saving was successful.
*/
@@ -573,13 +576,12 @@ json_generator_to_file (JsonGenerator *generator,
* json_generator_to_stream:
* @generator: a #JsonGenerator
* @stream: a #GOutputStream
- * @cancellable: (allow-none): a #GCancellable, or %NULL
+ * @cancellable: (nullable): a #GCancellable
* @error: return location for a #GError, or %NULL
*
* Outputs JSON data and streams it (synchronously) to @stream.
*
- * Return value: %TRUE if the write operation was successful, and %FALSE
- * on failure. In case of error, the #GError will be filled accordingly
+ * Return value: whether the write operation was successful
*
* Since: 0.12
*/
@@ -607,7 +609,7 @@ json_generator_to_stream (JsonGenerator *generator,
}
/**
- * json_generator_set_root:
+ * json_generator_set_root: (attributes org.gtk.Method.set_property=root)
* @generator: a #JsonGenerator
* @node: a #JsonNode
*
@@ -639,14 +641,13 @@ json_generator_set_root (JsonGenerator *generator,
}
/**
- * json_generator_get_root:
+ * json_generator_get_root: (attributes org.gtk.Method.get_property=root)
* @generator: a #JsonGenerator
*
- * Retrieves a pointer to the root #JsonNode set using
- * json_generator_set_root().
+ * Retrieves a pointer to the root node set using
+ * [method@Json.Generator.set_root].
*
- * Return value: (nullable) (transfer none): a #JsonNode, or %NULL. The returned
- * node is owned by the #JsonGenerator and it should not be freed
+ * Return value: (nullable) (transfer none): the root node
*
* Since: 0.14
*/
@@ -659,13 +660,15 @@ json_generator_get_root (JsonGenerator *generator)
}
/**
- * json_generator_set_pretty:
+ * json_generator_set_pretty: (attributes org.gtk.Method.set_property=pretty)
* @generator: a #JsonGenerator
* @is_pretty: whether the generated string should be pretty printed
*
- * Sets whether the generated JSON should be pretty printed, using the
- * indentation character specified in the #JsonGenerator:indent-char
- * property and the spacing specified in #JsonGenerator:indent property.
+ * Sets whether the generated JSON should be pretty printed.
+ *
+ * Pretty printing will use indentation character specified in the
+ * [property@Json.Generator:indent-char] property and the spacing
+ * specified in the [property@Json.Generator:indent] property.
*
* Since: 0.14
*/
@@ -690,10 +693,10 @@ json_generator_set_pretty (JsonGenerator *generator,
}
/**
- * json_generator_get_pretty:
+ * json_generator_get_pretty: (attributes org.gtk.Method.get_property=pretty)
* @generator: a #JsonGenerator
*
- * Retrieves the value set using json_generator_set_pretty().
+ * Retrieves the value set using [method@Json.Generator.set_pretty].
*
* Return value: %TRUE if the generated JSON should be pretty-printed, and
* %FALSE otherwise
@@ -709,7 +712,7 @@ json_generator_get_pretty (JsonGenerator *generator)
}
/**
- * json_generator_set_indent:
+ * json_generator_set_indent: (attributes org.gtk.Method.set_property=indent)
* @generator: a #JsonGenerator
* @indent_level: the number of repetitions of the indentation character
* that should be applied when pretty printing
@@ -737,10 +740,10 @@ json_generator_set_indent (JsonGenerator *generator,
}
/**
- * json_generator_get_indent:
+ * json_generator_get_indent: (attributes org.gtk.Method.get_property=indent)
* @generator: a #JsonGenerator
*
- * Retrieves the value set using json_generator_set_indent().
+ * Retrieves the value set using [method@Json.Generator.set_indent].
*
* Return value: the number of repetitions per indentation level
*
@@ -755,7 +758,7 @@ json_generator_get_indent (JsonGenerator *generator)
}
/**
- * json_generator_set_indent_char:
+ * json_generator_set_indent_char: (attributes org.gtk.Method.set_property=indent-char)
* @generator: a #JsonGenerator
* @indent_char: a Unicode character to be used when indenting
*
@@ -782,10 +785,10 @@ json_generator_set_indent_char (JsonGenerator *generator,
}
/**
- * json_generator_get_indent_char:
+ * json_generator_get_indent_char: (attributes org.gtk.Method.get_property=indent-char)
* @generator: a #JsonGenerator
*
- * Retrieves the value set using json_generator_set_indent_char().
+ * Retrieves the value set using [method@Json.Generator.set_indent_char].
*
* Return value: the character to be used when indenting
*
diff --git a/json-glib/json-generator.h b/json-glib/json-generator.h
index 30a28dc..8f62ba3 100644
--- a/json-glib/json-generator.h
+++ b/json-glib/json-generator.h
@@ -44,12 +44,6 @@ typedef struct _JsonGenerator JsonGenerator;
typedef struct _JsonGeneratorPrivate JsonGeneratorPrivate;
typedef struct _JsonGeneratorClass JsonGeneratorClass;
-/**
- * JsonGenerator:
- *
- * JSON data streams generator. The contents of the #JsonGenerator structure
- * are private and should only be accessed via the provided API.
- */
struct _JsonGenerator
{
/*< private >*/
@@ -58,11 +52,6 @@ struct _JsonGenerator
JsonGeneratorPrivate *priv;
};
-/**
- * JsonGeneratorClass:
- *
- * #JsonGenerator class
- */
struct _JsonGeneratorClass
{
/*< private >*/
diff --git a/json-glib/json-gobject.c b/json-glib/json-gobject.c
index b42dc83..8d31623 100644
--- a/json-glib/json-gobject.c
+++ b/json-glib/json-gobject.c
@@ -17,21 +17,6 @@
* Emmanuele Bassi <ebassi openedhand com>
*/
-/**
- * SECTION:json-gobject
- * @short_description: Serialize and deserialize GObjects
- *
- * JSON-GLib provides API for serializing and deserializing #GObject
- * instances to and from JSON data streams.
- *
- * Simple #GObject classes can be (de)serialized into JSON objects, if the
- * properties have compatible types with the native JSON types (integers,
- * booleans, strings, string vectors). If the class to be (de)serialized has
- * complex data types for properties (like boxed types or other objects)
- * then the class should implement the provided #JsonSerializable interface
- * and its virtual functions.
- */
-
#include "config.h"
#include <string.h>
@@ -857,18 +842,20 @@ json_gobject_serialize (GObject *gobject)
* @error: return location for a #GError, or %NULL
*
* Deserializes a JSON data stream and creates the corresponding
- * #GObject class. 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.
+ * #GObject class.
*
- * Note: the JSON data stream must be an object declaration.
+ * 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.
+ *
+ * **Note**: the JSON data stream must be an object declaration.
*
- * Return value: (transfer full): a #GObject or %NULL
+ * Return value: (transfer full) (nullable): a #GObject instance of the given type
*
* Since: 0.4
*
- * Deprecated: 0.10: Use json_gobject_from_data() instead
+ * Deprecated: 0.10: Use [func@Json.gobject_from_data] instead
*/
GObject *
json_construct_gobject (GType gtype,
@@ -887,14 +874,16 @@ json_construct_gobject (GType gtype,
* @error: return location for a #GError, or %NULL
*
* Deserializes a JSON data stream and creates the corresponding
- * #GObject class. 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.
+ * #GObject class.
+ *
+ * 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.
*
* Note: the JSON data stream must be an object declaration.
*
- * Return value: (transfer full): a #GObject or %NULL
+ * Return value: (transfer full) (nullable): a #GObject of the given type
*
* Since: 0.10
*/
@@ -948,16 +937,18 @@ json_gobject_from_data (GType gtype,
/**
* json_serialize_gobject:
* @gobject: a #GObject
- * @length: (out): return value for the length of the buffer, or %NULL
+ * @length: (out) (optional): return value for the length of the buffer
*
- * Serializes a #GObject into a JSON data stream. If @gobject implements
- * the #JsonSerializableIface 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.
+ * Serializes a #GObject into a JSON data stream.
*
- * Return value: a JSON data stream representing the passed #GObject
+ * If @gobject implements the #JsonSerializableIface 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.
+ *
+ * Return value: (transfer full): a JSON data stream representing the given object
*
- * Deprecated: 0.10: Use json_gobject_to_data() instead
+ * Deprecated: 0.10: Use [func@Json.gobject_to_data] instead
*/
gchar *
json_serialize_gobject (GObject *gobject,
@@ -969,7 +960,7 @@ json_serialize_gobject (GObject *gobject,
/**
* json_gobject_to_data:
* @gobject: a #GObject
- * @length: (out): return value for the length of the buffer, or %NULL
+ * @length: (out) (optional): return value for the length of the buffer
*
* Serializes a #GObject into a JSON data stream, iterating recursively
* over each property.
diff --git a/json-glib/json-gvariant.c b/json-glib/json-gvariant.c
index 72df81d..8e693c8 100644
--- a/json-glib/json-gvariant.c
+++ b/json-glib/json-gvariant.c
@@ -33,48 +33,6 @@
#include "json-parser.h"
#include "json-types-private.h"
-/**
- * SECTION:json-gvariant
- * @short_description: Serialize and deserialize GVariant types
- * @Title: JSON GVariant Integration
- *
- * Use json_gvariant_serialize() and json_gvariant_serialize_data() to
- * convert from any #GVariant value to a #JsonNode tree or its string
- * representation.
- *
- * Use json_gvariant_deserialize() and json_gvariant_deserialize_data() to
- * obtain the #GVariant value from a #JsonNode tree or directly from a JSON
- * string.
- *
- * Since many #GVariant data types cannot be directly represented as
- * JSON, a #GVariant type string (signature) should be provided to these
- * methods in order to obtain a correct, type-contrained result.
- * If no signature is provided, conversion can still be done, but the
- * resulting #GVariant value will be "guessed" from the JSON data types
- * using the following rules:
- *
- * ## Strings
- * JSON strings map to GVariant `(s)`.
- *
- * ## Integers
- * JSON integers map to GVariant int64 `(x)`.
- *
- * ## Booleans
- * JSON booleans map to GVariant boolean `(b)`.
- *
- * ## Numbers
- * JSON numbers map to GVariant double `(d)`.
- *
- * ## Arrays
- * JSON arrays map to GVariant arrays of variants `(av)`.
- *
- * ## Objects
- * JSON objects map to GVariant dictionaries of string to variants `(a{sv})`.
- *
- * ## Null values
- * JSON null values map to GVariant maybe variants `(mv)`.
- */
-
/* custom extension to the GVariantClass enumeration to differentiate
* a single dictionary entry from an array of dictionary entries
*/
@@ -257,12 +215,12 @@ gvariant_to_json_object (GVariant *variant)
/**
* json_gvariant_serialize:
- * @variant: A #GVariant to convert
+ * @variant: A `GVariant` to convert
*
- * Converts @variant to a JSON tree.
+ * Converts `variant` to a JSON tree.
*
- * Return value: (transfer full): A #JsonNode representing the root of the
- * JSON data structure obtained from @variant
+ * Return value: (transfer full): the root of the JSON data structure
+ * obtained from `variant`
*
* Since: 0.14
*/
@@ -413,15 +371,15 @@ json_gvariant_serialize (GVariant *variant)
/**
* json_gvariant_serialize_data:
* @variant: A #GVariant to convert
- * @length: (out) (allow-none): Return location for the length of the returned
- * string, or %NULL
+ * @length: (out) (optional): the length of the returned string
*
- * Converts @variant to its JSON encoded string representation. This method
- * is actually a helper function. It uses json_gvariant_serialize() to obtain the
- * JSON tree, and then #JsonGenerator to stringify it.
+ * Converts @variant to its JSON encoded string representation.
+ *
+ * This is a convenience function around [func@Json.gvariant_serialize], to
+ * obtain the JSON tree, and then [class@Json.Generator] to stringify it.
*
* Return value: (transfer full): The JSON encoded string corresponding to
- * @variant
+ * the given variant
*
* Since: 0.14
*/
@@ -1275,25 +1233,31 @@ out:
/**
* json_gvariant_deserialize:
* @json_node: A #JsonNode to convert
- * @signature: (allow-none): A valid #GVariant type string, or %NULL
+ * @signature: (nullable): A valid `GVariant` type string
* @error: A pointer to a #GError
*
- * Converts a JSON data structure to a GVariant value using @signature to
- * resolve ambiguous data types. If no error occurs, the resulting #GVariant
- * is guaranteed to conform to @signature.
+ * Converts a JSON data structure to a `GVariant`.
+ *
+ * If `signature` is not `NULL`, it will be used to resolve ambiguous
+ * data types.
*
- * If @signature is not %NULL but does not represent a valid GVariant type
- * string, %NULL is returned and error is set to %G_IO_ERROR_INVALID_ARGUMENT.
- * If a @signature is provided but the JSON structure cannot be mapped to it,
- * %NULL is returned and error is set to %G_IO_ERROR_INVALID_DATA.
- * If @signature is %NULL, the conversion is done based strictly on the types
+ * If no error occurs, the resulting `GVariant` is guaranteed to conform
+ * to `signature`.
+ *
+ * If `signature` is not `NULL` but does not represent a valid `GVariant` type
+ * string, `NULL` is returned and the `error` is set to
+ * `G_IO_ERROR_INVALID_ARGUMENT`.
+ *
+ * If a `signature` is provided but the JSON structure cannot be mapped to it,
+ * `NULL` is returned and the `error` is set to `G_IO_ERROR_INVALID_DATA`.
+ *
+ * If `signature` is `NULL`, the conversion is done based strictly on the types
* in the JSON nodes.
*
* The returned variant has a floating reference that will need to be sunk
* by the caller code.
*
- * Return value: (transfer none): A newly created, floating #GVariant
- * compliant with @signature, or %NULL on error
+ * Return value: (transfer floating) (nullable): A newly created `GVariant`
*
* Since: 0.14
*/
@@ -1319,20 +1283,23 @@ json_gvariant_deserialize (JsonNode *json_node,
/**
* json_gvariant_deserialize_data:
* @json: A JSON data string
- * @length: The length of @json, or -1 if %NULL-terminated
- * @signature: (allow-none): A valid #GVariant type string, or %NULL
+ * @length: The length of @json, or -1 if `NUL`-terminated
+ * @signature: (nullable): A valid `GVariant` type string
* @error: A pointer to a #GError
*
- * Converts a JSON string to a #GVariant value. This method works exactly
- * like json_gvariant_deserialize(), but takes a JSON encoded string instead.
- * The string is first converted to a #JsonNode using #JsonParser, and then
- * json_gvariant_deserialize() is called.
+ * Converts a JSON string to a `GVariant` value.
+ *
+ * This function works exactly like [func@Json.gvariant_deserialize], but
+ * takes a JSON encoded string instead.
+ *
+ * The string is first converted to a [struct Json Node] using
+ * [class@Json.Parser], and then `json_gvariant_deserialize` is called on
+ * the node.
*
* The returned variant has a floating reference that will need to be sunk
* by the caller code.
*
- * Returns: (transfer none): A newly created, floating #GVariant compliant
- * with @signature, or %NULL on error
+ * Returns: (transfer floating) (nullable): A newly created `GVariant`D compliant
*
* Since: 0.14
*/
diff --git a/json-glib/json-node.c b/json-glib/json-node.c
index a6898d9..1221e93 100644
--- a/json-glib/json-node.c
+++ b/json-glib/json-node.c
@@ -32,11 +32,11 @@
#include "json-debug.h"
/**
- * SECTION:json-node
- * @short_description: Node in a JSON object model
+ * JsonNode:
*
- * A #JsonNode is a generic container of elements inside a JSON stream.
- * It can contain fundamental types (integers, booleans, floating point
+ * A generic container of JSON data types.
+ *
+ * `JsonNode` can contain fundamental types (integers, booleans, floating point
* numbers, strings) and complex types (arrays and objects).
*
* When parsing a JSON data stream you extract the root node and walk
@@ -60,7 +60,7 @@
*
* #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 zero or more
+ * 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
@@ -68,7 +68,7 @@
* and json_node_unref() internally.
*/
-G_DEFINE_BOXED_TYPE (JsonNode, json_node, json_node_copy, json_node_unref);
+G_DEFINE_BOXED_TYPE (JsonNode, json_node, json_node_copy, json_node_unref)
/**
* json_node_get_value_type:
@@ -111,8 +111,9 @@ json_node_get_value_type (JsonNode *node)
/**
* json_node_alloc: (constructor)
*
- * Allocates a new #JsonNode. Use json_node_init() and its variants
- * to initialize the returned value.
+ * Allocates a new #JsonNode.
+ *
+ * Use 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
@@ -379,9 +380,9 @@ json_node_init_null (JsonNode *node)
* This is a convenience function for json_node_alloc() and json_node_init(),
* and it's the equivalent of:
*
- * |[<!-- language="C" -->
- json_node_init (json_node_alloc (), type);
- * ]|
+ * ```c
+ json_node_init (json_node_alloc (), type);
+ * ```
*
* Return value: (transfer full): the newly created #JsonNode
*/
@@ -398,7 +399,9 @@ json_node_new (JsonNodeType type)
* json_node_copy:
* @node: a #JsonNode
*
- * Copies @node. If the node contains complex data types, their reference
+ * Copies @node.
+ *
+ * If the node contains complex data types, their reference
* counts are increased, regardless of whether the node is mutable or
* immutable.
*
@@ -456,7 +459,7 @@ json_node_copy (JsonNode *node)
* json_node_ref:
* @node: a #JsonNode
*
- * Increment the reference count of @node.
+ * Increments the reference count of @node.
*
* Since: 1.2
* Returns: (transfer full): a pointer to @node
@@ -475,8 +478,9 @@ json_node_ref (JsonNode *node)
* json_node_unref:
* @node: (transfer full): a #JsonNode
*
- * Decrement the reference count of @node. If it reaches zero, the node is
- * freed.
+ * Decrements the reference count of @node.
+ *
+ * If the reference count reaches zero, the node is freed.
*
* Since: 1.2
*/
@@ -498,7 +502,9 @@ json_node_unref (JsonNode *node)
* @node: a #JsonNode initialized to %JSON_NODE_OBJECT
* @object: (nullable): a #JsonObject
*
- * Sets @objects inside @node. The reference count of @object is increased.
+ * Sets @objects inside @node.
+ *
+ * The reference count of @object is increased.
*
* If @object is %NULL, the node’s existing object is cleared.
*
@@ -527,7 +533,9 @@ json_node_set_object (JsonNode *node,
* @node: a #JsonNode initialized to %JSON_NODE_OBJECT
* @object: (transfer full): a #JsonObject
*
- * Sets @object inside @node. The reference count of @object is not increased.
+ * Sets @object inside @node.
+ *
+ * The reference count of @object is not increased.
*
* It is an error to call this on an immutable node, or on a node which is not
* an object node.
@@ -554,9 +562,10 @@ json_node_take_object (JsonNode *node,
* json_node_get_object:
* @node: a #JsonNode
*
- * Retrieves the #JsonObject stored inside a #JsonNode. It is a programmer error
- * to call this on a node which doesn’t hold an object value. Use
- * %JSON_NODE_HOLDS_OBJECT first.
+ * Retrieves the #JsonObject stored inside a #JsonNode.
+ *
+ * It is a programmer error to call this on a node which doesn’t hold an
+ * object value. Use %JSON_NODE_HOLDS_OBJECT first.
*
* Return value: (transfer none) (nullable): the #JsonObject
*/
@@ -573,10 +582,12 @@ json_node_get_object (JsonNode *node)
* json_node_dup_object:
* @node: a #JsonNode
*
- * Retrieves the #JsonObject 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.
+ * Retrieves the #JsonObject 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.
*
* Return value: (transfer full) (nullable): the #JsonObject
*/
@@ -597,10 +608,12 @@ json_node_dup_object (JsonNode *node)
* @node: a #JsonNode initialized to %JSON_NODE_ARRAY
* @array: a #JsonArray
*
- * Sets @array inside @node and increases the #JsonArray reference count.
+ * Sets @array inside @node.
*
- * It is an error to call this on an immutable node, or on a node which is not
- * an array 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.
*/
void
json_node_set_array (JsonNode *node,
@@ -624,10 +637,12 @@ json_node_set_array (JsonNode *node,
* @node: a #JsonNode initialized to %JSON_NODE_ARRAY
* @array: (transfer full): a #JsonArray
*
- * Sets @array into @node without increasing the #JsonArray reference count.
+ * Sets @array inside @node.
*
- * It is an error to call this on an immutable node, or a node which is not
- * an array 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.
*/
void
json_node_take_array (JsonNode *node,
@@ -651,9 +666,10 @@ json_node_take_array (JsonNode *node,
* json_node_get_array:
* @node: a #JsonNode
*
- * Retrieves the #JsonArray stored inside a #JsonNode. It is a programmer error
- * to call this on a node which doesn’t hold an array value. Use
- * %JSON_NODE_HOLDS_ARRAY first.
+ * Retrieves the #JsonArray stored inside a #JsonNode.
+ *
+ * It is a programmer error to call this on a node which doesn’t hold an
+ * array value. Use %JSON_NODE_HOLDS_ARRAY first.
*
* Return value: (transfer none) (nullable): the #JsonArray
*/
@@ -670,10 +686,12 @@ json_node_get_array (JsonNode *node)
* json_node_dup_array:
* @node: a #JsonNode
*
- * Retrieves the #JsonArray stored inside a #JsonNode and returns it
- * with its reference count increased by one. It is a programmer error
- * to call this on a node which doesn’t hold an array value. Use
- * %JSON_NODE_HOLDS_ARRAY first.
+ * Retrieves the #JsonArray 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.
*
* Return value: (transfer full) (nullable): the #JsonArray with its reference
* count increased.
@@ -695,10 +713,12 @@ json_node_dup_array (JsonNode *node)
* @node: a #JsonNode
* @value: (out caller-allocates): return location for an uninitialized value
*
- * Retrieves a value from a #JsonNode and copies into @value. When done
- * using it, call g_value_unset() on the #GValue. It is a programmer error
- * to call this on a node which doesn’t hold a scalar value. Use
- * %JSON_NODE_HOLDS_VALUE first.
+ * Retrieves a value from a #JsonNode and copies into @value.
+ *
+ * When done using it, call g_value_unset() on the #GValue.
+ *
+ * It is a programmer error to call this on a node which doesn’t hold a scalar
+ * value. Use %JSON_NODE_HOLDS_VALUE first.
*/
void
json_node_get_value (JsonNode *node,
@@ -739,7 +759,9 @@ json_node_get_value (JsonNode *node,
* @node: a #JsonNode initialized to %JSON_NODE_VALUE
* @value: the #GValue to set
*
- * Sets @value inside @node. The passed #GValue is copied into the #JsonNode.
+ * Sets @value inside @node.
+ *
+ * The passed #GValue is copied into the #JsonNode.
*
* It is an error to call this on an immutable node, or on a node which is not
* a value node.
@@ -822,10 +844,11 @@ json_node_free (JsonNode *node)
* json_node_seal:
* @node: a #JsonNode
*
- * Seals the #JsonNode, 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
- * sealed, etc.
+ * Seals the #JsonNode, 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 sealed, etc.
*
* If the @node is already immutable, this is a no-op.
*
@@ -886,8 +909,7 @@ json_node_is_immutable (JsonNode *node)
*
* Retrieves the user readable name of the data type contained by @node.
*
- * Return value: a string containing the name of the type. The returned string
- * is owned by the node and should never be modified or freed
+ * Return value: (transfer none): a string containing the name of the type.
*/
const gchar *
json_node_type_name (JsonNode *node)
@@ -941,8 +963,9 @@ json_node_type_get_name (JsonNodeType node_type)
*
* Sets the parent #JsonNode of @node.
*
- * It is an error to call this with an immutable @parent. @node may be
- * immutable.
+ * It is an error to call this with an immutable @parent.
+ *
+ * The @node may be immutable.
*
* Since: 0.8
*/
@@ -1028,12 +1051,12 @@ json_node_get_string (JsonNode *node)
* json_node_dup_string:
* @node: a #JsonNode of type %JSON_NODE_VALUE
*
- * Gets a copy of the string value stored inside a #JsonNode. If the node does
- * not hold a string value, %NULL is returned.
+ * Gets a copy of the string value stored inside a #JsonNode.
*
- * Return value: (transfer full) (nullable): a newly allocated string
- * containing a copy of the #JsonNode contents. Use g_free() to free the
- * allocated resources
+ * 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
*/
gchar *
json_node_dup_string (JsonNode *node)
@@ -1074,11 +1097,15 @@ json_node_set_int (JsonNode *node,
* json_node_get_int:
* @node: a #JsonNode of type %JSON_NODE_VALUE
*
- * Gets the integer value stored inside a #JsonNode. If the node holds a double
- * value, its integer component is returned. 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 non-integer type,
- * `0` is returned.
+ * Gets the integer value stored inside a #JsonNode.
+ *
+ * If the node holds a double value, its integer component is returned.
+ *
+ * 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
+ * non-integer type, `0` is returned.
*
* Return value: an integer value.
*/
@@ -1133,11 +1160,15 @@ json_node_set_double (JsonNode *node,
* json_node_get_double:
* @node: a #JsonNode of type %JSON_NODE_VALUE
*
- * Gets the double value stored inside a #JsonNode. 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 a non-zero double is returned. If the node holds
- * a %JSON_NODE_NULL value or a value of another non-double type, `0.0` is
- * returned.
+ * Gets the double value stored inside a #JsonNode.
+ *
+ * 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
+ * a non-zero double is returned.
+ *
+ * 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.
*/
@@ -1192,9 +1223,12 @@ json_node_set_boolean (JsonNode *node,
* json_node_get_boolean:
* @node: a #JsonNode of type %JSON_NODE_VALUE
*
- * Gets the boolean value stored inside a #JsonNode. 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
+ * Gets the boolean value stored inside a #JsonNode.
+ *
+ * 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.
*
* Return value: a boolean value.
@@ -1263,21 +1297,21 @@ json_node_is_null (JsonNode *node)
* @sub: sub-type
* @super: super-type
*
- * Check whether @sub is a sub-type of, or equal to, @super. The only sub-type
- * relationship in the JSON Schema type system is that
- * %WBL_PRIMITIVE_TYPE_INTEGER is a sub-type of %WBL_PRIMITIVE_TYPE_NUMBER.
+ * Check whether @sub is a sub-type of, or equal to, @super.
+ *
+ * The only sub-type relationship in the JSON Schema type system is that
+ * an integer type is a sub-type of a number type.
*
* Formally, this function calculates: `@sub <: @super`.
*
* 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
-json_type_is_a (JsonNode *sub,
- JsonNode *super)
+json_type_is_a (JsonNode *sub,
+ JsonNode *super)
{
if (super->type == JSON_NODE_VALUE && sub->type == JSON_NODE_VALUE)
{
@@ -1339,10 +1373,11 @@ json_string_equal (gconstpointer a,
* @b: (type utf8): another JSON string
*
* Check whether @a and @b are equal UTF-8 JSON strings and return an ordering
- * over them in strcmp() style.
+ * over them in `strcmp()` style.
+ *
+ * Returns: an integer less than zero if `a < b`, equal to zero if `a == b`, and
+ * greater than zero if `a > b`
*
- * Returns: an integer less than zero if @a < @b, equal to zero if @a == @b, and
- * greater than zero if @a > @b
* Since: 1.2
*/
gint
@@ -1402,9 +1437,10 @@ json_node_hash (gconstpointer key)
* @b: (type JsonNode): another JSON node
*
* Check whether @a and @b are equal #JsonNodes, 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.
+ * 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
* Since: 1.2
diff --git a/json-glib/json-object.c b/json-glib/json-object.c
index 8555eb9..3c4c376 100644
--- a/json-glib/json-object.c
+++ b/json-glib/json-object.c
@@ -29,22 +29,26 @@
#include "json-types-private.h"
/**
- * SECTION:json-object
- * @short_description: a JSON object representation
+ * JsonObject:
*
- * #JsonObject is the representation of the object type inside JSON. It
- * contains #JsonNodes, which may contain fundamental types, arrays or other
- * objects; each node inside an object, or "member", is accessed using a
- * unique string, or "name".
+ * `JsonObject` is the representation of the object type inside JSON.
*
- * Since objects can be expensive, they are reference counted. You can control
- * the lifetime of a #JsonObject using json_object_ref() and json_object_unref().
+ * A `JsonObject` contains [struct Json Node] "members", which may contain
+ * fundamental types, arrays or other objects; each member of an object is
+ * accessed using a unique string, or "name".
+ *
+ * Since objects can be arbitrarily big, copying them can be expensive; for
+ * this reason they are reference counted. You can control the lifetime of
+ * a `JsonObject` using [method Json Object ref] and [method@Json.Object.unref].
+ *
+ * To add or overwrite a member with a given name, use [method@Json.Object.set_member].
+ *
+ * To extract a member with a given name, use [method@Json.Object.get_member].
+ *
+ * To retrieve the list of members, use [method@Json.Object.get_members].
*
- * To add or overwrite a member with a given name, use json_object_set_member().
- * To extract a member with a given name, use json_object_get_member().
- * To retrieve the list of members, use json_object_get_members().
* To retrieve the size of the object (that is, the number of members it has),
- * use json_object_get_size().
+ * use [method@Json.Object.get_size].
*/
G_DEFINE_BOXED_TYPE (JsonObject, json_object, json_object_ref, json_object_unref);
@@ -52,9 +56,9 @@ G_DEFINE_BOXED_TYPE (JsonObject, json_object, json_object_ref, json_object_unref
/**
* json_object_new: (constructor)
*
- * Creates a new #JsonObject, an JSON object type representation.
+ * Creates a new object.
*
- * Return value: (transfer full): the newly created #JsonObject
+ * Return value: (transfer full): the newly created object
*/
JsonObject *
json_object_new (void)
@@ -75,11 +79,11 @@ json_object_new (void)
/**
* json_object_ref:
- * @object: a #JsonObject
+ * @object: an object
*
- * Increase by one the reference count of a #JsonObject.
+ * Acquires a reference on the given object.
*
- * Return value: (transfer none): the passed #JsonObject, with the reference count
+ * Return value: (transfer none): the given object, with the reference count
* increased by one.
*/
JsonObject *
@@ -95,11 +99,12 @@ json_object_ref (JsonObject *object)
/**
* json_object_unref:
- * @object: a #JsonObject
+ * @object: an object
*
- * Decreases by one the reference count of a #JsonObject. If the
- * reference count reaches zero, the object is destroyed and all
- * its allocated resources are freed.
+ * Releases a reference on the given object.
+ *
+ * If the reference count reaches zero, the object is destroyed and
+ * all its resources are freed.
*/
void
json_object_unref (JsonObject *object)
@@ -119,12 +124,13 @@ json_object_unref (JsonObject *object)
/**
* json_object_seal:
- * @object: a #JsonObject
+ * @object: an object
*
- * Seals the #JsonObject, making it immutable to further changes. This will
- * recursively seal all members of the object too.
+ * Seals the object, making it immutable to further changes.
*
- * If the @object is already immutable, this is a no-op.
+ * This function will recursively seal all members of the object too.
+ *
+ * If the object is already immutable, this is a no-op.
*
* Since: 1.2
*/
@@ -152,13 +158,13 @@ json_object_seal (JsonObject *object)
/**
* json_object_is_immutable:
- * @object: a #JsonObject
+ * @object: an object
*
- * Check whether the given @object has been marked as immutable by calling
- * json_object_seal() on it.
+ * Checks whether the given object has been marked as immutable by calling
+ * [method Json Object seal] on it.
*
* Since: 1.2
- * Returns: %TRUE if the @object is immutable
+ * Returns: `TRUE` if the object is immutable
*/
gboolean
json_object_is_immutable (JsonObject *object)
@@ -199,17 +205,16 @@ object_set_member_internal (JsonObject *object,
/**
* json_object_add_member:
- * @object: a #JsonObject
+ * @object: an object
* @member_name: the name of the member
* @node: (transfer full): the value of the member
*
- * Adds a member named @member_name and containing @node into a #JsonObject.
- * The object will take ownership of the #JsonNode.
+ * Adds a new member for the given name and value into an object.
*
- * This function will return if the @object already contains a member
- * @member_name.
+ * This function will return if the object already contains a member
+ * with the same name.
*
- * Deprecated: 0.8: Use json_object_set_member() instead
+ * Deprecated: 0.8: Use [method@Json.Object.set_member] instead
*/
void
json_object_add_member (JsonObject *object,
@@ -233,15 +238,17 @@ json_object_add_member (JsonObject *object,
/**
* json_object_set_member:
- * @object: a #JsonObject
+ * @object: an object
* @member_name: the name of the member
* @node: (transfer full): the value of the member
*
- * Sets @node as the value of @member_name inside @object.
+ * Sets the value of a member inside an object.
*
- * If @object already contains a member called @member_name then
- * the member's current value is overwritten. Otherwise, a new
- * member is added to @object.
+ * If the object does not have a member with the given name, a new member
+ * is created.
+ *
+ * If the object already has a member with the given name, the current
+ * value is overwritten with the new.
*
* Since: 0.8
*/
@@ -269,14 +276,13 @@ set_member:
/**
* json_object_set_int_member:
- * @object: a #JsonObject
+ * @object: an object
* @member_name: the name of the member
* @value: the value of the member
*
- * Convenience function for setting an integer @value of
- * @member_name inside @object.
+ * Convenience function for setting an object member with an integer value.
*
- * See also: json_object_set_member()
+ * See also: [method@Json.Object.set_member], [method Json Node.init_int]
*
* Since: 0.8
*/
@@ -293,14 +299,13 @@ json_object_set_int_member (JsonObject *object,
/**
* json_object_set_double_member:
- * @object: a #JsonObject
+ * @object: an object
* @member_name: the name of the member
* @value: the value of the member
*
- * Convenience function for setting a floating point @value
- * of @member_name inside @object.
+ * Convenience function for setting an object member with a floating point value.
*
- * See also: json_object_set_member()
+ * See also: [method@Json.Object.set_member], [method Json Node.init_double]
*
* Since: 0.8
*/
@@ -317,14 +322,13 @@ json_object_set_double_member (JsonObject *object,
/**
* json_object_set_boolean_member:
- * @object: a #JsonObject
+ * @object: an object
* @member_name: the name of the member
* @value: the value of the member
*
- * Convenience function for setting a boolean @value of
- * @member_name inside @object.
+ * Convenience function for setting an object member with a boolean value.
*
- * See also: json_object_set_member()
+ * See also: [method@Json.Object.set_member], [method Json Node.init_boolean]
*
* Since: 0.8
*/
@@ -341,14 +345,13 @@ json_object_set_boolean_member (JsonObject *object,
/**
* json_object_set_string_member:
- * @object: a #JsonObject
+ * @object: an object
* @member_name: the name of the member
* @value: the value of the member
*
- * Convenience function for setting a string @value of
- * @member_name inside @object.
+ * Convenience function for setting an object member with a string value.
*
- * See also: json_object_set_member()
+ * See also: [method@Json.Object.set_member], [method Json Node.init_string]
*
* Since: 0.8
*/
@@ -374,13 +377,12 @@ json_object_set_string_member (JsonObject *object,
/**
* json_object_set_null_member:
- * @object: a #JsonObject
+ * @object: an object
* @member_name: the name of the member
*
- * Convenience function for setting a null @value of
- * @member_name inside @object.
+ * Convenience function for setting an object member with a `null` value.
*
- * See also: json_object_set_member()
+ * See also: [method@Json.Object.set_member], [method Json Node.init_null]
*
* Since: 0.8
*/
@@ -396,16 +398,13 @@ json_object_set_null_member (JsonObject *object,
/**
* json_object_set_array_member:
- * @object: a #JsonObject
+ * @object: an bject
* @member_name: the name of the member
* @value: (transfer full): the value of the member
*
- * Convenience function for setting an array @value of
- * @member_name inside @object.
- *
- * The @object will take ownership of the passed #JsonArray
+ * Convenience function for setting an object member with an array value.
*
- * See also: json_object_set_member()
+ * See also: [method@Json.Object.set_member], [method Json Node.take_array]
*
* Since: 0.8
*/
@@ -438,12 +437,9 @@ json_object_set_array_member (JsonObject *object,
* @member_name: the name of the member
* @value: (transfer full): the value of the member
*
- * Convenience function for setting an object @value of
- * @member_name inside @object.
+ * Convenience function for setting an object member with an object value.
*
- * The @object will take ownership of the passed #JsonObject
- *
- * See also: json_object_set_member()
+ * See also: [method@Json.Object.set_member], [method Json Node.take_object]
*
* Since: 0.8
*/
@@ -472,16 +468,15 @@ json_object_set_object_member (JsonObject *object,
/**
* json_object_get_members:
- * @object: a #JsonObject
+ * @object: an object
*
- * Retrieves all the names of the members of a #JsonObject. You can
- * obtain the value for each member using json_object_get_member().
+ * Retrieves all the names of the members of an object.
*
- * Return value: (element-type utf8) (transfer container) (nullable): a
- * #GList of member names, or %NULL. The content of the list is owned
- * by the #JsonObject and should never be modified or freed. When you
- * have finished using the returned list, use g_list_free() to free
- * the resources it has allocated.
+ * 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
+ * member names of the object
*/
GList *
json_object_get_members (JsonObject *object)
@@ -502,15 +497,12 @@ json_object_get_members_internal (JsonObject *object)
/**
* json_object_get_values:
- * @object: a #JsonObject
+ * @object: an object
*
- * Retrieves all the values of the members of a #JsonObject.
+ * Retrieves all the values of the members of an object.
*
- * Return value: (element-type JsonNode) (transfer container) (nullable): a
- * #GList of #JsonNodes, or %NULL. The content of the list is owned by the
- * #JsonObject and should never be modified or freed. When you have finished
- * using the returned list, use g_list_free() to free the resources it has
- * allocated.
+ * Return value: (element-type JsonNode) (transfer container) (nullable): the
+ * member values of the object
*/
GList *
json_object_get_values (JsonObject *object)
@@ -528,14 +520,13 @@ json_object_get_values (JsonObject *object)
/**
* json_object_dup_member:
- * @object: a #JsonObject
+ * @object: an object
* @member_name: the name of the JSON object member to access
*
- * Retrieves a copy of the #JsonNode containing the value of @member_name
- * inside a #JsonObject
+ * Retrieves a copy of the value of the given member inside an object.
*
- * Return value: (transfer full) (nullable): a copy of the node for the
- * requested object member or %NULL. Use json_node_unref() when done.
+ * Return value: (transfer full) (nullable): a copy of the value for the
+ * requested object member
*
* Since: 0.6
*/
@@ -564,14 +555,13 @@ object_get_member_internal (JsonObject *object,
/**
* json_object_get_member:
- * @object: a #JsonObject
+ * @object: an object
* @member_name: the name of the JSON object member to access
*
- * Retrieves the #JsonNode containing the value of @member_name inside
- * a #JsonObject.
+ * Retrieves the value of the given member inside an object.
*
- * Return value: (transfer none) (nullable): a pointer to the node for the
- * requested object member, or %NULL if it does not exist.
+ * Return value: (transfer none) (nullable): the value for the
+ * requested object member
*/
JsonNode *
json_object_get_member (JsonObject *object,
@@ -1087,9 +1077,9 @@ json_object_equal (gconstpointer a,
* @iter: an uninitialised #JsonObjectIter
* @object: the #JsonObject to iterate over
*
- * Initialise the @iter and associate it with @object.
+ * Initialises the @iter and associate it with @object.
*
- * |[<!-- language="C" -->
+ * ```c
* JsonObjectIter iter;
* const gchar *member_name;
* JsonNode *member_node;
@@ -1099,7 +1089,12 @@ json_object_equal (gconstpointer a,
* {
* // Do something with @member_name and @member_node.
* }
- * ]|
+ * ```
+ *
+ * The iterator initialized with this function will iterate the
+ * members of the object in an undefined order.
+ *
+ * See also: [method@Json.ObjectIter.init_ordered]
*
* Since: 1.2
*/
@@ -1125,21 +1120,24 @@ json_object_iter_init (JsonObjectIter *iter,
* @member_node: (out callee-allocates) (transfer none) (optional): return
* location for the member value, or %NULL to ignore
*
- * Advance @iter and retrieve the next member in the object. 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.
+ * Advances @iter and retrieves the next member in the object.
+ *
+ * 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.
*
- * You must use this function with a #JsonObjectIter initialized with
- * json_object_iter_init(); using this function with an iterator initialized
- * with json_object_iter_init_ordered() yields undefined behavior.
+ * You must use this function with an iterator initialized with
+ * [method Json ObjectIter init]; using this function with an iterator
+ * initialized with [method@Json.ObjectIter.init_ordered] yields undefined
+ * behavior.
*
- * See also: json_object_iter_next_ordered()
+ * 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
+ * of the object has been reached
*
* Since: 1.2
*/
@@ -1164,9 +1162,9 @@ json_object_iter_next (JsonObjectIter *iter,
* @iter: an uninitialised #JsonObjectIter
* @object: the #JsonObject to iterate over
*
- * Initialise the @iter and associate it with @object.
+ * Initialises the @iter and associate it with @object.
*
- * |[<!-- language="C" -->
+ * ```c
* JsonObjectIter iter;
* const gchar *member_name;
* JsonNode *member_node;
@@ -1176,9 +1174,9 @@ json_object_iter_next (JsonObjectIter *iter,
* {
* // Do something with @member_name and @member_node.
* }
- * ]|
+ * ```
*
- * See also: json_object_iter_init()
+ * See also: [method Json ObjectIter init]
*
* Since: 1.6
*/
@@ -1206,19 +1204,20 @@ json_object_iter_init_ordered (JsonObjectIter *iter,
* @member_node: (out callee-allocates) (transfer none) (optional): return
* location for the member value, or %NULL to ignore
*
- * Advance @iter and retrieve the next member in the object. 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.
+ * Advances @iter and retrieves the next member in the object.
+ *
+ * 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
- * which the members were added to the #JsonObject. The iterator is invalidated
- * if its #JsonObject is modified during iteration.
+ * which the members were added to the `JsonObject`. The iterator is invalidated
+ * if its `JsonObject` is modified during iteration.
*
- * You must use this function with a #JsonObjectIter initialized with
- * json_object_iter_init_ordered(); using this function with an iterator initialized
- * with json_object_iter_init() yields undefined behavior.
+ * You must use this function with an iterator initialized with
+ * [method@Json.ObjectIter.init_ordered]; using this function with an iterator
+ * initialized with [method Json ObjectIter init] yields undefined behavior.
*
- * See also: json_object_iter_next()
+ * See also: [method Json ObjectIter next]
*
* Returns: %TRUE if @member_name and @member_node are valid; %FALSE if the end
* of the object has been reached
diff --git a/json-glib/json-parser.c b/json-glib/json-parser.c
index 94a2358..c5ea47b 100644
--- a/json-glib/json-parser.c
+++ b/json-glib/json-parser.c
@@ -25,8 +25,7 @@
*/
/**
- * SECTION:json-parser
- * @short_description: Parse JSON data streams
+ * JsonParser:
*
* #JsonParser provides an object for parsing a JSON data stream, either
* inside a file or inside a static buffer.
@@ -199,7 +198,9 @@ json_parser_class_init (JsonParserClass *klass)
* JsonParser:immutable:
*
* Whether the #JsonNode tree built by the #JsonParser should be immutable
- * when created. Making the output immutable on creation avoids the expense
+ * when created.
+ *
+ * Making the output immutable on creation avoids the expense
* of traversing it to make it immutable later.
*
* Since: 1.2
@@ -263,8 +264,9 @@ json_parser_class_init (JsonParserClass *klass)
* @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.
+ * has successfully parsed a single member of a #JsonObject.
+ *
+ * The object and member are passed to the signal handlers.
*/
parser_signals[OBJECT_MEMBER] =
g_signal_new ("object-member",
@@ -312,8 +314,9 @@ json_parser_class_init (JsonParserClass *klass)
* @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. The
- * array and element index are passed to the signal handlers.
+ * has successfully parsed a single element of a #JsonArray.
+ *
+ * The array and element index are passed to the signal handlers.
*/
parser_signals[ARRAY_ELEMENT] =
g_signal_new ("array-element",
@@ -942,12 +945,12 @@ json_scanner_create (JsonParser *parser)
/**
* json_parser_new:
*
- * Creates a new #JsonParser instance. 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.
+ * Creates a new JSON parser.
*
- * Return value: the newly created #JsonParser. Use g_object_unref()
- * to release all the memory it allocates.
+ * 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
*/
JsonParser *
json_parser_new (void)
@@ -1097,16 +1100,17 @@ json_parser_load (JsonParser *parser,
* json_parser_load_from_file:
* @parser: a #JsonParser
* @filename: the path for the file to parse
- * @error: return location for a #GError, or %NULL
+ * @error: return location for a #GError
*
- * Loads a JSON stream from the content of @filename and parses it. See
- * json_parser_load_from_data().
+ * Loads a JSON stream from the content of @filename and parses it.
*
* If the file is large or shared between processes,
- * json_parser_load_from_mapped_file() may be a more efficient way to load it.
+ * [method@Json.Parser.load_from_mapped_file] may be a more efficient
+ * way to load it.
+ *
+ * See also: [method@Json.Parser.load_from_data]
*
* Return value: %TRUE if the file was successfully loaded and parsed.
- * In case of error, @error is set accordingly and %FALSE is returned
*/
gboolean
json_parser_load_from_file (JsonParser *parser,
@@ -1151,16 +1155,17 @@ json_parser_load_from_file (JsonParser *parser,
* json_parser_load_from_mapped_file:
* @parser: a #JsonParser
* @filename: the path for the file to parse
- * @error: return location for a #GError, or %NULL
+ * @error: return location for a #GError
*
- * Loads a JSON stream from the content of @filename and parses it. Unlike
- * json_parser_load_from_file(), @filename will be memory mapped as read-only
- * and parsed. @filename will be unmapped before this function returns.
+ * Loads a JSON stream from the content of `filename` and parses it.
*
- * If mapping or reading the file fails, a %G_FILE_ERROR will be returned.
+ * Unlike [method@Json.Parser.load_from_file], `filename` will be memory
+ * mapped as read-only and parsed. `filename` will be unmapped before this
+ * function returns.
+ *
+ * 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.
- * In case of error, @error is set accordingly and %FALSE is returned
* Since: 1.6
*/
gboolean
@@ -1207,14 +1212,14 @@ json_parser_load_from_mapped_file (JsonParser *parser,
* @parser: a #JsonParser
* @data: the buffer to parse
* @length: the length of the buffer, or -1
- * @error: return location for a #GError, or %NULL
+ * @error: return location for a #GError
+ *
+ * Loads a JSON stream from a buffer and parses it.
*
- * Loads a JSON stream from a buffer and parses it. You can call this function
- * multiple times with the same #JsonParser object, but the contents of the
- * parser will be destroyed each time.
+ * 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. In case
- * of error, @error is set accordingly and %FALSE is returned
+ * Return value: %TRUE if the buffer was succesfully parsed
*/
gboolean
json_parser_load_from_data (JsonParser *parser,
@@ -1252,13 +1257,13 @@ json_parser_load_from_data (JsonParser *parser,
* json_parser_get_root:
* @parser: a #JsonParser
*
- * Retrieves the top level node from the parsed JSON stream. If the parser input
- * was an empty string, or if parsing failed, this will be %NULL. It will also
- * be %NULL if it has been stolen using json_parser_steal_root().
+ * Retrieves the top level node from the parsed JSON stream.
*
- * Return value: (transfer none) (nullable): the root #JsonNode . The returned
- * node is owned by the #JsonParser and should never be modified
- * or freed.
+ * If the parser input was an empty string, or if parsing failed, the root
+ * 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.
*/
JsonNode *
json_parser_get_root (JsonParser *parser)
@@ -1277,10 +1282,12 @@ json_parser_get_root (JsonParser *parser)
* json_parser_steal_root:
* @parser: a #JsonParser
*
- * Steals the top level node from the parsed JSON stream. This will be %NULL
- * in the same situations as json_parser_get_root() returns %NULL.
+ * Steals the top level node from the parsed JSON stream.
+ *
+ * This will be `NULL` in the same situations as [method@Json.Parser.get_root]
+ * return `NULL`.
*
- * Returns: (transfer full) (nullable): the top level #JsonNode
+ * Returns: (transfer full) (nullable): the root node
*
* Since: 1.4
*/
@@ -1306,7 +1313,7 @@ json_parser_steal_root (JsonParser *parser)
* Retrieves the line currently parsed, starting from 1.
*
* This function has defined behaviour only while parsing; calling this
- * function from outside the signal handlers emitted by #JsonParser will
+ * function from outside the signal handlers emitted by the parser will
* yield 0.
*
* Return value: the currently parsed line, or 0.
@@ -1330,7 +1337,7 @@ json_parser_get_current_line (JsonParser *parser)
* from 0.
*
* This function has defined behaviour only while parsing; calling this
- * function from outside the signal handlers emitted by #JsonParser will
+ * function from outside the signal handlers emitted by the parser will
* yield 0.
*
* Return value: the position in the current line, or 0.
@@ -1349,26 +1356,22 @@ json_parser_get_current_pos (JsonParser *parser)
/**
* json_parser_has_assignment:
* @parser: a #JsonParser
- * @variable_name: (out) (allow-none) (transfer none): Return location for the variable
- * name, or %NULL
+ * @variable_name: (out) (optional) (transfer none): the variable name
*
* A JSON data stream might sometimes contain an assignment, like:
*
- * |[
- * var _json_data = { "member_name" : [ ...
- * ]|
+ * ```
+ * var _json_data = { "member_name" : [ ...
+ * ```
*
* even though it would technically constitute a violation of the RFC.
*
- * #JsonParser will ignore the left hand identifier and parse the right
- * hand value of the assignment. #JsonParser will record, though, the
+ * `JsonParser` will ignore the left hand identifier and parse the right
+ * hand value of the assignment. `JsonParser` will record, though, the
* existence of the assignment in the data stream and the variable name
* used.
*
- * Return value: %TRUE if there was an assignment, %FALSE otherwise. If
- * @variable_name is not %NULL it will be set to the name of the variable
- * used in the assignment. The string is owned by #JsonParser and should
- * never be modified or freed.
+ * Return value: %TRUE if there was an assignment, %FALSE otherwise
*
* Since: 0.4
*/
@@ -1394,8 +1397,8 @@ json_parser_has_assignment (JsonParser *parser,
* json_parser_load_from_stream:
* @parser: a #JsonParser
* @stream: an open #GInputStream
- * @cancellable: (allow-none): a #GCancellable, or %NULL
- * @error: the return location for a #GError, or %NULL
+ * @cancellable: (nullable): a #GCancellable
+ * @error: the return location for a #GError
*
* Loads the contents of an input stream and parses them.
*
@@ -1485,14 +1488,13 @@ load_data_free (gpointer data_)
* json_parser_load_from_stream_finish:
* @parser: a #JsonParser
* @result: a #GAsyncResult
- * @error: the return location for a #GError or %NULL
+ * @error: the return location for a #GError
*
* Finishes an asynchronous stream loading started with
- * json_parser_load_from_stream_async().
+ * [method@Json.Parser.load_from_stream_async].
*
* Return value: %TRUE if the content of the stream was successfully retrieves
- * and parsed, and %FALSE otherwise. In case of error, the #GError will be
- * filled accordingly.
+ * and parsed, and %FALSE otherwise
*
* Since: 0.12
*/
@@ -1562,17 +1564,17 @@ read_from_stream (GTask *task,
* json_parser_load_from_stream_async:
* @parser: a #JsonParser
* @stream: a #GInputStream
- * @cancellable: (allow-none): a #GCancellable, or %NULL
- * @callback: a #GAsyncReadyCallback to call when the request is satisfied
+ * @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.
*
- * For more details, see json_parser_load_from_stream() which is the
+ * For more details, see [method@Json.Parser.load_from_stream], which is the
* synchronous version of this call.
*
* When the operation is finished, @callback will be called. You should
- * then call json_parser_load_from_stream_finish() to get the result
+ * then call [method@Json.Parser.load_from_stream_finish] to get the result
* of the operation.
*
* Since: 0.12
diff --git a/json-glib/json-parser.h b/json-glib/json-parser.h
index 91fde66..44efb29 100644
--- a/json-glib/json-parser.h
+++ b/json-glib/json-parser.h
@@ -73,12 +73,6 @@ typedef enum {
JSON_PARSER_ERROR_UNKNOWN
} JsonParserError;
-/**
- * JsonParser:
- *
- * JSON data streams parser. The contents of the #JsonParser structure are
- * private and should only be accessed via the provided API.
- */
struct _JsonParser
{
/*< private >*/
@@ -99,7 +93,7 @@ struct _JsonParser
* @parse_end: class handler for the JsonParser::parse-end signal
* @error: class handler for the JsonParser::error signal
*
- * #JsonParser class.
+ * The class structure for the JsonParser type.
*/
struct _JsonParserClass
{
diff --git a/json-glib/json-path.c b/json-glib/json-path.c
index fe6e7b1..8151376 100644
--- a/json-glib/json-path.c
+++ b/json-glib/json-path.c
@@ -21,45 +21,44 @@
*/
/**
- * SECTION:json-path
- * @Title: JsonPath
- * @short_description: JSONPath implementation
+ * JsonPath:
*
- * #JsonPath is a simple class implementing the JSONPath syntax for extracting
- * data out of a JSON tree. While the semantics of the JSONPath expressions are
- * heavily borrowed by the XPath specification for XML, the syntax follows the
- * ECMAScript origins of JSON.
+ * `JsonPath` is a simple class implementing the JSONPath syntax for extracting
+ * data out of a JSON tree.
+ *
+ * While the semantics of the JSONPath expressions are heavily borrowed by the
+ * 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
- * expression using json_path_compile() before being able to match it to a
- * JSON tree; the same #JsonPath instance can be used to match multiple JSON
+ * 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
* trees. It it also possible to compile a new JSONPath expression using the
* same #JsonPath instance; the previous expression will be discarded only if
* the compilation of the new expression is successful.
*
- * The simple convenience function json_path_query() can be used for one-off
- * matching.
+ * The simple convenience function [func Json Path.query] can be used for
+ * one-off matching.
*
- * ## Syntax of the JSONPath expressions ##
+ * ## Syntax of the JSONPath expressions
*
* A JSONPath expression is composed by path indices and operators.
* Each path index can either be a member name or an element index inside
- * a JSON tree. A JSONPath expression must start with the '$' operator; each
+ * a JSON tree. A JSONPath expression must start with the `$` operator; each
* path index is separated using either the dot notation or the bracket
* notation, e.g.:
*
- * |[<!-- language="plain" -->
- * // dot notation
- * $.store.book[0].title
+ * ```
+ * // dot notation
+ * $.store.book[0].title
*
- * // bracket notation
- * $['store']['book'][0]['title']
- * ]|
+ * // bracket notation
+ * $['store']['book'][0]['title']
+ * ```
*
* The available operators are:
*
- * * Root node
- * The `$` character represents the root node of the JSON tree, and
+ * * The `$` character represents the root node of the JSON tree, and
* matches the entire document.
*
* * Child nodes can either be matched using `.` or `[]`. For instance,
@@ -95,62 +94,63 @@
* [JSONPath website](http://goessner.net/articles/JsonPath/).
*
* ## Example of JSONPath matches
+ *
* The following example shows some of the results of using #JsonPath
* on a JSON tree. We use the following JSON description of a bookstore:
*
- * |[<!-- language="plain" -->
- * { "store": {
- * "book": [
- * { "category": "reference", "author": "Nigel Rees",
- * "title": "Sayings of the Century", "price": "8.95" },
- * { "category": "fiction", "author": "Evelyn Waugh",
- * "title": "Sword of Honour", "price": "12.99" },
- * { "category": "fiction", "author": "Herman Melville",
- * "title": "Moby Dick", "isbn": "0-553-21311-3",
- * "price": "8.99" },
- * { "category": "fiction", "author": "J. R. R. Tolkien",
- * "title": "The Lord of the Rings", "isbn": "0-395-19395-8",
- * "price": "22.99" }
- * ],
- * "bicycle": { "color": "red", "price": "19.95" }
- * }
+ * ```json
+ * { "store": {
+ * "book": [
+ * { "category": "reference", "author": "Nigel Rees",
+ * "title": "Sayings of the Century", "price": "8.95" },
+ * { "category": "fiction", "author": "Evelyn Waugh",
+ * "title": "Sword of Honour", "price": "12.99" },
+ * { "category": "fiction", "author": "Herman Melville",
+ * "title": "Moby Dick", "isbn": "0-553-21311-3",
+ * "price": "8.99" },
+ * { "category": "fiction", "author": "J. R. R. Tolkien",
+ * "title": "The Lord of the Rings", "isbn": "0-395-19395-8",
+ * "price": "22.99" }
+ * ],
+ * "bicycle": { "color": "red", "price": "19.95" }
* }
- * ]|
+ * }
+ * ```
*
* We can parse the JSON using #JsonParser:
*
- * |[<!-- language="C" -->
+ * ```c
* JsonParser *parser = json_parser_new ();
* json_parser_load_from_data (parser, json_data, -1, NULL);
- * ]|
+ * ```
*
* If we run the following code:
*
- * |[<!-- language="C" -->
+ * ```c
* JsonNode *result;
* JsonPath *path = json_path_new ();
* json_path_compile (path, "$.store..author", NULL);
* result = json_path_match (path, json_parser_get_root (parser));
- * ]|
+ * ```
*
* The result #JsonNode will contain an array with all values of the
* author member of the objects in the JSON tree. If we use a
* #JsonGenerator to convert the #JsonNode to a string and print it:
*
- * |[<!-- language="C" -->
+ * ```c
* JsonGenerator *generator = json_generator_new ();
* json_generator_set_root (generator, result);
* char *str = json_generator_to_data (generator, NULL);
* g_print ("Results: %s\n", str);
- * ]|
+ * ```
*
* The output will be:
*
- * |[<!-- language="plain" -->
- * ["Nigel Rees","Evelyn Waugh","Herman Melville","J. R. R. Tolkien"]
- * ]|
+ * ```json
+ * ["Nigel Rees","Evelyn Waugh","Herman Melville","J. R. R. Tolkien"]
+ * ```
*
- * #JsonPath is available since JSON-GLib 0.14
+ * Since: 0.14
*/
#include "config.h"
diff --git a/json-glib/json-path.h b/json-glib/json-path.h
index 3c3ddf0..9d47a2e 100644
--- a/json-glib/json-path.h
+++ b/json-glib/json-path.h
@@ -56,24 +56,7 @@ typedef enum {
JSON_PATH_ERROR_INVALID_QUERY
} JsonPathError;
-/**
- * JsonPath:
- *
- * The `JsonPath` structure is an opaque object whose members cannot be
- * directly accessed except through the provided API.
- *
- * Since: 0.14
- */
typedef struct _JsonPath JsonPath;
-
-/**
- * JsonPathClass:
- *
- * The `JsonPathClass` structure is an opaque object class whose members
- * cannot be directly accessed.
- *
- * Since: 0.14
- */
typedef struct _JsonPathClass JsonPathClass;
JSON_AVAILABLE_IN_1_0
diff --git a/json-glib/json-reader.c b/json-glib/json-reader.c
index f371dd9..f550b00 100644
--- a/json-glib/json-reader.c
+++ b/json-glib/json-reader.c
@@ -21,18 +21,17 @@
*/
/**
- * SECTION:json-reader
- * @Title: JsonReader
- * @short_description: A cursor-based parser
+ * JsonReader:
*
- * #JsonReader provides a simple, cursor-based API for parsing a JSON DOM. It
- * is similar, in spirit, to the XML Reader API.
+ * `JsonReader` provides a simple, cursor-based API for parsing a JSON DOM.
*
- * In case of error, #JsonReader will be set in an error state; all subsequent
+ * It is similar, in spirit, to the XML Reader API.
+ *
+ * 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.:
*
- * |[
+ * ```c
* // ask for the 7th element; if the element does not exist, the
* // reader will be put in an error state
* json_reader_read_element (reader, 6);
@@ -43,12 +42,12 @@
*
* // this function resets the error state if any was set
* json_reader_end_element (reader);
- * ]|
+ * ```
*
* If you want to detect the error state as soon as possible, you can use
- * json_reader_get_error():
+ * [method@Json.Reader.get_error]:
*
- * |[<!-- language="C" -->
+ * ```c
* // like the example above, but in this case we print out the
* // error immediately
* if (!json_reader_read_element (reader, 6))
@@ -56,9 +55,9 @@
* const GError *error = json_reader_get_error (reader);
* g_print ("Unable to read the element: %s", error->message);
* }
- * ]|
+ * ```
*
- * #JsonReader is available since JSON-GLib 0.12.
+ * Since: 0.12
*/
#include "config.h"
@@ -198,8 +197,9 @@ json_reader_init (JsonReader *self)
* json_reader_new:
* @node: (allow-none): a #JsonNode, or %NULL
*
- * Creates a new #JsonReader. You can use this object to read the contents of
- * the JSON tree starting from @node
+ * Creates a new #JsonReader.
+ *
+ * You can use this object to read the contents of the JSON tree starting from @node.
*
* Return value: the newly created #JsonReader. Use g_object_unref() to
* release the allocated resources when done
@@ -234,10 +234,11 @@ json_reader_unset_error (JsonReader *reader)
/**
* json_reader_set_root:
* @reader: a #JsonReader
- * @root: (allow-none): a #JsonNode
+ * @root: (nullable): a #JsonNode
+ *
+ * Sets the root #JsonNode to be read by @reader.
*
- * Sets the root #JsonNode to be read by @reader. The @reader will take
- * a copy of @root
+ * The @reader will take a copy of @root
*
* If another #JsonNode is currently set as root, it will be replaced.
*
@@ -282,7 +283,7 @@ json_reader_set_root (JsonReader *reader,
* @Varargs: list of arguments for the @error_fmt string
*
* Sets the error state of @reader using the given error code
- * and string
+ * and string.
*
* Return value: %FALSE, to be used to return immediately from
* the caller function
@@ -319,7 +320,7 @@ json_reader_set_error (JsonReader *reader,
* @reader: a #JsonReader
*
* Retrieves the #GError currently set on @reader, if the #JsonReader
- * is in error state
+ * is in error state.
*
* Return value: (nullable) (transfer none): the pointer to the error, or %NULL
*
@@ -337,7 +338,7 @@ json_reader_get_error (JsonReader *reader)
* json_reader_is_array:
* @reader: a #JsonReader
*
- * 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
@@ -360,7 +361,7 @@ json_reader_is_array (JsonReader *reader)
* json_reader_is_object:
* @reader: a #JsonReader
*
- * 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
@@ -383,7 +384,7 @@ json_reader_is_object (JsonReader *reader)
* json_reader_is_value:
* @reader: a #JsonReader
*
- * 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
@@ -414,15 +415,15 @@ json_reader_is_value (JsonReader *reader)
* You can use the json_reader_get_value* family of functions to retrieve
* the value of the element; for instance:
*
- * |[
+ * ```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.:
*
- * |[
+ * ```c
* json_reader_read_element (reader, 1);
* str_value = json_reader_get_string_value (reader);
* json_reader_end_element (reader);
@@ -430,7 +431,7 @@ json_reader_is_value (JsonReader *reader)
* json_reader_read_element (reader, 2);
* str_value = json_reader_get_string_value (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
@@ -438,7 +439,7 @@ json_reader_is_value (JsonReader *reader)
* that if used conditionally, json_reader_end_element() must be called on both
* code paths:
*
- * |[
+ * ```c
* if (!json_reader_read_element (reader, 1))
* {
* json_reader_end_element (reader);
@@ -448,7 +449,7 @@ json_reader_is_value (JsonReader *reader)
*
* str_value = json_reader_get_string_value (reader);
* json_reader_end_element (reader);
- * ]|
+ * ```c
*
* Return value: %TRUE on success, and %FALSE otherwise
*
@@ -527,9 +528,9 @@ json_reader_read_element (JsonReader *reader,
* @reader: a #JsonReader
*
* Moves the cursor back to the previous node after being positioned
- * inside an array
+ * inside an array.
*
- * This function resets the error state of @reader, if any was set
+ * This function resets the error state of @reader, if any was set.
*
* Since: 0.12
*/
@@ -563,7 +564,7 @@ json_reader_end_element (JsonReader *reader)
* @reader: a #JsonReader
*
* Counts the elements of the current position, if @reader is
- * positioned on an array
+ * positioned on an array.
*
* Return value: the number of elements, or -1. In case of failure
* the #JsonReader is set in an error state
@@ -608,15 +609,15 @@ json_reader_count_elements (JsonReader *reader)
* You can use the json_reader_get_value* family of 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.:
*
- * |[
+ * ```c
* json_reader_read_member (reader, "author");
* author = json_reader_get_string_value (reader);
* json_reader_end_member (reader);
@@ -624,14 +625,14 @@ json_reader_count_elements (JsonReader *reader)
* json_reader_read_member (reader, "title");
* title = json_reader_get_string_value (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:
*
- * |[
+ * ```c
* if (!json_reader_read_member (reader, "title"))
* {
* json_reader_end_member (reader);
@@ -641,7 +642,7 @@ json_reader_count_elements (JsonReader *reader)
*
* str_value = json_reader_get_string_value (reader);
* json_reader_end_member (reader);
- * ]|
+ * ```
*
* Return value: %TRUE on success, and %FALSE otherwise
*
@@ -688,9 +689,9 @@ json_reader_read_member (JsonReader *reader,
* @reader: a #JsonReader
*
* Moves the cursor back to the previous node after being positioned
- * inside an object
+ * inside an object.
*
- * This function resets the error state of @reader, if any was set
+ * This function resets the error state of @reader, if any was set.
*
* Since: 0.12
*/
@@ -777,7 +778,7 @@ json_reader_list_members (JsonReader *reader)
* @reader: a #JsonReader
*
* Counts the members of the current position, if @reader is
- * positioned on an object
+ * positioned on an object.
*
* Return value: the number of members, or -1. In case of failure
* the #JsonReader is set in an error state
@@ -815,11 +816,9 @@ json_reader_count_members (JsonReader *reader)
* json_reader_get_value:
* @reader: a #JsonReader
*
- * Retrieves the #JsonNode of the current position of @reader
+ * Retrieves the #JsonNode of the current position of @reader.
*
- * Return value: (nullable) (transfer none): a #JsonNode, or %NULL. The
- * returned node is owned by the #JsonReader and it should not be
- * modified or freed directly
+ * Return value: (nullable) (transfer none): the current value node
*
* Since: 0.12
*/
@@ -855,7 +854,7 @@ json_reader_get_value (JsonReader *reader)
* json_reader_get_int_value:
* @reader: a #JsonReader
*
- * Retrieves the integer value of the current position of @reader
+ * Retrieves the integer value of the current position of @reader.
*
* Return value: the integer value
*
@@ -893,7 +892,7 @@ json_reader_get_int_value (JsonReader *reader)
* json_reader_get_double_value:
* @reader: a #JsonReader
*
- * Retrieves the floating point value of the current position of @reader
+ * Retrieves the floating point value of the current position of @reader.
*
* Return value: the floating point value
*
@@ -931,7 +930,7 @@ json_reader_get_double_value (JsonReader *reader)
* json_reader_get_string_value:
* @reader: a #JsonReader
*
- * Retrieves the string value of the current position of @reader
+ * Retrieves the string value of the current position of @reader.
*
* Return value: the string value
*
@@ -976,7 +975,7 @@ json_reader_get_string_value (JsonReader *reader)
* json_reader_get_boolean_value:
* @reader: a #JsonReader
*
- * Retrieves the boolean value of the current position of @reader
+ * Retrieves the boolean value of the current position of @reader.
*
* Return value: the boolean value
*
@@ -1014,9 +1013,9 @@ json_reader_get_boolean_value (JsonReader *reader)
* json_reader_get_null_value:
* @reader: a #JsonReader
*
- * Checks whether the value of the current position of @reader is 'null'
+ * Checks whether the value of the current position of @reader is `null`.
*
- * Return value: %TRUE if 'null' is set, and %FALSE otherwise
+ * Return value: %TRUE if `null` is set, and %FALSE otherwise
*
* Since: 0.12
*/
@@ -1042,7 +1041,7 @@ json_reader_get_null_value (JsonReader *reader)
*
* Retrieves the name of the current member.
*
- * Return value: (nullable) (transfer none): the name of the member, or %NULL
+ * 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 786ed7b..9376a5d 100644
--- a/json-glib/json-reader.h
+++ b/json-glib/json-reader.h
@@ -77,14 +77,6 @@ typedef enum {
JSON_READER_ERROR_INVALID_TYPE
} JsonReaderError;
-/**
- * JsonReader:
- *
- * The `JsonReader` structure contains only private data and should
- * be accessed using the provided API
- *
- * Since: 0.12
- */
struct _JsonReader
{
/*< private >*/
@@ -93,13 +85,6 @@ struct _JsonReader
JsonReaderPrivate *priv;
};
-/**
- * JsonReaderClass:
- *
- * The `JsonReaderClass` structure contains only private data
- *
- * Since: 0.12
- */
struct _JsonReaderClass
{
/*< private >*/
diff --git a/json-glib/json-serializable.c b/json-glib/json-serializable.c
index 8eb64d7..3cdd757 100644
--- a/json-glib/json-serializable.c
+++ b/json-glib/json-serializable.c
@@ -18,13 +18,14 @@
*/
/**
- * SECTION:json-serializable
- * @short_description: Interface for serialize and deserialize special GObjects
+ * JsonSerializable:
*
- * #JsonSerializable is an interface for #GObject classes that
- * allows controlling how the class is going to be serialized
- * or deserialized by json_construct_gobject() and
- * json_serialize_gobject() respectively.
+ * `JsonSerializable` is an interface for controlling the serialization
+ * and deserialization of `GObject` classes.
+ *
+ * Implementing this interface allows controlling how the class is going
+ * to be serialized or deserialized by [func@Json.construct_gobject] and
+ * [func@Json.serialize_gobject], respectively.
*/
#include "config.h"
@@ -78,6 +79,7 @@ json_serializable_serialize_property (JsonSerializable *serializable,
* property contained inside @property_node into @value.
*
* 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
@@ -190,15 +192,14 @@ G_DEFINE_INTERFACE (JsonSerializable, json_serializable, G_TYPE_OBJECT);
* @value: the value of the property
* @pspec: a #GParamSpec
*
- * Calls the default implementation of the #JsonSerializable
- * #JsonSerializableIface.serialize_property() virtual function.
+ * Calls the default implementation of the [vfunc@Json.Serializable.serialize_property]
+ * virtual function.
*
- * This function can be used inside a custom implementation
- * of the #JsonSerializableIface.serialize_property() virtual
- * function in lieu of calling the default implementation
- * through g_type_default_interface_peek():
+ * This function can be used inside a custom implementation of the
+ * `serialize_property()` virtual function in lieu of calling the
+ * default implementation through `g_type_default_interface_peek()`:
*
- * |[<!-- language="C" -->
+ * ```c
* JsonSerializable *iface;
* JsonNode *node;
*
@@ -206,7 +207,7 @@ G_DEFINE_INTERFACE (JsonSerializable, json_serializable, G_TYPE_OBJECT);
* 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.
@@ -237,13 +238,14 @@ json_serializable_default_serialize_property (JsonSerializable *serializable,
* @pspec: a #GParamSpec
* @property_node: a #JsonNode containing the serialized property
*
- * Calls the default implementation of the #JsonSerializable
- * deserialize_property() virtual function
+ * Calls the default implementation of the [vfunc@Json.Serializable.deserialize_property]
+ * virtual function.
*
- * This function can be used inside a custom implementation
- * of the deserialize_property() virtual function in lieu of:
+ * This function can be used inside a custom implementation of the
+ * `deserialize_property()` virtual function in lieu of calling the
+ * default implementation through `g_type_default_interface_peek()`:
*
- * |[<!-- language="C" -->
+ * ```c
* JsonSerializable *iface;
* gboolean res;
*
@@ -252,7 +254,7 @@ json_serializable_default_serialize_property (JsonSerializable *serializable,
* value,
* pspec,
* property_node);
- * ]|
+ * ```
*
* Return value: %TRUE if the property was successfully deserialized.
*
@@ -282,7 +284,7 @@ json_serializable_default_deserialize_property (JsonSerializable *serializable,
* @serializable: a #JsonSerializable
* @name: the name of the property
*
- * Calls the #JsonSerializableIface.find_property() implementation on
+ * Calls the [vfunc@Json.Serializable.find_property] implementation on
* the @serializable instance. *
*
* Return value: (nullable) (transfer none): the #GParamSpec for the property
@@ -306,11 +308,11 @@ json_serializable_find_property (JsonSerializable *serializable,
* @n_pspecs: (out): return location for the length of the array
* of #GParamSpec returned by the function
*
- * Calls the #JsonSerializableIface.list_properties() implementation on
+ * Calls the [vfunc@Json.Serializable.list_properties] implementation on
* the @serializable instance.
*
* Return value: (array length=n_pspecs) (transfer container): an array
- * of #GParamSpec. Use g_free() to free the array when done.
+ * of #GParamSpec
*
* Since: 0.14
*/
@@ -329,7 +331,7 @@ json_serializable_list_properties (JsonSerializable *serializable,
* @pspec: a #GParamSpec
* @value: the property value to set
*
- * Calls the #JsonSerializableIface.set_property() implementation
+ * Calls the [vfunc@Json.Serializable.set_property] implementation
* on the @serializable instance.
*
* Since: 0.14
@@ -354,7 +356,7 @@ json_serializable_set_property (JsonSerializable *serializable,
* @pspec: a #GParamSpec
* @value: (out): return location for the property value
*
- * Calls the #JsonSerializableIface.get_property() implementation
+ * Calls the [vfunc@Json.Serializable.get_property] implementation
* on the @serializable instance.
*
* Since: 0.14
diff --git a/json-glib/json-types.h b/json-glib/json-types.h
index 5e16d4d..52f3346 100644
--- a/json-glib/json-types.h
+++ b/json-glib/json-types.h
@@ -96,29 +96,8 @@ G_BEGIN_DECLS
#define JSON_TYPE_OBJECT (json_object_get_type ())
#define JSON_TYPE_ARRAY (json_array_get_type ())
-/**
- * JsonNode:
- *
- * A generic container of JSON data types. The contents of the #JsonNode
- * structure are private and should only be accessed via the provided
- * functions and never directly.
- */
typedef struct _JsonNode JsonNode;
-
-/**
- * JsonObject:
- *
- * A JSON object type. The contents of the #JsonObject structure are private
- * and should only be accessed by the provided API
- */
typedef struct _JsonObject JsonObject;
-
-/**
- * JsonArray:
- *
- * A JSON array type. The contents of the #JsonArray structure are private
- * and should only be accessed by the provided API
- */
typedef struct _JsonArray JsonArray;
/**
@@ -144,9 +123,12 @@ typedef enum {
* @member_node: a #JsonNode containing the @member_name value
* @user_data: data passed to the function
*
- * The function to be passed to json_object_foreach_member(). You
- * should not add or remove members to and from @object within
- * this function. It is safe to change the value of @member_node.
+ * The function to be passed to [method@Json.Object.foreach_member].
+ *
+ * You should not add or remove members to and from @object within
+ * this function.
+ *
+ * It is safe to change the value of @member_node.
*
* Since: 0.8
*/
@@ -162,9 +144,12 @@ typedef void (* JsonObjectForeach) (JsonObject *object,
* @element_node: a #JsonNode containing the value at @index_
* @user_data: data passed to the function
*
- * The function to be passed to json_array_foreach_element(). You
- * should not add or remove elements to and from @array within
- * this function. It is safe to change the value of @element_node.
+ * The function to be passed to [method@Json.Array.foreach_element].
+ *
+ * You should not add or remove elements to and from @array within
+ * this function.
+ *
+ * It is safe to change the value of @element_node.
*
* Since: 0.8
*/
@@ -423,12 +408,15 @@ gboolean json_object_equal (gconstpointer a,
/**
* JsonObjectIter:
*
- * An iterator used to iterate over the members of a #JsonObject. This must
- * be allocated on the stack and initialised using json_object_iter_init().
- * The order in which members are returned by the iterator is undefined. The
- * iterator is invalidated if its #JsonObject is modified during iteration.
+ * An iterator object used to iterate over the members of a #JsonObject.
+ *
+ * `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
+ * iteration.
*
- * All the fields in the #JsonObjectIter structure are private and should
+ * All the fields in the `JsonObjectIter` structure are private and should
* never be accessed directly.
*
* Since: 1.2
diff --git a/json-glib/json-utils.c b/json-glib/json-utils.c
index 5fc8496..dda4602 100644
--- a/json-glib/json-utils.c
+++ b/json-glib/json-utils.c
@@ -17,14 +17,6 @@
* License along with this library. If not, see <http://www.gnu.org/licenses/>.
*/
-/**
- * SECTION:json-utils
- * @Title: Utility API
- * @Short_description: Various utility functions
- *
- * Various utility functions.
- */
-
#include "config.h"
#include "json-utils.h"
@@ -37,12 +29,14 @@
* @error: return location for a #GError
*
* Parses the string in @str and returns a #JsonNode representing
- * the JSON tree. If @str is empty, this function will return %NULL.
+ * the JSON tree.
+ *
+ * If @str is empty, this function will return %NULL.
*
* In case of parsing error, this function returns %NULL and sets
* @error appropriately.
*
- * Returns: (transfer full) (nullable): a #JsonNode, or %NULL
+ * Returns: (transfer full) (nullable): the root node of the JSON tree
*
* Since: 1.2
*/
@@ -77,7 +71,7 @@ json_from_string (const char *str,
* Generates a stringified JSON representation of the contents of
* the passed @node.
*
- * Returns: (transfer full): the string representation of the #JsonNode
+ * Returns: (transfer full): the string representation of the node
*
* Since: 1.2
*/
diff --git a/json-glib/json-version.h.in b/json-glib/json-version.h.in
index d18caa2..8fe3a5b 100644
--- a/json-glib/json-version.h.in
+++ b/json-glib/json-version.h.in
@@ -28,14 +28,6 @@
#error "Only <json-glib/json-glib.h> can be included directly."
#endif
-/**
- * SECTION:json-version
- * @short_description: JSON-GLib version checking
- *
- * JSON-GLib provides macros to check the version of the library
- * at compile-time
- */
-
/**
* JSON_MAJOR_VERSION:
*
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
