From d2ce6e60cb915dff3a0920a0b48f786435bd4ec8 Mon Sep 17 00:00:00 2001
From: Andre Noll <maan@systemlinux.org>
Date: Tue, 11 Nov 2008 23:08:43 +0100
Subject: [PATCH] Add yet more source code documentation.

---
 adu.h         | 18 +++++++++++++++---
 create.c      |  5 +++++
 error.h       | 22 ++++++++++++++++++++--
 fd.h          |  2 +-
 format.c      |  1 +
 format.h      |  2 +-
 interactive.c | 14 ++++++++++++++
 select.h      |  1 +
 string.c      | 22 +++++++++++++++++++---
 string.h      |  2 +-
 user.h        |  2 ++
 11 files changed, 80 insertions(+), 11 deletions(-)

diff --git a/adu.h b/adu.h
index 3105044..c67dd6b 100644
--- a/adu.h
+++ b/adu.h
@@ -4,7 +4,7 @@
  * Licensed under the GPL v2. For licencing details see COPYING.
  */
 
-/** \file adu.h Global definitions. */
+/** \file adu.h \brief Global definitions. */
 
 #include <sys/stat.h>
 #include <fcntl.h>
@@ -41,6 +41,18 @@
 /** 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__)
@@ -157,7 +169,7 @@ extern struct select_args_info select_conf;
  *
  * \sa osl_compare_func, osl_hash_compare().
  */
