From: Andre Noll <maan@systemlinux.org>
Date: Wed, 12 Nov 2008 21:40:00 +0000 (+0100)
Subject: Some more source code documentation.
X-Git-Tag: v0.1.0~24
X-Git-Url: http://git.tuebingen.mpg.de/?p=adu.git;a=commitdiff_plain;h=5008f98a8208d96c3c777476d6df7534c6d2ca49

Some more source code documentation.
---

diff --git a/adu.c b/adu.c
index b8c7b68..dd74ca4 100644
--- a/adu.c
+++ b/adu.c
@@ -13,7 +13,6 @@
  * - User handling: \ref user.c
  * - Error handling: \ref error.h
  * - Library-type functions: \ref fd.c, \ref format.c, \ref string.c, \ref portable_io.h
- * - Generated files: \ref cmdline.h, \ref select.cmdline.h
  */
 
 #include "adu.h"
@@ -32,7 +31,7 @@
 DEFINE_ERRLIST;
 
 /**
- * The error code of the last osl library function.
+ * The error code of the last called osl library function.
  *
  * \sa osl().
  */
diff --git a/adu.h b/adu.h
index c67dd6b..5e99709 100644
--- a/adu.h
+++ b/adu.h
@@ -41,18 +41,6 @@
 /** Log messages with lower priority than that will not be compiled in. */
 #define COMPILE_TIME_LOGLEVEL 0
 
-/**
- *  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
-
 /** \cond */
 #if DEBUG > COMPILE_TIME_LOGLEVEL
 #define DEBUG_LOG(f,...) __log(DEBUG, "%s: " f, __FUNCTION__, ## __VA_ARGS__)
diff --git a/gcc-compat.h b/gcc-compat.h
index df80001..ec24db9 100644
--- 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
diff --git a/string.c b/string.c
index 17edffc..77c90cb 100644
--- a/string.c
+++ b/string.c
@@ -340,7 +340,7 @@ void free_argv(char **argv)
  *
  * In contrast to gengetopt's string parser, double quotes, backslash-escaped
  * characters and special characters like \p \\n are honored. The result
- * contains pointers to copies of the words contained in \line and has to be
+ * contains pointers to copies of the words contained in \a line and has to be
  * freed by using \ref free_argv().
  *
  * \param line The line to be split.