docs: Initial, rough port away from gtk-doc

Drop `SECTION` blurbs.

Use gi-docgen syntax for internal links.

Use summary lines for gi-docgen indices.

Use Markdown syntax for code fragments.

1 files changed, 119 insertions, 120 deletions

diff --git a/json-glib/json-object.c b/json-glib/json-object.c
index 8555eb9..3c4c376 100644
--- a/json-glib/json-object.c
+++ b/json-glib/json-object.c
@@ -29,22 +29,26 @@
 #include "json-types-private.h"
 
 /**
- * SECTION:json-object
- * @short_description: a JSON object representation
+ * JsonObject:
  *
- * #JsonObject is the representation of the object type inside JSON. It
- * contains #JsonNodes, which may contain fundamental types, arrays or other
- * objects; each node inside an object, or "member", is accessed using a
- * unique string, or "name".
+ * `JsonObject` is the representation of the object type inside JSON.
  *
- * Since objects can be expensive, they are reference counted. You can control
- * the lifetime of a #JsonObject using json_object_ref() and json_object_unref().
+ * A `JsonObject` contains [struct@Json.Node] "members", which may contain
+ * fundamental types, arrays or other objects; each member of an object is
+ * accessed using a unique string, or "name".
+ *
+ * Since objects can be arbitrarily big, copying them can be expensive; for
+ * this reason they are reference counted. You can control the lifetime of
+ * a `JsonObject` using [method@Json.Object.ref] and [method@Json.Object.unref].
+ *
+ * To add or overwrite a member with a given name, use [method@Json.Object.set_member].
+ *
+ * To extract a member with a given name, use [method@Json.Object.get_member].
+ *
+ * To retrieve the list of members, use [method@Json.Object.get_members].
  *
- * To add or overwrite a member with a given name, use json_object_set_member().
- * To extract a member with a given name, use json_object_get_member().
- * To retrieve the list of members, use json_object_get_members().
  * To retrieve the size of the object (that is, the number of members it has),
- * use json_object_get_size().
+ * use [method@Json.Object.get_size].
  */
 
 G_DEFINE_BOXED_TYPE (JsonObject, json_object, json_object_ref, json_object_unref);
