summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--src/alloc.h90
-rw-r--r--src/atomic.h4
-rw-r--r--src/bar.h4
-rw-r--r--src/bfstd.h110
-rw-r--r--src/bftw.h18
-rw-r--r--src/color.c12
-rw-r--r--src/color.h12
-rw-r--r--src/ctx.h16
-rw-r--r--src/dir.h18
-rw-r--r--src/dstring.h104
-rw-r--r--src/eval.h6
-rw-r--r--src/exec.h12
-rw-r--r--src/fsade.h12
-rw-r--r--src/ioq.h46
-rw-r--r--src/list.h120
-rw-r--r--src/mtab.h8
-rw-r--r--src/opt.h2
-rw-r--r--src/parse.h4
-rw-r--r--src/printf.h12
-rw-r--r--src/pwcache.h24
-rw-r--r--src/sighook.h18
-rw-r--r--src/stat.h8
-rw-r--r--src/trie.h32
-rw-r--r--src/typo.h4
-rw-r--r--src/xregex.h16
-rw-r--r--src/xspawn.h10
-rw-r--r--src/xtime.h12
27 files changed, 367 insertions, 367 deletions
diff --git a/src/alloc.h b/src/alloc.h
index 9bab01b..4f119e0 100644
--- a/src/alloc.h
+++ b/src/alloc.h
@@ -32,11 +32,11 @@ static inline size_t align_ceil(size_t align, size_t size) {
/**
* Saturating array size.
*
- * @param align
+ * @align
* Array element alignment.
- * @param size
+ * @size
* Array element size.
- * @param count
+ * @count
* Array element count.
* @return
* size * count, saturating to the maximum aligned value on overflow.
@@ -57,15 +57,15 @@ static inline size_t array_size(size_t align, size_t size, size_t count) {
/**
* Saturating flexible struct size.
*
- * @param align
+ * @align
* Struct alignment.
- * @param min
+ * @min
* Minimum struct size.
- * @param offset
+ * @offset
* Flexible array member offset.
- * @param size
+ * @size
* Flexible array element size.
- * @param count
+ * @count
* Flexible array element count.
* @return
* The size of the struct with count flexible array elements. Saturates
@@ -93,11 +93,11 @@ static inline size_t flex_size(size_t align, size_t min, size_t offset, size_t s
/**
* Computes the size of a flexible struct.
*
- * @param type
+ * @type
* The type of the struct containing the flexible array.
- * @param member
+ * @member
* The name of the flexible array member.
- * @param count
+ * @count
* The length of the flexible array.
* @return
* The size of the struct with count flexible array elements. Saturates
@@ -109,9 +109,9 @@ static inline size_t flex_size(size_t align, size_t min, size_t offset, size_t s
/**
* General memory allocator.
*
- * @param align
+ * @align
* The required alignment.
- * @param size
+ * @size
* The size of the allocation.
* @return
* The allocated memory, or NULL on failure.
@@ -123,9 +123,9 @@ void *alloc(size_t align, size_t size);
/**
* Zero-initialized memory allocator.
*
- * @param align
+ * @align
* The required alignment.
- * @param size
+ * @size
* The size of the allocation.
* @return
* The allocated memory, or NULL on failure.
@@ -161,13 +161,13 @@ void *zalloc(size_t align, size_t size);
/**
* Alignment-aware realloc().
*
- * @param ptr
+ * @ptr
* The pointer to reallocate.
- * @param align
+ * @align
* The required alignment.
- * @param old_size
+ * @old_size
* The previous allocation size.
- * @param new_size
+ * @new_size
* The new allocation size.
* @return
* The reallocated memory, or NULL on failure.
@@ -187,11 +187,11 @@ void *xrealloc(void *ptr, size_t align, size_t old_size, size_t new_size);
/**
* Reserve space for one more element in a dynamic array.
*
- * @param ptr
+ * @ptr
* The pointer to reallocate.
- * @param align
+ * @align
* The required alignment.
- * @param count
+ * @count
* The current size of the array.
* @return
* The reallocated memory, on both success *and* failure. On success,
@@ -205,11 +205,11 @@ void *reserve(void *ptr, size_t align, size_t size, size_t count);
/**
* Convenience macro to grow a dynamic array.
*
- * @param type
+ * @type
* The array element type.
- * @param type **ptr
+ * @type **ptr
* A pointer to the array.
- * @param size_t *count
+ * @size_t *count
* A pointer to the array's size.
* @return
* On success, a pointer to the newly reserved array element, i.e.
@@ -291,15 +291,15 @@ struct varena {
/**
* Initialize a varena for a struct with the given layout.
*
- * @param varena
+ * @varena
* The varena to initialize.
- * @param align
+ * @align
* alignof(type)
- * @param min
+ * @min
* sizeof(type)
- * @param offset
+ * @offset
* offsetof(type, flexible_array)
- * @param size
+ * @size
* sizeof(flexible_array[i])
*/
void varena_init(struct varena *varena, size_t align, size_t min, size_t offset, size_t size);
@@ -307,11 +307,11 @@ void varena_init(struct varena *varena, size_t align, size_t min, size_t offset,
/**
* Initialize a varena for the given type and flexible array.
*
- * @param varena
+ * @varena
* The varena to initialize.
- * @param type
+ * @type
* A struct type containing a flexible array.
- * @param member
+ * @member
* The name of the flexible array member.
*/
#define VARENA_INIT(varena, type, member) \
@@ -320,11 +320,11 @@ void varena_init(struct varena *varena, size_t align, size_t min, size_t offset,
/**
* Free an arena-allocated flexible struct.
*
- * @param varena
+ * @varena
* The that allocated the object.
- * @param ptr
+ * @ptr
* The object to free.
- * @param count
+ * @count
* The length of the flexible array.
*/
void varena_free(struct varena *varena, void *ptr, size_t count);
@@ -332,9 +332,9 @@ void varena_free(struct varena *varena, void *ptr, size_t count);
/**
* Arena-allocate a flexible struct.
*
- * @param varena
+ * @varena
* The varena to allocate from.
- * @param count
+ * @count
* The length of the flexible array.
* @return
* The allocated struct, or NULL on failure.
@@ -345,13 +345,13 @@ void *varena_alloc(struct varena *varena, size_t count);
/**
* Resize a flexible struct.
*
- * @param varena
+ * @varena
* The varena to allocate from.
- * @param ptr
+ * @ptr
* The object to resize.
- * @param old_count
+ * @old_count
* The old array length.
- * @param new_count
+ * @new_count
* The new array length.
* @return
* The resized struct, or NULL on failure.
@@ -362,11 +362,11 @@ void *varena_realloc(struct varena *varena, void *ptr, size_t old_count, size_t
/**
* Grow a flexible struct by an arbitrary amount.
*
- * @param varena
+ * @varena
* The varena to allocate from.
- * @param ptr
+ * @ptr
* The object to resize.
- * @param count
+ * @count
* Pointer to the flexible array length.
* @return
* The resized struct, or NULL on failure.
diff --git a/src/atomic.h b/src/atomic.h
index 2682c29..5c2826f 100644
--- a/src/atomic.h
+++ b/src/atomic.h
@@ -20,9 +20,9 @@
/**
* Shorthand for atomic_load_explicit().
*
- * @param obj
+ * @obj
* A pointer to the atomic object.
- * @param order
+ * @order
* The memory ordering to use, without the memory_order_ prefix.
* @return
* The loaded value.
diff --git a/src/bar.h b/src/bar.h
index 20d92a9..ec9e590 100644
--- a/src/bar.h
+++ b/src/bar.h
@@ -27,9 +27,9 @@ unsigned int bfs_bar_width(const struct bfs_bar *bar);
/**
* Update the status bar message.
*
- * @param bar
+ * @bar
* The status bar to update.
- * @param str
+ * @str
* The string to display.
* @return
* 0 on success, -1 on failure.
diff --git a/src/bfstd.h b/src/bfstd.h
index 557f253..97867fd 100644
--- a/src/bfstd.h
+++ b/src/bfstd.h
@@ -48,9 +48,9 @@
* Check if an error code is "like" another one. For example, ENOTDIR is
* like ENOENT because they can both be triggered by non-existent paths.
*
- * @param error
+ * @error
* The error code to check.
- * @param category
+ * @category
* The category to test for. Known categories include ENOENT and
* ENAMETOOLONG.
* @return
@@ -66,7 +66,7 @@ bool errno_is_like(int category);
/**
* Apply the "negative errno" convention.
*
- * @param ret
+ * @ret
* The return value of the attempted operation.
* @return
* ret, if non-negative, otherwise -errno.
@@ -106,7 +106,7 @@ int try(int ret);
/**
* Re-entrant dirname() variant that always allocates a copy.
*
- * @param path
+ * @path
* The path in question.
* @return
* The parent directory of the path.
@@ -116,7 +116,7 @@ char *xdirname(const char *path);
/**
* Re-entrant basename() variant that always allocates a copy.
*
- * @param path
+ * @path
* The path in question.
* @return
* The final component of the path.
@@ -126,7 +126,7 @@ char *xbasename(const char *path);
/**
* Find the offset of the final component of a path.
*
- * @param path
+ * @path
* The path in question.
* @return
* The offset of the basename.
@@ -138,9 +138,9 @@ size_t xbaseoff(const char *path);
/**
* fopen() variant that takes open() style flags.
*
- * @param path
+ * @path
* The path to open.
- * @param flags
+ * @flags
* Flags to pass to open().
*/
FILE *xfopen(const char *path, int flags);
@@ -148,9 +148,9 @@ FILE *xfopen(const char *path, int flags);
/**
* Convenience wrapper for getdelim().
*
- * @param file
+ * @file
* The file to read.
- * @param delim
+ * @delim
* The delimiter character to split on.
* @return
* The read chunk (without the delimiter), allocated with malloc().
@@ -161,7 +161,7 @@ char *xgetdelim(FILE *file, char delim);
/**
* Open the controlling terminal.
*
- * @param flags
+ * @flags
* The open() flags.
* @return
* An open file descriptor, or -1 on failure.
@@ -181,14 +181,14 @@ const char *xgetprogname(void);
/**
* Wrapper for strtoll() that forbids leading spaces.
*
- * @param str
+ * @str
* The string to parse.
- * @param end
+ * @end
* If non-NULL, will hold a pointer to the first invalid character.
* If NULL, the entire string must be valid.
- * @param base
+ * @base
* The base for the conversion, or 0 to auto-detect.
- * @param value
+ * @value
* Will hold the parsed integer value, on success.
* @return
* 0 on success, -1 on failure.
@@ -212,9 +212,9 @@ size_t asciilen(const char *str);
/**
* Get the length of the pure-ASCII prefix of a string.
*
- * @param str
+ * @str
* The string to check.
- * @param n
+ * @n
* The maximum prefix length.
*/
size_t asciinlen(const char *str, size_t n);
@@ -222,9 +222,9 @@ size_t asciinlen(const char *str, size_t n);
/**
* Allocate a copy of a region of memory.
*
- * @param src
+ * @src
* The memory region to copy.
- * @param size
+ * @size
* The size of the memory region.
* @return
* A copy of the region, allocated with malloc(), or NULL on failure.
@@ -234,12 +234,12 @@ void *xmemdup(const void *src, size_t size);
/**
* A nice string copying function.
*
- * @param dest
+ * @dest
* The NUL terminator of the destination string, or `end` if it is
* already truncated.
- * @param end
+ * @end
* The end of the destination buffer.
- * @param src
+ * @src
* The string to copy from.
* @return
* The new NUL terminator of the destination, or `end` on truncation.
@@ -249,14 +249,14 @@ char *xstpecpy(char *dest, char *end, const char *src);
/**
* A nice string copying function.
*
- * @param dest
+ * @dest
* The NUL terminator of the destination string, or `end` if it is
* already truncated.
- * @param end
+ * @end
* The end of the destination buffer.
- * @param src
+ * @src
* The string to copy from.
- * @param n
+ * @n
* The maximum number of characters to copy.
* @return
* The new NUL terminator of the destination, or `end` on truncation.
@@ -266,7 +266,7 @@ char *xstpencpy(char *dest, char *end, const char *src, size_t n);
/**
* Thread-safe strerror().
*
- * @param errnum
+ * @errnum
* An error number.
* @return
* A string describing that error, which remains valid until the next
@@ -282,9 +282,9 @@ const char *errstr(void);
/**
* Format a mode like ls -l (e.g. -rw-r--r--).
*
- * @param mode
+ * @mode
* The mode to format.
- * @param str
+ * @str
* The string to hold the formatted mode.
*/
void xstrmode(mode_t mode, char str[11]);
@@ -344,7 +344,7 @@ pid_t xwaitpid(pid_t pid, int *status, int flags);
/**
* Like dup(), but set the FD_CLOEXEC flag.
*
- * @param fd
+ * @fd
* The file descriptor to duplicate.
* @return
* A duplicated file descriptor, or -1 on failure.
@@ -354,7 +354,7 @@ int dup_cloexec(int fd);
/**
* Like pipe(), but set the FD_CLOEXEC flag.
*
- * @param pipefd
+ * @pipefd
* The array to hold the two file descriptors.
* @return
* 0 on success, -1 on failure.
@@ -383,7 +383,7 @@ size_t xwrite(int fd, const void *buf, size_t nbytes);
/**
* close() variant that preserves errno.
*
- * @param fd
+ * @fd
* The file descriptor to close.
*/
void close_quietly(int fd);
@@ -391,7 +391,7 @@ void close_quietly(int fd);
/**
* close() wrapper that asserts the file descriptor is valid.
*
- * @param fd
+ * @fd
* The file descriptor to close.
* @return
* 0 on success, or -1 on error.
@@ -406,11 +406,11 @@ int xfaccessat(int fd, const char *path, int amode);
/**
* readlinkat() wrapper that dynamically allocates the result.
*
- * @param fd
+ * @fd
* The base directory descriptor.
- * @param path
+ * @path
* The path to the link, relative to fd.
- * @param size
+ * @size
* An estimate for the size of the link name (pass 0 if unknown).
* @return
* The target of the link, allocated with malloc(), or NULL on failure.
@@ -420,7 +420,7 @@ char *xreadlinkat(int fd, const char *path, size_t size);
/**
* Wrapper for confstr() that allocates with malloc().
*
- * @param name
+ * @name
* The ID of the confstr to look up.
* @return
* The value of the confstr, or NULL on failure.
@@ -430,12 +430,12 @@ char *xconfstr(int name);
/**
* Portability wrapper for strtofflags().
*
- * @param str
+ * @str
* The string to parse. The pointee will be advanced to the first
* invalid position on error.
- * @param set
+ * @set
* The flags that are set in the string.
- * @param clear
+ * @clear
* The flags that are cleared in the string.
* @return
* 0 on success, -1 on failure.
@@ -452,7 +452,7 @@ long xsysconf(int name);
*
* [1]: https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/V1_chap02.html#tag_02_01_06
*
- * @param name
+ * @name
* The symbolic name of the POSIX option (e.g. SPAWN).
* @return
* The value of the option, either -1 or a date like 202405.
@@ -465,13 +465,13 @@ long xsysconf(int name);
/**
* Error-recovering mbrtowc() wrapper.
*
- * @param str
+ * @str
* The string to convert.
- * @param i
+ * @i
* The current index.
- * @param len
+ * @len
* The length of the string.
- * @param mb
+ * @mb
* The multi-byte decoding state.
* @return
* The wide character at index *i, or WEOF if decoding fails. In either
@@ -482,7 +482,7 @@ wint_t xmbrtowc(const char *str, size_t *i, size_t len, mbstate_t *mb);
/**
* wcswidth() variant that works on narrow strings.
*
- * @param str
+ * @str
* The string to measure.
* @return
* The likely width of that string in a terminal.
@@ -534,13 +534,13 @@ enum wesc_flags {
/**
* Escape a string as a single shell word.
*
- * @param dest
+ * @dest
* The destination string to fill.
- * @param end
+ * @end
* The end of the destination buffer.
- * @param src
+ * @src
* The string to escape.
- * @param flags
+ * @flags
* Controls which characters to escape.
* @return
* The new NUL terminator of the destination, or `end` on truncation.
@@ -550,15 +550,15 @@ char *wordesc(char *dest, char *end, const char *str, enum wesc_flags flags);
/**
* Escape a string as a single shell word.
*
- * @param dest
+ * @dest
* The destination string to fill.
- * @param end
+ * @end
* The end of the destination buffer.
- * @param src
+ * @src
* The string to escape.
- * @param n
+ * @n
* The maximum length of the string.
- * @param flags
+ * @flags
* Controls which characters to escape.
* @return
* The new NUL terminator of the destination, or `end` on truncation.
diff --git a/src/bftw.h b/src/bftw.h
index 28e0679..8b3ed7f 100644
--- a/src/bftw.h
+++ b/src/bftw.h
@@ -75,9 +75,9 @@ struct BFTW {
* Get bfs_stat() info for a file encountered during bftw(), caching the result
* whenever possible.
*
- * @param ftwbuf
+ * @ftwbuf
* bftw() data for the file to stat.
- * @param flags
+ * @flags
* flags for bfs_stat(). Pass ftwbuf->stat_flags for the default flags.
* @return
* A pointer to a bfs_stat() buffer, or NULL if the call failed.
@@ -88,9 +88,9 @@ const struct bfs_stat *bftw_stat(const struct BFTW *ftwbuf, enum bfs_stat_flags
* Get bfs_stat() info for a file encountered during bftw(), if it has already
* been cached.
*
- * @param ftwbuf
+ * @ftwbuf
* bftw() data for the file to stat.
- * @param flags
+ * @flags
* flags for bfs_stat(). Pass ftwbuf->stat_flags for the default flags.
* @return
* A pointer to a bfs_stat() buffer, or NULL if no stat info is cached.
@@ -102,9 +102,9 @@ const struct bfs_stat *bftw_cached_stat(const struct BFTW *ftwbuf, enum bfs_stat
* whether to follow links. This function will avoid calling bfs_stat() if
* possible.
*
- * @param ftwbuf
+ * @ftwbuf
* bftw() data for the file to check.
- * @param flags
+ * @flags
* flags for bfs_stat(). Pass ftwbuf->stat_flags for the default flags.
* @return
* The type of the file, or BFS_ERROR if an error occurred.
@@ -126,9 +126,9 @@ enum bftw_action {
/**
* Callback function type for bftw().
*
- * @param ftwbuf
+ * @ftwbuf
* Data about the current file.
- * @param ptr
+ * @ptr
* The pointer passed to bftw().
* @return
* An action value.
@@ -211,7 +211,7 @@ struct bftw_args {
* Like ftw(3) and nftw(3), this function walks a directory tree recursively,
* and invokes a callback for each path it encounters.
*
- * @param args
+ * @args
* The arguments that control the walk.
* @return
* 0 on success, or -1 on failure.
diff --git a/src/color.c b/src/color.c
index 1ee6662..37a22f9 100644
--- a/src/color.c
+++ b/src/color.c
@@ -277,9 +277,9 @@ fail:
/**
* The "smart case" algorithm.
*
- * @param ext
+ * @ext
* The current extension being added.
- * @param iext
+ * @iext
* The previous case-insensitive match, if any, for the same extension.
* @return
* Whether this extension should become case-sensitive.
@@ -418,13 +418,13 @@ static const struct esc_seq *get_ext(const struct colors *colors, const char *fi
*
* See man dir_colors.
*
- * @param str
+ * @str
* A dstring to fill with the unescaped chunk.
- * @param value
+ * @value
* The value to parse.
- * @param end
+ * @end
* The character that marks the end of the chunk.
- * @param[out] next
+ * @next (out)
* Will be set to the next chunk.
* @return
* 0 on success, -1 on failure.
diff --git a/src/color.h b/src/color.h
index 38f5ad7..2394af2 100644
--- a/src/color.h
+++ b/src/color.h
@@ -54,11 +54,11 @@ typedef struct CFILE {
/**
* Wrap an existing file into a colored stream.
*
- * @param file
+ * @file
* The underlying file.
- * @param colors
+ * @colors
* The color table to use if file is a TTY.
- * @param close
+ * @close
* Whether to close the underlying stream when this stream is closed.
* @return
* A colored wrapper around file.
@@ -68,7 +68,7 @@ CFILE *cfwrap(FILE *file, const struct colors *colors, bool close);
/**
* Close a colored file.
*
- * @param cfile
+ * @cfile
* The colored file to close.
* @return
* 0 on success, -1 on failure.
@@ -78,9 +78,9 @@ int cfclose(CFILE *cfile);
/**
* Colored, formatted output.
*
- * @param cfile
+ * @cfile
* The colored stream to print to.
- * @param format
+ * @format
* A printf()-style format string, supporting these format specifiers:
*
* %c: A single character
diff --git a/src/ctx.h b/src/ctx.h
index e532550..be6e2af 100644
--- a/src/ctx.h
+++ b/src/ctx.h
@@ -129,7 +129,7 @@ struct bfs_ctx *bfs_ctx_new(void);
/**
* Get the mount table.
*
- * @param ctx
+ * @ctx
* The bfs context.
* @return
* The cached mount table, or NULL on failure.
@@ -139,11 +139,11 @@ const struct bfs_mtab *bfs_ctx_mtab(const struct bfs_ctx *ctx);
/**
* Deduplicate an opened file.
*
- * @param ctx
+ * @ctx
* The bfs context.
- * @param cfile
+ * @cfile
* The opened file.
- * @param path
+ * @path
* The path to the opened file (or NULL for standard streams).
* @return
* If the same file was opened previously, that file is returned. If cfile is a new file,
@@ -154,7 +154,7 @@ struct CFILE *bfs_ctx_dedup(struct bfs_ctx *ctx, struct CFILE *cfile, const char
/**
* Flush any caches for consistency with external processes.
*
- * @param ctx
+ * @ctx
* The bfs context.
*/
void bfs_ctx_flush(const struct bfs_ctx *ctx);
@@ -162,9 +162,9 @@ void bfs_ctx_flush(const struct bfs_ctx *ctx);
/**
* Dump the parsed command line.
*
- * @param ctx
+ * @ctx
* The bfs context.
- * @param flag
+ * @flag
* The -D flag that triggered the dump.
*/
void bfs_ctx_dump(const struct bfs_ctx *ctx, enum debug_flags flag);
@@ -172,7 +172,7 @@ void bfs_ctx_dump(const struct bfs_ctx *ctx, enum debug_flags flag);
/**
* Free a bfs context.
*
- * @param ctx
+ * @ctx
* The context to free.
* @return
* 0 on success, -1 if any errors occurred.
diff --git a/src/dir.h b/src/dir.h
index 4482003..0040b95 100644
--- a/src/dir.h
+++ b/src/dir.h
@@ -87,7 +87,7 @@ struct arena;
/**
* Initialize an arena for directories.
*
- * @param arena
+ * @arena
* The arena to initialize.
*/
void bfs_dir_arena(struct arena *arena);
@@ -105,14 +105,14 @@ enum bfs_dir_flags {
/**
* Open a directory.
*
- * @param dir
+ * @dir
* The allocated directory.
- * @param at_fd
+ * @at_fd
* The base directory for path resolution.
- * @param at_path
+ * @at_path
* The path of the directory to open, relative to at_fd. Pass NULL to
* open at_fd itself.
- * @param flags
+ * @flags
* Flags that control which directory entries are listed.
* @return
* 0 on success, or -1 on failure.
@@ -127,7 +127,7 @@ int bfs_dirfd(const struct bfs_dir *dir);
/**
* Performs any I/O necessary for the next bfs_readdir() call.
*
- * @param dir
+ * @dir
* The directory to poll.
* @return
* 1 on success, 0 on EOF, or -1 on failure.
@@ -137,9 +137,9 @@ int bfs_polldir(struct bfs_dir *dir);
/**
* Read a directory entry.
*
- * @param dir
+ * @dir
* The directory to read.
- * @param[out] dirent
+ * @dirent (out)
* The directory entry to populate.
* @return
* 1 on success, 0 on EOF, or -1 on failure.
@@ -165,7 +165,7 @@ int bfs_closedir(struct bfs_dir *dir);
/**
* Detach the file descriptor from an open directory.
*
- * @param dir
+ * @dir
* The directory to detach.
* @return
* The file descriptor of the directory.
diff --git a/src/dstring.h b/src/dstring.h
index 79458e4..f7afcf7 100644
--- a/src/dstring.h
+++ b/src/dstring.h
@@ -31,7 +31,7 @@ typedef char dchar;
/**
* Free a dynamic string.
*
- * @param dstr
+ * @dstr
* The string to free.
*/
void dstrfree(dchar *dstr);
@@ -39,7 +39,7 @@ void dstrfree(dchar *dstr);
/**
* Allocate a dynamic string.
*
- * @param cap
+ * @cap
* The initial capacity of the string.
*/
_malloc(dstrfree, 1)
@@ -48,7 +48,7 @@ dchar *dstralloc(size_t cap);
/**
* Create a dynamic copy of a string.
*
- * @param str
+ * @str
* The NUL-terminated string to copy.
*/
_malloc(dstrfree, 1)
@@ -57,9 +57,9 @@ dchar *dstrdup(const char *str);
/**
* Create a length-limited dynamic copy of a string.
*
- * @param str
+ * @str
* The string to copy.
- * @param n
+ * @n
* The maximum number of characters to copy from str.
*/
_malloc(dstrfree, 1)
@@ -68,7 +68,7 @@ dchar *dstrndup(const char *str, size_t n);
/**
* Create a dynamic copy of a dynamic string.
*
- * @param dstr
+ * @dstr
* The dynamic string to copy.
*/
_malloc(dstrfree, 1)
@@ -77,9 +77,9 @@ dchar *dstrddup(const dchar *dstr);
/**
* Create an exact-sized dynamic copy of a string.
*
- * @param str
+ * @str
* The string to copy.
- * @param len
+ * @len
* The length of the string, which may include internal NUL bytes.
*/
_malloc(dstrfree, 1)
@@ -88,7 +88,7 @@ dchar *dstrxdup(const char *str, size_t len);
/**
* Get a dynamic string's length.
*
- * @param dstr
+ * @dstr
* The string to measure.
* @return
* The length of dstr.
@@ -98,9 +98,9 @@ size_t dstrlen(const dchar *dstr);
/**
* Reserve some capacity in a dynamic string.
*
- * @param dstr
+ * @dstr
* The dynamic string to preallocate.
- * @param cap
+ * @cap
* The new capacity for the string.
* @return
* 0 on success, -1 on failure.
@@ -110,9 +110,9 @@ int dstreserve(dchar **dstr, size_t cap);
/**
* Resize a dynamic string.
*
- * @param dstr
+ * @dstr
* The dynamic string to resize.
- * @param len
+ * @len
* The new length for the dynamic string.
* @return
* 0 on success, -1 on failure.
@@ -122,9 +122,9 @@ int dstresize(dchar **dstr, size_t len);
/**
* Append to a dynamic string.
*
- * @param dest
+ * @dest
* The destination dynamic string.
- * @param src
+ * @src
* The string to append.
* @return 0 on success, -1 on failure.
*/
@@ -133,11 +133,11 @@ int dstrcat(dchar **dest, const char *src);
/**
* Append to a dynamic string.
*
- * @param dest
+ * @dest
* The destination dynamic string.
- * @param src
+ * @src
* The string to append.
- * @param n
+ * @n
* The maximum number of characters to take from src.
* @return
* 0 on success, -1 on failure.
@@ -147,9 +147,9 @@ int dstrncat(dchar **dest, const char *src, size_t n);
/**
* Append a dynamic string to another dynamic string.
*
- * @param dest
+ * @dest
* The destination dynamic string.
- * @param src
+ * @src
* The dynamic string to append.
* @return
* 0 on success, -1 on failure.
@@ -159,11 +159,11 @@ int dstrdcat(dchar **dest, const dchar *src);
/**
* Append to a dynamic string.
*
- * @param dest
+ * @dest
* The destination dynamic string.
- * @param src
+ * @src
* The string to append.
- * @param len
+ * @len
* The exact number of characters to take from src.
* @return
* 0 on success, -1 on failure.
@@ -173,9 +173,9 @@ int dstrxcat(dchar **dest, const char *src, size_t len);
/**
* Append a single character to a dynamic string.
*
- * @param str
+ * @str
* The string to append to.
- * @param c
+ * @c
* The character to append.
* @return
* 0 on success, -1 on failure.
@@ -185,9 +185,9 @@ int dstrapp(dchar **str, char c);
/**
* Copy a string into a dynamic string.
*
- * @param dest
+ * @dest
* The destination dynamic string.
- * @param src
+ * @src
* The string to copy.
* @returns
* 0 on success, -1 on failure.
@@ -197,9 +197,9 @@ int dstrcpy(dchar **dest, const char *str);
/**
* Copy a dynamic string into another one.
*
- * @param dest
+ * @dest
* The destination dynamic string.
- * @param src
+ * @src
* The dynamic string to copy.
* @returns
* 0 on success, -1 on failure.
@@ -209,11 +209,11 @@ int dstrdcpy(dchar **dest, const dchar *str);
/**
* Copy a string into a dynamic string.
*
- * @param dest
+ * @dest
* The destination dynamic string.
- * @param src
+ * @src
* The dynamic string to copy.
- * @param n
+ * @n
* The maximum number of characters to take from src.
* @returns
* 0 on success, -1 on failure.
@@ -223,11 +223,11 @@ int dstrncpy(dchar **dest, const char *str, size_t n);
/**
* Copy a string into a dynamic string.
*
- * @param dest
+ * @dest
* The destination dynamic string.
- * @param src
+ * @src
* The dynamic string to copy.
- * @param len
+ * @len
* The exact number of characters to take from src.
* @returns
* 0 on success, -1 on failure.
@@ -237,9 +237,9 @@ int dstrxcpy(dchar **dest, const char *str, size_t len);
/**
* Create a dynamic string from a format string.
*
- * @param format
+ * @format
* The format string to fill in.
- * @param ...
+ * @...
* Any arguments for the format string.
* @return
* The created string, or NULL on failure.
@@ -250,9 +250,9 @@ dchar *dstrprintf(const char *format, ...);
/**
* Create a dynamic string from a format string and a va_list.
*
- * @param format
+ * @format
* The format string to fill in.
- * @param args
+ * @args
* The arguments for the format string.
* @return
* The created string, or NULL on failure.
@@ -263,11 +263,11 @@ dchar *dstrvprintf(const char *format, va_list args);
/**
* Format some text onto the end of a dynamic string.
*
- * @param str
+ * @str
* The destination dynamic string.
- * @param format
+ * @format
* The format string to fill in.
- * @param ...
+ * @...
* Any arguments for the format string.
* @return
* 0 on success, -1 on failure.
@@ -278,11 +278,11 @@ int dstrcatf(dchar **str, const char *format, ...);
/**
* Format some text from a va_list onto the end of a dynamic string.
*
- * @param str
+ * @str
* The destination dynamic string.
- * @param format
+ * @format
* The format string to fill in.
- * @param args
+ * @args
* The arguments for the format string.
* @return
* 0 on success, -1 on failure.
@@ -293,11 +293,11 @@ int dstrvcatf(dchar **str, const char *format, va_list args);
/**
* Concatenate while shell-escaping.
*
- * @param dest
+ * @dest
* The destination dynamic string.
- * @param str
+ * @str
* The string to escape.
- * @param flags
+ * @flags
* Flags for wordesc().
* @return
* 0 on success, -1 on failure.
@@ -307,13 +307,13 @@ int dstrescat(dchar **dest, const char *str, enum wesc_flags flags);
/**
* Concatenate while shell-escaping.
*
- * @param dest
+ * @dest
* The destination dynamic string.
- * @param str
+ * @str
* The string to escape.
- * @param n
+ * @n
* The maximum length of the string.
- * @param flags
+ * @flags
* Flags for wordesc().
* @return
* 0 on success, -1 on failure.
diff --git a/src/eval.h b/src/eval.h
index 48184c7..b038740 100644
--- a/src/eval.h
+++ b/src/eval.h
@@ -20,9 +20,9 @@ struct bfs_eval;
/**
* Expression evaluation function.
*
- * @param expr
+ * @expr
* The current expression.
- * @param state
+ * @state
* The current evaluation state.
* @return
* The result of the test.
@@ -32,7 +32,7 @@ typedef bool bfs_eval_fn(const struct bfs_expr *expr, struct bfs_eval *state);
/**
* Evaluate the command line.
*
- * @param ctx
+ * @ctx
* The bfs context to evaluate.
* @return
* EXIT_SUCCESS on success, otherwise on failure.
diff --git a/src/exec.h b/src/exec.h
index 9d4192d..1d8e75f 100644
--- a/src/exec.h
+++ b/src/exec.h
@@ -67,11 +67,11 @@ struct bfs_exec {
/**
* Parse an exec action.
*
- * @param argv
+ * @argv
* The (bfs) command line argument to parse.
- * @param flags
+ * @flags
* Any flags for this exec action.
- * @param ctx
+ * @ctx
* The bfs context.
* @return
* The parsed exec action, or NULL on failure.
@@ -81,9 +81,9 @@ struct bfs_exec *bfs_exec_parse(const struct bfs_ctx *ctx, char **argv, enum bfs
/**
* Execute the command for a file.
*
- * @param execbuf
+ * @execbuf
* The parsed exec action.
- * @param ftwbuf
+ * @ftwbuf
* The bftw() data for the current file.
* @return 0 if the command succeeded, -1 if it failed. If the command could
* be executed, -1 is returned, and errno will be non-zero. For
@@ -94,7 +94,7 @@ int bfs_exec(struct bfs_exec *execbuf, const struct BFTW *ftwbuf);
/**
* Finish executing any commands.
*
- * @param execbuf
+ * @execbuf
* The parsed exec action.
* @return 0 on success, -1 if any errors were encountered.
*/
diff --git a/src/fsade.h b/src/fsade.h
index 77cf82a..edac68b 100644
--- a/src/fsade.h
+++ b/src/fsade.h
@@ -26,7 +26,7 @@ struct BFTW;
/**
* Check if a file has a non-trivial Access Control List.
*
- * @param ftwbuf
+ * @ftwbuf
* The file to check.
* @return
* 1 if it does, 0 if it doesn't, or -1 if an error occurred.
@@ -36,7 +36,7 @@ int bfs_check_acl(const struct BFTW *ftwbuf);
/**
* Check if a file has a non-trivial capability set.
*
- * @param ftwbuf
+ * @ftwbuf
* The file to check.
* @return
* 1 if it does, 0 if it doesn't, or -1 if an error occurred.
@@ -46,7 +46,7 @@ int bfs_check_capabilities(const struct BFTW *ftwbuf);
/**
* Check if a file has any extended attributes set.
*
- * @param ftwbuf
+ * @ftwbuf
* The file to check.
* @return
* 1 if it does, 0 if it doesn't, or -1 if an error occurred.
@@ -56,9 +56,9 @@ int bfs_check_xattrs(const struct BFTW *ftwbuf);
/**
* Check if a file has an extended attribute with the given name.
*
- * @param ftwbuf
+ * @ftwbuf
* The file to check.
- * @param name
+ * @name
* The name of the xattr to check.
* @return
* 1 if it does, 0 if it doesn't, or -1 if an error occurred.
@@ -68,7 +68,7 @@ int bfs_check_xattr_named(const struct BFTW *ftwbuf, const char *name);
/**
* Get a file's SELinux context
*
- * @param ftwbuf
+ * @ftwbuf
* The file to check.
* @return
* The file's SELinux context, or NULL on failure.
diff --git a/src/ioq.h b/src/ioq.h
index 458c9e7..cb14be4 100644
--- a/src/ioq.h
+++ b/src/ioq.h
@@ -83,9 +83,9 @@ struct ioq_ent {
/**
* Create an I/O queue.
*
- * @param depth
+ * @depth
* The maximum depth of the queue.
- * @param nthreads
+ * @nthreads
* The maximum number of background threads.
* @return
* The new I/O queue, or NULL on failure.
@@ -100,11 +100,11 @@ size_t ioq_capacity(const struct ioq *ioq);
/**
* Asynchronous close().
*
- * @param ioq
+ * @ioq
* The I/O queue.
- * @param fd
+ * @fd
* The fd to close.
- * @param ptr
+ * @ptr
* An arbitrary pointer to associate with the request.
* @return
* 0 on success, or -1 on failure.
@@ -114,17 +114,17 @@ int ioq_close(struct ioq *ioq, int fd, void *ptr);
/**
* Asynchronous bfs_opendir().
*
- * @param ioq
+ * @ioq
* The I/O queue.
- * @param dir
+ * @dir
* The allocated directory.
- * @param dfd
+ * @dfd
* The base file descriptor.
- * @param path
+ * @path
* The path to open, relative to dfd.
- * @param flags
+ * @flags
* Flags that control which directory entries are listed.
- * @param ptr
+ * @ptr
* An arbitrary pointer to associate with the request.
* @return
* 0 on success, or -1 on failure.
@@ -134,11 +134,11 @@ int ioq_opendir(struct ioq *ioq, struct bfs_dir *dir, int dfd, const char *path,
/**
* Asynchronous bfs_closedir().
*
- * @param ioq
+ * @ioq
* The I/O queue.
- * @param dir
+ * @dir
* The directory to close.
- * @param ptr
+ * @ptr
* An arbitrary pointer to associate with the request.
* @return
* 0 on success, or -1 on failure.
@@ -148,17 +148,17 @@ int ioq_closedir(struct ioq *ioq, struct bfs_dir *dir, void *ptr);
/**
* Asynchronous bfs_stat().
*
- * @param ioq
+ * @ioq
* The I/O queue.
- * @param dfd
+ * @dfd
* The base file descriptor.
- * @param path
+ * @path
* The path to stat, relative to dfd.
- * @param flags
+ * @flags
* Flags that affect the lookup.
- * @param buf
+ * @buf
* A place to store the stat buffer, if successful.
- * @param ptr
+ * @ptr
* An arbitrary pointer to associate with the request.
* @return
* 0 on success, or -1 on failure.
@@ -168,7 +168,7 @@ int ioq_stat(struct ioq *ioq, int dfd, const char *path, enum bfs_stat_flags fla
/**
* Pop a response from the queue.
*
- * @param ioq
+ * @ioq
* The I/O queue.
* @return
* The next response, or NULL.
@@ -178,9 +178,9 @@ struct ioq_ent *ioq_pop(struct ioq *ioq, bool block);
/**
* Free a queue entry.
*
- * @param ioq
+ * @ioq
* The I/O queue.
- * @param ent
+ * @ent
* The entry to free.
*/
void ioq_free(struct ioq *ioq, struct ioq_ent *ent);
diff --git a/src/list.h b/src/list.h
index 6f96139..48f0d06 100644
--- a/src/list.h
+++ b/src/list.h
@@ -92,7 +92,7 @@
/**
* Initialize a singly-linked list.
*
- * @param list
+ * @list
* The list to initialize.
*
* ---
@@ -119,9 +119,9 @@
/**
* Initialize a singly-linked list item.
*
- * @param item
+ * @item
* The item to initialize.
- * @param node (optional)
+ * @node (optional)
* If specified, use item->node.next rather than item->next.
*
* ---
@@ -203,7 +203,7 @@
/**
* Get the head of a singly-linked list.
*
- * @param list
+ * @list
* The list in question.
* @return
* The first item in the list.
@@ -230,9 +230,9 @@
/**
* Get the tail of a singly-linked list.
*
- * @param list
+ * @list
* The list in question.
- * @param node (optional)
+ * @node (optional)
* If specified, use item->node.next rather than item->next.
* @return
* The last item in the list.
@@ -249,11 +249,11 @@
/**
* Check if an item is attached to a singly-linked list.
*
- * @param list
+ * @list
* The list to check.
- * @param item
+ * @item
* The item to check.
- * @param node (optional)
+ * @node (optional)
* If specified, use item->node.next rather than item->next.
* @return
* Whether the item is attached to the list.
@@ -270,13 +270,13 @@
/**
* Insert an item into a singly-linked list.
*
- * @param list
+ * @list
* The list to modify.
- * @param cursor
+ * @cursor
* A pointer to the item to insert after, e.g. &list->head or list->tail.
- * @param item
+ * @item
* The item to insert.
- * @param node (optional)
+ * @node (optional)
* If specified, use item->node.next rather than item->next.
* @return
* A cursor for the next item.
@@ -297,11 +297,11 @@
/**
* Add an item to the tail of a singly-linked list.
*
- * @param list
+ * @list
* The list to modify.
- * @param item
+ * @item
* The item to append.
- * @param node (optional)
+ * @node (optional)
* If specified, use item->node.next rather than item->next.
*/
#define SLIST_APPEND(list, ...) \
@@ -313,11 +313,11 @@
/**
* Add an item to the head of a singly-linked list.
*
- * @param list
+ * @list
* The list to modify.
- * @param item
+ * @item
* The item to prepend.
- * @param node (optional)
+ * @node (optional)
* If specified, use item->node.next rather than item->next.
*/
#define SLIST_PREPEND(list, ...) \
@@ -329,11 +329,11 @@
/**
* Splice a singly-linked list into another.
*
- * @param dest
+ * @dest
* The destination list.
- * @param cursor
+ * @cursor
* A pointer to the item to splice after, e.g. &list->head or list->tail.
- * @param src
+ * @src
* The source list.
*/
#define SLIST_SPLICE(dest, cursor, src) \
@@ -348,9 +348,9 @@
/**
* Add an entire singly-linked list to the tail of another.
*
- * @param dest
+ * @dest
* The destination list.
- * @param src
+ * @src
* The source list.
*/
#define SLIST_EXTEND(dest, src) \
@@ -359,11 +359,11 @@
/**
* Remove an item from a singly-linked list.
*
- * @param list
+ * @list
* The list to modify.
- * @param cursor
+ * @cursor
* A pointer to the item to remove, either &list->head or &prev->next.
- * @param node (optional)
+ * @node (optional)
* If specified, use item->node.next rather than item->next.
* @return
* The removed item.
@@ -396,9 +396,9 @@ static inline void *_slist_cast(uintptr_t ptr) {
/**
* Pop the head off a singly-linked list.
*
- * @param list
+ * @list
* The list to modify.
- * @param node (optional)
+ * @node (optional)
* If specified, use head->node.next rather than head->next.
* @return
* The popped item, or NULL if the list was empty.
@@ -415,13 +415,13 @@ static inline void *_slist_cast(uintptr_t ptr) {
/**
* Loop over the items in a singly-linked list.
*
- * @param type
+ * @type
* The list item type.
- * @param item
+ * @item
* The induction variable name.
- * @param list
+ * @list
* The list to iterate.
- * @param node (optional)
+ * @node (optional)
* If specified, use head->node.next rather than head->next.
*/
#define for_slist(type, item, ...) \
@@ -438,13 +438,13 @@ static inline void *_slist_cast(uintptr_t ptr) {
/**
* Loop over a singly-linked list, popping each item.
*
- * @param type
+ * @type
* The list item type.
- * @param item
+ * @item
* The induction variable name.
- * @param list
+ * @list
* The list to drain.
- * @param node (optional)
+ * @node (optional)
* If specified, use head->node.next rather than head->next.
*/
#define drain_slist(type, item, ...) \
@@ -453,7 +453,7 @@ static inline void *_slist_cast(uintptr_t ptr) {
/**
* Initialize a doubly-linked list.
*
- * @param list
+ * @list
* The list to initialize.
*/
#define LIST_INIT(list) \
@@ -472,9 +472,9 @@ static inline void *_slist_cast(uintptr_t ptr) {
/**
* Initialize a doubly-linked list item.
*
- * @param item
+ * @item
* The item to initialize.
- * @param node (optional)
+ * @node (optional)
* If specified, use item->node.next rather than item->next.
*/
#define LIST_ITEM_INIT(...) \
@@ -504,11 +504,11 @@ static inline void *_slist_cast(uintptr_t ptr) {
/**
* Add an item to the tail of a doubly-linked list.
*
- * @param list
+ * @list
* The list to modify.
- * @param item
+ * @item
* The item to append.
- * @param node (optional)
+ * @node (optional)
* If specified, use item->node.{prev,next} rather than item->{prev,next}.
*/
#define LIST_APPEND(list, ...) \
@@ -517,11 +517,11 @@ static inline void *_slist_cast(uintptr_t ptr) {
/**
* Add an item to the head of a doubly-linked list.
*
- * @param list
+ * @list
* The list to modify.
- * @param item
+ * @item
* The item to prepend.
- * @param node (optional)
+ * @node (optional)
* If specified, use item->node.{prev,next} rather than item->{prev,next}.
*/
#define LIST_PREPEND(list, ...) \
@@ -530,11 +530,11 @@ static inline void *_slist_cast(uintptr_t ptr) {
/**
* Check if an item is attached to a doubly-linked list.
*
- * @param list
+ * @list
* The list to check.
- * @param item
+ * @item
* The item to check.
- * @param node (optional)
+ * @node (optional)
* If specified, use item->node.{prev,next} rather than item->{prev,next}.
* @return
* Whether the item is attached to the list.
@@ -551,13 +551,13 @@ static inline void *_slist_cast(uintptr_t ptr) {
/**
* Insert into a doubly-linked list after the given cursor.
*
- * @param list
+ * @list
* The list to modify.
- * @param cursor
+ * @cursor
* Insert after this element.
- * @param item
+ * @item
* The item to insert.
- * @param node (optional)
+ * @node (optional)
* If specified, use item->node.{prev,next} rather than item->{prev,next}.
*/
#define LIST_INSERT(list, cursor, ...) \
@@ -576,11 +576,11 @@ static inline void *_slist_cast(uintptr_t ptr) {
/**
* Remove an item from a doubly-linked list.
*
- * @param list
+ * @list
* The list to modify.
- * @param item
+ * @item
* The item to remove.
- * @param node (optional)
+ * @node (optional)
* If specified, use item->node.{prev,next} rather than item->{prev,next}.
*/
#define LIST_REMOVE(list, ...) \
@@ -597,13 +597,13 @@ static inline void *_slist_cast(uintptr_t ptr) {
/**
* Loop over the items in a doubly-linked list.
*
- * @param type
+ * @type
* The list item type.
- * @param item
+ * @item
* The induction variable name.
- * @param list
+ * @list
* The list to iterate.
- * @param node (optional)
+ * @node (optional)
* If specified, use head->node.next rather than head->next.
*/
#define for_list(type, item, ...) \
diff --git a/src/mtab.h b/src/mtab.h
index 6c7d5cb..090392b 100644
--- a/src/mtab.h
+++ b/src/mtab.h
@@ -26,9 +26,9 @@ struct bfs_mtab *bfs_mtab_parse(void);
/**
* Determine the file system type that a file is on.
*
- * @param mtab
+ * @mtab
* The current mount table.
- * @param statbuf
+ * @statbuf
* The bfs_stat() buffer for the file in question.
* @return
* The type of file system containing this file, "unknown" if not known,
@@ -39,9 +39,9 @@ const char *bfs_fstype(const struct bfs_mtab *mtab, const struct bfs_stat *statb
/**
* Check if a file could be a mount point.
*
- * @param mtab
+ * @mtab
* The current mount table.
- * @param name
+ * @name
* The name of the file to check.
* @return
* Whether the named file could be a mount point.
diff --git a/src/opt.h b/src/opt.h
index 4aac129..a5729b3 100644
--- a/src/opt.h
+++ b/src/opt.h
@@ -13,7 +13,7 @@ struct bfs_ctx;
/**
* Apply optimizations to the command line.
*
- * @param ctx
+ * @ctx
* The bfs context to optimize.
* @return
* 0 if successful, -1 on error.
diff --git a/src/parse.h b/src/parse.h
index 6895c9f..fcc8234 100644
--- a/src/parse.h
+++ b/src/parse.h
@@ -11,9 +11,9 @@
/**
* Parse the command line.
*
- * @param argc
+ * @argc
* The number of arguments.
- * @param argv
+ * @argv
* The arguments to parse.
* @return
* A new bfs context, or NULL on failure.
diff --git a/src/printf.h b/src/printf.h
index 2bff087..e8d862e 100644
--- a/src/printf.h
+++ b/src/printf.h
@@ -22,11 +22,11 @@ struct bfs_printf;
/**
* Parse a -printf format string.
*
- * @param ctx
+ * @ctx
* The bfs context.
- * @param expr
+ * @expr
* The expression to fill in.
- * @param format
+ * @format
* The format string to parse.
* @return
* 0 on success, -1 on failure.
@@ -36,11 +36,11 @@ int bfs_printf_parse(const struct bfs_ctx *ctx, struct bfs_expr *expr, const cha
/**
* Evaluate a parsed format string.
*
- * @param cfile
+ * @cfile
* The CFILE to print to.
- * @param format
+ * @format
* The parsed printf format.
- * @param ftwbuf
+ * @ftwbuf
* The bftw() data for the current file.
* @return
* 0 on success, -1 on failure.
diff --git a/src/pwcache.h b/src/pwcache.h
index b6c0b67..d7c602d 100644
--- a/src/pwcache.h
+++ b/src/pwcache.h
@@ -27,9 +27,9 @@ struct bfs_users *bfs_users_new(void);
/**
* Get a user entry by name.
*
- * @param users
+ * @users
* The user cache.
- * @param name
+ * @name
* The username to look up.
* @return
* The matching user, or NULL if not found (errno == 0) or an error
@@ -40,9 +40,9 @@ const struct passwd *bfs_getpwnam(struct bfs_users *users, const char *name);
/**
* Get a user entry by ID.
*
- * @param users
+ * @users
* The user cache.
- * @param uid
+ * @uid
* The ID to look up.
* @return
* The matching user, or NULL if not found (errno == 0) or an error
@@ -53,7 +53,7 @@ const struct passwd *bfs_getpwuid(struct bfs_users *users, uid_t uid);
/**
* Flush a user cache.
*
- * @param users
+ * @users
* The cache to flush.
*/
void bfs_users_flush(struct bfs_users *users);
@@ -61,7 +61,7 @@ void bfs_users_flush(struct bfs_users *users);
/**
* Free a user cache.
*
- * @param users
+ * @users
* The user cache to free.
*/
void bfs_users_free(struct bfs_users *users);
@@ -82,9 +82,9 @@ struct bfs_groups *bfs_groups_new(void);
/**
* Get a group entry by name.
*
- * @param groups
+ * @groups
* The group cache.
- * @param name
+ * @name
* The group name to look up.
* @return
* The matching group, or NULL if not found (errno == 0) or an error
@@ -95,9 +95,9 @@ const struct group *bfs_getgrnam(struct bfs_groups *groups, const char *name);
/**
* Get a group entry by ID.
*
- * @param groups
+ * @groups
* The group cache.
- * @param uid
+ * @uid
* The ID to look up.
* @return
* The matching group, or NULL if not found (errno == 0) or an error
@@ -108,7 +108,7 @@ const struct group *bfs_getgrgid(struct bfs_groups *groups, gid_t gid);
/**
* Flush a group cache.
*
- * @param groups
+ * @groups
* The cache to flush.
*/
void bfs_groups_flush(struct bfs_groups *groups);
@@ -116,7 +116,7 @@ void bfs_groups_flush(struct bfs_groups *groups);
/**
* Free a group cache.
*
- * @param groups
+ * @groups
* The group cache to free.
*/
void bfs_groups_free(struct bfs_groups *groups);
diff --git a/src/sighook.h b/src/sighook.h
index 74d18c0..3bece21 100644
--- a/src/sighook.h
+++ b/src/sighook.h
@@ -27,11 +27,11 @@ enum sigflags {
* A signal hook callback. Hooks are executed from a signal handler, so must
* only call async-signal-safe functions.
*
- * @param sig
+ * @sig
* The signal number.
- * @param info
+ * @info
* Additional information about the signal.
- * @param arg
+ * @arg
* An arbitrary pointer passed to the hook.
*/
typedef void sighook_fn(int sig, siginfo_t *info, void *arg);
@@ -39,13 +39,13 @@ typedef void sighook_fn(int sig, siginfo_t *info, void *arg);
/**
* Install a hook for a signal.
*
- * @param sig
+ * @sig
* The signal to hook.
- * @param fn
+ * @fn
* The function to call.
- * @param arg
+ * @arg
* An argument passed to the function.
- * @param flags
+ * @flags
* Flags for the new hook.
* @return
* The installed hook, or NULL on failure.
@@ -56,9 +56,9 @@ struct sighook *sighook(int sig, sighook_fn *fn, void *arg, enum sigflags flags)
* On a best-effort basis, invoke the given hook just before the program is
* abnormally terminated by a signal.
*
- * @param fn
+ * @fn
* The function to call.
- * @param arg
+ * @arg
* An argument passed to the function.
* @return
* The installed hook, or NULL on failure.
diff --git a/src/stat.h b/src/stat.h
index 8d0bd9b..6adeb52 100644
--- a/src/stat.h
+++ b/src/stat.h
@@ -119,14 +119,14 @@ struct bfs_stat {
/**
* Facade over fstatat().
*
- * @param at_fd
+ * @at_fd
* The base file descriptor for the lookup.
- * @param at_path
+ * @at_path
* The path to stat, relative to at_fd. Pass NULL to fstat() at_fd
* itself.
- * @param flags
+ * @flags
* Flags that affect the lookup.
- * @param[out] buf
+ * @buf (out)
* A place to store the stat buffer, if successful.
* @return
* 0 on success, -1 on error.
diff --git a/src/trie.h b/src/trie.h
index 8f7f94b..318a23b 100644
--- a/src/trie.h
+++ b/src/trie.h
@@ -46,9 +46,9 @@ void trie_init(struct trie *trie);
/**
* Find the leaf for a string key.
*
- * @param trie
+ * @trie
* The trie to search.
- * @param key
+ * @key
* The key to look up.
* @return
* The found leaf, or NULL if the key is not present.
@@ -58,11 +58,11 @@ struct trie_leaf *trie_find_str(const struct trie *trie, const char *key);
/**
* Find the leaf for a fixed-size key.
*
- * @param trie
+ * @trie
* The trie to search.
- * @param key
+ * @key
* The key to look up.
- * @param length
+ * @length
* The length of the key in bytes.
* @return
* The found leaf, or NULL if the key is not present.
@@ -72,9 +72,9 @@ struct trie_leaf *trie_find_mem(const struct trie *trie, const void *key, size_t
/**
* Find the shortest leaf that starts with a given key.
*
- * @param trie
+ * @trie
* The trie to search.
- * @param key
+ * @key
* The key to look up.
* @return
* A leaf that starts with the given key, or NULL.
@@ -84,9 +84,9 @@ struct trie_leaf *trie_find_postfix(const struct trie *trie, const char *key);
/**
* Find the leaf that is the longest prefix of the given key.
*
- * @param trie
+ * @trie
* The trie to search.
- * @param key
+ * @key
* The key to look up.
* @return
* The longest prefix match for the given key, or NULL.
@@ -96,9 +96,9 @@ struct trie_leaf *trie_find_prefix(const struct trie *trie, const char *key);
/**
* Insert a string key into the trie.
*
- * @param trie
+ * @trie
* The trie to modify.
- * @param key
+ * @key
* The key to insert.
* @return
* The inserted leaf, or NULL on failure.
@@ -108,11 +108,11 @@ struct trie_leaf *trie_insert_str(struct trie *trie, const char *key);
/**
* Insert a fixed-size key into the trie.
*
- * @param trie
+ * @trie
* The trie to modify.
- * @param key
+ * @key
* The key to insert.
- * @param length
+ * @length
* The length of the key in bytes.
* @return
* The inserted leaf, or NULL on failure.
@@ -122,9 +122,9 @@ struct trie_leaf *trie_insert_mem(struct trie *trie, const void *key, size_t len
/**
* Remove a leaf from a trie.
*
- * @param trie
+ * @trie
* The trie to modify.
- * @param leaf
+ * @leaf
* The leaf to remove.
*/
void trie_remove(struct trie *trie, struct trie_leaf *leaf);
diff --git a/src/typo.h b/src/typo.h
index 13eaa67..b0daaf1 100644
--- a/src/typo.h
+++ b/src/typo.h
@@ -7,9 +7,9 @@
/**
* Find the "typo" distance between two strings.
*
- * @param actual
+ * @actual
* The actual string typed by the user.
- * @param expected
+ * @expected
* The expected valid string.
* @return The distance between the two strings.
*/
diff --git a/src/xregex.h b/src/xregex.h
index 750db24..3bf3535 100644
--- a/src/xregex.h
+++ b/src/xregex.h
@@ -42,13 +42,13 @@ enum bfs_regexec_flags {
/**
* Wrapper for regcomp() that supports additional regex types.
*
- * @param[out] preg
+ * @preg (out)
* Will hold the compiled regex.
- * @param pattern
+ * @pattern
* The regular expression to compile.
- * @param type
+ * @type
* The regular expression syntax to use.
- * @param flags
+ * @flags
* Regex compilation flags.
* @return
* 0 on success, -1 on failure.
@@ -58,11 +58,11 @@ int bfs_regcomp(struct bfs_regex **preg, const char *pattern, enum bfs_regex_typ
/**
* Wrapper for regexec().
*
- * @param regex
+ * @regex
* The regular expression to execute.
- * @param str
+ * @str
* The string to match against.
- * @param flags
+ * @flags
* Regex execution flags.
* @return
* 1 for a match, 0 for no match, -1 on failure.
@@ -77,7 +77,7 @@ void bfs_regfree(struct bfs_regex *regex);
/**
* Get a human-readable regex error message.
*
- * @param regex
+ * @regex
* The compiled regex.
* @return
* A human-readable description of the error, which should be free()'d.
diff --git a/src/xspawn.h b/src/xspawn.h
index 9cfbaf7..3c74ccd 100644
--- a/src/xspawn.h
+++ b/src/xspawn.h
@@ -109,13 +109,13 @@ int bfs_spawn_setrlimit(struct bfs_spawn *ctx, int resource, const struct rlimit
/**
* Spawn a new process.
*
- * @param exe
+ * @exe
* The executable to run.
- * @param ctx
+ * @ctx
* The context for the new process.
- * @param argv
+ * @argv
* The arguments for the new process.
- * @param envp
+ * @envp
* The environment variables for the new process (NULL for the current
* environment).
* @return
@@ -127,7 +127,7 @@ pid_t bfs_spawn(const char *exe, const struct bfs_spawn *ctx, char **argv, char
* Look up an executable in the current PATH, as BFS_SPAWN_USE_PATH or execvp()
* would do.
*
- * @param exe
+ * @exe
* The name of the binary to execute. Bare names without a '/' will be
* searched on the provided PATH.
* @return
diff --git a/src/xtime.h b/src/xtime.h
index a3547a7..7a1cf99 100644
--- a/src/xtime.h
+++ b/src/xtime.h
@@ -13,9 +13,9 @@
/**
* mktime() wrapper that reports errors more reliably.
*
- * @param[in,out] tm
+ * @tm (in+out)
* The struct tm to convert.
- * @param[out] timep
+ * @timep (out)
* A pointer to the result.
* @return
* 0 on success, -1 on failure.
@@ -25,9 +25,9 @@ int xmktime(struct tm *tm, time_t *timep);
/**
* A portable timegm(), the inverse of gmtime().
*
- * @param[in,out] tm
+ * @tm (in+out)
* The struct tm to convert.
- * @param[out] timep
+ * @timep (out)
* A pointer to the result.
* @return
* 0 on success, -1 on failure.
@@ -37,9 +37,9 @@ int xtimegm(struct tm *tm, time_t *timep);
/**
* Parse an ISO 8601-style timestamp.
*
- * @param[in] str
+ * @str
* The string to parse.
- * @param[out] result
+ * @result (out)
* A pointer to the result.
* @return
* 0 on success, -1 on failure.