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