[gtk/docs-gtk-org] gobject: Add a description page for GValue

[Emmanuele Bassi <ebassi src gnome org>]

commit ca8e0284646c5a7c871489fd5ce9a5e7a380fc0c
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Sun Nov 7 17:31:32 2021 +0000

    gobject: Add a description page for GValue
    
    From the GValue section description in the gtk-doc reference.

 glib/gobject/gobject.toml.in |  1 +
 glib/gobject/gvalue.md       | 83 ++++++++++++++++++++++++++++++++++++++++++++
 glib/gobject/meson.build     |  1 +
 3 files changed, 85 insertions(+)
---
diff --git a/glib/gobject/gobject.toml.in b/glib/gobject/gobject.toml.in
index 26b8faa0f1..f82585abfc 100644
--- a/glib/gobject/gobject.toml.in
+++ b/glib/gobject/gobject.toml.in
@@ -39,6 +39,7 @@ content_files = [
   "tutorial.md",
   "floating-refs.md",
   "boxed.md",
+  "gvalue.md",
 ]
 content_images = [
   "images/glue.png",
diff --git a/glib/gobject/gvalue.md b/glib/gobject/gvalue.md
new file mode 100644
index 0000000000..b9634fb717
--- /dev/null
+++ b/glib/gobject/gvalue.md
@@ -0,0 +1,83 @@
+Title: Generic value container
+
+# Generic value container
+
+The [`struct@GObject.Value`] structure is basically a variable container
+that consists of a type identifier and a specific value of that type. The
+type identifier within a `GValue` structure always determines the type of the
+associated value.
+
+To create an undefined `GValue` structure, simply create a zero-filled
+GValue structure. To initialize the `GValue`, use the
+[`method GObject Value init`] function. A `GValue` cannot be used until it
+is initialized.
+
+Once you have finished using a `GValue`, you must call
+[`method@GObject.Value.unset`] to ensure that all the resources associated
+with the `GValue` are freed.
+
+The basic type operations (such as freeing and copying) are determined by
+the [`struct@GObject.TypeValueTable`] associated with the type ID stored in
+the `GValue`. Other `GValue` operations (such as converting values between
+types) are provided by this interface.
+
+The code in the example program below demonstrates `GValue`'s features:
+
+```c
+#include <glib-object.h>
+
+static void
+int2string (const GValue *src_value,
+            GValue       *dest_value)
+{
+  if (g_value_get_int (src_value) == 42)
+    g_value_set_static_string (dest_value, "An important number");
+  else
+    g_value_set_static_string (dest_value, "What's that?");
+}
+
+int
+main (int   argc,
+      char *argv[])
+{
+  // GValues must be initialized
+  GValue a = G_VALUE_INIT;
+  GValue b = G_VALUE_INIT;
+  const char *message;
+
+  // The GValue starts empty
+  g_assert (!G_VALUE_HOLDS_STRING (&a));
+
+  // Put a string in it
+  g_value_init (&a, G_TYPE_STRING);
+  g_assert (G_VALUE_HOLDS_STRING (&a));
+  g_value_set_static_string (&a, "Hello, world!");
+  g_printf ("%s\n", g_value_get_string (&a));
+
+  // Reset it to its pristine state
+  g_value_unset (&a);
+
+  // It can then be reused for another type
+  g_value_init (&a, G_TYPE_INT);
+  g_value_set_int (&a, 42);
+
+  // Attempt to transform it into a GValue of type STRING
+  g_value_init (&b, G_TYPE_STRING);
+
+  // An INT is transformable to a STRING
+  g_assert (g_value_type_transformable (G_TYPE_INT, G_TYPE_STRING));
+
+  g_value_transform (&a, &b);
+  g_printf ("%s\n", g_value_get_string (&b));
+
+  // Attempt to transform it again using a custom transform function
+  g_value_register_transform_func (G_TYPE_INT, G_TYPE_STRING, int2string);
+  g_value_transform (&a, &b);
+  g_printf ("%s\n", g_value_get_string (&b));
+
+  g_value_unset (&b);
+  g_value_unset (&a);
+
+  return 0;
+}
+```
diff --git a/glib/gobject/meson.build b/glib/gobject/meson.build
index 442896625a..55f978ea1c 100644
--- a/glib/gobject/meson.build
+++ b/glib/gobject/meson.build
@@ -2,6 +2,7 @@ expand_content_files = [
   'boxed.md',
   'concepts.md',
   'floating-refs.md',
+  'gvalue.md',
   'tutorial.md',
 ]