[gtk/docs-gtk-org] gobject: Add section on enumeration types

[Emmanuele Bassi <ebassi src gnome org>]

commit 1601b21160d256add91d56a5083a956a62cd5666
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Sun Nov 7 17:41:34 2021 +0000

    gobject: Add section on enumeration types
    
    Port the enumeration and flag types section from the gtk-doc reference.

 glib/gobject/enum-types.md   | 36 ++++++++++++++++++++++++++++++++++++
 glib/gobject/gobject.toml.in |  1 +
 glib/gobject/meson.build     |  1 +
 3 files changed, 38 insertions(+)
---
diff --git a/glib/gobject/enum-types.md b/glib/gobject/enum-types.md
new file mode 100644
index 0000000000..d869f8a93a
--- /dev/null
+++ b/glib/gobject/enum-types.md
@@ -0,0 +1,36 @@
+Title: Enumeration types
+
+# Enumeration types
+
+The GLib type system provides fundamental types for enumeration and flags
+types. Enumerations types are collection of identifiers associated with a
+numeric value; flags types are like enumerations, but allow their values to
+be combined by bitwise or.
+
+A registered enumeration or flags type associates a name and a nickname with
+each allowed value, and the methods [`func@GObject.enum_get_value_by_name`],
+[`func@GObject.enum_get_value_by_nick`], [`func@GObject.flags_get_value_by_name`] and
+[`func@GObject.flags_get_value_by_nick`] can look up values by their name or nickname.
+
+When an enumeration or flags type is registered with the GLib type system,
+it can be used as value type for object properties, using
+[`func@GObject.param_spec_enum`] or [`func@GObject.param_spec_flags`].
+
+GObject ships with a utility called `glib-mkenums`, that can construct
+suitable type registration functions from C enumeration definitions.
+
+Example of how to get a string representation of an enum value:
+
+```c
+GEnumClass *enum_class;
+GEnumValue *enum_value;
+
+enum_class = g_type_class_ref (EXAMPLE_TYPE_ENUM);
+enum_value = g_enum_get_value (enum_class, EXAMPLE_ENUM_FOO);
+
+g_print ("Name: %s\n", enum_value->value_name);
+
+g_type_class_unref (enum_class);
+```
+
+Alternatively, you can use [`func@GObject.enum_to_string`].
diff --git a/glib/gobject/gobject.toml.in b/glib/gobject/gobject.toml.in
index f82585abfc..219d3a3853 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",
+  "enum-types.md",
   "gvalue.md",
 ]
 content_images = [
diff --git a/glib/gobject/meson.build b/glib/gobject/meson.build
index 55f978ea1c..caa9f41476 100644
--- a/glib/gobject/meson.build
+++ b/glib/gobject/meson.build
@@ -1,6 +1,7 @@
 expand_content_files = [
   'boxed.md',
   'concepts.md',
+  'enum-types.md',
   'floating-refs.md',
   'gvalue.md',
   'tutorial.md',