Issue #850: fill in & adjust the "@returns" docs for several functions.

json_object.h

@@ -175,7 +175,7 @@ JSON_EXPORT struct json_object *json_object_get(struct json_object *obj);
  * NULL may be passed, in which case this is a no-op.
  *
  * @param obj the json_object instance
- * @returns 1 if the object was freed.
+ * @returns 1 if the object was freed, 0 if only the refcount was decremented
  * @see json_object_get()
  */
 JSON_EXPORT int json_object_put(struct json_object *obj);
@@ -191,6 +191,7 @@ JSON_EXPORT int json_object_put(struct json_object *obj);
      json_type_object,
      json_type_array,
      json_type_string
+ * @returns 1 if the object is of the specified type, 0 otherwise
  */
 JSON_EXPORT int json_object_is_type(const struct json_object *obj, enum json_type type);
 
@@ -458,9 +459,9 @@ JSON_EXPORT struct json_object *json_object_object_get(const struct json_object
  *              associated with the given field name.
  *
  *              It is safe to pass a NULL value.
- * @returns whether or not the key exists
+ * @returns 1 if the key exists, 0 otherwise
  */
-JSON_EXPORT json_bool json_object_object_get_ex(const struct json_object *obj, const char *key,
+JSON_EXPORT int json_object_object_get_ex(const struct json_object *obj, const char *key,
                                                 struct json_object **value);
 
 /** Delete the given json_object field
@@ -560,7 +561,7 @@ JSON_EXPORT struct array_list *json_object_get_array(const struct json_object *o
 
 /** Get the length of a json_object of type json_type_array
  * @param obj the json_object instance
- * @returns an int
+ * @returns the length of the array
  */
 JSON_EXPORT size_t json_object_array_length(const struct json_object *obj);
 
@@ -1042,7 +1043,7 @@ JSON_EXPORT struct json_object *json_object_new_null(void);
  *
  * @param obj1 the first json_object instance
  * @param obj2 the second json_object instance
- * @returns whether both objects are equal or not
+ * @returns 1 if both objects are equal, 0 otherwise
  */
 JSON_EXPORT int json_object_equal(struct json_object *obj1, struct json_object *obj2);