docs: Move the datalist and dataset SECTIONs

Move them to a separate page as they don’t really have a ‘class’ struct
each to hang docs off.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Helps: #3037

docs/reference/glib/datalist-and-dataset.md

@@ -0,0 +1,78 @@
+Title: Keyed Data Lists and Datasets
+SPDX-License-Identifier: LGPL-2.1-or-later
+SPDX-FileCopyrightText: 1999 Owen Taylor
+SPDX-FileCopyrightText: 2000 Red Hat, Inc.
+SPDX-FileCopyrightText: 2005 Tim Janik
+
+## Keyed Data Lists
+
+Keyed data lists provide lists of arbitrary data elements which can
+be accessed either with a string or with a [type@GLib.Quark] corresponding to
+the string.
+
+The [type@GLib.Quark] methods are quicker, since the strings have to be
+converted to [type@GLib.Quark]s anyway.
+
+Data lists are used for associating arbitrary data with
+[class@GObject.Object]s, using [method@GObject.Object.set_data] and related
+functions. The data is stored inside opaque [type@GLib.Data] elements.
+
+To create a datalist, use [func@GLib.datalist_init].
+
+To add data elements to a datalist use [func@GLib.datalist_id_set_data],
+[func@GLib.datalist_id_set_data_full], [func@GLib.datalist_set_data],
+[func@GLib.datalist_set_data_full] and [func@GLib.datalist_id_replace_data].
+
+To get data elements from a datalist use [func@GLib.datalist_id_get_data],
+[func@GLib.datalist_get_data] and [func@GLib.datalist_id_dup_data].
+
+To iterate over all data elements in a datalist use
+[func@GLib.datalist_foreach] (not thread-safe).
+
+To remove data elements from a datalist use
+[func@GLib.datalist_id_remove_data], [func@GLib.datalist_remove_data] and
+[func@GLib.datalist_id_remove_multiple]. To remove elements without destroying
+them, use [func@GLib.datalist_id_remove_no_notify] and
+[func@GLib.datalist_remove_no_notify].
+
+To remove all data elements from a datalist, use [func@GLib.datalist_clear].
+
+A small number of boolean flags can be stored alongside a datalist, using
+[func@GLib.datalist_set_flags], [func@GLib.datalist_unset_flags] and
+[func@GLib.datalist_get_flags].
+
+## Datasets
+
+Datasets associate groups of data elements with particular memory
+locations. These are useful if you need to associate data with a
+structure returned from an external library. Since you cannot modify
+the structure, you use its location in memory as the key into a
+dataset, where you can associate any number of data elements with it.
+
+There are two forms of most of the dataset functions. The first form
+uses strings to identify the data elements associated with a
+location. The second form uses [type@GLib.Quark] identifiers, which are
+created with a call to [func@GLib.quark_from_string] or
+[func@GLib.quark_from_static_string]. The second form is quicker, since it
+does not require looking up the string in the hash table of [type@GLib.Quark]
+identifiers.
+
+There is no function to create a dataset. It is automatically
+created as soon as you add elements to it.
+
+To add data elements to a dataset use [func@GLib.dataset_id_set_data],
+[func@GLib.dataset_id_set_data_full], [func@GLib.dataset_set_data] and
+[func@GLib.dataset_set_data_full].
+
+To get data elements from a dataset use [func@GLib.dataset_id_get_data] and
+[func@GLib.dataset_get_data].
+
+To iterate over all data elements in a dataset use
+[func@GLib.dataset_foreach] (not thread-safe).
+
+To remove data elements from a dataset use
+[func@GLib.dataset_id_remove_data] and [func@GLib.dataset_remove_data]. To
+remove data without destroying it, use [func@GLib.dataset_id_remove_no_notify]
+and [func@GLib.dataset_remove_no_notify].
+
+To destroy a dataset, use [func@GLib.dataset_destroy].

docs/reference/glib/glib.toml.in

