From 5008f98a8208d96c3c777476d6df7534c6d2ca49 Mon Sep 17 00:00:00 2001 From: Andre Noll Date: Wed, 12 Nov 2008 22:40:00 +0100 Subject: [PATCH] Some more source code documentation. --- adu.c | 3 +-- adu.h | 12 ------------ gcc-compat.h | 54 ++++++++++++++++++++++++++++++++++++++++++++++------ string.c | 2 +- 4 files changed, 50 insertions(+), 21 deletions(-) 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. -- 2.39.5