From: Andre Noll Date: Thu, 1 Feb 2007 19:43:30 +0000 (+0100) Subject: string.c: Documentation update X-Git-Tag: v0.2.15~51 X-Git-Url: http://git.tuebingen.mpg.de/?p=paraslash.git;a=commitdiff_plain;h=45f29beab3d711b91e4d3551958173f53f1c5436 string.c: Documentation update - Add documentation of return value to all functions. - Replace \a by \p which looks nicer in the html output. - Clarify s_a_r documentation --- diff --git a/string.c b/string.c index 2bdc7e89..52c5183b 100644 --- a/string.c +++ b/string.c @@ -1,5 +1,5 @@ /* - * Copyright (C) 2004-2006 Andre Noll + * Copyright (C) 2004-2007 Andre Noll * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by @@ -37,6 +37,10 @@ * * A wrapper for realloc(3). It calls \p exit(\p EXIT_FAILURE) on errors, * i.e. there is no need to check the return value in the caller. + * + * \return A pointer to the newly allocated memory, which is suitably aligned + * for any kind of variable and may be different from \p p. + * * \sa realloc(3) */ __must_check __malloc void *para_realloc(void *p, size_t size) @@ -58,6 +62,10 @@ __must_check __malloc void *para_realloc(void *p, size_t size) * \param size desired new size * * A wrapper for malloc(3) which exits on errors. + * + * \return A pointer to the allocated memory, which is suitably aligned for any + * kind of variable. + * * \sa malloc(3) */ __must_check __malloc void *para_malloc(size_t size) @@ -77,6 +85,10 @@ __must_check __malloc void *para_malloc(size_t size) * \param size desired new size * * A wrapper for calloc(3) which exits on errors. + * + * A pointer to the allocated and zeroed-out memory, which is suitably aligned + * for any kind of variable. + * * \sa calloc(3) */ __must_check __malloc void *para_calloc(size_t size) @@ -90,12 +102,13 @@ __must_check __malloc void *para_calloc(size_t size) /** * paraslash's version of strdup() * - * \param s: string to be duplicated + * \param s string to be duplicated * - * A wrapper for strdup(3). It calls exit(EXIT_FAILURE) on - * errors, i.e. there is no need to check the return value in the caller. - * Moreover, this wrapper checks for \a s being NULL and returns an empty - * string in this case. + * A wrapper for strdup(3). It calls exit(EXIT_FAILURE) on errors, i.e. there + * is no need to check the return value in the caller. + * + * \return A pointer to the duplicated string. If \p s was the NULL pointer, + * an pointer to an empty string is returned. * * \sa strdup(3) */ @@ -114,9 +127,11 @@ __must_check __malloc char *para_strdup(const char *s) * * \param fmt usual format string * - * Produce output according to \a fmt. No artificial bound on the length of the - * resulting string is imposed. This function either returns a pointer to a - * string that must be freed by the caller or aborts without returning. + * Produce output according to \p fmt. No artificial bound on the length of the + * resulting string is imposed. + * + * \return This function either returns a pointer to a string that must be + * freed by the caller or aborts without returning. * * \sa printf(3) */ @@ -134,10 +149,12 @@ __must_check __printf_1_2 __malloc char *make_message(const char *fmt, ...) * \param a string to be appended to * \param b string to append * - * Append \a b to \a a. If \a a is NULL, return a copy of \a b, i.e. - * para_strcat(NULL, b) is equivalent to para_strdup(b). If \a b is NULL, - * return \a a without making a copy of \a a. Otherwise, construct the - * concatenation \a c, free \a a (but not \a b) and return \a c. + * Append \p b to \p a. + * + * \return If \p a is NULL, return a pointer to a copy of \p b, i.e. + * para_strcat(NULL, b) is equivalent to para_strdup(b). If \p b is NULL, + * return \p a without making a copy of \p a. Otherwise, construct the + * concatenation \p c, free \p a (but not \p b) and return \p c. * * \sa strcat(3) */ @@ -157,11 +174,13 @@ __must_check __malloc char *para_strcat(char *a, const char *b) /** * paraslash's version of dirname() * - * \param name pointer to The full path + * \param name pointer to the full path + * + * Compute the directory component of \p name * - * If \a name is \þ NULL or the empty string, return \p NULL, Otherwise, Make a - * copy of \a name and return its directory component. Caller is responsible to - * free the result. + * \return If \p name is \þ NULL or the empty string, return \p NULL. + * Otherwise, Make a copy of \p name and return its directory component. Caller + * is responsible to free the result. */ __must_check __malloc char *para_dirname(const char *name) { @@ -183,9 +202,11 @@ __must_check __malloc char *para_dirname(const char *name) * * \param name Pointer to the full path * - * If \a name is \p NULL or the empty string, return \p NULL, Otherwise, make a - * copy of \a name and return its filename component. Caller is responsible to - * free the result. + * Compute the filename component of \p name + * + * \return If \p name is \p NULL or the empty string, return \p NULL, + * Otherwise, make a copy of \p name and return its filename component. Caller + * is responsible to free the result. */ __must_check __malloc char *para_basename(const char *name) { @@ -209,12 +230,13 @@ __must_check __malloc char *para_basename(const char *name) * \param macro_name the name of the macro * \param replacement the replacement format string * - * Replace \a macro_name(arg) by \a replacement. \a replacement is a format - * string which may contain a single string conversion specifier which gets - * replaced by 'arg'. + * In \p src, replace each occurence of \p macro_name(arg) by the string + * determined by the \p replacement format string. \p replacement may (but + * needs not) contain a single string conversion specifier (%s) which gets + * replaced by \p arg. * - * \return A string in which all matches in \a src are replaced, or NULL if an - * syntax error was encountered. Caller must free the result. + * \return A string in which all matches in \p src are replaced, or \p NULL if + * an syntax error was encountered. Caller must free the result. * * \sa regcomp(3) */ @@ -266,7 +288,10 @@ out: * \param macro_list the array containing a macro/replacement pairs. * \param src the source string * - * This function just calls s_a_r() for each element of \a macro_list. + * This function just calls s_a_r() for each element of \p macro_list. + * + * \return \p NULL if one of the underlying calls to \p s_a_r returned \p NULL. + * Otherwise the completely expanded version of \p src is returned. */ __must_check __malloc char *s_a_r_list(struct para_macro *macro_list, char *src) { @@ -290,7 +315,7 @@ __must_check __malloc char *s_a_r_list(struct para_macro *macro_list, char *src) * * \param buf the string to be chopped. * - * Replace the last character in \a buf by zero if it is euqal to + * Replace the last character in \p buf by zero if it is euqal to * the newline character. */ void chop(char *buf) @@ -306,8 +331,11 @@ void chop(char *buf) * get a random filename * * This is by no means a secure way to create temporary files in a hostile - * direcory like /tmp. However, it is OK to use for temp files, fifos, sockets - * that are created in ~/.paraslash. Result must be freed by the caller. + * direcory like \p /tmp. However, it is OK to use for temp files, fifos, + * sockets that are created in ~/.paraslash. Result must be freed by the + * caller. + * + * \return a pointer to a random filename. */ __must_check __malloc char *para_tmpname(void) { @@ -325,7 +353,8 @@ __must_check __malloc char *para_tmpname(void) * * This wrapper for mkstemp additionally uses fchmod() to * set the given mode of the tempfile if mkstemp() returned success. - * Return value: The file descriptor of the temp file just created on success. + * + * \return The file descriptor of the temp file just created on success. * On errors, -E_MKSTEMP or -E_FCHMOD is returned. */ __must_check int para_mkstemp(char *template, mode_t mode) @@ -348,6 +377,8 @@ __must_check int para_mkstemp(char *template, mode_t mode) * \return A dynammically allocated string that must be freed by the caller. On * errors, the string "unknown user" is returned, i.e. this function never * returns NULL. + * + * \sa getpwuid(3) */ __must_check __malloc char *para_logname(void) { @@ -374,15 +405,14 @@ __must_check __malloc char *para_homedir(void) * \param argv_ptr pointer to the list of substrings * \param delim delimiter * - * This function modifies \a args by replacing each occurance of \a delim by + * This function modifies \p args by replacing each occurance of \p delim by * zero. A NULL-terminated array of pointers to char* is allocated dynamically * and these pointers are initialized to point to the broken-up substrings - * within \a args. A pointer to this array is returned via \a argv_ptr. It's OK - * to call this function with \a args == NULL. + * within \p args. A pointer to this array is returned via \p argv_ptr. It's OK + * to call this function with \p args \p == \p NULL. * - * \return The number of substrings found in \a args. + * \return The number of substrings found in \p args. */ - __must_check unsigned split_args(char *args, char ***argv_ptr, const char *delim) { char *p = args;