@@ -76,6 +76,7 @@ content_files = [
   "base64.md",
   "goption.md",
   "data-structures.md",
+  "datalist-and-dataset.md",
   "shell.md",
   "uuid.md",
   "unicode.md",

docs/reference/glib/meson.build

@@ -151,6 +151,7 @@ expand_content_files = [
   'character-set.md',
   'compiling.md',
   'cross-compiling.md',
+  'datalist-and-dataset.md',
   'error-reporting.md',
   'file-utils.md',
   'gvariant-format-strings.md',

glib/gdataset.c

@@ -48,85 +48,12 @@
 #include "glib_trace.h"
 #include "galloca.h"
 
-/**
- * SECTION:datasets
- * @title: Datasets
- * @short_description: associate groups of data elements with
- *                     particular memory locations
- *
- * Datasets associate groups of data elements with particular memory
- * locations. These are useful if you need to associate data with a
- * structure returned from an external library. Since you cannot modify
- * the structure, you use its location in memory as the key into a
- * dataset, where you can associate any number of data elements with it.
- *
- * There are two forms of most of the dataset functions. The first form
- * uses strings to identify the data elements associated with a
- * location. The second form uses #GQuark identifiers, which are
- * created with a call to g_quark_from_string() or
- * g_quark_from_static_string(). The second form is quicker, since it
- * does not require looking up the string in the hash table of #GQuark
- * identifiers.
- *
- * There is no function to create a dataset. It is automatically
- * created as soon as you add elements to it.
- *
- * To add data elements to a dataset use g_dataset_id_set_data(),
- * g_dataset_id_set_data_full(), g_dataset_set_data() and
- * g_dataset_set_data_full().
- *
- * To get data elements from a dataset use g_dataset_id_get_data() and
- * g_dataset_get_data().
- *
- * To iterate over all data elements in a dataset use
- * g_dataset_foreach() (not thread-safe).
- *
- * To remove data elements from a dataset use
- * g_dataset_id_remove_data() and g_dataset_remove_data().
- *
- * To destroy a dataset, use g_dataset_destroy().
- **/
-
-/**
- * SECTION:datalist
- * @title: Keyed Data Lists
- * @short_description: lists of data elements which are accessible by a
- *                     string or GQuark identifier
- *
- * Keyed data lists provide lists of arbitrary data elements which can
- * be accessed either with a string or with a #GQuark corresponding to
- * the string.
- *
- * The #GQuark methods are quicker, since the strings have to be
- * converted to #GQuarks anyway.
- *
- * Data lists are used for associating arbitrary data with #GObjects,
- * using g_object_set_data() and related functions.
- *
- * To create a datalist, use g_datalist_init().
- *
- * To add data elements to a datalist use g_datalist_id_set_data(),
- * g_datalist_id_set_data_full(), g_datalist_set_data() and
- * g_datalist_set_data_full().
- *
- * To get data elements from a datalist use g_datalist_id_get_data()
- * and g_datalist_get_data().
- *
- * To iterate over all data elements in a datalist use
- * g_datalist_foreach() (not thread-safe).
- *
- * To remove data elements from a datalist use
- * g_datalist_id_remove_data() and g_datalist_remove_data().
- *
- * To remove all data elements from a datalist, use g_datalist_clear().
- **/
-
 /**
  * GData:
  *
  * An opaque data structure that represents a keyed data list.
  *
- * See also: [Keyed data lists][glib-Keyed-Data-Lists].
+ * See also: [Keyed data lists](datalist-and-dataset.html).
  **/
 
 /**

glib/gquark.c

@@ -78,8 +78,8 @@ g_quark_init (void)
  * Given either the string or the `GQuark` identifier it is possible to
  * retrieve the other.
  *
- * Quarks are used for both [datasets][glib-Datasets] and
- * [keyed data lists][glib-Keyed-Data-Lists].
+ * Quarks are used for both
+ * [datasets and keyed data lists](datalist-and-dataset.html).
  *
  * To create a new quark from a string, use [func@GLib.quark_from_string]
  * or [func@GLib.quark_from_static_string].