Use gi-docgen to build the API reference

The gi-docgen utility generates documentation from introspection data,
which means it's faster than gtk-doc, and matches the expectation of
what kind of API we expose to projects.

5 files changed, 172 insertions, 33 deletions

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.toml.in b/doc/json-glib.toml.in
new file mode 100644
index 0000000..af43d54
--- /dev/null
+++ b/doc/json-glib.toml.in
@@ -0,0 +1,35 @@
+[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
+
+[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',
+]
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..aefc0e8 100644
--- a/doc/meson.build
+++ b/doc/meson.build
@@ -1,43 +1,46 @@
-if find_program('gtkdoc-scan', required : get_option('gtk_doc')).found()
-  subdir('xml')
+if get_option('gtk_doc').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())
+
+  json_toml = configure_file(
+    input: 'json-glib.toml.in',
+    output: 'json-glib.toml',
+    configuration: toml_conf,
+  )
 
-  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_content_files = [
+    'json-gboxed.md',
+    'json-gobject.md',
+    'json-gvariant.md',
+  ]
 
-  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')),
+  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,
   )
 endif