From e03a2c8633c45f8f342f916c7784a0e8efc933f3 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Fri, 8 Mar 2019 19:10:32 +0000 Subject: [PATCH 1/2] glib: Move various documentation comments from docs.c to macros.h MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Move them next to their definitions, so they’re more likely to be kept up to date. This doesn’t modify any of the documentation comments at all. Signed-off-by: Philip Withnall --- glib/docs.c | 335 ------------------------------------------------- glib/gmacros.h | 329 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 329 insertions(+), 335 deletions(-) diff --git a/glib/docs.c b/glib/docs.c index 9a722b8cd..cfcbcfea7 100644 --- a/glib/docs.c +++ b/glib/docs.c @@ -2038,157 +2038,6 @@ * Since: 2.42 */ -/** - * G_GNUC_CONST: - * - * Expands to the GNU C const function attribute if the compiler is gcc. - * Declaring a function as const enables better optimization of calls to - * the function. A const function doesn't examine any values except its - * parameters, and has no effects except its return value. - * - * Place the attribute after the declaration, just before the semicolon. - * - * See the GNU C documentation for more details. - * - * A function that has pointer arguments and examines the data pointed to - * must not be declared const. Likewise, a function that calls a non-const - * function usually must not be const. It doesn't make sense for a const - * function to return void. - */ - -/** - * G_GNUC_PURE: - * - * Expands to the GNU C pure function attribute if the compiler is gcc. - * Declaring a function as pure enables better optimization of calls to - * the function. A pure function has no effects except its return value - * and the return value depends only on the parameters and/or global - * variables. - * - * Place the attribute after the declaration, just before the semicolon. - * - * See the GNU C documentation for more details. - */ - -/** - * G_GNUC_NO_INLINE: - * - * Expands to the GNU C `noinline` function attribute if the compiler is gcc. - * If the compiler is not gcc, this macro expands to nothing. - * - * Declaring a function as `noinline` prevents the function from being - * considered for inlining. - * - * The attribute may be placed before the declaration, right before the - * `static` keyword. - * - * See the - * [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-noinline-function-attribute) - * for more details. - * - * Since: 2.58 - */ - -/** - * G_GNUC_MALLOC: - * - * Expands to the - * [GNU C `malloc` function attribute](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-functions-that-behave-like-malloc) - * if the compiler is gcc. - * Declaring a function as `malloc` enables better optimization of the function, - * but must only be done if the allocation behaviour of the function is fully - * understood, otherwise miscompilation can result. - * - * A function can have the `malloc` attribute if it returns a pointer which is - * guaranteed to not alias with any other pointer valid when the function - * returns, and moreover no pointers to valid objects occur in any storage - * addressed by the returned pointer. - * - * In practice, this means that `G_GNUC_MALLOC` can be used with any function - * which returns unallocated or zeroed-out memory, but not with functions which - * return initialised structures containing other pointers, or with functions - * that reallocate memory. This definition changed in GLib 2.58 to match the - * stricter definition introduced around GCC 5. - * - * Place the attribute after the declaration, just before the semicolon. - * - * See the - * [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-functions-that-behave-like-malloc) - * for more details. - * - * Since: 2.6 - */ - -/** - * G_GNUC_ALLOC_SIZE: - * @x: the index of the argument specifying the allocation size - * - * Expands to the GNU C alloc_size function attribute if the compiler - * is a new enough gcc. This attribute tells the compiler that the - * function returns a pointer to memory of a size that is specified - * by the @xth function parameter. - * - * Place the attribute after the function declaration, just before the - * semicolon. - * - * See the GNU C documentation for more details. - * - * Since: 2.18 - */ - -/** - * G_GNUC_ALLOC_SIZE2: - * @x: the index of the argument specifying one factor of the allocation size - * @y: the index of the argument specifying the second factor of the allocation size - * - * Expands to the GNU C alloc_size function attribute if the compiler is a - * new enough gcc. This attribute tells the compiler that the function returns - * a pointer to memory of a size that is specified by the product of two - * function parameters. - * - * Place the attribute after the function declaration, just before the - * semicolon. - * - * See the GNU C documentation for more details. - * - * Since: 2.18 - */ - -/** - * G_GNUC_DEPRECATED: - * - * Expands to the GNU C deprecated attribute if the compiler is gcc. - * It can be used to mark typedefs, variables and functions as deprecated. - * When called with the `-Wdeprecated-declarations` option, - * gcc will generate warnings when deprecated interfaces are used. - * - * Place the attribute after the declaration, just before the semicolon. - * - * See the GNU C documentation for more details. - * - * Since: 2.2 - */ - -/** - * G_GNUC_DEPRECATED_FOR: - * @f: the intended replacement for the deprecated symbol, - * such as the name of a function - * - * Like %G_GNUC_DEPRECATED, but names the intended replacement for the - * deprecated symbol if the version of gcc in use is new enough to support - * custom deprecation messages. - * - * Place the attribute after the declaration, just before the semicolon. - * - * See the GNU C documentation for more details. - * - * Note that if @f is a macro, it will be expanded in the warning message. - * You can enclose it in quotes to prevent this. (The quotes will show up - * in the warning, but it's better than showing the macro expansion.) - * - * Since: 2.26 - */ - /** * G_GNUC_BEGIN_IGNORE_DEPRECATIONS: * @@ -2264,165 +2113,6 @@ * of deprecated GLib APIs. */ -/** - * G_GNUC_NORETURN: - * - * Expands to the GNU C noreturn function attribute if the compiler is gcc. - * It is used for declaring functions which never return. It enables - * optimization of the function, and avoids possible compiler warnings. - * - * Place the attribute after the declaration, just before the semicolon. - * - * See the GNU C documentation for more details. - */ - -/** - * G_GNUC_FALLTHROUGH: - * - * Expands to the GNU C fallthrough statement attribute if the compiler is gcc. - * This allows declaring case statement to explicitly fall through in switch - * statements. To enable this feature, use -Wimplicit-fallthrough during - * compilation. - * - * Put the attribute right before the case statement you want to fall through - * to. - * - * See the GNU C documentation for more details. - * - * Since: 2.60 - */ - -/** - * G_GNUC_UNUSED: - * - * Expands to the GNU C unused function attribute if the compiler is gcc. - * It is used for declaring functions and arguments which may never be used. - * It avoids possible compiler warnings. - * - * For functions, place the attribute after the declaration, just before the - * semicolon. For arguments, place the attribute at the beginning of the - * argument declaration. - * - * |[ - * void my_unused_function (G_GNUC_UNUSED gint unused_argument, - * gint other_argument) G_GNUC_UNUSED; - * ]| - * - * See the GNU C documentation for more details. - */ - -/** - * G_GNUC_PRINTF: - * @format_idx: the index of the argument corresponding to the - * format string (the arguments are numbered from 1) - * @arg_idx: the index of the first of the format arguments, or 0 if - * there are no format arguments - * - * Expands to the GNU C format function attribute if the compiler is gcc. - * This is used for declaring functions which take a variable number of - * arguments, with the same syntax as printf(). It allows the compiler - * to type-check the arguments passed to the function. - * - * Place the attribute after the function declaration, just before the - * semicolon. - * - * See the - * [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-Wformat-3288) - * for more details. - * - * |[ - * gint g_snprintf (gchar *string, - * gulong n, - * gchar const *format, - * ...) G_GNUC_PRINTF (3, 4); - * ]| - */ - -/** - * G_GNUC_SCANF: - * @format_idx: the index of the argument corresponding to - * the format string (the arguments are numbered from 1) - * @arg_idx: the index of the first of the format arguments, or 0 if - * there are no format arguments - * - * Expands to the GNU C format function attribute if the compiler is gcc. - * This is used for declaring functions which take a variable number of - * arguments, with the same syntax as scanf(). It allows the compiler - * to type-check the arguments passed to the function. - * - * See the - * [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-Wformat-3288) - * for details. - */ - -/** - * G_GNUC_STRFTIME: - * @format_idx: the index of the argument corresponding to - * the format string (the arguments are numbered from 1) - * - * Expands to the GNU C strftime format function attribute if the compiler - * is gcc. This is used for declaring functions which take a format argument - * which is passed to strftime() or an API implementing its formats. It allows - * the compiler check the format passed to the function. - * - * See the - * [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-Wformat-3288) - * for details. - * - * Since: 2.60 - */ - -/** - * G_GNUC_FORMAT: - * @arg_idx: the index of the argument - * - * Expands to the GNU C format_arg function attribute if the compiler - * is gcc. This function attribute specifies that a function takes a - * format string for a printf(), scanf(), strftime() or strfmon() style - * function and modifies it, so that the result can be passed to a printf(), - * scanf(), strftime() or strfmon() style function (with the remaining - * arguments to the format function the same as they would have been - * for the unmodified string). - * - * Place the attribute after the function declaration, just before the - * semicolon. - * - * See the GNU C documentation for more details. - * - * |[ - * gchar *g_dgettext (gchar *domain_name, gchar *msgid) G_GNUC_FORMAT (2); - * ]| - */ - -/** - * G_GNUC_NULL_TERMINATED: - * - * Expands to the GNU C sentinel function attribute if the compiler is gcc. - * This function attribute only applies to variadic functions and instructs - * the compiler to check that the argument list is terminated with an - * explicit %NULL. - * - * Place the attribute after the declaration, just before the semicolon. - * - * See the GNU C documentation for more details. - * - * Since: 2.8 - */ - -/** - * G_GNUC_WARN_UNUSED_RESULT: - * - * Expands to the GNU C warn_unused_result function attribute if the compiler - * is gcc. This function attribute makes the compiler emit a warning if the - * result of a function call is ignored. - * - * Place the attribute after the declaration, just before the semicolon. - * - * See the GNU C documentation for more details. - * - * Since: 2.10 - */ - /** * G_GNUC_FUNCTION: * @@ -2441,19 +2131,6 @@ * Deprecated: 2.16: Use G_STRFUNC() instead */ -/** - * G_GNUC_NO_INSTRUMENT: - * - * Expands to the GNU C no_instrument_function function attribute if the - * compiler is gcc. Functions with this attribute will not be instrumented - * for profiling, when the compiler is called with the - * `-finstrument-functions` option. - * - * Place the attribute after the declaration, just before the semicolon. - * - * See the GNU C documentation for more details. - */ - /** * G_GNUC_INTERNAL: * @@ -2482,18 +2159,6 @@ * Since: 2.6 */ -/** - * G_GNUC_MAY_ALIAS: - * - * Expands to the GNU C may_alias type attribute if the compiler is gcc. - * Types with this attribute will not be subjected to type-based alias - * analysis, but are assumed to alias with any other type, just like char. - * - * See the GNU C documentation for details. - * - * Since: 2.14 - */ - /** * G_LIKELY: * @expr: the expression diff --git a/glib/gmacros.h b/glib/gmacros.h index b0384ccf0..1df192801 100644 --- a/glib/gmacros.h +++ b/glib/gmacros.h @@ -94,6 +94,70 @@ /* Provide macros to feature the GCC function attribute. */ + +/** + * G_GNUC_PURE: + * + * Expands to the GNU C pure function attribute if the compiler is gcc. + * Declaring a function as pure enables better optimization of calls to + * the function. A pure function has no effects except its return value + * and the return value depends only on the parameters and/or global + * variables. + * + * Place the attribute after the declaration, just before the semicolon. + * + * See the GNU C documentation for more details. + */ + +/** + * G_GNUC_MALLOC: + * + * Expands to the + * [GNU C `malloc` function attribute](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-functions-that-behave-like-malloc) + * if the compiler is gcc. + * Declaring a function as `malloc` enables better optimization of the function, + * but must only be done if the allocation behaviour of the function is fully + * understood, otherwise miscompilation can result. + * + * A function can have the `malloc` attribute if it returns a pointer which is + * guaranteed to not alias with any other pointer valid when the function + * returns, and moreover no pointers to valid objects occur in any storage + * addressed by the returned pointer. + * + * In practice, this means that `G_GNUC_MALLOC` can be used with any function + * which returns unallocated or zeroed-out memory, but not with functions which + * return initialised structures containing other pointers, or with functions + * that reallocate memory. This definition changed in GLib 2.58 to match the + * stricter definition introduced around GCC 5. + * + * Place the attribute after the declaration, just before the semicolon. + * + * See the + * [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-functions-that-behave-like-malloc) + * for more details. + * + * Since: 2.6 + */ + +/** + * G_GNUC_NO_INLINE: + * + * Expands to the GNU C `noinline` function attribute if the compiler is gcc. + * If the compiler is not gcc, this macro expands to nothing. + * + * Declaring a function as `noinline` prevents the function from being + * considered for inlining. + * + * The attribute may be placed before the declaration, right before the + * `static` keyword. + * + * See the + * [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-noinline-function-attribute) + * for more details. + * + * Since: 2.58 + */ + #if __GNUC__ > 2 || (__GNUC__ == 2 && __GNUC_MINOR__ >= 96) #define G_GNUC_PURE __attribute__((__pure__)) #define G_GNUC_MALLOC __attribute__((__malloc__)) @@ -104,6 +168,20 @@ #define G_GNUC_NO_INLINE #endif +/** + * G_GNUC_NULL_TERMINATED: + * + * Expands to the GNU C sentinel function attribute if the compiler is gcc. + * This function attribute only applies to variadic functions and instructs + * the compiler to check that the argument list is terminated with an + * explicit %NULL. + * + * Place the attribute after the declaration, just before the semicolon. + * + * See the GNU C documentation for more details. + * + * Since: 2.8 + */ #if __GNUC__ >= 4 #define G_GNUC_NULL_TERMINATED __attribute__((__sentinel__)) #else @@ -150,6 +228,40 @@ #define g_macro__has_builtin(x) 0 #endif +/** + * G_GNUC_ALLOC_SIZE: + * @x: the index of the argument specifying the allocation size + * + * Expands to the GNU C alloc_size function attribute if the compiler + * is a new enough gcc. This attribute tells the compiler that the + * function returns a pointer to memory of a size that is specified + * by the @xth function parameter. + * + * Place the attribute after the function declaration, just before the + * semicolon. + * + * See the GNU C documentation for more details. + * + * Since: 2.18 + */ + +/** + * G_GNUC_ALLOC_SIZE2: + * @x: the index of the argument specifying one factor of the allocation size + * @y: the index of the argument specifying the second factor of the allocation size + * + * Expands to the GNU C alloc_size function attribute if the compiler is a + * new enough gcc. This attribute tells the compiler that the function returns + * a pointer to memory of a size that is specified by the product of two + * function parameters. + * + * Place the attribute after the function declaration, just before the + * semicolon. + * + * See the GNU C documentation for more details. + * + * Since: 2.18 + */ #if (!defined(__clang__) && ((__GNUC__ > 4) || (__GNUC__ == 4 && __GNUC_MINOR__ >= 3))) || \ (defined(__clang__) && g_macro__has_attribute(__alloc_size__)) #define G_GNUC_ALLOC_SIZE(x) __attribute__((__alloc_size__(x))) @@ -159,6 +271,151 @@ #define G_GNUC_ALLOC_SIZE2(x,y) #endif +/** + * G_GNUC_PRINTF: + * @format_idx: the index of the argument corresponding to the + * format string (the arguments are numbered from 1) + * @arg_idx: the index of the first of the format arguments, or 0 if + * there are no format arguments + * + * Expands to the GNU C format function attribute if the compiler is gcc. + * This is used for declaring functions which take a variable number of + * arguments, with the same syntax as printf(). It allows the compiler + * to type-check the arguments passed to the function. + * + * Place the attribute after the function declaration, just before the + * semicolon. + * + * See the + * [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-Wformat-3288) + * for more details. + * + * |[ + * gint g_snprintf (gchar *string, + * gulong n, + * gchar const *format, + * ...) G_GNUC_PRINTF (3, 4); + * ]| + */ + +/** + * G_GNUC_SCANF: + * @format_idx: the index of the argument corresponding to + * the format string (the arguments are numbered from 1) + * @arg_idx: the index of the first of the format arguments, or 0 if + * there are no format arguments + * + * Expands to the GNU C format function attribute if the compiler is gcc. + * This is used for declaring functions which take a variable number of + * arguments, with the same syntax as scanf(). It allows the compiler + * to type-check the arguments passed to the function. + * + * See the + * [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-Wformat-3288) + * for details. + */ + +/** + * G_GNUC_STRFTIME: + * @format_idx: the index of the argument corresponding to + * the format string (the arguments are numbered from 1) + * + * Expands to the GNU C strftime format function attribute if the compiler + * is gcc. This is used for declaring functions which take a format argument + * which is passed to strftime() or an API implementing its formats. It allows + * the compiler check the format passed to the function. + * + * See the + * [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-Wformat-3288) + * for details. + * + * Since: 2.60 + */ + +/** + * G_GNUC_FORMAT: + * @arg_idx: the index of the argument + * + * Expands to the GNU C format_arg function attribute if the compiler + * is gcc. This function attribute specifies that a function takes a + * format string for a printf(), scanf(), strftime() or strfmon() style + * function and modifies it, so that the result can be passed to a printf(), + * scanf(), strftime() or strfmon() style function (with the remaining + * arguments to the format function the same as they would have been + * for the unmodified string). + * + * Place the attribute after the function declaration, just before the + * semicolon. + * + * See the GNU C documentation for more details. + * + * |[ + * gchar *g_dgettext (gchar *domain_name, gchar *msgid) G_GNUC_FORMAT (2); + * ]| + */ + +/** + * G_GNUC_NORETURN: + * + * Expands to the GNU C noreturn function attribute if the compiler is gcc. + * It is used for declaring functions which never return. It enables + * optimization of the function, and avoids possible compiler warnings. + * + * Place the attribute after the declaration, just before the semicolon. + * + * See the GNU C documentation for more details. + */ + +/** + * G_GNUC_CONST: + * + * Expands to the GNU C const function attribute if the compiler is gcc. + * Declaring a function as const enables better optimization of calls to + * the function. A const function doesn't examine any values except its + * parameters, and has no effects except its return value. + * + * Place the attribute after the declaration, just before the semicolon. + * + * See the GNU C documentation for more details. + * + * A function that has pointer arguments and examines the data pointed to + * must not be declared const. Likewise, a function that calls a non-const + * function usually must not be const. It doesn't make sense for a const + * function to return void. + */ + +/** + * G_GNUC_UNUSED: + * + * Expands to the GNU C unused function attribute if the compiler is gcc. + * It is used for declaring functions and arguments which may never be used. + * It avoids possible compiler warnings. + * + * For functions, place the attribute after the declaration, just before the + * semicolon. For arguments, place the attribute at the beginning of the + * argument declaration. + * + * |[ + * void my_unused_function (G_GNUC_UNUSED gint unused_argument, + * gint other_argument) G_GNUC_UNUSED; + * ]| + * + * See the GNU C documentation for more details. + */ + +/** + * G_GNUC_NO_INSTRUMENT: + * + * Expands to the GNU C no_instrument_function function attribute if the + * compiler is gcc. Functions with this attribute will not be instrumented + * for profiling, when the compiler is called with the + * `-finstrument-functions` option. + * + * Place the attribute after the declaration, just before the semicolon. + * + * See the GNU C documentation for more details. + */ + #if __GNUC__ > 2 || (__GNUC__ == 2 && __GNUC_MINOR__ > 4) #if !defined (__clang__) && G_GNUC_CHECK_VERSION (4, 4) #define G_GNUC_PRINTF( format_idx, arg_idx ) \ @@ -200,18 +457,66 @@ #define G_GNUC_NO_INSTRUMENT #endif /* !__GNUC__ */ +/** + * G_GNUC_FALLTHROUGH: + * + * Expands to the GNU C fallthrough statement attribute if the compiler is gcc. + * This allows declaring case statement to explicitly fall through in switch + * statements. To enable this feature, use -Wimplicit-fallthrough during + * compilation. + * + * Put the attribute right before the case statement you want to fall through + * to. + * + * See the GNU C documentation for more details. + * + * Since: 2.60 + */ #if __GNUC__ > 6 #define G_GNUC_FALLTHROUGH __attribute__((fallthrough)) #else #define G_GNUC_FALLTHROUGH #endif /* __GNUC__ */ +/** + * G_GNUC_DEPRECATED: + * + * Expands to the GNU C deprecated attribute if the compiler is gcc. + * It can be used to mark typedefs, variables and functions as deprecated. + * When called with the `-Wdeprecated-declarations` option, + * gcc will generate warnings when deprecated interfaces are used. + * + * Place the attribute after the declaration, just before the semicolon. + * + * See the GNU C documentation for more details. + * + * Since: 2.2 + */ #if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 1) #define G_GNUC_DEPRECATED __attribute__((__deprecated__)) #else #define G_GNUC_DEPRECATED #endif /* __GNUC__ */ +/** + * G_GNUC_DEPRECATED_FOR: + * @f: the intended replacement for the deprecated symbol, + * such as the name of a function + * + * Like %G_GNUC_DEPRECATED, but names the intended replacement for the + * deprecated symbol if the version of gcc in use is new enough to support + * custom deprecation messages. + * + * Place the attribute after the declaration, just before the semicolon. + * + * See the GNU C documentation for more details. + * + * Note that if @f is a macro, it will be expanded in the warning message. + * You can enclose it in quotes to prevent this. (The quotes will show up + * in the warning, but it's better than showing the macro expansion.) + * + * Since: 2.26 + */ #if __GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 5) #define G_GNUC_DEPRECATED_FOR(f) \ __attribute__((deprecated("Use " #f " instead"))) @@ -248,12 +553,36 @@ #define G_GNUC_END_IGNORE_DEPRECATIONS #endif +/** + * G_GNUC_MAY_ALIAS: + * + * Expands to the GNU C may_alias type attribute if the compiler is gcc. + * Types with this attribute will not be subjected to type-based alias + * analysis, but are assumed to alias with any other type, just like char. + * + * See the GNU C documentation for details. + * + * Since: 2.14 + */ #if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 3) #define G_GNUC_MAY_ALIAS __attribute__((may_alias)) #else #define G_GNUC_MAY_ALIAS #endif +/** + * G_GNUC_WARN_UNUSED_RESULT: + * + * Expands to the GNU C warn_unused_result function attribute if the compiler + * is gcc. This function attribute makes the compiler emit a warning if the + * result of a function call is ignored. + * + * Place the attribute after the declaration, just before the semicolon. + * + * See the GNU C documentation for more details. + * + * Since: 2.10 + */ #if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 4) #define G_GNUC_WARN_UNUSED_RESULT __attribute__((warn_unused_result)) #else From a2a17a978a62257759599578ff495f258b69c85b Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Fri, 8 Mar 2019 19:21:39 +0000 Subject: [PATCH 2/2] gmacros: Improve documentation of GCC attributes Link to the GCC documentation pages, and format the attribute names as code. Signed-off-by: Philip Withnall --- glib/gmacros.h | 92 +++++++++++++++++++++++++------------------------- 1 file changed, 46 insertions(+), 46 deletions(-) diff --git a/glib/gmacros.h b/glib/gmacros.h index 1df192801..00e949c35 100644 --- a/glib/gmacros.h +++ b/glib/gmacros.h @@ -98,15 +98,15 @@ /** * G_GNUC_PURE: * - * Expands to the GNU C pure function attribute if the compiler is gcc. - * Declaring a function as pure enables better optimization of calls to - * the function. A pure function has no effects except its return value + * Expands to the GNU C `pure` function attribute if the compiler is gcc. + * Declaring a function as `pure` enables better optimization of calls to + * the function. A `pure` function has no effects except its return value * and the return value depends only on the parameters and/or global * variables. * * Place the attribute after the declaration, just before the semicolon. * - * See the GNU C documentation for more details. + * See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-pure-function-attribute) for more details. */ /** @@ -171,14 +171,14 @@ /** * G_GNUC_NULL_TERMINATED: * - * Expands to the GNU C sentinel function attribute if the compiler is gcc. + * Expands to the GNU C `sentinel` function attribute if the compiler is gcc. * This function attribute only applies to variadic functions and instructs * the compiler to check that the argument list is terminated with an * explicit %NULL. * * Place the attribute after the declaration, just before the semicolon. * - * See the GNU C documentation for more details. + * See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-sentinel-function-attribute) for more details. * * Since: 2.8 */ @@ -232,7 +232,7 @@ * G_GNUC_ALLOC_SIZE: * @x: the index of the argument specifying the allocation size * - * Expands to the GNU C alloc_size function attribute if the compiler + * Expands to the GNU C `alloc_size` function attribute if the compiler * is a new enough gcc. This attribute tells the compiler that the * function returns a pointer to memory of a size that is specified * by the @xth function parameter. @@ -240,7 +240,7 @@ * Place the attribute after the function declaration, just before the * semicolon. * - * See the GNU C documentation for more details. + * See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-alloc_005fsize-function-attribute) for more details. * * Since: 2.18 */ @@ -250,7 +250,7 @@ * @x: the index of the argument specifying one factor of the allocation size * @y: the index of the argument specifying the second factor of the allocation size * - * Expands to the GNU C alloc_size function attribute if the compiler is a + * Expands to the GNU C `alloc_size` function attribute if the compiler is a * new enough gcc. This attribute tells the compiler that the function returns * a pointer to memory of a size that is specified by the product of two * function parameters. @@ -258,7 +258,7 @@ * Place the attribute after the function declaration, just before the * semicolon. * - * See the GNU C documentation for more details. + * See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-alloc_005fsize-function-attribute) for more details. * * Since: 2.18 */ @@ -278,9 +278,9 @@ * @arg_idx: the index of the first of the format arguments, or 0 if * there are no format arguments * - * Expands to the GNU C format function attribute if the compiler is gcc. + * Expands to the GNU C `format` function attribute if the compiler is gcc. * This is used for declaring functions which take a variable number of - * arguments, with the same syntax as printf(). It allows the compiler + * arguments, with the same syntax as `printf()`. It allows the compiler * to type-check the arguments passed to the function. * * Place the attribute after the function declaration, just before the @@ -305,9 +305,9 @@ * @arg_idx: the index of the first of the format arguments, or 0 if * there are no format arguments * - * Expands to the GNU C format function attribute if the compiler is gcc. + * Expands to the GNU C `format` function attribute if the compiler is gcc. * This is used for declaring functions which take a variable number of - * arguments, with the same syntax as scanf(). It allows the compiler + * arguments, with the same syntax as `scanf()`. It allows the compiler * to type-check the arguments passed to the function. * * See the @@ -320,9 +320,9 @@ * @format_idx: the index of the argument corresponding to * the format string (the arguments are numbered from 1) * - * Expands to the GNU C strftime format function attribute if the compiler + * Expands to the GNU C `strftime` format function attribute if the compiler * is gcc. This is used for declaring functions which take a format argument - * which is passed to strftime() or an API implementing its formats. It allows + * which is passed to `strftime()` or an API implementing its formats. It allows * the compiler check the format passed to the function. * * See the @@ -336,18 +336,18 @@ * G_GNUC_FORMAT: * @arg_idx: the index of the argument * - * Expands to the GNU C format_arg function attribute if the compiler + * Expands to the GNU C `format_arg` function attribute if the compiler * is gcc. This function attribute specifies that a function takes a - * format string for a printf(), scanf(), strftime() or strfmon() style - * function and modifies it, so that the result can be passed to a printf(), - * scanf(), strftime() or strfmon() style function (with the remaining + * format string for a `printf()`, `scanf()`, `strftime()` or `strfmon()` style + * function and modifies it, so that the result can be passed to a `printf()`, + * `scanf()`, `strftime()` or `strfmon()` style function (with the remaining * arguments to the format function the same as they would have been * for the unmodified string). * * Place the attribute after the function declaration, just before the * semicolon. * - * See the GNU C documentation for more details. + * See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-Wformat-nonliteral-1) for more details. * * |[ * gchar *g_dgettext (gchar *domain_name, gchar *msgid) G_GNUC_FORMAT (2); @@ -357,37 +357,37 @@ /** * G_GNUC_NORETURN: * - * Expands to the GNU C noreturn function attribute if the compiler is gcc. + * Expands to the GNU C `noreturn` function attribute if the compiler is gcc. * It is used for declaring functions which never return. It enables * optimization of the function, and avoids possible compiler warnings. * * Place the attribute after the declaration, just before the semicolon. * - * See the GNU C documentation for more details. + * See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-noreturn-function-attribute) for more details. */ /** * G_GNUC_CONST: * - * Expands to the GNU C const function attribute if the compiler is gcc. - * Declaring a function as const enables better optimization of calls to - * the function. A const function doesn't examine any values except its + * Expands to the GNU C `const` function attribute if the compiler is gcc. + * Declaring a function as `const` enables better optimization of calls to + * the function. A `const` function doesn't examine any values except its * parameters, and has no effects except its return value. * * Place the attribute after the declaration, just before the semicolon. * - * See the GNU C documentation for more details. + * See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-const-function-attribute) for more details. * * A function that has pointer arguments and examines the data pointed to - * must not be declared const. Likewise, a function that calls a non-const - * function usually must not be const. It doesn't make sense for a const - * function to return void. + * must not be declared `const`. Likewise, a function that calls a non-`const` + * function usually must not be `const`. It doesn't make sense for a `const` + * function to return `void`. */ /** * G_GNUC_UNUSED: * - * Expands to the GNU C unused function attribute if the compiler is gcc. + * Expands to the GNU C `unused` function attribute if the compiler is gcc. * It is used for declaring functions and arguments which may never be used. * It avoids possible compiler warnings. * @@ -400,20 +400,20 @@ * gint other_argument) G_GNUC_UNUSED; * ]| * - * See the GNU C documentation for more details. + * See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-unused-function-attribute) for more details. */ /** * G_GNUC_NO_INSTRUMENT: * - * Expands to the GNU C no_instrument_function function attribute if the + * Expands to the GNU C `no_instrument_function` function attribute if the * compiler is gcc. Functions with this attribute will not be instrumented * for profiling, when the compiler is called with the * `-finstrument-functions` option. * * Place the attribute after the declaration, just before the semicolon. * - * See the GNU C documentation for more details. + * See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-no_005finstrument_005ffunction-function-attribute) for more details. */ #if __GNUC__ > 2 || (__GNUC__ == 2 && __GNUC_MINOR__ > 4) @@ -460,15 +460,15 @@ /** * G_GNUC_FALLTHROUGH: * - * Expands to the GNU C fallthrough statement attribute if the compiler is gcc. + * Expands to the GNU C `fallthrough` statement attribute if the compiler is gcc. * This allows declaring case statement to explicitly fall through in switch - * statements. To enable this feature, use -Wimplicit-fallthrough during + * statements. To enable this feature, use `-Wimplicit-fallthrough` during * compilation. * * Put the attribute right before the case statement you want to fall through * to. * - * See the GNU C documentation for more details. + * See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Statement-Attributes.html#index-fallthrough-statement-attribute) for more details. * * Since: 2.60 */ @@ -481,14 +481,14 @@ /** * G_GNUC_DEPRECATED: * - * Expands to the GNU C deprecated attribute if the compiler is gcc. - * It can be used to mark typedefs, variables and functions as deprecated. + * Expands to the GNU C `deprecated` attribute if the compiler is gcc. + * It can be used to mark `typedef`s, variables and functions as deprecated. * When called with the `-Wdeprecated-declarations` option, * gcc will generate warnings when deprecated interfaces are used. * * Place the attribute after the declaration, just before the semicolon. * - * See the GNU C documentation for more details. + * See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-deprecated-function-attribute) for more details. * * Since: 2.2 */ @@ -509,7 +509,7 @@ * * Place the attribute after the declaration, just before the semicolon. * - * See the GNU C documentation for more details. + * See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-deprecated-function-attribute) for more details. * * Note that if @f is a macro, it will be expanded in the warning message. * You can enclose it in quotes to prevent this. (The quotes will show up @@ -556,11 +556,11 @@ /** * G_GNUC_MAY_ALIAS: * - * Expands to the GNU C may_alias type attribute if the compiler is gcc. + * Expands to the GNU C `may_alias` type attribute if the compiler is gcc. * Types with this attribute will not be subjected to type-based alias - * analysis, but are assumed to alias with any other type, just like char. + * analysis, but are assumed to alias with any other type, just like `char`. * - * See the GNU C documentation for details. + * See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Type-Attributes.html#index-may_005falias-type-attribute) for details. * * Since: 2.14 */ @@ -573,13 +573,13 @@ /** * G_GNUC_WARN_UNUSED_RESULT: * - * Expands to the GNU C warn_unused_result function attribute if the compiler + * Expands to the GNU C `warn_unused_result` function attribute if the compiler * is gcc. This function attribute makes the compiler emit a warning if the * result of a function call is ignored. * * Place the attribute after the declaration, just before the semicolon. * - * See the GNU C documentation for more details. + * See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-warn_005funused_005fresult-function-attribute) for more details. * * Since: 2.10 */