Various Doxygen-related fixes in libpayload (trivial).

 
 - Drop all '@brief's, they're not needed as we use JAVADOC_AUTOBRIEF.
   The first sentence of every description will be treated as the '@brief'
   automatically.
 
 - Also, put all documentation/descriptions on top of the Doxygen-comments,
   and put the '@foo' keywords at the bottom of the comments for consistency.
 
 - Change comments for SEEK_SET/SEEK_CUR/SEEK_END from '/**@def' to '/**<'
   in order to make them appear in the output.
 
 - Drop all explicit '@struct' lines (which are optional; Doxygen will figure
   out that it's a struct if the comment is right before the struct).
 
 - Fix various typos, whitespace issues, etc.
 
 - Fix incorrect @param variable names, e.g. change '@param n foobar' to
   '@param s foobar' if the variable is named 's'.

Signed-off-by: Uwe Hermann <uwe@hermann-uwe.de>
Acked-by: Uwe Hermann <uwe@hermann-uwe.de>



git-svn-id: svn://svn.coreboot.org/coreboot/trunk@3555 2b7e53f0-3cfb-0310-b3e9-8179ed1497e1

4 files changed, 90 insertions, 103 deletions

diff --git a/payloads/libpayload/i386/timer.c b/payloads/libpayload/i386/timer.c
index 46d21cc6ae..e1a886e302 100644
--- a/payloads/libpayload/i386/timer.c
+++ b/payloads/libpayload/i386/timer.c
@@ -27,8 +27,9 @@
  * SUCH DAMAGE.
  */
 
-/** @file i386/timer.c
- * @brief i386 specific timer routines
+/**
+ * @file i386/timer.c
+ * i386 specific timer routines
  */
 
 #include <libpayload.h>
@@ -36,7 +37,7 @@
 
 /**
  * @ingroup arch
- * Global variable containing the speed of the processor in KHz
+ * Global variable containing the speed of the processor in KHz.
  */
 u32 cpu_khz;
 
@@ -81,8 +82,9 @@ static inline void _delay(unsigned int delta)
 }
 
 /**
- * Delay for a specified number of nanoseconds
- * @param n Number of nanoseconds to delay for
+ * Delay for a specified number of nanoseconds.
+ *
+ * @param n Number of nanoseconds to delay for.
  */
 void ndelay(unsigned int n)
 {
@@ -90,8 +92,9 @@ void ndelay(unsigned int n)
 }
 
 /**
- * Delay for a specified number of microseconds
- * @param n Number of microseconds to delay for
+ * Delay for a specified number of microseconds.
+ *
+ * @param n Number of microseconds to delay for.
  */
 void udelay(unsigned int n)
 {
@@ -99,20 +102,20 @@ void udelay(unsigned int n)
 }
 
 /**
- * Delay for a specified number of milliseconds
- * @param n Number of milliseconds to delay for
+ * Delay for a specified number of milliseconds.
+ *
+ * @param m Number of milliseconds to delay for.
  */
-
 void mdelay(unsigned int m)
 {
 	_delay(m * cpu_khz);
 }
 
 /**
- * Delay for a specified number of seconds
- * @param n Number of seconds to delay for
+ * Delay for a specified number of seconds.
+ *
+ * @param s Number of seconds to delay for.
  */
