From d4a875d8cd13618490f4a6ad845cbbaae9f04ed6 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Wed, 20 Jan 2021 15:42:55 +0000 Subject: [PATCH] gtype: Improve formatting of GType documentation Signed-off-by: Philip Withnall --- gobject/gtype.h | 152 ++++++++++++++++++++++++------------------------ 1 file changed, 76 insertions(+), 76 deletions(-) diff --git a/gobject/gtype.h b/gobject/gtype.h index 666fadb0c..621c6514d 100644 --- a/gobject/gtype.h +++ b/gobject/gtype.h @@ -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: * * |[ @@ -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 */