diff options
| -rw-r--r-- | json-glib/json-array.c | 259 | ||||
| -rw-r--r-- | json-glib/json-builder.c | 61 | ||||
| -rw-r--r-- | json-glib/json-builder.h | 15 | ||||
| -rw-r--r-- | json-glib/json-gboxed.c | 63 | ||||
| -rw-r--r-- | json-glib/json-generator.c | 85 | ||||
| -rw-r--r-- | json-glib/json-generator.h | 11 | ||||
| -rw-r--r-- | json-glib/json-gobject.c | 61 | ||||
| -rw-r--r-- | json-glib/json-gvariant.c | 109 | ||||
| -rw-r--r-- | json-glib/json-node.c | 198 | ||||
| -rw-r--r-- | json-glib/json-object.c | 239 | ||||
| -rw-r--r-- | json-glib/json-parser.c | 124 | ||||
| -rw-r--r-- | json-glib/json-parser.h | 8 | ||||
| -rw-r--r-- | json-glib/json-path.c | 96 | ||||
| -rw-r--r-- | json-glib/json-path.h | 17 | ||||
| -rw-r--r-- | json-glib/json-reader.c | 101 | ||||
| -rw-r--r-- | json-glib/json-reader.h | 15 | ||||
| -rw-r--r-- | json-glib/json-serializable.c | 52 | ||||
| -rw-r--r-- | json-glib/json-types.h | 52 | ||||
| -rw-r--r-- | json-glib/json-utils.c | 16 | ||||
| -rw-r--r-- | 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 @@ -29,14 +29,6 @@ #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: * * Json major version component (e.g. 1 if %JSON_VERSION is 1.2.3) |