[glib: 1/3] glib: Move various documentation comments from docs.c to macros.h

[Simon McVittie <smcv src gnome org>]

commit e03a2c8633c45f8f342f916c7784a0e8efc933f3
Author: Philip Withnall <withnall endlessm com>
Date:   Fri Mar 8 19:10:32 2019 +0000

    glib: Move various documentation comments from docs.c to macros.h
    
    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 <withnall endlessm com>

 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.
- *
- * |[<!-- language="C" -->
- * 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.
- *
- * |[<!-- language="C" -->
- * 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.
- *
- * |[<!-- language="C" -->
- * 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.
+ *
+ * |[<!-- language="C" -->
+ * 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.
+ *
+ * |[<!-- language="C" -->
+ * 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.
+ *
+ * |[<!-- language="C" -->
+ * 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