-
 void delay(unsigned int s)
 {
 	_delay(s * cpu_khz * 1000);
diff --git a/payloads/libpayload/include/libpayload.h b/payloads/libpayload/include/libpayload.h
index cace3ae1da..7b1d5750bf 100644
--- a/payloads/libpayload/include/libpayload.h
+++ b/payloads/libpayload/include/libpayload.h
@@ -27,7 +27,9 @@
  * SUCH DAMAGE.
  */
 
-/** @mainpage
+/**
+ * @mainpage
+ *
  * @section intro Introduction
  * libpayload is a small BSD-licensed static library (a lightweight
  * implementation of common and useful functions) intended to be used
@@ -36,10 +38,8 @@
  * @section example Example
  * Here is an example of a very simple payload:
  * @include sample/hello.c
- *
  */
 
-
 #ifndef _LIBPAYLOAD_H
 #define _LIBPAYLOAD_H
 
@@ -64,12 +64,12 @@
 
 #define RAND_MAX 0x7fffffff
 
-/* Payload information parameters - these are used to pass information
- * to the entity loading the payload
- * Usage:  PAYLOAD_INFO(key, value)
- * Example:  PAYLOAD_INFO(name, "CoreInfo!")
+/*
+ * Payload information parameters - these are used to pass information
+ * to the entity loading the payload.
+ * Usage:   PAYLOAD_INFO(key, value)
+ * Example: PAYLOAD_INFO(name, "CoreInfo!")
  */
-
 #define _pstruct(key) __pinfo_ ##key
 #define PAYLOAD_INFO(key, value)                                        \
 static const char _pstruct(key)[]                                        \
@@ -90,9 +90,7 @@ static const char _pstruct(key)[]                                        \
 #define NVRAM_RTC_FREQ_SELECT    10     /**< RTC Update Status Register */
 #define  NVRAM_RTC_UIP           0x80
 
-/** @struct tm
- *  \brief Broken down time structure
- */
+/** Broken down time structure */
 struct tm {
 	int tm_sec;   /**< Number of seconds after the minute */
 	int tm_min;   /**< Number of minutes after the hour */
@@ -136,7 +134,6 @@ void serial_init(void);
 void serial_putchar(unsigned char c);
 int serial_havechar(void);
 int serial_getchar(void);
-
 void serial_clear(void);
 void serial_start_bold(void);
 void serial_end_bold(void);
@@ -189,7 +186,7 @@ extern int last_putchar;
 /** @} */
 
 /**
- * @defgroup ctype Character Type Functions
+ * @defgroup ctype Character type functions
  * @{
  */
 int isalnum(int c);
@@ -210,14 +207,14 @@ int toupper(int c);
 /** @} */
 
 /**
- * @defgroup ipchecksum IP Checksum Functions
+ * @defgroup ipchecksum IP checksum functions
  * @{
  */
 unsigned short ipchksum(const void *ptr, unsigned long nbytes);
 /** @} */
 
 /**
- * @defgroup malloc Memory Allocation Functions
+ * @defgroup malloc Memory allocation functions
  * @{
  */
 void free(void *ptr);
@@ -227,14 +224,14 @@ void *realloc(void *ptr, size_t size);
 /** @} */
 
 /**
- * @defgroup exec Execution Functions
+ * @defgroup exec Execution functions
  * @{
  */
 int exec(long addr, int argc, char **argv);
 /** @} */
 
 /**
- * @defgroup misc Misc Functions
+ * @defgroup misc Misc functions
  * @{
  */
 int bcd2dec(int b);
@@ -244,11 +241,11 @@ long int labs(long int j);
 long long int llabs(long long int j);
 u8 bin2hex(u8 b);
 u8 hex2bin(u8 h);
-void fatal(const char* msg) __attribute__ ((noreturn));
+void fatal(const char *msg) __attribute__ ((noreturn));
 /** @} */
 
 /**
- * @defgroup memory Memory Manipulation Functions
+ * @defgroup memory Memory manipulation functions
  * @{
  */
 void *memset(void *s, int c, size_t n);
@@ -258,7 +255,7 @@ int memcmp(const void *s1, const void *s2, size_t len);
 /** @} */
 
 /**
- * @defgroup printf Print Functions
+ * @defgroup printf Print functions
  * @{
  */
 int snprintf(char *str, size_t size, const char *fmt, ...);
@@ -270,7 +267,7 @@ int vprintf(const char *fmt, va_list ap);
 /** @} */
 
 /**
- * @defgroup rand Random Number Generator Functions
+ * @defgroup rand Random number generator functions
  * @{
  */
 int rand_r(unsigned int *seed);
@@ -279,7 +276,7 @@ void srand(unsigned int seed);
 /** @} */
 
 /**
- * @defgroup hash Hashing Functions
+ * @defgroup hash Hashing functions
  * @{
  */
 #define SHA1_BLOCK_LENGTH	64
@@ -297,7 +294,7 @@ u8 *sha1(const u8 *data, size_t len, u8 *buf);
 /** @} */
 
 /**
- * @defgroup string String Functions
+ * @defgroup string String functions
  * @{
  */
 size_t strnlen(const char *str, size_t maxlen);
@@ -313,14 +310,11 @@ char *strstr(const char *h, const char *n);
 /** @} */
 
 /**
- * @defgroup time Time Functions
+ * @defgroup time Time functions
  * @{
  */
 
-/** @struct timeval
- * @brief System time structure
- */
-
+/** System time structure */
 struct timeval {
 	time_t tv_sec;       /**< Seconds */
 	suseconds_t tv_usec; /**< Microseconds */
@@ -330,15 +324,13 @@ int gettimeofday(struct timeval *tv, void *tz);
 /** @} */
 
 /**
- * @defgroup lar LAR Functions
+ * @defgroup lar LAR functions
  * @{
  */
 
-/** @struct LAR
- * @brief LAR File Header
- */
+/** LAR file header */
 struct LAR {
-	void * start;   /**< Location of the LAR in memory */
+	void *start;    /**< Location of the LAR in memory */
 	int cindex;     /**< Next file to return in readlar() */
 	int count;      /**< Number of entries in the header cache */
 	int alloc;      /**< Number of slots in the header cache */
@@ -346,16 +338,12 @@ struct LAR {
 	void **headers; /**< Pointer to the header cache */
 };
 
-/** @struct larent
- * @brief A structure representing the next LAR entry
- */
+/** A structure representing the next LAR entry */
 struct larent {
 	u8 name[LAR_MAX_PATHLEN]; /**< The name of the next LAR entry */
 };
 
-/** @struct larstat
- * @brief A structure containing information about a LAR file
- */
+/** A structure containing information about a LAR file */
 struct larstat {
 	u32 len;           /**< Length of the file in the LAR */
 	u32 reallen;       /**< Length of the uncompressed file */
@@ -367,10 +355,7 @@ struct larstat {
 	u64 loadaddress;   /**< Address in memory to put the uncompressed file */
 };
 
-/** @struct LFILE
- * @brief A structure representing a LAR file
- */
-
+/** A structure representing a LAR file */
 struct LFILE {
 	struct LAR *lar;           /**< Pointer to the LAR struct */
 	struct lar_header *header; /**< Pointer to the header struct */
@@ -386,20 +371,20 @@ void rewindlar(struct LAR *lar);
 int larstat(struct LAR *lar, const char *path, struct larstat *buf);
 void *larfptr(struct LAR *lar, const char *filename);
 int lfverify(struct LAR *lar, const char *filename);
-struct LFILE * lfopen(struct LAR *lar, const char *filename);
+struct LFILE *lfopen(struct LAR *lar, const char *filename);
 int lfread(void *ptr, size_t size, size_t nmemb, struct LFILE *stream);
 
-#define SEEK_SET 0 /**@def The seek offset is absolute  */
-#define SEEK_CUR 1 /**@def The seek offset is against the current position */
-#define SEEK_END 2 /**@def The see offset is against the end of the file */
+#define SEEK_SET 0 /**< The seek offset is absolute. */
+#define SEEK_CUR 1 /**< The seek offset is against the current position. */
+#define SEEK_END 2 /**< The seek offset is against the end of the file. */
 
 int lfseek(struct LFILE *stream, long offset, int whence);
 int lfclose(struct LFILE *file);
 /** @} */
 
 /**
- * @defgroup arch Architecture Specific Functions
- * This modules contains global architecture specific functions.
+ * @defgroup arch Architecture specific functions
+ * This module contains global architecture specific functions.
  * All architectures are expected to define these functions.
  * @{
  */
@@ -417,20 +402,18 @@ void delay(unsigned int n);
 #define abort() halt()    /**< Alias for the halt() function */
 
 /**
- * Stops executions and halts the processor.  This function does
- * not return.
+ * Stop execution and halt the processor (this function does not return).
  */
 void halt(void) __attribute__ ((noreturn));
 /** @} */
 
 /**
- * @defgroup readline Readline Functions
- * This interface provides a simple implementation of the standard
- * readline and getline functions.  They are suitable for reading a
- * line of input from the console.
+ * @defgroup readline Readline functions
+ * This interface provides a simple implementation of the standard readline()
+ * and getline() functions. They read a line of input from the console.
  * @{
  */
-char * readline(const char * prompt);
+char *readline(const char *prompt);
 int getline(char *buffer, int len);
 /** @} */
 
diff --git a/payloads/libpayload/libc/readline.c b/payloads/libpayload/libc/readline.c
index 4faf3d7895..01a565a698 100644
--- a/payloads/libpayload/libc/readline.c
+++ b/payloads/libpayload/libc/readline.c
@@ -27,27 +27,27 @@
  * SUCH DAMAGE.
  */
 
-/** @file libc/readline.c
- * @brief Simple readline implementation
+/**
+ * @file libc/readline.c
+ * Simple readline implementation
  */
 
 #include <libpayload.h>
 
-static char * readline_buffer;
+static char *readline_buffer;
 static int readline_bufferlen;
 
 /**
- * @brief Read a line from the terminal and return it
- * @param prompt A prompt to display on the line
- * @return A pointer to the input string
+ * Read a line from the terminal and return it.
+ *
+ * This readline implementation is rather simple, but it does more than the
+ * original readline() because it allows us to have a pre-filled buffer.
+ * To pre-fill the buffer, use the getline() function.
  *
- * Read a line from the terminal and return it.  This readline implementation
- * is rather simple, but it does more than the original readline() because
- * it allows us to have a pre-filled buffer. To pre-fill the buffer, use the
- * getline() function.
+ * @param prompt A prompt to display on the line.
+ * @return A pointer to the input string.
  */
-
-char * readline(const char * prompt)
+char *readline(const char *prompt)
 {
 	char *buffer;
 	int current, ch, nonspace_seen;
@@ -141,7 +141,6 @@ char * readline(const char * prompt)
 		}
 	}
 
-
 out:
 	if (current >= readline_bufferlen)
 		current = readline_bufferlen - 1;
@@ -151,22 +150,23 @@ out:
 }
 
 /**
- * @brief Read a line from the input and store it in a buffer
- * @param prompt A buffer to store the line in
- * @param len Length of the buffer
- * @return The final length of the string
- * This function allows the user to pass a predefined buffer to
- * readline().  The buffer may be filled with a default value
- * which will be displayed by readline and can be edited as normal.
- * The final input string returned by readline will be returned in
+ * Read a line from the input and store it in a buffer.
+ *
+ * This function allows the user to pass a predefined buffer to readline().
+ * The buffer may be filled with a default value which will be displayed by
+ * readline() and can be edited as normal.
+ * The final input string returned by readline() will be returned in
  * the buffer and the function will return the length of the string.
+ *
+ * @param buffer Pointer to a buffer to store the line in.
+ * @param len Length of the buffer.
+ * @return The final length of the string.
  */
-
 int getline(char *buffer, int len)
 {
 	readline_buffer = buffer;
 	readline_bufferlen = len;
 	readline(NULL);
+
 	return strlen(buffer);
 }
-
diff --git a/payloads/libpayload/libc/time.c b/payloads/libpayload/libc/time.c
index b49879b9d8..b47e452e49 100644
--- a/payloads/libpayload/libc/time.c
+++ b/payloads/libpayload/libc/time.c
@@ -27,8 +27,9 @@
  * SUCH DAMAGE.
  */
 
-/** @file libc/time.c
- * @brief General Time Functions
+/**
+ * @file libc/time.c
+ * General time functions
  */
 
 #include <config.h>
@@ -115,18 +116,18 @@ static void gettimeofday_init(void)
 #endif
 
 /**
- * Return the current time broken into a timeval structure
- * @param tv A pointer to a timeval structure
- * @param tz Added for compatability - not used
- * @return 0 for success
+ * Return the current time broken into a timeval structure.
+ *
+ * @param tv A pointer to a timeval structure.
+ * @param tz Added for compatability - not used.
+ * @return 0 for success (this function cannot return non-zero currently).
  */
 int gettimeofday(struct timeval *tv, void *tz)
 {
-	/* Call the gtod init when we need it - this keeps
-	   the code from being included in the binary if we don't
-	   need it
-	*/
-
+	/*
+	 * Call the gtod init when we need it - this keeps the code from
+	 * being included in the binary if we don't need it.
+	 */
 	if (!clock.ticks)
 		gettimeofday_init();