Finish converting existing comments for internal API docs (#8146)

* Finish converting existing comments for internal API docs

99% of this was just reformatting existing comments. Only two exceptions:

- Expanded upon `BuildResult::status` compat note

- Split up file-level `symbol-table.hh` doc comments to get
  per-definition docs

Also fixed a few whitespace goofs, turning leading tabs to spaces and
removing trailing spaces.

Picking up from #8133

* Fix two things from comments

* Use triple-backtick not indent for `dumpPath`

* Convert GNU-style `\`..'` quotes to markdown style in API docs

This will render correctly.

7 files changed, 408 insertions, 206 deletions

diff --git a/src/libutil/ansicolor.hh b/src/libutil/ansicolor.hh
index 54721649c..86becafa6 100644
--- a/src/libutil/ansicolor.hh
+++ b/src/libutil/ansicolor.hh
@@ -1,9 +1,12 @@
 #pragma once
-///@file
+/**
+ * @file
+ *
+ * @brief Some ANSI escape sequences.
+ */
 
 namespace nix {
 
-/* Some ANSI escape sequences. */
 #define ANSI_NORMAL "\e[0m"
 #define ANSI_BOLD "\e[1m"
 #define ANSI_FAINT "\e[2m"
diff --git a/src/libutil/archive.hh b/src/libutil/archive.hh
index 60e33dd40..2cf164a41 100644
--- a/src/libutil/archive.hh
+++ b/src/libutil/archive.hh
@@ -20,39 +20,41 @@ namespace nix {
  *
  * The format is as follows:
  *
- *     IF path points to a REGULAR FILE:
- *       dump(path) = attrs(
- *         [ ("type", "regular")
- *         , ("contents", contents(path))
- *         ])
+ * ```
+ * IF path points to a REGULAR FILE:
+ *   dump(path) = attrs(
+ *     [ ("type", "regular")
+ *     , ("contents", contents(path))
+ *     ])
  *
- *     IF path points to a DIRECTORY:
- *       dump(path) = attrs(
- *         [ ("type", "directory")
- *         , ("entries", concat(map(f, sort(entries(path)))))
- *         ])
- *         where f(fn) = attrs(
- *           [ ("name", fn)
- *           , ("file", dump(path + "/" + fn))
- *           ])
+ * IF path points to a DIRECTORY:
+ *   dump(path) = attrs(
+ *     [ ("type", "directory")
+ *     , ("entries", concat(map(f, sort(entries(path)))))
+ *     ])
+ *     where f(fn) = attrs(
+ *       [ ("name", fn)
+ *       , ("file", dump(path + "/" + fn))
+ *       ])
  *
- *     where:
+ * where:
  *
- *       attrs(as) = concat(map(attr, as)) + encN(0)
- *       attrs((a, b)) = encS(a) + encS(b)
+ *   attrs(as) = concat(map(attr, as)) + encN(0)
+ *   attrs((a, b)) = encS(a) + encS(b)
  *
- *       encS(s) = encN(len(s)) + s + (padding until next 64-bit boundary)
+ *   encS(s) = encN(len(s)) + s + (padding until next 64-bit boundary)
  *
- *       encN(n) = 64-bit little-endian encoding of n.
+ *   encN(n) = 64-bit little-endian encoding of n.
  *
- *       contents(path) = the contents of a regular file.
+ *   contents(path) = the contents of a regular file.
  *
- *       sort(strings) = lexicographic sort by 8-bit value (strcmp).
+ *   sort(strings) = lexicographic sort by 8-bit value (strcmp).
  *
- *       entries(path) = the entries of a directory, without `.' and
- *       `..'.
+ *   entries(path) = the entries of a directory, without `.` and
+ *   `..`.
  *
- *       `+' denotes string concatenation.
+ *   `+` denotes string concatenation.
+ * ```
  */
 void dumpPath(const Path & path, Sink & sink,
     PathFilter & filter = defaultPathFilter);
@@ -88,7 +90,7 @@ struct ParseSink
 
 /**
  * If the NAR archive contains a single file at top-level, then save
- * the contents of the file to `s'.  Otherwise barf.
+ * the contents of the file to `s`.  Otherwise barf.
  */
 struct RetrieveRegularNARSink : ParseSink
 {
diff --git a/src/libutil/canon-path.hh b/src/libutil/canon-path.hh
index 76e48c4f2..614883c06 100644
--- a/src/libutil/canon-path.hh
+++ b/src/libutil/canon-path.hh
@@ -192,8 +192,10 @@ public:
      */
     bool isAllowed(const std::set<CanonPath> & allowed) const;
 
-    /* Return a representation `x` of `path` relative to `this`, i.e.
-       `CanonPath(this.makeRelative(x), this) == path`. */
+    /**
+     * Return a representation `x` of `path` relative to `this`, i.e.
+     * `CanonPath(this.makeRelative(x), this) == path`.
+     */
     std::string makeRelative(const CanonPath & path) const;
 };
 
diff --git a/src/libutil/error.hh b/src/libutil/error.hh
index eafc6a540..6a0923081 100644
--- a/src/libutil/error.hh
+++ b/src/libutil/error.hh
@@ -1,5 +1,19 @@
 #pragma once
-///@file
+/**
+ * @file
+ *
+ * @brief This file defines two main structs/classes used in nix error handling.
+ *
+ * ErrorInfo provides a standard payload of error information, with conversion to string
+ * happening in the logger rather than at the call site.
+ *
+ * BaseError is the ancestor of nix specific exceptions (and Interrupted), and contains
+ * an ErrorInfo.
+ *
+ * ErrorInfo structs are sent to the logger as part of an exception, or directly with the
+ * logError or logWarning macros.
+ * See libutil/tests/logging.cc for usage examples.
+ */
 
 #include "suggestions.hh"
 #include "ref.hh"
@@ -27,22 +41,6 @@
 
 namespace nix {
 
-/*
-
-   This file defines two main structs/classes used in nix error handling.
-
-   ErrorInfo provides a standard payload of error information, with conversion to string
-   happening in the logger rather than at the call site.
-
-   BaseError is the ancestor of nix specific exceptions (and Interrupted), and contains
-   an ErrorInfo.
-
-   ErrorInfo structs are sent to the logger as part of an exception, or directly with the
-   logError or logWarning macros.
-
-   See libutil/tests/logging.cc for usage examples.
-
- */
 
 typedef enum {
     lvlError = 0,
diff --git a/src/libutil/logging.hh b/src/libutil/logging.hh
index 576068c22..5aa6bee95 100644
--- a/src/libutil/logging.hh
+++ b/src/libutil/logging.hh
@@ -183,12 +183,17 @@ bool handleJSONLogMessage(const std::string & msg,
     const Activity & act, std::map<ActivityId, Activity> & activities,
     bool trusted);
 
-extern Verbosity verbosity; /* suppress msgs > this */
+/**
+ * suppress msgs > this
+ */
+extern Verbosity verbosity;
 
-/* Print a message with the standard ErrorInfo format.
-   In general, use these 'log' macros for reporting problems that may require user
-   intervention or that need more explanation.  Use the 'print' macros for more
-   lightweight status messages. */
+/**
+ * Print a message with the standard ErrorInfo format.
+ * In general, use these 'log' macros for reporting problems that may require user
+ * intervention or that need more explanation.  Use the 'print' macros for more
+ * lightweight status messages.
+ */
 #define logErrorInfo(level, errorInfo...) \
     do { \
         if ((level) <= nix::verbosity) {     \
@@ -199,9 +204,11 @@ extern Verbosity verbosity; /* suppress msgs > this */
 #define logError(errorInfo...) logErrorInfo(lvlError, errorInfo)
 #define logWarning(errorInfo...) logErrorInfo(lvlWarn, errorInfo)
 
-/* Print a string message if the current log level is at least the specified
-   level. Note that this has to be implemented as a macro to ensure that the
-   arguments are evaluated lazily. */
+/**
+ * Print a string message if the current log level is at least the specified
+ * level. Note that this has to be implemented as a macro to ensure that the
+ * arguments are evaluated lazily.
+ */
 #define printMsgUsing(loggerParam, level, args...) \
     do { \
         auto __lvl = level; \
diff --git a/src/libutil/thread-pool.hh b/src/libutil/thread-pool.hh
index 14b32279c..0e09fae97 100644
--- a/src/libutil/thread-pool.hh
+++ b/src/libutil/thread-pool.hh
@@ -40,15 +40,15 @@ public:
 
     /**
      * Execute work items until the queue is empty.
-     * 
-	 * \note Note that work items are allowed to add new items to the
-	 * queue; this is handled correctly.
      *
-	 * Queue processing stops prematurely if any work item throws an
-	 * exception. This exception is propagated to the calling thread. If
-	 * multiple work items throw an exception concurrently, only one
-	 * item is propagated; the others are printed on stderr and
-	 * otherwise ignored.
+     * \note Note that work items are allowed to add new items to the
+     * queue; this is handled correctly.
+     *
+     * Queue processing stops prematurely if any work item throws an
+     * exception. This exception is propagated to the calling thread. If
+     * multiple work items throw an exception concurrently, only one
+     * item is propagated; the others are printed on stderr and
+     * otherwise ignored.
      */
     void process();
 
diff --git a/src/libutil/util.hh b/src/libutil/util.hh
index 6c2706cc1..56160baaf 100644
--- a/src/libutil/util.hh
+++ b/src/libutil/util.hh
@@ -33,77 +33,112 @@ struct Sink;
 struct Source;
 
 
-/* The system for which Nix is compiled. */
+/**
+ * The system for which Nix is compiled.
+ */
 extern const std::string nativeSystem;
 
 
-/* Return an environment variable. */
+/**
+ * @return an environment variable.
+ */
 std::optional<std::string> getEnv(const std::string & key);
 
-/* Return a non empty environment variable. Returns nullopt if the env
-variable is set to "" */
+/**
+ * @return a non empty environment variable. Returns nullopt if the env
+ * variable is set to ""
+ */
 std::optional<std::string> getEnvNonEmpty(const std::string & key);
 
-/* Get the entire environment. */
+/**
+ * Get the entire environment.
+ */
 std::map<std::string, std::string> getEnv();
 
-/* Clear the environment. */
+/**
+ * Clear the environment.
+ */
 void clearEnv();
 
-/* Return an absolutized path, resolving paths relative to the
-   specified directory, or the current directory otherwise.  The path
-   is also canonicalised. */
+/**
+ * @return An absolutized path, resolving paths relative to the
+ * specified directory, or the current directory otherwise.  The path
+ * is also canonicalised.
+ */
 Path absPath(Path path,
     std::optional<PathView> dir = {},
     bool resolveSymlinks = false);
 
-/* Canonicalise a path by removing all `.' or `..' components and
-   double or trailing slashes.  Optionally resolves all symlink
-   components such that each component of the resulting path is *not*
-   a symbolic link. */
+/**
+ * Canonicalise a path by removing all `.` or `..` components and
+ * double or trailing slashes.  Optionally resolves all symlink
+ * components such that each component of the resulting path is *not*
+ * a symbolic link.
+ */
 Path canonPath(PathView path, bool resolveSymlinks = false);
 
-/* Return the directory part of the given canonical path, i.e.,
-   everything before the final `/'.  If the path is the root or an
-   immediate child thereof (e.g., `/foo'), this means `/'
-   is returned.*/
+/**
+ * @return The directory part of the given canonical path, i.e.,
+ * everything before the final `/`.  If the path is the root or an
+ * immediate child thereof (e.g., `/foo`), this means `/`
+ * is returned.
+ */
 Path dirOf(const PathView path);
 
-/* Return the base name of the given canonical path, i.e., everything
-   following the final `/' (trailing slashes are removed). */
+/**
+ * @return the base name of the given canonical path, i.e., everything
+ * following the final `/` (trailing slashes are removed).
+ */
 std::string_view baseNameOf(std::string_view path);
 
-/* Perform tilde expansion on a path. */
+/**
+ * Perform tilde expansion on a path.
+ */
 std::string expandTilde(std::string_view path);
 
-/* Check whether 'path' is a descendant of 'dir'. Both paths must be
-   canonicalized. */
+/**
+ * Check whether 'path' is a descendant of 'dir'. Both paths must be
+ * canonicalized.
+ */
 bool isInDir(std::string_view path, std::string_view dir);
 
-/* Check whether 'path' is equal to 'dir' or a descendant of
-   'dir'. Both paths must be canonicalized. */
+/**
+ * Check whether 'path' is equal to 'dir' or a descendant of
+ * 'dir'. Both paths must be canonicalized.
+ */
 bool isDirOrInDir(std::string_view path, std::string_view dir);
 
-/* Get status of `path'. */
+/**
+ * Get status of `path`.
+ */
 struct stat stat(const Path & path);
 struct stat lstat(const Path & path);
 
-/* Return true iff the given path exists. */
+/**
+ * @return true iff the given path exists.
+ */
 bool pathExists(const Path & path);
 
-/* Read the contents (target) of a symbolic link.  The result is not
-   in any way canonicalised. */
+/**
+ * Read the contents (target) of a symbolic link.  The result is not
+ * in any way canonicalised.
+ */
 Path readLink(const Path & path);
 
 bool isLink(const Path & path);
 
-/* Read the contents of a directory.  The entries `.' and `..' are
-   removed. */
+/**
+ * Read the contents of a directory.  The entries `.` and `..` are
+ * removed.
+ */
 struct DirEntry
 {
     std::string name;
     ino_t ino;
-    unsigned char type; // one of DT_*
+    /**
+     * one of DT_*
+     */
+    unsigned char type;
     DirEntry(std::string name, ino_t ino, unsigned char type)
         : name(std::move(name)), ino(ino), type(type) { }
 };
@@ -114,74 +149,110 @@ DirEntries readDirectory(const Path & path);
 
 unsigned char getFileType(const Path & path);
 
-/* Read the contents of a file into a string. */
+/**
+ * Read the contents of a file into a string.
+ */
 std::string readFile(int fd);
 std::string readFile(const Path & path);
 void readFile(const Path & path, Sink & sink);
 
-/* Write a string to a file. */
+/**
+ * Write a string to a file.
+ */
 void writeFile(const Path & path, std::string_view s, mode_t mode = 0666, bool sync = false);
 
 void writeFile(const Path & path, Source & source, mode_t mode = 0666, bool sync = false);
 
-/* Flush a file's parent directory to disk */
+/**
+ * Flush a file's parent directory to disk
+ */
 void syncParent(const Path & path);
 
-/* Read a line from a file descriptor. */
+/**
+ * Read a line from a file descriptor.
+ */
 std::string readLine(int fd);
 
-/* Write a line to a file descriptor. */
+/**
+ * Write a line to a file descriptor.
+ */
 void writeLine(int fd, std::string s);
 
-/* Delete a path; i.e., in the case of a directory, it is deleted
-   recursively. It's not an error if the path does not exist. The
-   second variant returns the number of bytes and blocks freed. */
+/**
+ * Delete a path; i.e., in the case of a directory, it is deleted
+ * recursively. It's not an error if the path does not exist. The
+ * second variant returns the number of bytes and blocks freed.
+ */
 void deletePath(const Path & path);
 
 void deletePath(const Path & path, uint64_t & bytesFreed);
 
 std::string getUserName();
 
-/* Return the given user's home directory from /etc/passwd. */
+/**
+ * @return the given user's home directory from /etc/passwd.
+ */
 Path getHomeOf(uid_t userId);
 
-/* Return $HOME or the user's home directory from /etc/passwd. */
+/**
+ * @return $HOME or the user's home directory from /etc/passwd.
+ */
 Path getHome();
 
-/* Return $XDG_CACHE_HOME or $HOME/.cache. */
+/**
+ * @return $XDG_CACHE_HOME or $HOME/.cache.
+ */
 Path getCacheDir();
 
-/* Return $XDG_CONFIG_HOME or $HOME/.config. */
+/**
+ * @return $XDG_CONFIG_HOME or $HOME/.config.
+ */
 Path getConfigDir();
 
-/* Return the directories to search for user configuration files */
+/**
+ * @return the directories to search for user configuration files
+ */
 std::vector<Path> getConfigDirs();
 
-/* Return $XDG_DATA_HOME or $HOME/.local/share. */
+/**
+ * @return $XDG_DATA_HOME or $HOME/.local/share.
+ */
 Path getDataDir();
 
-/* Return the path of the current executable. */
+/**
+ * @return the path of the current executable.
+ */
 std::optional<Path> getSelfExe();
 
-/* Return $XDG_STATE_HOME or $HOME/.local/state. */
+/**
+ * @return $XDG_STATE_HOME or $HOME/.local/state.
+ */
 Path getStateDir();
 
-/* Create the Nix state directory and return the path to it. */
+/**
+ * Create the Nix state directory and return the path to it.
+ */
 Path createNixStateDir();
 
-/* Create a directory and all its parents, if necessary.  Returns the
-   list of created directories, in order of creation. */
+/**
+ * Create a directory and all its parents, if necessary.  Returns the
+ * list of created directories, in order of creation.
+ */
 Paths createDirs(const Path & path);
 inline Paths createDirs(PathView path)
 {
     return createDirs(Path(path));
 }
 
-/* Create a symlink. */
+/**
+ * Create a symlink.
+ */
 void createSymlink(const Path & target, const Path & link,
     std::optional<time_t> mtime = {});
 
-/* Atomically create or replace a symlink. */
+/**
+ * Atomically create or replace a symlink.
+ */
 void replaceSymlink(const Path & target, const Path & link,
     std::optional<time_t> mtime = {});
 
@@ -197,24 +268,32 @@ void renameFile(const Path & src, const Path & dst);
 void moveFile(const Path & src, const Path & dst);
 
 
-/* Wrappers arount read()/write() that read/write exactly the
-   requested number of bytes. */
+/**
+ * Wrappers arount read()/write() that read/write exactly the
+ * requested number of bytes.
+ */
 void readFull(int fd, char * buf, size_t count);
 void writeFull(int fd, std::string_view s, bool allowInterrupts = true);
 
 MakeError(EndOfFile, Error);
 
 
-/* Read a file descriptor until EOF occurs. */
+/**
+ * Read a file descriptor until EOF occurs.
+ */
 std::string drainFD(int fd, bool block = true, const size_t reserveSize=0);
 
 void drainFD(int fd, Sink & sink, bool block = true);
 
-/* If cgroups are active, attempt to calculate the number of CPUs available.
-   If cgroups are unavailable or if cpu.max is set to "max", return 0. */
+/**
+ * If cgroups are active, attempt to calculate the number of CPUs available.
+ * If cgroups are unavailable or if cpu.max is set to "max", return 0.
+ */
 unsigned int getMaxCPU();
 
-/* Automatic cleanup of resources. */
+/**
+ * Automatic cleanup of resources.
+ */
 
 
 class AutoDelete
@@ -252,11 +331,15 @@ public:
 };
 
 
-/* Create a temporary directory. */
+/**
+ * Create a temporary directory.
+ */
 Path createTempDir(const Path & tmpRoot = "", const Path & prefix = "nix",
     bool includePid = true, bool useGlobalCounter = true, mode_t mode = 0755);
 
-/* Create a temporary file, returning a file handle and its path. */
+/**
+ * Create a temporary file, returning a file handle and its path.
+ */
 std::pair<AutoCloseFD, Path> createTempFile(const Path & prefix = "nix");
 
 
@@ -299,27 +382,36 @@ public:
 };
 
 
-/* Kill all processes running under the specified uid by sending them
-   a SIGKILL. */
+/**
+ * Kill all processes running under the specified uid by sending them
+ * a SIGKILL.
+ */
 void killUser(uid_t uid);
 
 
-/* Fork a process that runs the given function, and return the child
-   pid to the caller. */
+/**
+ * Fork a process that runs the given function, and return the child
+ * pid to the caller.
+ */
 struct ProcessOptions
 {
     std::string errorPrefix = "";
     bool dieWithParent = true;
     bool runExitHandlers = false;
     bool allowVfork = false;
-    int cloneFlags = 0; // use clone() with the specified flags (Linux only)
+    /**
+     * use clone() with the specified flags (Linux only)
+     */
+    int cloneFlags = 0;
 };
 
 pid_t startProcess(std::function<void()> fun, const ProcessOptions & options = ProcessOptions());
 
 
-/* Run a program and return its stdout in a string (i.e., like the
-   shell backtick operator). */
+/**
+ * Run a program and return its stdout in a string (i.e., like the
+ * shell backtick operator).
+ */
 std::string runProgram(Path program, bool searchPath = false,
     const Strings & args = Strings(),
     const std::optional<std::string> & input = {});
@@ -344,25 +436,35 @@ std::pair<int, std::string> runProgram(RunOptions && options);
 void runProgram2(const RunOptions & options);
 
 
-/* Change the stack size. */
+/**
+ * Change the stack size.
+ */
 void setStackSize(size_t stackSize);
 
 
-/* Restore the original inherited Unix process context (such as signal
-   masks, stack size). */
+/**
+ * Restore the original inherited Unix process context (such as signal
+ * masks, stack size).
+ */
 void restoreProcessContext(bool restoreMounts = true);
 
-/* Save the current mount namespace. Ignored if called more than
-   once. */
+/**
+ * Save the current mount namespace. Ignored if called more than
+ * once.
+ */
 void saveMountNamespace();
 
-/* Restore the mount namespace saved by saveMountNamespace(). Ignored
-   if saveMountNamespace() was never called. */
+/**
+ * Restore the mount namespace saved by saveMountNamespace(). Ignored
+ * if saveMountNamespace() was never called.
+ */
 void restoreMountNamespace();
 
-/* Cause this thread to not share any FS attributes with the main
-   thread, because this causes setns() in restoreMountNamespace() to
-   fail. */
+/**
+ * Cause this thread to not share any FS attributes with the main
+ * thread, because this causes setns() in restoreMountNamespace() to
+ * fail.
+ */
 void unshareFilesystem();
 
 
@@ -377,16 +479,22 @@ public:
     { }
 };
 
-/* Convert a list of strings to a null-terminated vector of char
-   *'s. The result must not be accessed beyond the lifetime of the
-   list of strings. */
+/**
+ * Convert a list of strings to a null-terminated vector of `char
+ * *`s. The result must not be accessed beyond the lifetime of the
+ * list of strings.
+ */
 std::vector<char *> stringsToCharPtrs(const Strings & ss);
 
-/* Close all file descriptors except those listed in the given set.
-   Good practice in child processes. */
+/**
+ * Close all file descriptors except those listed in the given set.
+ * Good practice in child processes.
+ */
 void closeMostFDs(const std::set<int> & exceptions);
 
-/* Set the close-on-exec flag for the given file descriptor. */
+/**
+ * Set the close-on-exec flag for the given file descriptor.
+ */
 void closeOnExec(int fd);
 
 
@@ -412,12 +520,16 @@ MakeError(Interrupted, BaseError);
 MakeError(FormatError, Error);
 
 
-/* String tokenizer. */
+/**
+ * String tokenizer.
+ */
 template<class C> C tokenizeString(std::string_view s, std::string_view separators = " \t\n\r");
 
 
-/* Concatenate the given strings with a separator between the
-   elements. */
+/**
+ * Concatenate the given strings with a separator between the
+ * elements.
+ */
 template<class C>
 std::string concatStringsSep(const std::string_view sep, const C & ss)
 {
@@ -442,7 +554,9 @@ auto concatStrings(Parts && ... parts)
 }
 
 
-/* Add quotes around a collection of strings. */
+/**
+ * Add quotes around a collection of strings.
+ */
 template<class C> Strings quoteStrings(const C & c)
 {
     Strings res;
@@ -451,16 +565,23 @@ template<class C> Strings quoteStrings(const C & c)
     return res;
 }
 
-/* Remove trailing whitespace from a string. FIXME: return
-   std::string_view. */
+/**
+ * Remove trailing whitespace from a string.
+ *
+ * \todo return std::string_view.
+ */
 std::string chomp(std::string_view s);
 
 
-/* Remove whitespace from the start and end of a string. */
+/**
+ * Remove whitespace from the start and end of a string.
+ */
 std::string trim(std::string_view s, std::string_view whitespace = " \n\r\t");
 
 
-/* Replace all occurrences of a string inside another string. */
+/**
+ * Replace all occurrences of a string inside another string.
+ */
 std::string replaceStrings(
     std::string s,
     std::string_view from,
@@ -470,14 +591,18 @@ std::string replaceStrings(
 std::string rewriteStrings(std::string s, const StringMap & rewrites);
 
 
-/* Convert the exit status of a child as returned by wait() into an
-   error string. */
+/**
+ * Convert the exit status of a child as returned by wait() into an
+ * error string.
+ */
 std::string statusToString(int status);
 
 bool statusOk(int status);
 
 
-/* Parse a string into an integer. */
+/**
+ * Parse a string into an integer.
+ */
 template<class N>
 std::optional<N> string2Int(const std::string_view s)
 {
@@ -490,8 +615,10 @@ std::optional<N> string2Int(const std::string_view s)
     }
 }
 
-/* Like string2Int(), but support an optional suffix 'K', 'M', 'G' or
-   'T' denoting a binary unit prefix. */
+/**
+ * Like string2Int(), but support an optional suffix 'K', 'M', 'G' or
+ * 'T' denoting a binary unit prefix.
+ */
 template<class N>
 N string2IntWithUnitPrefix(std::string_view s)
 {
@@ -512,7 +639,9 @@ N string2IntWithUnitPrefix(std::string_view s)
     throw UsageError("'%s' is not an integer", s);
 }
 
-/* Parse a string into a float. */
+/**
+ * Parse a string into a float.
+ */
 template<class N>
 std::optional<N> string2Float(const std::string_view s)
 {
@@ -524,7 +653,9 @@ std::optional<N> string2Float(const std::string_view s)
 }
 
 
-/* Convert a little-endian integer to host order. */
+/**
+ * Convert a little-endian integer to host order.
+ */
 template<typename T>
 T readLittleEndian(unsigned char * p)
 {
@@ -536,66 +667,90 @@ T readLittleEndian(unsigned char * p)
 }
 
 
-/* Return true iff `s' starts with `prefix'. */
+/**
+ * @return true iff `s` starts with `prefix`.
+ */
 bool hasPrefix(std::string_view s, std::string_view prefix);
 
 
-/* Return true iff `s' ends in `suffix'. */
+/**
+ * @return true iff `s` ends in `suffix`.
+ */
 bool hasSuffix(std::string_view s, std::string_view suffix);
 
 
-/* Convert a string to lower case. */
+/**
+ * Convert a string to lower case.
+ */
 std::string toLower(const std::string & s);
 
 
-/* Escape a string as a shell word. */
+/**
+ * Escape a string as a shell word.
+ */
 std::string shellEscape(const std::string_view s);
 
 
-/* Exception handling in destructors: print an error message, then
-   ignore the exception. */
+/**
+ * Exception handling in destructors: print an error message, then
+ * ignore the exception.
+ */
 void ignoreException(Verbosity lvl = lvlError);
 
 
 
-/* Tree formatting. */
+/**
+ * Tree formatting.
+ */
 constexpr char treeConn[] = "├───";
 constexpr char treeLast[] = "└───";
 constexpr char treeLine[] = "│   ";
 constexpr char treeNull[] = "    ";
 
-/* Determine whether ANSI escape sequences are appropriate for the
-   present output. */
+/**
+ * Determine whether ANSI escape sequences are appropriate for the
+ * present output.
+ */
 bool shouldANSI();
 
-/* Truncate a string to 'width' printable characters. If 'filterAll'
-   is true, all ANSI escape sequences are filtered out. Otherwise,
-   some escape sequences (such as colour setting) are copied but not
-   included in the character count. Also, tabs are expanded to
-   spaces. */
+/**
+ * Truncate a string to 'width' printable characters. If 'filterAll'
+ * is true, all ANSI escape sequences are filtered out. Otherwise,
+ * some escape sequences (such as colour setting) are copied but not
+ * included in the character count. Also, tabs are expanded to
+ * spaces.
+ */
 std::string filterANSIEscapes(std::string_view s,
     bool filterAll = false,
     unsigned int width = std::numeric_limits<unsigned int>::max());
 
 
-/* Base64 encoding/decoding. */
+/**
+ * Base64 encoding/decoding.
+ */
 std::string base64Encode(std::string_view s);
 std::string base64Decode(std::string_view s);
 
 
-/* Remove common leading whitespace from the lines in the string
-   's'. For example, if every line is indented by at least 3 spaces,
-   then we remove 3 spaces from the start of every line. */
+/**
+ * Remove common leading whitespace from the lines in the string
+ * 's'. For example, if every line is indented by at least 3 spaces,
+ * then we remove 3 spaces from the start of every line.
+ */
 std::string stripIndentation(std::string_view s);
 
 
-/* Get the prefix of 's' up to and excluding the next line break (LF
-   optionally preceded by CR), and the remainder following the line
-   break. */
+/**
+ * Get the prefix of 's' up to and excluding the next line break (LF
+ * optionally preceded by CR), and the remainder following the line
+ * break.
+ */
 std::pair<std::string_view, std::string_view> getLine(std::string_view s);
 
 
-/* Get a value for the specified key from an associate container. */
+/**
+ * Get a value for the specified key from an associate container.
+ */
 template <class T>
 const typename T::mapped_type * get(const T & map, const typename T::key_type & key)
 {
@@ -612,7 +767,9 @@ typename T::mapped_type * get(T & map, const typename T::key_type & key)
     return &i->second;
 }
 
-/* Get a value for the specified key from an associate container, or a default value if the key isn't present. */
+/**
+ * Get a value for the specified key from an associate container, or a default value if the key isn't present.
+ */
 template <class T>
 const typename T::mapped_type & getOr(T & map,
     const typename T::key_type & key,
@@ -623,7 +780,9 @@ const typename T::mapped_type & getOr(T & map,
     return i->second;
 }
 
-/* Remove and return the first item from a container. */
+/**
+ * Remove and return the first item from a container.
+ */
 template <class T>
 std::optional<typename T::value_type> remove_begin(T & c)
 {
@@ -635,7 +794,9 @@ std::optional<typename T::value_type> remove_begin(T & c)
 }
 
 
-/* Remove and return the first item from a container. */
+/**
+ * Remove and return the first item from a container.
+ */
 template <class T>
 std::optional<typename T::value_type> pop(T & c)
 {
@@ -650,8 +811,10 @@ template<typename T>
 class Callback;
 
 
-/* Start a thread that handles various signals. Also block those signals
-   on the current thread (and thus any threads created by it). */
+/**
+ * Start a thread that handles various signals. Also block those signals
+ * on the current thread (and thus any threads created by it).
+ */
 void startSignalHandlerThread();
 
 struct InterruptCallback
@@ -659,16 +822,20 @@ struct InterruptCallback
     virtual ~InterruptCallback() { };
 };
 
-/* Register a function that gets called on SIGINT (in a non-signal
-   context). */
+/**
+ * Register a function that gets called on SIGINT (in a non-signal
+ * context).
+ */
 std::unique_ptr<InterruptCallback> createInterruptCallback(
     std::function<void()> callback);
 
 void triggerInterrupt();
 
-/* A RAII class that causes the current thread to receive SIGUSR1 when
-   the signal handler thread receives SIGINT. That is, this allows
-   SIGINT to be multiplexed to multiple threads. */
+/**
+ * A RAII class that causes the current thread to receive SIGUSR1 when
+ * the signal handler thread receives SIGINT. That is, this allows
+ * SIGINT to be multiplexed to multiple threads.
+ */
 struct ReceiveInterrupts
 {
     pthread_t target;
@@ -682,8 +849,10 @@ struct ReceiveInterrupts
 
 
 
-/* A RAII helper that increments a counter on construction and
-   decrements it on destruction. */
+/**
+ * A RAII helper that increments a counter on construction and
+ * decrements it on destruction.
+ */
 template<typename T>
 struct MaintainCount
 {
@@ -694,33 +863,50 @@ struct MaintainCount
 };
 
 
-/* Return the number of rows and columns of the terminal. */
+/**
+ * @return the number of rows and columns of the terminal.
+ */
 std::pair<unsigned short, unsigned short> getWindowSize();
 
 
-/* Used in various places. */
+/**
+ * Used in various places.
+ */
 typedef std::function<bool(const Path & path)> PathFilter;
 
 extern PathFilter defaultPathFilter;
 
-/* Common initialisation performed in child processes. */
+/**
+ * Common initialisation performed in child processes.
+ */
 void commonChildInit();
 
-/* Create a Unix domain socket. */
+/**
+ * Create a Unix domain socket.
+ */
 AutoCloseFD createUnixDomainSocket();
 
-/* Create a Unix domain socket in listen mode. */
+/**
+ * Create a Unix domain socket in listen mode.
+ */
 AutoCloseFD createUnixDomainSocket(const Path & path, mode_t mode);
 
-/* Bind a Unix domain socket to a path. */
+/**
+ * Bind a Unix domain socket to a path.
+ */
 void bind(int fd, const std::string & path);
 
-/* Connect to a Unix domain socket. */
+/**
+ * Connect to a Unix domain socket.
+ */
 void connect(int fd, const std::string & path);
 
 
-// A Rust/Python-like enumerate() iterator adapter.
-// Borrowed from http://reedbeta.com/blog/python-like-enumerate-in-cpp17.
+/**
+ * A Rust/Python-like enumerate() iterator adapter.
+ *
+ * Borrowed from http://reedbeta.com/blog/python-like-enumerate-in-cpp17.
+ */
 template <typename T,
           typename TIter = decltype(std::begin(std::declval<T>())),
           typename = decltype(std::end(std::declval<T>()))>
@@ -746,7 +932,9 @@ constexpr auto enumerate(T && iterable)
 }
 
 
-// C++17 std::visit boilerplate
+/**
+ * C++17 std::visit boilerplate
+ */
 template<class... Ts> struct overloaded : Ts... { using Ts::operator()...; };
 template<class... Ts> overloaded(Ts...) -> overloaded<Ts...>;
 
@@ -754,8 +942,10 @@ template<class... Ts> overloaded(Ts...) -> overloaded<Ts...>;
 std::string showBytes(uint64_t bytes);
 
 
-/* Provide an addition operator between strings and string_views
-   inexplicably omitted from the standard library. */
+/**
+ * Provide an addition operator between strings and string_views
+ * inexplicably omitted from the standard library.
+ */
 inline std::string operator + (const std::string & s1, std::string_view s2)
 {
     auto s = s1;