[glib: 1/2] Provide examples for GNUC attribute macros

[Philip Withnall <pwithnall src gnome org>]

commit 1e3793546dc1128ce5504f8ea5bfba81260a68d0
Author: Simon McVittie <smcv collabora com>
Date:   Wed Mar 13 15:45:23 2019 +0000

    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: Simon McVittie <smcv collabora com>

 glib/docs.c    | 20 +++++++++++++
 glib/gmacros.h | 88 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 106 insertions(+), 2 deletions(-)
---
diff --git a/glib/docs.c b/glib/docs.c
index cfcbcfea7..cbe929a0a 100644
--- a/glib/docs.c
+++ b/glib/docs.c
@@ -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
  */
 
diff --git a/glib/gmacros.h b/glib/gmacros.h
index 00e949c35..cb78bd20c 100644
--- a/glib/gmacros.h
+++ b/glib/gmacros.h
@@ -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