From 5bad618fcbe931bdba768a814d871d8f4ecaabd2 Mon Sep 17 00:00:00 2001 From: JinWang An Date: Fri, 17 Dec 2021 14:27:45 +0900 Subject: [PATCH] Imported Upstream version 1.6.4 --- .gitlab-ci.yml | 95 +++++++-- CONTRIBUTING.md | 36 ++++ NEWS | 4 + README.md | 56 +---- doc/json-gboxed.md | 45 ++++ doc/json-glib-docs.xml | 269 ----------------------- doc/json-glib-overrides.txt | 14 -- doc/json-glib-sections.txt | 462 ---------------------------------------- doc/json-glib.toml.in | 67 ++++++ doc/json-gobject.md | 13 ++ doc/json-gvariant.md | 43 ++++ doc/meson.build | 84 +++++--- doc/xml/gtkdocentities.ent.in | 8 - doc/xml/meson.build | 11 - json-glib/json-array.c | 265 ++++++++++++----------- json-glib/json-builder.c | 239 ++++++++++++--------- json-glib/json-builder.h | 15 -- json-glib/json-enum-types.c.in | 2 +- json-glib/json-gboxed.c | 103 +++------ json-glib/json-generator.c | 144 +++++++------ json-glib/json-generator.h | 11 - json-glib/json-gobject.c | 125 +++++------ json-glib/json-gobject.h | 76 +++++-- json-glib/json-gvariant.c | 113 ++++------ json-glib/json-node.c | 457 ++++++++++++++++++++++----------------- json-glib/json-object.c | 354 +++++++++++++++--------------- json-glib/json-parser.c | 284 +++++++++++++----------- json-glib/json-parser.h | 15 +- json-glib/json-path.c | 183 ++++++++-------- json-glib/json-path.h | 23 +- json-glib/json-reader.c | 314 +++++++++++++++------------ json-glib/json-reader.h | 21 +- json-glib/json-serializable.c | 179 ++++++++-------- json-glib/json-types.h | 92 ++++---- json-glib/json-utils.c | 25 +-- json-glib/json-value.c | 10 +- json-glib/json-version-macros.h | 31 ++- json-glib/json-version.h.in | 33 +-- json-glib/meson.build | 3 +- meson.build | 38 +++- po/gl.po | 29 ++- po/ru.po | 186 ++++++++-------- subprojects/gi-docgen.wrap | 6 + subprojects/glib.wrap | 2 +- 44 files changed, 2100 insertions(+), 2485 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 doc/json-gboxed.md delete mode 100644 doc/json-glib-docs.xml delete mode 100644 doc/json-glib-overrides.txt delete mode 100644 doc/json-glib-sections.txt create mode 100644 doc/json-glib.toml.in create mode 100644 doc/json-gobject.md create mode 100644 doc/json-gvariant.md delete mode 100644 doc/xml/gtkdocentities.ent.in delete mode 100644 doc/xml/meson.build create mode 100644 subprojects/gi-docgen.wrap diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index fb3c392..526d222 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -1,37 +1,86 @@ -image: fedora:31 +image: fedora:34 stages: - build + - docs + - deploy -before_script: - - dnf install -y gcc gettext glib2-devel gobject-introspection-devel gtk-doc meson ninja-build redhat-rpm-config - -build-json-glib: - stage: build +.build-default: + before_script: + - dnf install -y ${FEDORA_DEPS} + - pip3 install --user meson==${MESON_VERSION} + - export PATH="$PATH:$HOME/.local/bin" script: - - meson --prefix /usr -Dman=true _build . - - cd _build - - ninja - - meson test - except: - - tags + - meson setup ${MESON_EXTRA_FLAGS} --prefix /usr _build . + - meson compile -C _build + - meson test -C _build + - meson install -C _build artifacts: - when: on_failure + when: always name: "json-glib-${CI_COMMIT_REF_NAME}" paths: - "${CI_PROJECT_DIR}/_build/meson-logs" -dist-json-glib: +fedora-x86_64: + extends: .build-default stage: build - only: - - tags + needs: [] + variables: + FEDORA_DEPS: + gcc + gettext + git + glib2-devel + gobject-introspection-devel + ninja-build + python3 + python3-pip + python3-wheel + redhat-rpm-config + MESON_VERSION: "0.55.3" + MESON_EXTRA_FLAGS: "--buildtype=debug --default-library=both -Dwerror=true -Dglib:werror=false -Dintrospection=enabled" + +reference: + extends: .build-default + stage: docs + needs: [] + variables: + FEDORA_DEPS: + docbook-style-xsl + gcc + gettext + git + glib2-devel + gobject-introspection-devel + graphviz + ninja-build + python3 + python3-jinja2 + python3-markdown + python3-markupsafe + python3-pip + python3-pygments + python3-toml + python3-typogrify + python3-wheel + redhat-rpm-config + libxslt + MESON_VERSION: "0.55.3" + MESON_EXTRA_FLAGS: "-Dgtk_doc=enabled -Dman=true -Dintrospection=enabled" + after_script: + - mkdir _reference + - mv _build/doc/json-glib-1.0/ _reference/ + artifacts: + paths: + - _reference + +pages: + stage: deploy + needs: ['reference'] script: - - meson --prefix /usr --buildtype release -Dman=true -Ddocs=true _build . - - cd _build - - ninja dist - - ninja json-glib-doc - - tar -c -f "json-glib-docs-${CI_COMMIT_TAG}.tar.xz" -C docs html + - mv _reference public artifacts: paths: - - "${CI_PROJECT_DIR}/_build/json-glib-docs-${CI_COMMIT_TAG}.tar.xz" - - "${CI_PROJECT_DIR}/_build/meson-dist/json-glib-*.tar.xz" + - public + only: + - master diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..7bc45a1 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,36 @@ +# Contributing + +If you find a bug in JSON-GLib, please file an issue on the +[Issues page][gitlab-issues]. + +Required information: + + * the version of JSON-GLib + * if it is a development version, the branch of the git repository + * the JSON data that produced the bug (if any) + * a small, self-contained test case, if none of the test units exhibit the + buggy behaviour + * in case of a segmentation fault, a full stack trace with debugging + symbols obtained through gdb is greatly appreaciated + +JSON-GLib is developed mainly inside a GIT repository available at: + + https://gitlab.gnome.org/GNOME/json-glib/ + +You can clone the GIT repository with: + + git clone https://gitlab.gnome.org/GNOME/json-glib.git + +If you want to contribute functionality or bug fixes to JSON-GLib you should +fork the json-glib repository, work on a separate branch, and then open a +merge request on Gitlab: + + https://gitlab.gnome.org/GNOME/json-glib/merge_requests/new + +Please, try to conform to the coding style used by JSON-GLib, which is the same +used by projects like GLib, [GTK][gtk-coding-style], and Clutter. Coding style +conformance is a requirement for upstream acceptance. + +Make sure you always run the test suite when you are fixing bugs. New features +should come with a test unit. Functionality that regress the test suite will be +rejected. diff --git a/NEWS b/NEWS index f0379d9..06778ff 100644 --- a/NEWS +++ b/NEWS @@ -26,6 +26,10 @@ Overview of changes for 1.6 • Fix build reproducibility [!33, Alexander Kanavin] • #26 - Fix parsing of UTF-16 surrogate pairs [James Westman] • #56 - Ignore UTF-8 BOM [Jan-Michael Brummer] +• Discover linker flags on all toolchains +• #58 - Fix memory leak [Richard Hughes] +• Use gi-docgen instead of gtk-doc for generating the API reference +• Build against newer versions of GLib Overview of changes for 1.4 ============================== diff --git a/README.md b/README.md index 9c9d56d..39f07b0 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ GLib is a C library providing common and efficient data types for the C developers. GObject is a library providing a run-time Object Oriented type system for C -developers. GLib and GObject are extensively used by the GTK+ toolkit and by the +developers. GLib and GObject are extensively used by the GTK toolkit and by the [GNOME][gnome] project. For more information, see: @@ -34,9 +34,8 @@ In order to build JSON-GLib you will need: * [ninja](http://ninja-build.org) * [meson](http://mesonbuild.com) * pkg-config - * gtk-doc ≥ 1.13 (optional) - * GLib, GIO ≥ 2.38 - * GObject-Introspection ≥ 1.38 (optional) + * GLib, GIO ≥ 2.54 + * GObject-Introspection ≥ 1.54 (optional) Build and installation -------------------------------------------------------------------------------- @@ -44,50 +43,13 @@ To build JSON-GLib just run: ```sh $ meson _build . - $ ninja -C _build + $ meson -C _build $ meson test -C _build - $ sudo ninja -C _build install + $ meson install -C _build ``` See the [Meson documentation](http://mesonbuild.com) for more information. -Contributing --------------------------------------------------------------------------------- -If you find a bug in JSON-GLib, please file an issue on the -[Issues page][gitlab-issues]. - -Required information: - - * the version of JSON-GLib - * if it is a development version, the branch of the git repository - * the JSON data that produced the bug (if any) - * a small, self-contained test case, if none of the test units exhibit the - buggy behaviour - * in case of a segmentation fault, a full stack trace with debugging - symbols obtained through gdb is greatly appreaciated - -JSON-GLib is developed mainly inside a GIT repository available at: - - https://gitlab.gnome.org/GNOME/json-glib/ - -You can clone the GIT repository with: - - git clone https://gitlab.gnome.org/GNOME/json-glib.git - -If you want to contribute functionality or bug fixes to JSON-GLib you should -fork the json-glib repository, work on a separate branch, and then open a -merge request on Gitlab: - - https://gitlab.gnome.org/GNOME/json-glib/merge_requests/new - -Please, try to conform to the coding style used by JSON-GLib, which is the same -used by projects like GLib, [GTK+][gtk-coding-style], and Clutter. Coding style -conformance is a requirement for upstream acceptance. - -Make sure you always run the test suite when you are fixing bugs. New features -should come with a test unit. Patches that regress the test suite will be -rejected. - Release notes -------------------------------------------------------------------------------- * Prior to JSON-GLib 0.10, a JsonSerializable implementation could @@ -111,9 +73,9 @@ Copyright 2007, 2008 OpenedHand Ltd Copyright 2009, 2010, 2011, 2012 Intel Corp. Copyright 2013 Emmanuele Bassi -[json]: http://www.json.org "JSON" -[glib]: http://www.gtk.org "GTK+" -[json-glib]: https://wiki.gnome.org/Projects/JsonGlib "JSON-GLib wiki" +[json]: https://www.json.org "JSON" +[glib]: https://www.gtk.org "GTK" +[json-glib]: https://gnome.pages.gitlab.gnome.org/json-glib/json-glib-1.0/ [gnome]: https://www.gnome.org "GNOME" [gitlab-issues]: https://gitlab.gnome.org/GNOME/json-glib/issues -[gtk-coding-style]: https://git.gnome.org/browse/gtk+/tree/docs/CODING-STYLE +[gtk-coding-style]: https://gitlab.gnome.org/GNOME/gtk/-/blob/HEAD/docs/CODING-STYLE.md diff --git a/doc/json-gboxed.md b/doc/json-gboxed.md new file mode 100644 index 0000000..40a59ff --- /dev/null +++ b/doc/json-gboxed.md @@ -0,0 +1,45 @@ +Title: Serializing GBoxed Types + +# Serializing GBoxed Types + +GLib's `GBoxed` type is a generic wrapper for arbitrary C structures. + +JSON-GLib allows serialization and deserialization of a boxed type +by registering functions mapping a [enum@Json.NodeType] to a specific +`GType`. + +When registering a boxed type you should also register the +corresponding transformation functions, e.g.: + +```c +GType +my_struct_get_type (void) +{ + static GType boxed_type = 0; + + if (boxed_type == 0) + { + boxed_type = + g_boxed_type_register_static (g_intern_static_string ("MyStruct"), + (GBoxedCopyFunc) my_struct_copy, + (GBoxedFreeFunc) my_struct_free); + + json_boxed_register_serialize_func (boxed_type, JSON_NODE_OBJECT, + my_struct_serialize); + json_boxed_register_deserialize_func (boxed_type, JSON_NODE_OBJECT, + my_struct_deserialize); + } + + return boxed_type; +} +``` + +The serialization function will be invoked by [func@Json.boxed_serialize]: +it will be passed a pointer to the C structure and it must return a +[struct@Json.Node]. The deserialization function will be invoked by +[func@Json.boxed_deserialize]: it will be passed a `JsonNode` for the +declared type and it must return a newly allocated C structure. + +It is possible to check whether a boxed type can be deserialized +from a specific `JsonNodeType`, and whether a boxed can be serialized +and to which specific `JsonNodeType`. diff --git a/doc/json-glib-docs.xml b/doc/json-glib-docs.xml deleted file mode 100644 index 2ea960d..0000000 --- a/doc/json-glib-docs.xml +++ /dev/null @@ -1,269 +0,0 @@ - - - - %gtkdocentities; -]> - - - - &package_name; Reference Manual - - This document is the API reference for for &package_name; &package_version;. - - The latest version of this API reference is also available - online. - - - If you find any issues in this API reference, please report it - using the online - bug reporting tool at bugzilla.gnome.org. - - - - - 2007, 2008 - OpenedHand LTD - - - - 2009, 2010, 2011 - Intel Corporation - - - - - Permission is granted to copy, distribute and/or modify this - document under the terms of the GNU Free - Documentation License, Version 1.1 or any later - version published by the Free Software Foundation with no - Invariant Sections, no Front-Cover Texts, and no Back-Cover - Texts. You may obtain a copy of the GNU Free - Documentation License from the Free Software - Foundation by visiting their Web site or by writing - to: - -
- The Free Software Foundation, Inc., - 59 Temple Place - Suite 330, - Boston, MA 02111-1307, - USA -
- - - - - - - JSON-GLib Overview - - - - - JSON-GLib is a library aimed at providing an API for efficient parsing - and writing of JSON (JavaScript Object Notation) streams, using GLib's - data types and API. - - - - JSON (JavaScript Object Notation) is a lightweight data-interchange - format. More information on the grammar is available on json.org. - - - - - - - - JSON-GLib Reference - - - - - JSON-GLib provides wrappers around the complex data types defined - by the JSON specification. The fundamental types are handled using - the Generic Value container (GValue) provided by GLib. - - - - JSON complex data types are either arrays (a n-tuple of items) - or objects (a mapping between a string and a value); arrays and - objects can contain multiple values, including other arrays and - objects. - - - - - - Data Types - - - - - - - - - Reading and writing - - - - - JSON-GLib provides a parser object to read any valid JSON data - stream and build the data object model in memory. - - - - - - Parser - - - - - - - Generator - - - - - - General Purpose API - - - - - - - JSON-GLib Advanced API - - - - - - - - - - JSON-GLib Additional Reference - - - JSON-GLib Tools - - - - - - Object Hierarchy - - - - - - - Index - - - - - Index of deprecated symbols - - - - - Index of new symbols in 0.4 - - - - - Index of new symbols in 0.6 - - - - - Index of new symbols in 0.8 - - - - - Index of new symbols in 0.10 - - - - - Index of new symbols in 0.12 - - - - - Index of new symbols in 0.14 - - - - - Index of new symbols in 0.16 - - - - - Index of new symbols in 1.0 - - - - - Index of new symbols in 1.2 - - - - - Index of new symbols in 1.4 - - - - - Index of new symbols in 1.6 - - - - - - - License - - - This library is free software; you can redistribute it and/or - modify it under the terms of the GNU Library General - Public License as published by the Free Software - Foundation; either version 2 of the License, or (at your option) - any later version. - - - - This library is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU Library General Public License for - more details. - - - - You may obtain a copy of the GNU Library General - Public License from the Free Software Foundation by - visiting their Web - site or by writing to: - -
- Free Software Foundation, Inc. - 59 Temple Place - Suite 330 - Boston, MA 02111-1307 - USA -
- - - - diff --git a/doc/json-glib-overrides.txt b/doc/json-glib-overrides.txt deleted file mode 100644 index 68de4f0..0000000 --- a/doc/json-glib-overrides.txt +++ /dev/null @@ -1,14 +0,0 @@ - -JSON_MAJOR_VERSION -#define JSON_MAJOR_VERSION - - - -JSON_MINOR_VERSION -#define JSON_MINOR_VERSION - - - -JSON_MICRO_VERSION -#define JSON_MICRO_VERSION - diff --git a/doc/json-glib-sections.txt b/doc/json-glib-sections.txt deleted file mode 100644 index eaafe9b..0000000 --- a/doc/json-glib-sections.txt +++ /dev/null @@ -1,462 +0,0 @@ -json-glib/json-glib.h - -
-json-object -JSON Object -JsonObject -json_object_new -json_object_ref -json_object_unref -json_object_seal -json_object_is_immutable -json_object_hash -json_object_equal - - -json_object_add_member -json_object_set_member -json_object_has_member -json_object_get_member -json_object_dup_member -json_object_get_members -json_object_get_values -json_object_get_size -json_object_remove_member -JsonObjectForeach -json_object_foreach_member -JsonObjectIter -json_object_iter_init -json_object_iter_next -json_object_iter_init_ordered -json_object_iter_next_ordered - - -json_object_set_array_member -json_object_get_array_member -json_object_set_object_member -json_object_get_object_member -json_object_set_null_member -json_object_get_null_member -json_object_set_boolean_member -json_object_get_boolean_member -json_object_get_boolean_member_with_default -json_object_set_double_member -json_object_get_double_member -json_object_get_double_member_with_default -json_object_set_int_member -json_object_get_int_member -json_object_get_int_member_with_default -json_object_set_string_member -json_object_get_string_member -json_object_get_string_member_with_default - - -JSON_TYPE_OBJECT -json_object_get_type -
- -
-json-array -JSON Array -JsonArray -json_array_new -json_array_sized_new -json_array_ref -json_array_unref -json_array_seal -json_array_is_immutable -json_array_hash -json_array_equal - - -json_array_add_element -json_array_get_element -json_array_dup_element -json_array_get_elements -json_array_get_length -json_array_remove_element -JsonArrayForeach -json_array_foreach_element - - -json_array_add_array_element -json_array_get_array_element -json_array_add_boolean_element -json_array_get_boolean_element -json_array_add_double_element -json_array_get_double_element -json_array_add_int_element -json_array_get_int_element -json_array_add_null_element -json_array_get_null_element -json_array_add_object_element -json_array_get_object_element -json_array_add_string_element -json_array_get_string_element - - -JSON_TYPE_ARRAY -json_array_get_type -
- -
-json-node -JSON Node -JsonNodeType -JsonNode -JSON_NODE_TYPE -JSON_NODE_HOLDS -JSON_NODE_HOLDS_VALUE -JSON_NODE_HOLDS_OBJECT -JSON_NODE_HOLDS_ARRAY -JSON_NODE_HOLDS_NULL -json_node_alloc -json_node_init -json_node_init_int -json_node_init_double -json_node_init_boolean -json_node_init_string -json_node_init_null -json_node_init_object -json_node_init_array -json_node_new -json_node_copy -json_node_free -json_node_ref -json_node_unref -json_node_is_immutable -json_node_seal -json_node_hash -json_node_equal - - -json_node_set_array -json_node_take_array -json_node_get_array -json_node_dup_array - - -json_node_set_object -json_node_take_object -json_node_get_object -json_node_dup_object - - -json_node_set_value -json_node_get_value -json_node_set_boolean -json_node_get_boolean -json_node_set_double -json_node_get_double -json_node_set_int -json_node_get_int -json_node_set_string -json_node_get_string -json_node_dup_string - - -json_node_set_parent -json_node_get_parent -json_node_type_name -json_node_get_value_type -json_node_get_node_type -json_node_is_null - - -json_string_hash -json_string_equal -json_string_compare - - -JSON_DEPRECATED -JSON_DEPRECATED_FOR -JSON_TYPE_NODE -json_node_get_type -
- -
-json-parser -JsonParser -JsonParserError - - -JsonParser -JsonParserClass -json_parser_new -json_parser_new_immutable -json_parser_load_from_file -json_parser_load_from_mapped_file -json_parser_load_from_data -json_parser_load_from_stream -json_parser_load_from_stream_async -json_parser_load_from_stream_finish - - -json_parser_get_root -json_parser_steal_root - - -json_parser_get_current_line -json_parser_get_current_pos -json_parser_has_assignment - - -JSON_TYPE_PARSER -JSON_PARSER -JSON_IS_PARSER -JSON_PARSER_CLASS -JSON_IS_PARSER_CLASS -JSON_PARSER_ERROR -JSON_PARSER_GET_CLASS - - -JsonParserPrivate -json_parser_get_type -json_parser_error_quark -
- -
-json-generator -JsonGenerator - -JsonGenerator -JsonGeneratorClass -json_generator_new -json_generator_set_root -json_generator_get_root -json_generator_set_pretty -json_generator_get_pretty -json_generator_set_indent -json_generator_get_indent -json_generator_set_indent_char -json_generator_get_indent_char - - -json_generator_to_file -json_generator_to_data -json_generator_to_gstring -json_generator_to_stream - - -JSON_TYPE_GENERATOR -JSON_GENERATOR -JSON_IS_GENERATOR -JSON_GENERATOR_CLASS -JSON_IS_GENERATOR_CLASS -JSON_GENERATOR_GET_CLASS - - -JsonGeneratorPrivate -json_generator_get_type -
- -
-json-serializable -Serializable Interface -JsonSerializableIface -json_serializable_serialize_property -json_serializable_deserialize_property -json_serializable_find_property -json_serializable_get_property -json_serializable_list_properties -json_serializable_set_property - - -json_serializable_default_serialize_property -json_serializable_default_deserialize_property - - -JSON_TYPE_SERIALIZABLE -JSON_SERIALIZABLE -JSON_IS_SERIALIZABLE -JSON_SERIALIZABLE_GET_IFACE - - -JsonSerializable -json_serializable_get_type -
- -
-json-gboxed -Boxed Types Serialization -JsonBoxedSerializeFunc -JsonBoxedDeserializeFunc -json_boxed_register_serialize_func -json_boxed_register_deserialize_func - - -json_boxed_can_serialize -json_boxed_can_deserialize -json_boxed_serialize -json_boxed_deserialize -
- -
-json-gobject -GObject Serialization -json_gobject_serialize -json_gobject_deserialize -json_gobject_to_data -json_gobject_from_data - - -json_construct_gobject -json_serialize_gobject -
- -
-json-gvariant - - -json_gvariant_serialize -json_gvariant_serialize_data -json_gvariant_deserialize -json_gvariant_deserialize_data -
- -
-json-version -Versioning information -JSON_MAJOR_VERSION -JSON_MINOR_VERSION -JSON_MICRO_VERSION - - -JSON_VERSION -JSON_VERSION_S -JSON_VERSION_HEX - - -JSON_CHECK_VERSION -JSON_VERSION_MIN_REQUIRED -JSON_VERSION_MAX_ALLOWED - - -JSON_VERSION_CUR_STABLE -JSON_VERSION_PREV_STABLE -JSON_VERSION_1_0 -JSON_AVAILABLE_IN_1_0 -JSON_DEPRECATED_IN_1_0 -JSON_DEPRECATED_IN_1_0_FOR -JSON_VERSION_1_2 -JSON_AVAILABLE_IN_1_2 -JSON_DEPRECATED_IN_1_2 -JSON_DEPRECATED_IN_1_2_FOR -JSON_VERSION_1_4 -JSON_AVAILABLE_IN_1_4 -JSON_DEPRECATED_IN_1_4 -JSON_DEPRECATED_IN_1_4_FOR -JSON_VERSION_1_6 -JSON_AVAILABLE_IN_1_6 -JSON_DEPRECATED_IN_1_6 -JSON_DEPRECATED_IN_1_6_FOR - - -JSON_ENCODE_VERSION -JSON_DEPRECATED -JSON_DEPRECATED_FOR -JSON_UNAVAILABLE -_JSON_EXTERN -
- -
-json-builder -JsonBuilder -JsonBuilderClass -json_builder_new -json_builder_new_immutable -json_builder_get_root -json_builder_reset - -json_builder_begin_array -json_builder_end_array -json_builder_begin_object -json_builder_set_member_name -json_builder_end_object - -json_builder_add_value -json_builder_add_int_value -json_builder_add_double_value -json_builder_add_boolean_value -json_builder_add_string_value -json_builder_add_null_value - -JSON_TYPE_BUILDER -JSON_BUILDER -JSON_BUILDER_CLASS -JSON_IS_BUILDER -JSON_IS_BUILDER_CLASS -JSON_BUILDER_GET_CLASS - -JsonBuilderPrivate -json_builder_get_type -
- -
-json-reader -JsonReader -JsonReaderClass -json_reader_new -json_reader_set_root - -json_reader_read_element -json_reader_end_element -json_reader_is_array -json_reader_count_elements - -json_reader_read_member -json_reader_end_member -json_reader_is_object -json_reader_count_members -json_reader_list_members -json_reader_get_member_name - -json_reader_is_value -json_reader_get_value -json_reader_get_int_value -json_reader_get_double_value -json_reader_get_string_value -json_reader_get_boolean_value -json_reader_get_null_value - -JsonReaderError -JSON_READER_ERROR -json_reader_get_error - -JSON_READER -JSON_READER_CLASS -JSON_IS_READER -JSON_IS_READER_CLASS -JSON_READER_GET_CLASS -JSON_TYPE_READER - -JsonReaderPrivate -json_reader_get_type -json_reader_error_quark -
- -
-json-path -JsonPath -JsonPathClass -json_path_new -JSON_PATH_ERROR -JsonPathError -json_path_compile -json_path_match - -json_path_query - -JSON_TYPE_PATH -JSON_PATH -JSON_IS_PATH - -json_path_get_type -json_path_error_quark -
- -
-json-utils -json_from_string -json_to_string -
diff --git a/doc/json-glib.toml.in b/doc/json-glib.toml.in new file mode 100644 index 0000000..9987232 --- /dev/null +++ b/doc/json-glib.toml.in @@ -0,0 +1,67 @@ +[library] +namespace = "Json" +version = "@JSON_VERSION@" +browse_url = "https://gitlab.gnome.org/GNOME/json-glib/" +repository_url = "https://gitlab.gnome.org/GNOME/json-glib.git" +authors = "Emmanuele Bassi" +license = "LGPL-2.1-or-later" +description = "JSON parser and generator" +dependencies = [ "GObject-2.0", "Gio-2.0" ] +devhelp = true +search_index = true + + [dependencies."GObject-2.0"] + name = "GObject" + description = "The base type system library" + docs_url = "https://developer.gnome.org/gobject/stable" + + [dependencies."Gio-2.0"] + name = "Gio" + description = "GObject interfaces and objects" + docs_url = "https://developer.gnome.org/gio/stable" + +[theme] +name = "basic" +show_index_summary = true +show_class_hierarchy = true + +[source-location] +base_url = "https://gitlab.gnome.org/GNOME/json-glib/-/blob/master/" + +[extra] +content_files = [ + 'json-gboxed.md', + 'json-gobject.md', + 'json-gvariant.md', +] + +[[object]] +pattern = "DEPRECATED_IN_*" +hidden = true + +[[object]] +name = "DEPRECATED_FOR" +hidden = true + +[[object]] +name = "UNAVAILABLE" +hidden = true + +[[object]] +name = "ParserError" + [[object.function]] + name = "quark" + check_ignore = true + + +[[object]] +name = "PathError" + [[object.function]] + name = "quark" + check_ignore = true + +[[object]] +name = "ReaderError" + [[object.function]] + name = "quark" + check_ignore = true diff --git a/doc/json-gobject.md b/doc/json-gobject.md new file mode 100644 index 0000000..2832cfa --- /dev/null +++ b/doc/json-gobject.md @@ -0,0 +1,13 @@ +Title: Serializing GObject Types + +# Serializing GObject Types + +JSON-GLib provides API for serializing and deserializing `GObject` instances +to and from JSON data streams. + +Simple `GObject` classes can be (de)serialized into JSON objects, if the +properties have compatible types with the native JSON types (integers, +booleans, strings, string vectors). If the class to be (de)serialized has +complex data types for properties (like boxed types or other objects) then +the class should implement the provided [iface@Json.Serializable] interface +and its virtual functions. diff --git a/doc/json-gvariant.md b/doc/json-gvariant.md new file mode 100644 index 0000000..796bea8 --- /dev/null +++ b/doc/json-gvariant.md @@ -0,0 +1,43 @@ +Title: Serializing GVariants + +# Serializing GVariants + +`GVariant` is a serialization format mainly used as the wire data for D-Bus, +as well as storing values in GSettings. JSON-GLib provides utility functions +to serialize and deserialize `GVariant` data to and from JSON. + +Use [`func@Json.gvariant_serialize`] and [`func@Json.gvariant_serialize_data`] to +convert from any `GVariant` value to a [struct@Json.Node] tree or its string +representation. + +Use [`func@Json.gvariant_deserialize`] and [`func@Json.gvariant_deserialize_data`] +to obtain the `GVariant` value from a `JsonNode` tree or directly from a JSON +string. + +Since many `GVariant` data types cannot be directly represented as +JSON, a `GVariant` type string (signature) should be provided to these +methods in order to obtain a correct, type-contrained result. +If no signature is provided, conversion can still be done, but the +resulting `GVariant` value will be "guessed" from the JSON data types +using the following rules: + +Strings: + A JSON string maps to a GVariant string `(s)`. + +Integers: + A JSON integer maps to a GVariant 64-bit integer `(x)`. + +Booleans: + A JSON boolean maps to a GVariant boolean `(b)`. + +Numbers: + A JSON number maps to a GVariant double `(d)`. + +Arrays: + A JSON array maps to a GVariant array of variants `(av)`. + +Objects: + A JSON object maps to a GVariant dictionary of string to variants `(a{sv})`. + +`NULL` values: + A JSON `null` value maps to a GVariant "maybe" variant `(mv)`. diff --git a/doc/meson.build b/doc/meson.build index 8f27ff6..30e2039 100644 --- a/doc/meson.build +++ b/doc/meson.build @@ -1,44 +1,62 @@ -if find_program('gtkdoc-scan', required : get_option('gtk_doc')).found() - subdir('xml') +if get_option('gtk_doc').enabled() and get_option('introspection').enabled() + dependency('gi-docgen', version: '>= 2021.6', + fallback: ['gi-docgen', 'dummy_dep'], + ) - private_headers = [ - 'config.h', + gidocgen = find_program('gi-docgen', required: get_option('gtk_doc')) - 'json-debug.h', - 'json-enum-types.h', - 'json-glib.h', - 'json-gobject-private.h', - 'json-marshal.h', - 'json-private.h', - 'json-scanner.h', - 'json-types-private.h', + json_docdir = json_datadir / 'doc' - 'tests/json-test-utils.h', - ] + toml_conf = configuration_data() + toml_conf.set('JSON_VERSION', meson.project_version()) - glib_prefix = dependency('glib-2.0').get_pkgconfig_variable('prefix') - glib_docpath = join_paths(glib_prefix, 'share', 'gtk-doc', 'html') - docpath = join_paths(json_datadir, 'gtk-doc', 'html') + json_toml = configure_file( + input: 'json-glib.toml.in', + output: 'json-glib.toml', + configuration: toml_conf, + ) - gnome.gtkdoc( - 'json-glib', - main_xml: 'json-glib-docs.xml', - src_dir: include_directories('../json-glib'), - dependencies: json_glib_dep, - gobject_typesfile: 'json-glib.types', - scan_args: [ - '--rebuild-types', - '--ignore-decorators=_JSON_EXTERN', - '--ignore-headers=' + ' '.join(private_headers), - ], - fixxref_args: [ - '--html-dir=@0@'.format(docpath), - '--extra-dir=@0@'.format(join_paths(glib_docpath, 'glib')), - '--extra-dir=@0@'.format(join_paths(glib_docpath, 'gobject')), - '--extra-dir=@0@'.format(join_paths(glib_docpath, 'gio')), + json_content_files = [ + 'json-gboxed.md', + 'json-gobject.md', + 'json-gvariant.md', + ] + + custom_target('json-glib-doc', + input: json_glib_gir[0], + output: 'json-glib-1.0', + command: [ + gidocgen, + 'generate', + '--quiet', + '--fatal-warnings', + '--add-include-path=@0@'.format(meson.current_build_dir() / '../json-glib'), + '--config', json_toml, + '--output-dir=@OUTPUT@', + '--no-namespace-dir', + '--content-dir=@0@'.format(meson.current_source_dir()), + '@INPUT@', ], + depend_files: [ json_toml, json_content_files ], + build_by_default: true, install: true, + install_dir: json_docdir, ) + + if get_option('tests') + test('doc-check', + gidocgen, + args: [ + 'check', + '--config', json_toml, + '--add-include-path=@0@'.format(meson.current_build_dir() / '../json-glib'), + json_glib_gir[0], + ], + depends: json_glib_gir[0], + suite: ['docs'], + ) + endif + endif xsltproc = find_program('xsltproc', required: false) diff --git a/doc/xml/gtkdocentities.ent.in b/doc/xml/gtkdocentities.ent.in deleted file mode 100644 index f12c9ff..0000000 --- a/doc/xml/gtkdocentities.ent.in +++ /dev/null @@ -1,8 +0,0 @@ - - - - - - - - diff --git a/doc/xml/meson.build b/doc/xml/meson.build deleted file mode 100644 index 587d773..0000000 --- a/doc/xml/meson.build +++ /dev/null @@ -1,11 +0,0 @@ -ent_conf = configuration_data() -ent_conf.set('PACKAGE', 'JSON-GLib') -ent_conf.set('PACKAGE_BUGREPORT', 'https://bugzilla.gnome.org/enter_bug.cgi?product=json-glib') -ent_conf.set('PACKAGE_NAME', 'JSON-GLib') -ent_conf.set('PACKAGE_STRING', meson.project_name()) -ent_conf.set('PACKAGE_TARNAME', '@0@-@1@'.format(meson.project_name(), meson.project_version())) -ent_conf.set('PACKAGE_URL', 'http://wiki.gnome.org/Project/JsonGlib') -ent_conf.set('PACKAGE_VERSION', meson.project_version()) -ent_conf.set('PACKAGE_API_VERSION', json_api_version) -configure_file(input: 'gtkdocentities.ent.in', output: 'gtkdocentities.ent', configuration: ent_conf) - diff --git a/json-glib/json-array.c b/json-glib/json-array.c index 4834cdc..b242ce7 100644 --- a/json-glib/json-array.c +++ b/json-glib/json-array.c @@ -26,20 +26,24 @@ #include "json-types-private.h" /** - * SECTION:json-array - * @short_description: a JSON array representation + * JsonArray: * - * #JsonArray is the representation of the array type inside JSON. It contains - * #JsonNode elements, which may contain fundamental types, other arrays or - * objects. + * `JsonArray` is the representation of the array type inside JSON. * - * Since arrays can be expensive, they are reference counted. You can control - * the lifetime of a #JsonArray using json_array_ref() and json_array_unref(). + * A `JsonArray` contains [struct@Json.Node] elements, which may contain + * fundamental types, other arrays or objects. * - * To append an element, use json_array_add_element(). - * To extract an element at a given index, use json_array_get_element(). - * To retrieve the entire array in list form, use json_array_get_elements(). - * To retrieve the length of the array, use json_array_get_length(). + * Since arrays can be arbitrarily big, copying them can be expensive; for + * this reason, they are reference counted. You can control the lifetime of + * a `JsonArray` using [method@Json.Array.ref] and [method@Json.Array.unref]. + * + * To append an element, use [method@Json.Array.add_element]. + * + * To extract an element at a given index, use [method@Json.Array.get_element]. + * + * To retrieve the entire array in list form, use [method@Json.Array.get_elements]. + * + * To retrieve the length of the array, use [method@Json.Array.get_length]. */ G_DEFINE_BOXED_TYPE (JsonArray, json_array, json_array_ref, json_array_unref); @@ -47,9 +51,9 @@ G_DEFINE_BOXED_TYPE (JsonArray, json_array, json_array_ref, json_array_unref); /** * json_array_new: (constructor) * - * Creates a new #JsonArray. + * Creates a new array. * - * Return value: (transfer full): the newly created #JsonArray + * Return value: (transfer full): the newly created array */ JsonArray * json_array_new (void) @@ -68,9 +72,9 @@ json_array_new (void) * json_array_sized_new: (constructor) * @n_elements: number of slots to pre-allocate * - * Creates a new #JsonArray with @n_elements slots already allocated. + * Creates a new array with `n_elements` slots already allocated. * - * Return value: (transfer full): the newly created #JsonArray + * Return value: (transfer full): the newly created array */ JsonArray * json_array_sized_new (guint n_elements) @@ -87,12 +91,12 @@ json_array_sized_new (guint n_elements) /** * json_array_ref: - * @array: a #JsonArray + * @array: the array to reference * - * Increase by one the reference count of a #JsonArray. + * Acquires a reference on the given array. * - * Return value: (transfer none): the passed #JsonArray, with the reference count - * increased by one. + * Return value: (transfer none): the passed array, with the reference count + * increased by one */ JsonArray * json_array_ref (JsonArray *array) @@ -107,10 +111,11 @@ json_array_ref (JsonArray *array) /** * json_array_unref: - * @array: a #JsonArray + * @array: the array to unreference * - * Decreases by one the reference count of a #JsonArray. If the - * reference count reaches zero, the array is destroyed and all + * Releases a reference on the given array. + * + * If the reference count reaches zero, the array is destroyed and all * its allocated resources are freed. */ void @@ -135,12 +140,13 @@ json_array_unref (JsonArray *array) /** * json_array_seal: - * @array: a #JsonArray + * @array: the array to seal + * + * Seals the given array, making it immutable to further changes. * - * Seals the #JsonArray, making it immutable to further changes. This will - * recursively seal all elements in the array too. + * This function will recursively seal all elements in the array too. * - * If the @array is already immutable, this is a no-op. + * If the `array` is already immutable, this is a no-op. * * Since: 1.2 */ @@ -165,13 +171,13 @@ json_array_seal (JsonArray *array) /** * json_array_is_immutable: - * @array: a #JsonArray + * @array: a JSON array * - * Check whether the given @array has been marked as immutable by calling - * json_array_seal() on it. + * Check whether the given `array` has been marked as immutable by calling + * [method@Json.Array.seal] on it. * * Since: 1.2 - * Returns: %TRUE if the @array is immutable + * Returns: %TRUE if the array is immutable */ gboolean json_array_is_immutable (JsonArray *array) @@ -184,14 +190,12 @@ json_array_is_immutable (JsonArray *array) /** * json_array_get_elements: - * @array: a #JsonArray + * @array: a JSON array * - * Gets the elements of a #JsonArray as a list of #JsonNode instances. + * Retrieves all the elements of an array as a list of nodes. * - * 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 + * Return value: (element-type JsonNode) (transfer container) (nullable): the elements + * of the array */ GList * json_array_get_elements (JsonArray *array) @@ -211,14 +215,12 @@ json_array_get_elements (JsonArray *array) /** * json_array_dup_element: - * @array: a #JsonArray + * @array: a JSON array * @index_: the index of the element to retrieve * - * Retrieves a copy of the #JsonNode containing the value of the - * element at @index_ inside a #JsonArray + * Retrieves a copy of the element at the given position in the array. * - * Return value: (transfer full): a copy of the #JsonNode at the requested - * index. Use json_node_unref() when done. + * Return value: (transfer full): a copy of the element at the given position * * Since: 0.6 */ @@ -240,13 +242,12 @@ json_array_dup_element (JsonArray *array, /** * json_array_get_element: - * @array: a #JsonArray + * @array: a JSON array * @index_: the index of the element to retrieve - * - * Retrieves the #JsonNode containing the value of the element at @index_ - * inside a #JsonArray. * - * Return value: (transfer none): a pointer to the #JsonNode at the requested index + * Retrieves the element at the given position in the array. + * + * Return value: (transfer none): the element at the given position */ JsonNode * json_array_get_element (JsonArray *array, @@ -260,13 +261,13 @@ json_array_get_element (JsonArray *array, /** * json_array_get_int_element: - * @array: a #JsonArray + * @array: a JSON array * @index_: the index of the element to retrieve * - * Conveniently retrieves the integer value of the element at @index_ - * inside @array + * Conveniently retrieves the integer value of the element at the given + * position inside an array. * - * See also: json_array_get_element(), json_node_get_int() + * See also: [method@Json.Array.get_element], [method@Json.Node.get_int] * * Return value: the integer value * @@ -290,13 +291,13 @@ json_array_get_int_element (JsonArray *array, /** * json_array_get_double_element: - * @array: a #JsonArray + * @array: a JSON array * @index_: the index of the element to retrieve * * Conveniently retrieves the floating point value of the element at - * @index_ inside @array + * the given position inside an array. * - * See also: json_array_get_element(), json_node_get_double() + * See also: [method@Json.Array.get_element], [method@Json.Node.get_double] * * Return value: the floating point value * @@ -320,15 +321,15 @@ json_array_get_double_element (JsonArray *array, /** * json_array_get_boolean_element: - * @array: a #JsonArray + * @array: a JSON array * @index_: the index of the element to retrieve * - * Conveniently retrieves the boolean value of the element at @index_ - * inside @array + * Conveniently retrieves the boolean value of the element at the given + * position inside an array. * - * See also: json_array_get_element(), json_node_get_boolean() + * See also: [method@Json.Array.get_element], [method@Json.Node.get_boolean] * - * Return value: the integer value + * Return value: the boolean value * * Since: 0.8 */ @@ -350,16 +351,15 @@ json_array_get_boolean_element (JsonArray *array, /** * json_array_get_string_element: - * @array: a #JsonArray + * @array: a JSON array * @index_: the index of the element to retrieve * - * Conveniently retrieves the string value of the element at @index_ - * inside @array + * Conveniently retrieves the string value of the element at the given + * position inside an array. * - * See also: json_array_get_element(), json_node_get_string() + * See also: [method@Json.Array.get_element], [method@Json.Node.get_string] * - * Return value: the string value; the returned string is owned by - * the #JsonArray and should not be modified or freed + * Return value: (transfer none): the string value * * Since: 0.8 */ @@ -384,14 +384,15 @@ json_array_get_string_element (JsonArray *array, /** * json_array_get_null_element: - * @array: a #JsonArray + * @array: a JSON array * @index_: the index of the element to retrieve * - * Conveniently retrieves whether the element at @index_ is set to null + * Conveniently checks whether the element at the given position inside the + * array contains a `null` value. * - * See also: json_array_get_element(), JSON_NODE_TYPE(), %JSON_NODE_NULL + * See also: [method@Json.Array.get_element], [method@Json.Node.is_null] * - * Return value: %TRUE if the element is null + * Return value: `TRUE` if the element is `null` * * Since: 0.8 */ @@ -421,13 +422,12 @@ json_array_get_null_element (JsonArray *array, /** * json_array_get_array_element: - * @array: a #JsonArray + * @array: a JSON array * @index_: the index of the element to retrieve * - * Conveniently retrieves the array from the element at @index_ - * inside @array + * Conveniently retrieves the array at the given position inside an array. * - * See also: json_array_get_element(), json_node_get_array() + * See also: [method@Json.Array.get_element], [method@Json.Node.get_array] * * Return value: (transfer none): the array * @@ -454,13 +454,12 @@ json_array_get_array_element (JsonArray *array, /** * json_array_get_object_element: - * @array: a #JsonArray + * @array: a JSON array * @index_: the index of the element to retrieve * - * Conveniently retrieves the object from the element at @index_ - * inside @array + * Conveniently retrieves the object at the given position inside an array. * - * See also: json_array_get_element(), json_node_get_object() + * See also: [method@Json.Array.get_element], [method@Json.Node.get_object] * * Return value: (transfer none): the object * @@ -487,9 +486,9 @@ json_array_get_object_element (JsonArray *array, /** * json_array_get_length: - * @array: a #JsonArray + * @array: a JSON array * - * Retrieves the length of a #JsonArray + * Retrieves the length of the given array * * Return value: the length of the array */ @@ -503,11 +502,10 @@ json_array_get_length (JsonArray *array) /** * json_array_add_element: - * @array: a #JsonArray - * @node: (transfer full): a #JsonNode + * @array: a JSON array + * @node: (transfer full): the element to add * - * Appends @node inside @array. The array will take ownership of the - * #JsonNode. + * Appends the given `node` inside an array. */ void json_array_add_element (JsonArray *array, @@ -521,12 +519,12 @@ json_array_add_element (JsonArray *array, /** * json_array_add_int_element: - * @array: a #JsonArray - * @value: an integer value + * @array: a JSON array + * @value: the integer value to add * - * Conveniently adds an integer @value into @array + * Conveniently adds the given integer value into an array. * - * See also: json_array_add_element(), json_node_set_int() + * See also: [method@Json.Array.add_element], [method@Json.Node.set_int] * * Since: 0.8 */ @@ -541,12 +539,12 @@ json_array_add_int_element (JsonArray *array, /** * json_array_add_double_element: - * @array: a #JsonArray - * @value: a floating point value + * @array: a JSON array + * @value: the floating point value to add * - * Conveniently adds a floating point @value into @array + * Conveniently adds the given floating point value into an array. * - * See also: json_array_add_element(), json_node_set_double() + * See also: [method@Json.Array.add_element], [method@Json.Node.set_double] * * Since: 0.8 */ @@ -561,12 +559,12 @@ json_array_add_double_element (JsonArray *array, /** * json_array_add_boolean_element: - * @array: a #JsonArray - * @value: a boolean value + * @array: a JSON array + * @value: the boolean value to add * - * Conveniently adds a boolean @value into @array + * Conveniently adds the given boolean value into an array. * - * See also: json_array_add_element(), json_node_set_boolean() + * See also: [method@Json.Array.add_element], [method@Json.Node.set_boolean] * * Since: 0.8 */ @@ -581,12 +579,12 @@ json_array_add_boolean_element (JsonArray *array, /** * json_array_add_string_element: - * @array: a #JsonArray - * @value: a string value + * @array: a JSON array + * @value: the string value to add * - * Conveniently adds a string @value into @array + * Conveniently adds the given string value into an array. * - * See also: json_array_add_element(), json_node_set_string() + * See also: [method@Json.Array.add_element], [method@Json.Node.set_string] * * Since: 0.8 */ @@ -610,11 +608,11 @@ json_array_add_string_element (JsonArray *array, /** * json_array_add_null_element: - * @array: a #JsonArray + * @array: a JSON array * - * Conveniently adds a null element into @array + * Conveniently adds a `null` element into an array * - * See also: json_array_add_element(), %JSON_NODE_NULL + * See also: [method@Json.Array.add_element], `JSON_NODE_NULL` * * Since: 0.8 */ @@ -628,13 +626,14 @@ json_array_add_null_element (JsonArray *array) /** * json_array_add_array_element: - * @array: a #JsonArray - * @value: (allow-none) (transfer full): a #JsonArray + * @array: a JSON array + * @value: (nullable) (transfer full): the array to add + * + * Conveniently adds an array element into an array. * - * Conveniently adds an array into @array. The @array takes ownership - * of the newly added #JsonArray + * If `value` is `NULL`, a `null` element will be added instead. * - * See also: json_array_add_element(), json_node_take_array() + * See also: [method@Json.Array.add_element], [method@Json.Node.take_array] * * Since: 0.8 */ @@ -661,13 +660,14 @@ json_array_add_array_element (JsonArray *array, /** * json_array_add_object_element: - * @array: a #JsonArray - * @value: (transfer full): a #JsonObject + * @array: a JSON array + * @value: (transfer full) (nullable): the object to add * - * Conveniently adds an object into @array. The @array takes ownership - * of the newly added #JsonObject + * Conveniently adds an object into an array. * - * See also: json_array_add_element(), json_node_take_object() + * If `value` is `NULL`, a `null` element will be added instead. + * + * See also: [method@Json.Array.add_element], [method@Json.Node.take_object] * * Since: 0.8 */ @@ -694,11 +694,12 @@ json_array_add_object_element (JsonArray *array, /** * json_array_remove_element: - * @array: a #JsonArray + * @array: a JSON array * @index_: the position of the element to be removed * - * Removes the #JsonNode inside @array at @index_ freeing its allocated - * resources. + * Removes the element at the given position inside an array. + * + * This function will release the reference held on the element. */ void json_array_remove_element (JsonArray *array, @@ -712,16 +713,16 @@ json_array_remove_element (JsonArray *array, /** * json_array_foreach_element: - * @array: a #JsonArray + * @array: a JSON array * @func: (scope call): the function to be called on each element * @data: (closure): data to be passed to the function * - * Iterates over all elements of @array and calls @func on + * Iterates over all elements of an array, and calls a function on * each one of them. * - * It is safe to change the value of a #JsonNode of the @array - * from within the iterator @func, but it is not safe to add or - * remove elements from the @array. + * It is safe to change the value of an element of the array while + * iterating over it, but it is not safe to add or remove elements + * from the array. * * Since: 0.8 */ @@ -747,15 +748,16 @@ json_array_foreach_element (JsonArray *array, /** * json_array_hash: - * @key: (type JsonArray): a JSON array to hash + * @key: (type JsonArray) (not nullable): a JSON array to hash * - * Calculate a hash value for the given @key (a #JsonArray). + * Calculates a hash value for the given `key`. * - * The hash is calculated over the array and all its elements, recursively. If - * the array is immutable, this is a fast operation; otherwise, it scales + * The hash is calculated over the array and all its elements, recursively. + * + * If the array is immutable, this is a fast operation; otherwise, it scales * proportionally with the length of the array. * - * Returns: hash value for @key + * Returns: hash value for the key * Since: 1.2 */ guint @@ -785,14 +787,17 @@ json_array_hash (gconstpointer key) /** * json_array_equal: - * @a: (type JsonArray): a JSON array - * @b: (type JsonArray): another JSON array + * @a: (type JsonArray) (not nullable): a JSON array + * @b: (type JsonArray) (not nullable): another JSON array + * + * Check whether two arrays are equal. + * + * Equality is defined as: * - * Check whether @a and @b are equal #JsonArrays, meaning they have the same - * number of elements, and the values of elements in corresponding positions - * are equal. + * - the array have the same number of elements + * - the values of elements in corresponding positions are equal * - * Returns: %TRUE if @a and @b are equal; %FALSE otherwise + * Returns: `TRUE` if the arrays are equal, and `FALSE` otherwise * Since: 1.2 */ gboolean diff --git a/json-glib/json-builder.c b/json-glib/json-builder.c index 0a7f536..45f6cbe 100644 --- a/json-glib/json-builder.c +++ b/json-glib/json-builder.c @@ -23,20 +23,44 @@ */ /** - * SECTION:json-builder - * @Title: JsonBuilder - * @short_description: Generates JSON trees - * @See_Also: JsonGenerator + * JsonBuilder: * - * #JsonBuilder provides an object for generating a JSON tree. - * You can generate only one tree with one #JsonBuilder instance. + * `JsonBuilder` provides an object for generating a JSON tree. * - * The root of the JSON tree can be either a #JsonObject or a #JsonArray. + * The root of the JSON tree can be either a [struct@Json.Object] or a [struct@Json.Array]. * Thus the first call must necessarily be either - * json_builder_begin_object() or json_builder_begin_array(). + * [method@Json.Builder.begin_object] or [method@Json.Builder.begin_array]. * - * For convenience to language bindings, #JsonBuilder returns itself from - * most of functions, making it easy to chain function calls. + * For convenience to language bindings, most `JsonBuilder` method return the + * instance, making it easy to chain function calls. + * + * ## Using `JsonBuilder` + * + * ```c + * g_autoptr(JsonBuilder) builder = json_builder_new (); + * + * json_builder_begin_object (builder); + * + * json_builder_set_member_name (builder, "url"); + * json_builder_add_string_value (builder, "http://www.gnome.org/img/flash/two-thirty.png"); + * + * json_builder_set_member_name (builder, "size"); + * json_builder_begin_array (builder); + * json_builder_add_int_value (builder, 652); + * json_builder_add_int_value (builder, 242); + * json_builder_end_array (builder); + * + * json_builder_end_object (builder); + * + * g_autoptr(JsonNode) root root = json_builder_get_root (builder); + * + * g_autoptr(JsonGenerator) gen = json_generator_new (); + * json_generator_set_root (gen, root); + * g_autofree char *str = json_generator_to_data (gen, NULL); + * + * // str now contains the following JSON data + * // { "url" : "http://www.gnome.org/img/flash/two-thirty.png", "size" : [ 652, 242 ] } + * ``` */ #include "config.h" @@ -190,8 +214,9 @@ json_builder_class_init (JsonBuilderClass *klass) /** * JsonBuilder:immutable: * - * Whether the #JsonNode tree built by the #JsonBuilder should be immutable - * when created. Making the output immutable on creation avoids the expense + * Whether the tree should be immutable when created. + * + * Making the output immutable on creation avoids the expense * of traversing it to make it immutable later. * * Since: 1.2 @@ -238,10 +263,11 @@ json_builder_is_valid_add_mode (JsonBuilder *builder) /** * json_builder_new: * - * Creates a new #JsonBuilder. You can use this object to generate a - * JSON tree and obtain the root #JsonNode. + * Creates a new `JsonBuilder`. + * + * You can use this object to generate a JSON tree and obtain the root node. * - * Return value: the newly created #JsonBuilder instance + * Return value: the newly created builder instance */ JsonBuilder * json_builder_new (void) @@ -252,11 +278,13 @@ json_builder_new (void) /** * json_builder_new_immutable: (constructor) * - * Creates a new #JsonBuilder instance with its #JsonBuilder:immutable property - * set to %TRUE to create immutable output trees. + * Creates a new, immutable `JsonBuilder` instance. + * + * It is equivalent to setting the [property@Json.Builder:immutable] property + * set to `TRUE` at construction time. * * Since: 1.2 - * Returns: (transfer full): a new #JsonBuilder + * Returns: (transfer full): the newly create builder instance */ JsonBuilder * json_builder_new_immutable (void) @@ -266,13 +294,15 @@ json_builder_new_immutable (void) /** * json_builder_get_root: - * @builder: a #JsonBuilder + * @builder: a builder * - * Returns the root of the current constructed tree, if the build is complete - * (ie: all opened objects, object members and arrays are being closed). + * Returns the root of the currently constructed tree. * - * Return value: (nullable) (transfer full): the #JsonNode, or %NULL if the - * build is not complete. Free the returned value with json_node_unref(). + * if the build is incomplete (ie: if there are any opened objects, or any + * open object members and array elements) then this function will return + * `NULL`. + * + * Return value: (nullable) (transfer full): the root node */ JsonNode * json_builder_get_root (JsonBuilder *builder) @@ -294,9 +324,9 @@ json_builder_get_root (JsonBuilder *builder) /** * json_builder_reset: - * @builder: a #JsonBuilder + * @builder: a builder * - * Resets the state of the @builder back to its initial state. + * Resets the state of the builder back to its initial state. */ void json_builder_reset (JsonBuilder *builder) @@ -308,16 +338,19 @@ json_builder_reset (JsonBuilder *builder) /** * json_builder_begin_object: - * @builder: a #JsonBuilder + * @builder: a builder + * + * Opens an object inside the given builder. + * + * You can add a new member to the object by using [method@Json.Builder.set_member_name], + * followed by [method@Json.Builder.add_value]. * - * Opens a subobject inside the given @builder. When done adding members to - * the subobject, json_builder_end_object() must be called. + * Once you added all members to the object, you must call [method@Json.Builder.end_object] + * to close the object. * - * Can be called for first or only if the call is associated to an object member - * or an array element. + * If the builder is in an inconsistent state, this function will return `NULL`. * - * Return value: (nullable) (transfer none): the #JsonBuilder, or %NULL if the - * call was inconsistent + * Return value: (nullable) (transfer none): the builder instance */ JsonBuilder * json_builder_begin_object (JsonBuilder *builder) @@ -363,15 +396,14 @@ json_builder_begin_object (JsonBuilder *builder) /** * json_builder_end_object: - * @builder: a #JsonBuilder + * @builder: a builder * - * Closes the subobject inside the given @builder that was opened by the most - * recent call to json_builder_begin_object(). + * Closes the object inside the given builder that was opened by the most + * recent call to [method@Json.Builder.begin_object]. * - * Cannot be called after json_builder_set_member_name(). + * This function cannot be called after [method@Json.Builder.set_member_name]. * - * Return value: (nullable) (transfer none): the #JsonBuilder, or %NULL if the - * call was inconsistent + * Return value: (nullable) (transfer none): the builder instance */ JsonBuilder * json_builder_end_object (JsonBuilder *builder) @@ -403,16 +435,16 @@ json_builder_end_object (JsonBuilder *builder) /** * json_builder_begin_array: - * @builder: a #JsonBuilder + * @builder: a builder * - * Opens a subarray inside the given @builder. When done adding members to - * the subarray, json_builder_end_array() must be called. + * Opens an array inside the given builder. * - * Can be called for first or only if the call is associated to an object member - * or an array element. + * You can add a new element to the array by using [method@Json.Builder.add_value]. * - * Return value: (nullable) (transfer none): the #JsonBuilder, or %NULL if the - * call was inconsistent + * Once you added all elements to the array, you must call + * [method@Json.Builder.end_array] to close the array. + * + * Return value: (nullable) (transfer none): the builder instance */ JsonBuilder * json_builder_begin_array (JsonBuilder *builder) @@ -457,15 +489,14 @@ json_builder_begin_array (JsonBuilder *builder) /** * json_builder_end_array: - * @builder: a #JsonBuilder + * @builder: a builder * - * Closes the subarray inside the given @builder that was opened by the most - * recent call to json_builder_begin_array(). + * Closes the array inside the given builder that was opened by the most + * recent call to [method@Json.Builder.begin_array]. * - * Cannot be called after json_builder_set_member_name(). + * This function cannot be called after [method@Json.Builder.set_member_name]. * - * Return value: (nullable) (transfer none): the #JsonBuilder, or %NULL if the - * call was inconsistent + * Return value: (nullable) (transfer none): the builder instance */ JsonBuilder * json_builder_end_array (JsonBuilder *builder) @@ -497,16 +528,20 @@ json_builder_end_array (JsonBuilder *builder) /** * json_builder_set_member_name: - * @builder: a #JsonBuilder + * @builder: a builder * @member_name: the name of the member * - * Set the name of the next member in an object. The next call must add a value, - * open an object or an array. + * Sets the name of the member in an object. + * + * This function must be followed by of these functions: + * + * - [method@Json.Builder.add_value], to add a scalar value to the member + * - [method@Json.Builder.begin_object], to add an object to the member + * - [method@Json.Builder.begin_array], to add an array to the member * - * Can be called only if the call is associated to an object. + * This function can only be called within an open object. * - * Return value: (nullable) (transfer none): the #JsonBuilder, or %NULL if the - * call was inconsistent + * Return value: (nullable) (transfer none): the builder instance */ JsonBuilder * json_builder_set_member_name (JsonBuilder *builder, @@ -528,17 +563,18 @@ json_builder_set_member_name (JsonBuilder *builder, /** * json_builder_add_value: - * @builder: a #JsonBuilder + * @builder: a builder * @node: (transfer full): the value of the member or element * - * If called after json_builder_set_member_name(), sets @node as member of the - * most recent opened object, otherwise @node is added as element of the most - * recent opened array. + * Adds a value to the currently open object member or array. * - * The builder will take ownership of the #JsonNode. + * If called after [method@Json.Builder.set_member_name], sets the given node + * as the value of the current member in the open object; otherwise, the node + * is appended to the elements of the open array. * - * Return value: (nullable) (transfer none): the #JsonBuilder, or %NULL if the - * call was inconsistent + * The builder will take ownership of the node. + * + * Return value: (nullable) (transfer none): the builder instance */ JsonBuilder * json_builder_add_value (JsonBuilder *builder, @@ -578,17 +614,18 @@ json_builder_add_value (JsonBuilder *builder, /** * json_builder_add_int_value: - * @builder: a #JsonBuilder + * @builder: a builder * @value: the value of the member or element * - * If called after json_builder_set_member_name(), sets @value as member of the - * most recent opened object, otherwise @value is added as element of the most - * recent opened array. + * Adds an integer value to the currently open object member or array. + * + * If called after [method@Json.Builder.set_member_name], sets the given value + * as the value of the current member in the open object; otherwise, the value + * is appended to the elements of the open array. * - * See also: json_builder_add_value() + * See also: [method@Json.Builder.add_value] * - * Return value: (nullable) (transfer none): the #JsonBuilder, or %NULL if the - * call was inconsistent + * Return value: (nullable) (transfer none): the builder instance */ JsonBuilder * json_builder_add_int_value (JsonBuilder *builder, @@ -623,17 +660,18 @@ json_builder_add_int_value (JsonBuilder *builder, /** * json_builder_add_double_value: - * @builder: a #JsonBuilder + * @builder: a builder * @value: the value of the member or element * - * If called after json_builder_set_member_name(), sets @value as member of the - * most recent opened object, otherwise @value is added as element of the most - * recent opened array. + * Adds a floating point value to the currently open object member or array. + * + * If called after [method@Json.Builder.set_member_name], sets the given value + * as the value of the current member in the open object; otherwise, the value + * is appended to the elements of the open array. * - * See also: json_builder_add_value() + * See also: [method@Json.Builder.add_value] * - * Return value: (nullable) (transfer none): the #JsonBuilder, or %NULL if the - * call was inconsistent + * Return value: (nullable) (transfer none): the builder instance */ JsonBuilder * json_builder_add_double_value (JsonBuilder *builder, @@ -669,17 +707,18 @@ json_builder_add_double_value (JsonBuilder *builder, /** * json_builder_add_boolean_value: - * @builder: a #JsonBuilder + * @builder: a builder * @value: the value of the member or element * - * If called after json_builder_set_member_name(), sets @value as member of the - * most recent opened object, otherwise @value is added as element of the most - * recent opened array. + * Adds a boolean value to the currently open object member or array. * - * See also: json_builder_add_value() + * If called after [method@Json.Builder.set_member_name], sets the given value + * as the value of the current member in the open object; otherwise, the value + * is appended to the elements of the open array. * - * Return value: (nullable) (transfer none): the #JsonBuilder, or %NULL if the - * call was inconsistent + * See also: [method@Json.Builder.add_value] + * + * Return value: (nullable) (transfer none): the builder instance */ JsonBuilder * json_builder_add_boolean_value (JsonBuilder *builder, @@ -715,17 +754,18 @@ json_builder_add_boolean_value (JsonBuilder *builder, /** * json_builder_add_string_value: - * @builder: a #JsonBuilder + * @builder: a builder * @value: the value of the member or element * - * If called after json_builder_set_member_name(), sets @value as member of the - * most recent opened object, otherwise @value is added as element of the most - * recent opened array. + * Adds a boolean value to the currently open object member or array. + * + * If called after [method@Json.Builder.set_member_name], sets the given value + * as the value of the current member in the open object; otherwise, the value + * is appended to the elements of the open array. * - * See also: json_builder_add_value() + * See also: [method@Json.Builder.add_value] * - * Return value: (nullable) (transfer none): the #JsonBuilder, or %NULL if the - * call was inconsistent + * Return value: (nullable) (transfer none): the builder instance */ JsonBuilder * json_builder_add_string_value (JsonBuilder *builder, @@ -761,16 +801,17 @@ json_builder_add_string_value (JsonBuilder *builder, /** * json_builder_add_null_value: - * @builder: a #JsonBuilder + * @builder: a builder + * + * Adds a null value to the currently open object member or array. * - * If called after json_builder_set_member_name(), sets null as member of the - * most recent opened object, otherwise null is added as element of the most - * recent opened array. + * If called after [method@Json.Builder.set_member_name], sets the given value + * as the value of the current member in the open object; otherwise, the value + * is appended to the elements of the open array. * - * See also: json_builder_add_value() + * See also: [method@Json.Builder.add_value] * - * Return value: (nullable) (transfer none): the #JsonBuilder, or %NULL if - * the call was inconsistent + * Return value: (nullable) (transfer none): the builder instance */ JsonBuilder * json_builder_add_null_value (JsonBuilder *builder) diff --git a/json-glib/json-builder.h b/json-glib/json-builder.h index b35230e..9cc016c 100644 --- a/json-glib/json-builder.h +++ b/json-glib/json-builder.h @@ -42,14 +42,6 @@ typedef struct _JsonBuilder JsonBuilder; typedef struct _JsonBuilderPrivate JsonBuilderPrivate; typedef struct _JsonBuilderClass JsonBuilderClass; -/** - * JsonBuilder: - * - * The `JsonBuilder` structure contains only private data and should be - * accessed using the provided API - * - * Since: 0.12 - */ struct _JsonBuilder { /*< private >*/ @@ -58,13 +50,6 @@ struct _JsonBuilder JsonBuilderPrivate *priv; }; -/** - * JsonBuilderClass: - * - * The `JsonBuilderClass` structure contains only private data - * - * Since: 0.12 - */ struct _JsonBuilderClass { /*< private >*/ diff --git a/json-glib/json-enum-types.c.in b/json-glib/json-enum-types.c.in index 7b39290..81a342c 100644 --- a/json-glib/json-enum-types.c.in +++ b/json-glib/json-enum-types.c.in @@ -18,7 +18,7 @@ GType @enum_name@_get_type (void) { - static volatile gsize g_enum_type_id__volatile = 0; + static gsize g_enum_type_id__volatile = 0; if (g_once_init_enter (&g_enum_type_id__volatile)) { diff --git a/json-glib/json-gboxed.c b/json-glib/json-gboxed.c index f274e6d..8b51288 100644 --- a/json-glib/json-gboxed.c +++ b/json-glib/json-gboxed.c @@ -19,53 +19,6 @@ * Emmanuele Bassi */ -/** - * SECTION:json-gboxed - * @short_description: Serialize and deserialize GBoxed types - * - * GLib's #GBoxed type is a generic wrapper for arbitrary C structures. - * - * JSON-GLib allows serialization and deserialization of a #GBoxed type - * by registering functions mapping a #JsonNodeType to a specific - * #GType. - * - * When registering a #GBoxed type you should also register the - * corresponding transformation functions, e.g.: - * - * |[ - * GType - * my_struct_get_type (void) - * { - * static GType boxed_type = 0; - * - * if (boxed_type == 0) - * { - * boxed_type = - * g_boxed_type_register_static (g_intern_static_string ("MyStruct"), - * (GBoxedCopyFunc) my_struct_copy, - * (GBoxedFreeFunc) my_struct_free); - * - * json_boxed_register_serialize_func (boxed_type, JSON_NODE_OBJECT, - * my_struct_serialize); - * json_boxed_register_deserialize_func (boxed_type, JSON_NODE_OBJECT, - * my_struct_deserialize); - * } - * - * return boxed_type; - * } - * ]| - * - * The serialization function will be invoked by json_boxed_serialize(): - * it will be passed a pointer to the C structure and it must return a - * #JsonNode. The deserialization function will be invoked by - * json_boxed_deserialize(): it will be passed a #JsonNode for the - * declared type and it must return a newly allocated C structure. - * - * It is possible to check whether a #GBoxed type can be deserialized - * from a specific #JsonNodeType, and whether a #GBoxed can be serialized - * and to which specific #JsonNodeType. - */ - #include "config.h" #include @@ -137,11 +90,10 @@ lookup_boxed_transform (GSList *transforms, * json_boxed_register_serialize_func: (skip) * @gboxed_type: a boxed type * @node_type: a node type - * @serialize_func: serialization function for @boxed_type into - * a #JsonNode of type @node_type + * @serialize_func: serialization function * - * Registers a serialization function for a #GBoxed of type @gboxed_type - * to a #JsonNode of type @node_type + * Registers a serialization function for a `GBoxed` of type `gboxed_type` + * to a [struct@Json.Node] of type `node_type`. * * Since: 0.10 */ @@ -182,11 +134,10 @@ json_boxed_register_serialize_func (GType gboxed_type, * json_boxed_register_deserialize_func: (skip) * @gboxed_type: a boxed type * @node_type: a node type - * @deserialize_func: deserialization function for @boxed_type from - * a #JsonNode of type @node_type + * @deserialize_func: deserialization function * - * Registers a deserialization function for a #GBoxed of type @gboxed_type - * from a #JsonNode of type @node_type + * Registers a deserialization function for a `GBoxed` of type `gboxed_type` + * from a [struct@Json.Node] of type `node_type`. * * Since: 0.10 */ @@ -226,16 +177,16 @@ json_boxed_register_deserialize_func (GType gboxed_type, /** * json_boxed_can_serialize: * @gboxed_type: a boxed type - * @node_type: (out): the #JsonNode type to which the boxed type can be - * serialized into + * @node_type: (out) (optional): the node type to which the boxed type + * can be serialized into * - * Checks whether it is possible to serialize a #GBoxed of - * type @gboxed_type into a #JsonNode. The type of the - * #JsonNode is placed inside @node_type if the function - * returns %TRUE and it's undefined otherwise. + * Checks whether it is possible to serialize a `GBoxed` of + * type `gboxed_type` into a [struct@Json.Node]. * - * Return value: %TRUE if the type can be serialized, - * and %FALSE otherwise. + * The type of the node is placed inside `node_type` if the function + * returns `TRUE`, and it's undefined otherwise. + * + * Return value: `TRUE` if the type can be serialized, and `FALSE` otherwise * * Since: 0.10 */ @@ -263,12 +214,12 @@ json_boxed_can_serialize (GType gboxed_type, /** * json_boxed_can_deserialize: * @gboxed_type: a boxed type - * @node_type: a #JsonNode type + * @node_type: a node type * - * Checks whether it is possible to deserialize a #GBoxed of - * type @gboxed_type from a #JsonNode of type @node_type + * Checks whether it is possible to deserialize a `GBoxed` of + * type `gboxed_type` from a [struct@Json.Node] of type `node_type`. * - * Return value: %TRUE if the type can be deserialized, %FALSE otherwise + * Return value: `TRUE` if the type can be deserialized, and `FALSE` otherwise * * Since: 0.10 */ @@ -291,13 +242,13 @@ json_boxed_can_deserialize (GType gboxed_type, /** * json_boxed_serialize: * @gboxed_type: a boxed type - * @boxed: a pointer to a #GBoxed of type @gboxed_type + * @boxed: a pointer to a boxed of type `gboxed_type` + * + * Serializes a pointer to a `GBoxed` of the given type into a [struct@Json.Node]. * - * Serializes @boxed, a pointer to a #GBoxed of type @gboxed_type, - * into a #JsonNode + * If the serialization is not possible, this function will return `NULL`. * - * Return value: (nullable) (transfer full): a #JsonNode with the serialization of - * the boxed type, or %NULL if serialization either failed or was not possible + * Return value: (nullable) (transfer full): a node with the serialized boxed type * * Since: 0.10 */ @@ -321,13 +272,11 @@ json_boxed_serialize (GType gboxed_type, /** * json_boxed_deserialize: * @gboxed_type: a boxed type - * @node: a #JsonNode + * @node: a node * - * Deserializes @node into a #GBoxed of @gboxed_type + * Deserializes the given [struct@Json.Node] into a `GBoxed` of the given type. * - * Return value: (transfer full): the newly allocated #GBoxed. Use - * g_boxed_free() to release the resources allocated by this - * function + * Return value: (transfer full): the newly allocated boxed data * * Since: 0.10 */ diff --git a/json-glib/json-generator.c b/json-glib/json-generator.c index 4ccf320..fc8dcfc 100644 --- a/json-glib/json-generator.c +++ b/json-glib/json-generator.c @@ -22,11 +22,11 @@ */ /** - * SECTION:json-generator - * @short_description: Generates JSON data streams + * JsonGenerator: * - * #JsonGenerator provides an object for generating a JSON data stream and - * put it into a buffer or a file. + * `JsonGenerator` provides an object for generating a JSON data stream + * from a tree of [struct@Json.Node] instances, and put it into a buffer + * or a file. */ #include "config.h" @@ -203,11 +203,13 @@ json_generator_class_init (JsonGeneratorClass *klass) GObjectClass *gobject_class = G_OBJECT_CLASS (klass); /** - * JsonGenerator:pretty: + * JsonGenerator:pretty: (attributes org.gtk.Property.get=json_generator_get_pretty org.gtk.Property.set=json_generator_set_pretty) * * Whether the output should be "pretty-printed", with indentation and - * newlines. The indentation level can be controlled by using the - * JsonGenerator:indent property + * newlines. + * + * The indentation level can be controlled by using the + * [property@Json.Generator:indent] property. */ generator_props[PROP_PRETTY] = g_param_spec_boolean ("pretty", @@ -217,7 +219,7 @@ json_generator_class_init (JsonGeneratorClass *klass) G_PARAM_READWRITE); /** - * JsonGenerator:indent: + * JsonGenerator:indent: (attributes org.gtk.Property.get=json_generator_get_indent org.gtk.Property.set=json_generator_set_indent) * * Number of spaces to be used to indent when pretty printing. */ @@ -230,9 +232,9 @@ json_generator_class_init (JsonGeneratorClass *klass) G_PARAM_READWRITE); /** - * JsonGenerator:root: + * JsonGenerator:root: (attributes org.gtk.Property.get=json_generator_get_root org.gtk.Property.set=json_generator_set_root) * - * The root #JsonNode to be used when constructing a JSON data + * The root node to be used when constructing a JSON data * stream. * * Since: 0.4 @@ -245,7 +247,7 @@ json_generator_class_init (JsonGeneratorClass *klass) G_PARAM_READWRITE); /** - * JsonGenerator:indent-char: + * JsonGenerator:indent-char: (attributes org.gtk.Property.get=json_generator_get_indent_char org.gtk.Property.set=json_generator_set_indent_char) * * The character that should be used when indenting in pretty print. * @@ -469,11 +471,12 @@ dump_object (JsonGenerator *generator, /** * json_generator_new: * - * Creates a new #JsonGenerator. You can use this object to generate a - * JSON data stream starting from a data object model composed by - * #JsonNodes. + * Creates a new `JsonGenerator`. + * + * You can use this object to generate a JSON data stream starting from a + * data object model composed by [struct@Json.Node]s. * - * Return value: the newly created #JsonGenerator instance + * Return value: the newly created generator instance */ JsonGenerator * json_generator_new (void) @@ -483,14 +486,13 @@ json_generator_new (void) /** * json_generator_to_gstring: - * @generator: a #JsonGenerator - * @string: a #GString + * @generator: a generator + * @string: a string buffer * - * Generates a JSON data stream from @generator - * and appends it to @string. + * Generates a JSON data stream and appends it to the string buffer. * - * Return value: (transfer none): a #GString holding a JSON data stream. - * Use g_string_free() to free the allocated resources. + * Return value: (transfer none): the passed string, updated with + * the generated JSON data * * Since: 1.4 */ @@ -512,15 +514,14 @@ json_generator_to_gstring (JsonGenerator *generator, /** * json_generator_to_data: - * @generator: a #JsonGenerator - * @length: (out): return location for the length of the returned - * buffer, or %NULL + * @generator: a generator + * @length: (out) (optional): return location for the length of the returned + * buffer * * Generates a JSON data stream from @generator and returns it as a * buffer. * - * Return value: a newly allocated buffer holding a JSON data stream. - * Use g_free() to free the allocated resources. + * Return value: (transfer full): a newly allocated string holding a JSON data stream */ gchar * json_generator_to_data (JsonGenerator *generator, @@ -541,12 +542,15 @@ json_generator_to_data (JsonGenerator *generator, /** * json_generator_to_file: - * @generator: a #JsonGenerator - * @filename: path to the target file + * @generator: a generator + * @filename: (type filename): the path to the target file * @error: return location for a #GError, or %NULL * - * Creates a JSON data stream and puts it inside @filename, overwriting the - * current file contents. This operation is atomic. + * Creates a JSON data stream and puts it inside `filename`, overwriting + * the file's current contents. + * + * This operation is atomic, in the sense that the data is written to a + * temporary file which is then renamed to the given `filename`. * * Return value: %TRUE if saving was successful. */ @@ -571,15 +575,14 @@ json_generator_to_file (JsonGenerator *generator, /** * json_generator_to_stream: - * @generator: a #JsonGenerator - * @stream: a #GOutputStream - * @cancellable: (allow-none): a #GCancellable, or %NULL + * @generator: a generator + * @stream: the output stream used to write the JSON data + * @cancellable: (nullable): a `GCancellable` * @error: return location for a #GError, or %NULL * - * Outputs JSON data and streams it (synchronously) to @stream. + * Outputs JSON data and writes it (synchronously) to the given stream. * - * Return value: %TRUE if the write operation was successful, and %FALSE - * on failure. In case of error, the #GError will be filled accordingly + * Return value: whether the write operation was successful * * Since: 0.12 */ @@ -607,14 +610,14 @@ json_generator_to_stream (JsonGenerator *generator, } /** - * json_generator_set_root: - * @generator: a #JsonGenerator - * @node: a #JsonNode + * json_generator_set_root: (attributes org.gtk.Method.set_property=root) + * @generator: a generator + * @node: the root node * - * Sets @node as the root of the JSON data stream to be serialized by - * the #JsonGenerator. + * Sets the root of the JSON data stream to be serialized by + * the given generator. * - * The passed @node is copied by the generator object, so it can be + * The passed `node` is copied by the generator object, so it can be * safely freed after calling this function. */ void @@ -639,14 +642,13 @@ json_generator_set_root (JsonGenerator *generator, } /** - * json_generator_get_root: - * @generator: a #JsonGenerator + * json_generator_get_root: (attributes org.gtk.Method.get_property=root) + * @generator: a generator * - * Retrieves a pointer to the root #JsonNode set using - * json_generator_set_root(). + * Retrieves a pointer to the root node set using + * [method@Json.Generator.set_root]. * - * Return value: (nullable) (transfer none): a #JsonNode, or %NULL. The returned - * node is owned by the #JsonGenerator and it should not be freed + * Return value: (nullable) (transfer none): the root node * * Since: 0.14 */ @@ -659,13 +661,15 @@ json_generator_get_root (JsonGenerator *generator) } /** - * json_generator_set_pretty: - * @generator: a #JsonGenerator + * json_generator_set_pretty: (attributes org.gtk.Method.set_property=pretty) + * @generator: a generator * @is_pretty: whether the generated string should be pretty printed * - * Sets whether the generated JSON should be pretty printed, using the - * indentation character specified in the #JsonGenerator:indent-char - * property and the spacing specified in #JsonGenerator:indent property. + * Sets whether the generated JSON should be pretty printed. + * + * Pretty printing will use indentation character specified in the + * [property@Json.Generator:indent-char] property and the spacing + * specified in the [property@Json.Generator:indent] property. * * Since: 0.14 */ @@ -690,13 +694,13 @@ json_generator_set_pretty (JsonGenerator *generator, } /** - * json_generator_get_pretty: - * @generator: a #JsonGenerator + * json_generator_get_pretty: (attributes org.gtk.Method.get_property=pretty) + * @generator: a generator * - * Retrieves the value set using json_generator_set_pretty(). + * Retrieves the value set using [method@Json.Generator.set_pretty]. * - * Return value: %TRUE if the generated JSON should be pretty-printed, and - * %FALSE otherwise + * Return value: `TRUE` if the generated JSON should be pretty-printed, and + * `FALSE` otherwise * * Since: 0.14 */ @@ -709,8 +713,8 @@ json_generator_get_pretty (JsonGenerator *generator) } /** - * json_generator_set_indent: - * @generator: a #JsonGenerator + * json_generator_set_indent: (attributes org.gtk.Method.set_property=indent) + * @generator: a generator * @indent_level: the number of repetitions of the indentation character * that should be applied when pretty printing * @@ -737,10 +741,10 @@ json_generator_set_indent (JsonGenerator *generator, } /** - * json_generator_get_indent: - * @generator: a #JsonGenerator + * json_generator_get_indent: (attributes org.gtk.Method.get_property=indent) + * @generator: a generator * - * Retrieves the value set using json_generator_set_indent(). + * Retrieves the value set using [method@Json.Generator.set_indent]. * * Return value: the number of repetitions per indentation level * @@ -749,17 +753,17 @@ json_generator_set_indent (JsonGenerator *generator, guint json_generator_get_indent (JsonGenerator *generator) { - g_return_val_if_fail (JSON_IS_GENERATOR (generator), FALSE); + g_return_val_if_fail (JSON_IS_GENERATOR (generator), 0); return generator->priv->indent; } /** - * json_generator_set_indent_char: - * @generator: a #JsonGenerator + * json_generator_set_indent_char: (attributes org.gtk.Method.set_property=indent-char) + * @generator: a generator * @indent_char: a Unicode character to be used when indenting * - * Sets the character to be used when indenting + * Sets the character to be used when indenting. * * Since: 0.14 */ @@ -782,10 +786,10 @@ json_generator_set_indent_char (JsonGenerator *generator, } /** - * json_generator_get_indent_char: - * @generator: a #JsonGenerator + * json_generator_get_indent_char: (attributes org.gtk.Method.get_property=indent-char) + * @generator: a generator * - * Retrieves the value set using json_generator_set_indent_char(). + * Retrieves the value set using [method@Json.Generator.set_indent_char]. * * Return value: the character to be used when indenting * diff --git a/json-glib/json-generator.h b/json-glib/json-generator.h index 30a28dc..8f62ba3 100644 --- a/json-glib/json-generator.h +++ b/json-glib/json-generator.h @@ -44,12 +44,6 @@ typedef struct _JsonGenerator JsonGenerator; typedef struct _JsonGeneratorPrivate JsonGeneratorPrivate; typedef struct _JsonGeneratorClass JsonGeneratorClass; -/** - * JsonGenerator: - * - * JSON data streams generator. The contents of the #JsonGenerator structure - * are private and should only be accessed via the provided API. - */ struct _JsonGenerator { /*< private >*/ @@ -58,11 +52,6 @@ struct _JsonGenerator JsonGeneratorPrivate *priv; }; -/** - * JsonGeneratorClass: - * - * #JsonGenerator class - */ struct _JsonGeneratorClass { /*< private >*/ diff --git a/json-glib/json-gobject.c b/json-glib/json-gobject.c index b42dc83..5b7331c 100644 --- a/json-glib/json-gobject.c +++ b/json-glib/json-gobject.c @@ -17,21 +17,6 @@ * Emmanuele Bassi */ -/** - * SECTION:json-gobject - * @short_description: Serialize and deserialize GObjects - * - * JSON-GLib provides API for serializing and deserializing #GObject - * instances to and from JSON data streams. - * - * Simple #GObject classes can be (de)serialized into JSON objects, if the - * properties have compatible types with the native JSON types (integers, - * booleans, strings, string vectors). If the class to be (de)serialized has - * complex data types for properties (like boxed types or other objects) - * then the class should implement the provided #JsonSerializable interface - * and its virtual functions. - */ - #include "config.h" #include @@ -57,8 +42,8 @@ enum_from_string (GType type, gint value; gboolean retval = TRUE; - g_return_val_if_fail (G_TYPE_IS_ENUM (type), 0); - g_return_val_if_fail (string != NULL, 0); + g_return_val_if_fail (G_TYPE_IS_ENUM (type), FALSE); + g_return_val_if_fail (string != NULL, FALSE); value = strtoul (string, &endptr, 0); if (endptr != string) /* parsed a number */ @@ -95,8 +80,8 @@ flags_from_string (GType type, gunichar ch; gboolean eos; - g_return_val_if_fail (G_TYPE_IS_FLAGS (type), 0); - g_return_val_if_fail (string != 0, 0); + g_return_val_if_fail (G_TYPE_IS_FLAGS (type), FALSE); + g_return_val_if_fail (string != 0, FALSE); ret = TRUE; @@ -799,16 +784,14 @@ json_serialize_pspec (const GValue *real_value, /** * json_gobject_deserialize: - * @gtype: the type of the #GObject to create - * @node: a #JsonNode of type %JSON_NODE_OBJECT describing the - * instance of type @gtype + * @gtype: the type of the object to create + * @node: a node of type `JSON_NODE_OBJECT` describing the + * object instance for the given type * - * Creates a new #GObject of type @gtype, and constructs it - * using the members of the passed #JsonObject + * Creates a new `GObject` instance of the given type, and constructs it + * using the members of the object in the given node. * - * Return value: (transfer full): The newly created #GObject - * instance. Use g_object_unref() to free the resources - * allocated by this function + * Return value: (transfer full): The newly created instance * * Since: 0.10 */ @@ -824,15 +807,17 @@ json_gobject_deserialize (GType gtype, /** * json_gobject_serialize: - * @gobject: a #GObject + * @gobject: the object to serialize * - * Creates a #JsonNode representing the passed #GObject - * instance. Each member of the returned JSON object will - * map to a property of the #GObject + * Creates a JSON tree representing the passed object instance. * - * Return value: (transfer full): the newly created #JsonNode - * of type %JSON_NODE_OBJECT. Use json_node_unref() to free - * the resources allocated by this function + * Each member of the returned JSON object will map to a property of + * the object type. + * + * The returned JSON tree will be returned as a `JsonNode` with a type + * of `JSON_NODE_OBJECT`. + * + * Return value: (transfer full): the newly created JSON tree * * Since: 0.10 */ @@ -851,24 +836,26 @@ json_gobject_serialize (GObject *gobject) /** * json_construct_gobject: - * @gtype: the #GType of object to construct + * @gtype: the type of the object to construct * @data: a JSON data stream * @length: length of the data stream * @error: return location for a #GError, or %NULL * - * Deserializes a JSON data stream and creates the corresponding - * #GObject class. If @gtype implements the #JsonSerializableIface - * interface, it will be asked to deserialize all the JSON members - * into the respective properties; otherwise, the default implementation - * will be used to translate the compatible JSON native types. + * Deserializes a JSON data stream and creates an instance of the given + * type + * + * If the given type implements the [iface@Json.Serializable] interface, it + * will be asked to deserialize all the JSON members into their respective + * properties; otherwise, the default implementation will be used to translate + * the compatible JSON native types. * - * Note: the JSON data stream must be an object declaration. + * **Note**: the JSON data stream must be an object. * - * Return value: (transfer full): a #GObject or %NULL + * Return value: (transfer full) (nullable): a new object instance of the given type * * Since: 0.4 * - * Deprecated: 0.10: Use json_gobject_from_data() instead + * Deprecated: 0.10: Use [func@Json.gobject_from_data] instead */ GObject * json_construct_gobject (GType gtype, @@ -881,20 +868,22 @@ json_construct_gobject (GType gtype, /** * json_gobject_from_data: - * @gtype: the #GType of object to construct + * @gtype: the type of the object to construct * @data: a JSON data stream - * @length: length of the data stream, or -1 if it is NUL-terminated + * @length: length of the data stream, or -1 if it is `NUL`-terminated * @error: return location for a #GError, or %NULL * - * Deserializes a JSON data stream and creates the corresponding - * #GObject class. If @gtype implements the #JsonSerializableIface - * interface, it will be asked to deserialize all the JSON members - * into the respective properties; otherwise, the default implementation - * will be used to translate the compatible JSON native types. + * Deserializes a JSON data stream and creates an instance of the + * given type. * - * Note: the JSON data stream must be an object declaration. + * If the type implements the [iface@Json.Serializable] interface, it will + * be asked to deserialize all the JSON members into their respective properties; + * otherwise, the default implementation will be used to translate the + * compatible JSON native types. * - * Return value: (transfer full): a #GObject or %NULL + * **Note**: the JSON data stream must be an object + * + * Return value: (transfer full) (nullable): a new object instance of the given type * * Since: 0.10 */ @@ -947,17 +936,19 @@ json_gobject_from_data (GType gtype, /** * json_serialize_gobject: - * @gobject: a #GObject - * @length: (out): return value for the length of the buffer, or %NULL + * @gobject: the object to serialize + * @length: (out) (optional): return value for the length of the buffer + * + * Serializes a `GObject` instance into a JSON data stream. * - * Serializes a #GObject into a JSON data stream. If @gobject implements - * the #JsonSerializableIface interface, it will be asked to serizalize all - * its properties; otherwise, the default implementation will be use to - * translate the compatible types into JSON native types. + * If the object implements the [iface@Json.Serializable] interface, it will be + * asked to serizalize all its properties; otherwise, the default + * implementation will be use to translate the compatible types into JSON + * native types. * - * Return value: a JSON data stream representing the passed #GObject + * Return value: (transfer full): a JSON data stream representing the given object * - * Deprecated: 0.10: Use json_gobject_to_data() instead + * Deprecated: 0.10: Use [func@Json.gobject_to_data] instead */ gchar * json_serialize_gobject (GObject *gobject, @@ -968,18 +959,18 @@ json_serialize_gobject (GObject *gobject, /** * json_gobject_to_data: - * @gobject: a #GObject - * @length: (out): return value for the length of the buffer, or %NULL + * @gobject: the object to serialize + * @length: (out) (optional): return value for the length of the buffer * - * Serializes a #GObject into a JSON data stream, iterating recursively - * over each property. + * Serializes a `GObject` instance into a JSON data stream, iterating + * recursively over each property. * - * If @gobject implements the #JsonSerializableIface interface, it will - * be asked to serialize all its properties; otherwise, the default + * If the given object implements the [iface@Json.Serializable] interface, + * it will be asked to serialize all its properties; otherwise, the default * implementation will be use to translate the compatible types into * JSON native types. * - * Return value: a JSON data stream representing the passed #GObject + * Return value: a JSON data stream representing the given object * * Since: 0.10 */ diff --git a/json-glib/json-gobject.h b/json-glib/json-gobject.h index 47ac125..5fc0c63 100644 --- a/json-glib/json-gobject.h +++ b/json-glib/json-gobject.h @@ -38,10 +38,10 @@ typedef struct _JsonSerializableIface JsonSerializableIface; /** * JsonSerializableIface: - * @serialize_property: virtual function for serializing a #GObject property - * into a #JsonNode - * @deserialize_property: virtual function for deserializing a #JsonNode - * into a #GObject property + * @serialize_property: virtual function for serializing an object property + * into JSON + * @deserialize_property: virtual function for deserializing JSON + * into an object property * @find_property: virtual function for finding a property definition using * its name * @list_properties: virtual function for listing the installed property @@ -49,9 +49,11 @@ typedef struct _JsonSerializableIface JsonSerializableIface; * @set_property: virtual function for setting a property * @get_property: virtual function for getting a property * - * Interface that allows serializing and deserializing #GObject instances - * with properties storing complex data types. The json_serialize_gobject() - * function will check if the passed #GObject implements this interface, + * Interface that allows serializing and deserializing object instances + * with properties storing complex data types. + * + * The [func@Json.gobject_from_data] and [func@Json.gobject_to_data] + * functions will check if the passed object type implements this interface, * so it can also be used to override the default property serialization * sequence. */ @@ -127,11 +129,30 @@ gboolean json_serializable_default_deserialize_property (JsonSerializable *seri /** * JsonBoxedSerializeFunc: - * @boxed: a #GBoxed + * @boxed: a boxed data structure + * + * Serializes the passed `GBoxed` and stores it inside a `JsonNode`, for instance: + * + * ```c + * static JsonNode * + * my_point_serialize (gconstpointer boxed) + * { + * const MyPoint *point = boxed; + * + * g_autoptr(JsonBuilder) builder = json_builder_new (); + * + * json_builder_begin_object (builder); + * json_builder_set_member_name (builder, "x"); + * json_builder_add_double_value (builder, point->x); + * json_builder_set_member_name (builder, "y"); + * json_builder_add_double_value (builder, point->y); + * json_builder_end_object (builder); * - * Serializes the passed #GBoxed and stores it inside a #JsonNode + * return json_builder_get_root (builder); + * } + * ``` * - * Return value: the newly created #JsonNode + * Return value: the newly created JSON node tree representing the boxed data * * Since: 0.10 */ @@ -139,11 +160,40 @@ typedef JsonNode *(* JsonBoxedSerializeFunc) (gconstpointer boxed); /** * JsonBoxedDeserializeFunc: - * @node: a #JsonNode + * @node: a node tree representing a boxed data + * + * Deserializes the contents of the passed `JsonNode` into a `GBoxed`, for instance: + * + * ```c + * static gpointer + * my_point_deserialize (JsonNode *node) + * { + * double x = 0.0, y = 0.0; + * + * if (JSON_NODE_HOLDS_ARRAY (node)) + * { + * JsonArray *array = json_node_get_array (node); + * + * if (json_array_get_length (array) == 2) + * { + * x = json_array_get_double_element (array, 0); + * y = json_array_get_double_element (array, 1); + * } + * } + * else if (JSON_NODE_HOLDS_OBJECT (node)) + * { + * JsonObject *obj = json_node_get_object (node); + * + * x = json_object_get_double_member_with_default (obj, "x", 0.0); + * y = json_object_get_double_member_with_default (obj, "y", 0.0); + * } * - * Deserializes the contents of the passed #JsonNode into a #GBoxed + * // my_point_new() is defined elsewhere + * return my_point_new (x, y); + * } + * ``` * - * Return value: the newly created boxed type + * Return value: the newly created boxed structure * * Since: 0.10 */ diff --git a/json-glib/json-gvariant.c b/json-glib/json-gvariant.c index 72df81d..15f03f5 100644 --- a/json-glib/json-gvariant.c +++ b/json-glib/json-gvariant.c @@ -33,48 +33,6 @@ #include "json-parser.h" #include "json-types-private.h" -/** - * SECTION:json-gvariant - * @short_description: Serialize and deserialize GVariant types - * @Title: JSON GVariant Integration - * - * Use json_gvariant_serialize() and json_gvariant_serialize_data() to - * convert from any #GVariant value to a #JsonNode tree or its string - * representation. - * - * Use json_gvariant_deserialize() and json_gvariant_deserialize_data() to - * obtain the #GVariant value from a #JsonNode tree or directly from a JSON - * string. - * - * Since many #GVariant data types cannot be directly represented as - * JSON, a #GVariant type string (signature) should be provided to these - * methods in order to obtain a correct, type-contrained result. - * If no signature is provided, conversion can still be done, but the - * resulting #GVariant value will be "guessed" from the JSON data types - * using the following rules: - * - * ## Strings - * JSON strings map to GVariant `(s)`. - * - * ## Integers - * JSON integers map to GVariant int64 `(x)`. - * - * ## Booleans - * JSON booleans map to GVariant boolean `(b)`. - * - * ## Numbers - * JSON numbers map to GVariant double `(d)`. - * - * ## Arrays - * JSON arrays map to GVariant arrays of variants `(av)`. - * - * ## Objects - * JSON objects map to GVariant dictionaries of string to variants `(a{sv})`. - * - * ## Null values - * JSON null values map to GVariant maybe variants `(mv)`. - */ - /* custom extension to the GVariantClass enumeration to differentiate * a single dictionary entry from an array of dictionary entries */ @@ -257,12 +215,12 @@ gvariant_to_json_object (GVariant *variant) /** * json_gvariant_serialize: - * @variant: A #GVariant to convert + * @variant: A `GVariant` to convert * - * Converts @variant to a JSON tree. + * Converts `variant` to a JSON tree. * - * Return value: (transfer full): A #JsonNode representing the root of the - * JSON data structure obtained from @variant + * Return value: (transfer full): the root of the JSON data structure + * obtained from `variant` * * Since: 0.14 */ @@ -413,15 +371,15 @@ json_gvariant_serialize (GVariant *variant) /** * json_gvariant_serialize_data: * @variant: A #GVariant to convert - * @length: (out) (allow-none): Return location for the length of the returned - * string, or %NULL + * @length: (out) (optional): the length of the returned string * - * Converts @variant to its JSON encoded string representation. This method - * is actually a helper function. It uses json_gvariant_serialize() to obtain the - * JSON tree, and then #JsonGenerator to stringify it. + * Converts @variant to its JSON encoded string representation. + * + * This is a convenience function around [func@Json.gvariant_serialize], to + * obtain the JSON tree, and then [class@Json.Generator] to stringify it. * * Return value: (transfer full): The JSON encoded string corresponding to - * @variant + * the given variant * * Since: 0.14 */ @@ -1274,26 +1232,32 @@ out: /** * json_gvariant_deserialize: - * @json_node: A #JsonNode to convert - * @signature: (allow-none): A valid #GVariant type string, or %NULL - * @error: A pointer to a #GError + * @json_node: the node to convert + * @signature: (nullable): a valid `GVariant` type string + * @error: (nullable): return location for a #GError, or `NULL` + * + * Converts a JSON data structure to a `GVariant`. * - * Converts a JSON data structure to a GVariant value using @signature to - * resolve ambiguous data types. If no error occurs, the resulting #GVariant - * is guaranteed to conform to @signature. + * If `signature` is not `NULL`, it will be used to resolve ambiguous + * data types. * - * If @signature is not %NULL but does not represent a valid GVariant type - * string, %NULL is returned and error is set to %G_IO_ERROR_INVALID_ARGUMENT. - * If a @signature is provided but the JSON structure cannot be mapped to it, - * %NULL is returned and error is set to %G_IO_ERROR_INVALID_DATA. - * If @signature is %NULL, the conversion is done based strictly on the types + * If no error occurs, the resulting `GVariant` is guaranteed to conform + * to `signature`. + * + * If `signature` is not `NULL` but does not represent a valid `GVariant` type + * string, `NULL` is returned and the `error` is set to + * `G_IO_ERROR_INVALID_ARGUMENT`. + * + * If a `signature` is provided but the JSON structure cannot be mapped to it, + * `NULL` is returned and the `error` is set to `G_IO_ERROR_INVALID_DATA`. + * + * If `signature` is `NULL`, the conversion is done based strictly on the types * in the JSON nodes. * * The returned variant has a floating reference that will need to be sunk * by the caller code. * - * Return value: (transfer none): A newly created, floating #GVariant - * compliant with @signature, or %NULL on error + * Return value: (transfer floating) (nullable): A newly created `GVariant` * * Since: 0.14 */ @@ -1319,20 +1283,23 @@ json_gvariant_deserialize (JsonNode *json_node, /** * json_gvariant_deserialize_data: * @json: A JSON data string - * @length: The length of @json, or -1 if %NULL-terminated - * @signature: (allow-none): A valid #GVariant type string, or %NULL + * @length: The length of @json, or -1 if `NUL`-terminated + * @signature: (nullable): A valid `GVariant` type string * @error: A pointer to a #GError * - * Converts a JSON string to a #GVariant value. This method works exactly - * like json_gvariant_deserialize(), but takes a JSON encoded string instead. - * The string is first converted to a #JsonNode using #JsonParser, and then - * json_gvariant_deserialize() is called. + * Converts a JSON string to a `GVariant` value. + * + * This function works exactly like [func@Json.gvariant_deserialize], but + * takes a JSON encoded string instead. + * + * The string is first converted to a [struct@Json.Node] using + * [class@Json.Parser], and then `json_gvariant_deserialize` is called on + * the node. * * The returned variant has a floating reference that will need to be sunk * by the caller code. * - * Returns: (transfer none): A newly created, floating #GVariant compliant - * with @signature, or %NULL on error + * Returns: (transfer floating) (nullable): A newly created `GVariant`D compliant * * Since: 0.14 */ diff --git a/json-glib/json-node.c b/json-glib/json-node.c index a6898d9..2737453 100644 --- a/json-glib/json-node.c +++ b/json-glib/json-node.c @@ -32,51 +32,54 @@ #include "json-debug.h" /** - * SECTION:json-node - * @short_description: Node in a JSON object model + * JsonNode: * - * A #JsonNode is a generic container of elements inside a JSON stream. - * It can contain fundamental types (integers, booleans, floating point + * A generic container of JSON data types. + * + * `JsonNode` can contain fundamental types (integers, booleans, floating point * numbers, strings) and complex types (arrays and objects). * * When parsing a JSON data stream you extract the root node and walk * the node tree by retrieving the type of data contained inside the - * node with the %JSON_NODE_TYPE macro. If the node contains a fundamental - * type you can retrieve a copy of the #GValue holding it with the - * json_node_get_value() function, and then use the #GValue API to extract + * node with the `JSON_NODE_TYPE` macro. If the node contains a fundamental + * type you can retrieve a copy of the `GValue` holding it with the + * [method@Json.Node.get_value] function, and then use the `GValue` API to extract * the data; if the node contains a complex type you can retrieve the - * #JsonObject or the #JsonArray using json_node_get_object() or - * json_node_get_array() respectively, and then retrieve the nodes + * [struct@Json.Object] or the [struct@Json.Array] using [method@Json.Node.get_object] + * or [method@Json.Node.get_array] respectively, and then retrieve the nodes * they contain. * - * A #JsonNode may be marked as immutable using json_node_seal(). This marks the - * node and all its descendents as read-only, and means that subsequent calls to - * setter functions (such as json_node_set_array()) on them will abort as a - * programmer error. By marking a node tree as immutable, it may be referenced - * in multiple places and its hash value cached for fast lookups, without the - * possibility of a value deep within the tree changing and affecting hash - * values. Immutable #JsonNodes may be passed to functions which retain a - * reference to them without needing to take a copy. - * - * #JsonNode supports two types of memory management: alloc/free semantics, and - * ref/unref semantics. The two may be mixed to a limited extent: nodes may be - * allocated (which gives them a reference count of 1), referenced zero or more - * times, unreferenced exactly that number of times (using json_node_unref()), - * then either unreferenced exactly once more or freed (using json_node_free()) - * to destroy them. json_node_free() must not be used when a node might have a - * reference count not equal to 1. To this end, json-glib uses json_node_copy() - * and json_node_unref() internally. + * A `JsonNode` may be marked as immutable using [method@Json.Node.seal]. This + * marks the node and all its descendents as read-only, and means that + * subsequent calls to setter functions (such as [method@Json.Node.set_array]) + * on them will abort as a programmer error. By marking a node tree as + * immutable, it may be referenced in multiple places and its hash value cached + * for fast lookups, without the possibility of a value deep within the tree + * changing and affecting hash values. Immutable nodes may be passed to + * functions which retain a reference to them without needing to take a copy. + * + * A `JsonNode` supports two types of memory management: `malloc`/`free` + * semantics, and reference counting semantics. The two may be mixed to a + * limited extent: nodes may be allocated (which gives them a reference count + * of 1), referenced one or more times, unreferenced exactly that number of + * times (using [method@Json.Node.unref]), then either unreferenced exactly + * once more or freed (using [method@Json.Node.free]) to destroy them. + * The [method@Json.Node.free] function must not be used when a node might + * have a reference count not equal to 1. To this end, JSON-GLib uses + * [method@Json.Node.copy] and [method@Json.Node.unref] internally. */ -G_DEFINE_BOXED_TYPE (JsonNode, json_node, json_node_copy, json_node_unref); +G_DEFINE_BOXED_TYPE (JsonNode, json_node, json_node_copy, json_node_unref) /** * json_node_get_value_type: - * @node: a #JsonNode + * @node: the node to check + * + * Returns the `GType` of the payload of the node. * - * Returns the #GType of the payload of the node. + * For `JSON_NODE_NULL` nodes, the returned type is `G_TYPE_INVALID`. * - * Return value: a #GType for the payload. + * Return value: the type for the payload * * Since: 0.4 */ @@ -111,11 +114,11 @@ json_node_get_value_type (JsonNode *node) /** * json_node_alloc: (constructor) * - * Allocates a new #JsonNode. Use json_node_init() and its variants - * to initialize the returned value. + * Allocates a new, uninitialized node. + * + * Use [method@Json.Node.init] and its variants to initialize the returned value. * - * Return value: (transfer full): the newly allocated #JsonNode. Use - * json_node_free() to free the resources allocated by this function + * Return value: (transfer full): the newly allocated node * * Since: 0.16 */ @@ -162,7 +165,7 @@ json_node_unset (JsonNode *node) /** * json_node_init: - * @node: the #JsonNode to initialize + * @node: the node to initialize * @type: the type of JSON node to initialize @node to * * Initializes a @node to a specific @type. @@ -170,7 +173,7 @@ json_node_unset (JsonNode *node) * If the node has already been initialized once, it will be reset to * the given type, and any data contained will be cleared. * - * Return value: (transfer none): the initialized #JsonNode + * Return value: (transfer none): the initialized node * * Since: 0.16 */ @@ -191,17 +194,17 @@ json_node_init (JsonNode *node, /** * json_node_init_object: - * @node: the #JsonNode to initialize - * @object: (allow-none): the #JsonObject to initialize @node with, or %NULL + * @node: the node to initialize + * @object: (nullable): the JSON object to initialize @node with, or `NULL` * - * Initializes @node to %JSON_NODE_OBJECT and sets @object into it. + * Initializes @node to `JSON_NODE_OBJECT` and sets @object into it. * * This function will take a reference on @object. * * If the node has already been initialized once, it will be reset to * the given type, and any data contained will be cleared. * - * Return value: (transfer none): the initialized #JsonNode + * Return value: (transfer none): the initialized node * * Since: 0.16 */ @@ -219,17 +222,17 @@ json_node_init_object (JsonNode *node, /** * json_node_init_array: - * @node: the #JsonNode to initialize - * @array: (allow-none): the #JsonArray to initialize @node with, or %NULL + * @node: the node to initialize + * @array: (nullable): the JSON array to initialize @node with, or `NULL` * - * Initializes @node to %JSON_NODE_ARRAY and sets @array into it. + * Initializes @node to `JSON_NODE_ARRAY` and sets @array into it. * * This function will take a reference on @array. * * If the node has already been initialized once, it will be reset to * the given type, and any data contained will be cleared. * - * Return value: (transfer none): the initialized #JsonNode + * Return value: (transfer none): the initialized node * * Since: 0.16 */ @@ -247,15 +250,15 @@ json_node_init_array (JsonNode *node, /** * json_node_init_int: - * @node: the #JsonNode to initialize + * @node: the node to initialize * @value: an integer * - * Initializes @node to %JSON_NODE_VALUE and sets @value into it. + * Initializes @node to `JSON_NODE_VALUE` and sets @value into it. * * If the node has already been initialized once, it will be reset to * the given type, and any data contained will be cleared. * - * Return value: (transfer none): the initialized #JsonNode + * Return value: (transfer none): the initialized node * * Since: 0.16 */ @@ -273,15 +276,15 @@ json_node_init_int (JsonNode *node, /** * json_node_init_double: - * @node: the #JsonNode to initialize + * @node: the node to initialize * @value: a floating point value * - * Initializes @node to %JSON_NODE_VALUE and sets @value into it. + * Initializes @node to `JSON_NODE_VALUE` and sets @value into it. * * If the node has already been initialized once, it will be reset to * the given type, and any data contained will be cleared. * - * Return value: (transfer none): the initialized #JsonNode + * Return value: (transfer none): the initialized node * * Since: 0.16 */ @@ -299,15 +302,15 @@ json_node_init_double (JsonNode *node, /** * json_node_init_boolean: - * @node: the #JsonNode to initialize + * @node: the node to initialize * @value: a boolean value * - * Initializes @node to %JSON_NODE_VALUE and sets @value into it. + * Initializes @node to `JSON_NODE_VALUE` and sets @value into it. * * If the node has already been initialized once, it will be reset to * the given type, and any data contained will be cleared. * - * Return value: (transfer none): the initialized #JsonNode + * Return value: (transfer none): the initialized node * * Since: 0.16 */ @@ -325,15 +328,15 @@ json_node_init_boolean (JsonNode *node, /** * json_node_init_string: - * @node: the #JsonNode to initialize - * @value: (allow-none): a string value + * @node: the node to initialize + * @value: (nullable): a string value * - * Initializes @node to %JSON_NODE_VALUE and sets @value into it. + * Initializes @node to `JSON_NODE_VALUE` and sets @value into it. * * If the node has already been initialized once, it will be reset to * the given type, and any data contained will be cleared. * - * Return value: (transfer none): the initialized #JsonNode + * Return value: (transfer none): the initialized node * * Since: 0.16 */ @@ -351,14 +354,14 @@ json_node_init_string (JsonNode *node, /** * json_node_init_null: - * @node: the #JsonNode to initialize + * @node: the node to initialize * - * Initializes @node to %JSON_NODE_NULL. + * Initializes @node to `JSON_NODE_NULL`. * * If the node has already been initialized once, it will be reset to * the given type, and any data contained will be cleared. * - * Return value: (transfer none): the initialized #JsonNode + * Return value: (transfer none): the initialized node * * Since: 0.16 */ @@ -372,18 +375,18 @@ json_node_init_null (JsonNode *node) /** * json_node_new: (constructor) - * @type: a #JsonNodeType + * @type: the type of the node to create * - * Creates a new #JsonNode of @type. + * Creates a new node holding the given @type. * - * This is a convenience function for json_node_alloc() and json_node_init(), - * and it's the equivalent of: + * This is a convenience function for [ctor@Json.Node.alloc] and + * [method@Json.Node.init], and it's the equivalent of: * - * |[ - json_node_init (json_node_alloc (), type); - * ]| + * ```c + json_node_init (json_node_alloc (), type); + * ``` * - * Return value: (transfer full): the newly created #JsonNode + * Return value: (transfer full): the newly created node */ JsonNode * json_node_new (JsonNodeType type) @@ -396,16 +399,18 @@ json_node_new (JsonNodeType type) /** * json_node_copy: - * @node: a #JsonNode + * @node: the node to copy * - * Copies @node. If the node contains complex data types, their reference + * Copies @node. + * + * If the node contains complex data types, their reference * counts are increased, regardless of whether the node is mutable or * immutable. * * The copy will be immutable if, and only if, @node is immutable. However, * there should be no need to copy an immutable node. * - * Return value: (transfer full): the copied #JsonNode + * Return value: (transfer full): the copied of the given node */ JsonNode * json_node_copy (JsonNode *node) @@ -454,9 +459,9 @@ json_node_copy (JsonNode *node) /** * json_node_ref: - * @node: a #JsonNode + * @node: the node to reference * - * Increment the reference count of @node. + * Increments the reference count of @node. * * Since: 1.2 * Returns: (transfer full): a pointer to @node @@ -473,10 +478,11 @@ json_node_ref (JsonNode *node) /** * json_node_unref: - * @node: (transfer full): a #JsonNode + * @node: (transfer full): the node to unreference + * + * Decrements the reference count of @node. * - * Decrement the reference count of @node. If it reaches zero, the node is - * freed. + * If the reference count reaches zero, the node is freed. * * Since: 1.2 */ @@ -495,12 +501,14 @@ json_node_unref (JsonNode *node) /** * json_node_set_object: - * @node: a #JsonNode initialized to %JSON_NODE_OBJECT - * @object: (nullable): a #JsonObject + * @node: a node initialized to `JSON_NODE_OBJECT` + * @object: (nullable): a JSON object + * + * Sets @objects inside @node. * - * Sets @objects inside @node. The reference count of @object is increased. + * The reference count of @object is increased. * - * If @object is %NULL, the node’s existing object is cleared. + * If @object is `NULL`, the node’s existing object is cleared. * * It is an error to call this on an immutable node, or on a node which is not * an object node. @@ -524,10 +532,12 @@ json_node_set_object (JsonNode *node, /** * json_node_take_object: - * @node: a #JsonNode initialized to %JSON_NODE_OBJECT - * @object: (transfer full): a #JsonObject + * @node: a node initialized to `JSON_NODE_OBJECT` + * @object: (transfer full): a JSON object * - * Sets @object inside @node. The reference count of @object is not increased. + * Sets @object inside @node. + * + * The reference count of @object is not increased. * * It is an error to call this on an immutable node, or on a node which is not * an object node. @@ -552,13 +562,14 @@ json_node_take_object (JsonNode *node, /** * json_node_get_object: - * @node: a #JsonNode + * @node: a node holding a JSON object + * + * Retrieves the object stored inside a node. * - * 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. + * 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 + * Return value: (transfer none) (nullable): the JSON object */ JsonObject * json_node_get_object (JsonNode *node) @@ -571,14 +582,16 @@ json_node_get_object (JsonNode *node) /** * json_node_dup_object: - * @node: a #JsonNode + * @node: a node holding a JSON object + * + * Retrieves the object inside @node. * - * Retrieves the #JsonObject inside @node. The reference count of - * 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. + * The reference count of the returned object is increased. * - * Return value: (transfer full) (nullable): the #JsonObject + * 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 JSON object */ JsonObject * json_node_dup_object (JsonNode *node) @@ -594,13 +607,15 @@ json_node_dup_object (JsonNode *node) /** * json_node_set_array: - * @node: a #JsonNode initialized to %JSON_NODE_ARRAY - * @array: a #JsonArray + * @node: a node initialized to `JSON_NODE_ARRAY` + * @array: a JSON array * - * Sets @array inside @node and increases the #JsonArray reference count. + * Sets @array inside @node. * - * It is an error to call this on an immutable node, or on a node which is not - * an array node. + * The reference count of @array is increased. + * + * It is a programmer error to call this on a node which doesn’t hold an + * array value. Use `JSON_NODE_HOLDS_ARRAY` first. */ void json_node_set_array (JsonNode *node, @@ -621,13 +636,15 @@ json_node_set_array (JsonNode *node, /** * json_node_take_array: - * @node: a #JsonNode initialized to %JSON_NODE_ARRAY - * @array: (transfer full): a #JsonArray + * @node: a node initialized to `JSON_NODE_ARRAY` + * @array: (transfer full): a JSON array + * + * Sets @array inside @node. * - * Sets @array into @node without increasing the #JsonArray reference count. + * The reference count of @array is not increased. * - * It is an error to call this on an immutable node, or a node which is not - * an array node. + * It is a programmer error to call this on a node which doesn’t hold an + * array value. Use `JSON_NODE_HOLDS_ARRAY` first. */ void json_node_take_array (JsonNode *node, @@ -649,13 +666,14 @@ json_node_take_array (JsonNode *node, /** * json_node_get_array: - * @node: a #JsonNode + * @node: a node holding an array + * + * Retrieves the JSON array stored inside a node. * - * 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. + * 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 + * Return value: (transfer none) (nullable): the JSON array */ JsonArray * json_node_get_array (JsonNode *node) @@ -668,14 +686,16 @@ json_node_get_array (JsonNode *node) /** * json_node_dup_array: - * @node: a #JsonNode + * @node: a node holding an array + * + * Retrieves the JSON array inside @node. + * + * The reference count of the returned array is increased. * - * Retrieves the #JsonArray stored inside a #JsonNode and returns it - * 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. + * 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 + * Return value: (transfer full) (nullable): the JSON array with its reference * count increased. */ JsonArray * @@ -692,13 +712,16 @@ json_node_dup_array (JsonNode *node) /** * json_node_get_value: - * @node: a #JsonNode + * @node: a 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. It is a programmer error - * to call this on a node which doesn’t hold a scalar value. Use - * %JSON_NODE_HOLDS_VALUE first. + * Retrieves a value from a node and copies into @value. + * + * When done using it, call `g_value_unset()` on the `GValue` to free the + * associated resources. + * + * 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, @@ -736,10 +759,24 @@ json_node_get_value (JsonNode *node, /** * json_node_set_value: - * @node: a #JsonNode initialized to %JSON_NODE_VALUE - * @value: the #GValue to set + * @node: a node initialized to `JSON_NODE_VALUE` + * @value: the value to set + * + * Sets a scalar value inside the given node. + * + * The contents of the given `GValue` are copied into the `JsonNode`. + * + * The following `GValue` types have a direct mapping to JSON types: * - * Sets @value inside @node. The passed #GValue is copied into the #JsonNode. + * - `G_TYPE_INT64` + * - `G_TYPE_DOUBLE` + * - `G_TYPE_BOOLEAN` + * - `G_TYPE_STRING` + * + * JSON-GLib will also automatically promote the following `GValue` types: + * + * - `G_TYPE_INT` to `G_TYPE_INT64` + * - `G_TYPE_FLOAT` to `G_TYPE_DOUBLE` * * It is an error to call this on an immutable node, or on a node which is not * a value node. @@ -798,9 +835,9 @@ json_node_set_value (JsonNode *node, /** * json_node_free: - * @node: a #JsonNode + * @node: the node to free * - * Frees the resources allocated by @node. + * Frees the resources allocated by the node. */ void json_node_free (JsonNode *node) @@ -820,14 +857,15 @@ json_node_free (JsonNode *node) /** * json_node_seal: - * @node: a #JsonNode + * @node: the node to seal + * + * Seals the given node, making it immutable to further changes. * - * Seals the #JsonNode, making it immutable to further changes. In order to be - * sealed, the @node must have a type and value set. The value will be - * recursively sealed — if the node holds an object, that #JsonObject will be - * sealed, etc. + * In order to be sealed, the @node must have a type and value set. The value + * will be recursively sealed — if the node holds an object, that JSON object + * will be sealed, etc. * - * If the @node is already immutable, this is a no-op. + * If the `node` is already immutable, this is a no-op. * * Since: 1.2 */ @@ -864,13 +902,13 @@ json_node_seal (JsonNode *node) /** * json_node_is_immutable: - * @node: a #JsonNode + * @node: the node to check * * Check whether the given @node has been marked as immutable by calling - * json_node_seal() on it. + * [method@Json.Node.seal] on it. * * Since: 1.2 - * Returns: %TRUE if the @node is immutable + * Returns: `TRUE` if the @node is immutable */ gboolean json_node_is_immutable (JsonNode *node) @@ -882,12 +920,14 @@ json_node_is_immutable (JsonNode *node) /** * json_node_type_name: - * @node: a #JsonNode + * @node: a node * * Retrieves the user readable name of the data type contained by @node. * - * Return value: a string containing the name of the type. The returned string - * is owned by the node and should never be modified or freed + * **Note**: The name is only meant for debugging purposes, and there is no + * guarantee the name will stay the same across different versions. + * + * Return value: (transfer none): a string containing the name of the type */ const gchar * json_node_type_name (JsonNode *node) @@ -936,13 +976,14 @@ json_node_type_get_name (JsonNodeType node_type) /** * json_node_set_parent: - * @node: a #JsonNode - * @parent: (transfer none): the parent #JsonNode of @node + * @node: the node to change + * @parent: (transfer none) (nullable): the parent node * - * Sets the parent #JsonNode of @node. + * Sets the parent node for the given `node`. * - * It is an error to call this with an immutable @parent. @node may be - * immutable. + * It is an error to call this with an immutable @parent. + * + * The @node may be immutable. * * Since: 0.8 */ @@ -959,11 +1000,11 @@ json_node_set_parent (JsonNode *node, /** * json_node_get_parent: - * @node: a #JsonNode + * @node: the node to query * - * Retrieves the parent #JsonNode of @node. + * Retrieves the parent node of the given @node. * - * Return value: (transfer none) (nullable): the parent node, or %NULL if @node + * Return value: (transfer none) (nullable): the parent node, or `NULL` if @node * is the root node */ JsonNode * @@ -976,7 +1017,7 @@ json_node_get_parent (JsonNode *node) /** * json_node_set_string: - * @node: a #JsonNode initialized to %JSON_NODE_VALUE + * @node: a node initialized to `JSON_NODE_VALUE` * @value: a string value * * Sets @value as the string content of the @node, replacing any existing @@ -1003,10 +1044,11 @@ json_node_set_string (JsonNode *node, /** * json_node_get_string: - * @node: a #JsonNode of type %JSON_NODE_VALUE + * @node: a node holding a string + * + * Gets the string value stored inside a node. * - * Gets the string value stored inside a #JsonNode. If the node does not hold a - * string value, %NULL is returned. + * If the node does not hold a string value, `NULL` is returned. * * Return value: (nullable): a string value. */ @@ -1026,14 +1068,14 @@ json_node_get_string (JsonNode *node) /** * json_node_dup_string: - * @node: a #JsonNode of type %JSON_NODE_VALUE + * @node: a node holding a string + * + * Gets a copy of the string value stored inside a node. * - * Gets a copy of the string value stored inside a #JsonNode. If the node does - * not hold a string value, %NULL is returned. + * If the node does not hold a string value, `NULL` is returned. * - * Return value: (transfer full) (nullable): a newly allocated string - * containing a copy of the #JsonNode contents. Use g_free() to free the - * allocated resources + * Return value: (transfer full) (nullable): a copy of the string + * inside the node */ gchar * json_node_dup_string (JsonNode *node) @@ -1045,7 +1087,7 @@ json_node_dup_string (JsonNode *node) /** * json_node_set_int: - * @node: a #JsonNode of type %JSON_NODE_VALUE + * @node: a node initialized to `JSON_NODE_VALUE` * @value: an integer value * * Sets @value as the integer content of the @node, replacing any existing @@ -1072,13 +1114,17 @@ json_node_set_int (JsonNode *node, /** * json_node_get_int: - * @node: a #JsonNode of type %JSON_NODE_VALUE + * @node: a node holding an integer + * + * Gets the integer value stored inside a node. + * + * If the node holds a double value, its integer component is returned. * - * Gets the integer value stored inside a #JsonNode. If the node holds a double - * value, its integer component is returned. If the node holds a %FALSE boolean - * value, `0` is returned; otherwise a non-zero integer is returned. If the - * node holds a %JSON_NODE_NULL value or a value of another non-integer type, - * `0` is returned. + * If the node holds a `FALSE` boolean value, `0` is returned; otherwise, + * a non-zero integer is returned. + * + * If the node holds a `JSON_NODE_NULL` value or a value of another + * non-integer type, `0` is returned. * * Return value: an integer value. */ @@ -1104,7 +1150,7 @@ json_node_get_int (JsonNode *node) /** * json_node_set_double: - * @node: a #JsonNode of type %JSON_NODE_VALUE + * @node: a node initialized to `JSON_NODE_VALUE` * @value: a double value * * Sets @value as the double content of the @node, replacing any existing @@ -1131,13 +1177,17 @@ json_node_set_double (JsonNode *node, /** * json_node_get_double: - * @node: a #JsonNode of type %JSON_NODE_VALUE + * @node: a node holding a floating point value + * + * Gets the double value stored inside a node. + * + * If the node holds an integer value, it is returned as a double. * - * Gets the double value stored inside a #JsonNode. If the node holds an integer - * value, it is returned as a double. If the node holds a %FALSE boolean value, - * `0.0` is returned; otherwise a non-zero double is returned. If the node holds - * a %JSON_NODE_NULL value or a value of another non-double type, `0.0` is - * returned. + * If the node holds a `FALSE` boolean value, `0.0` is returned; otherwise + * a non-zero double is returned. + * + * If the node holds a `JSON_NODE_NULL` value or a value of another + * non-double type, `0.0` is returned. * * Return value: a double value. */ @@ -1163,7 +1213,7 @@ json_node_get_double (JsonNode *node) /** * json_node_set_boolean: - * @node: a #JsonNode of type %JSON_NODE_VALUE + * @node: a node initialized to `JSON_NODE_VALUE` * @value: a boolean value * * Sets @value as the boolean content of the @node, replacing any existing @@ -1190,12 +1240,15 @@ json_node_set_boolean (JsonNode *node, /** * json_node_get_boolean: - * @node: a #JsonNode of type %JSON_NODE_VALUE + * @node: a node holding a boolean value + * + * Gets the boolean value stored inside a node. * - * Gets the boolean value stored inside a #JsonNode. If the node holds an - * integer or double value which is zero, %FALSE is returned; otherwise %TRUE - * is returned. If the node holds a %JSON_NODE_NULL value or a value of another - * non-boolean type, %FALSE is returned. + * If the node holds an integer or double value which is zero, `FALSE` is + * returned; otherwise `TRUE` is returned. + * + * If the node holds a `JSON_NODE_NULL` value or a value of another + * non-boolean type, `FALSE` is returned. * * Return value: a boolean value. */ @@ -1221,9 +1274,9 @@ json_node_get_boolean (JsonNode *node) /** * json_node_get_node_type: - * @node: a #JsonNode + * @node: the node to check * - * Retrieves the #JsonNodeType of @node + * Retrieves the type of a @node. * * Return value: the type of the node * @@ -1239,14 +1292,14 @@ json_node_get_node_type (JsonNode *node) /** * json_node_is_null: - * @node: a #JsonNode + * @node: the node to check * - * Checks whether @node is a %JSON_NODE_NULL. + * Checks whether @node is a `JSON_NODE_NULL`. * - * A %JSON_NODE_NULL node is not the same as a %NULL #JsonNode; a - * %JSON_NODE_NULL represents a 'null' value in the JSON tree. + * A `JSON_NODE_NULL` node is not the same as a `NULL` node; a `JSON_NODE_NULL` + * represents a literal `null` value in the JSON tree. * - * Return value: %TRUE if the node is null + * Return value: `TRUE` if the node is null * * Since: 0.8 */ @@ -1258,26 +1311,26 @@ json_node_is_null (JsonNode *node) return node->type == JSON_NODE_NULL; } -/** +/*< private > * json_type_is_a: * @sub: sub-type * @super: super-type * - * Check whether @sub is a sub-type of, or equal to, @super. The only sub-type - * relationship in the JSON Schema type system is that - * %WBL_PRIMITIVE_TYPE_INTEGER is a sub-type of %WBL_PRIMITIVE_TYPE_NUMBER. + * Check whether @sub is a sub-type of, or equal to, @super. + * + * The only sub-type relationship in the JSON Schema type system is that + * an integer type is a sub-type of a number type. * * Formally, this function calculates: `@sub <: @super`. * * Reference: http://json-schema.org/latest/json-schema-core.html#rfc.section.3.5 * - * Returns: %TRUE if @sub is a sub-type of, or equal to, @super; %FALSE - * otherwise + * Returns: `TRUE` if @sub is a sub-type of, or equal to, @super; `FALSE` otherwise * Since: 1.2 */ static gboolean -json_type_is_a (JsonNode *sub, - JsonNode *super) +json_type_is_a (JsonNode *sub, + JsonNode *super) { if (super->type == JSON_NODE_VALUE && sub->type == JSON_NODE_VALUE) { @@ -1323,7 +1376,7 @@ json_string_hash (gconstpointer key) * * Check whether @a and @b are equal UTF-8 JSON strings. * - * Returns: %TRUE if @a and @b are equal; %FALSE otherwise + * Returns: `TRUE` if @a and @b are equal; `FALSE` otherwise * Since: 1.2 */ gboolean @@ -1339,10 +1392,11 @@ json_string_equal (gconstpointer a, * @b: (type utf8): another JSON string * * Check whether @a and @b are equal UTF-8 JSON strings and return an ordering - * over them in strcmp() style. + * over them in `strcmp()` style. + * + * Returns: an integer less than zero if `a < b`, equal to zero if `a == b`, and + * greater than zero if `a > b` * - * Returns: an integer less than zero if @a < @b, equal to zero if @a == @b, and - * greater than zero if @a > @b * Since: 1.2 */ gint @@ -1356,12 +1410,12 @@ json_string_compare (gconstpointer a, * json_node_hash: * @key: (type JsonNode): a JSON node to hash * - * Calculate a hash value for the given @key (a #JsonNode). + * Calculate a hash value for the given @key. * * The hash is calculated over the node and its value, recursively. If the node * is immutable, this is a fast operation; otherwise, it scales proportionally * with the size of the node’s value (for example, with the number of members - * in the #JsonObject if this node contains an object). + * in the JSON object if this node contains an object). * * Returns: hash value for @key * Since: 1.2 @@ -1401,12 +1455,13 @@ json_node_hash (gconstpointer key) * @a: (type JsonNode): a JSON node * @b: (type JsonNode): another JSON node * - * Check whether @a and @b are equal #JsonNodes, meaning they have the same - * type and same values (checked recursively). Note that integer values are - * compared numerically, ignoring type, so a double value 4.0 is equal to the - * integer value 4. + * Check whether @a and @b are equal node, meaning they have the same + * type and same values (checked recursively). + * + * Note that integer values are compared numerically, ignoring type, so a + * double value 4.0 is equal to the integer value 4. * - * Returns: %TRUE if @a and @b are equal; %FALSE otherwise + * Returns: `TRUE` if @a and @b are equal; `FALSE` otherwise * Since: 1.2 */ gboolean diff --git a/json-glib/json-object.c b/json-glib/json-object.c index 8555eb9..b109abd 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 + * Returns: (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: a JSON 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 + * Returns: (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: a JSON object + * + * Releases a reference on the given 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. + * 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: a JSON 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: a JSON 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: a JSON 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: a JSON 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 the object does not have a member with the given name, a new member + * is created. * - * 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 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: a JSON 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: a JSON 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: a JSON 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: a JSON 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: a JSON 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: a JSON object * @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 */ @@ -434,16 +433,13 @@ json_object_set_array_member (JsonObject *object, /** * json_object_set_object_member: - * @object: a #JsonObject + * @object: a JSON 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: a JSON object + * + * Retrieves all the names of the members of 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(). + * 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): 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. + * Returns: (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: a JSON 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. + * Returns: (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: a JSON 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. + * Returns: (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: a JSON 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. + * Returns: (transfer none) (nullable): the value for the + * requested object member */ JsonNode * json_object_get_member (JsonObject *object, @@ -625,17 +615,17 @@ json_object_get_ ##type_name## _member_with_default (JsonObject *object, \ /** * json_object_get_int_member: - * @object: a #JsonObject - * @member_name: the name of the @object member + * @object: a JSON object + * @member_name: the name of the object member * * Convenience function that retrieves the integer value * stored in @member_name of @object. It is an error to specify a * @member_name which does not exist. * - * See also: json_object_get_int_member_with_default(), - * json_object_get_member() and json_object_has_member() + * See also: [method@Json.Object.get_int_member_with_default], + * [method@Json.Object.get_member], [method@Json.Object.has_member] * - * Return value: the integer value of the object's member + * Returns: the integer value of the object's member * * Since: 0.8 */ @@ -643,8 +633,8 @@ JSON_OBJECT_GET (gint64, int) /** * json_object_get_int_member_with_default: - * @object: a #JsonObject - * @member_name: the name of the @object member + * @object: a JSON object + * @member_name: the name of the object member * @default_value: the value to return if @member_name is not valid * * Convenience function that retrieves the integer value @@ -662,17 +652,17 @@ JSON_OBJECT_GET_DEFAULT (gint64, int) /** * json_object_get_double_member: - * @object: a #JsonObject + * @object: a JSON object * @member_name: the name of the member * * Convenience function that retrieves the floating point value * stored in @member_name of @object. It is an error to specify a * @member_name which does not exist. * - * See also: json_object_get_double_member_with_default(), - * json_object_get_member() and json_object_has_member() + * See also: [method@Json.Object.get_double_member_with_default], + * [method@Json.Object.get_member], [method@Json.Object.has_member] * - * Return value: the floating point value of the object's member + * Returns: the floating point value of the object's member * * Since: 0.8 */ @@ -680,7 +670,7 @@ JSON_OBJECT_GET (gdouble, double) /** * json_object_get_double_member_with_default: - * @object: a #JsonObject + * @object: a JSON object * @member_name: the name of the @object member * @default_value: the value to return if @member_name is not valid * @@ -699,17 +689,17 @@ JSON_OBJECT_GET_DEFAULT (double, double) /** * json_object_get_boolean_member: - * @object: a #JsonObject + * @object: a JSON object * @member_name: the name of the member * * Convenience function that retrieves the boolean value * stored in @member_name of @object. It is an error to specify a * @member_name which does not exist. * - * See also: json_object_get_boolean_member_with_default(), - * json_object_get_member() and json_object_has_member() + * See also: [method@Json.Object.get_boolean_member_with_default], + * [method@Json.Object.get_member], [method@Json.Object.has_member] * - * Return value: the boolean value of the object's member + * Returns: the boolean value of the object's member * * Since: 0.8 */ @@ -717,7 +707,7 @@ JSON_OBJECT_GET (gboolean, boolean) /** * json_object_get_boolean_member_with_default: - * @object: a #JsonObject + * @object: a JSON object * @member_name: the name of the @object member * @default_value: the value to return if @member_name is not valid * @@ -736,17 +726,17 @@ JSON_OBJECT_GET_DEFAULT (gboolean, boolean) /** * json_object_get_string_member: - * @object: a #JsonObject + * @object: a JSON object * @member_name: the name of the member * * Convenience function that retrieves the string value * stored in @member_name of @object. It is an error to specify a * @member_name that does not exist. * - * See also: json_object_get_string_member_with_default(), - * json_object_get_member() and json_object_has_member() + * See also: [method@Json.Object.get_string_member_with_default], + * [method@Json.Object.get_member], [method@Json.Object.has_member] * - * Return value: the string value of the object's member + * Returns: the string value of the object's member * * Since: 0.8 */ @@ -754,7 +744,7 @@ JSON_OBJECT_GET (const gchar *, string) /** * json_object_get_string_member_with_default: - * @object: a #JsonObject + * @object: a JSON object * @member_name: the name of the @object member * @default_value: the value to return if @member_name is not valid * @@ -773,16 +763,16 @@ JSON_OBJECT_GET_DEFAULT (const char *, string) /** * json_object_get_null_member: - * @object: a #JsonObject + * @object: a JSON object * @member_name: the name of the member * * Convenience function that checks whether the value * stored in @member_name of @object is null. It is an error to * specify a @member_name which does not exist. * - * See also: json_object_get_member() and json_object_has_member() + * See also: [method@Json.Object.get_member], [method@Json.Object.has_member] * - * Return value: %TRUE if the value is null + * Returns: `TRUE` if the value is `null` * * Since: 0.8 */ @@ -812,16 +802,18 @@ json_object_get_null_member (JsonObject *object, /** * json_object_get_array_member: - * @object: a #JsonObject + * @object: a JSON object * @member_name: the name of the member * * Convenience function that retrieves the array * stored in @member_name of @object. It is an error to specify a * @member_name which does not exist. * - * See also: json_object_get_member() and json_object_has_member() + * If @member_name contains `null`, then this function will return `NULL`. + * + * See also: [method@Json.Object.get_member], [method@Json.Object.has_member] * - * Return value: (transfer none): the array inside the object's member + * Returns: (transfer none) (nullable): the array inside the object's member * * Since: 0.8 */ @@ -846,17 +838,18 @@ json_object_get_array_member (JsonObject *object, /** * json_object_get_object_member: - * @object: a #JsonObject + * @object: a JSON object * @member_name: the name of the member * * Convenience function that retrieves the object * stored in @member_name of @object. It is an error to specify a @member_name * which does not exist. * - * See also: json_object_get_member() and json_object_has_member() + * If @member_name contains `null`, then this function will return `NULL`. * - * Return value: (transfer none) (nullable): the object inside the object’s - * member, or %NULL if the value for the member is `null` + * See also: [method@Json.Object.get_member], [method@Json.Object.has_member] + * + * Returns: (transfer none) (nullable): the object inside the object's member * * Since: 0.8 */ @@ -881,12 +874,12 @@ json_object_get_object_member (JsonObject *object, /** * json_object_has_member: - * @object: a #JsonObject + * @object: a JSON object * @member_name: the name of a JSON object member * * Checks whether @object has a member named @member_name. * - * Return value: %TRUE if the JSON object has the requested member + * Returns: `TRUE` if the JSON object has the requested member */ gboolean json_object_has_member (JsonObject *object, @@ -900,11 +893,11 @@ json_object_has_member (JsonObject *object, /** * json_object_get_size: - * @object: a #JsonObject + * @object: a JSON object * - * Retrieves the number of members of a #JsonObject. + * Retrieves the number of members of a JSON object. * - * Return value: the number of members + * Returns: the number of members */ guint json_object_get_size (JsonObject *object) @@ -916,7 +909,7 @@ json_object_get_size (JsonObject *object) /** * json_object_remove_member: - * @object: a #JsonObject + * @object: a JSON object * @member_name: the name of the member to remove * * Removes @member_name from @object, freeing its allocated resources. @@ -946,18 +939,18 @@ json_object_remove_member (JsonObject *object, /** * json_object_foreach_member: - * @object: a #JsonObject + * @object: a JSON object * @func: (scope call): the function to be called on each member * @data: (closure): data to be passed to the function * * Iterates over all members of @object and calls @func on * each one of them. * - * It is safe to change the value of a #JsonNode of the @object - * from within the iterator @func, but it is not safe to add or - * remove members from the @object. + * It is safe to change the value of a member of the oobject + * from within the iterator function, but it is not safe to add or + * remove members from the object. * - * The order in which the @object members are iterated is the + * The order in which the object members are iterated is the * insertion order. * * Since: 0.8 @@ -990,7 +983,7 @@ json_object_foreach_member (JsonObject *object, * json_object_hash: * @key: (type JsonObject): a JSON object to hash * - * Calculate a hash value for the given @key (a #JsonObject). + * Calculate a hash value for the given @key (a JSON object). * * The hash is calculated over the object and all its members, recursively. If * the object is immutable, this is a fast operation; otherwise, it scales @@ -1028,10 +1021,10 @@ json_object_hash (gconstpointer key) * @a: (type JsonObject): a JSON object * @b: (type JsonObject): another JSON object * - * Check whether @a and @b are equal #JsonObjects, meaning they have the same + * Check whether @a and @b are equal objects, meaning they have the same * set of members, and the values of corresponding members are equal. * - * Returns: %TRUE if @a and @b are equal; %FALSE otherwise + * Returns: `TRUE` if @a and @b are equal, and `FALSE` otherwise * Since: 1.2 */ gboolean @@ -1084,12 +1077,12 @@ json_object_equal (gconstpointer a, /** * json_object_iter_init: - * @iter: an uninitialised #JsonObjectIter - * @object: the #JsonObject to iterate over + * @iter: an uninitialised JSON object iterator + * @object: the JSON object to iterate over * - * Initialise the @iter and associate it with @object. + * Initialises the @iter and associate it with @object. * - * |[ + * ```c * JsonObjectIter iter; * const gchar *member_name; * JsonNode *member_node; @@ -1099,7 +1092,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 */ @@ -1119,27 +1117,30 @@ json_object_iter_init (JsonObjectIter *iter, /** * json_object_iter_next: - * @iter: a #JsonObjectIter + * @iter: a JSON object iterator * @member_name: (out callee-allocates) (transfer none) (optional): return * location for the member name, or %NULL to ignore * @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 the iterator 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. + * iterator is invalidated if the object 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 + * Returns: `TRUE` if @member_name and @member_node are valid; `FALSE` if + * there are no more members * * Since: 1.2 */ @@ -1161,12 +1162,12 @@ json_object_iter_next (JsonObjectIter *iter, /** * json_object_iter_init_ordered: - * @iter: an uninitialised #JsonObjectIter - * @object: the #JsonObject to iterate over + * @iter: an uninitialised iterator + * @object: the JSON object to iterate over * - * Initialise the @iter and associate it with @object. + * Initialises the @iter and associate it with @object. * - * |[ + * ```c * JsonObjectIter iter; * const gchar *member_name; * JsonNode *member_node; @@ -1176,9 +1177,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 */ @@ -1200,27 +1201,28 @@ json_object_iter_init_ordered (JsonObjectIter *iter, /** * json_object_iter_next_ordered: - * @iter: a #JsonObjectIter + * @iter: an ordered JSON object iterator * @member_name: (out callee-allocates) (transfer none) (optional): return * location for the member name, or %NULL to ignore * @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 the iterator 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 + * Returns: `TRUE `if @member_name and @member_node are valid; `FALSE` if the end * of the object has been reached * * Since: 1.6 diff --git a/json-glib/json-parser.c b/json-glib/json-parser.c index 4a560d8..c5e58f4 100644 --- a/json-glib/json-parser.c +++ b/json-glib/json-parser.c @@ -25,11 +25,44 @@ */ /** - * SECTION:json-parser - * @short_description: Parse JSON data streams + * JsonParser: * - * #JsonParser provides an object for parsing a JSON data stream, either + * `JsonParser` provides an object for parsing a JSON data stream, either * inside a file or inside a static buffer. + * + * ## Using `JsonParser` + * + * The `JsonParser` API is fairly simple: + * + * ```c + * gboolean + * parse_json (const char *filename) + * { + * g_autoptr(JsonParser) parser = json_parser_new (); + * g_autoptr(GError) error = NULL + * + * json_parser_load_from_file (parser, filename, &error); + * if (error != NULL) + * { + * g_critical ("Unable to parse '%s': %s", filename, error->message); + * return FALSE; + * } + * + * g_autoptr(JsonNode) root = json_parser_get_root (parser); + * + * // manipulate the object tree from the root node + * + * return TRUE + * } + * ``` + * + * By default, the entire process of loading the data and parsing it is + * synchronous; the [method@Json.Parser.load_from_stream_async()] API will + * load the data asynchronously, but parse it in the main context as the + * signals of the parser must be emitted in the same thread. If you do + * not use signals, and you wish to also parse the JSON data without blocking, + * you should use a `GTask` and the synchronous `JsonParser` API inside the + * task itself. */ #include "config.h" @@ -198,8 +231,10 @@ json_parser_class_init (JsonParserClass *klass) /** * JsonParser:immutable: * - * Whether the #JsonNode tree built by the #JsonParser should be immutable - * when created. Making the output immutable on creation avoids the expense + * Whether the tree built by the parser should be immutable + * when created. + * + * Making the output immutable on creation avoids the expense * of traversing it to make it immutable later. * * Since: 1.2 @@ -215,10 +250,9 @@ json_parser_class_init (JsonParserClass *klass) /** * JsonParser::parse-start: - * @parser: the #JsonParser that received the signal + * @parser: the parser that emitted the signal * - * The ::parse-start signal is emitted when the parser began parsing - * a JSON data stream. + * This signal is emitted when a parser starts parsing a JSON data stream. */ parser_signals[PARSE_START] = g_signal_new ("parse-start", @@ -230,10 +264,10 @@ json_parser_class_init (JsonParserClass *klass) G_TYPE_NONE, 0); /** * JsonParser::parse-end: - * @parser: the #JsonParser that received the signal + * @parser: the parser that emitted the signal * - * The ::parse-end signal is emitted when the parser successfully - * finished parsing a JSON data stream + * This signal is emitted when a parser successfully finished parsing a + * JSON data stream */ parser_signals[PARSE_END] = g_signal_new ("parse-end", @@ -244,10 +278,9 @@ json_parser_class_init (JsonParserClass *klass) G_TYPE_NONE, 0); /** * JsonParser::object-start: - * @parser: the #JsonParser that received the signal + * @parser: the parser that emitted the signal * - * The ::object-start signal is emitted each time the #JsonParser - * starts parsing a #JsonObject. + * This signal is emitted each time a parser starts parsing a JSON object. */ parser_signals[OBJECT_START] = g_signal_new ("object-start", @@ -258,13 +291,12 @@ json_parser_class_init (JsonParserClass *klass) G_TYPE_NONE, 0); /** * JsonParser::object-member: - * @parser: the #JsonParser that received the signal - * @object: a #JsonObject + * @parser: the parser that emitted the signal + * @object: the JSON object being parsed * @member_name: the name of the newly parsed member * - * The ::object-member signal is emitted each time the #JsonParser - * has successfully parsed a single member of a #JsonObject. The - * object and member are passed to the signal handlers. + * The `::object-member` signal is emitted each time a parser + * has successfully parsed a single member of a JSON object */ parser_signals[OBJECT_MEMBER] = g_signal_new ("object-member", @@ -277,11 +309,11 @@ json_parser_class_init (JsonParserClass *klass) G_TYPE_STRING); /** * JsonParser::object-end: - * @parser: the #JsonParser that received the signal - * @object: the parsed #JsonObject + * @parser: the parser that emitted the signal + * @object: the parsed JSON object * - * The ::object-end signal is emitted each time the #JsonParser - * has successfully parsed an entire #JsonObject. + * The `::object-end` signal is emitted each time a parser + * has successfully parsed an entire JSON object. */ parser_signals[OBJECT_END] = g_signal_new ("object-end", @@ -293,10 +325,10 @@ json_parser_class_init (JsonParserClass *klass) JSON_TYPE_OBJECT); /** * JsonParser::array-start: - * @parser: the #JsonParser that received the signal + * @parser: the parser that emitted the signal * - * The ::array-start signal is emitted each time the #JsonParser - * starts parsing a #JsonArray + * The `::array-start` signal is emitted each time a parser + * starts parsing a JSON array. */ parser_signals[ARRAY_START] = g_signal_new ("array-start", @@ -307,13 +339,12 @@ json_parser_class_init (JsonParserClass *klass) G_TYPE_NONE, 0); /** * JsonParser::array-element: - * @parser: the #JsonParser that received the signal - * @array: a #JsonArray - * @index_: the index of the newly parsed element + * @parser: the parser that emitted the signal + * @array: a JSON array + * @index_: the index of the newly parsed array element * - * The ::array-element signal is emitted each time the #JsonParser - * has successfully parsed a single element of a #JsonArray. The - * array and element index are passed to the signal handlers. + * The `::array-element` signal is emitted each time a parser + * has successfully parsed a single element of a JSON array. */ parser_signals[ARRAY_ELEMENT] = g_signal_new ("array-element", @@ -326,11 +357,11 @@ json_parser_class_init (JsonParserClass *klass) G_TYPE_INT); /** * JsonParser::array-end: - * @parser: the #JsonParser that received the signal - * @array: the parsed #JsonArray + * @parser: the parser that emitted the signal + * @array: the parsed JSON array * - * The ::array-end signal is emitted each time the #JsonParser - * has successfully parsed an entire #JsonArray + * The `::array-end` signal is emitted each time a parser + * has successfully parsed an entire JSON array. */ parser_signals[ARRAY_END] = g_signal_new ("array-end", @@ -342,10 +373,10 @@ json_parser_class_init (JsonParserClass *klass) JSON_TYPE_ARRAY); /** * JsonParser::error: - * @parser: the parser instance that received the signal - * @error: a pointer to the #GError + * @parser: the parser that emitted the signal + * @error: the error * - * The ::error signal is emitted each time a #JsonParser encounters + * The `::error` signal is emitted each time a parser encounters * an error in a JSON stream. */ parser_signals[ERROR] = @@ -844,6 +875,8 @@ json_parse_statement (JsonParser *parser, return '='; } + if (priv->has_assignment) + g_free (priv->variable_name); priv->has_assignment = TRUE; priv->variable_name = name; @@ -940,12 +973,12 @@ json_scanner_create (JsonParser *parser) /** * json_parser_new: * - * Creates a new #JsonParser instance. You can use the #JsonParser to - * load a JSON stream from either a file or a buffer and then walk the - * hierarchy using the data types API. + * Creates a new JSON parser. + * + * You can use the `JsonParser` to load a JSON stream from either a file or a + * buffer and then walk the hierarchy using the data types API. * - * Return value: the newly created #JsonParser. Use g_object_unref() - * to release all the memory it allocates. + * Returns: (transfer full): the newly created parser */ JsonParser * json_parser_new (void) @@ -956,11 +989,11 @@ json_parser_new (void) /** * json_parser_new_immutable: * - * Creates a new #JsonParser instance with its #JsonParser:immutable property - * set to %TRUE to create immutable output trees. + * Creates a new parser instance with its [property@Json.Parser:immutable] + * property set to `TRUE` to create immutable output trees. * * Since: 1.2 - * Returns: (transfer full): a new #JsonParser + * Returns: (transfer full): the newly created parser */ JsonParser * json_parser_new_immutable (void) @@ -1093,18 +1126,19 @@ json_parser_load (JsonParser *parser, /** * json_parser_load_from_file: - * @parser: a #JsonParser - * @filename: the path for the file to parse - * @error: return location for a #GError, or %NULL + * @parser: a parser + * @filename: (type filename): the path for the file to parse + * @error: return location for a #GError * - * Loads a JSON stream from the content of @filename and parses it. See - * json_parser_load_from_data(). + * Loads a JSON stream from the content of `filename` and parses it. * * If the file is large or shared between processes, - * json_parser_load_from_mapped_file() may be a more efficient way to load it. + * [method@Json.Parser.load_from_mapped_file] may be a more efficient + * way to load it. * - * Return value: %TRUE if the file was successfully loaded and parsed. - * In case of error, @error is set accordingly and %FALSE is returned + * See also: [method@Json.Parser.load_from_data] + * + * Returns: `TRUE` if the file was successfully loaded and parsed. */ gboolean json_parser_load_from_file (JsonParser *parser, @@ -1147,18 +1181,19 @@ json_parser_load_from_file (JsonParser *parser, /** * json_parser_load_from_mapped_file: - * @parser: a #JsonParser - * @filename: the path for the file to parse - * @error: return location for a #GError, or %NULL + * @parser: a parser + * @filename: (type filename): the path for the file to parse + * @error: return location for a #GError + * + * Loads a JSON stream from the content of `filename` and parses it. * - * Loads a JSON stream from the content of @filename and parses it. Unlike - * json_parser_load_from_file(), @filename will be memory mapped as read-only - * and parsed. @filename will be unmapped before this function returns. + * Unlike [method@Json.Parser.load_from_file], `filename` will be memory + * mapped as read-only and parsed. `filename` will be unmapped before this + * function returns. * - * If mapping or reading the file fails, a %G_FILE_ERROR will be returned. + * If mapping or reading the file fails, a `G_FILE_ERROR` will be returned. * - * Return value: %TRUE if the file was successfully loaded and parsed. - * In case of error, @error is set accordingly and %FALSE is returned + * Returns: `TRUE` if the file was successfully loaded and parsed. * Since: 1.6 */ gboolean @@ -1202,17 +1237,17 @@ json_parser_load_from_mapped_file (JsonParser *parser, /** * json_parser_load_from_data: - * @parser: a #JsonParser + * @parser: a parser * @data: the buffer to parse - * @length: the length of the buffer, or -1 - * @error: return location for a #GError, or %NULL + * @length: the length of the buffer, or -1 if it is `NUL` terminated + * @error: return location for a #GError * - * Loads a JSON stream from a buffer and parses it. You can call this function - * multiple times with the same #JsonParser object, but the contents of the - * parser will be destroyed each time. + * Loads a JSON stream from a buffer and parses it. * - * Return value: %TRUE if the buffer was succesfully parsed. In case - * of error, @error is set accordingly and %FALSE is returned + * You can call this function multiple times with the same parser, but the + * contents of the parser will be destroyed each time. + * + * Returns: `TRUE` if the buffer was succesfully parsed */ gboolean json_parser_load_from_data (JsonParser *parser, @@ -1248,15 +1283,15 @@ json_parser_load_from_data (JsonParser *parser, /** * json_parser_get_root: - * @parser: a #JsonParser + * @parser: a parser + * + * Retrieves the top level node from the parsed JSON stream. * - * Retrieves the top level node from the parsed JSON stream. If the parser input - * was an empty string, or if parsing failed, this will be %NULL. It will also - * be %NULL if it has been stolen using json_parser_steal_root(). + * If the parser input was an empty string, or if parsing failed, the root + * will be `NULL`. It will also be `NULL` if it has been stolen using + * [method@Json.Parser.steal_root]. * - * Return value: (transfer none) (nullable): the root #JsonNode . The returned - * node is owned by the #JsonParser and should never be modified - * or freed. + * Returns: (transfer none) (nullable): the root node. */ JsonNode * json_parser_get_root (JsonParser *parser) @@ -1273,12 +1308,14 @@ json_parser_get_root (JsonParser *parser) /** * json_parser_steal_root: - * @parser: a #JsonParser + * @parser: a parser + * + * Steals the top level node from the parsed JSON stream. * - * Steals the top level node from the parsed JSON stream. This will be %NULL - * in the same situations as json_parser_get_root() returns %NULL. + * This will be `NULL` in the same situations as [method@Json.Parser.get_root] + * return `NULL`. * - * Returns: (transfer full) (nullable): the top level #JsonNode + * Returns: (transfer full) (nullable): the root node * * Since: 1.4 */ @@ -1299,15 +1336,15 @@ json_parser_steal_root (JsonParser *parser) /** * json_parser_get_current_line: - * @parser: a #JsonParser + * @parser: a parser * * Retrieves the line currently parsed, starting from 1. * * This function has defined behaviour only while parsing; calling this - * function from outside the signal handlers emitted by #JsonParser will + * function from outside the signal handlers emitted by the parser will * yield 0. * - * Return value: the currently parsed line, or 0. + * Returns: the currently parsed line, or 0. */ guint json_parser_get_current_line (JsonParser *parser) @@ -1322,16 +1359,16 @@ json_parser_get_current_line (JsonParser *parser) /** * json_parser_get_current_pos: - * @parser: a #JsonParser + * @parser: a parser * * Retrieves the current position inside the current line, starting * from 0. * * This function has defined behaviour only while parsing; calling this - * function from outside the signal handlers emitted by #JsonParser will + * function from outside the signal handlers emitted by the parser will * yield 0. * - * Return value: the position in the current line, or 0. + * Returns: the position in the current line, or 0. */ guint json_parser_get_current_pos (JsonParser *parser) @@ -1346,27 +1383,23 @@ json_parser_get_current_pos (JsonParser *parser) /** * json_parser_has_assignment: - * @parser: a #JsonParser - * @variable_name: (out) (allow-none) (transfer none): Return location for the variable - * name, or %NULL + * @parser: a parser + * @variable_name: (out) (optional) (transfer none): the variable name * * A JSON data stream might sometimes contain an assignment, like: * - * |[ - * var _json_data = { "member_name" : [ ... - * ]| + * ``` + * var _json_data = { "member_name" : [ ... + * ``` * * even though it would technically constitute a violation of the RFC. * - * #JsonParser will ignore the left hand identifier and parse the right - * hand value of the assignment. #JsonParser will record, though, the + * `JsonParser` will ignore the left hand identifier and parse the right + * hand value of the assignment. `JsonParser` will record, though, the * existence of the assignment in the data stream and the variable name * used. * - * Return value: %TRUE if there was an assignment, %FALSE otherwise. If - * @variable_name is not %NULL it will be set to the name of the variable - * used in the assignment. The string is owned by #JsonParser and should - * never be modified or freed. + * Returns: `TRUE` if there was an assignment, and `FALSE` otherwise * * Since: 0.4 */ @@ -1390,20 +1423,20 @@ json_parser_has_assignment (JsonParser *parser, /** * json_parser_load_from_stream: - * @parser: a #JsonParser - * @stream: an open #GInputStream - * @cancellable: (allow-none): a #GCancellable, or %NULL - * @error: the return location for a #GError, or %NULL + * @parser: a parser + * @stream: the input stream with the JSON data + * @cancellable: (nullable): a #GCancellable + * @error: the return location for a #GError * * Loads the contents of an input stream and parses them. * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the @cancellable object from another thread. If the - * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be set - * on the passed @error. + * If `cancellable` is not `NULL`, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the + * operation was cancelled, `G_IO_ERROR_CANCELLED` will be set + * on the given `error`. * - * Return value: %TRUE if the data stream was successfully read and - * parsed, and %FALSE otherwise + * Returns: `TRUE` if the data stream was successfully read and + * parsed, and `FALSE` otherwise * * Since: 0.12 */ @@ -1481,16 +1514,15 @@ load_data_free (gpointer data_) /** * json_parser_load_from_stream_finish: - * @parser: a #JsonParser - * @result: a #GAsyncResult - * @error: the return location for a #GError or %NULL + * @parser: a parser + * @result: the result of the asynchronous operation + * @error: the return location for a #GError * * Finishes an asynchronous stream loading started with - * json_parser_load_from_stream_async(). + * [method@Json.Parser.load_from_stream_async]. * - * Return value: %TRUE if the content of the stream was successfully retrieves - * and parsed, and %FALSE otherwise. In case of error, the #GError will be - * filled accordingly. + * Returns: `TRUE` if the content of the stream was successfully retrieved + * and parsed, and `FALSE` otherwise * * Since: 0.12 */ @@ -1510,7 +1542,7 @@ json_parser_load_from_stream_finish (JsonParser *parser, LoadData *data = g_task_get_task_data (G_TASK (result)); GError *internal_error = NULL; - /* We need to do this inside the finis() function because JsonParser will emit + /* We need to do this inside the finish() function because JsonParser will emit * signals, and we need to ensure that the signals are emitted in the right * context; it's easier to do that if we just rely on the async callback being * called in the right context, even if it means making the finish() function @@ -1558,19 +1590,19 @@ read_from_stream (GTask *task, /** * json_parser_load_from_stream_async: - * @parser: a #JsonParser - * @stream: a #GInputStream - * @cancellable: (allow-none): a #GCancellable, or %NULL - * @callback: a #GAsyncReadyCallback to call when the request is satisfied + * @parser: a parser + * @stream: the input stream with the JSON data + * @cancellable: (nullable): a #GCancellable + * @callback: (scope async): the function to call when the request is satisfied * @user_data: the data to pass to @callback * - * Asynchronously reads the contents of @stream. + * Asynchronously reads the contents of a stream. * - * For more details, see json_parser_load_from_stream() which is the + * For more details, see [method@Json.Parser.load_from_stream], which is the * synchronous version of this call. * * When the operation is finished, @callback will be called. You should - * then call json_parser_load_from_stream_finish() to get the result + * then call [method@Json.Parser.load_from_stream_finish] to get the result * of the operation. * * Since: 0.12 diff --git a/json-glib/json-parser.h b/json-glib/json-parser.h index 91fde66..33c4699 100644 --- a/json-glib/json-parser.h +++ b/json-glib/json-parser.h @@ -40,6 +40,11 @@ G_BEGIN_DECLS #define JSON_IS_PARSER_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), JSON_TYPE_PARSER)) #define JSON_PARSER_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), JSON_TYPE_PARSER, JsonParserClass)) +/** + * JSON_PARSER_ERROR: + * + * Error domain for `JsonParser`. + */ #define JSON_PARSER_ERROR (json_parser_error_quark ()) typedef struct _JsonParser JsonParser; @@ -57,7 +62,7 @@ typedef struct _JsonParserClass JsonParserClass; * @JSON_PARSER_ERROR_INVALID_DATA: invalid data (Since: 0.18) * @JSON_PARSER_ERROR_UNKNOWN: unknown error * - * Error enumeration for #JsonParser + * Error codes for `JSON_PARSER_ERROR`. * * This enumeration can be extended at later date */ @@ -73,12 +78,6 @@ typedef enum { JSON_PARSER_ERROR_UNKNOWN } JsonParserError; -/** - * JsonParser: - * - * JSON data streams parser. The contents of the #JsonParser structure are - * private and should only be accessed via the provided API. - */ struct _JsonParser { /*< private >*/ @@ -99,7 +98,7 @@ struct _JsonParser * @parse_end: class handler for the JsonParser::parse-end signal * @error: class handler for the JsonParser::error signal * - * #JsonParser class. + * The class structure for the JsonParser type. */ struct _JsonParserClass { diff --git a/json-glib/json-path.c b/json-glib/json-path.c index fe6e7b1..86fe97f 100644 --- a/json-glib/json-path.c +++ b/json-glib/json-path.c @@ -21,45 +21,44 @@ */ /** - * SECTION:json-path - * @Title: JsonPath - * @short_description: JSONPath implementation - * - * #JsonPath is a simple class implementing the JSONPath syntax for extracting - * data out of a JSON tree. While the semantics of the JSONPath expressions are - * heavily borrowed by the XPath specification for XML, the syntax follows the - * ECMAScript origins of JSON. - * - * Once a #JsonPath instance has been created, it has to compile a JSONPath - * expression using json_path_compile() before being able to match it to a - * JSON tree; the same #JsonPath instance can be used to match multiple JSON + * JsonPath: + * + * `JsonPath` is a simple class implementing the JSONPath syntax for extracting + * data out of a JSON tree. + * + * While the semantics of the JSONPath expressions are heavily borrowed by the + * XPath specification for XML, the syntax follows the ECMAScript origins of + * JSON. + * + * Once a `JsonPath` instance has been created, it has to compile a JSONPath + * expression using [method@Json.Path.compile] before being able to match it to + * a JSON tree; the same `JsonPath` instance can be used to match multiple JSON * trees. It it also possible to compile a new JSONPath expression using the - * same #JsonPath instance; the previous expression will be discarded only if + * same `JsonPath` instance; the previous expression will be discarded only if * the compilation of the new expression is successful. * - * The simple convenience function json_path_query() can be used for one-off - * matching. + * The simple convenience function [func@Json.Path.query] can be used for + * one-off matching. * - * ## Syntax of the JSONPath expressions ## + * ## Syntax of the JSONPath expressions * * A JSONPath expression is composed by path indices and operators. * Each path index can either be a member name or an element index inside - * a JSON tree. A JSONPath expression must start with the '$' operator; each + * a JSON tree. A JSONPath expression must start with the `$` operator; each * path index is separated using either the dot notation or the bracket * notation, e.g.: * - * |[ - * // dot notation - * $.store.book[0].title + * ``` + * // dot notation + * $.store.book[0].title * - * // bracket notation - * $['store']['book'][0]['title'] - * ]| + * // bracket notation + * $['store']['book'][0]['title'] + * ``` * * The available operators are: * - * * Root node - * The `$` character represents the root node of the JSON tree, and + * * The `$` character represents the root node of the JSON tree, and * matches the entire document. * * * Child nodes can either be matched using `.` or `[]`. For instance, @@ -95,62 +94,64 @@ * [JSONPath website](http://goessner.net/articles/JsonPath/). * * ## Example of JSONPath matches - * The following example shows some of the results of using #JsonPath + * + * The following example shows some of the results of using `JsonPath` * on a JSON tree. We use the following JSON description of a bookstore: * - * |[ - * { "store": { - * "book": [ - * { "category": "reference", "author": "Nigel Rees", - * "title": "Sayings of the Century", "price": "8.95" }, - * { "category": "fiction", "author": "Evelyn Waugh", - * "title": "Sword of Honour", "price": "12.99" }, - * { "category": "fiction", "author": "Herman Melville", - * "title": "Moby Dick", "isbn": "0-553-21311-3", - * "price": "8.99" }, - * { "category": "fiction", "author": "J. R. R. Tolkien", - * "title": "The Lord of the Rings", "isbn": "0-395-19395-8", - * "price": "22.99" } - * ], - * "bicycle": { "color": "red", "price": "19.95" } - * } + * ```json + * { "store": { + * "book": [ + * { "category": "reference", "author": "Nigel Rees", + * "title": "Sayings of the Century", "price": "8.95" }, + * { "category": "fiction", "author": "Evelyn Waugh", + * "title": "Sword of Honour", "price": "12.99" }, + * { "category": "fiction", "author": "Herman Melville", + * "title": "Moby Dick", "isbn": "0-553-21311-3", + * "price": "8.99" }, + * { "category": "fiction", "author": "J. R. R. Tolkien", + * "title": "The Lord of the Rings", "isbn": "0-395-19395-8", + * "price": "22.99" } + * ], + * "bicycle": { "color": "red", "price": "19.95" } * } - * ]| + * } + * ``` * - * We can parse the JSON using #JsonParser: + * We can parse the JSON using [class@Json.Parser]: * - * |[ - * JsonParser *parser = json_parser_new (); - * json_parser_load_from_data (parser, json_data, -1, NULL); - * ]| + * ```c + * JsonParser *parser = json_parser_new (); + * json_parser_load_from_data (parser, json_data, -1, NULL); + * ``` * * If we run the following code: * - * |[ - * JsonNode *result; - * JsonPath *path = json_path_new (); - * json_path_compile (path, "$.store..author", NULL); - * result = json_path_match (path, json_parser_get_root (parser)); - * ]| + * ```c + * JsonNode *result; + * JsonPath *path = json_path_new (); + * json_path_compile (path, "$.store..author", NULL); + * result = json_path_match (path, json_parser_get_root (parser)); + * ``` * - * The result #JsonNode will contain an array with all values of the + * The `result` node will contain an array with all values of the * author member of the objects in the JSON tree. If we use a - * #JsonGenerator to convert the #JsonNode to a string and print it: + * [class@Json.Generator] to convert the `result` node to a string + * and print it: * - * |[ - * JsonGenerator *generator = json_generator_new (); - * json_generator_set_root (generator, result); - * char *str = json_generator_to_data (generator, NULL); - * g_print ("Results: %s\n", str); - * ]| + * ```c + * JsonGenerator *generator = json_generator_new (); + * json_generator_set_root (generator, result); + * char *str = json_generator_to_data (generator, NULL); + * g_print ("Results: %s\n", str); + * ``` * * The output will be: * - * |[ - * ["Nigel Rees","Evelyn Waugh","Herman Melville","J. R. R. Tolkien"] - * ]| + * ```json + * ["Nigel Rees","Evelyn Waugh","Herman Melville","J. R. R. Tolkien"] + * ``` * - * #JsonPath is available since JSON-GLib 0.14 + * Since: 0.14 */ #include "config.h" @@ -264,13 +265,12 @@ json_path_init (JsonPath *self) /** * json_path_new: * - * Creates a new #JsonPath instance. + * Creates a new `JsonPath` instance. * - * Once created, the #JsonPath object should be used with json_path_compile() - * and json_path_match(). + * Once created, the `JsonPath` object should be used with + * [method@Json.Path.compile] and [method@Json.Path.match]. * - * Return value: (transfer full): the newly created #JsonPath instance. Use - * g_object_unref() to free the allocated resources when done + * Return value: (transfer full): the newly created path * * Since: 0.14 */ @@ -347,17 +347,17 @@ json_path_foreach_print (gpointer data, /** * json_path_compile: - * @path: a #JsonPath + * @path: a path * @expression: a JSONPath expression * @error: return location for a #GError, or %NULL * - * Validates and decomposes @expression. + * Validates and decomposes the given expression. * - * A JSONPath expression must be compiled before calling json_path_match(). + * A JSONPath expression must be compiled before calling + * [method@Json.Path.match]. * - * Return value: %TRUE on success; on error, @error will be set with - * the %JSON_PATH_ERROR domain and a code from the #JsonPathError - * enumeration, and %FALSE will be returned + * Return value: `TRUE` if the compilation was successful, and `FALSE` + * otherwise * * Since: 0.14 */ @@ -924,18 +924,16 @@ walk_path_node (GList *path, /** * json_path_match: - * @path: a compiled #JsonPath - * @root: a #JsonNode + * @path: a compiled path + * @root: the root node of the JSON data to match * - * Matches the JSON tree pointed by @root using the expression compiled - * into the #JsonPath. + * Matches the JSON tree pointed by `root` using the expression compiled + * into the `JsonPath`. * - * The matching #JsonNodes will be copied into a #JsonArray and - * returned wrapped in a #JsonNode. + * The nodes matching the expression will be copied into an array. * - * Return value: (transfer full): a newly-created #JsonNode of type - * %JSON_NODE_ARRAY containing an array of matching #JsonNodes. - * Use json_node_unref() when done + * Return value: (transfer full): a newly-created node of type + * `JSON_NODE_ARRAY` containing the array of matching nodes * * Since: 0.14 */ @@ -968,14 +966,13 @@ json_path_match (JsonPath *path, * * Queries a JSON tree using a JSONPath expression. * - * This function is a simple wrapper around json_path_new(), - * json_path_compile() and json_path_match(). It implicitly - * creates a #JsonPath instance, compiles @expression and - * matches it against the JSON tree pointed by @root. + * This function is a simple wrapper around [ctor@Json.Path.new], + * [method@Json.Path.compile], and [method@Json.Path.match]. It implicitly + * creates a `JsonPath` instance, compiles the given expression and matches + * it against the JSON tree pointed by `root`. * - * Return value: (transfer full): a newly-created #JsonNode of type - * %JSON_NODE_ARRAY containing an array of matching #JsonNodes. - * Use json_node_unref() when done + * Return value: (transfer full): a newly-created node of type + * `JSON_NODE_ARRAY` containing the array of matching nodes * * Since: 0.14 */ diff --git a/json-glib/json-path.h b/json-glib/json-path.h index 3c3ddf0..d9a29d9 100644 --- a/json-glib/json-path.h +++ b/json-glib/json-path.h @@ -38,7 +38,7 @@ G_BEGIN_DECLS /** * JSON_PATH_ERROR: * - * Error domain for #JsonPath errors + * Error domain for `JsonPath`. * * Since: 0.14 */ @@ -48,7 +48,9 @@ G_BEGIN_DECLS * JsonPathError: * @JSON_PATH_ERROR_INVALID_QUERY: Invalid query * - * Error code enumeration for the %JSON_PATH_ERROR domain. + * Error codes for `JSON_PATH_ERROR`. + * + * This enumeration can be extended at later date * * Since: 0.14 */ @@ -56,24 +58,7 @@ typedef enum { JSON_PATH_ERROR_INVALID_QUERY } JsonPathError; -/** - * JsonPath: - * - * The `JsonPath` structure is an opaque object whose members cannot be - * directly accessed except through the provided API. - * - * Since: 0.14 - */ typedef struct _JsonPath JsonPath; - -/** - * JsonPathClass: - * - * The `JsonPathClass` structure is an opaque object class whose members - * cannot be directly accessed. - * - * Since: 0.14 - */ typedef struct _JsonPathClass JsonPathClass; JSON_AVAILABLE_IN_1_0 diff --git a/json-glib/json-reader.c b/json-glib/json-reader.c index f371dd9..cc10cc8 100644 --- a/json-glib/json-reader.c +++ b/json-glib/json-reader.c @@ -21,18 +21,43 @@ */ /** - * 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. + * + * ## Using `JsonReader` + * + * ```c + * g_autoptr(JsonParser) parser = json_parser_new (); + * + * // str is defined elsewhere + * json_parser_load_from_data (parser, str, -1, NULL); + * + * g_autoptr(JsonReader) reader = json_reader_new (json_parser_get_root (parser)); + * + * json_reader_read_member (reader, "url"); + * const char *url = json_reader_get_string_value (reader); + * json_reader_end_member (reader); + * + * json_reader_read_member (reader, "size"); + * json_reader_read_element (reader, 0); + * int width = json_reader_get_int_value (reader); + * json_reader_end_element (reader); + * json_reader_read_element (reader, 1); + * int height = json_reader_get_int_value (reader); + * json_reader_end_element (reader); + * json_reader_end_member (reader); + * ``` + * + * ## Error handling + * + * 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 +68,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]: * - * |[ + * ```c * // like the example above, but in this case we print out the * // error immediately * if (!json_reader_read_element (reader, 6)) @@ -56,9 +81,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" @@ -166,9 +191,9 @@ json_reader_class_init (JsonReaderClass *klass) GObjectClass *gobject_class = G_OBJECT_CLASS (klass); /** - * JsonReader:root: + * JsonReader:root: (attributes org.gtk.Property.set=json_reader_set_root) * - * The root of the JSON tree that the #JsonReader should read. + * The root of the JSON tree that the reader should read. * * Since: 0.12 */ @@ -196,13 +221,14 @@ json_reader_init (JsonReader *self) /** * json_reader_new: - * @node: (allow-none): a #JsonNode, or %NULL + * @node: (nullable): the root node + * + * Creates a new reader. * - * Creates a new #JsonReader. You can use this object to read the contents of - * the JSON tree starting from @node + * You can use this object to read the contents of the JSON tree starting + * from the given node. * - * Return value: the newly created #JsonReader. Use g_object_unref() to - * release the allocated resources when done + * Return value: the newly created reader * * Since: 0.12 */ @@ -214,7 +240,7 @@ json_reader_new (JsonNode *node) /* * json_reader_unset_error: - * @reader: a #JsonReader + * @reader: a reader * * Unsets the error state of @reader, if set * @@ -232,14 +258,13 @@ json_reader_unset_error (JsonReader *reader) } /** - * json_reader_set_root: - * @reader: a #JsonReader - * @root: (allow-none): a #JsonNode + * json_reader_set_root: (attributes org.gtk.Method.set_property=root) + * @reader: a reader + * @root: (nullable): the root node * - * Sets the root #JsonNode to be read by @reader. The @reader will take - * a copy of @root + * Sets the root node of the JSON tree to be read by @reader. * - * If another #JsonNode is currently set as root, it will be replaced. + * The reader will take a copy of the node. * * Since: 0.12 */ @@ -275,16 +300,16 @@ json_reader_set_root (JsonReader *reader, } /* - * json_reader_ser_error: - * @reader: a #JsonReader - * @error_code: the #JsonReaderError code for the error + * json_reader_set_error: + * @reader: a reader + * @error_code: the [error@Json.ReaderError] code for the error * @error_fmt: format string - * @Varargs: list of arguments for the @error_fmt string + * @Varargs: list of arguments for the `error_fmt` string * - * Sets the error state of @reader using the given error code - * and string + * Sets the error state of the reader using the given error code + * and string. * - * Return value: %FALSE, to be used to return immediately from + * Return value: `FALSE`, to be used to return immediately from * the caller function */ G_GNUC_PRINTF (3, 4) @@ -316,12 +341,11 @@ json_reader_set_error (JsonReader *reader, /** * json_reader_get_error: - * @reader: a #JsonReader + * @reader: a reader * - * Retrieves the #GError currently set on @reader, if the #JsonReader - * is in error state + * Retrieves the error currently set on the reader. * - * Return value: (nullable) (transfer none): the pointer to the error, or %NULL + * Return value: (nullable) (transfer none): the current error * * Since: 0.12 */ @@ -335,12 +359,11 @@ json_reader_get_error (JsonReader *reader) /** * json_reader_is_array: - * @reader: a #JsonReader + * @reader: a reader * - * 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 + * Return value: `TRUE` if the reader is on an array * * Since: 0.12 */ @@ -358,12 +381,11 @@ json_reader_is_array (JsonReader *reader) /** * json_reader_is_object: - * @reader: a #JsonReader + * @reader: a reader * - * 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 + * Return value: `TRUE` if the reader is on an object * * Since: 0.12 */ @@ -381,12 +403,11 @@ json_reader_is_object (JsonReader *reader) /** * json_reader_is_value: - * @reader: a #JsonReader + * @reader: a reader * - * 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 + * Return value: `TRUE` if the reader is on a value * * Since: 0.12 */ @@ -405,24 +426,27 @@ json_reader_is_value (JsonReader *reader) /** * json_reader_read_element: - * @reader: a #JsonReader + * @reader: a reader * @index_: the index of the element * - * Advances the cursor of @reader to the element @index_ of the array - * or the object at the current position. + * Advances the cursor of the reader to the element of the array or + * the member of the object at the given position. * - * You can use the json_reader_get_value* family of functions to retrieve - * the value of the element; for instance: + * You can use [method@Json.Reader.get_value] and its wrapper functions to + * retrieve the value of the element; for instance, the following code will + * read the first element of the array at the current cursor position: * - * |[ + * ```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.: + * After reading the value, you should call [method@Json.Reader.end_element] + * to reposition the cursor inside the reader, e.g.: + * + * ```c + * const char *str_value = NULL; * - * |[ * json_reader_read_element (reader, 1); * str_value = json_reader_get_string_value (reader); * json_reader_end_element (reader); @@ -430,27 +454,33 @@ 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 - * put in an error state until json_reader_end_element() is called. This means - * that if used conditionally, json_reader_end_element() must be called on both - * code paths: + * If the 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 reader will be + * put in an error state until [method@Json.Reader.end_element] is called. This + * means that, if used conditionally, [method@Json.Reader.end_element] must be + * called on all branches: * - * |[ + * ```c * if (!json_reader_read_element (reader, 1)) * { + * g_propagate_error (error, json_reader_get_error (reader)); * json_reader_end_element (reader); - * g_set_error (error, …); * return FALSE; * } + * else + * { + * const char *str_value = json_reader_get_string_value (reader); + * json_reader_end_element (reader); * - * str_value = json_reader_get_string_value (reader); - * json_reader_end_element (reader); - * ]| + * // use str_value * - * Return value: %TRUE on success, and %FALSE otherwise + * return TRUE; + * } + * ```c + * + * Return value: `TRUE` on success, and `FALSE` otherwise * * Since: 0.12 */ @@ -524,12 +554,12 @@ json_reader_read_element (JsonReader *reader, /** * json_reader_end_element: - * @reader: a #JsonReader + * @reader: a reader * * 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 the reader, if any was set. * * Since: 0.12 */ @@ -560,13 +590,14 @@ json_reader_end_element (JsonReader *reader) /** * json_reader_count_elements: - * @reader: a #JsonReader + * @reader: a reader + * + * Counts the elements of the current position, if the reader is + * positioned on an array. * - * Counts the elements of the current position, if @reader is - * positioned on an array + * In case of failure, the reader is set to an error state. * - * Return value: the number of elements, or -1. In case of failure - * the #JsonReader is set in an error state + * Return value: the number of elements, or -1. * * Since: 0.12 */ @@ -599,24 +630,24 @@ json_reader_count_elements (JsonReader *reader) /** * json_reader_read_member: - * @reader: a #JsonReader + * @reader: a reader * @member_name: the name of the member to read * - * Advances the cursor of @reader to the @member_name of the object at the - * current position. + * Advances the cursor of the reader to the `member_name` of the object at + * the current position. * - * You can use the json_reader_get_value* family of functions to retrieve - * the value of the member; for instance: + * You can use [method@Json.Reader.get_value] and its wrapper 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.: + * After reading the value, `json_reader_end_member()` should be called to + * reposition the cursor inside the reader, e.g.: * - * |[ + * ```c * json_reader_read_member (reader, "author"); * author = json_reader_get_string_value (reader); * json_reader_end_member (reader); @@ -624,26 +655,32 @@ 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: + * If the reader is not currently on an object, or if the `member_name` is not + * defined in the object, the reader will be put in an error state until + * [method@Json.Reader.end_member] is called. This means that if used + * conditionally, [method@Json.Reader.end_member] must be called on all branches: * - * |[ + * ```c * if (!json_reader_read_member (reader, "title")) * { + * g_propagate_error (error, json_reader_get_error (reader)); * json_reader_end_member (reader); - * g_set_error (error, …); * return FALSE; * } + * else + * { + * const char *str_value = json_reader_get_string_value (reader); + * json_reader_end_member (reader); * - * str_value = json_reader_get_string_value (reader); - * json_reader_end_member (reader); - * ]| + * // use str_value + * + * return TRUE; + * } + * ``` * - * Return value: %TRUE on success, and %FALSE otherwise + * Return value: `TRUE` on success, and `FALSE` otherwise * * Since: 0.12 */ @@ -685,12 +722,12 @@ json_reader_read_member (JsonReader *reader, /** * json_reader_end_member: - * @reader: a #JsonReader + * @reader: a reader * * 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 the reader, if any was set. * * Since: 0.12 */ @@ -720,14 +757,15 @@ json_reader_end_member (JsonReader *reader) /** * json_reader_list_members: - * @reader: a #JsonReader + * @reader: a reader * - * Retrieves a list of member names from the current position, if @reader + * Retrieves a list of member names from the current position, if the reader * is positioned on an object. * - * Return value: (transfer full): a newly allocated, %NULL-terminated - * array of strings holding the members name. Use g_strfreev() when - * done. + * In case of failure, the reader is set to an error state. + * + * Return value: (transfer full) (array zero-terminated=1): the members of + * the object * * Since: 0.14 */ @@ -774,13 +812,14 @@ json_reader_list_members (JsonReader *reader) /** * json_reader_count_members: - * @reader: a #JsonReader + * @reader: a reader * - * Counts the members of the current position, if @reader is - * positioned on an object + * Counts the members of the current position, if the reader is + * positioned on an object. * - * Return value: the number of members, or -1. In case of failure - * the #JsonReader is set in an error state + * In case of failure, the reader is set to an error state. + * + * Return value: the number of members, or -1 * * Since: 0.12 */ @@ -813,13 +852,14 @@ json_reader_count_members (JsonReader *reader) /** * json_reader_get_value: - * @reader: a #JsonReader + * @reader: a reader + * + * Retrieves the value node at the current position of the reader. * - * Retrieves the #JsonNode of the current position of @reader + * If the current position does not contain a scalar value, the reader + * is set to an error state. * - * 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 */ @@ -853,9 +893,11 @@ json_reader_get_value (JsonReader *reader) /** * json_reader_get_int_value: - * @reader: a #JsonReader + * @reader: a reader * - * Retrieves the integer value of the current position of @reader + * Retrieves the integer value of the current position of the reader. + * + * See also: [method@Json.Reader.get_value] * * Return value: the integer value * @@ -891,9 +933,11 @@ json_reader_get_int_value (JsonReader *reader) /** * json_reader_get_double_value: - * @reader: a #JsonReader + * @reader: a reader + * + * Retrieves the floating point value of the current position of the reader. * - * Retrieves the floating point value of the current position of @reader + * See also: [method@Json.Reader.get_value] * * Return value: the floating point value * @@ -929,9 +973,11 @@ json_reader_get_double_value (JsonReader *reader) /** * json_reader_get_string_value: - * @reader: a #JsonReader + * @reader: a reader * - * Retrieves the string value of the current position of @reader + * Retrieves the string value of the current position of the reader. + * + * See also: [method@Json.Reader.get_value] * * Return value: the string value * @@ -974,9 +1020,11 @@ json_reader_get_string_value (JsonReader *reader) /** * json_reader_get_boolean_value: - * @reader: a #JsonReader + * @reader: a reader + * + * Retrieves the boolean value of the current position of the reader. * - * Retrieves the boolean value of the current position of @reader + * See also: [method@Json.Reader.get_value] * * Return value: the boolean value * @@ -1012,11 +1060,13 @@ json_reader_get_boolean_value (JsonReader *reader) /** * json_reader_get_null_value: - * @reader: a #JsonReader + * @reader: a reader * - * Checks whether the value of the current position of @reader is 'null' + * Checks whether the value of the current position of the reader is `null`. * - * Return value: %TRUE if 'null' is set, and %FALSE otherwise + * See also: [method@Json.Reader.get_value] + * + * Return value: `TRUE` if `null` is set, and `FALSE` otherwise * * Since: 0.12 */ @@ -1038,11 +1088,13 @@ json_reader_get_null_value (JsonReader *reader) /** * json_reader_get_member_name: - * @reader: a #JsonReader + * @reader: a reader * * Retrieves the name of the current member. * - * Return value: (nullable) (transfer none): the name of the member, or %NULL + * In case of failure, the reader is set to an error state. + * + * Return value: (nullable) (transfer none): the name of the member * * Since: 0.14 */ diff --git a/json-glib/json-reader.h b/json-glib/json-reader.h index 786ed7b..105e88c 100644 --- a/json-glib/json-reader.h +++ b/json-glib/json-reader.h @@ -41,7 +41,7 @@ G_BEGIN_DECLS /** * JSON_READER_ERROR: * - * Error domain for #JsonReader errors + * Error domain for `JsonReader`. * * Since: 0.12 */ @@ -63,7 +63,9 @@ typedef struct _JsonReaderClass JsonReaderClass; * @JSON_READER_ERROR_INVALID_TYPE: The node at the current position does not * hold a value of the desired type * - * Error codes enumeration for #JsonReader errors + * Error codes for `JSON_READER_ERROR`. + * + * This enumeration can be extended at later date * * Since: 0.12 */ @@ -77,14 +79,6 @@ typedef enum { JSON_READER_ERROR_INVALID_TYPE } JsonReaderError; -/** - * JsonReader: - * - * The `JsonReader` structure contains only private data and should - * be accessed using the provided API - * - * Since: 0.12 - */ struct _JsonReader { /*< private >*/ @@ -93,13 +87,6 @@ struct _JsonReader JsonReaderPrivate *priv; }; -/** - * JsonReaderClass: - * - * The `JsonReaderClass` structure contains only private data - * - * Since: 0.12 - */ struct _JsonReaderClass { /*< private >*/ diff --git a/json-glib/json-serializable.c b/json-glib/json-serializable.c index 8eb64d7..de6c1c4 100644 --- a/json-glib/json-serializable.c +++ b/json-glib/json-serializable.c @@ -18,13 +18,14 @@ */ /** - * SECTION:json-serializable - * @short_description: Interface for serialize and deserialize special GObjects + * JsonSerializable: * - * #JsonSerializable is an interface for #GObject classes that - * allows controlling how the class is going to be serialized - * or deserialized by json_construct_gobject() and - * json_serialize_gobject() respectively. + * `JsonSerializable` is an interface for controlling the serialization + * and deserialization of `GObject` classes. + * + * Implementing this interface allows controlling how the class is going + * to be serialized or deserialized by [func@Json.construct_gobject] and + * [func@Json.serialize_gobject], respectively. */ #include "config.h" @@ -38,15 +39,15 @@ /** * json_serializable_serialize_property: - * @serializable: a #JsonSerializable object - * @property_name: the name of the property - * @value: the value of the property - * @pspec: a #GParamSpec + * @serializable: a serializable object + * @property_name: the name of the property to serialize + * @value: the value of the property to serialize + * @pspec: a property description * - * Asks a #JsonSerializable implementation to serialize a #GObject - * property into a #JsonNode object. + * Asks a `JsonSerializable` implementation to serialize an object + * property into a JSON node. * - * Return value: a #JsonNode containing the serialized property + * Return value: (transfer full): a node containing the serialized property */ JsonNode * json_serializable_serialize_property (JsonSerializable *serializable, @@ -68,21 +69,24 @@ json_serializable_serialize_property (JsonSerializable *serializable, /** * json_serializable_deserialize_property: - * @serializable: a #JsonSerializable - * @property_name: the name of the property - * @value: (out): a pointer to an uninitialized #GValue - * @pspec: a #GParamSpec - * @property_node: a #JsonNode containing the serialized property + * @serializable: a serializable object + * @property_name: the name of the property to serialize + * @value: (out): a pointer to an uninitialized value + * @pspec: a property description + * @property_node: the JSON node containing the serialized property + * + * Asks a `JsonSerializable` implementation to deserialize the + * property contained inside `property_node` and place its value + * into `value`. * - * Asks a #JsonSerializable implementation to deserialize the - * property contained inside @property_node into @value. + * The `value` can be: * - * The @value can be: - * - an empty #GValue initialized by %G_VALUE_INIT, which will be automatically - * initialized with the expected type of the property (since JSON-GLib 1.6) - * - a #GValue initialized with the expected type of the property + * - an empty `GValue` initialized by `G_VALUE_INIT`, which will be automatically + * initialized with the expected type of the property by using the given + * property description (since JSON-GLib 1.6) + * - a `GValue` initialized with the expected type of the property * - * Return value: %TRUE if the property was successfully deserialized. + * Returns: `TRUE` if the property was successfully deserialized */ gboolean json_serializable_deserialize_property (JsonSerializable *serializable, @@ -181,35 +185,37 @@ json_serializable_default_init (JsonSerializableInterface *iface) iface->get_property = json_serializable_real_get_property; } -G_DEFINE_INTERFACE (JsonSerializable, json_serializable, G_TYPE_OBJECT); +G_DEFINE_INTERFACE (JsonSerializable, json_serializable, G_TYPE_OBJECT) /** * json_serializable_default_serialize_property: - * @serializable: a #JsonSerializable object - * @property_name: the name of the property - * @value: the value of the property - * @pspec: a #GParamSpec + * @serializable: a serializable object + * @property_name: the name of the property to serialize + * @value: the value of the property to serialize + * @pspec: a property description + * + * Calls the default implementation of the [vfunc@Json.Serializable.serialize_property] + * virtual function. * - * Calls the default implementation of the #JsonSerializable - * #JsonSerializableIface.serialize_property() virtual function. + * This function can be used inside a custom implementation of the + * `serialize_property()` virtual function in lieu of calling the + * default implementation through `g_type_default_interface_peek()`: * - * This function can be used inside a custom implementation - * of the #JsonSerializableIface.serialize_property() virtual - * function in lieu of calling the default implementation - * through g_type_default_interface_peek(): + * ```c + * JsonSerializable *iface; + * JsonNode *node; * - * |[ - * JsonSerializable *iface; - * JsonNode *node; + * iface = g_type_default_interface_peek (JSON_TYPE_SERIALIZABLE); + * node = iface->serialize_property (serializable, property_name, + * value, + * pspec); + * ``` * - * iface = g_type_default_interface_peek (JSON_TYPE_SERIALIZABLE); - * node = iface->serialize_property (serializable, property_name, - * value, - * pspec); - * ]| + * This function will return `NULL` if the property could not be + * serialized. * - * Return value: (transfer full) (nullable): a #JsonNode containing the - * serialized property, or %NULL if it should be omitted. + * Returns: (transfer full) (nullable): a node containing the + * serialized property * * Since: 0.10 */ @@ -231,30 +237,31 @@ json_serializable_default_serialize_property (JsonSerializable *serializable, /** * json_serializable_default_deserialize_property: - * @serializable: a #JsonSerializable - * @property_name: the name of the property - * @value: a pointer to an uninitialized #GValue - * @pspec: a #GParamSpec - * @property_node: a #JsonNode containing the serialized property + * @serializable: a serializable object + * @property_name: the name of the property to deserialize + * @value: a pointer to an uninitialized value + * @pspec: a property description + * @property_node: the JSON node containing the serialized property * - * Calls the default implementation of the #JsonSerializable - * deserialize_property() virtual function + * Calls the default implementation of the [vfunc@Json.Serializable.deserialize_property] + * virtual function. * - * This function can be used inside a custom implementation - * of the deserialize_property() virtual function in lieu of: + * This function can be used inside a custom implementation of the + * `deserialize_property()` virtual function in lieu of calling the + * default implementation through `g_type_default_interface_peek()`: * - * |[ - * JsonSerializable *iface; - * gboolean res; + * ```c + * JsonSerializable *iface; + * gboolean res; * - * iface = g_type_default_interface_peek (JSON_TYPE_SERIALIZABLE); - * res = iface->deserialize_property (serializable, property_name, - * value, - * pspec, - * property_node); - * ]| + * iface = g_type_default_interface_peek (JSON_TYPE_SERIALIZABLE); + * res = iface->deserialize_property (serializable, property_name, + * value, + * pspec, + * property_node); + * ``` * - * Return value: %TRUE if the property was successfully deserialized. + * Return value: `TRUE` if the property was successfully deserialized * * Since: 0.10 */ @@ -279,14 +286,14 @@ json_serializable_default_deserialize_property (JsonSerializable *serializable, /** * json_serializable_find_property: - * @serializable: a #JsonSerializable + * @serializable: a serializable object * @name: the name of the property * - * Calls the #JsonSerializableIface.find_property() implementation on - * the @serializable instance. * + * Calls the [vfunc@Json.Serializable.find_property] implementation on + * the `JsonSerializable` instance, which will return the property + * description for the given name. * - * Return value: (nullable) (transfer none): the #GParamSpec for the property - * or %NULL if no property was found + * Return value: (nullable) (transfer none): the property description * * Since: 0.14 */ @@ -302,15 +309,15 @@ json_serializable_find_property (JsonSerializable *serializable, /** * json_serializable_list_properties: - * @serializable: a #JsonSerializable - * @n_pspecs: (out): return location for the length of the array - * of #GParamSpec returned by the function + * @serializable: a serializable object + * @n_pspecs: (out): return location for the length of the returned array * - * Calls the #JsonSerializableIface.list_properties() implementation on - * the @serializable instance. + * Calls the [vfunc@Json.Serializable.list_properties] implementation on + * the `JsonSerializable` instance, which will return the list of serializable + * properties. * - * Return value: (array length=n_pspecs) (transfer container): an array - * of #GParamSpec. Use g_free() to free the array when done. + * Return value: (array length=n_pspecs) (transfer container): the serializable + * properties of the object * * Since: 0.14 */ @@ -325,12 +332,13 @@ json_serializable_list_properties (JsonSerializable *serializable, /** * json_serializable_set_property: - * @serializable: a #JsonSerializable - * @pspec: a #GParamSpec + * @serializable: a serializable object + * @pspec: a property description * @value: the property value to set * - * Calls the #JsonSerializableIface.set_property() implementation - * on the @serializable instance. + * Calls the [vfunc@Json.Serializable.set_property] implementation + * on the `JsonSerializable` instance, which will set the property + * with the given value. * * Since: 0.14 */ @@ -350,12 +358,13 @@ json_serializable_set_property (JsonSerializable *serializable, /** * json_serializable_get_property: - * @serializable: a #JsonSerializable - * @pspec: a #GParamSpec + * @serializable: a serializable object + * @pspec: a property description * @value: (out): return location for the property value * - * Calls the #JsonSerializableIface.get_property() implementation - * on the @serializable instance. + * Calls the [vfunc@Json.Serializable.get_property] implementation + * on the `JsonSerializable` instance, which will get the value of + * the given property. * * Since: 0.14 */ diff --git a/json-glib/json-types.h b/json-glib/json-types.h index 5e16d4d..3468257 100644 --- a/json-glib/json-types.h +++ b/json-glib/json-types.h @@ -35,18 +35,18 @@ G_BEGIN_DECLS /** * JSON_NODE_TYPE: - * @node: a #JsonNode + * @node: (type Json.Node): the [struct@Json.Node] to check * - * Evaluates to the #JsonNodeType contained by @node + * Evaluates to the [enum@Json.NodeType] value contained by the node. */ #define JSON_NODE_TYPE(node) (json_node_get_node_type ((node))) /** * JSON_NODE_HOLDS: - * @node: a #JsonNode - * @t: a #JsonNodeType + * @node: (type Json.Node): the [struct@Json.Node] to check + * @t: (type Json.NodeType): the desired [enum@Json.NodeType] * - * Evaluates to %TRUE if the @node holds type @t + * Evaluates to `TRUE` if the node holds the given type. * * Since: 0.10 */ @@ -54,9 +54,9 @@ G_BEGIN_DECLS /** * JSON_NODE_HOLDS_VALUE: - * @node: a #JsonNode + * @node: (type Json.Node): the [struct@Json.Node] to check * - * Evaluates to %TRUE if @node holds a %JSON_NODE_VALUE + * Evaluates to `TRUE` if the node holds a scalar value. * * Since: 0.10 */ @@ -64,9 +64,9 @@ G_BEGIN_DECLS /** * JSON_NODE_HOLDS_OBJECT: - * @node: a #JsonNode + * @node: (type Json.Node): the [struct@Json.Node] to check * - * Evaluates to %TRUE if @node holds a %JSON_NODE_OBJECT + * Evaluates to `TRUE` if the node holds a JSON object. * * Since: 0.10 */ @@ -74,9 +74,9 @@ G_BEGIN_DECLS /** * JSON_NODE_HOLDS_ARRAY: - * @node: a #JsonNode + * @node: (type Json.Node): the [struct@Json.Node] to check * - * Evaluates to %TRUE if @node holds a %JSON_NODE_ARRAY + * Evaluates to `TRUE` if the node holds a JSON array. * * Since: 0.10 */ @@ -84,9 +84,9 @@ G_BEGIN_DECLS /** * JSON_NODE_HOLDS_NULL: - * @node: a #JsonNode + * @node: (type Json.Node): the [struct@Json.Node] to check * - * Evaluates to %TRUE if @node holds a %JSON_NODE_NULL + * Evaluates to `TRUE` if the node holds `null`. * * Since: 0.10 */ @@ -96,39 +96,18 @@ G_BEGIN_DECLS #define JSON_TYPE_OBJECT (json_object_get_type ()) #define JSON_TYPE_ARRAY (json_array_get_type ()) -/** - * JsonNode: - * - * A generic container of JSON data types. The contents of the #JsonNode - * structure are private and should only be accessed via the provided - * functions and never directly. - */ typedef struct _JsonNode JsonNode; - -/** - * JsonObject: - * - * A JSON object type. The contents of the #JsonObject structure are private - * and should only be accessed by the provided API - */ typedef struct _JsonObject JsonObject; - -/** - * JsonArray: - * - * A JSON array type. The contents of the #JsonArray structure are private - * and should only be accessed by the provided API - */ typedef struct _JsonArray JsonArray; /** * JsonNodeType: - * @JSON_NODE_OBJECT: The node contains a #JsonObject - * @JSON_NODE_ARRAY: The node contains a #JsonArray + * @JSON_NODE_OBJECT: The node contains a JSON object + * @JSON_NODE_ARRAY: The node contains a JSON array * @JSON_NODE_VALUE: The node contains a fundamental type * @JSON_NODE_NULL: Special type, for nodes containing null * - * Indicates the content of a #JsonNode. + * Indicates the content of a node. */ typedef enum { JSON_NODE_OBJECT, @@ -139,14 +118,17 @@ typedef enum { /** * JsonObjectForeach: - * @object: the iterated #JsonObject + * @object: the iterated JSON object * @member_name: the name of the member - * @member_node: a #JsonNode containing the @member_name value + * @member_node: the value of the member * @user_data: data passed to the function * - * The function to be passed to json_object_foreach_member(). You - * should not add or remove members to and from @object within - * this function. It is safe to change the value of @member_node. + * The function to be passed to [method@Json.Object.foreach_member]. + * + * You should not add or remove members to and from @object within + * this function. + * + * It is safe to change the value of @member_node. * * Since: 0.8 */ @@ -157,14 +139,17 @@ typedef void (* JsonObjectForeach) (JsonObject *object, /** * JsonArrayForeach: - * @array: the iterated #JsonArray + * @array: the iterated JSON array * @index_: the index of the element - * @element_node: a #JsonNode containing the value at @index_ + * @element_node: the value of the element at the given @index_ * @user_data: data passed to the function * - * The function to be passed to json_array_foreach_element(). You - * should not add or remove elements to and from @array within - * this function. It is safe to change the value of @element_node. + * The function to be passed to [method@Json.Array.foreach_element]. + * + * You should not add or remove elements to and from @array within + * this function. + * + * It is safe to change the value of @element_node. * * Since: 0.8 */ @@ -423,12 +408,15 @@ gboolean json_object_equal (gconstpointer a, /** * JsonObjectIter: * - * An iterator used to iterate over the members of a #JsonObject. This must - * be allocated on the stack and initialised using json_object_iter_init(). - * The order in which members are returned by the iterator is undefined. The - * iterator is invalidated if its #JsonObject is modified during iteration. + * An iterator object used to iterate over the members of a JSON object. + * + * `JsonObjectIter` must be allocated on the stack and initialised using + * [method@Json.ObjectIter.init] or [method@Json.ObjectIter.init_ordered]. + * + * The iterator is invalidated if the object is modified during + * iteration. * - * All the fields in the #JsonObjectIter structure are private and should + * All the fields in the `JsonObjectIter` structure are private and should * never be accessed directly. * * Since: 1.2 diff --git a/json-glib/json-utils.c b/json-glib/json-utils.c index 5fc8496..72c78e5 100644 --- a/json-glib/json-utils.c +++ b/json-glib/json-utils.c @@ -17,14 +17,6 @@ * License along with this library. If not, see . */ -/** - * SECTION:json-utils - * @Title: Utility API - * @Short_description: Various utility functions - * - * Various utility functions. - */ - #include "config.h" #include "json-utils.h" @@ -36,13 +28,14 @@ * @str: a valid UTF-8 string containing JSON data * @error: return location for a #GError * - * Parses the string in @str and returns a #JsonNode representing - * the JSON tree. If @str is empty, this function will return %NULL. + * Parses the given string and returns the corresponding JSON tree. + * + * If the string is empty, this function will return `NULL`. * - * In case of parsing error, this function returns %NULL and sets - * @error appropriately. + * In case of parsing error, this function returns `NULL` and sets + * the error appropriately. * - * Returns: (transfer full) (nullable): a #JsonNode, or %NULL + * Returns: (transfer full) (nullable): the root node of the JSON tree * * Since: 1.2 */ @@ -71,13 +64,13 @@ json_from_string (const char *str, /** * json_to_string: - * @node: a #JsonNode + * @node: a JSON tree * @pretty: whether the output should be prettyfied for printing * * Generates a stringified JSON representation of the contents of - * the passed @node. + * the given `node`. * - * Returns: (transfer full): the string representation of the #JsonNode + * Returns: (transfer full): the string representation of the node * * Since: 1.2 */ diff --git a/json-glib/json-value.c b/json-glib/json-value.c index 1b6f971..77ce864 100644 --- a/json-glib/json-value.c +++ b/json-glib/json-value.c @@ -167,15 +167,13 @@ json_value_free (JsonValue *value) } } -/** +/*< private > * json_value_seal: - * @value: a #JsonValue + * @value: a JSON scalar value * - * Seals the #JsonValue, making it immutable to further changes. + * Seals the value, making it immutable to further changes. * - * If the @value is already immutable, this is a no-op. - * - * Since: 1.2 + * If the value is already immutable, this is a no-op. */ void json_value_seal (JsonValue *value) diff --git a/json-glib/json-version-macros.h b/json-glib/json-version-macros.h index c1c269c..75ac770 100644 --- a/json-glib/json-version-macros.h +++ b/json-glib/json-version-macros.h @@ -41,12 +41,32 @@ #endif /* XXX: Each new cycle should add a new version symbol here */ +/** + * JSON_VERSION_1_0: + * + * The encoded representation of JSON-GLib version "1.0". + */ #define JSON_VERSION_1_0 (G_ENCODE_VERSION (1, 0)) +/** + * JSON_VERSION_1_2: + * + * The encoded representation of JSON-GLib version "1.2". + */ #define JSON_VERSION_1_2 (G_ENCODE_VERSION (1, 2)) +/** + * JSON_VERSION_1_4: + * + * The encoded representation of JSON-GLib version "1.4". + */ #define JSON_VERSION_1_4 (G_ENCODE_VERSION (1, 4)) +/** + * JSON_VERSION_1_6: + * + * The encoded representation of JSON-GLib version "1.6". + */ #define JSON_VERSION_1_6 (G_ENCODE_VERSION (1, 6)) /* evaluates to the current stable version; for development cycles, @@ -73,9 +93,10 @@ * JSON_VERSION_MIN_REQUIRED: * * A macro that should be defined by the user prior to including - * the gdk.h header. - * The definition should be one of the predefined JSON version - * macros: %JSON_VERSION_1_0, %JSON_VERSION_1_2,... + * the `json-glib/json-glib.h` header. + * + * The definition should be one of the predefined JSON-GLib version + * macros: `JSON_VERSION_1_0`, `JSON_VERSION_1_2`, ... * * This macro defines the lower bound for the JSON-GLib API to use. * @@ -93,10 +114,10 @@ * JSON_VERSION_MAX_ALLOWED: * * A macro that should be defined by the user prior to including - * the json-glib.h header. + * the `json-glib/json-glib.h` header. * The definition should be one of the predefined JSON-GLib version - * macros: %JSON_VERSION_1_0, %JSON_VERSION_1_2,... + * macros: `JSON_VERSION_1_0`, `JSON_VERSION_1_2`, ... * * This macro defines the upper bound for the JSON API-GLib to use. * diff --git a/json-glib/json-version.h.in b/json-glib/json-version.h.in index d18caa2..65c343e 100644 --- a/json-glib/json-version.h.in +++ b/json-glib/json-version.h.in @@ -29,56 +29,57 @@ #endif /** - * SECTION:json-version - * @short_description: JSON-GLib version checking - * - * JSON-GLib provides macros to check the version of the library - * at compile-time - */ - -/** * JSON_MAJOR_VERSION: * - * Json major version component (e.g. 1 if %JSON_VERSION is 1.2.3) + * Json major version component (e.g. 1 if `JSON_VERSION` is "1.2.3") */ #define JSON_MAJOR_VERSION (@JSON_MAJOR_VERSION@) /** * JSON_MINOR_VERSION: * - * Json minor version component (e.g. 2 if %JSON_VERSION is 1.2.3) + * Json minor version component (e.g. 2 if `JSON_VERSION` is "1.2.3") */ #define JSON_MINOR_VERSION (@JSON_MINOR_VERSION@) /** * JSON_MICRO_VERSION: * - * Json micro version component (e.g. 3 if %JSON_VERSION is 1.2.3) + * Json micro version component (e.g. 3 if `JSON_VERSION` is "1.2.3") */ #define JSON_MICRO_VERSION (@JSON_MICRO_VERSION@) /** * JSON_VERSION * - * Json version. + * The version of JSON-GLib. */ #define JSON_VERSION (@JSON_VERSION@) /** * JSON_VERSION_S: * - * JSON-GLib version, encoded as a string, useful for printing and + * The version of JSON-GLib, encoded as a string, useful for printing and * concatenation. */ #define JSON_VERSION_S "@JSON_VERSION@" +/** + * JSON_ENCODE_VERSION: + * @major: (type int): the major version to encode + * @minor: (type int): the minor version to encode + * @micro: (type int): the micro version to encode + * + * Encodes a JSON-GLib version in an hexadecimal number, useful for + * integer comparisons. + */ #define JSON_ENCODE_VERSION(major,minor,micro) \ ((major) << 24 | (minor) << 16 | (micro) << 8) /** * JSON_VERSION_HEX: * - * JSON-GLib version, encoded as an hexadecimal number, useful for + * The version of JSON-GLib, encoded as an hexadecimal number, useful for * integer comparisons. */ #define JSON_VERSION_HEX \ @@ -90,8 +91,8 @@ * @minor: required minor version * @micro: required micro version * - * Compile-time version checking. Evaluates to %TRUE if the version - * of Json is greater than the required one. + * Compile-time version checking. Evaluates to `TRUE` if the version + * of JSON-GLib is greater than the required one. */ #define JSON_CHECK_VERSION(major,minor,micro) \ (JSON_MAJOR_VERSION > (major) || \ diff --git a/json-glib/meson.build b/json-glib/meson.build index 70c3171..e13e688 100644 --- a/json-glib/meson.build +++ b/json-glib/meson.build @@ -97,7 +97,7 @@ gir = find_program('g-ir-scanner', required : get_option('introspection')) if gir.found() gir_args = [ '--quiet', - '--c-include=json-glib/json-glib.h', + '--warn-all', '-DJSON_COMPILATION', ] @@ -113,6 +113,7 @@ if gir.found() header: 'json-glib/json-glib.h', install: true, extra_args: gir_args, + fatal_warnings: true, ) else json_glib_gir = [] diff --git a/meson.build b/meson.build index 5613ca5..61fae31 100644 --- a/meson.build +++ b/meson.build @@ -1,11 +1,11 @@ -project('json-glib', 'c', version: '1.6.2', +project('json-glib', 'c', version: '1.6.4', license: 'LGPLv2.1+', default_options: [ 'warning_level=1', 'buildtype=debugoptimized', 'c_std=c99', ], - meson_version: '>= 0.52.0') + meson_version: '>= 0.55.3') # Versioning json_version = meson.project_version() @@ -137,15 +137,12 @@ if get_option('debug') cdata.set('JSON_ENABLE_DEBUG', true) endif -common_ldflags = [] -if host_system == 'linux' - common_ldflags += cc.get_supported_link_arguments([ - '-Wl,-Bsymbolic', - '-Wl,-z,relro', - '-Wl,-z,now', - '-Wl,--default-symver', - ]) -endif +common_ldflags = cc.get_supported_link_arguments([ + '-Wl,-Bsymbolic', + '-Wl,-z,relro', + '-Wl,-z,now', + '-Wl,--default-symver', +]) root_dir = include_directories('.') @@ -157,3 +154,22 @@ gen_installed_test = files('build-aux/gen-installed-test.py') subdir('json-glib') subdir('po') subdir('doc') + +summary({ + 'prefix': get_option('prefix'), + 'includedir': json_includedir, + 'libdir': get_option('prefix') / get_option('libdir'), + 'datadir': json_datadir, + }, + section: 'Directories', +) + +summary({ + 'Introspection': get_option('introspection').enabled() or get_option('introspection').auto(), + 'Documentation': get_option('gtk_doc').enabled() or get_option('gtk_doc').auto(), + 'Manual pages': get_option('man'), + 'Tests': get_option('tests'), + }, + section: 'Build', + bool_yn: true, +) diff --git a/po/gl.po b/po/gl.po index 47b01f7..e724542 100644 --- a/po/gl.po +++ b/po/gl.po @@ -1,13 +1,13 @@ # Galician translation for json-glib. # Copyright (C) 2012 json-glib's COPYRIGHT HOLDER # This file is distributed under the same license as the json-glib package. -# Fran Dieguez , 2012, 2013, 2017, 2018. +# Fran Dieguez , 2012, 2013, 2017, 2018, 2021. msgid "" msgstr "" "Project-Id-Version: json-glib master\n" "Report-Msgid-Bugs-To: https://gitlab.gnome.org/GNOME/json-glib/issues\n" -"POT-Creation-Date: 2018-06-30 18:31+0000\n" -"PO-Revision-Date: 2018-08-30 00:28+0200\n" +"POT-Creation-Date: 2020-06-16 13:37+0000\n" +"PO-Revision-Date: 2021-02-23 20:08+0100\n" "Last-Translator: Fran Dieguez \n" "Language-Team: Proxecto Trasno \n" "Language: gl\n" @@ -15,7 +15,7 @@ msgstr "" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" "Plural-Forms: nplurals=2; plural=(n != 1);\n" -"X-Generator: Virtaal 0.7.1\n" +"X-Generator: Gtranslator 3.38.0\n" "X-Project-Style: gnome\n" #: json-glib/json-glib-format.c:58 @@ -28,7 +28,7 @@ msgstr "Espazos de sangrado" #: json-glib/json-glib-format.c:59 msgid "SPACES" -msgstr "ESPACIOS" +msgstr "ESPAZOS" #: json-glib/json-glib-format.c:60 msgid "Output file" @@ -39,7 +39,6 @@ msgid "FILE" msgstr "FICHEIRO" #: json-glib/json-glib-format.c:61 -#| msgid "FILE" msgid "FILE…" msgstr "FICHEIRO…" @@ -80,7 +79,7 @@ msgstr "%s: %s: erro ao pechar: %s\n" #. and before the list of options. #: json-glib/json-glib-format.c:192 msgid "Format JSON files." -msgstr "Formatea de ficheiros JSON." +msgstr "Formato de ficheiros JSON." #: json-glib/json-glib-format.c:193 msgid "json-glib-format formats JSON resources." @@ -144,26 +143,26 @@ msgstr "Falta o símbolo de peche «)» na tupla de GVariant" msgid "Unexpected extra elements in JSON array" msgstr "Elementos adicionais non agardados no vector JSON" -#: json-glib/json-gvariant.c:909 +#: json-glib/json-gvariant.c:931 msgid "Invalid string value converting to GVariant" msgstr "Valor de cadea non válido ao converter a GVariant" -#: json-glib/json-gvariant.c:964 +#: json-glib/json-gvariant.c:986 msgid "" "A GVariant dictionary entry expects a JSON object with exactly one member" msgstr "" "Unha entrada do dicionario e GVariant agarda un obxecto JSON con só un membro" -#: json-glib/json-gvariant.c:1242 +#: json-glib/json-gvariant.c:1264 #, c-format msgid "GVariant class “%c” not supported" msgstr "Clase «%c» de GVariant non admitida" -#: json-glib/json-gvariant.c:1290 +#: json-glib/json-gvariant.c:1312 msgid "Invalid GVariant signature" msgstr "Firma de GVariant non válida" -#: json-glib/json-gvariant.c:1338 +#: json-glib/json-gvariant.c:1360 msgid "JSON data is empty" msgstr "Datos de JSON baleiros" @@ -192,7 +191,7 @@ msgstr "Nodo raíz seguido dun carácter «%c» non válido" #: json-glib/json-path.c:438 msgid "Missing member name or wildcard after . character" -msgstr "Falta o nome do membro ou comodín logo do caracter «.»" +msgstr "Falta o nome do membro ou comodín logo do carácter «.»" #: json-glib/json-path.c:512 #, c-format @@ -217,7 +216,7 @@ msgstr "Definición de índice de vector non válida «%*s»" #: json-glib/json-path.c:656 #, c-format msgid "Invalid first character “%c”" -msgstr "Primeiro caracter «%c» non válido" +msgstr "Primeiro carácter «%c» non válido" #: json-glib/json-reader.c:474 #, c-format @@ -244,7 +243,7 @@ msgstr "O índice «%d» é maior que o tamaño do obxecto na posición actual." #: json-glib/json-reader.c:951 json-glib/json-reader.c:996 #: json-glib/json-reader.c:1032 json-glib/json-reader.c:1058 msgid "No node available at the current position" -msgstr "Non hai ningún nodo dipoñíbel na posición actual" +msgstr "Non hai ningún nodo dispoñíbel na posición actual" #: json-glib/json-reader.c:592 #, c-format diff --git a/po/ru.po b/po/ru.po index 5b60ba7..b437ac6 100644 --- a/po/ru.po +++ b/po/ru.po @@ -8,11 +8,10 @@ msgid "" msgstr "" "Project-Id-Version: json-glib master\n" -"Report-Msgid-Bugs-To: http://bugzilla.gnome.org/enter_bug.cgi?product=json-" -"glib&keywords=I18N+L10N&component=general\n" -"POT-Creation-Date: 2014-03-10 22:18+0000\n" -"PO-Revision-Date: 2014-03-11 12:23+0300\n" -"Last-Translator: Yuri Myasoedov \n" +"Report-Msgid-Bugs-To: https://gitlab.gnome.org/GNOME/json-glib/issues\n" +"POT-Creation-Date: 2020-06-16 13:37+0000\n" +"PO-Revision-Date: 2021-06-28 14:25+0300\n" +"Last-Translator: Alexey Rubtsov \n" "Language-Team: русский \n" "Language: ru\n" "MIME-Version: 1.0\n" @@ -20,20 +19,37 @@ msgstr "" "Content-Transfer-Encoding: 8bit\n" "Plural-Forms: nplurals=3; plural=(n%10==1 && n%100!=11 ? 0 : n%10>=2 && n" "%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2);\n" -"X-Generator: Poedit 1.5.4\n" +"X-Generator: Poedit 3.0\n" -#: ../json-glib/json-glib-format.c:50 +#: json-glib/json-glib-format.c:58 msgid "Prettify output" msgstr "Выводить в удобочитаемой форме" -#: ../json-glib/json-glib-format.c:51 +#: json-glib/json-glib-format.c:59 msgid "Indentation spaces" msgstr "Отступы" +#: json-glib/json-glib-format.c:59 +msgid "SPACES" +msgstr "ОТСТУПЫ" + +#: json-glib/json-glib-format.c:60 +msgid "Output file" +msgstr "Выходной файл" + +#: json-glib/json-glib-format.c:60 json-glib/json-glib-validate.c:115 +msgid "FILE" +msgstr "ФАЙЛ" + +#: json-glib/json-glib-format.c:61 +msgid "FILE…" +msgstr "ФАЙЛ…" + #. Translators: the first %s is the program name, the second one #. * is the URI of the file, the third is the error message. #. -#: ../json-glib/json-glib-format.c:77 ../json-glib/json-glib-validate.c:63 +#: json-glib/json-glib-format.c:87 json-glib/json-glib-format.c:120 +#: json-glib/json-glib-validate.c:63 #, c-format msgid "%s: %s: error opening file: %s\n" msgstr "%s: %s: не удалось открыть файл: %s\n" @@ -41,7 +57,7 @@ msgstr "%s: %s: не удалось открыть файл: %s\n" #. Translators: the first %s is the program name, the second one #. * is the URI of the file, the third is the error message. #. -#: ../json-glib/json-glib-format.c:89 ../json-glib/json-glib-validate.c:75 +#: json-glib/json-glib-format.c:99 json-glib/json-glib-validate.c:75 #, c-format msgid "%s: %s: error parsing file: %s\n" msgstr "%s: %s: не удалось разобрать файл: %s\n" @@ -49,7 +65,7 @@ msgstr "%s: %s: не удалось разобрать файл: %s\n" #. Translators: the first %s is the program name, the #. * second one is the URI of the file. #. -#: ../json-glib/json-glib-format.c:108 +#: json-glib/json-glib-format.c:138 #, c-format msgid "%s: %s: error writing to stdout" msgstr "%s: %s: не удалось записать в стандартный вывод" @@ -57,22 +73,18 @@ msgstr "%s: %s: не удалось записать в стандартный #. Translators: the first %s is the program name, the second one #. * is the URI of the file, the third is the error message. #. -#: ../json-glib/json-glib-format.c:128 ../json-glib/json-glib-validate.c:87 +#: json-glib/json-glib-format.c:159 json-glib/json-glib-validate.c:87 #, c-format msgid "%s: %s: error closing: %s\n" msgstr "%s: %s: не удалось закрыть: %s\n" -#: ../json-glib/json-glib-format.c:157 ../json-glib/json-glib-validate.c:115 -msgid "FILE" -msgstr "ФАЙЛ" - #. Translators: this message will appear after the usage string #. and before the list of options. -#: ../json-glib/json-glib-format.c:160 +#: json-glib/json-glib-format.c:192 msgid "Format JSON files." msgstr "Форматирование файлов JSON." -#: ../json-glib/json-glib-format.c:161 +#: json-glib/json-glib-format.c:193 msgid "json-glib-format formats JSON resources." msgstr "json-glib-format форматирует ресурсы JSON." @@ -80,184 +92,192 @@ msgstr "json-glib-format форматирует ресурсы JSON." #. * means the user is calling json-glib-validate without any #. * argument. #. -#: ../json-glib/json-glib-format.c:178 ../json-glib/json-glib-validate.c:136 +#: json-glib/json-glib-format.c:208 json-glib/json-glib-validate.c:136 #, c-format msgid "Error parsing commandline options: %s\n" msgstr "Не удалось разобрать параметры командной строки: %s\n" -#: ../json-glib/json-glib-format.c:180 ../json-glib/json-glib-format.c:194 -#: ../json-glib/json-glib-validate.c:138 ../json-glib/json-glib-validate.c:152 +#: json-glib/json-glib-format.c:210 json-glib/json-glib-format.c:224 +#: json-glib/json-glib-validate.c:138 json-glib/json-glib-validate.c:152 #, c-format -msgid "Try \"%s --help\" for more information." -msgstr "Используйте «%s --help» для получения подробной информации." +msgid "Try “%s --help” for more information." +msgstr "" +"Для получения дополнительной информации используйте команду «%s --help»." #. Translators: the %s is the program name. This error message #. * means the user is calling json-glib-validate without any #. * argument. #. -#: ../json-glib/json-glib-format.c:192 ../json-glib/json-glib-validate.c:150 +#: json-glib/json-glib-format.c:222 json-glib/json-glib-validate.c:150 #, c-format msgid "%s: missing files" msgstr "%s: отсутствуют файлы" #. Translators: this message will appear after the usage string #. and before the list of options. -#: ../json-glib/json-glib-validate.c:118 +#: json-glib/json-glib-validate.c:118 msgid "Validate JSON files." msgstr "Проверка корректности файлов JSON." -#: ../json-glib/json-glib-validate.c:119 +#: json-glib/json-glib-validate.c:119 msgid "json-glib-validate validates JSON data at the given URI." msgstr "" "json-glib-validate проверяет корректность данных JSON по заданному URI." -#: ../json-glib/json-gobject.c:917 +#. translators: the %s is the name of the data structure +#: json-glib/json-gobject.c:940 #, c-format -msgid "Expecting a JSON object, but the root node is of type `%s'" +msgid "Expecting a JSON object, but the root node is of type “%s”" msgstr "Ожидается объект JSON, но корневой узел имеет тип «%s»" -#: ../json-glib/json-gvariant.c:545 +#. translators: the '%s' is the type name +#: json-glib/json-gvariant.c:524 #, c-format -msgid "Unexpected type '%s' in JSON node" +msgid "Unexpected type “%s” in JSON node" msgstr "Неожиданный тип «%s» в узле JSON" -#: ../json-glib/json-gvariant.c:615 +#: json-glib/json-gvariant.c:594 msgid "Missing elements in JSON array to conform to a tuple" msgstr "Отсутствуют элементы в массиве JSON для соответствия кортежу" -#: ../json-glib/json-gvariant.c:643 -msgid "Missing closing symbol ')' in the GVariant tuple type" +#: json-glib/json-gvariant.c:622 +msgid "Missing closing symbol “)” in the GVariant tuple type" msgstr "Отсутствует закрывающий символ «)» в кортеже типа GVariant" -#: ../json-glib/json-gvariant.c:651 +#: json-glib/json-gvariant.c:630 msgid "Unexpected extra elements in JSON array" msgstr "Неожиданные дополнительные символы в массиве JSON" -#: ../json-glib/json-gvariant.c:930 +#: json-glib/json-gvariant.c:931 msgid "Invalid string value converting to GVariant" msgstr "Некорректное строковое значение для преобразования к GVariant" -#: ../json-glib/json-gvariant.c:986 +#: json-glib/json-gvariant.c:986 msgid "" "A GVariant dictionary entry expects a JSON object with exactly one member" msgstr "" "Элемент словаря GVariant должен быть объектом JSON с единственным членом" -#: ../json-glib/json-gvariant.c:1266 +#: json-glib/json-gvariant.c:1264 #, c-format -msgid "GVariant class '%c' not supported" +msgid "GVariant class “%c” not supported" msgstr "Класс GVariant «%c» не поддерживается" -#: ../json-glib/json-gvariant.c:1314 +#: json-glib/json-gvariant.c:1312 msgid "Invalid GVariant signature" msgstr "Недопустимая подпись GVariant" -#: ../json-glib/json-gvariant.c:1362 +#: json-glib/json-gvariant.c:1360 msgid "JSON data is empty" msgstr "Данные JSON отсутствуют" -#: ../json-glib/json-parser.c:817 +#. translators: %s: is the file name, the first %d is the line +#. * number, the second %d is the position on the line, and %s is +#. * the error message +#. +#: json-glib/json-parser.c:909 #, c-format msgid "%s:%d:%d: Parse error: %s" msgstr "%s:%d:%d: ошибка разбора: %s" -#: ../json-glib/json-parser.c:885 +#: json-glib/json-parser.c:992 msgid "JSON data must be UTF-8 encoded" msgstr "Данные JSON должны быть в кодировке UTF-8" -#: ../json-glib/json-path.c:438 +#: json-glib/json-path.c:389 msgid "Only one root node is allowed in a JSONPath expression" msgstr "В выражении JSONPath может быть только один корневой узел" -#: ../json-glib/json-path.c:447 +#. translators: the %c is the invalid character +#: json-glib/json-path.c:398 #, c-format -msgid "Root node followed by invalid character '%c'" +msgid "Root node followed by invalid character “%c”" msgstr "Корневой узел заканчивается некорректным символом «%c»" -#: ../json-glib/json-path.c:487 +#: json-glib/json-path.c:438 msgid "Missing member name or wildcard after . character" msgstr "Отсутствует имя члена или шаблон после символа «.»" -#: ../json-glib/json-path.c:561 +#: json-glib/json-path.c:512 #, c-format -msgid "Malformed slice expression '%*s'" +msgid "Malformed slice expression “%*s”" msgstr "Неправильное выражение среза «%*s»" -#: ../json-glib/json-path.c:605 +#: json-glib/json-path.c:556 #, c-format -msgid "Invalid set definition '%*s'" -msgstr "Неверное определение присвоения «%*s»" +msgid "Invalid set definition “%*s”" +msgstr "Неверное определение набора «%*s»" -#: ../json-glib/json-path.c:658 +#: json-glib/json-path.c:609 #, c-format -msgid "Invalid slice definition '%*s'" +msgid "Invalid slice definition “%*s”" msgstr "Неверное определение среза «%*s»" -#: ../json-glib/json-path.c:686 +#: json-glib/json-path.c:637 #, c-format -msgid "Invalid array index definition '%*s'" +msgid "Invalid array index definition “%*s”" msgstr "Неверное определение индекса массива «%*s»" -#: ../json-glib/json-path.c:705 +#: json-glib/json-path.c:656 #, c-format -msgid "Invalid first character '%c'" +msgid "Invalid first character “%c”" msgstr "Неверный первый символ «%c»" -#: ../json-glib/json-reader.c:463 +#: json-glib/json-reader.c:474 #, c-format msgid "" -"The current node is of type '%s', but an array or an object was expected." +"The current node is of type “%s”, but an array or an object was expected." msgstr "Текущий узел имеет тип «%s», но ожидается массив или объект." -#: ../json-glib/json-reader.c:475 +#: json-glib/json-reader.c:486 #, c-format msgid "" -"The index '%d' is greater than the size of the array at the current position." +"The index “%d” is greater than the size of the array at the current position." msgstr "В текущей позиции индекс «%d» больше размера массива." -#: ../json-glib/json-reader.c:492 +#: json-glib/json-reader.c:503 #, c-format msgid "" -"The index '%d' is greater than the size of the object at the current " +"The index “%d” is greater than the size of the object at the current " "position." -msgstr "В текущей позиции индекс «%d» больше размера объекта." +msgstr "Индекс «%d» больше, чем размер объекта в текущей позиции." -#: ../json-glib/json-reader.c:577 ../json-glib/json-reader.c:731 -#: ../json-glib/json-reader.c:782 ../json-glib/json-reader.c:820 -#: ../json-glib/json-reader.c:858 ../json-glib/json-reader.c:896 -#: ../json-glib/json-reader.c:934 ../json-glib/json-reader.c:979 -#: ../json-glib/json-reader.c:1015 ../json-glib/json-reader.c:1041 +#: json-glib/json-reader.c:585 json-glib/json-reader.c:751 +#: json-glib/json-reader.c:799 json-glib/json-reader.c:837 +#: json-glib/json-reader.c:875 json-glib/json-reader.c:913 +#: json-glib/json-reader.c:951 json-glib/json-reader.c:996 +#: json-glib/json-reader.c:1032 json-glib/json-reader.c:1058 msgid "No node available at the current position" msgstr "В текущей позиции отсутствует узел" -#: ../json-glib/json-reader.c:584 +#: json-glib/json-reader.c:592 #, c-format -msgid "The current position holds a '%s' and not an array" -msgstr "В текущей позиции содержится «%s», а не массив" +msgid "The current position holds a “%s” and not an array" +msgstr "Текущая позиция содержит «%s», а не массив" -#: ../json-glib/json-reader.c:647 +#: json-glib/json-reader.c:668 #, c-format -msgid "The current node is of type '%s', but an object was expected." +msgid "The current node is of type “%s”, but an object was expected." msgstr "Текущий узел имеет тип «%s», но ожидается объект." -#: ../json-glib/json-reader.c:654 +#: json-glib/json-reader.c:675 #, c-format -msgid "The member '%s' is not defined in the object at the current position." +msgid "The member “%s” is not defined in the object at the current position." msgstr "В текущей позиции член «%s» не определён в объекте." -#: ../json-glib/json-reader.c:738 ../json-glib/json-reader.c:789 +#: json-glib/json-reader.c:758 json-glib/json-reader.c:806 #, c-format -msgid "The current position holds a '%s' and not an object" +msgid "The current position holds a “%s” and not an object" msgstr "В текущей позиции содержится «%s», а не объект" -#: ../json-glib/json-reader.c:829 ../json-glib/json-reader.c:867 -#: ../json-glib/json-reader.c:905 ../json-glib/json-reader.c:943 -#: ../json-glib/json-reader.c:988 +#: json-glib/json-reader.c:846 json-glib/json-reader.c:884 +#: json-glib/json-reader.c:922 json-glib/json-reader.c:960 +#: json-glib/json-reader.c:1005 #, c-format -msgid "The current position holds a '%s' and not a value" +msgid "The current position holds a “%s” and not a value" msgstr "В текущей позиции содержится «%s», а не значение" -#: ../json-glib/json-reader.c:951 +#: json-glib/json-reader.c:968 msgid "The current position does not hold a string type" msgstr "В текущей позиции не содержится строковое значение" diff --git a/subprojects/gi-docgen.wrap b/subprojects/gi-docgen.wrap new file mode 100644 index 0000000..98cd921 --- /dev/null +++ b/subprojects/gi-docgen.wrap @@ -0,0 +1,6 @@ +[wrap-git] +directory=gi-docgen +url=https://gitlab.gnome.org/GNOME/gi-docgen.git +push-url=ssh://git@gitlab.gnome.org:GNOME/gi-docgen.git +revision=main +depth=1 diff --git a/subprojects/glib.wrap b/subprojects/glib.wrap index 87021ae..b492f23 100644 --- a/subprojects/glib.wrap +++ b/subprojects/glib.wrap @@ -2,4 +2,4 @@ directory=glib url=https://gitlab.gnome.org/GNOME/glib.git push-url=git@gitlab.gnome.org:GNOME/glib.git -revision=master +revision=main -- 2.7.4