From e530fbe8e25a707f0f22529c365633cba0b5b817 Mon Sep 17 00:00:00 2001 From: Kalle Olavi Niemitalo Date: Fri, 27 Jul 2007 12:35:13 +0300 Subject: [PATCH] Doxygenate src/util/ --- src/osdep/os2/os2.c | 4 +- src/util/base64.c | 12 +++- src/util/bitfield.h | 19 ++++--- src/util/box.h | 4 +- src/util/color.c | 5 +- src/util/color.h | 16 +++--- src/util/conv.c | 40 +++++++------ src/util/conv.h | 74 ++++++++++++------------ src/util/env.c | 11 ++-- src/util/error.c | 3 +- src/util/error.h | 87 +++++++++++++++------------- src/util/fastfind.c | 134 +++++++++++++++++++++++--------------------- src/util/fastfind.h | 35 ++++++------ src/util/file.c | 19 ++++--- src/util/file.h | 41 +++++++------- src/util/hash.c | 32 +++++++---- src/util/hash.h | 6 +- src/util/lists.h | 4 +- src/util/math.h | 11 ++-- src/util/md5.c | 26 +++++---- src/util/md5.h | 8 ++- src/util/memdebug.c | 27 ++++----- src/util/memlist.c | 14 +++-- src/util/memory.c | 10 ++-- src/util/memory.h | 29 ++++++---- src/util/profile.h | 18 +++--- src/util/scanner.c | 8 ++- src/util/scanner.h | 92 +++++++++++++++--------------- src/util/secsave.c | 17 +++--- src/util/secsave.h | 19 ++++--- src/util/string.c | 5 +- src/util/string.h | 100 +++++++++++++++++++-------------- src/util/time.c | 20 ++++--- src/util/time.h | 16 +++--- 34 files changed, 529 insertions(+), 437 deletions(-) diff --git a/src/osdep/os2/os2.c b/src/osdep/os2/os2.c index 8812b4bdc..20d6d9f4c 100644 --- a/src/osdep/os2/os2.c +++ b/src/osdep/os2/os2.c @@ -436,9 +436,9 @@ resize_window(int x, int y, int old_width, int old_height) #if 0 unsigned char cmdline[16]; sprintf(cmdline, "mode "); - snprint(cmdline + 5, 5, x); + ulongcat(cmdline + 5, NULL, x, 5, 0); strcat(cmdline, ","); - snprint(cmdline + strlen(cmdline), 5, y); + ulongcat(cmdline + strlen(cmdline), NULL, y, 5, 0); #endif return 0; } diff --git a/src/util/base64.c b/src/util/base64.c index fc777174e..8046cc9c8 100644 --- a/src/util/base64.c +++ b/src/util/base64.c @@ -1,4 +1,5 @@ -/* Base64 encode/decode implementation. */ +/** Base64 encode/decode implementation. + * @file */ #ifdef HAVE_CONFIG_H #include "config.h" @@ -75,8 +76,13 @@ base64_decode(register unsigned char *in) return base64_decode_bin(in, strlen(in), NULL); } -/* base64_decode: @in string to decode - * returns the string decoded (must be freed by the caller) */ +/** Decode a Base64 string. + * @param in Input Base64 string + * @param inlen Length of @a in, in bytes + * @param[out] outlen Length of decoded string + * + * @returns the string decoded (must be freed by the caller) + * or NULL if an error occurred (syntax error or out of memory) */ unsigned char * base64_decode_bin(register unsigned char *in, int inlen, int *outlen) { diff --git a/src/util/bitfield.h b/src/util/bitfield.h index 0c8d7cd12..f1d258162 100644 --- a/src/util/bitfield.h +++ b/src/util/bitfield.h @@ -7,9 +7,10 @@ /* Bitfield operations: */ +/** A vector of bits. The size is fixed at initialization time. */ struct bitfield { - unsigned int bitsize; /* Number of bits in the bitfield. */ - unsigned char bits[1]; /* Strawberry bitfields forever. */ + unsigned int bitsize; /**< Number of bits in the bitfield. */ + unsigned char bits[1]; /**< Strawberry bitfields forever. */ }; #define foreach_bitfield_set(bit, bitfield) \ @@ -31,7 +32,7 @@ struct bitfield { /* +7 to round up to nearest byte. */ #define get_bitfield_byte_size(bits) ((size_t) (((bits) + 7) / 8)) -/* Allocate a bitfield containing @bits number of bits. */ +/** Allocate a bitfield containing @a bits number of bits. */ static inline struct bitfield * init_bitfield(size_t bits) { @@ -44,7 +45,7 @@ init_bitfield(size_t bits) return bitfield; } -/* Update @bitfield with the @size bytes from the @bits string in @bits. */ +/** Update @a bitfield with the @a bytesize bytes from the bit string in @a bits. */ static inline void copy_bitfield(struct bitfield *bitfield, const unsigned char *bits, unsigned int bytesize) @@ -54,7 +55,7 @@ copy_bitfield(struct bitfield *bitfield, memcpy(bitfield->bits, bits, bytesize); } -/* Test whether @bit is set in the bitfield. */ +/** Test whether @a bit is set in the @a bitfield. */ static inline int test_bitfield_bit(struct bitfield *bitfield, unsigned int bit) { @@ -69,7 +70,7 @@ test_bitfield_bit(struct bitfield *bitfield, unsigned int bit) return !!(bitfield->bits[byte_offset] & bit_offset); } -/* Set @bit in the bitfield. */ +/** Set @a bit in the @a bitfield. */ static inline void set_bitfield_bit(struct bitfield *bitfield, unsigned int bit) { @@ -84,7 +85,7 @@ set_bitfield_bit(struct bitfield *bitfield, unsigned int bit) bitfield->bits[byte_offset] |= bit_offset; } -/* Unset @bit in the bitfield. */ +/** Unset @a bit in the @a bitfield. */ static inline void clear_bitfield_bit(struct bitfield *bitfield, unsigned int bit) { @@ -99,6 +100,7 @@ clear_bitfield_bit(struct bitfield *bitfield, unsigned int bit) bitfield->bits[byte_offset] &= ~bit_offset; } +/** Count the set bits in @a bitfield. */ static inline unsigned int get_bitfield_set_count(struct bitfield *bitfield) { @@ -110,6 +112,7 @@ get_bitfield_set_count(struct bitfield *bitfield) return count; } +/** Count the unset bits in @a bitfield. */ static inline unsigned int get_bitfield_cleared_count(struct bitfield *bitfield) { @@ -121,6 +124,7 @@ get_bitfield_cleared_count(struct bitfield *bitfield) return count; } +/** Check whether all bits of @a bitfield are set. */ static inline unsigned int bitfield_is_set(struct bitfield *bitfield) { @@ -132,6 +136,7 @@ bitfield_is_set(struct bitfield *bitfield) return 1; } +/** Check whether all bits of @a bitfield are unset. */ static inline unsigned int bitfield_is_cleared(struct bitfield *bitfield) { diff --git a/src/util/box.h b/src/util/box.h index dcb572745..edcc4e008 100644 --- a/src/util/box.h +++ b/src/util/box.h @@ -1,6 +1,7 @@ #ifndef EL__UTIL_BOX_H #define EL__UTIL_BOX_H +/** A rectangular part of a drawing surface, such as the screen. */ struct box { int x; int y; @@ -28,7 +29,8 @@ col_is_in_box(struct box *box, int x) return (x >= box->x && x < box->x + box->width); } -/* Mainly intended for use with double-width characters. */ +/** Check whether a span of columns is in @a box. + * Mainly intended for use with double-width characters. */ static inline int colspan_is_in_box(struct box *box, int x, int span) { diff --git a/src/util/color.c b/src/util/color.c index 8aa0b01c6..5b7872a59 100644 --- a/src/util/color.c +++ b/src/util/color.c @@ -1,4 +1,5 @@ -/* Color parser */ +/** Color parser + * @file */ #ifdef HAVE_CONFIG_H #include "config.h" @@ -40,7 +41,7 @@ colors_list_reset(void) internal_pointer = color_specs; } -/* Returns a pointer to a struct that contains +/** Returns a pointer to a struct that contains * current key and data pointers and increment * internal pointer. * It returns NULL when key is NULL. */ diff --git a/src/util/color.h b/src/util/color.h index 7fb6c46e9..80ad9f8b7 100644 --- a/src/util/color.h +++ b/src/util/color.h @@ -10,21 +10,23 @@ struct color_pair { #define INIT_COLOR_PAIR(bg, fg) { bg, fg } -/* Decode the color string. */ -/* The color string can either contain '#FF0044' style declarations or +/** Decode the color string. + * The color string can either contain '@#FF0044' style declarations or * color names. */ int decode_color(unsigned char *str, int slen, color_T *color); -/* Returns a string containing the color info. If no ``English'' name can be - * found the hex color (#rrggbb) is returned in the given buffer. */ +/** Returns a string containing the color info. If no 'English' name can be + * found the hex color (@#rrggbb) is returned in the given buffer. */ const unsigned char *get_color_string(color_T color, unsigned char hexcolor[8]); -/* Translate rgb color to string in #rrggbb format. str should be a pointer to - * a 8 bytes memory space. */ +/** Translate rgb color to string in @#rrggbb format. + * @a str should be a pointer to an 8 bytes memory space. */ void color_to_string(color_T color, unsigned char str[8]); -/* Fastfind lookup management. */ +/** @name Fastfind lookup management. + * @{ */ void init_colors_lookup(void); void free_colors_lookup(void); +/** @} */ #endif diff --git a/src/util/conv.c b/src/util/conv.c index 13c27f69a..bee6a587b 100644 --- a/src/util/conv.c +++ b/src/util/conv.c @@ -1,4 +1,5 @@ -/* Conversion functions */ +/** Conversion functions + * @file */ #ifdef HAVE_CONFIG_H #include "config.h" @@ -22,30 +23,33 @@ -/* This function takes string @s and stores the @number (of a result width - * @width) in string format there, starting at position [*@slen]. If the number - * would take more space than @width, it is truncated and only the _last_ - * digits of it are inserted to the string. If the number takes less space than - * @width, it is padded by @fillchar from left. - * @base defined which base should be used (10, 16, 8, 2, ...) - * @upper selects either hexa uppercased chars or lowercased chars. +/** This function takes string @a s and stores the @a number (of a + * result width @a width) in string format there, starting at position + * [*@a slen]. If the number would take more space than @a width, it + * is truncated and only the _last_ digits of it are inserted to the + * string. If the number takes less space than @a width, it is padded + * by @a fillchar from left. + * @a base defined which base should be used (10, 16, 8, 2, ...) + * @a upper selects either hexa uppercased chars or lowercased chars. * - * A NUL char is always added at the end of the string. @s must point to a - * sufficiently large memory space, at least *@slen + @width + 1. + * A NUL char is always added at the end of the string. @a s must point + * to a sufficiently large memory space, at least *@a slen + @a width + 1. * * Examples: * + * @code * elinks_ulongcat(s, NULL, 12345, 4, 0, 10, 0) : s = "2345" * elinks_ulongcat(s, NULL, 255, 4, '*', 16, 1) : s = "**FF" * elinks_ulongcat(s, NULL, 123, 5, '0', 10, 0) : s = "00123" + * @endcode * * Note that this function exists to provide a fast and efficient, however * still quite powerful alternative to sprintf(). It is optimized for speed and * is *MUCH* faster than sprintf(). If you can use it, use it ;-). But do not * get too enthusiastic, do not use it in cases where it would break i18n. - */ -/* The function returns 0 if OK or width needed for the whole number to fit - * there, if it had to be truncated. A negative value signs an error. */ + * + * @returns 0 if OK or width needed for the whole number to fit there, + * if it had to be truncated. A negative value signs an error. */ int inline elinks_ulongcat(unsigned char *s, unsigned int *slen, unsigned long number, unsigned int width, @@ -103,7 +107,7 @@ elinks_ulongcat(unsigned char *s, unsigned int *slen, return ret; } -/* Similar to elinks_ulongcat() but for long number. */ +/** Similar to elinks_ulongcat() but for @c long number. */ int inline elinks_longcat(unsigned char *s, unsigned int *slen, long number, unsigned int width, @@ -469,8 +473,8 @@ month2num(const unsigned char *str) } } -/* This function drops control chars, nbsp char and limit the number of consecutive - * space chars to one. It modifies its argument. */ +/** This function drops control chars, nbsp char and limit the number + * of consecutive space chars to one. It modifies its argument. */ void clr_spaces(unsigned char *str) { @@ -492,7 +496,7 @@ clr_spaces(unsigned char *str) *dest = '\0'; } -/* Replace invalid chars in @title with ' ' and trim all starting/ending +/** Replace invalid chars in @a title with ' ' and trim all starting/ending * spaces. */ void sanitize_title(unsigned char *title) @@ -508,7 +512,7 @@ sanitize_title(unsigned char *title) trim_chars(title, ' ', NULL); } -/* Returns 0 if @url contains invalid chars, 1 if ok. +/** Returns 0 if @a url contains invalid chars, 1 if ok. * It trims starting/ending spaces. */ int sanitize_url(unsigned char *url) diff --git a/src/util/conv.h b/src/util/conv.h index 8f5c2b127..212acf8e7 100644 --- a/src/util/conv.h +++ b/src/util/conv.h @@ -17,23 +17,23 @@ is_safe_in_shell(unsigned char c) long strtolx(unsigned char *, unsigned char **); -/* Convert a decimal number to hexadecimal (lowercase) (0 <= a <= 15). */ +/** Convert a decimal number to hexadecimal (lowercase) (0 <= @a a <= 15). */ static inline unsigned char hx(register int a) { return a >= 10 ? a + 'a' - 10 : a + '0'; } -/* Convert a decimal number to hexadecimal (uppercase) (0 <= a <= 15). */ +/** Convert a decimal number to hexadecimal (uppercase) (0 <= @a a <= 15). */ static inline unsigned char Hx(register int a) { return a >= 10 ? a + 'A' - 10 : a + '0'; } -/* Convert an hexadecimal char ([0-9][a-z][A-Z]) to - * its decimal value (0 <= result <= 15) - * returns -1 if parameter is not an hexadecimal char. */ +/** Convert an hexadecimal char ([0-9][a-z][A-Z]) to + * its decimal value (0 <= result <= 15). + * Returns -1 if parameter is not an hexadecimal char. */ static inline int unhx(register unsigned char a) { @@ -51,21 +51,23 @@ struct string *add_duration_to_string(struct string *string, long seconds); struct string *add_timeval_to_string(struct string *string, timeval_T *timeval); #ifdef HAVE_STRFTIME -/* Uses strftime() to add @fmt time format to @string. If @time is NULL - * time(NULL) will be used. */ +/** Uses strftime() to format @a time according to @a format and adds + * the result to @a string. If @a time is NULL, time(NULL) will be + * used. */ struct string *add_date_to_string(struct string *string, const unsigned char *format, const time_t *time); #endif -/* Encoders: */ -/* They encode and add to the string. This way we don't need to first allocate +/** @name Encoders: + * They encode and add to the string. This way we don't need to first allocate * and encode a temporary string, add it and then free it. Can be used as - * backends for encoder. */ + * backends for encoder. + * @{ */ -/* A simple generic encoder. Should maybe take @replaceable as a string so we - * could also use it for adding shell safe strings. */ +/** A simple generic encoder. Should maybe take @a replaceable as a + * string so we could also use it for adding shell safe strings. */ struct string * add_string_replace(struct string *string, unsigned char *src, int len, unsigned char replaceable, unsigned char replacement); @@ -73,36 +75,37 @@ add_string_replace(struct string *string, unsigned char *src, int len, #define add_optname_to_string(str, src, len) \ add_string_replace(str, src, len, '.', '*') -/* Maybe a bad name but it is actually the real name, but you may also think of - * it as adding the decoded option name. */ +/** Maybe a bad name but it is actually the real name, but you may + * also think of it as adding the decoded option name. */ #define add_real_optname_to_string(str, src, len) \ add_string_replace(str, src, len, '*', '.') -/* Convert reserved chars to html &#xx;. This function copies bytes +/** Convert reserved chars to html @&@#xx;. This function copies bytes * 0x80...0xFF unchanged, so the caller should ensure that the * resulting HTML will be parsed with the same charset as the original - * string. (This function cannot use the   syntax for non-ASCII, + * string. (This function cannot use the @&@#160; syntax for non-ASCII, * because HTML wants Unicode numbers there and this function does not * know the charset of the input data.) */ struct string *add_html_to_string(struct string *string, const unsigned char *html, int htmllen); -/* Convert reserved or non-ASCII chars to html &#xx;. The resulting +/** Convert reserved or non-ASCII chars to html @&@#xx;. The resulting * string can be correctly parsed in any charset where bytes * 0x20...0x7E match ASCII. */ struct string *add_cp_html_to_string(struct string *string, int src_codepage, const unsigned char *html, int htmllen); -/* Escapes \ and " with a \ */ +/** Escapes @\ and " with a @\ */ struct string *add_quoted_to_string(struct string *string, const unsigned char *q, int qlen); -/* Adds ', |len| bytes of |src| with all single-quotes converted to '\'', - * and ' to |string|. */ +/** Adds ', @a len bytes of @a src with all single-quotes converted to '\'', + * and ' to @a string. */ struct string *add_shell_quoted_to_string(struct string *string, unsigned char *src, int len); /* Escapes non shell safe chars with '_'. */ struct string *add_shell_safe_to_string(struct string *string, unsigned char *cmd, int cmdlen); +/** @} */ /* These are fast functions to convert integers to string, or to hexadecimal string. */ @@ -115,7 +118,7 @@ int elinks_longcat(unsigned char *s, unsigned int *slen, long number, unsigned int upper); /* Type casting is enforced, to shorten calls. --Zas */ -/* unsigned long to decimal string */ +/** unsigned long to decimal string */ #define ulongcat(s, slen, number, width, fillchar) \ elinks_ulongcat((unsigned char *) (s), \ (unsigned int *) (slen), \ @@ -125,7 +128,7 @@ int elinks_longcat(unsigned char *s, unsigned int *slen, long number, (unsigned int) 10, \ (unsigned int) 0) -/* signed long to decimal string */ +/** signed long to decimal string */ #define longcat(s, slen, number, width, fillchar) \ elinks_longcat((unsigned char *) (s), \ (unsigned int *) (slen), \ @@ -135,7 +138,7 @@ int elinks_longcat(unsigned char *s, unsigned int *slen, long number, (unsigned int) 10, \ (unsigned int) 0) -/* unsigned long to hexadecimal string */ +/** unsigned long to hexadecimal string */ #define ulonghexcat(s, slen, number, width, fillchar, upper) \ elinks_ulongcat((unsigned char *) (s), \ (unsigned int *) (slen), \ @@ -146,19 +149,15 @@ int elinks_longcat(unsigned char *s, unsigned int *slen, long number, (unsigned int) (upper)) -/* XXX: Compatibility only. Remove these at some time. --Zas */ -#define snprint(str, len, num) ulongcat(str, NULL, num, len, 0); -#define snzprint(str, len, num) longcat(str, NULL, num, len, 0); - -/* Return 0 if starting with jan, 11 for dec, -1 for failure. - * @month must be a lowercased string. */ +/** Return 0 if starting with jan, 11 for dec, -1 for failure. + * @a month must be a lowercased string. */ int month2num(const unsigned char *month); #include -/* Trim starting and ending chars equal to @c in string @s. - * If @len != NULL, it stores new string length in pointed integer. - * It returns @s for convenience. */ +/** Trim starting and ending chars equal to @a c in string @a s. + * If @a len != NULL, it stores new string length in pointed integer. + * It returns @a s for convenience. */ static inline unsigned char * trim_chars(unsigned char *s, unsigned char c, int *len) { @@ -174,7 +173,8 @@ trim_chars(unsigned char *s, unsigned char c, int *len) return s; } -/* Convert uppercase letters in @string with the given @length to lowercase. */ +/** Convert uppercase letters in @a string with the given @a length to + * lowercase. */ static inline void convert_to_lowercase(unsigned char *string, int length) { @@ -183,15 +183,15 @@ convert_to_lowercase(unsigned char *string, int length) string[length] = tolower(string[length]); } -/* This function drops control chars, nbsp char and limit the number of consecutive - * space chars to one. It modifies its argument. */ +/** This function drops control chars, nbsp char and limit the number + * of consecutive space chars to one. It modifies its argument. */ void clr_spaces(unsigned char *str); -/* Replace invalid chars in @title with ' ' and trim all starting/ending +/** Replace invalid chars in @a title with ' ' and trim all starting/ending * spaces. */ void sanitize_title(unsigned char *title); -/* Returns 0 if @url contains invalid chars, 1 if ok. +/** Returns 0 if @a url contains invalid chars, 1 if ok. * It trims starting/ending spaces. */ int sanitize_url(unsigned char *url); diff --git a/src/util/env.c b/src/util/env.c index 6a948a1ca..d9bc42c8f 100644 --- a/src/util/env.c +++ b/src/util/env.c @@ -1,4 +1,5 @@ -/* Environment variables handling */ +/** Environment variables handling + * @file */ #ifdef HAVE_CONFIG_H #include "config.h" @@ -16,11 +17,11 @@ #include "util/memory.h" #include "util/string.h" -/* Set @name environment variable to @value or a substring of it: +/** Set @a name environment variable to @a value or a substring of it: * On success, it returns 0. - * If @value is NULL and on error, it returns -1. - * If @length >= 0 and smaller than true @value length, it will - * set @name to specified substring of @value. + * If @a value is NULL and on error, it returns -1. + * If @a length >= 0 and smaller than true @a value length, it will + * set @a name to specified substring of @a value. */ int env_set(unsigned char *name, unsigned char *value, int length) diff --git a/src/util/error.c b/src/util/error.c index 34e4c88f1..f3a6f3e94 100644 --- a/src/util/error.c +++ b/src/util/error.c @@ -1,4 +1,5 @@ -/* Error handling and debugging stuff */ +/** Error handling and debugging stuff + * @file */ #ifndef _GNU_SOURCE #define _GNU_SOURCE /* Needed for vasprintf() */ diff --git a/src/util/error.h b/src/util/error.h index a97c921b8..0a8867f1d 100644 --- a/src/util/error.h +++ b/src/util/error.h @@ -1,26 +1,27 @@ -#ifndef EL__UTIL_ERROR_H -#define EL__UTIL_ERROR_H - - -/* Here you will found a chunk of functions useful for error states --- from +/** Error handling and debugging stuff + * @file + * + * Here you will found a chunk of functions useful for error states --- from * reporting of various problems to generic error tests/workarounds to some * tools to be used when you got into an error state already. Some of the * functions are also useful for debugging. */ +#ifndef EL__UTIL_ERROR_H +#define EL__UTIL_ERROR_H /* This errfile thing is needed, as we don't have var-arg macros in standart, * only as gcc extension :(. */ extern int errline; extern const unsigned char *errfile; -/* @DBG(format_string) is used for printing of debugging information. It +/** @c DBG(format_string) is used for printing of debugging information. It * should not be used anywhere in the official codebase (although it is often * lying there commented out, as it may get handy). */ #undef DBG #define DBG errfile = __FILE__, errline = __LINE__, elinks_debug void elinks_debug(unsigned char *fmt, ...); -/* @WDBG(format_string) is used for printing of debugging information, akin +/** @c WDBG(format_string) is used for printing of debugging information, akin * to DBG(). However, it sleep(1)s, therefore being useful when it is going * to be overdrawn or so. It should not be used anywhere in the official * codebase (although it is often lying there commented out, as it may get @@ -29,7 +30,7 @@ void elinks_debug(unsigned char *fmt, ...); #define WDBG errfile = __FILE__, errline = __LINE__, elinks_wdebug void elinks_wdebug(unsigned char *fmt, ...); -/* @ERROR(format_string) is used to report non-fatal unexpected errors during +/** @c ERROR(format_string) is used to report non-fatal unexpected errors during * the ELinks run. It tries to (not that agressively) draw user's attention to * the error, but never dumps core or so. Note that this should be used only in * cases of non-severe internal inconsistences etc, never as an indication of @@ -39,7 +40,7 @@ void elinks_wdebug(unsigned char *fmt, ...); #define ERROR errfile = __FILE__, errline = __LINE__, elinks_error void elinks_error(unsigned char *fmt, ...); -/* @INTERNAL(format_string) is used to report fatal errors during the ELinks +/** @c INTERNAL(format_string) is used to report fatal errors during the ELinks * run. It tries to draw user's attention to the error and dumps core if ELinks * is running in the CONFIG_DEBUG mode. */ #undef INTERNAL @@ -47,7 +48,7 @@ void elinks_error(unsigned char *fmt, ...); void elinks_internal(unsigned char *fmt, ...); -/* @usrerror(format_string) is used to report user errors during a peaceful +/** @c usrerror(format_string) is used to report user errors during a peaceful * ELinks run. It does not belong to the family above - it doesn't print code * location, beep nor sleep, it just wraps around fprintf(stderr, "...\n");. */ void usrerror(unsigned char *fmt, ...); @@ -55,16 +56,18 @@ void usrerror(unsigned char *fmt, ...); #ifdef HAVE_VARIADIC_MACROS #ifdef CONFIG_DEBUG -/* The LOG_*() macros can be used to log to a file, however, by default log +/** The @c LOG_*() macros can be used to log to a file, however, by default log * messages are written to stderr. Set the following environment variables * to configure the log behavior: * - * ELINKS_LOG - The path to the log file, it is opened for appending - * ELINKS_MSG - A comma separated list containing "error", "warn", - * "info" and/or "debug" which can be used to limit - * what messages to emit to the log. - * ELINKS_FILES - A comma separated list of which files names to - * emit log messages from. + *
+ *
ELINKS_LOG
The path to the log file, it is opened for appending + *
ELINKS_MSG
A comma separated list containing "error", "warn", + * "info" and/or "debug" which can be used to limit + * what messages to emit to the log. + *
ELINKS_FILES
A comma separated list of which files names to + * emit log messages from. + *
*/ void elinks_log(unsigned char *msg, unsigned char *file, int line, @@ -91,10 +94,10 @@ elinks_log(unsigned char *msg, unsigned char *file, int line, -/* This is our smart assert(). It is basically equivalent to if (x) INTERNAL(), +/** This is our smart assert(). It is basically equivalent to if (x) INTERNAL(), * but it generates a uniform message and mainly does not do the test if we are * supposed to be lightning fast. Use it, use it a lot! And never forget the - * recovery path, see below if_assert_failed. */ + * recovery path, see below ::if_assert_failed. */ #undef assert #ifdef CONFIG_FASTMEM @@ -107,7 +110,7 @@ do { if (!assert_failed && (assert_failed = !(x))) { \ #endif -/* This is extended assert() version, it can print additional user-specified +/** This is extended assert() version, it can print additional user-specified * message. Quite useful not only to detect that _something_ is wrong, but also * _how_ wrong is it ;-). Note that the format string must always be a regular * string, not a variable reference. Also, be careful _what_ will you attempt @@ -152,29 +155,31 @@ void elinks_assertm(int x, unsigned char *fmt, ...) #endif /* HAVE_VARIADIC_MACROS */ -/* To make recovery path possible (assertion failed may not mean end of the +/** Whether an assertion has failed and the failure has not yet been handled. + * To make recovery path possible (assertion failed may not mean end of the * world, the execution goes on if we're outside of CONFIG_DEBUG and CONFIG_FASTMEM), - * @assert_failed is set to true if the last assert() failed, otherwise it's + * @c assert_failed is set to true if the last assert() failed, otherwise it's * zero. Note that you must never change assert_failed value, sorry guys. * - * You should never test assert_failed directly anyway. Use if_assert_failed + * You should never test @c assert_failed directly anyway. Use ::if_assert_failed * instead, it will attempt to hint compiler to optimize out the recovery path * if we're CONFIG_FASTMEM. So it should go like: * + * @code * assertm(1 == 1, "The world's gonna blow up!"); - * if_assert_failed { schedule_time_machine(); return; } */ - -/* In-depth explanation: this restriction is here because in the CONFIG_FASTMEM mode, - * assert_failed is initially initialized to zero and then not ever touched + * if_assert_failed { schedule_time_machine(); return; } + * @endcode + * + * In-depth explanation: this restriction is here because in the CONFIG_FASTMEM mode, + * @c assert_failed is initially initialized to zero and then not ever touched * anymore. So if you change it to non-zero failure, your all further recovery * paths will get hit (and since developers usually don't test CONFIG_FASTMEM mode * extensively...). So better don't mess with it, even if you would do that * with awareness of this fact. We don't want to iterate over tens of spots all * over the code when we change one detail regarding CONFIG_FASTMEM operation. * - * This is not that actual after introduction of if_assert_failed, but it's + * This is not that actual after introduction of ::if_assert_failed, but it's * a safe recommendation anyway, so... ;-) */ - extern int assert_failed; #undef if_assert_failed @@ -186,17 +191,18 @@ extern int assert_failed; -/* This will print some fancy message, version string and possibly do something - * else useful. Then, it will dump core. */ +/** This will print some fancy message, version string and possibly do + * something else useful. Then, it will dump core. */ #ifdef CONFIG_DEBUG void force_dump(void); #endif -/* This function does nothing, except making compiler not to optimize certains +/** This function does nothing, except making compiler not to optimize certains * spots of code --- this is useful when that particular optimization is buggy. - * So we are just workarounding buggy compilers. */ -/* This function should be always used only in context of compiler version + * So we are just workarounding buggy compilers. + * + * This function should be always used only in context of compiler version * specific macros. */ void do_not_optimize_here(void *x); @@ -219,11 +225,12 @@ void do_not_optimize_here(void *x); #endif -/* This function dumps backtrace (or whatever similiar it founds on the stack) - * nicely formatted and with symbols resolved to @f. When @trouble is set, it - * tells it to be extremely careful and not use dynamic memory allocation - * functions etc (useful in SIGSEGV handler etc). */ -/* Note that this function just calls system-specific backend provided by the +/** This function dumps backtrace (or whatever similar it founds on the stack) + * nicely formatted and with symbols resolved to @a f. When @a trouble is set, + * it tells it to be extremely careful and not use dynamic memory allocation + * functions etc (useful in SIGSEGV handler etc). + * + * Note that this function just calls system-specific backend provided by the * libc, so it is available only on some systems. CONFIG_BACKTRACE is defined * if it is available on yours. */ #ifdef CONFIG_BACKTRACE @@ -231,7 +238,7 @@ void do_not_optimize_here(void *x); void dump_backtrace(FILE *f, int trouble); #endif -/* This is needed for providing info about features when dumping core */ +/** This is needed for providing info about features when dumping core */ extern unsigned char full_static_version[1024]; #endif diff --git a/src/util/fastfind.c b/src/util/fastfind.c index 3ee3bb5f1..9279dc590 100644 --- a/src/util/fastfind.c +++ b/src/util/fastfind.c @@ -1,4 +1,57 @@ -/* Very fast search_keyword_in_list. */ +/** Very fast search_keyword_in_list. + * @file + * + * + * It replaces bsearch() + strcasecmp() + callback + ... + * + * Following conditions should be met: + * + * - list keys are C strings. + * - keys should not be greater than 255 characters, and optimally < 20 + * characters. It can work with greater keys but then memory usage will + * grow a lot. + * - each key must be unique and non empty. + * - list do not have to be ordered. + * - total number of unique characters used in all keys should be <= 128 + * - idealy total number of keys should be <= 512 (but see below) + * + * (c) 2003 Laurent MONIN (aka Zas) + * Feel free to do whatever you want with that code. + * + * + * These routines use a tree search. First, a big tree is composed from the + * keys on input. Then, when searching we just go through the tree. If we will + * end up on an 'ending' node, we've got it. + * + * Hm, okay. For keys { 'head', 'h1', 'body', 'bodyrock', 'bodyground' }, it + * would look like: + * + * @verbatim + * [root] + * b h + * o e 1 + * d a + * Y D + * g r + * r o + * o c + * u K + * D + * @endverbatim + * + * (the ending nodes are upcased just for this drawing, not in real) + * + * To optimize this for speed, leafs of nodes are organized in per-node arrays + * (so-called 'leafsets'), indexed by symbol value of the key's next character. + * But to optimize that for memory, we first compose own alphabet consisting + * only from the chars we ever use in the key strings. fastfind_info.uniq_chars + * holds that alphabet and fastfind_info.idxtab is used to translate between it + * and ASCII. + * + * Tree building: O((L+M)*N) + * (L: mean key length, M: alphabet size, + * N: number of items). + * String lookup: O(N) (N: string length). */ #ifdef HAVE_CONFIG_H #include "config.h" @@ -17,61 +70,12 @@ #ifdef USE_FASTFIND -/* It replaces bsearch() + strcasecmp() + callback + ... - * - * Following conditions should be met: - * - * - list keys are C strings. - * - keys should not be greater than 255 characters, and optimally < 20 - * characters. It can work with greater keys but then memory usage will - * grow a lot. - * - each key must be unique and non empty. - * - list do not have to be ordered. - * - total number of unique characters used in all keys should be <= 128 - * - idealy total number of keys should be <= 512 (but see below) - * - * (c) 2003 Laurent MONIN (aka Zas) - * Feel free to do whatever you want with that code. */ - - -/* These routines use a tree search. First, a big tree is composed from the - * keys on input. Then, when searching we just go through the tree. If we will - * end up on an 'ending' node, we've got it. - * - * Hm, okay. For keys { 'head', 'h1', 'body', 'bodyrock', 'bodyground' }, it - * would look like: - * - * [root] - * b h - * o e 1 - * d a - * Y D - * g r - * r o - * o c - * u K - * D - * - * (the ending nodes are upcased just for this drawing, not in real) - * - * To optimize this for speed, leafs of nodes are organized in per-node arrays - * (so-called 'leafsets'), indexed by symbol value of the key's next character. - * But to optimize that for memory, we first compose own alphabet consisting - * only from the chars we ever use in the key strings. @uniq_chars holds that - * alphabet and @idxtab is used to translate between it and ASCII. - * - * Tree building: O((L+M)*N) - * (L: mean key length, M: alphabet size, - * N: number of items). - * String lookup: O(N) (N: string length). */ - - -/* Define it to generate performance and memory usage statistics to stderr. */ +/** Define it to generate performance and memory usage statistics to stderr. */ #if 0 #define DEBUG_FASTFIND #endif -/* Define whether to use 32 or 64 bits per compressed element. */ +/** Define whether to use 32 or 64 bits per compressed element. */ #if 1 #define USE_32_BITS #endif @@ -114,16 +118,16 @@ #endif struct ff_node { - /* End leaf -> p is significant */ + /** End leaf -> p is significant */ unsigned int e:END_LEAF_BITS; - /* Compressed */ + /** Compressed */ unsigned int c:COMPRESSED_BITS; - /* Index in pointers */ + /** Index in pointers */ unsigned int p:POINTER_INDEX_BITS; - /* Index in leafsets */ + /** Index in leafsets */ unsigned int l:LEAFSET_INDEX_BITS; }; @@ -141,7 +145,7 @@ struct ff_node_c { unsigned int p:POINTER_INDEX_BITS; unsigned int l:LEAFSET_INDEX_BITS; - /* Index of char when compressed. */ + /** Index of char when compressed. */ unsigned int ch:COMP_CHAR_INDEX_BITS; }; @@ -212,7 +216,7 @@ struct fastfind_info { } while (0) #define FF_DBG_comment(x, str) do { (x)->debug.comment = empty_string_or_(str); } while (0) -/* Update search stats. */ +/** Update search stats. */ static void FF_DBG_search_stats(struct fastfind_info *info, int key_len) { @@ -222,7 +226,7 @@ FF_DBG_search_stats(struct fastfind_info *info, int key_len) info->debug.itertmp = info->debug.iterations; } -/* Dump all stats. */ +/** Dump all stats. */ static void FF_DBG_dump_stats(struct fastfind_info *info) { @@ -296,7 +300,7 @@ init_fastfind(struct fastfind_index *index, enum fastfind_flags flags) return info; } -/* Return 1 on success, 0 on allocation failure */ +/** @returns 1 on success, 0 on allocation failure */ static int alloc_ff_data(struct fastfind_info *info) { @@ -315,7 +319,7 @@ alloc_ff_data(struct fastfind_info *info) return 1; } -/* Add pointer and its key length to correspondant arrays, incrementing +/** Add pointer and its key length to correspondant arrays, incrementing * internal counter. */ static void add_to_ff_data(void *p, int key_len, struct fastfind_info *info) @@ -327,7 +331,7 @@ add_to_ff_data(void *p, int key_len, struct fastfind_info *info) data->keylen = key_len; } -/* Return 1 on success, 0 on allocation failure */ +/** @returns 1 on success, 0 on allocation failure */ static int alloc_leafset(struct fastfind_info *info) { @@ -542,7 +546,7 @@ return_error: #undef ifcase -/* This macro searchs for the key in indexed list */ +/** This macro searchs for the key in indexed list */ #define FF_SEARCH(what) do { \ int i; \ \ @@ -729,14 +733,14 @@ struct list list[] = { struct list *internal_pointer; -/* Reset internal list pointer */ +/** Reset internal list pointer */ void reset_list(void) { internal_pointer = list; } -/* Returns a pointer to a struct that contains +/** Returns a pointer to a struct that contains * current key and data pointers and increment * internal pointer. * It returns NULL when key is NULL. */ diff --git a/src/util/fastfind.h b/src/util/fastfind.h index 4f50ea3d6..d81c9cfa2 100644 --- a/src/util/fastfind.h +++ b/src/util/fastfind.h @@ -1,7 +1,7 @@ #ifndef EL__UTIL_FASTFIND_H #define EL__UTIL_FASTFIND_H -/* Whether to use these routines or not. */ +/** Whether to use these routines or not. */ #ifndef CONFIG_SMALL #define USE_FASTFIND 1 #else @@ -17,39 +17,40 @@ struct fastfind_key_value { enum fastfind_flags { FF_NONE = 0, - FF_CASE_AWARE = 1, /* honour case when comparing */ - FF_COMPRESS = 2, /* compress nodes if possible */ + FF_CASE_AWARE = 1, /**< honour case when comparing */ + FF_COMPRESS = 2, /**< compress nodes if possible */ }; struct fastfind_index { - /* Description useful for debugging mode. */ + /** Description useful for debugging mode. */ unsigned char *comment; - /* Start over. */ + /** Start over. */ void (*reset)(void); - /* Get next struct fastfind_key_value in line. */ + /** Get next struct fastfind_key_value in line. */ struct fastfind_key_value *(*next)(void); - /* Internal reference */ + /** Internal reference */ void *handle; }; #define INIT_FASTFIND_INDEX(comment, reset, next) \ { (comment), (reset), (next) } -/* Initialize and index a list of keys. */ -/* Keys are iterated using: - * @index index info - * @flags control case sensitivity, compression */ -/* This function must be called once and only once per list. */ -/* Failure is not an option, so call it at startup. */ +/** Initialize and index a list of keys. + * Keys are iterated using: + * @param index index info + * @param flags control case sensitivity, compression + * + * This function must be called once and only once per list. + * Failure is not an option, so call it at startup. */ struct fastfind_index *fastfind_index(struct fastfind_index *index, enum fastfind_flags flags); /* The main reason of all that stuff is here. */ -/* Search the index for @key with length @key_len using the - * @index' handle created with fastfind_index(). */ +/** Search the index for @a key with length @a key_len using the + * @a index' handle created with fastfind_index(). */ void *fastfind_search(struct fastfind_index *index, unsigned char *key, int key_len); -/* Fastfind cleanup. It frees the index given by the @fastfind_handle. */ -/* Must be called once per list. */ +/** Fastfind cleanup. It frees the given @a index. + * Must be called once per list. */ void fastfind_done(struct fastfind_index *index); #endif diff --git a/src/util/file.c b/src/util/file.c index d44d83b03..2c2c2bc51 100644 --- a/src/util/file.c +++ b/src/util/file.c @@ -1,4 +1,5 @@ -/* File utilities */ +/** File utilities + * @file */ #ifdef HAVE_CONFIG_H #include "config.h" @@ -283,7 +284,8 @@ safe_mkstemp(unsigned char *template) } -/* The stat_* functions set the various attributes for directory entries. */ +/** @name The stat_* functions set the various attributes for directory entries. + * @{ */ static inline void stat_type(struct string *string, struct stat *stp) @@ -476,6 +478,8 @@ stat_date(struct string *string, struct stat *stp) add_to_string(string, " "); } +/** @} */ + static int compare_dir_entries(struct directory_entry *d1, struct directory_entry *d2) @@ -488,8 +492,8 @@ compare_dir_entries(struct directory_entry *d1, struct directory_entry *d2) } -/* This function decides whether a file should be shown in directory listing or - * not. Returns according boolean value. */ +/** This function decides whether a file should be shown in directory + * listing or not. @returns according boolean value. */ static inline int file_visible(unsigned char *name, int get_hidden_files, int is_root_directory) { @@ -510,9 +514,8 @@ file_visible(unsigned char *name, int get_hidden_files, int is_root_directory) return get_hidden_files; } -/* First information such as permissions is gathered for each directory entry. - * All entries are then sorted and finally the sorted entries are added to the - * @data->fragment one by one. */ +/** First information such as permissions is gathered for each directory entry. + * All entries are then sorted. */ struct directory_entry * get_directory_entries(unsigned char *dirname, int get_hidden) { @@ -585,7 +588,7 @@ get_directory_entries(unsigned char *dirname, int get_hidden) return entries; } -/* Recursively create directories in a path. The last element in the path is +/** Recursively create directories in @a path. The last element in the path is * taken to be a filename, and simply ignored */ int mkalldirs(const unsigned char *path) diff --git a/src/util/file.h b/src/util/file.h index 32121337f..18e62e872 100644 --- a/src/util/file.h +++ b/src/util/file.h @@ -4,18 +4,18 @@ #include +/** Data read about an entry in a directory. + * The strings pointed to by this structure are in the system + * charset (i.e. LC_CTYPE) and must be freed with mem_free(). */ struct directory_entry { - /* The strings pointed to by this structure are in the system - * charset (i.e. LC_CTYPE) and must be freed with mem_free. */ - - /* The various attribute info collected with the stat_* functions. */ + /** The various attribute info collected with the @c stat_* functions. */ unsigned char *attrib; - /* The full path of the dir entry. */ + /** The full path of the dir entry. */ unsigned char *name; }; -/* First information such as permissions is gathered for each directory entry. +/** First information such as permissions is gathered for each directory entry. * All entries are then sorted. */ struct directory_entry * get_directory_entries(unsigned char *dirname, int get_hidden_files); @@ -24,37 +24,38 @@ int file_exists(const unsigned char *filename); int file_can_read(const unsigned char *filename); int file_is_dir(const unsigned char *filename); -/* Strips all directory stuff from @filename and returns the +/** Strips all directory stuff from @a filename and returns the * position of where the actual filename starts */ unsigned char *get_filename_position(unsigned char *filename); -/* Tilde is only expanded for the current users homedir (~/). */ -/* The returned file name is allocated. */ +/** Tilde is only expanded for the current users homedir (~/). + * The returned file name is allocated. */ unsigned char *expand_tilde(unsigned char *filename); -/* Generate a unique file name by trial and error based on the @fileprefix by - * adding suffix counter (e.g. '.42'). */ -/* The returned file name is allocated if @fileprefix is not unique. */ +/*! \brief Generate a unique file name by trial and error based on the + * @a fileprefix by adding suffix counter (e.g. '.42'). + * + * The returned file name is allocated if @a fileprefix is not unique. */ unsigned char *get_unique_name(unsigned char *fileprefix); -/* Checks various environment variables to get the name of the temp dir. +/** Checks various environment variables to get the name of the temp dir. * Returns a filename by concatenating "/". */ unsigned char *get_tempdir_filename(unsigned char *name); -/* Read a line from @file into the dynamically allocated @line, increasing - * @line if necessary. Ending whitespace is trimmed. If a line ends - * with "\" the next line is read too. */ -/* If @line is NULL the returned line is allocated and if file reading fails - * @line is free()d. */ +/** Read a line from @a file into the dynamically allocated @a line, + * increasing @a line if necessary. Ending whitespace is trimmed. + * If a line ends with "\" the next line is read too. + * If @a line is NULL the returned line is allocated and if file + * reading fails @a line is free()d. */ unsigned char *file_read_line(unsigned char *line, size_t *linesize, FILE *file, int *linenumber); -/* Safe wrapper for mkstemp(). +/** Safe wrapper for mkstemp(). * It enforces permissions by calling umask(0177), call mkstemp(), then * restore previous umask(). */ int safe_mkstemp(unsigned char *template); -/* Recursively create directories in a path. The last element in the path is +/** Recursively create directories in @a path. The last element in the path is * taken to be a filename, and simply ignored */ int mkalldirs(const unsigned char *path); diff --git a/src/util/hash.c b/src/util/hash.c index 6d0036ad9..f4b49f558 100644 --- a/src/util/hash.c +++ b/src/util/hash.c @@ -1,4 +1,5 @@ -/* Hashing infrastructure */ +/** Hashing infrastructure + * @file */ #ifdef HAVE_CONFIG_H #include "config.h" @@ -71,11 +72,12 @@ free_hash(struct hash **hashp) } -/* I've no much idea about what to set here.. I think it doesn't matter much +/** Initialization vector for the hash function. + * I've no much idea about what to set here.. I think it doesn't matter much * anyway.. ;) --pasky */ #define HASH_MAGIC 0xdeadbeef -/* Returns hash_item if ok, NULL if error. */ +/** @returns hash_item if ok, NULL if error. */ struct hash_item * add_hash_item(struct hash *hash, unsigned char *key, unsigned int keylen, void *value) @@ -123,7 +125,8 @@ get_hash_item(struct hash *hash, unsigned char *key, unsigned int keylen) #undef HASH_MAGIC -/* If key and/or value were dynamically allocated, think about freeing them. +/** Delete @a item from @a hash. + * If key and/or value were dynamically allocated, think about freeing them. * This function doesn't do that. */ void del_hash_item(struct hash *hash, struct hash_item *item) @@ -138,11 +141,14 @@ del_hash_item(struct hash *hash, struct hash_item *item) #ifdef X31_HASH -/* Fast string hashing. */ +/** Fast string hashing. + * @param k the key + * @param length the length of the key + * @param initval the previous hash, or an arbitrary value */ static hash_value_T -strhash(unsigned char *k, /* the key */ - unsigned int length, /* the length of the key */ - hash_value_T initval /* the previous hash, or an arbitrary value */) +strhash(unsigned char *k, + unsigned int length, + hash_value_T initval) { const unsigned char *p = (const unsigned char *) k; hash_value_T h = initval; @@ -260,10 +266,14 @@ strhash(unsigned char *k, /* the key */ + ((hash_value_T) (k[(a)+2])<<16) \ + ((hash_value_T) (k[(a)+3])<<24)) +/** Hash an array of bytes. + * @param k the key + * @param length the length of the key + * @param initval the previous hash, or an arbitrary value */ static hash_value_T -strhash(unsigned char *k, /* the key */ - unsigned int length, /* the length of the key */ - hash_value_T initval /* the previous hash, or an arbitrary value */) +strhash(unsigned char *k, + unsigned int length, + hash_value_T initval) { int len; hash_value_T a, b, c; diff --git a/src/util/hash.h b/src/util/hash.h index d79da0a0d..6618d8e43 100644 --- a/src/util/hash.h +++ b/src/util/hash.h @@ -3,7 +3,7 @@ #include "util/lists.h" -/* This should be hopefully always 32bit at least. I'm not sure what will +/** This should be hopefully always 32bit at least. I'm not sure what will * happen when this will be of other length, but it should still work ok. * --pasky */ typedef unsigned long hash_value_T; @@ -18,9 +18,9 @@ struct hash_item { }; struct hash { - unsigned int width; /* Number of bits - hash array must be 2^width long. */ + unsigned int width; /**< Number of bits - hash array must be 2^width long. */ hash_func_T func; - struct list_head hash[1]; /* Must be at end ! */ + struct list_head hash[1]; /**< Must be at end ! */ }; struct hash *init_hash8(void); diff --git a/src/util/lists.h b/src/util/lists.h index 094f3ec33..d1f8fdef4 100644 --- a/src/util/lists.h +++ b/src/util/lists.h @@ -14,7 +14,7 @@ * * Fixing this would be a nice and needed janitorial project. */ -/* Lists debugging +/** Lists debugging. * Two unsigned int magic number will be put before and after the next and * prev pointers, these will be check on list operations. * Some pointers are set to specific values after action. */ @@ -81,7 +81,7 @@ do { \ } while (0) -/* Backend for list_magic_check() and list_magic_chkbool(). */ +/** Backend for list_magic_check() and list_magic_chkbool(). */ #define list_magic_correct(x) ((x).magic1 == LISTMAGIC1 && (x).magic2 == LISTMAGIC2) #define list_magic_check(x, where) \ diff --git a/src/util/math.h b/src/util/math.h index d30f1b5b0..0d5c0f3a1 100644 --- a/src/util/math.h +++ b/src/util/math.h @@ -38,22 +38,22 @@ int_max(register int x, register int y) } -/* Limit @what pointed value to upper bound @limit. */ +/** Limit @a what pointed value to upper bound @a limit. */ static inline void int_upper_bound(register int *what, register int limit) { if (*what > limit) *what = limit; } -/* Limit @what pointed value to lower bound @limit. */ +/** Limit @a what pointed value to lower bound @a limit. */ static inline void int_lower_bound(register int *what, register int limit) { if (*what < limit) *what = limit; } -/* Limit @what pointed value to lower bound @lower_limit and to upper bound - * @upper_limit. */ +/** Limit @a what pointed value to lower bound @a lower_limit and to + * upper bound @a upper_limit. */ static inline void int_bounds(register int *what, register int lower_limit, register int upper_limit) @@ -65,7 +65,8 @@ int_bounds(register int *what, register int lower_limit, } -/* This is supposed to evaluate at compile time, giving no performance hit. */ +/** Swap values @a a and @a b, both of type @a type. + * This is supposed to evaluate at compile time, giving no performance hit. */ #define swap_values(type, a, b) \ do { \ type swap_register_ = (a); \ diff --git a/src/util/md5.c b/src/util/md5.c index 0785848ac..67fc2d57b 100644 --- a/src/util/md5.c +++ b/src/util/md5.c @@ -1,6 +1,7 @@ -/* MD5 implementation (RFC 1321) */ - -/* This code implements the MD5 message-digest algorithm. The algorithm is due +/** MD5 implementation (RFC 1321) + * @file + * + * This code implements the MD5 message-digest algorithm. The algorithm is due * to Ron Rivest. * * This code was written by Colin Plumb in 1993, no copyright is claimed. This @@ -26,8 +27,9 @@ static void transform_md5(uint32_t buf[4], uint32_t const in[16]); -/* This code is harmless on little-endian machines. */ -/* FIXME: Optimize it away on little-endian machines. */ +/** Swap the bytes of each uint32_t, if necessary. + * This code is harmless on little-endian machines. + * \todo FIXME: Optimize it away on little-endian machines. */ static void reverse_md5_bytes(unsigned char *buf, unsigned int longs) { @@ -41,7 +43,7 @@ reverse_md5_bytes(unsigned char *buf, unsigned int longs) } while (--longs); } -/* Start MD5 accumulation. Set bit count to 0 and buffer to mysterious +/** Start MD5 accumulation. Set bit count to 0 and buffer to mysterious * initialization constants. */ void init_md5(struct md5_context *ctx) @@ -55,7 +57,7 @@ init_md5(struct md5_context *ctx) ctx->bits[1] = 0; } -/* Update context to reflect the concatenation of another buffer full +/** Update context to reflect the concatenation of another buffer full * of bytes. */ void update_md5(struct md5_context *ctx, const unsigned char *buf, unsigned long len) @@ -103,10 +105,10 @@ update_md5(struct md5_context *ctx, const unsigned char *buf, unsigned long len) memmove(ctx->in, buf, len); } -/* Final wrapup - pad to 64-byte boundary with the bit pattern 1 0* (64-bit +/** Final wrapup - pad to 64-byte boundary with the bit pattern 1 0* (64-bit * count of bits processed, MSB-first) */ void -done_md5(struct md5_context *ctx, unsigned char digest[16]) +done_md5(struct md5_context *ctx, md5_digest_bin_T digest) { unsigned int count; unsigned char *p; @@ -150,7 +152,7 @@ done_md5(struct md5_context *ctx, unsigned char digest[16]) unsigned char * digest_md5(const unsigned char *data, unsigned long length, - unsigned char digest[16]) + md5_digest_bin_T digest) { struct md5_context ctx; @@ -172,11 +174,11 @@ digest_md5(const unsigned char *data, unsigned long length, #define F3(x, y, z) (x ^ y ^ z) #define F4(x, y, z) (y ^ (x | ~z)) -/* This is the central step in the MD5 algorithm. */ +/** This is the central step in the MD5 algorithm. */ #define MD5STEP(f, w, x, y, z, data, s) \ ( w += f(x, y, z) + data, w = w<>(32-s), w += x ) -/* The core of the MD5 algorithm, this alters an existing MD5 hash to reflect +/** The core of the MD5 algorithm, this alters an existing MD5 hash to reflect * the addition of 16 longwords of new data. md5_update() blocks the data and * converts bytes into longwords for this routine. */ static void diff --git a/src/util/md5.h b/src/util/md5.h index f4f7f4c49..f23caf8b7 100644 --- a/src/util/md5.h +++ b/src/util/md5.h @@ -37,13 +37,14 @@ void init_md5(struct md5_context *context); void update_md5(struct md5_context *context, const unsigned char *data, unsigned long length); void done_md5(struct md5_context *context, md5_digest_bin_T digest); -/* Digest the passed @data with the given length and stores the MD5 digest in - * the @digest parameter. */ +/** Digest the passed @a data with the given length and stores the MD5 + * digest in the @a digest parameter. */ unsigned char * digest_md5(const unsigned char *data, unsigned long length, md5_digest_bin_T digest); #ifdef CONFIG_MD5 -/* Provide compatibility with the OpenSSL interface: */ +/** @name Provide compatibility with the OpenSSL interface: + * @{ */ typedef struct md5_context MD5_CTX; #define MD5_Init(context) init_md5(context) @@ -51,6 +52,7 @@ typedef struct md5_context MD5_CTX; #define MD5_Final(md5, context) done_md5(context, md5) #define MD5(data, len, md5) digest_md5(data, len, md5) +/** @} */ #endif /* CONFIG_MD5 */ #endif diff --git a/src/util/memdebug.c b/src/util/memdebug.c index d87b590b9..8551c5238 100644 --- a/src/util/memdebug.c +++ b/src/util/memdebug.c @@ -1,6 +1,7 @@ -/* Memory debugging (leaks, overflows & co) */ - -/* Wrappers for libc memory managment providing protection against common +/** Memory debugging (leaks, overflows & co) + * @file + * + * Wrappers for libc memory managment providing protection against common * pointers manipulation mistakes - bad realloc()/free() pointers, double * free() problem, using uninitialized/freed memory, underflow/overflow * protection, leaks tracking... @@ -52,49 +53,49 @@ #ifdef DEBUG_MEMLEAK -/* Eat less memory, but sacrifice speed? +/** Eat less memory, but sacrifice speed? * Default is defined. */ #define LESS_MEMORY_SPEED -/* Fill memory on alloc() ? +/** Fill memory on alloc() ? * Default is defined. */ #define FILL_ON_ALLOC #define FILL_ON_ALLOC_VALUE 'X' -/* Fill memory on realloc() ? +/** Fill memory on realloc() ? * Default is defined. */ #define FILL_ON_REALLOC #define FILL_ON_REALLOC_VALUE 'Y' -/* Fill memory before free() ? +/** Fill memory before free() ? * Default is undef. */ #undef FILL_ON_FREE #define FILL_ON_FREE_VALUE 'Z' -/* Check alloc_header block sanity ? +/** Check alloc_header block sanity ? * Default is defined. */ #define CHECK_AH_SANITY #define AH_SANITY_MAGIC 0xD3BA110C -/* Check for useless reallocation ? +/** Check for useless reallocation ? * If oldsize is equal to newsize, print a message to stderr. * It may help to find inefficient code. * Default is undefined. */ #undef CHECK_USELESS_REALLOC -/* Check for validity of address passed to free() ? +/** Check for validity of address passed to free() ? * Note that this is VERY slow, as we iterate through whole memory_list each * time. We can't check magics etc, as it would break double free() check. * Default is undef. */ #undef CHECK_INVALID_FREE -/* Check for double free ? +/** Check for double free ? * Default is defined. */ #define CHECK_DOUBLE_FREE #define AH_FREE_MAGIC 0xD3BF110C -/* Check for overflows and underflows ? +/** Check for overflows and underflows ? * Default is defined. */ #define CHECK_XFLOWS #define XFLOW_MAGIC (char) 0xFA @@ -118,7 +119,7 @@ struct alloc_header { unsigned char *comment; #ifdef CHECK_XFLOWS - /* This is a little magic. We want to keep the main pointer aligned, + /** This is a little magic. We want to keep the main pointer aligned, * that means we want to have the xflow underflow mark in the * alloc_header space, but at the _end_ of the aligned reserved space. * This means we in fact live at [SIZE_AH_ALIGNED - 1], not here. (Of diff --git a/src/util/memlist.c b/src/util/memlist.c index f33975328..b22fb07ff 100644 --- a/src/util/memlist.c +++ b/src/util/memlist.c @@ -1,4 +1,5 @@ -/* These routines represent handling of struct memory_list. */ +/** These routines represent handling of struct memory_list. + * @file */ #ifdef HAVE_CONFIG_H #include "config.h" @@ -14,7 +15,8 @@ #include "util/memory.h" -/* +/** + * \struct memory_list * memory_list is used to track information about all allocated memory * belonging to something. Then we can free it when we won't need it * anymore, but the one who allocated it won't be able to get control @@ -23,8 +25,8 @@ #define ML_SIZE(n) (sizeof(struct memory_list) + (n) * sizeof(void *)) -/* Create a memory list. If p is NULL or allocation fails, it will - * returns NULL. +/** Create a memory list. If @a p is NULL or allocation fails, it will + * return NULL. * It always stops at first NULL element. */ #if defined(DEBUG_MEMLIST) && defined(HAVE_VARIADIC_MACROS) struct memory_list * @@ -65,7 +67,7 @@ getml(void *p, ...) return ml; } -/* Add elements to a memory list. +/** Add elements to a memory list. * If memory list exists, it enlarges it, else it creates it. * if there's no elements or first element is NULL, it does nothing. * It always stops at first NULL element. */ @@ -161,7 +163,7 @@ add_one_to_ml(struct memory_list **ml, void *p) } -/* Free elements and memory list. +/** Free elements and memory list. * It returns safely if passed a NULL pointer. */ void freeml(struct memory_list *ml) diff --git a/src/util/memory.c b/src/util/memory.c index 78ef23d23..4a067adb6 100644 --- a/src/util/memory.c +++ b/src/util/memory.c @@ -1,4 +1,5 @@ -/* Memory allocation manager */ +/** Memory allocation manager + * @file */ #ifndef _GNU_SOURCE #define _GNU_SOURCE /* MREMAP_MAYMOVE */ @@ -128,8 +129,9 @@ mem_realloc(void *p, size_t size) static int page_size; -/* This tries to prevent useless reallocations, especially since they are quite - * expensive in the mremap()-less case. */ +/** Round up to a full page. + * This tries to prevent useless reallocations, especially since they + * are quite expensive in the mremap()-less case. */ static size_t round_size(size_t size) { @@ -140,7 +142,7 @@ round_size(size_t size) return (size / page_size + 1) * page_size; } -/* Some systems may not have MAP_ANON but MAP_ANONYMOUS instead. */ +/** Some systems may not have MAP_ANON but MAP_ANONYMOUS instead. */ #if defined(MAP_ANONYMOUS) && !defined(MAP_ANON) #define MAP_ANON MAP_ANONYMOUS #endif diff --git a/src/util/memory.h b/src/util/memory.h index 9fab2fd44..b8925189a 100644 --- a/src/util/memory.h +++ b/src/util/memory.h @@ -5,17 +5,17 @@ * if not defined, we'll try to continue. */ /* #define CRASH_IF_ALLOC_MAXTRIES */ -/* Max. number of retry in case of memory allocation failure. */ +/** Max. number of retry in case of memory allocation failure. */ #define ALLOC_MAXTRIES 3 -/* Delay in seconds between each alloc try. */ +/** Delay in seconds between each alloc try. */ #define ALLOC_DELAY 3 #define fmem_alloc(x) mem_alloc(x) #define fmem_free(x) mem_free(x) -/* Cygwin wants some size_t definition here... let's try to make it happy +/** Cygwin wants some size_t definition here... let's try to make it happy * then. Hrmpf. */ #include #include @@ -108,17 +108,17 @@ void *mem_realloc(void *, size_t); #endif /* DEBUG_MEMLEAK */ -/* Granular memory allocation. */ +/** @name Granular memory allocation. + * The granularity used by the aligned memory functions below must be a mask + * with all bits set from but not including the most significant bit and down. + * So if an alignment of 256 is wanted use 0xFF. + * @{ */ -/* The ``old'' style granularity. XXX: Must be power of 2 */ +/** The 'old' style granularity. XXX: Must be power of 2 */ #define ALLOC_GR 0x100 #include /* for memset() */ -/* The granularity used by the aligned memory functions below must be a mask - * with all bits set from but not including the most significant bit and down. - * So if an alignment of 256 is wanted use 0xFF. */ - #define ALIGN_MEMORY_SIZE(x, gr) (((x) + (gr)) & ~(gr)) static inline void * @@ -159,10 +159,14 @@ mem_align_alloc__( mem_align_alloc__((void **) ptr, old, new, sizeof(**ptr), mask) #endif +/** @} */ -/* Maybe-free macros */ -/* TODO: Think about making what they do more obvious in their identifier, they - * could be obfuscating their users a little for the newcomers otherwise. */ + +/** @name Maybe-free macros + * \todo TODO: Think about making what they do more obvious in their + * identifier, they could be obfuscating their users a little for the + * newcomers otherwise. + * @{ */ #define mem_free_set(x, v) do { if (*(x)) mem_free(*(x)); *(x) = (v); } while (0) #define mem_free_if(x) do { register void *p = (x); if (p) mem_free(p); } while (0) @@ -172,6 +176,7 @@ mem_align_alloc__( #undef mem_free_if #define mem_free_if(x) mem_free_set(&x, NULL) #endif +/** @} */ /* This is out of place, but there is no better place. */ diff --git a/src/util/profile.h b/src/util/profile.h index c06d8e5c4..6568c6e2b 100644 --- a/src/util/profile.h +++ b/src/util/profile.h @@ -1,3 +1,6 @@ +/** Process' CPU time utilities + * @file*/ + #ifndef EL__UTIL_PROFILE_H #define EL__UTIL_PROFILE_H @@ -5,31 +8,30 @@ #include "config.h" #endif -/* Process' CPU time utilities */ #ifdef CONFIG_DEBUG #include -/* CLK_DECL(n) declares an array of @n clock_t to be used by CLK_* macros. - * Must occur before any CLK_* macros call. */ +/** @c CLK_DECL(n) declares an array of @a n clock_t to be used by + * CLK_* macros. Must occur before any CLK_* macros call. */ #define CLK_DECL(n) clock_t clk_start[n], clk_end[n], clk_diff[n]; int clk_start_line[n], clk_stop_line[n] -/* CLK_START(n) starts clock @n. +/** @c CLK_START(n) starts clock @a n. * Must occur after CLK_DECL() and before CLK_STOP(). */ #define CLK_START(n) do { clk_start_line[n] = __LINE__; clk_start[n] = clock(); } while (0) -/* CLK_STOP(n) stops clock @n. +/* @c CLK_STOP(n) stops clock @a n. * Must occur after CLK_START() and before CLK_DUMP(). */ #define CLK_STOP(n) do { clk_end[n] = clock(); clk_diff[n] = clk_end[n] - clk_start[n]; clk_stop_line[n] = __LINE__; } while (0) -/* CLK_DUMP(n) echoes cpu time spent between CLK_START(@n) and CLK_STOP(@n). - * Must occur after CLK_START() and CLK_STOP(). */ +/* @c CLK_DUMP(n) echoes cpu time spent between CLK_START(@a n) and + * CLK_STOP(@a n). Must occur after CLK_START() and CLK_STOP(). */ #define CLK_DUMP(n) do { \ fprintf(stderr, "%s:%d->%d CLK[%d]= %.16f sec.\n", \ __FILE__, clk_start_line[n], clk_stop_line[n], \ n, (double) clk_diff[n] / (double) CLOCKS_PER_SEC);\ } while (0) -/* Shortcuts for function profiling. +/** Shortcuts for function profiling. * CLK_STA() must be at end of local declarations. * CLK_STO() must be just before end of function. */ #define CLK_STA() CLK_DECL(1); CLK_START(0) diff --git a/src/util/scanner.c b/src/util/scanner.c index 3f7da6c08..d2440967b 100644 --- a/src/util/scanner.c +++ b/src/util/scanner.c @@ -1,4 +1,5 @@ -/* A pretty generic scanner */ +/** A pretty generic scanner + * @file */ #ifdef HAVE_CONFIG_H #include "config.h" @@ -116,7 +117,8 @@ get_scanner_token_debug(struct scanner *scanner) #endif -/* Initializers */ +/** @name Initializers + * @{ */ static inline void init_scanner_info(struct scanner_info *scanner_info) @@ -170,3 +172,5 @@ init_scanner(struct scanner *scanner, struct scanner_info *scanner_info, scanner->info = scanner_info; scanner->info->scan(scanner); } + +/** @} */ diff --git a/src/util/scanner.h b/src/util/scanner.h index 2bbe99f85..f52e7a09a 100644 --- a/src/util/scanner.h +++ b/src/util/scanner.h @@ -6,19 +6,19 @@ /* Define if you want a talking scanner */ /* #define DEBUG_SCANNER */ -/* The {struct scanner_token} describes one scanner state. There are two kinds +/** The struct scanner_token describes one scanner state. There are two kinds * of tokens: char and non-char tokens. Char tokens contains only one char and * simply have their char value as type. They are tokens having special control * meaning in the code, like ':', ';', '{', '}' and '*'. Non char tokens has * one or more chars and contain stuff like number or indentifier strings. */ struct scanner_token { - /* The type the token */ + /** The type of the token */ int type; - /* Some precedence value */ + /** Some precedence value */ int precedence; - /* The start of the token string and the token length */ + /** The start of the token string and the token length */ unsigned char *string; int length; }; @@ -27,11 +27,11 @@ struct scanner_token { * "static" strings (I don't have a better word) so the macro name should * be short. --jonas */ -/* Compare the string of @token with @string */ +/** Compare the string of @a token with @a str */ #define scanner_token_strlcasecmp(token, str, len) \ ((token) && !strlcasecmp((token)->string, (token)->length, str, len)) -/* Also compares the token string but using a "static" string */ +/** Also compares the token string but using a "static" string */ #define scanner_token_contains(token, str) \ scanner_token_strlcasecmp(token, str, sizeof(str) - 1) @@ -63,65 +63,66 @@ struct scanner_string_mapping { struct scanner; struct scanner_info { - /* Table containing how to map strings to token types */ + /** Table containing how to map strings to token types */ const struct scanner_string_mapping *mappings; - /* Information for how to initialize the scanner table */ + /** Information for how to initialize the scanner table */ const struct scan_table_info *scan_table_info; - /* Fills the scanner with tokens. Already scanned tokens which have not - * been requested remain and are moved to the start of the scanners - * token table. */ - /* Returns the current token or NULL if there are none. */ + /** Fills the scanner with tokens. Already scanned tokens + * which have not been requested remain and are moved to the + * start of the scanners token table. + * @returns the current token or NULL if there are none. */ struct scanner_token *(*scan)(struct scanner *scanner); - /* The scanner table */ - /* Contains bitmaps for the various characters groups. - * Idea sync'ed from mozilla browser. */ + /** The scanner table. Contains bitmaps for the various + * characters groups. Idea sync'ed from mozilla browser. */ int scan_table[SCAN_TABLE_SIZE]; - /* Has the scanner info been initialized? */ + /** Has the scanner info been initialized? */ unsigned int initialized:1; }; -/* Initializes the scanner. */ +/** Initializes the scanner. */ void init_scanner(struct scanner *scanner, struct scanner_info *scanner_info, unsigned char *string, unsigned char *end); -/* The number of tokens in the scanners token table: +/** The number of tokens in the scanners token table: * At best it should be big enough to contain properties with space separated * values and function calls with up to 3 variables like rgb(). At worst it * should be no less than 2 in order to be able to peek at the next token in * the scanner. */ #define SCANNER_TOKENS 10 -/* The {struct scanner} describes the current state of the scanner. */ +/** The struct scanner describes the current state of the scanner. */ struct scanner { - /* The very start of the scanned string, the position in the string - * where to scan next and the end of the string. If position is NULL it - * means that no more tokens can be retrieved from the string. */ + /** The very start of the scanned string, the position in the string + * where to scan next and the end of the string. If #position is NULL + * it means that no more tokens can be retrieved from the string. */ unsigned char *string, *position, *end; - /* The current token and number of scanned tokens in the table. - * If the number of scanned tokens is less than SCANNER_TOKENS + /** The current token and number of scanned tokens in the table. + * If the number of scanned tokens is less than ::SCANNER_TOKENS * it is because there are no more tokens in the string. */ struct scanner_token *current; int tokens; - /* The 'meta' scanner information */ + /** The 'meta' scanner information */ struct scanner_info *info; #ifdef DEBUG_SCANNER - /* Debug info about the caller. */ + /** @name Debug info about the caller. + * @{ */ unsigned char *file; int line; + /** @} */ #endif - /* Some state indicator only meaningful to the scanner internals */ + /** Some state indicator only meaningful to the scanner internals */ int state; - /* The table contain already scanned tokens. It is maintained in + /** The table contain already scanned tokens. It is maintained in * order to optimize the scanning a bit and make it possible to look * ahead at the next token. You should always use the accessors * (defined below) for getting tokens from the scanner. */ @@ -131,7 +132,7 @@ struct scanner { #define scanner_has_tokens(scanner) \ ((scanner)->tokens > 0 && (scanner)->current < (scanner)->table + (scanner)->tokens) -/* This macro checks if the current scanner state is valid. Meaning if the +/** This macro checks if the current scanner state is valid. Meaning if the * scanners table is full the last token skipping or get_next_scanner_token() * call made it possible to get the type of the next token. */ #define check_scanner(scanner) \ @@ -139,15 +140,16 @@ struct scanner { || scanner->current + 1 < scanner->table + scanner->tokens) -/* Scanner table accessors and mutators */ +/** @name Scanner table accessors and mutators + * @{ */ -/* Checks the type of the next token */ +/** Checks the type of the next token */ #define check_next_scanner_token(scanner, token_type) \ (scanner_has_tokens(scanner) \ && ((scanner)->current + 1 < (scanner)->table + (scanner)->tokens) \ && (scanner)->current[1].type == (token_type)) -/* Access current and next token. Getting the next token might cause +/** Access current and next token. Getting the next token might cause * a rescan so any token pointers that has been stored in a local variable * might not be valid after the call. */ static inline struct scanner_token * @@ -156,7 +158,7 @@ get_scanner_token(struct scanner *scanner) return scanner_has_tokens(scanner) ? scanner->current : NULL; } -/* Do a scanning if we do not have also have access to next token. */ +/** Do a scanning if we do not have also have access to next token. */ static inline struct scanner_token * get_next_scanner_token(struct scanner *scanner) { @@ -165,16 +167,18 @@ get_next_scanner_token(struct scanner *scanner) ? scanner->info->scan(scanner) : get_scanner_token(scanner)); } -/* This should just make the code more understandable .. hopefully */ +/** This should just make the code more understandable .. hopefully */ #define skip_scanner_token(scanner) get_next_scanner_token(scanner) -/* Removes tokens from the scanner until it meets a token of the given type. +/** Removes tokens from the scanner until it meets a token of the given type. * This token will then also be skipped. */ struct scanner_token * skip_scanner_tokens(struct scanner *scanner, int skipto, int precedence); -/* Looks up the string from @ident to @end to in the scanners string mapping - * table */ +/** @} */ + +/** Looks up the string from @a ident to @a end to in the scanners + * string mapping table */ int map_scanner_string(struct scanner *scanner, unsigned char *ident, unsigned char *end, int base_type); @@ -185,9 +189,8 @@ void dump_scanner(struct scanner *scanner); /* The begin_token_scanning() and end_token_scanning() functions provide the * basic setup and teardown for the rescan function made public via the - * scanner_info->scan member. */ - -/* Returns NULL if it is not necessary to try to scan for more tokens */ + * scanner_info->scan member. + * @returns NULL if it is not necessary to try to scan for more tokens */ static inline struct scanner_token * begin_token_scanning(struct scanner *scanner) { @@ -221,10 +224,11 @@ begin_token_scanning(struct scanner *scanner) return table; } -/* Updates the @scanner struct after scanning has been done. The position - * _after_ the last valid token is taken as the @end argument. */ -/* It is ok for @end to be < scanner->table since scanner->tokens will become - * <= 0 anyway. */ +/* Updates the @a scanner struct after scanning has been done. The position + * _after_ the last valid token is taken as the @a end argument. + * + * It is ok for @a end to be < scanner->table since scanner->tokens + * will become <= 0 anyway. */ static inline struct scanner_token * end_token_scanning(struct scanner *scanner, struct scanner_token *end) { diff --git a/src/util/secsave.c b/src/util/secsave.c index fae599f2d..13df96d4f 100644 --- a/src/util/secsave.c +++ b/src/util/secsave.c @@ -1,4 +1,5 @@ -/* Secure file saving handling */ +/** Secure file saving handling + * @file */ #ifdef HAVE_CONFIG_H #include "config.h" @@ -67,8 +68,8 @@ enum secsave_errno secsave_errno = SS_ERR_NONE; -/* Open a file for writing in a secure way. It returns a pointer to a structure - * secure_save_info on success, or NULL on failure. */ +/** Open a file for writing in a secure way. @returns a pointer to a + * structure secure_save_info on success, or NULL on failure. */ static struct secure_save_info * secure_open_umask(unsigned char *file_name) { @@ -219,8 +220,8 @@ secure_open(unsigned char *file_name) return ssi; } -/* Close a file opened with secure_open, and return 0 on success, errno - * or -1 on failure. */ +/** Close a file opened with secure_open(). @returns 0 on success, + * errno or -1 on failure. */ int secure_close(struct secure_save_info *ssi) { @@ -298,7 +299,7 @@ free: } -/* fputs() wrapper, set ssi->err to errno on error. If ssi->err is set when +/** fputs() wrapper, set ssi->err to errno on error. If ssi->err is set when * called, it immediatly returns EOF. */ int secure_fputs(struct secure_save_info *ssi, const char *s) @@ -317,7 +318,7 @@ secure_fputs(struct secure_save_info *ssi, const char *s) } -/* fputc() wrapper, set ssi->err to errno on error. If ssi->err is set when +/** fputc() wrapper, set ssi->err to errno on error. If ssi->err is set when * called, it immediatly returns EOF. */ int secure_fputc(struct secure_save_info *ssi, int c) @@ -335,7 +336,7 @@ secure_fputc(struct secure_save_info *ssi, int c) return ret; } -/* fprintf() wrapper, set ssi->err to errno on error and return a negative +/** fprintf() wrapper, set ssi->err to errno on error and return a negative * value. If ssi->err is set when called, it immediatly returns -1. */ int secure_fprintf(struct secure_save_info *ssi, const char *format, ...) diff --git a/src/util/secsave.h b/src/util/secsave.h index 65506dc0c..e1e38305c 100644 --- a/src/util/secsave.h +++ b/src/util/secsave.h @@ -1,4 +1,5 @@ -/* Secure file saving handling */ +/** Secure file saving handling + * @file */ #ifndef EL__UTIL_SECSAVE_H #define EL__UTIL_SECSAVE_H @@ -10,8 +11,8 @@ struct terminal; enum secsave_errno { SS_ERR_NONE = 0, - SS_ERR_DISABLED, /* secsave is disabled. */ - SS_ERR_OUT_OF_MEM, /* memory allocation failure */ + SS_ERR_DISABLED, /**< secsave is disabled. */ + SS_ERR_OUT_OF_MEM, /**< memory allocation failure */ /* see err field in struct secure_save_info */ SS_ERR_OPEN_READ, @@ -23,14 +24,14 @@ enum secsave_errno { SS_ERR_OTHER, }; -extern enum secsave_errno secsave_errno; /* internal secsave error number */ +extern enum secsave_errno secsave_errno; /**< internal secsave error number */ struct secure_save_info { - FILE *fp; /* file stream pointer */ - unsigned char *file_name; /* final file name */ - unsigned char *tmp_file_name; /* temporary file name */ - int err; /* set to non-zero value in case of error */ - int secure_save; /* use secure save for this file */ + FILE *fp; /**< file stream pointer */ + unsigned char *file_name; /**< final file name */ + unsigned char *tmp_file_name; /**< temporary file name */ + int err; /**< set to non-zero value in case of error */ + int secure_save; /**< use secure save for this file */ }; struct secure_save_info *secure_open(unsigned char *); diff --git a/src/util/string.c b/src/util/string.c index 65fb19352..c627ccbf0 100644 --- a/src/util/string.c +++ b/src/util/string.c @@ -1,4 +1,5 @@ -/* String handling functions */ +/** String handling functions + * @file */ #ifdef HAVE_CONFIG_H #include "config.h" @@ -432,7 +433,7 @@ add_xchar_to_string(struct string *string, unsigned char character, int times) return string; } -/* Add printf-like format string to @string. */ +/** Add printf()-style format string to @a string. */ struct string * add_format_to_string(struct string *string, const unsigned char *format, ...) { diff --git a/src/util/string.h b/src/util/string.h index b1043a8be..b5a04d291 100644 --- a/src/util/string.h +++ b/src/util/string.h @@ -16,20 +16,22 @@ #ifndef DEBUG_MEMLEAK -/* Autoallocation string constructors: */ - -/* Note that, contrary to the utilities using the string struct, these +/** @name Autoallocation string constructors: + * Note that, contrary to the utilities using the string struct, these * functions are NOT granular, thus you can't simply reuse strings allocated by - * these in add_to_string()-style functions. */ + * these in add_to_string()-style functions. + * @{ */ -/* Allocates NUL terminated string with @len bytes from @src. - * If @src == NULL or @len < 0 only one byte is allocated and set it to 0. */ -/* Returns the string or NULL on allocation failure. */ +/** Allocates NUL terminated string with @a len bytes from @a src. + * If @a src == NULL or @a len < 0 only one byte is allocated and set it to 0. + * @returns the string or NULL on allocation failure. */ unsigned char *memacpy(const unsigned char *src, int len); -/* Allocated NUL terminated string with the content of @src. */ +/** Allocated NUL terminated string with the content of @a src. */ unsigned char *stracpy(const unsigned char *src); +/** @} */ + #else /* DEBUG_MEMLEAK */ unsigned char *debug_memacpy(const unsigned char *, int, const unsigned char *, int); @@ -41,60 +43,69 @@ unsigned char *debug_stracpy(const unsigned char *, int, const unsigned char *); #endif /* DEBUG_MEMLEAK */ -/* Concatenates @src to @str. */ -/* If reallocation of @str fails @str is not touched. */ +/** Concatenates @a src to @a str. + * If reallocation of @a str fails @a str is not touched. */ void add_to_strn(unsigned char **str, const unsigned char *src); -/* Inserts @seqlen chars from @seq at position @pos in the @dst string. */ -/* If reallocation of @dst fails it is not touched and NULL is returned. */ +/** Inserts @a seqlen chars from @a seq at position @a pos in the @a + * dst string. + * If reallocation of @a dst fails it is not touched and NULL is returned. */ unsigned char *insert_in_string(unsigned char **dst, int pos, const unsigned char *seq, int seqlen); -/* Takes a list of strings where the last parameter _must_ be - * (unsigned char *) NULL and concatenates them. */ -/* Returns the allocated string or NULL on allocation failure. */ -/* Example: +/** Takes a list of strings where the last parameter _must_ be + * (unsigned char *) NULL and concatenates them. + * + * @returns the allocated string or NULL on allocation failure. + * + * Example: @code * unsigned char *abc = straconcat("A", "B", "C", (unsigned char *) NULL); * if (abc) return; * printf("%s", abc); -> print "ABC" - * mem_free(abc); -> free memory used by @abc */ + * mem_free(abc); -> free memory used by @abc + * @endcode */ unsigned char *straconcat(const unsigned char *str, ...); -/* Misc. utility string functions. */ +/** @name Misc. utility string functions. + * @{ */ -/* Compare two strings, handling correctly @s1 or @s2 being NULL. */ +/** Compare two strings, handling correctly @a s1 or @a s2 being NULL. */ int xstrcmp(const unsigned char *s1, const unsigned char *s2); -/* Copies at most @len chars into @dst. Ensures null termination of @dst. */ +/** Copies at most @a len chars into @a dst. Ensures null termination of @a dst. */ unsigned char *safe_strncpy(unsigned char *dst, const unsigned char *src, size_t len); /* strlcmp() is the middle child of history, everyone is using it differently. * On some weird *systems* it seems to be defined (equivalent to strcasecmp()), * so we'll better use our #define redir. */ -/* This routine compares string @s1 of length @n1 with string @s2 of length - * @n2. +/** This routine compares string @a s1 of length @a n1 with string @a s2 + * of length @a n2. * * This acts identically to strcmp() but for non-zero-terminated strings, - * rather than being similiar to strncmp(). That means, it fails if @n1 != @n2, - * thus you may use it for testing whether @s2 matches *full* @s1, not only its - * start (which can be a security hole, ie. in the cookies domain checking). + * rather than being similiar to strncmp(). That means, it fails if @a n1 + * != @a n2, thus you may use it for testing whether @a s2 matches *full* + * @a s1, not only its start (which can be a security hole, e.g. in the + * cookies domain checking). * - * @n1 or @n2 may be -1, which is same as strlen(@s[12]) but possibly more - * effective (in the future ;-). */ -/* Returns zero if the strings match or undefined non-zero value if they + * @a n1 or @a n2 may be -1, which is same as strlen(@a s1 or @a s2) but + * possibly more effective (in the future ;-). + * + * @returns zero if the strings match or undefined non-zero value if they * differ. (The non-zero return value is _not_ same as for the standard * strcmp() family.) */ #define strlcmp(a,b,c,d) (errfile = __FILE__, errline = __LINE__, elinks_strlcmp(a,b,c,d)) int elinks_strlcmp(const unsigned char *s1, size_t n1, const unsigned char *s2, size_t n2); -/* Acts identically to strlcmp(), except for being case insensitive. */ +/** Acts identically to strlcmp(), except for being case insensitive. */ #define strlcasecmp(a,b,c,d) (errfile = __FILE__, errline = __LINE__, elinks_strlcasecmp(a,b,c,d)) int elinks_strlcasecmp(const unsigned char *s1, size_t n1, const unsigned char *s2, size_t n2); +/** @} */ + #define skip_space(S) \ do { while (isspace(*(S))) (S)++; } while (0) @@ -109,16 +120,16 @@ int elinks_strlcasecmp(const unsigned char *s1, size_t n1, #define isasciialnum(c) (isasciialpha(c) || isdigit(c)) #define isident(c) (isasciialnum(c) || (c) == '_' || (c) == '-') -/* Char is safe to write to the terminal screen. Cannot test for C1 +/** Char is safe to write to the terminal screen. Cannot test for C1 * control characters (0x80 to 0x9F) because this is also used for * non-ISO-8859 charsets. */ #define isscreensafe(c) ((c) >= ' ' && (c) != ASCII_DEL) -/* Like isscreensafe but takes Unicode values and so can check for C1. */ +/** Like isscreensafe() but takes Unicode values and so can check for C1. */ #define isscreensafe_ucs(c) (((c) >= 0x20 && (c) <= 0x7E) || (c) >= 0xA0) -/* String debugging using magic number, it may catch some errors. */ +/** String debugging using magic number, it may catch some errors. */ #ifdef CONFIG_DEBUG #define DEBUG_STRING #endif @@ -132,7 +143,7 @@ struct string { }; -/* The granularity used for the struct string based utilities. */ +/** The granularity used for the struct string based utilities. */ #define STRING_GRANULARITY 0xFF #ifdef DEBUG_STRING @@ -148,7 +159,10 @@ struct string { #define INIT_STRING(s, l) { s, l } #endif -/* Initializes the passed string struct by preallocating the @source member. */ +/** Initializes the passed string struct by preallocating the + * string.source member. + * @returns @a string if successful, or NULL if out of memory. + * @post done_string(@a string) is safe, even if this returned NULL. */ #ifdef DEBUG_MEMLEAK struct string *init_string__(const unsigned char *file, int line, struct string *string); #define init_string(string) init_string__(__FILE__, __LINE__, string) @@ -156,7 +170,7 @@ struct string *init_string__(const unsigned char *file, int line, struct string struct string *init_string(struct string *string); #endif -/* Resets @string and free()s the @source member. */ +/** Resets @a string and free()s the string.source member. */ void done_string(struct string *string); @@ -167,17 +181,17 @@ struct string *add_string_to_string(struct string *to, const struct string *from struct string *add_file_to_string(struct string *string, const unsigned char *filename); struct string *add_crlf_to_string(struct string *string); -/* Adds each C string to @string until a terminating +/** Adds each C string to @a string until a terminating * (unsigned char *) NULL is met. */ struct string *string_concat(struct string *string, ...); -/* Extends the string with @times number of @character. */ +/** Extends the string with @a times number of @a character. */ struct string *add_xchar_to_string(struct string *string, unsigned char character, int times); -/* Add printf-style format string to @string. */ +/** Add printf()-style format string to @a string. */ struct string *add_format_to_string(struct string *string, const unsigned char *format, ...); -/* Get a regular newly allocated stream of bytes from @string. */ +/** Get a regular newly allocated stream of bytes from @a string. */ static unsigned char *squeezastring(struct string *string); @@ -247,8 +261,8 @@ struct string_list_item { struct string string; }; -/* Adds @string with @length chars to the list. If length is -1 it will be set - * to the return value of strlen(). */ +/** Adds @a string with @a length chars to the list. If @a length is -1 + * it will be set to the return value of strlen(). */ struct string * add_to_string_list(LIST_OF(struct string_list_item) *list, const unsigned char *string, int length); @@ -256,10 +270,10 @@ add_to_string_list(LIST_OF(struct string_list_item) *list, void free_string_list(LIST_OF(struct string_list_item) *list); -/* Returns an empty C string or @str if different from NULL. */ +/** Returns an empty C string or @a str if different from NULL. */ #define empty_string_or_(str) ((str) ? (unsigned char *) (str) : (unsigned char *) "") -/* Allocated copy if not NULL or returns NULL. */ +/** Allocated copy if not NULL or returns NULL. */ #define null_or_stracpy(str) ((str) ? stracpy(str) : NULL) #endif /* EL__UTIL_STRING_H */ diff --git a/src/util/time.c b/src/util/time.c index d7691a14d..b046de9ab 100644 --- a/src/util/time.c +++ b/src/util/time.c @@ -1,4 +1,5 @@ -/* Time operations */ +/** Time operations + * @file */ #ifdef HAVE_CONFIG_H #include "config.h" @@ -17,7 +18,7 @@ #include "util/error.h" #include "util/time.h" -/* Get the current time. +/** Get the current time. * It attempts to use available functions, granularity * may be as worse as 1 second if time() is used. */ timeval_T * @@ -45,7 +46,7 @@ timeval_now(timeval_T *t) return t; } -/* Subtract an interval to a timeval, it ensures that +/** Subtract an interval to a timeval, it ensures that * result is never negative. */ timeval_T * timeval_sub_interval(timeval_T *t, timeval_T *interval) @@ -134,7 +135,7 @@ timeval_from_milliseconds(timeval_T *t, milliseconds_T milliseconds) return t; } -/* Bug 923: Assumes time_t values fit in long. (This function is used +/** @bug 923: Assumes time_t values fit in long. (This function is used * for both timestamps and durations.) */ timeval_T * timeval_from_seconds(timeval_T *t, long seconds) @@ -186,7 +187,7 @@ timeval_to_milliseconds(timeval_T *t) return add_ms_to_ms(a, b); } -/* Bug 923: Assumes time_t values fit in long. (This function is used +/** @bug 923: Assumes time_t values fit in long. (This function is used * for both timestamps and durations.) */ long timeval_to_seconds(timeval_T *t) @@ -200,7 +201,7 @@ timeval_is_positive(timeval_T *t) return (t->sec > 0 || (t->sec == 0 && t->usec > 0)); } -/* Be sure timeval is not negative. */ +/** Be sure timeval is not negative. */ void timeval_limit_to_zero_or_one(timeval_T *t) { @@ -212,9 +213,10 @@ timeval_limit_to_zero_or_one(timeval_T *t) #endif } -/* Returns 1 if t1 > t2 - * -1 if t1 < t2 - * 0 if t1 == t2 */ +/** Compare time values. + * @returns 1 if t1 > t2; + * -1 if t1 < t2; + * 0 if t1 == t2. */ int timeval_cmp(timeval_T *t1, timeval_T *t2) { diff --git a/src/util/time.h b/src/util/time.h index 7d81a7757..0f820dafc 100644 --- a/src/util/time.h +++ b/src/util/time.h @@ -16,19 +16,19 @@ typedef long milliseconds_T; #define ms_max(a, b) ((a) < (b) ? (b) : (a)) #define ms_min(a, b) ((a) < (b) ? (a) : (b)) -/* Bug 923: Assumes time_t values fit in long. */ +/** @bug 923: Assumes time_t values fit in @c long. */ #define str_to_time_t(s) ((time_t) atol(s)) -/* When formatting time_t values to be parsed with str_to_time_t, - * we first cast to time_print_T and then printf the result with - * TIME_PRINT_FORMAT. - * Bug 923: Assumes time_t values fit in long. */ +/** When formatting time_t values to be parsed with str_to_time_t(), + * we first cast to @c time_print_T and then printf() the result with + * ::TIME_PRINT_FORMAT. + * @bug 923: Assumes time_t values fit in @c long. */ typedef long time_print_T; -#define TIME_PRINT_FORMAT "ld" +#define TIME_PRINT_FORMAT "ld" /**< @see time_print_T */ -/* Redefine a timeval that has all fields signed so calculations +/** Redefine a timeval that has all fields signed so calculations * will be simplified on rare systems that define timeval with * unsigned fields. - * Bug 923: Assumes time_t values fit in long. (This structure is + * @bug 923: Assumes time_t values fit in long. (This structure is * used for both timestamps and durations.) */ typedef struct { long sec; long usec; } timeval_T;