docs: Move enum type documentation to Markdown

Helps: #3037
This commit is contained in:
Matthias Clasen 2023-10-09 23:16:51 +01:00 committed by Philip Withnall
parent 24e93078d3
commit 58019515d6
4 changed files with 38 additions and 37 deletions

View File

@ -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`].

View File

@ -43,6 +43,7 @@ urlmap_file = "urlmap.js"
# The same order will be used when generating the index # The same order will be used when generating the index
content_files = [ content_files = [
"boxed.md", "boxed.md",
"enum-types.md",
] ]
content_images = [ content_images = [
] ]

View File

@ -72,6 +72,7 @@ endif
# gi-docgen version # gi-docgen version
expand_content_files = [ expand_content_files = [
'boxed.md', 'boxed.md',
'enum-types.md',
] ]
gobject_gir = meson.current_source_dir() / 'GObject-2.0.gir' gobject_gir = meson.current_source_dir() / 'GObject-2.0.gir'

View File

@ -31,43 +31,6 @@
#include "gvaluecollector.h" #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:
* |[<!-- language="C" -->
* 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 --- */ /* --- prototypes --- */
static void g_enum_class_init (GEnumClass *class, static void g_enum_class_init (GEnumClass *class,
gpointer class_data); gpointer class_data);