[json-glib/doc-fixes: 2/17] Update the documentation for the GBoxed API

[Emmanuele Bassi <ebassi src gnome org>]

commit cb354fce58c06b6cfc18c685cc6ba1b3e1649ade
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Tue Jun 8 19:22:18 2021 +0100

    Update the documentation for the GBoxed API

 json-glib/json-gboxed.c  | 52 ++++++++++++++++++++++--------------------------
 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
  *