-# define inline inline __attribute__ ((always_inline))
-# define __noreturn __attribute__ ((noreturn))
-# define __malloc __attribute__ ((malloc))
+/** \file gcc-compat.h Compatibility defines and macros. */
+
+/** We want you-asked-for-it-you-got-it behavior. */
+# define inline inline __attribute__ ((always_inline))
+
+/** Using \p __malloc for malloc-type functions often improves optimization. */
+# define __malloc __attribute__ ((malloc))
+
+/**
+ * This allows to enable gcc's -Wunused messages.
+ *
+ * This gcc option can print warnings that can not be avoided easily. For
+ * example when using an array of (structures containing) function pointers.
+ * If not all the functions (handlers) use all arguments, gcc will print
+ * a warning.
+ *
+ * Marking those few unused function parameters with \p __a_unused to suppress
+ * the gcc warnings allows us to get a clean build _and_ the benefit of the
+ * warning in other cases where we do care about unused parameters.
+ */