Some more source code documentation.

[adu.git] / gcc-compat.h

diff --git a/gcc-compat.h b/gcc-compat.h
index df80001c941142ecb609a68d0a8fc8b66615f7b9..ec24db9250afbe4bff0786b0c95747dc297933db 100644 (file)
--- a/gcc-compat.h
+++ b/gcc-compat.h
@@ -4,28 +4,70 @@
  * Licensed under the GPL v2. For licencing details see COPYING.
  */
 
-# 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 supress
+ * 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.
+ */
 # define __a_unused    __attribute__ ((unused))
+
+/** The result \a x is expected to be non-zero. */
 # define likely(x)     __builtin_expect (!!(x), 1)
+/** The result \a x is expected to be zero (or \p NULL). */
 # define unlikely(x)   __builtin_expect (!!(x), 0)
-/*
- * p is the number of the "format string" parameter, and q is
- * the number of the first variadic parameter
+
+/**
+ * Let gcc check format strings also for our own functions.
+ *
+ * Functions marked with \p __printf will be cheked by gcc for format string
+ * bugs, just like printf() if -Wformat-security is enabled.
+ *
+ * \param p The number of the "format string" parameter.
+ * \param q The Number of the first variadic parameter.
  */
 # define __printf(p,q) __attribute__ ((format (printf, p, q)))
+
 /*
  * as direct use of __printf(p,q) confuses doxygen, here are two extra macros
  * for those values p,q that are actually used.
  */
+
+/** First parameter is the format string, second the first variadic parameter. */
 #define  __printf_1_2 __printf(1,2)
+/** Second parameter is the format string, third the first variadic parameter. */
 #define  __printf_2_3 __printf(2,3)
 
+/** Print a warning if the return value is not used by the caller. */
 # if __GNUC__ > 3  || (__GNUC__ == 3 && __GNUC_MINOR__ > 3)
 # define __must_check  __attribute__ ((warn_unused_result))
 # else
 # define __must_check  /* no warn_unused_result */
 # endif
 
+
+/**
+ *  A variant of static inline that requires the object being documented.
+ *
+ * If doxygen finds the \p static keyword in any context, that part will not be
+ * included in the documentation. However, we want static inline functions in
+ * header files to be documented while static functions in C files and
+ * statically declared variables should be left out. As a workaround for this
+ * flaw we use \p _static_inline_ for static inline functions declared in
+ * header files.
+ */
 #define _static_inline_ static inline