From 58019515d6933c5b72ab0e8df60c8006032b7eb5 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Mon, 9 Oct 2023 23:16:51 +0100 Subject: [PATCH] docs: Move enum type documentation to Markdown Helps: #3037 --- docs/reference/gobject/enum-types.md | 36 +++++++++++++++++++++++++ docs/reference/gobject/gobject.toml.in | 1 + docs/reference/gobject/meson.build | 1 + gobject/genums.c | 37 -------------------------- 4 files changed, 38 insertions(+), 37 deletions(-) create mode 100644 docs/reference/gobject/enum-types.md diff --git a/docs/reference/gobject/enum-types.md b/docs/reference/gobject/enum-types.md new file mode 100644 index 000000000..d869f8a93 --- /dev/null +++ b/docs/reference/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/docs/reference/gobject/gobject.toml.in b/docs/reference/gobject/gobject.toml.in index c963b2fb1..8f24462bf 100644 --- a/docs/reference/gobject/gobject.toml.in +++ b/docs/reference/gobject/gobject.toml.in @@ -43,6 +43,7 @@ urlmap_file = "urlmap.js" # The same order will be used when generating the index content_files = [ "boxed.md", + "enum-types.md", ] content_images = [ ] diff --git a/docs/reference/gobject/meson.build b/docs/reference/gobject/meson.build index 0eba6d1a7..136f5a5b9 100644 --- a/docs/reference/gobject/meson.build +++ b/docs/reference/gobject/meson.build @@ -72,6 +72,7 @@ endif # gi-docgen version expand_content_files = [ 'boxed.md', + 'enum-types.md', ] gobject_gir = meson.current_source_dir() / 'GObject-2.0.gir' diff --git a/gobject/genums.c b/gobject/genums.c index 1fe7f7211..96b367daa 100644 --- a/gobject/genums.c +++ b/gobject/genums.c @@ -31,43 +31,6 @@ #include "gvaluecollector.h" -/** - * SECTION:enumerations_flags - * @short_description: Enumeration and flags types - * @title: Enumeration and Flag Types - * @see_also:#GParamSpecEnum, #GParamSpecFlags, g_param_spec_enum(), - * g_param_spec_flags() - * - * The GLib type system provides fundamental types for enumeration and - * flags types. (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 g_enum_get_value_by_name(), - * g_enum_get_value_by_nick(), g_flags_get_value_by_name() and - * g_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 g_param_spec_enum() or g_param_spec_flags(). - * - * GObject ships with a utility called [glib-mkenums][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: - * |[ - * GEnumClass *enum_class; - * GEnumValue *enum_value; - * - * enum_class = g_type_class_ref (MAMAN_TYPE_MY_ENUM); - * enum_value = g_enum_get_value (enum_class, MAMAN_MY_ENUM_FOO); - * - * g_print ("Name: %s\n", enum_value->value_name); - * - * g_type_class_unref (enum_class); - * ]| - */ - - /* --- prototypes --- */ static void g_enum_class_init (GEnumClass *class, gpointer class_data);