Author: uwe Date: 2008-09-01 00:10:35 +0200 (Mon, 01 Sep 2008) New Revision: 3555
Modified: trunk/payloads/libpayload/i386/timer.c trunk/payloads/libpayload/include/libpayload.h trunk/payloads/libpayload/libc/readline.c trunk/payloads/libpayload/libc/time.c Log: 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
Modified: trunk/payloads/libpayload/i386/timer.c =================================================================== --- trunk/payloads/libpayload/i386/timer.c 2008-08-29 09:06:16 UTC (rev 3554) +++ trunk/payloads/libpayload/i386/timer.c 2008-08-31 22:10:35 UTC (rev 3555) @@ -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 @@ }
/** - * 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 @@ }
/** - * 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 @@ }
/** - * 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);
Modified: trunk/payloads/libpayload/include/libpayload.h =================================================================== --- trunk/payloads/libpayload/include/libpayload.h 2008-08-29 09:06:16 UTC (rev 3554) +++ trunk/payloads/libpayload/include/libpayload.h 2008-08-31 22:10:35 UTC (rev 3555) @@ -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 @@ #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_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 @@ /** @} */
/** - * @defgroup ctype Character Type Functions + * @defgroup ctype Character type functions * @{ */ int isalnum(int c); @@ -210,14 +207,14 @@ /** @} */
/** - * @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 @@ /** @} */
/** - * @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 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 @@ /** @} */
/** - * @defgroup printf Print Functions + * @defgroup printf Print functions * @{ */ int snprintf(char *str, size_t size, const char *fmt, ...); @@ -270,7 +267,7 @@ /** @} */
/** - * @defgroup rand Random Number Generator Functions + * @defgroup rand Random number generator functions * @{ */ int rand_r(unsigned int *seed); @@ -279,7 +276,7 @@ /** @} */
/** - * @defgroup hash Hashing Functions + * @defgroup hash Hashing functions * @{ */ #define SHA1_BLOCK_LENGTH 64 @@ -297,7 +294,7 @@ /** @} */
/** - * @defgroup string String Functions + * @defgroup string String functions * @{ */ size_t strnlen(const char *str, size_t maxlen); @@ -313,14 +310,11 @@ /** @} */
/** - * @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 @@ /** @} */
/** - * @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 @@ 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 @@ 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 @@ 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 @@ #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); /** @} */
Modified: trunk/payloads/libpayload/libc/readline.c =================================================================== --- trunk/payloads/libpayload/libc/readline.c 2008-08-29 09:06:16 UTC (rev 3554) +++ trunk/payloads/libpayload/libc/readline.c 2008-08-31 22:10:35 UTC (rev 3555) @@ -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. * - * 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. + * 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 @@ } }
- out: if (current >= readline_bufferlen) current = readline_bufferlen - 1; @@ -151,22 +150,23 @@ }
/** - * @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); } -
Modified: trunk/payloads/libpayload/libc/time.c =================================================================== --- trunk/payloads/libpayload/libc/time.c 2008-08-29 09:06:16 UTC (rev 3554) +++ trunk/payloads/libpayload/libc/time.c 2008-08-31 22:10:35 UTC (rev 3555) @@ -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 @@ #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();