Write @arg instead of @param arg in doc comments

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.