-static inline int uint64_compare(const struct osl_object *obj1,
+_static_inline_ int uint64_compare(const struct osl_object *obj1,
 		const struct osl_object *obj2)
 {
 	uint64_t d1 = read_u64((const char *)obj1->data);
@@ -180,7 +192,7 @@ static inline int uint64_compare(const struct osl_object *obj1,
  * equal, the address of \a obj1 and \a obj2 are compared. So this compare function
  * returns zero if and only if \a obj1 and \a obj2 point to the same memory area.
  */
-static inline int size_compare(const struct osl_object *obj1, const struct osl_object *obj2)
+_static_inline_ int size_compare(const struct osl_object *obj1, const struct osl_object *obj2)
 {
 	uint64_t d1 = *(uint64_t *)obj1->data;
 	uint64_t d2 = *(uint64_t *)obj2->data;
diff --git a/create.c b/create.c
index 3a221ca..65567e0 100644
--- a/create.c
+++ b/create.c
@@ -151,6 +151,11 @@ out:
 	return ret;
 }
 
+/**
+ * The main function of the create mode.
+ *
+ * \return Standard.
+ */
 int com_create(void)
 {
 	uint64_t zero = 0ULL;
diff --git a/error.h b/error.h
index 9874003..00bdede 100644
--- a/error.h
+++ b/error.h
@@ -4,6 +4,8 @@
  * Licensed under the GPL v2. For licencing details see COPYING.
  */
 
+/** \file error.h \brief Error handling functions and macros. */
+
 /**
  * This bit indicates whether a number is considered a system error code.
  * If yes, the system errno is just the result of clearing this bit from
@@ -17,6 +19,7 @@
 /** Set the system error bit for the given number. */
 #define ERRNO_TO_ERROR(num) ((num) | (1 << SYSTEM_ERROR_BIT))
 
+/** The list of all adu error codes with descriptions. */
 #define ALL_ERRORS \
 	_ERROR(SUCCESS, "success") \
 	_ERROR(SYNTAX, "syntax error") \
@@ -48,14 +51,27 @@
  */
 #define _ERROR(err, msg) E_ ## err,
 
+/**
+ * \cond (doxygen can not handle multiple definitions of the same macro).
+ *
+ * This just creates an enum consisting of the first argument of the above
+ * error list.
+ */
 enum error_codes {
 	ALL_ERRORS
 };
 #undef _ERROR
+
+/*
+ * Here we define the array of error texts used by adu_strerror().
+ */
 #define _ERROR(err, msg) msg,
 #define DEFINE_ERRLIST char *adu_errlist[] = {ALL_ERRORS}
+/** \endcond */
 
 extern int osl_errno;
+
+/** Contains the description of all adu error codes. */
 extern char *adu_errlist[];
 
 
@@ -66,7 +82,7 @@ extern char *adu_errlist[];
  *
  * \return The error text of \a num.
  */
-static inline const char *adu_strerror(int num)
+_static_inline_ const char *adu_strerror(int num)
 {
 	assert(num > 0);
 	if (num == E_OSL) {
@@ -81,13 +97,15 @@ static inline const char *adu_strerror(int num)
 /**
  * Wrapper for osl library calls.
  *
+ * \param ret The return value of an osl library function.
+ *
  * This should be used for all calls to osl functions that return an osl error
  * code. It changes the return value to \p -E_OSL appropriately so that it can
  * be used for printing the correct error message.
  *
  * \return \a ret if \a ret >= 0, \p -E_OSL otherwise.
  */
-static inline int osl(int ret)
+_static_inline_ int osl(int ret)
 {
 	if (ret >= 0)
 		return ret;
diff --git a/fd.h b/fd.h
index 87083c2..6ebd9c9 100644
--- a/fd.h
+++ b/fd.h
@@ -4,7 +4,7 @@
  * Licensed under the GPL v2. For licencing details see COPYING.
  */
 
-/** \file fd.h exported symbols from fd.c */
+/** \file fd.h \brief Exported symbols from fd.c */
 
 int adu_opendir(const char *dirname, DIR **dir, int *cwd);
 int adu_fchdir(int fd);
diff --git a/format.c b/format.c
index f1d1247..e8a9a28 100644
--- a/format.c
+++ b/format.c
@@ -14,6 +14,7 @@
 #include "error.h"
 #include "format.h"
 
+/** The three different alignment types. */
 enum alignment {ALIGN_LEFT, ALIGN_RIGHT, ALIGN_CENTER};
 
 struct num_format {
diff --git a/format.h b/format.h
index 9761ea2..b5ca1af 100644
--- a/format.h
+++ b/format.h
@@ -4,7 +4,7 @@
  * Licensed under the GPL v2. For licencing details see COPYING.
  */
 
-/** \file format.h Exported symbols from \p format.c. */
+/** \file format.h \brief Exported symbols from \p format.c. */
 
 /** The possible types of format string directives (aka atoms). */
 enum atom_type {
diff --git a/interactive.c b/interactive.c
index 4c03927..7327ee1 100644
--- a/interactive.c
+++ b/interactive.c
@@ -4,6 +4,8 @@
  * Licensed under the GPL v2. For licencing details see COPYING.
  */
 
+/** \file interactive.c \brief Commands for interactive mode. */
+
 #include <ctype.h> /* isspace() */
 
 #include "adu.h"
@@ -32,6 +34,7 @@ struct interactive_command {
 static struct uid_range *admissible_uids;
 static struct format_info *fi;
 
+/** The set of supported interactive commands. */
 #define INTERACTIVE_COMMANDS \
 	INTERACTIVE_COMMAND(set, "change the current configuration") \
 	INTERACTIVE_COMMAND(reset, "reset configuration to defaults") \
@@ -40,6 +43,7 @@ static struct format_info *fi;
 	INTERACTIVE_COMMAND(source, "read and execute interactive commands from a file")
 
 
+/** \cond doxygen is not smart enough for this */
 #define INTERACTIVE_COMMAND(name, desc) \
 	static int icom_ ## name (char *line);
 
@@ -58,7 +62,9 @@ struct interactive_command icmds[] = {
 	INTERACTIVE_COMMANDS
 	{.name  = NULL}
 };
+/** \endcond */
 
+/** Iterate over the list of all interactive commands. */
 #define FOR_EACH_COMMAND(c) for (c = icmds; c->name; c++)
 
 static int read_input_line(char *line, size_t size)
@@ -80,6 +86,9 @@ static int icom_help(__a_unused char *line)
 	return 1;
 }
 
+/**
+ * Print the list of commands with short descriptions.
+ */
 void print_interactive_help(void)
 {
 	struct interactive_command *c;
@@ -190,6 +199,11 @@ out:
 	return ret;
 }
 
+/**
+ * The main function for interactive mode.
+ *
+ * \return Standard.
+ */
 int com_interactive(void)
 {
 	char line[255];
diff --git a/select.h b/select.h
index 7891ff8..06ee034 100644
--- a/select.h
+++ b/select.h
@@ -4,6 +4,7 @@
  * Licensed under the GPL v2. For licencing details see COPYING.
  */
 
+/** \file select.h \brief Exported functions from string.c. */
 int parse_select_options(char *string, struct select_cmdline_parser_params *params,
 		struct uid_range **admissible_uids, struct format_info **fi);
 int run_select_query(struct uid_range *admissible_uids, struct format_info *fi);
diff --git a/string.c b/string.c
index 07dd845..17edffc 100644
--- a/string.c
+++ b/string.c
@@ -196,14 +196,14 @@ __must_check int atoi64(const char *str, int64_t *result)
 }
 
 /**
- * Split string and return pointers to its parts.
+ * Split a string and return pointers to its parts.
  *
  * \param args The string to be split.
  * \param argv_ptr Pointer to the list of substrings.
  * \param delim Delimiter.
  *
  * This function modifies \a args by replacing each occurance of \a delim by
- * zero. A \p NULL-terminated array of pointers to char* is allocated dynamically
+ * zero. A \p NULL terminated array of pointers to char* is allocated dynamically
  * and these pointers are initialized to point to the broken-up substrings
  * within \a args. A pointer to this array is returned via \a argv_ptr.
  *
@@ -245,10 +245,11 @@ __must_check unsigned split_args(char *args, char *** const argv_ptr, const char
 	return n;
 }
 
-enum line_state_flags {LSF_HAVE_WORD = 1, LSF_BACKSLASH = 2, LSF_QUOTE = 4};
 
 static int get_next_word(const char *line, char **word)
 {
+	enum line_state_flags {LSF_HAVE_WORD = 1, LSF_BACKSLASH = 2,
+		LSF_QUOTE = 4};
 	const char *in;
 	char *out;
 	int ret, state = 0;
@@ -320,6 +321,11 @@ out:
 	return ret;
 }
 
+/**
+ * Free an array of words created by create_argv().
+ *
+ * \param argv A pointer previously obtained by \ref create_argv().
+ */
 void free_argv(char **argv)
 {
 	int i;
@@ -330,6 +336,16 @@ void free_argv(char **argv)
 }
 
 /**
+ * Split a line into words which are separated by whitespace.
+ *
+ * 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
+ * freed by using \ref free_argv().
+ *
+ * \param line The line to be split.
+ * \param result The array of words is returned here.
+ *
  * \return Number of words in \a line, negative on errors.
  */
 int create_argv(const char *line, char ***result)
diff --git a/string.h b/string.h
index 1eb8f01..1283769 100644
--- a/string.h
+++ b/string.h
@@ -4,7 +4,7 @@
  * Licensed under the GPL v2. For licencing details see COPYING.
  */
 
-/** \file string.h exported sybmols from string.c */
+/** \file string.h \brief Exported sybmols from string.c */
 
 __must_check __malloc void *adu_realloc(void *p, size_t size);
 __must_check __malloc void *adu_malloc(size_t size);
diff --git a/user.h b/user.h
index c561a3f..acd0b8d 100644
--- a/user.h
+++ b/user.h
@@ -4,6 +4,8 @@
  * Licensed under the GPL v2. For licencing details see COPYING.
  */
 
+/** \file user.h \brief User structures and exported symbols from user.c. */
+
 /** The columns of the id table. */
 enum user_table_columns {
 	/** The numer of the directory. */
-- 
2.39.2