diff options
Diffstat (limited to 'json-glib/json-reader.c')
| -rw-r--r-- | json-glib/json-reader.c | 101 |
1 files changed, 50 insertions, 51 deletions
diff --git a/json-glib/json-reader.c b/json-glib/json-reader.c index f371dd9..f550b00 100644 --- a/json-glib/json-reader.c +++ b/json-glib/json-reader.c @@ -21,18 +21,17 @@ */ /** - * SECTION:json-reader - * @Title: JsonReader - * @short_description: A cursor-based parser + * JsonReader: * - * #JsonReader provides a simple, cursor-based API for parsing a JSON DOM. It - * is similar, in spirit, to the XML Reader API. + * `JsonReader` provides a simple, cursor-based API for parsing a JSON DOM. * - * In case of error, #JsonReader will be set in an error state; all subsequent + * It is similar, in spirit, to the XML Reader API. + * + * In case of error, `JsonReader` will be set in an error state; all subsequent * calls will simply be ignored until a function that resets the error state is * called, e.g.: * - * |[ + * ```c * // ask for the 7th element; if the element does not exist, the * // reader will be put in an error state * json_reader_read_element (reader, 6); @@ -43,12 +42,12 @@ * * // this function resets the error state if any was set * json_reader_end_element (reader); - * ]| + * ``` * * If you want to detect the error state as soon as possible, you can use - * json_reader_get_error(): + * [method@Json.Reader.get_error]: * - * |[<!-- language="C" --> + * ```c * // like the example above, but in this case we print out the * // error immediately * if (!json_reader_read_element (reader, 6)) @@ -56,9 +55,9 @@ * const GError *error = json_reader_get_error (reader); * g_print ("Unable to read the element: %s", error->message); * } - * ]| + * ``` * - * #JsonReader is available since JSON-GLib 0.12. + * Since: 0.12 */ #include "config.h" @@ -198,8 +197,9 @@ json_reader_init (JsonReader *self) * json_reader_new: * @node: (allow-none): a #JsonNode, or %NULL * - * Creates a new #JsonReader. You can use this object to read the contents of - * the JSON tree starting from @node + * Creates a new #JsonReader. + * + * You can use this object to read the contents of the JSON tree starting from @node. * * Return value: the newly created #JsonReader. Use g_object_unref() to * release the allocated resources when done @@ -234,10 +234,11 @@ json_reader_unset_error (JsonReader *reader) /** * json_reader_set_root: * @reader: a #JsonReader - * @root: (allow-none): a #JsonNode + * @root: (nullable): a #JsonNode + * + * Sets the root #JsonNode to be read by @reader. * - * Sets the root #JsonNode to be read by @reader. The @reader will take - * a copy of @root + * The @reader will take a copy of @root * * If another #JsonNode is currently set as root, it will be replaced. * @@ -282,7 +283,7 @@ json_reader_set_root (JsonReader *reader, * @Varargs: list of arguments for the @error_fmt string * * Sets the error state of @reader using the given error code - * and string + * and string. * * Return value: %FALSE, to be used to return immediately from * the caller function @@ -319,7 +320,7 @@ json_reader_set_error (JsonReader *reader, * @reader: a #JsonReader * * Retrieves the #GError currently set on @reader, if the #JsonReader - * is in error state + * is in error state. * * Return value: (nullable) (transfer none): the pointer to the error, or %NULL * @@ -337,7 +338,7 @@ json_reader_get_error (JsonReader *reader) * json_reader_is_array: * @reader: a #JsonReader * - * Checks whether the @reader is currently on an array + * Checks whether the @reader is currently on an array. * * Return value: %TRUE if the #JsonReader is on an array, and %FALSE * otherwise @@ -360,7 +361,7 @@ json_reader_is_array (JsonReader *reader) * json_reader_is_object: * @reader: a #JsonReader * - * Checks whether the @reader is currently on an object + * Checks whether the @reader is currently on an object. * * Return value: %TRUE if the #JsonReader is on an object, and %FALSE * otherwise @@ -383,7 +384,7 @@ json_reader_is_object (JsonReader *reader) * json_reader_is_value: * @reader: a #JsonReader * - * Checks whether the @reader is currently on a value + * Checks whether the @reader is currently on a value. * * Return value: %TRUE if the #JsonReader is on a value, and %FALSE * otherwise @@ -414,15 +415,15 @@ json_reader_is_value (JsonReader *reader) * You can use the json_reader_get_value* family of functions to retrieve * the value of the element; for instance: * - * |[ + * ```c * json_reader_read_element (reader, 0); * int_value = json_reader_get_int_value (reader); - * ]| + * ``` * * After reading the value, json_reader_end_element() should be called to * reposition the cursor inside the #JsonReader, e.g.: * - * |[ + * ```c * json_reader_read_element (reader, 1); * str_value = json_reader_get_string_value (reader); * json_reader_end_element (reader); @@ -430,7 +431,7 @@ json_reader_is_value (JsonReader *reader) * json_reader_read_element (reader, 2); * str_value = json_reader_get_string_value (reader); * json_reader_end_element (reader); - * ]| + * ``` * * If @reader is not currently on an array or an object, or if the @index_ is * bigger than the size of the array or the object, the #JsonReader will be @@ -438,7 +439,7 @@ json_reader_is_value (JsonReader *reader) * that if used conditionally, json_reader_end_element() must be called on both * code paths: * - * |[ + * ```c * if (!json_reader_read_element (reader, 1)) * { * json_reader_end_element (reader); @@ -448,7 +449,7 @@ json_reader_is_value (JsonReader *reader) * * str_value = json_reader_get_string_value (reader); * json_reader_end_element (reader); - * ]| + * ```c * * Return value: %TRUE on success, and %FALSE otherwise * @@ -527,9 +528,9 @@ json_reader_read_element (JsonReader *reader, * @reader: a #JsonReader * * Moves the cursor back to the previous node after being positioned - * inside an array + * inside an array. * - * This function resets the error state of @reader, if any was set + * This function resets the error state of @reader, if any was set. * * Since: 0.12 */ @@ -563,7 +564,7 @@ json_reader_end_element (JsonReader *reader) * @reader: a #JsonReader * * Counts the elements of the current position, if @reader is - * positioned on an array + * positioned on an array. * * Return value: the number of elements, or -1. In case of failure * the #JsonReader is set in an error state @@ -608,15 +609,15 @@ json_reader_count_elements (JsonReader *reader) * You can use the json_reader_get_value* family of functions to retrieve * the value of the member; for instance: * - * |[ + * ```c * json_reader_read_member (reader, "width"); * width = json_reader_get_int_value (reader); - * ]| + * ``` * * After reading the value, json_reader_end_member() should be called to * reposition the cursor inside the #JsonReader, e.g.: * - * |[ + * ```c * json_reader_read_member (reader, "author"); * author = json_reader_get_string_value (reader); * json_reader_end_member (reader); @@ -624,14 +625,14 @@ json_reader_count_elements (JsonReader *reader) * json_reader_read_member (reader, "title"); * title = json_reader_get_string_value (reader); * json_reader_end_member (reader); - * ]| + * ``` * * If @reader is not currently on an object, or if the @member_name is not * defined in the object, the #JsonReader will be put in an error state until * json_reader_end_member() is called. This means that if used conditionally, * json_reader_end_member() must be called on both code paths: * - * |[ + * ```c * if (!json_reader_read_member (reader, "title")) * { * json_reader_end_member (reader); @@ -641,7 +642,7 @@ json_reader_count_elements (JsonReader *reader) * * str_value = json_reader_get_string_value (reader); * json_reader_end_member (reader); - * ]| + * ``` * * Return value: %TRUE on success, and %FALSE otherwise * @@ -688,9 +689,9 @@ json_reader_read_member (JsonReader *reader, * @reader: a #JsonReader * * Moves the cursor back to the previous node after being positioned - * inside an object + * inside an object. * - * This function resets the error state of @reader, if any was set + * This function resets the error state of @reader, if any was set. * * Since: 0.12 */ @@ -777,7 +778,7 @@ json_reader_list_members (JsonReader *reader) * @reader: a #JsonReader * * Counts the members of the current position, if @reader is - * positioned on an object + * positioned on an object. * * Return value: the number of members, or -1. In case of failure * the #JsonReader is set in an error state @@ -815,11 +816,9 @@ json_reader_count_members (JsonReader *reader) * json_reader_get_value: * @reader: a #JsonReader * - * Retrieves the #JsonNode of the current position of @reader + * Retrieves the #JsonNode of the current position of @reader. * - * Return value: (nullable) (transfer none): a #JsonNode, or %NULL. The - * returned node is owned by the #JsonReader and it should not be - * modified or freed directly + * Return value: (nullable) (transfer none): the current value node * * Since: 0.12 */ @@ -855,7 +854,7 @@ json_reader_get_value (JsonReader *reader) * json_reader_get_int_value: * @reader: a #JsonReader * - * Retrieves the integer value of the current position of @reader + * Retrieves the integer value of the current position of @reader. * * Return value: the integer value * @@ -893,7 +892,7 @@ json_reader_get_int_value (JsonReader *reader) * json_reader_get_double_value: * @reader: a #JsonReader * - * Retrieves the floating point value of the current position of @reader + * Retrieves the floating point value of the current position of @reader. * * Return value: the floating point value * @@ -931,7 +930,7 @@ json_reader_get_double_value (JsonReader *reader) * json_reader_get_string_value: * @reader: a #JsonReader * - * Retrieves the string value of the current position of @reader + * Retrieves the string value of the current position of @reader. * * Return value: the string value * @@ -976,7 +975,7 @@ json_reader_get_string_value (JsonReader *reader) * json_reader_get_boolean_value: * @reader: a #JsonReader * - * Retrieves the boolean value of the current position of @reader + * Retrieves the boolean value of the current position of @reader. * * Return value: the boolean value * @@ -1014,9 +1013,9 @@ json_reader_get_boolean_value (JsonReader *reader) * json_reader_get_null_value: * @reader: a #JsonReader * - * Checks whether the value of the current position of @reader is 'null' + * Checks whether the value of the current position of @reader is `null`. * - * Return value: %TRUE if 'null' is set, and %FALSE otherwise + * Return value: %TRUE if `null` is set, and %FALSE otherwise * * Since: 0.12 */ @@ -1042,7 +1041,7 @@ json_reader_get_null_value (JsonReader *reader) * * Retrieves the name of the current member. * - * Return value: (nullable) (transfer none): the name of the member, or %NULL + * Return value: (nullable) (transfer none): the name of the member * * Since: 0.14 */ |