luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-12-28 08:26:14 +01:00
Code Issues Packages Projects Releases Wiki Activity

gmacros: Improve documentation of GCC attributes

Browse Source 
Link to the GCC documentation pages, and format the attribute names as
code.

Signed-off-by: Philip Withnall <withnall@endlessm.com>
This commit is contained in:
Philip Withnall 2019-03-08 19:21:39 +00:00
parent e03a2c8633
commit a2a17a978a
1 changed files with 46 additions and 46 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

92
glib/gmacros.h
View File

@ -98,15 +98,15 @@
/** /**
* G_GNUC_PURE: * G_GNUC_PURE:
* *
* Expands to the GNU C pure function attribute if the compiler is gcc. * Expands to the GNU C `pure` function attribute if the compiler is gcc.
* Declaring a function as pure enables better optimization of calls to * Declaring a function as `pure` enables better optimization of calls to
* the function. A pure function has no effects except its return value * the function. A `pure` function has no effects except its return value
* and the return value depends only on the parameters and/or global * and the return value depends only on the parameters and/or global
* variables. * variables.
* *
* Place the attribute after the declaration, just before the semicolon. * 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: * 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 * This function attribute only applies to variadic functions and instructs
* the compiler to check that the argument list is terminated with an * the compiler to check that the argument list is terminated with an
* explicit %NULL. * explicit %NULL.
* *
* Place the attribute after the declaration, just before the semicolon. * 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 * Since: 2.8
*/ */
@ -232,7 +232,7 @@
* G_GNUC_ALLOC_SIZE: * G_GNUC_ALLOC_SIZE:
* @x: the index of the argument specifying the allocation 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 * is a new enough gcc. This attribute tells the compiler that the
* function returns a pointer to memory of a size that is specified * function returns a pointer to memory of a size that is specified
* by the @xth function parameter. * by the @xth function parameter.
@ -240,7 +240,7 @@
* Place the attribute after the function declaration, just before the * Place the attribute after the function declaration, just before the
* semicolon. * 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 * Since: 2.18
*/ */
@ -250,7 +250,7 @@
* @x: the index of the argument specifying one factor of the allocation size * @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 * @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 * 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 * a pointer to memory of a size that is specified by the product of two
* function parameters. * function parameters.
@ -258,7 +258,7 @@
* Place the attribute after the function declaration, just before the * Place the attribute after the function declaration, just before the
* semicolon. * 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 * Since: 2.18
*/ */
@ -278,9 +278,9 @@
* @arg_idx: the index of the first of the format arguments, or 0 if * @arg_idx: the index of the first of the format arguments, or 0 if
* there are no format arguments * 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 * 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. * to type-check the arguments passed to the function.
* *
* Place the attribute after the function declaration, just before the * 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 * @arg_idx: the index of the first of the format arguments, or 0 if
* there are no format arguments * 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 * 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. * to type-check the arguments passed to the function.
* *
* See the * See the
@ -320,9 +320,9 @@
* @format_idx: the index of the argument corresponding to * @format_idx: the index of the argument corresponding to
* the format string (the arguments are numbered from 1) * 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 * 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. * the compiler check the format passed to the function.
* *
* See the * See the
@ -336,18 +336,18 @@
* G_GNUC_FORMAT: * G_GNUC_FORMAT:
* @arg_idx: the index of the argument * @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 * is gcc. This function attribute specifies that a function takes a
* format string for a printf(), scanf(), strftime() or strfmon() style * format string for a `printf()`, `scanf()`, `strftime()` or `strfmon()` style
* function and modifies it, so that the result can be passed to a printf(), * function and modifies it, so that the result can be passed to a `printf()`,
* scanf(), strftime() or strfmon() style function (with the remaining * `scanf()`, `strftime()` or `strfmon()` style function (with the remaining
* arguments to the format function the same as they would have been * arguments to the format function the same as they would have been
* for the unmodified string). * for the unmodified string).
* *
* Place the attribute after the function declaration, just before the * Place the attribute after the function declaration, just before the
* semicolon. * 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.
* *
* |[<!-- language="C" --> * |[<!-- language="C" -->
* gchar *g_dgettext (gchar *domain_name, gchar *msgid) G_GNUC_FORMAT (2); * gchar *g_dgettext (gchar *domain_name, gchar *msgid) G_GNUC_FORMAT (2);
@ -357,37 +357,37 @@
/** /**
* G_GNUC_NORETURN: * 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 * It is used for declaring functions which never return. It enables
* optimization of the function, and avoids possible compiler warnings. * optimization of the function, and avoids possible compiler warnings.
* *
* Place the attribute after the declaration, just before the semicolon. * 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: * G_GNUC_CONST:
* *
* Expands to the GNU C const function attribute if the compiler is gcc. * Expands to the GNU C `const` function attribute if the compiler is gcc.
* Declaring a function as const enables better optimization of calls to * Declaring a function as `const` enables better optimization of calls to
* the function. A const function doesn't examine any values except its * the function. A `const` function doesn't examine any values except its
* parameters, and has no effects except its return value. * parameters, and has no effects except its return value.
* *
* Place the attribute after the declaration, just before the semicolon. * 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 * 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 * 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 usually must not be `const`. It doesn't make sense for a `const`
* function to return void. * function to return `void`.
*/ */
/** /**
* G_GNUC_UNUSED: * 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 is used for declaring functions and arguments which may never be used.
* It avoids possible compiler warnings. * It avoids possible compiler warnings.
* *
@ -400,20 +400,20 @@
* gint other_argument) G_GNUC_UNUSED; * 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: * 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 * compiler is gcc. Functions with this attribute will not be instrumented
* for profiling, when the compiler is called with the * for profiling, when the compiler is called with the
* `-finstrument-functions` option. * `-finstrument-functions` option.
* *
* Place the attribute after the declaration, just before the semicolon. * 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) #if __GNUC__ > 2 || (__GNUC__ == 2 && __GNUC_MINOR__ > 4)
@ -460,15 +460,15 @@
/** /**
* G_GNUC_FALLTHROUGH: * 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 * 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. * compilation.
* *
* Put the attribute right before the case statement you want to fall through * Put the attribute right before the case statement you want to fall through
* to. * 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 * Since: 2.60
*/ */
@ -481,14 +481,14 @@
/** /**
* G_GNUC_DEPRECATED: * G_GNUC_DEPRECATED:
* *
* Expands to the GNU C deprecated attribute if the compiler is gcc. * Expands to the GNU C `deprecated` attribute if the compiler is gcc.
* It can be used to mark typedefs, variables and functions as deprecated. * It can be used to mark `typedef`s, variables and functions as deprecated.
* When called with the `-Wdeprecated-declarations` option, * When called with the `-Wdeprecated-declarations` option,
* gcc will generate warnings when deprecated interfaces are used. * gcc will generate warnings when deprecated interfaces are used.
* *
* Place the attribute after the declaration, just before the semicolon. * 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 * Since: 2.2
*/ */
@ -509,7 +509,7 @@
* *
* Place the attribute after the declaration, just before the semicolon. * 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. * 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 * You can enclose it in quotes to prevent this. (The quotes will show up
@ -556,11 +556,11 @@
/** /**
* G_GNUC_MAY_ALIAS: * 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 * 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 * Since: 2.14
*/ */
@ -573,13 +573,13 @@
/** /**
* G_GNUC_WARN_UNUSED_RESULT: * 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 * is gcc. This function attribute makes the compiler emit a warning if the
* result of a function call is ignored. * result of a function call is ignored.
* *
* Place the attribute after the declaration, just before the semicolon. * 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 * Since: 2.10
*/ */