diff options
author | Emmanuele Bassi <ebassi@gnome.org> | 2021-06-08 19:22:18 +0100 |
---|---|---|
committer | Emmanuele Bassi <ebassi@gnome.org> | 2021-06-08 19:22:18 +0100 |
commit | cb354fce58c06b6cfc18c685cc6ba1b3e1649ade (patch) | |
tree | 90e80a4ef44a699d2313cfb717c5ca0b03020ed5 /json-glib | |
parent | 9e681fa47331b526327f707ec690618584c66c67 (diff) | |
download | json-glib-cb354fce58c06b6cfc18c685cc6ba1b3e1649ade.tar.gz |
Update the documentation for the GBoxed API
Diffstat (limited to 'json-glib')
-rw-r--r-- | json-glib/json-gboxed.c | 52 | ||||
-rw-r--r-- | json-glib/json-gobject.h | 52 |
2 files changed, 74 insertions, 30 deletions
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-gobject.h b/json-glib/json-gobject.h index 47ac125..0d3a129 100644 --- a/json-glib/json-gobject.h +++ b/json-glib/json-gobject.h @@ -129,7 +129,26 @@ gboolean json_serializable_default_deserialize_property (JsonSerializable *seri * JsonBoxedSerializeFunc: * @boxed: a #GBoxed * - * Serializes the passed #GBoxed and stores it inside a #JsonNode + * 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); + * + * return json_builder_get_root (builder); + * } + * ``` * * Return value: the newly created #JsonNode * @@ -141,7 +160,36 @@ typedef JsonNode *(* JsonBoxedSerializeFunc) (gconstpointer boxed); * JsonBoxedDeserializeFunc: * @node: a #JsonNode * - * Deserializes the contents of the passed #JsonNode into a #GBoxed + * 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); + * } + * + * // my_point_new() is defined elsewhere + * return my_point_new (x, y); + * } + * ``` * * Return value: the newly created boxed type * |