Update Introspection annotations

• Fix the transfer rules for JsonNode, JsonObject and JsonArray
getters.

• Annotate the methods returning lists

4 files changed, 33 insertions, 30 deletions

diff --git a/json-glib/json-array.c b/json-glib/json-array.c
index 16f36a4..5149aad 100644
--- a/json-glib/json-array.c
+++ b/json-glib/json-array.c
@@ -157,10 +157,10 @@ json_array_unref (JsonArray *array)
  *
  * Gets the elements of a #JsonArray as a list of #JsonNode<!-- -->s.
  *
- * Return value: a #GList containing the elements of the array. The
- *   contents of the list are owned by the array and should never be
- *   modified or freed. Use g_list_free() on the returned list when
- *   done using it
+ * Return value: (element-type JsonNode) (transfer container): a #GList
+ *   containing the elements of the array. The contents of the list are
+ *   owned by the array and should never be modified or freed. Use
+ *   g_list_free() on the returned list when done using it
  */
 GList *
 json_array_get_elements (JsonArray *array)
@@ -186,8 +186,8 @@ json_array_get_elements (JsonArray *array)
  * Retrieves a copy of the #JsonNode containing the value of the
  * element at @index_ inside a #JsonArray
  *
- * Return value: a copy of the #JsonNode at the requested index.
- *   Use json_node_free() when done.
+ * Return value: (transfer full): a copy of the #JsonNode at the requested
+ *   index. Use json_node_free() when done.
  *
  * Since: 0.6
  */
@@ -386,7 +386,7 @@ json_array_get_null_element (JsonArray *array,
  *
  * See also: json_array_get_element(), json_node_get_array()
  *
- * Return value: the array
+ * Return value: (transfer none): the array
  *
  * Since: 0.8
  */
@@ -416,7 +416,7 @@ json_array_get_array_element (JsonArray *array,
  *
  * See also: json_array_get_element(), json_node_get_object()
  *
- * Return value: the object
+ * Return value: (transfer none): the object
  *
  * Since: 0.8
  */
@@ -669,7 +669,7 @@ json_array_remove_element (JsonArray *array,
  * json_array_foreach_element:
  * @array: a #JsonArray
  * @func: the function to be called on each element
- * @data: data to be passed to the function
+ * @data: (allow-none): data to be passed to the function
  *
  * Iterates over all elements of @array and calls @func on
  * each one of them.
diff --git a/json-glib/json-node.c b/json-glib/json-node.c
index a21d587..6a79c4c 100644
--- a/json-glib/json-node.c
+++ b/json-glib/json-node.c
@@ -125,7 +125,7 @@ json_node_new (JsonNodeType type)
  * Copies @node. If the node contains complex data types then the reference
  * count of the objects is increased.
  *
- * Return value: the copied #JsonNode
+ * Return value: (transfer full): the copied #JsonNode
  */
 JsonNode *
 json_node_copy (JsonNode *node)
@@ -220,7 +220,7 @@ json_node_take_object (JsonNode   *node,
  *
  * Retrieves the #JsonObject stored inside a #JsonNode
  *
- * Return value: the #JsonObject
+ * Return value: (transfer none): the #JsonObject
  */
 JsonObject *
 json_node_get_object (JsonNode *node)
@@ -238,7 +238,7 @@ json_node_get_object (JsonNode *node)
  * Retrieves the #JsonObject inside @node. The reference count of
  * the returned object is increased.
  *
- * Return value: the #JsonObject
+ * Return value: (transfer full): the #JsonObject
  */
 JsonObject *
 json_node_dup_object (JsonNode *node)
@@ -305,7 +305,7 @@ json_node_take_array (JsonNode  *node,
  *
  * Retrieves the #JsonArray stored inside a #JsonNode
  *
- * Return value: the #JsonArray
+ * Return value: (transfer none): the #JsonArray
  */
 JsonArray *
 json_node_get_array (JsonNode *node)
@@ -323,7 +323,8 @@ json_node_get_array (JsonNode *node)
  * Retrieves the #JsonArray stored inside a #JsonNode and returns it
  * with its reference count increased by one.
  *
- * Return value: the #JsonArray with its reference count increased.
+ * Return value: (transfer full): the #JsonArray with its reference
+ *   count increased.
  */
 JsonArray *
 json_node_dup_array (JsonNode *node)
@@ -597,8 +598,8 @@ json_node_get_string (JsonNode *node)
  *
  * Gets a copy of the string value stored inside a #JsonNode
  *
- * Return value: a newly allocated string containing a copy of
- *   the #JsonNode contents
+ * Return value: (transfer full): a newly allocated string containing a copy
+ *   of the #JsonNode contents. Use g_free() to free the allocated resources
  */
 gchar *
 json_node_dup_string (JsonNode *node)
diff --git a/json-glib/json-object.c b/json-glib/json-object.c
index 9a339a1..b81254e 100644
--- a/json-glib/json-object.c
+++ b/json-glib/json-object.c
@@ -409,10 +409,11 @@ json_object_set_object_member (JsonObject  *object,
  * Retrieves all the names of the members of a #JsonObject. You can
  * obtain the value for each member using json_object_get_member().
  *
- * Return value: a #GList of member names. 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 utf8) (transfer container): a #GList
+ *   of member names. 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.
  */
 GList *
 json_object_get_members (JsonObject *object)
@@ -432,10 +433,10 @@ json_object_get_members (JsonObject *object)
  *
  * Retrieves all the values of the members of a #JsonObject.
  *
- * Return value: a #GList of #JsonNode<!-- -->s. 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): a #GList of
+ *   #JsonNode<!-- -->s. 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.
  */
 GList *
 json_object_get_values (JsonObject *object)
@@ -459,8 +460,8 @@ json_object_get_values (JsonObject *object)
  * Retrieves a copy of the #JsonNode containing the value of @member_name
  * inside a #JsonObject
  *
- * Return value: a copy of the node for the requested object member
- *   or %NULL. Use json_node_free() when done.
+ * Return value: (transfer full) a copy of the node for the requested
+ *   object member or %NULL. Use json_node_free() when done.
  *
  * Since: 0.6
  */
@@ -667,7 +668,7 @@ json_object_get_string_member (JsonObject  *object,
  *
  * See also: json_object_get_member()
  *
- * Return value: the array inside the object's member
+ * Return value: (transfer none): the array inside the object's member
  *
  * Since: 0.8
  */
@@ -697,7 +698,7 @@ json_object_get_array_member (JsonObject  *object,
  *
  * See also: json_object_get_member()
  *
- * Return value: the object inside the object's member
+ * Return value: (transfer none): the object inside the object's member
  *
  * Since: 0.8
  */
diff --git a/json-glib/json-parser.c b/json-glib/json-parser.c
index fe6cfe6..46feaf7 100644
--- a/json-glib/json-parser.c
+++ b/json-glib/json-parser.c
@@ -1124,8 +1124,9 @@ json_parser_load_from_data (JsonParser   *parser,
  *
  * Retrieves the top level node from the parsed JSON stream.
  *
- * Return value: the root #JsonNode . The returned node is owned by
- *   the #JsonParser and should never be modified or freed.
+ * Return value: (transfer none): the root #JsonNode . The returned
+ *   node is owned by the #JsonParser and should never be modified
+ *   or freed.
  */
 JsonNode *
 json_parser_get_root (JsonParser *parser)