[json-glib: 1/2] json-node: Clarify documentation regarding programmer errors

[Emmanuele Bassi <ebassi src gnome org>]

commit acb22e9e18c2a5bf93ed82af4d8194341acfdc01
Author: Philip Withnall <withnall endlessm com>
Date:   Fri Dec 15 15:41:20 2017 +0000

    json-node: Clarify documentation regarding programmer errors
    
    Despite my efforts in commit 011c1e424b7 (parts of which were completely
    incorrect), the JsonNode documentation still wasn’t particularly helpful
    about differentiating between methods which return NULL if the JsonNode
    is not of the right type, and methods which emit a critical warning.
    
    Try and improve that across the board, hopefully without saying
    blatantly incorrect things this time.
    
    Signed-off-by: Philip Withnall <withnall endlessm com>

 json-glib/json-node.c | 52 ++++++++++++++++++++++++++++++++-------------------
 1 file changed, 33 insertions(+), 19 deletions(-)
---
diff --git a/json-glib/json-node.c b/json-glib/json-node.c
index 5e158c5..a6898d9 100644
--- a/json-glib/json-node.c
+++ b/json-glib/json-node.c
@@ -502,7 +502,8 @@ json_node_unref (JsonNode *node)
  *
  * If @object is %NULL, the node’s existing object is cleared.
  *
- * It is an error to call this on an immutable node.
+ * It is an error to call this on an immutable node, or on a node which is not
+ * an object node.
  */
 void
 json_node_set_object (JsonNode   *node,
@@ -528,7 +529,8 @@ json_node_set_object (JsonNode   *node,
  *
  * Sets @object inside @node. The reference count of @object is not increased.
  *
- * It is an error to call this on an immutable node.
+ * It is an error to call this on an immutable node, or on a node which is not
+ * an object node.
  */
 void
 json_node_take_object (JsonNode   *node,
@@ -552,8 +554,9 @@ json_node_take_object (JsonNode   *node,
  * json_node_get_object:
  * @node: a #JsonNode
  *
- * Retrieves the #JsonObject stored inside a #JsonNode. If the node does not
- * hold an object value, %NULL is returned.
+ * Retrieves the #JsonObject stored inside a #JsonNode. It is a programmer error
+ * to call this on a node which doesn’t hold an object value. Use
+ * %JSON_NODE_HOLDS_OBJECT first.
  *
  * Return value: (transfer none) (nullable): the #JsonObject
  */
@@ -571,8 +574,9 @@ json_node_get_object (JsonNode *node)
  * @node: a #JsonNode
  *
  * Retrieves the #JsonObject inside @node. The reference count of
- * the returned object is increased. If the node does not hold an object value,
- * %NULL is returned.
+ * 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.
  *
  * Return value: (transfer full) (nullable): the #JsonObject
  */
@@ -595,7 +599,8 @@ json_node_dup_object (JsonNode *node)
  *
  * Sets @array inside @node and increases the #JsonArray reference count.
  *
- * It is an error to call this on an immutable node.
+ * It is an error to call this on an immutable node, or on a node which is not
+ * an array node.
  */
 void
 json_node_set_array (JsonNode  *node,
@@ -621,7 +626,8 @@ json_node_set_array (JsonNode  *node,
  *
  * Sets @array into @node without increasing the #JsonArray reference count.
  *
- * It is an error to call this on an immutable node.
+ * It is an error to call this on an immutable node, or a node which is not
+ * an array node.
  */
 void
 json_node_take_array (JsonNode  *node,
@@ -645,8 +651,9 @@ json_node_take_array (JsonNode  *node,
  * json_node_get_array:
  * @node: a #JsonNode
  *
- * Retrieves the #JsonArray stored inside a #JsonNode. If the node does not
- * hold an array value, %NULL is returned.
+ * Retrieves the #JsonArray stored inside a #JsonNode. It is a programmer error
+ * to call this on a node which doesn’t hold an array value. Use
+ * %JSON_NODE_HOLDS_ARRAY first.
  *
  * Return value: (transfer none) (nullable): the #JsonArray
  */
@@ -664,8 +671,9 @@ json_node_get_array (JsonNode *node)
  * @node: a #JsonNode
  *
  * Retrieves the #JsonArray stored inside a #JsonNode and returns it
- * with its reference count increased by one. If the node does not hold an
- * array value, %NULL is returned.
+ * with its reference count increased by one. It is a programmer error
+ * to call this on a node which doesn’t hold an array value. Use
+ * %JSON_NODE_HOLDS_ARRAY first.
  *
  * Return value: (transfer full) (nullable): the #JsonArray with its reference
  *   count increased.
@@ -688,8 +696,9 @@ json_node_dup_array (JsonNode *node)
  * @value: (out caller-allocates): return location for an uninitialized value
  *
  * Retrieves a value from a #JsonNode and copies into @value. When done
- * using it, call g_value_unset() on the #GValue. If the node does not hold a
- * scalar value, @value is not modified.
+ * using it, call g_value_unset() on the #GValue. It is a programmer error
+ * to call this on a node which doesn’t hold a scalar value. Use
+ * %JSON_NODE_HOLDS_VALUE first.
  */
 void
 json_node_get_value (JsonNode *node,
@@ -732,7 +741,8 @@ json_node_get_value (JsonNode *node,
  *
  * Sets @value inside @node. The passed #GValue is copied into the #JsonNode.
  *
- * It is an error to call this on an immutable node.
+ * It is an error to call this on an immutable node, or on a node which is not
+ * a value node.
  */
 void
 json_node_set_value (JsonNode     *node,
@@ -972,7 +982,8 @@ json_node_get_parent (JsonNode *node)
  * Sets @value as the string content of the @node, replacing any existing
  * content.
  *
- * It is an error to call this on an immutable node.
+ * It is an error to call this on an immutable node, or on a node which is not
+ * a value node.
  */
 void
 json_node_set_string (JsonNode    *node,
@@ -1040,7 +1051,8 @@ json_node_dup_string (JsonNode *node)
  * Sets @value as the integer content of the @node, replacing any existing
  * content.
  *
- * It is an error to call this on an immutable node.
+ * It is an error to call this on an immutable node, or on a node which is not
+ * a value node.
  */
 void
 json_node_set_int (JsonNode *node,
@@ -1098,7 +1110,8 @@ json_node_get_int (JsonNode *node)
  * Sets @value as the double content of the @node, replacing any existing
  * content.
  *
- * It is an error to call this on an immutable node.
+ * It is an error to call this on an immutable node, or on a node which is not
+ * a value node.
  */
 void
 json_node_set_double (JsonNode *node,
@@ -1156,7 +1169,8 @@ json_node_get_double (JsonNode *node)
  * Sets @value as the boolean content of the @node, replacing any existing
  * content.
  *
- * It is an error to call this on an immutable node.
+ * It is an error to call this on an immutable node, or on a node which is not
+ * a value node.
  */
 void
 json_node_set_boolean (JsonNode *node,