docs: Initial, rough port away from gtk-doc

Drop `SECTION` blurbs.

Use gi-docgen syntax for internal links.

Use summary lines for gi-docgen indices.

Use Markdown syntax for code fragments.

1 files changed, 44 insertions, 41 deletions

diff --git a/json-glib/json-generator.c b/json-glib/json-generator.c
index 4ccf320..dc67c78 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,7 +232,7 @@ 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
    * stream.
@@ -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,9 +471,10 @@ 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 `JsonNode`s.
  *
  * Return value: the newly created #JsonGenerator instance
  */
@@ -486,8 +489,7 @@ json_generator_new (void)
  * @generator: a #JsonGenerator
  * @string: a #GString
  *
- * Generates a JSON data stream from @generator
- * and appends it to @string.
+ * Generates a JSON data stream from @generator and appends it to @string.
  *
  * Return value: (transfer none): a #GString holding a JSON data stream.
  *   Use g_string_free() to free the allocated resources.
@@ -513,14 +515,13 @@ 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
+ * @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,
@@ -546,7 +547,9 @@ json_generator_to_data (JsonGenerator *generator,
  * @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.
+ * current file contents.
+ *
+ * This operation is atomic.
  *
  * Return value: %TRUE if saving was successful.
  */
@@ -573,13 +576,12 @@ json_generator_to_file (JsonGenerator  *generator,
  * json_generator_to_stream:
  * @generator: a #JsonGenerator
  * @stream: a #GOutputStream
- * @cancellable: (allow-none): a #GCancellable, or %NULL
+ * @cancellable: (nullable): a #GCancellable
  * @error: return location for a #GError, or %NULL
  *
  * Outputs JSON data and streams it (synchronously) to @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,7 +609,7 @@ json_generator_to_stream (JsonGenerator  *generator,
 }
 
 /**
- * json_generator_set_root:
+ * json_generator_set_root: (attributes org.gtk.Method.set_property=root)
  * @generator: a #JsonGenerator
  * @node: a #JsonNode
  *
@@ -639,14 +641,13 @@ json_generator_set_root (JsonGenerator *generator,
 }
 
 /**
- * json_generator_get_root:
+ * json_generator_get_root: (attributes org.gtk.Method.get_property=root)
  * @generator: a #JsonGenerator
  *
- * 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 +660,15 @@ json_generator_get_root (JsonGenerator *generator)
 }
 
 /**
- * json_generator_set_pretty:
+ * json_generator_set_pretty: (attributes org.gtk.Method.set_property=pretty)
  * @generator: a #JsonGenerator
  * @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,10 +693,10 @@ json_generator_set_pretty (JsonGenerator *generator,
 }
 
 /**
- * json_generator_get_pretty:
+ * json_generator_get_pretty: (attributes org.gtk.Method.get_property=pretty)
  * @generator: a #JsonGenerator
  *
- * 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
@@ -709,7 +712,7 @@ json_generator_get_pretty (JsonGenerator *generator)
 }
 
 /**
- * json_generator_set_indent:
+ * json_generator_set_indent: (attributes org.gtk.Method.set_property=indent)
  * @generator: a #JsonGenerator
  * @indent_level: the number of repetitions of the indentation character
  *   that should be applied when pretty printing
@@ -737,10 +740,10 @@ json_generator_set_indent (JsonGenerator *generator,
 }
 
 /**
- * json_generator_get_indent:
+ * json_generator_get_indent: (attributes org.gtk.Method.get_property=indent)
  * @generator: a #JsonGenerator
  *
- * 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
  *
@@ -755,7 +758,7 @@ json_generator_get_indent (JsonGenerator *generator)
 }
 
 /**
- * json_generator_set_indent_char:
+ * json_generator_set_indent_char: (attributes org.gtk.Method.set_property=indent-char)
  * @generator: a #JsonGenerator
  * @indent_char: a Unicode character to be used when indenting
  *
@@ -782,10 +785,10 @@ json_generator_set_indent_char (JsonGenerator *generator,
 }
 
 /**
- * json_generator_get_indent_char:
+ * json_generator_get_indent_char: (attributes org.gtk.Method.get_property=indent-char)
  * @generator: a #JsonGenerator
  *
- * 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
  *