Commit 1e379354 authored by Simon McVittie's avatar Simon McVittie

Provide examples for GNUC attribute macros

It isn't always obvious how and where to use these. Where possible I've
chosen real examples from GLib, preferring simple examples that
developers considering using these macros have hopefully already seen.
Signed-off-by: 's avatarSimon McVittie <smcv@collabora.com>
parent b94a0fc2
......@@ -2054,6 +2054,16 @@
* This macro can be used either inside or outside of a function body,
* but must appear on a line by itself.
*
* |[<!-- language="C" --
* static void
* test_deprecated_function (void)
* {
* G_GNUC_BEGIN_IGNORE_DEPRECATIONS
* g_assert_cmpint (my_mistake (), ==, 42);
* G_GNUC_END_IGNORE_DEPRECATIONS
* }
* ]|
*
* Since: 2.32
*/
......@@ -2078,6 +2088,11 @@
* meant to be portable across different compilers and must be placed
* before the function declaration.
*
* |[<!-- language="C" --
* G_DEPRECATED
* int my_mistake (void);
* ]|
*
* Since: 2.32
*/
......@@ -2090,6 +2105,11 @@
* is meant to be portable across different compilers and must be placed
* before the function declaration.
*
* |[<!-- language="C" --
* G_DEPRECATED_FOR(my_replacement)
* int my_mistake (void);
* ]|
*
* Since: 2.32
*/
......
......@@ -106,6 +106,10 @@
*
* Place the attribute after the declaration, just before the semicolon.
*
* |[<!-- language="C" -->
* gboolean g_type_check_value (const GValue *value) G_GNUC_PURE;
* ]|
*
* See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-pure-function-attribute) for more details.
*/
......@@ -132,6 +136,10 @@
*
* Place the attribute after the declaration, just before the semicolon.
*
* |[<!-- language="C" -->
* gpointer g_malloc (gsize n_bytes) G_GNUC_MALLOC G_GNUC_ALLOC_SIZE(1);
* ]|
*
* See the
* [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-functions-that-behave-like-malloc)
* for more details.
......@@ -148,8 +156,17 @@
* 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.
* The attribute may be placed before the declaration or definition,
* right before the `static` keyword.
*
* |[<!-- language="C" -->
* G_GNUC_NO_INLINE
* static int
* do_not_inline_this (void)
* {
* ...
* }
* ]|
*
* See the
* [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-noinline-function-attribute)
......@@ -178,6 +195,11 @@
*
* Place the attribute after the declaration, just before the semicolon.
*
* |[<!-- language="C" -->
* gchar *g_strconcat (const gchar *string1,
* ...) G_GNUC_NULL_TERMINATED;
* ]|
*
* 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
......@@ -240,6 +262,10 @@
* Place the attribute after the function declaration, just before the
* semicolon.
*
* |[<!-- language="C" -->
* gpointer g_malloc (gsize n_bytes) G_GNUC_MALLOC G_GNUC_ALLOC_SIZE(1);
* ]|
*
* 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
......@@ -258,6 +284,11 @@
* Place the attribute after the function declaration, just before the
* semicolon.
*
* |[<!-- language="C" -->
* gpointer g_malloc_n (gsize n_blocks,
* gsize n_block_bytes) G_GNUC_MALLOC G_GNUC_ALLOC_SIZE2(1, 2);
* ]|
*
* 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
......@@ -310,6 +341,15 @@
* arguments, with the same syntax as `scanf()`. It allows the compiler
* to type-check the arguments passed to the function.
*
* |[<!-- language="C" -->
* int my_scanf (MyStream *stream,
* const char *format,
* ...) G_GNUC_SCANF (2, 3);
* int my_vscanf (MyStream *stream,
* const char *format,
* va_list ap) G_GNUC_SCANF (2, 0);
* ]|
*
* See the
* [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-Wformat-3288)
* for details.
......@@ -325,6 +365,12 @@
* which is passed to `strftime()` or an API implementing its formats. It allows
* the compiler check the format passed to the function.
*
* |[<!-- language="C" -->
* gsize my_strftime (MyBuffer *buffer,
* const char *format,
* const struct tm *tm) G_GNUC_STRFTIME (2);
* ]|
*
* See the
* [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-Wformat-3288)
* for details.
......@@ -363,6 +409,10 @@
*
* Place the attribute after the declaration, just before the semicolon.
*
* |[<!-- language="C" -->
* void g_abort (void) G_GNUC_NORETURN;
* ]|
*
* See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-noreturn-function-attribute) for more details.
*/
......@@ -376,6 +426,10 @@
*
* Place the attribute after the declaration, just before the semicolon.
*
* |[<!-- language="C" -->
* gchar g_ascii_tolower (gchar c) G_GNUC_CONST;
* ]|
*
* 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
......@@ -413,6 +467,10 @@
*
* Place the attribute after the declaration, just before the semicolon.
*
* |[<!-- language="C" -->
* int do_uninteresting_things (void) G_GNUC_NO_INSTRUMENT;
* ]|
*
* See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-no_005finstrument_005ffunction-function-attribute) for more details.
*/
......@@ -468,6 +526,19 @@
* Put the attribute right before the case statement you want to fall through
* to.
*
* |[<!-- language="C" -->
* switch (foo)
* {
* case 1:
* g_message ("it's 1");
* G_GNUC_FALLTHROUGH;
* case 2:
* g_message ("it's either 1 or 2");
* break;
* }
* ]|
*
*
* See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Statement-Attributes.html#index-fallthrough-statement-attribute) for more details.
*
* Since: 2.60
......@@ -488,6 +559,10 @@
*
* Place the attribute after the declaration, just before the semicolon.
*
* |[<!-- language="C" -->
* int my_mistake (void) G_GNUC_DEPRECATED;
* ]|
*
* 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,6 +584,10 @@
*
* Place the attribute after the declaration, just before the semicolon.
*
* |[<!-- language="C" -->
* int my_mistake (void) G_GNUC_DEPRECATED_FOR(my_replacement);
* ]|
*
* 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.
......@@ -579,6 +658,11 @@
*
* Place the attribute after the declaration, just before the semicolon.
*
* |[<!-- language="C" -->
* GList *g_list_append (GList *list,
* gpointer data) G_GNUC_WARN_UNUSED_RESULT;
* ]|
*
* 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
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment