Merge branch 'gtype-docs' into 'master'

gtype: Improve formatting of GType documentation

See merge request GNOME/glib!1890
This commit is contained in:
Emmanuele Bassi 2021-01-20 15:54:20 +00:00
commit caf2343fae

View File

@ -1334,12 +1334,12 @@ guint g_type_get_type_registration_serial (void);
/* --- GType boilerplate --- */
/**
* G_DECLARE_FINAL_TYPE:
* @ModuleObjName: The name of the new type, in camel case (like GtkWidget)
* @ModuleObjName: The name of the new type, in camel case (like `GtkWidget`)
* @module_obj_name: The name of the new type in lowercase, with words
* separated by '_' (like 'gtk_widget')
* @MODULE: The name of the module, in all caps (like 'GTK')
* @OBJ_NAME: The bare name of the type, in all caps (like 'WIDGET')
* @ParentName: the name of the parent type, in camel case (like GtkWidget)
* separated by `_` (like `gtk_widget`)
* @MODULE: The name of the module, in all caps (like `GTK`)
* @OBJ_NAME: The bare name of the type, in all caps (like `WIDGET`)
* @ParentName: the name of the parent type, in camel case (like `GtkWidget`)
*
* A convenience macro for emitting the usual declarations in the header file for a type which is not (at the
* present time) intended to be subclassed.
@ -1364,15 +1364,15 @@ guint g_type_get_type_registration_serial (void);
*
* This results in the following things happening:
*
* - the usual my_app_window_get_type() function is declared with a return type of #GType
* - the usual `my_app_window_get_type()` function is declared with a return type of #GType
*
* - the MyAppWindow types is defined as a typedef of struct _MyAppWindow. The struct itself is not
* - the `MyAppWindow` type is defined as a `typedef` of `struct _MyAppWindow`. The struct itself is not
* defined and should be defined from the .c file before G_DEFINE_TYPE() is used.
*
* - the MY_APP_WINDOW() cast is emitted as static inline function along with the MY_APP_IS_WINDOW() type
* - the `MY_APP_WINDOW()` cast is emitted as `static inline` function along with the `MY_APP_IS_WINDOW()` type
* checking function
*
* - the MyAppWindowClass type is defined as a struct containing GtkWindowClass. This is done for the
* - the `MyAppWindowClass` type is defined as a struct containing `GtkWindowClass`. This is done for the
* convenience of the person defining the type and should not be considered to be part of the ABI. In
* particular, without a firm declaration of the instance structure, it is not possible to subclass the type
* and therefore the fact that the size of the class structure is exposed is not a concern and it can be
@ -1382,10 +1382,10 @@ guint g_type_get_type_registration_serial (void);
*
* You can only use this function if your parent type also supports g_autoptr().
*
* Because the type macro (MY_APP_TYPE_WINDOW in the above example) is not a callable, you must continue to
* Because the type macro (`MY_APP_TYPE_WINDOW` in the above example) is not a callable, you must continue to
* manually define this as a macro for yourself.
*
* The declaration of the _get_type() function is the first thing emitted by the macro. This allows this macro
* The declaration of the `_get_type()` function is the first thing emitted by the macro. This allows this macro
* to be used in the usual way with export control and API versioning macros.
*
* If you want to declare your own class structure, use G_DECLARE_DERIVABLE_TYPE().
@ -1415,12 +1415,12 @@ guint g_type_get_type_registration_serial (void);
/**
* G_DECLARE_DERIVABLE_TYPE:
* @ModuleObjName: The name of the new type, in camel case (like GtkWidget)
* @ModuleObjName: The name of the new type, in camel case (like `GtkWidget`)
* @module_obj_name: The name of the new type in lowercase, with words
* separated by '_' (like 'gtk_widget')
* @MODULE: The name of the module, in all caps (like 'GTK')
* @OBJ_NAME: The bare name of the type, in all caps (like 'WIDGET')
* @ParentName: the name of the parent type, in camel case (like GtkWidget)
* separated by `_` (like `gtk_widget`)
* @MODULE: The name of the module, in all caps (like `GTK`)
* @OBJ_NAME: The bare name of the type, in all caps (like `WIDGET`)
* @ParentName: the name of the parent type, in camel case (like `GtkWidget`)
*
* A convenience macro for emitting the usual declarations in the
* header file for a type which is intended to be subclassed.
@ -1454,26 +1454,26 @@ guint g_type_get_type_registration_serial (void);
*
* This results in the following things happening:
*
* - the usual gtk_frobber_get_type() function is declared with a return type of #GType
* - the usual `gtk_frobber_get_type()` function is declared with a return type of #GType
*
* - the GtkFrobber struct is created with GtkWidget as the first and only item. You are expected to use
* - the `GtkFrobber` struct is created with `GtkWidget` as the first and only item. You are expected to use
* a private structure from your .c file to store your instance variables.
*
* - the GtkFrobberClass type is defined as a typedef to struct _GtkFrobberClass, which is left undefined.
* - the `GtkFrobberClass` type is defined as a typedef to `struct _GtkFrobberClass`, which is left undefined.
* You should do this from the header file directly after you use the macro.
*
* - the GTK_FROBBER() and GTK_FROBBER_CLASS() casts are emitted as static inline functions along with
* the GTK_IS_FROBBER() and GTK_IS_FROBBER_CLASS() type checking functions and GTK_FROBBER_GET_CLASS()
* - the `GTK_FROBBER()` and `GTK_FROBBER_CLASS()` casts are emitted as `static inline` functions along with
* the `GTK_IS_FROBBER()` and `GTK_IS_FROBBER_CLASS()` type checking functions and `GTK_FROBBER_GET_CLASS()`
* function.
*
* - g_autoptr() support being added for your type, based on the type of your parent class
*
* You can only use this function if your parent type also supports g_autoptr().
*
* Because the type macro (GTK_TYPE_FROBBER in the above example) is not a callable, you must continue to
* Because the type macro (`GTK_TYPE_FROBBER` in the above example) is not a callable, you must continue to
* manually define this as a macro for yourself.
*
* The declaration of the _get_type() function is the first thing emitted by the macro. This allows this macro
* The declaration of the `_get_type()` function is the first thing emitted by the macro. This allows this macro
* to be used in the usual way with export control and API versioning macros.
*
* If you are writing a library, it is important to note that it is possible to convert a type from using
@ -1513,14 +1513,14 @@ guint g_type_get_type_registration_serial (void);
/**
* G_DECLARE_INTERFACE:
* @ModuleObjName: The name of the new type, in camel case (like GtkWidget)
* @ModuleObjName: The name of the new type, in camel case (like `GtkWidget`)
* @module_obj_name: The name of the new type in lowercase, with words
* separated by '_' (like 'gtk_widget')
* @MODULE: The name of the module, in all caps (like 'GTK')
* @OBJ_NAME: The bare name of the type, in all caps (like 'WIDGET')
* @PrerequisiteName: the name of the prerequisite type, in camel case (like GtkWidget)
* separated by `_` (like `gtk_widget`)
* @MODULE: The name of the module, in all caps (like `GTK`)
* @OBJ_NAME: The bare name of the type, in all caps (like `WIDGET`)
* @PrerequisiteName: the name of the prerequisite type, in camel case (like `GtkWidget`)
*
* A convenience macro for emitting the usual declarations in the header file for a GInterface type.
* A convenience macro for emitting the usual declarations in the header file for a #GInterface type.
*
* You might use it in a header as follows:
*
@ -1548,23 +1548,23 @@ guint g_type_get_type_registration_serial (void);
*
* This results in the following things happening:
*
* - the usual my_model_get_type() function is declared with a return type of #GType
* - the usual `my_model_get_type()` function is declared with a return type of #GType
*
* - the MyModelInterface type is defined as a typedef to struct _MyModelInterface,
* - the `MyModelInterface` type is defined as a typedef to `struct _MyModelInterface`,
* which is left undefined. You should do this from the header file directly after
* you use the macro.
*
* - the MY_MODEL() cast is emitted as static inline functions along with
* the MY_IS_MODEL() type checking function and MY_MODEL_GET_IFACE() function.
* - the `MY_MODEL()` cast is emitted as `static inline` functions along with
* the `MY_IS_MODEL()` type checking function and `MY_MODEL_GET_IFACE()` function.
*
* - g_autoptr() support being added for your type, based on your prerequisite type.
*
* You can only use this function if your prerequisite type also supports g_autoptr().
*
* Because the type macro (MY_TYPE_MODEL in the above example) is not a callable, you must continue to
* Because the type macro (`MY_TYPE_MODEL` in the above example) is not a callable, you must continue to
* manually define this as a macro for yourself.
*
* The declaration of the _get_type() function is the first thing emitted by the macro. This allows this macro
* The declaration of the `_get_type()` function is the first thing emitted by the macro. This allows this macro
* to be used in the usual way with export control and API versioning macros.
*
* Since: 2.44
@ -1589,13 +1589,13 @@ guint g_type_get_type_registration_serial (void);
* G_DEFINE_TYPE:
* @TN: The name of the new type, in Camel case.
* @t_n: The name of the new type, in lowercase, with words
* separated by '_'.
* separated by `_`.
* @T_P: The #GType of the parent type.
*
* A convenience macro for type implementations, which declares a class
* initialization function, an instance initialization function (see #GTypeInfo
* for information about these) and a static variable named `t_n_parent_class`
* pointing to the parent class. Furthermore, it defines a *_get_type() function.
* pointing to the parent class. Furthermore, it defines a `*_get_type()` function.
* See G_DEFINE_TYPE_EXTENDED() for an example.
*
* Since: 2.4
@ -1604,13 +1604,13 @@ guint g_type_get_type_registration_serial (void);
/**
* G_DEFINE_TYPE_WITH_CODE:
* @TN: The name of the new type, in Camel case.
* @t_n: The name of the new type in lowercase, with words separated by '_'.
* @t_n: The name of the new type in lowercase, with words separated by `_`.
* @T_P: The #GType of the parent type.
* @_C_: Custom code that gets inserted in the *_get_type() function.
* @_C_: Custom code that gets inserted in the `*_get_type()` function.
*
* A convenience macro for type implementations.
* Similar to G_DEFINE_TYPE(), but allows you to insert custom code into the
* *_get_type() function, e.g. interface implementations via G_IMPLEMENT_INTERFACE().
* `*_get_type()` function, e.g. interface implementations via G_IMPLEMENT_INTERFACE().
* See G_DEFINE_TYPE_EXTENDED() for an example.
*
* Since: 2.4
@ -1620,18 +1620,18 @@ guint g_type_get_type_registration_serial (void);
* G_DEFINE_TYPE_WITH_PRIVATE:
* @TN: The name of the new type, in Camel case.
* @t_n: The name of the new type, in lowercase, with words
* separated by '_'.
* separated by `_`.
* @T_P: The #GType of the parent type.
*
* A convenience macro for type implementations, which declares a class
* initialization function, an instance initialization function (see #GTypeInfo
* for information about these), a static variable named `t_n_parent_class`
* pointing to the parent class, and adds private instance data to the type.
* Furthermore, it defines a *_get_type() function. See G_DEFINE_TYPE_EXTENDED()
* Furthermore, it defines a `*_get_type()` function. See G_DEFINE_TYPE_EXTENDED()
* for an example.
*
* Note that private structs added with this macros must have a struct
* name of the form @TN Private.
* name of the form `TN ## Private`.
*
* The private instance data can be retrieved using the automatically generated
* getter function `t_n_get_instance_private()`.
@ -1645,7 +1645,7 @@ guint g_type_get_type_registration_serial (void);
* G_DEFINE_ABSTRACT_TYPE:
* @TN: The name of the new type, in Camel case.
* @t_n: The name of the new type, in lowercase, with words
* separated by '_'.
* separated by `_`.
* @T_P: The #GType of the parent type.
*
* A convenience macro for type implementations.
@ -1659,13 +1659,13 @@ guint g_type_get_type_registration_serial (void);
* G_DEFINE_ABSTRACT_TYPE_WITH_CODE:
* @TN: The name of the new type, in Camel case.
* @t_n: The name of the new type, in lowercase, with words
* separated by '_'.
* separated by `_`.
* @T_P: The #GType of the parent type.
* @_C_: Custom code that gets inserted in the @type_name_get_type() function.
* @_C_: Custom code that gets inserted in the `type_name_get_type()` function.
*
* A convenience macro for type implementations.
* Similar to G_DEFINE_TYPE_WITH_CODE(), but defines an abstract type and
* allows you to insert custom code into the *_get_type() function, e.g.
* allows you to insert custom code into the `*_get_type()` function, e.g.
* interface implementations via G_IMPLEMENT_INTERFACE().
* See G_DEFINE_TYPE_EXTENDED() for an example.
*
@ -1676,7 +1676,7 @@ guint g_type_get_type_registration_serial (void);
* G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE:
* @TN: The name of the new type, in Camel case.
* @t_n: The name of the new type, in lowercase, with words
* separated by '_'.
* separated by `_`.
* @T_P: The #GType of the parent type.
*
* Similar to G_DEFINE_TYPE_WITH_PRIVATE(), but defines an abstract type.
@ -1689,10 +1689,10 @@ guint g_type_get_type_registration_serial (void);
* G_DEFINE_TYPE_EXTENDED:
* @TN: The name of the new type, in Camel case.
* @t_n: The name of the new type, in lowercase, with words
* separated by '_'.
* separated by `_`.
* @T_P: The #GType of the parent type.
* @_f_: #GTypeFlags to pass to g_type_register_static()
* @_C_: Custom code that gets inserted in the *_get_type() function.
* @_C_: Custom code that gets inserted in the `*_get_type()` function.
*
* The most general convenience macro for type implementations, on which
* G_DEFINE_TYPE(), etc are based.
@ -1764,12 +1764,12 @@ guint g_type_get_type_registration_serial (void);
/**
* G_DEFINE_INTERFACE:
* @TN: The name of the new type, in Camel case.
* @t_n: The name of the new type, in lowercase, with words separated by '_'.
* @T_P: The #GType of the prerequisite type for the interface, or 0
* (%G_TYPE_INVALID) for no prerequisite type.
* @t_n: The name of the new type, in lowercase, with words separated by `_`.
* @T_P: The #GType of the prerequisite type for the interface, or %G_TYPE_INVALID
* for no prerequisite type.
*
* A convenience macro for #GTypeInterface definitions, which declares
* a default vtable initialization function and defines a *_get_type()
* a default vtable initialization function and defines a `*_get_type()`
* function.
*
* The macro expects the interface initialization function to have the
@ -1789,14 +1789,14 @@ guint g_type_get_type_registration_serial (void);
/**
* G_DEFINE_INTERFACE_WITH_CODE:
* @TN: The name of the new type, in Camel case.
* @t_n: The name of the new type, in lowercase, with words separated by '_'.
* @T_P: The #GType of the prerequisite type for the interface, or 0
* (%G_TYPE_INVALID) for no prerequisite type.
* @_C_: Custom code that gets inserted in the *_get_type() function.
* @t_n: The name of the new type, in lowercase, with words separated by `_`.
* @T_P: The #GType of the prerequisite type for the interface, or %G_TYPE_INVALID
* for no prerequisite type.
* @_C_: Custom code that gets inserted in the `*_get_type()` function.
*
* A convenience macro for #GTypeInterface definitions. Similar to
* G_DEFINE_INTERFACE(), but allows you to insert custom code into the
* *_get_type() function, e.g. additional interface implementations
* `*_get_type()` function, e.g. additional interface implementations
* via G_IMPLEMENT_INTERFACE(), or additional prerequisite types. See
* G_DEFINE_TYPE_EXTENDED() for a similar example using
* G_DEFINE_TYPE_WITH_CODE().
@ -1814,7 +1814,7 @@ guint g_type_get_type_registration_serial (void);
* of G_DEFINE_TYPE_WITH_CODE() or G_DEFINE_ABSTRACT_TYPE_WITH_CODE().
* See G_DEFINE_TYPE_EXTENDED() for an example.
*
* Note that this macro can only be used together with the G_DEFINE_TYPE_*
* Note that this macro can only be used together with the `G_DEFINE_TYPE_*`
* macros, since it depends on variable names from those macros.
*
* Since: 2.4
@ -1849,10 +1849,10 @@ guint g_type_get_type_registration_serial (void);
* G_ADD_PRIVATE (MyObject))
* ]|
*
* Will add MyObjectPrivate as the private data to any instance of the MyObject
* type.
* Will add `MyObjectPrivate` as the private data to any instance of the
* `MyObject` type.
*
* G_DEFINE_TYPE_* macros will automatically create a private function
* `G_DEFINE_TYPE_*` macros will automatically create a private function
* based on the arguments to this macro, which can be used to safely
* retrieve the private data from an instance of the type; for instance:
*
@ -1880,7 +1880,7 @@ guint g_type_get_type_registration_serial (void);
* }
* ]|
*
* Note that this macro can only be used together with the G_DEFINE_TYPE_*
* Note that this macro can only be used together with the `G_DEFINE_TYPE_*`
* macros, since it depends on variable names from those macros.
*
* Also note that private structs added with these macros must have a struct
@ -1905,7 +1905,7 @@ guint g_type_get_type_registration_serial (void);
* Evaluates to the offset of the @field inside the instance private data
* structure for @TypeName.
*
* Note that this macro can only be used together with the G_DEFINE_TYPE_*
* Note that this macro can only be used together with the `G_DEFINE_TYPE_*`
* and G_ADD_PRIVATE() macros, since it depends on variable names from
* those macros.
*
@ -1923,7 +1923,7 @@ guint g_type_get_type_registration_serial (void);
* Evaluates to a pointer to the @field_name inside the @inst private data
* structure for @TypeName.
*
* Note that this macro can only be used together with the G_DEFINE_TYPE_*
* Note that this macro can only be used together with the `G_DEFINE_TYPE_*`
* and G_ADD_PRIVATE() macros, since it depends on variable names from
* those macros.
*
@ -1942,7 +1942,7 @@ guint g_type_get_type_registration_serial (void);
* Evaluates to the @field_name inside the @inst private data
* structure for @TypeName.
*
* Note that this macro can only be used together with the G_DEFINE_TYPE_*
* Note that this macro can only be used together with the `G_DEFINE_TYPE_*`
* and G_ADD_PRIVATE() macros, since it depends on variable names from
* those macros.
*
@ -2067,7 +2067,7 @@ type_name##_get_type (void) \
* G_DEFINE_BOXED_TYPE:
* @TypeName: The name of the new type, in Camel case
* @type_name: The name of the new type, in lowercase, with words
* separated by '_'
* separated by `_`
* @copy_func: the #GBoxedCopyFunc for the new type
* @free_func: the #GBoxedFreeFunc for the new type
*
@ -2081,14 +2081,14 @@ type_name##_get_type (void) \
* G_DEFINE_BOXED_TYPE_WITH_CODE:
* @TypeName: The name of the new type, in Camel case
* @type_name: The name of the new type, in lowercase, with words
* separated by '_'
* separated by `_`
* @copy_func: the #GBoxedCopyFunc for the new type
* @free_func: the #GBoxedFreeFunc for the new type
* @_C_: Custom code that gets inserted in the *_get_type() function
* @_C_: Custom code that gets inserted in the `*_get_type()` function
*
* A convenience macro for boxed type implementations.
* Similar to G_DEFINE_BOXED_TYPE(), but allows to insert custom code into the
* type_name_get_type() function, e.g. to register value transformations with
* `type_name_get_type()` function, e.g. to register value transformations with
* g_value_register_transform_func(), for instance:
*
* |[<!-- language="C" -->
@ -2176,10 +2176,10 @@ type_name##_get_type_once (void) \
* G_DEFINE_POINTER_TYPE:
* @TypeName: The name of the new type, in Camel case
* @type_name: The name of the new type, in lowercase, with words
* separated by '_'
* separated by `_`
*
* A convenience macro for pointer type implementations, which defines a
* type_name_get_type() function registering the pointer type.
* `type_name_get_type()` function registering the pointer type.
*
* Since: 2.26
*/
@ -2188,12 +2188,12 @@ type_name##_get_type_once (void) \
* G_DEFINE_POINTER_TYPE_WITH_CODE:
* @TypeName: The name of the new type, in Camel case
* @type_name: The name of the new type, in lowercase, with words
* separated by '_'
* @_C_: Custom code that gets inserted in the *_get_type() function
* separated by `_`
* @_C_: Custom code that gets inserted in the `*_get_type()` function
*
* A convenience macro for pointer type implementations.
* Similar to G_DEFINE_POINTER_TYPE(), but allows to insert
* custom code into the type_name_get_type() function.
* custom code into the `type_name_get_type()` function.
*
* Since: 2.26
*/