From 3153863567f51c9173227b9cb4375d53e6f3e6ed Mon Sep 17 00:00:00 2001 From: Uwe Hermann Date: Sun, 31 Aug 2008 22:10:35 +0000 Subject: [PATCH] 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 Acked-by: Uwe Hermann git-svn-id: svn://svn.coreboot.org/coreboot/trunk@3555 2b7e53f0-3cfb-0310-b3e9-8179ed1497e1 --- payloads/libpayload/i386/timer.c | 29 ++++---- payloads/libpayload/include/libpayload.h | 95 ++++++++++-------------- payloads/libpayload/libc/readline.c | 46 ++++++------ payloads/libpayload/libc/time.c | 23 +++--- 4 files changed, 90 insertions(+), 103 deletions(-) diff --git a/payloads/libpayload/i386/timer.c b/payloads/libpayload/i386/timer.c index 46d21cc6a..e1a886e30 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 @@ -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 cace3ae1d..7b1d5750b 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 4faf3d789..01a565a69 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 -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 b49879b9d..b47e452e4 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 @@ -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(); -- 2.25.1