@@ -52,9 +56,9 @@ G_DEFINE_BOXED_TYPE (JsonObject, json_object, json_object_ref, json_object_unref
 /**
  * json_object_new: (constructor)
  * 
- * Creates a new #JsonObject, an JSON object type representation.
+ * Creates a new object.
  *
- * Return value: (transfer full): the newly created #JsonObject
+ * Return value: (transfer full): the newly created object
  */
 JsonObject *
 json_object_new (void)
@@ -75,11 +79,11 @@ json_object_new (void)
 
 /**
  * json_object_ref:
- * @object: a #JsonObject
+ * @object: an object
  *
- * Increase by one the reference count of a #JsonObject.
+ * Acquires a reference on the given object.
  *
- * Return value: (transfer none): the passed #JsonObject, with the reference count
+ * Return value: (transfer none): the given object, with the reference count
  *   increased by one.
  */
 JsonObject *
@@ -95,11 +99,12 @@ json_object_ref (JsonObject *object)
 
 /**
  * json_object_unref:
- * @object: a #JsonObject
+ * @object: an object
  *
- * Decreases by one the reference count of a #JsonObject. If the
- * reference count reaches zero, the object is destroyed and all
- * its allocated resources are freed.
+ * Releases a reference on the given object.
+ *
+ * If the reference count reaches zero, the object is destroyed and
+ * all its resources are freed.
  */
 void
 json_object_unref (JsonObject *object)
@@ -119,12 +124,13 @@ json_object_unref (JsonObject *object)
 
 /**
  * json_object_seal:
- * @object: a #JsonObject
+ * @object: an object
  *
- * Seals the #JsonObject, making it immutable to further changes. This will
- * recursively seal all members of the object too.
+ * Seals the object, making it immutable to further changes.
  *
- * If the @object is already immutable, this is a no-op.
+ * This function will recursively seal all members of the object too.
+ *
+ * If the object is already immutable, this is a no-op.
  *
  * Since: 1.2
  */
@@ -152,13 +158,13 @@ json_object_seal (JsonObject *object)
 
 /**
  * json_object_is_immutable:
- * @object: a #JsonObject
+ * @object: an object
  *
- * Check whether the given @object has been marked as immutable by calling
- * json_object_seal() on it.
+ * Checks whether the given object has been marked as immutable by calling
+ * [method@Json.Object.seal] on it.
  *
  * Since: 1.2
- * Returns: %TRUE if the @object is immutable
+ * Returns: `TRUE` if the object is immutable
  */
 gboolean
 json_object_is_immutable (JsonObject *object)
@@ -199,17 +205,16 @@ object_set_member_internal (JsonObject  *object,
 
 /**
  * json_object_add_member:
- * @object: a #JsonObject
+ * @object: an object
  * @member_name: the name of the member
  * @node: (transfer full): the value of the member
  *
- * Adds a member named @member_name and containing @node into a #JsonObject.
- * The object will take ownership of the #JsonNode.
+ * Adds a new member for the given name and value into an object.
  *
- * This function will return if the @object already contains a member
- * @member_name.
+ * This function will return if the object already contains a member
+ * with the same name.
  *
- * Deprecated: 0.8: Use json_object_set_member() instead
+ * Deprecated: 0.8: Use [method@Json.Object.set_member] instead
  */
 void
 json_object_add_member (JsonObject  *object,
@@ -233,15 +238,17 @@ json_object_add_member (JsonObject  *object,
 
 /**
  * json_object_set_member:
- * @object: a #JsonObject
+ * @object: an object
  * @member_name: the name of the member
  * @node: (transfer full): the value of the member
  *
- * Sets @node as the value of @member_name inside @object.
+ * Sets the value of a member inside an object.
  *
- * If @object already contains a member called @member_name then
- * the member's current value is overwritten. Otherwise, a new
- * member is added to @object.
+ * If the object does not have a member with the given name, a new member
+ * is created.
+ *
+ * If the object already has a member with the given name, the current
+ * value is overwritten with the new.
  *
  * Since: 0.8
  */
@@ -269,14 +276,13 @@ set_member:
 
 /**
  * json_object_set_int_member:
- * @object: a #JsonObject
+ * @object: an object
  * @member_name: the name of the member
  * @value: the value of the member
  *
- * Convenience function for setting an integer @value of
- * @member_name inside @object.
+ * Convenience function for setting an object member with an integer value.
  *
- * See also: json_object_set_member()
+ * See also: [method@Json.Object.set_member], [method@Json.Node.init_int]
  *
  * Since: 0.8
  */
@@ -293,14 +299,13 @@ json_object_set_int_member (JsonObject  *object,
 
 /**
  * json_object_set_double_member:
- * @object: a #JsonObject
+ * @object: an object
  * @member_name: the name of the member
  * @value: the value of the member
  *
- * Convenience function for setting a floating point @value
- * of @member_name inside @object.
+ * Convenience function for setting an object member with a floating point value.
  *
- * See also: json_object_set_member()
+ * See also: [method@Json.Object.set_member], [method@Json.Node.init_double]
  *
  * Since: 0.8
  */
@@ -317,14 +322,13 @@ json_object_set_double_member (JsonObject  *object,
 
 /**
  * json_object_set_boolean_member:
- * @object: a #JsonObject
+ * @object: an object
  * @member_name: the name of the member
  * @value: the value of the member
  *
- * Convenience function for setting a boolean @value of
- * @member_name inside @object.
+ * Convenience function for setting an object member with a boolean value.
  *
- * See also: json_object_set_member()
+ * See also: [method@Json.Object.set_member], [method@Json.Node.init_boolean]
  *
  * Since: 0.8
  */
@@ -341,14 +345,13 @@ json_object_set_boolean_member (JsonObject  *object,
 
 /**
  * json_object_set_string_member:
- * @object: a #JsonObject
+ * @object: an object
  * @member_name: the name of the member
  * @value: the value of the member
  *
- * Convenience function for setting a string @value of
- * @member_name inside @object.
+ * Convenience function for setting an object member with a string value.
  *
- * See also: json_object_set_member()
+ * See also: [method@Json.Object.set_member], [method@Json.Node.init_string]
  *
  * Since: 0.8
  */
@@ -374,13 +377,12 @@ json_object_set_string_member (JsonObject  *object,
 
 /**
  * json_object_set_null_member:
- * @object: a #JsonObject
+ * @object: an object
  * @member_name: the name of the member
  *
- * Convenience function for setting a null @value of
- * @member_name inside @object.
+ * Convenience function for setting an object member with a `null` value.
  *
- * See also: json_object_set_member()
+ * See also: [method@Json.Object.set_member], [method@Json.Node.init_null]
  *
  * Since: 0.8
  */
@@ -396,16 +398,13 @@ json_object_set_null_member (JsonObject  *object,
 
 /**
  * json_object_set_array_member:
- * @object: a #JsonObject
+ * @object: an bject
  * @member_name: the name of the member
  * @value: (transfer full): the value of the member
  *
- * Convenience function for setting an array @value of
- * @member_name inside @object.
- *
- * The @object will take ownership of the passed #JsonArray
+ * Convenience function for setting an object member with an array value.
  *
- * See also: json_object_set_member()
+ * See also: [method@Json.Object.set_member], [method@Json.Node.take_array]
  *
  * Since: 0.8
  */
@@ -438,12 +437,9 @@ json_object_set_array_member (JsonObject  *object,
  * @member_name: the name of the member
  * @value: (transfer full): the value of the member
  *
- * Convenience function for setting an object @value of
- * @member_name inside @object.
+ * Convenience function for setting an object member with an object value.
  *
- * The @object will take ownership of the passed #JsonObject
- *
- * See also: json_object_set_member()
+ * See also: [method@Json.Object.set_member], [method@Json.Node.take_object]
  *
  * Since: 0.8
  */
@@ -472,16 +468,15 @@ json_object_set_object_member (JsonObject  *object,
 
 /**
  * json_object_get_members:
- * @object: a #JsonObject
+ * @object: an object
  *
- * Retrieves all the names of the members of a #JsonObject. You can
- * obtain the value for each member using json_object_get_member().
+ * Retrieves all the names of the members of an object.
  *
- * Return value: (element-type utf8) (transfer container) (nullable): a
- *   #GList of member names, or %NULL. The content of the list is owned
- *   by the #JsonObject and should never be modified or freed. When you
- *   have finished using the returned list, use g_list_free() to free
- *   the resources it has allocated.
+ * You can obtain the value for each member by iterating the returned list
+ * and calling [method@Json.Object.get_member].
+ *
+ * Return value: (element-type utf8) (transfer container) (nullable): the
+ *   member names of the object
  */
 GList *
 json_object_get_members (JsonObject *object)
@@ -502,15 +497,12 @@ json_object_get_members_internal (JsonObject *object)
 
 /**
  * json_object_get_values:
- * @object: a #JsonObject
+ * @object: an object
  *
- * Retrieves all the values of the members of a #JsonObject.
+ * Retrieves all the values of the members of an object.
  *
- * Return value: (element-type JsonNode) (transfer container) (nullable): a
- *   #GList of #JsonNodes, or %NULL. The content of the list is owned by the
- *   #JsonObject and should never be modified or freed. When you have finished
- *   using the returned list, use g_list_free() to free the resources it has
- *   allocated.
+ * Return value: (element-type JsonNode) (transfer container) (nullable): the
+ *   member values of the object
  */
 GList *
 json_object_get_values (JsonObject *object)
@@ -528,14 +520,13 @@ json_object_get_values (JsonObject *object)
 
 /**
  * json_object_dup_member:
- * @object: a #JsonObject
+ * @object: an object
  * @member_name: the name of the JSON object member to access
  *
- * Retrieves a copy of the #JsonNode containing the value of @member_name
- * inside a #JsonObject
+ * Retrieves a copy of the value of the given member inside an object.
  *
- * Return value: (transfer full) (nullable): a copy of the node for the
- *   requested object member or %NULL. Use json_node_unref() when done.
+ * Return value: (transfer full) (nullable): a copy of the value for the
+ *   requested object member
  *
  * Since: 0.6
  */
@@ -564,14 +555,13 @@ object_get_member_internal (JsonObject  *object,
 
 /**
  * json_object_get_member:
- * @object: a #JsonObject
+ * @object: an object
  * @member_name: the name of the JSON object member to access
  *
- * Retrieves the #JsonNode containing the value of @member_name inside
- * a #JsonObject.
+ * Retrieves the value of the given member inside an object.
  *
- * Return value: (transfer none) (nullable): a pointer to the node for the
- *   requested object member, or %NULL if it does not exist.
+ * Return value: (transfer none) (nullable): the value for the
+ *   requested object member
  */
 JsonNode *
 json_object_get_member (JsonObject  *object,
@@ -1087,9 +1077,9 @@ json_object_equal (gconstpointer  a,
  * @iter: an uninitialised #JsonObjectIter
  * @object: the #JsonObject to iterate over
  *
- * Initialise the @iter and associate it with @object.
+ * Initialises the @iter and associate it with @object.
  *
- * |[<!-- language="C" -->
+ * ```c
  * JsonObjectIter iter;
  * const gchar *member_name;
  * JsonNode *member_node;
@@ -1099,7 +1089,12 @@ json_object_equal (gconstpointer  a,
  *   {
  *     // Do something with @member_name and @member_node.
  *   }
- * ]|
+ * ```
+ *
+ * The iterator initialized with this function will iterate the
+ * members of the object in an undefined order.
+ *
+ * See also: [method@Json.ObjectIter.init_ordered]
  *
  * Since: 1.2
  */
@@ -1125,21 +1120,24 @@ json_object_iter_init (JsonObjectIter  *iter,
  * @member_node: (out callee-allocates) (transfer none) (optional): return
  *    location for the member value, or %NULL to ignore
  *
- * Advance @iter and retrieve the next member in the object. If the end of the
- * object is reached, %FALSE is returned and @member_name and @member_node are
- * set to invalid values. After that point, the @iter is invalid.
+ * Advances @iter and retrieves the next member in the object.
+ *
+ * If the end of the object is reached, %FALSE is returned and @member_name
+ * and @member_node are set to invalid values. After that point, the @iter
+ * is invalid.
  *
  * The order in which members are returned by the iterator is undefined. The
  * iterator is invalidated if its #JsonObject is modified during iteration.
  *
- * You must use this function with a #JsonObjectIter initialized with
- * json_object_iter_init(); using this function with an iterator initialized
- * with json_object_iter_init_ordered() yields undefined behavior.
+ * You must use this function with an iterator initialized with
+ * [method@Json.ObjectIter.init]; using this function with an iterator
+ * initialized with [method@Json.ObjectIter.init_ordered] yields undefined
+ * behavior.
  *
- * See also: json_object_iter_next_ordered()
+ * See also: [method@Json.ObjectIter.next_ordered]
  *
  * Returns: %TRUE if @member_name and @member_node are valid; %FALSE if the end
- *    of the object has been reached
+ *   of the object has been reached
  *
  * Since: 1.2
  */
@@ -1164,9 +1162,9 @@ json_object_iter_next (JsonObjectIter  *iter,
  * @iter: an uninitialised #JsonObjectIter
  * @object: the #JsonObject to iterate over
  *
- * Initialise the @iter and associate it with @object.
+ * Initialises the @iter and associate it with @object.
  *
- * |[<!-- language="C" -->
+ * ```c
  * JsonObjectIter iter;
  * const gchar *member_name;
  * JsonNode *member_node;
@@ -1176,9 +1174,9 @@ json_object_iter_next (JsonObjectIter  *iter,
  *   {
  *     // Do something with @member_name and @member_node.
  *   }
- * ]|
+ * ```
  *
- * See also: json_object_iter_init()
+ * See also: [method@Json.ObjectIter.init]
  *
  * Since: 1.6
  */
@@ -1206,19 +1204,20 @@ json_object_iter_init_ordered (JsonObjectIter  *iter,
  * @member_node: (out callee-allocates) (transfer none) (optional): return
  *    location for the member value, or %NULL to ignore
  *
- * Advance @iter and retrieve the next member in the object. If the end of the
- * object is reached, %FALSE is returned and @member_name and @member_node are
- * set to invalid values. After that point, the @iter is invalid.
+ * Advances @iter and retrieves the next member in the object.
+ *
+ * If the end of the object is reached, %FALSE is returned and @member_name and
+ * @member_node are set to invalid values. After that point, the @iter is invalid.
  *
  * The order in which members are returned by the iterator is the same order in
- * which the members were added to the #JsonObject. The iterator is invalidated
- * if its #JsonObject is modified during iteration.
+ * which the members were added to the `JsonObject`. The iterator is invalidated
+ * if its `JsonObject` is modified during iteration.
  *
- * You must use this function with a #JsonObjectIter initialized with
- * json_object_iter_init_ordered(); using this function with an iterator initialized
- * with json_object_iter_init() yields undefined behavior.
+ * You must use this function with an iterator initialized with
+ * [method@Json.ObjectIter.init_ordered]; using this function with an iterator
+ * initialized with [method@Json.ObjectIter.init] yields undefined behavior.
  *
- * See also: json_object_iter_next()
+ * See also: [method@Json.ObjectIter.next]
  *
  * Returns: %TRUE if @member_name and @member_node are valid; %FALSE if the end
  *    of the object has been reached