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.

src/libcmd/command-installable-value.cc

@@ -4,8 +4,8 @@ namespace nix {
 
 void InstallableValueCommand::run(ref<Store> store, ref<Installable> installable)
 {
-	auto installableValue = InstallableValue::require(installable);
+    auto installableValue = InstallableValue::require(installable);
-	run(store, installableValue);
+    run(store, installableValue);
 }
 
 }

src/libcmd/editor-for.hh

@@ -5,8 +5,10 @@
 
 namespace nix {
 
-/* Helper function to generate args that invoke $EDITOR on
+/**
-   filename:lineno. */
+ * Helper function to generate args that invoke $EDITOR on
+ * filename:lineno.
+ */
 Strings editorFor(const Path & file, uint32_t line);
 
 }

src/libcmd/installable-value.cc

@@ -22,7 +22,7 @@ InstallableValue::getCursor(EvalState & state)
 
 static UsageError nonValueInstallable(Installable & installable)
 {
-	return UsageError("installable '%s' does not correspond to a Nix language value", installable.what());
+    return UsageError("installable '%s' does not correspond to a Nix language value", installable.what());
 }
 
 InstallableValue & InstallableValue::require(Installable & installable)

src/libexpr/attr-path.hh

@@ -17,7 +17,9 @@ std::pair<Value *, PosIdx> findAlongAttrPath(
     Bindings & autoArgs,
     Value & vIn);
 
-/* Heuristic to find the filename and lineno or a nix value. */
+/**
+ * Heuristic to find the filename and lineno or a nix value.
+ */
 std::pair<std::string, uint32_t> findPackageFilename(EvalState & state, Value & v, std::string what);
 
 std::vector<Symbol> parseAttrPath(EvalState & state, std::string_view s);

src/libexpr/attr-set.hh

@@ -13,7 +13,9 @@ namespace nix {
 class EvalState;
 struct Value;
 
-/* Map one attribute name to its value. */
+/**
+ * Map one attribute name to its value.
+ */
 struct Attr
 {
     /* the placement of `name` and `pos` in this struct is important.
@@ -37,10 +39,12 @@ static_assert(sizeof(Attr) == 2 * sizeof(uint32_t) + sizeof(Value *),
     "avoid introducing any padding into Attr if at all possible, and do not "
     "introduce new fields that need not be present for almost every instance.");
 
-/* Bindings contains all the attributes of an attribute set. It is defined
+/**
-   by its size and its capacity, the capacity being the number of Attr
+ * Bindings contains all the attributes of an attribute set. It is defined
-   elements allocated after this structure, while the size corresponds to
+ * by its size and its capacity, the capacity being the number of Attr
-   the number of elements already inserted in this structure. */
+ * elements allocated after this structure, while the size corresponds to
+ * the number of elements already inserted in this structure.
+ */
 class Bindings
 {
 public:
@@ -95,7 +99,9 @@ public:
 
     size_t capacity() { return capacity_; }
 
-    /* Returns the attributes in lexicographically sorted order. */
+    /**
+     * Returns the attributes in lexicographically sorted order.
+     */
     std::vector<const Attr *> lexicographicOrder(const SymbolTable & symbols) const
     {
         std::vector<const Attr *> res;
@@ -112,9 +118,11 @@ public:
     friend class EvalState;
 };
 
-/* A wrapper around Bindings that ensures that its always in sorted
+/**
-   order at the end. The only way to consume a BindingsBuilder is to
+ * A wrapper around Bindings that ensures that its always in sorted
-   call finish(), which sorts the bindings. */
+ * order at the end. The only way to consume a BindingsBuilder is to
+ * call finish(), which sorts the bindings.
+ */
 class BindingsBuilder
 {
     Bindings * bindings;

src/libexpr/eval-cache.hh

@@ -110,8 +110,10 @@ public:
 
     ref<AttrCursor> getAttr(std::string_view name);
 
-    /* Get an attribute along a chain of attrsets. Note that this does
+    /**
-       not auto-call functors or functions. */
+     * Get an attribute along a chain of attrsets. Note that this does
+     * not auto-call functors or functions.
+     */
     OrSuggestions<ref<AttrCursor>> findAlongAttrPath(const std::vector<Symbol> & attrPath, bool force = false);
 
     std::string getString();
@@ -130,7 +132,9 @@ public:
 
     Value & forceValue();
 
-    /* Force creation of the .drv file in the Nix store. */
+    /**
+     * Force creation of the .drv file in the Nix store.
+     */
     StorePath forceDerivation();
 };
 

src/libexpr/eval-inline.hh

@@ -5,7 +5,9 @@
 
 namespace nix {
 
-/* Note: Various places expect the allocated memory to be zeroed. */
+/**
+ * Note: Various places expect the allocated memory to be zeroed.
+ */
 [[gnu::always_inline]]
 inline void * allocBytes(size_t n)
 {

src/libexpr/eval.hh

@@ -43,7 +43,10 @@ struct PrimOp
 struct Env
 {
     Env * up;
-    unsigned short prevWith:14; // nr of levels up to next `with' environment
+    /**
+     * Number of of levels up to next `with` environment
+     */
+    unsigned short prevWith:14;
     enum { Plain = 0, HasWithExpr, HasWithAttrs } type:2;
     Value * values[0];
 };
@@ -56,8 +59,10 @@ std::unique_ptr<ValMap> mapStaticEnvBindings(const SymbolTable & st, const Stati
 void copyContext(const Value & v, PathSet & context);
 
 
-/* Cache for calls to addToStore(); maps source paths to the store
+/**
-   paths. */
+ * Cache for calls to addToStore(); maps source paths to the store
+ * paths.
+ */
 typedef std::map<Path, StorePath> SrcToStore;
 
 
@@ -69,7 +74,9 @@ typedef std::pair<std::string, std::string> SearchPathElem;
 typedef std::list<SearchPathElem> SearchPath;
 
 
-/* Initialise the Boehm GC, if applicable. */
+/**
+ * Initialise the Boehm GC, if applicable.
+ */
 void initGC();
 
 
@@ -144,26 +151,36 @@ public:
         sOutputSpecified;
     Symbol sDerivationNix;
 
-    /* If set, force copying files to the Nix store even if they
+    /**
-       already exist there. */
+     * If set, force copying files to the Nix store even if they
+     * already exist there.
+     */
     RepairFlag repair;
 
-    /* The allowed filesystem paths in restricted or pure evaluation
+    /**
-       mode. */
+     * The allowed filesystem paths in restricted or pure evaluation
+     * mode.
+     */
     std::optional<PathSet> allowedPaths;
 
     Bindings emptyBindings;
 
-    /* Store used to materialise .drv files. */
+    /**
+     * Store used to materialise .drv files.
+     */
     const ref<Store> store;
 
-    /* Store used to build stuff. */
+    /**
+     * Store used to build stuff.
+     */
     const ref<Store> buildStore;
 
     RootValue vCallFlake = nullptr;
     RootValue vImportedDrvToDerivation = nullptr;
 
-    /* Debugger */
+    /**
+     * Debugger
+     */
     void (* debugRepl)(ref<EvalState> es, const ValMap & extraEnv);
     bool debugStop;
     bool debugQuit;
@@ -219,7 +236,9 @@ public:
 private:
     SrcToStore srcToStore;
 
-    /* A cache from path names to parse trees. */
+    /**
+     * A cache from path names to parse trees.
+     */
 #if HAVE_BOEHMGC
     typedef std::map<Path, Expr *, std::less<Path>, traceable_allocator<std::pair<const Path, Expr *>>> FileParseCache;
 #else
@@ -227,7 +246,9 @@ private:
 #endif
     FileParseCache fileParseCache;
 
-    /* A cache from path names to values. */
+    /**
+     * A cache from path names to values.
+     */
 #if HAVE_BOEHMGC
     typedef std::map<Path, Value, std::less<Path>, traceable_allocator<std::pair<const Path, Value>>> FileEvalCache;
 #else
@@ -239,17 +260,25 @@ private:
 
     std::map<std::string, std::pair<bool, std::string>> searchPathResolved;
 
-    /* Cache used by checkSourcePath(). */
+    /**
+     * Cache used by checkSourcePath().
+     */
     std::unordered_map<Path, Path> resolvedPaths;
 
-    /* Cache used by prim_match(). */
+    /**
+     * Cache used by prim_match().
+     */
     std::shared_ptr<RegexCache> regexCache;
 
 #if HAVE_BOEHMGC
-    /* Allocation cache for GC'd Value objects. */
+    /**
+     * Allocation cache for GC'd Value objects.
+     */
     std::shared_ptr<void *> valueAllocCache;
 
-    /* Allocation cache for size-1 Env objects. */
+    /**
+     * Allocation cache for size-1 Env objects.
+     */
     std::shared_ptr<void *> env1AllocCache;
 #endif
 
@@ -265,47 +294,65 @@ public:
 
     SearchPath getSearchPath() { return searchPath; }
 
-    /* Allow access to a path. */
+    /**
+     * Allow access to a path.
+     */
     void allowPath(const Path & path);
 
-    /* Allow access to a store path. Note that this gets remapped to
+    /**
-       the real store path if `store` is a chroot store. */
+     * Allow access to a store path. Note that this gets remapped to
+     * the real store path if `store` is a chroot store.
+     */
     void allowPath(const StorePath & storePath);
 
-    /* Allow access to a store path and return it as a string. */
+    /**
+     * Allow access to a store path and return it as a string.
+     */
     void allowAndSetStorePathString(const StorePath & storePath, Value & v);
 
-    /* Check whether access to a path is allowed and throw an error if
+    /**
-       not. Otherwise return the canonicalised path. */
+     * Check whether access to a path is allowed and throw an error if
+     * not. Otherwise return the canonicalised path.
+     */
     Path checkSourcePath(const Path & path);
 
     void checkURI(const std::string & uri);
 
-    /* When using a diverted store and 'path' is in the Nix store, map
+    /**
-       'path' to the diverted location (e.g. /nix/store/foo is mapped
+     * When using a diverted store and 'path' is in the Nix store, map
-       to /home/alice/my-nix/nix/store/foo). However, this is only
+     * 'path' to the diverted location (e.g. /nix/store/foo is mapped
-       done if the context is not empty, since otherwise we're
+     * to /home/alice/my-nix/nix/store/foo). However, this is only
-       probably trying to read from the actual /nix/store. This is
+     * done if the context is not empty, since otherwise we're
-       intended to distinguish between import-from-derivation and
+     * probably trying to read from the actual /nix/store. This is
-       sources stored in the actual /nix/store. */
+     * intended to distinguish between import-from-derivation and
+     * sources stored in the actual /nix/store.
+     */
     Path toRealPath(const Path & path, const PathSet & context);
 
-    /* Parse a Nix expression from the specified file. */
+    /**
+     * Parse a Nix expression from the specified file.
+     */
     Expr * parseExprFromFile(const Path & path);
     Expr * parseExprFromFile(const Path & path, std::shared_ptr<StaticEnv> & staticEnv);
 
-    /* Parse a Nix expression from the specified string. */
+    /**
+     * Parse a Nix expression from the specified string.
+     */
     Expr * parseExprFromString(std::string s, const Path & basePath, std::shared_ptr<StaticEnv> & staticEnv);
     Expr * parseExprFromString(std::string s, const Path & basePath);
 
     Expr * parseStdin();
 
-    /* Evaluate an expression read from the given file to normal
+    /**
-       form. Optionally enforce that the top-level expression is
+     * Evaluate an expression read from the given file to normal
-       trivial (i.e. doesn't require arbitrary computation). */
+     * form. Optionally enforce that the top-level expression is
+     * trivial (i.e. doesn't require arbitrary computation).
+     */
     void evalFile(const Path & path, Value & v, bool mustBeTrivial = false);
 
-    /* Like `evalFile`, but with an already parsed expression. */
+    /**
+     * Like `evalFile`, but with an already parsed expression.
+     */
     void cacheFile(
         const Path & path,
         const Path & resolvedPath,
@@ -315,37 +362,52 @@ public:
 
     void resetFileCache();
 
-    /* Look up a file in the search path. */
+    /**
+     * Look up a file in the search path.
+     */
     Path findFile(const std::string_view path);
     Path findFile(SearchPath & searchPath, const std::string_view path, const PosIdx pos = noPos);
 
-    /* If the specified search path element is a URI, download it. */
+    /**
+     * If the specified search path element is a URI, download it.
+     */
     std::pair<bool, std::string> resolveSearchPathElem(const SearchPathElem & elem);
 
-    /* Evaluate an expression to normal form, storing the result in
+    /**
-       value `v'. */
+     * Evaluate an expression to normal form
+     *
+     * @param [out] v The resulting is stored here.
+     */
     void eval(Expr * e, Value & v);
 
-    /* Evaluation the expression, then verify that it has the expected
+    /**
-       type. */
+     * Evaluation the expression, then verify that it has the expected
+     * type.
+     */
     inline bool evalBool(Env & env, Expr * e);
     inline bool evalBool(Env & env, Expr * e, const PosIdx pos, std::string_view errorCtx);
     inline void evalAttrs(Env & env, Expr * e, Value & v, const PosIdx pos, std::string_view errorCtx);
 
-    /* If `v' is a thunk, enter it and overwrite `v' with the result
+    /**
-       of the evaluation of the thunk.  If `v' is a delayed function
+     * If `v` is a thunk, enter it and overwrite `v` with the result
-       application, call the function and overwrite `v' with the
+     * of the evaluation of the thunk.  If `v` is a delayed function
-       result.  Otherwise, this is a no-op. */
+     * application, call the function and overwrite `v` with the
+     * result.  Otherwise, this is a no-op.
+     */
     inline void forceValue(Value & v, const PosIdx pos);
 
     template <typename Callable>
     inline void forceValue(Value & v, Callable getPos);
 
-    /* Force a value, then recursively force list elements and
+    /**
-       attributes. */
+     * Force a value, then recursively force list elements and
+     * attributes.
+     */
     void forceValueDeep(Value & v);
 
-    /* Force `v', and then verify that it has the expected type. */
+    /**
+     * Force `v`, and then verify that it has the expected type.
+     */
     NixInt forceInt(Value & v, const PosIdx pos, std::string_view errorCtx);
     NixFloat forceFloat(Value & v, const PosIdx pos, std::string_view errorCtx);
     bool forceBool(Value & v, const PosIdx pos, std::string_view errorCtx);
@@ -356,7 +418,10 @@ public:
     inline void forceAttrs(Value & v, Callable getPos, std::string_view errorCtx);
 
     inline void forceList(Value & v, const PosIdx pos, std::string_view errorCtx);
-    void forceFunction(Value & v, const PosIdx pos, std::string_view errorCtx); // either lambda or primop
+    /**
+     * @param v either lambda or primop
+     */
+    void forceFunction(Value & v, const PosIdx pos, std::string_view errorCtx);
     std::string_view forceString(Value & v, const PosIdx pos, std::string_view errorCtx);
     std::string_view forceString(Value & v, PathSet & context, const PosIdx pos, std::string_view errorCtx);
     std::string_view forceStringNoCtx(Value & v, const PosIdx pos, std::string_view errorCtx);
@@ -367,17 +432,23 @@ public:
     void addErrorTrace(Error & e, const PosIdx pos, const char * s, const std::string & s2, bool frame = false) const;
 
 public:
-    /* Return true iff the value `v' denotes a derivation (i.e. a
+    /**
-       set with attribute `type = "derivation"'). */
+     * @return true iff the value `v` denotes a derivation (i.e. a
+     * set with attribute `type = "derivation"`).
+     */
     bool isDerivation(Value & v);
 
     std::optional<std::string> tryAttrsToString(const PosIdx pos, Value & v,
         PathSet & context, bool coerceMore = false, bool copyToStore = true);
 
-    /* String coercion.  Converts strings, paths and derivations to a
+    /**
-       string.  If `coerceMore' is set, also converts nulls, integers,
+     * String coercion.
-       booleans and lists to a string.  If `copyToStore' is set,
+     *
-       referenced paths are copied to the Nix store as a side effect. */
+     * Converts strings, paths and derivations to a
+     * string.  If `coerceMore` is set, also converts nulls, integers,
+     * booleans and lists to a string.  If `copyToStore` is set,
+     * referenced paths are copied to the Nix store as a side effect.
+     */
     BackedStringView coerceToString(const PosIdx pos, Value & v, PathSet & context,
         std::string_view errorCtx,
         bool coerceMore = false, bool copyToStore = true,
@@ -385,21 +456,31 @@ public:
 
     StorePath copyPathToStore(PathSet & context, const Path & path);
 
-    /* Path coercion.  Converts strings, paths and derivations to a
+    /**
-       path.  The result is guaranteed to be a canonicalised, absolute
+     * Path coercion.
-       path.  Nothing is copied to the store. */
+     *
+     * Converts strings, paths and derivations to a
+     * path.  The result is guaranteed to be a canonicalised, absolute
+     * path.  Nothing is copied to the store.
+     */
     Path coerceToPath(const PosIdx pos, Value & v, PathSet & context, std::string_view errorCtx);
 
-    /* Like coerceToPath, but the result must be a store path. */
+    /**
+     * Like coerceToPath, but the result must be a store path.
+     */
     StorePath coerceToStorePath(const PosIdx pos, Value & v, PathSet & context, std::string_view errorCtx);
 
 public:
 
-    /* The base environment, containing the builtin functions and
+    /**
-       values. */
+     * The base environment, containing the builtin functions and
+     * values.
+     */
     Env & baseEnv;
 
-    /* The same, but used during parsing to resolve variables. */
+    /**
+     * The same, but used during parsing to resolve variables.
+     */
     std::shared_ptr<StaticEnv> staticBaseEnv; // !!! should be private
 
 private:
@@ -449,8 +530,10 @@ private:
 
 public:
 
-    /* Do a deep equality test between two values.  That is, list
+    /**
-       elements and attributes are compared recursively. */
+     * Do a deep equality test between two values.  That is, list
+     * elements and attributes are compared recursively.
+     */
     bool eqValues(Value & v1, Value & v2, const PosIdx pos, std::string_view errorCtx);
 
     bool isFunctor(Value & fun);
@@ -464,11 +547,15 @@ public:
         callFunction(fun, 1, args, vRes, pos);
     }
 
-    /* Automatically call a function for which each argument has a
+    /**
-       default value or has a binding in the `args' map. */
+     * Automatically call a function for which each argument has a
+     * default value or has a binding in the `args` map.
+     */
     void autoCallFunction(Bindings & args, Value & fun, Value & res);
 
-    /* Allocation primitives. */
+    /**
+     * Allocation primitives.
+     */
     inline Value * allocValue();
     inline Env & allocEnv(size_t size);
 
@@ -488,10 +575,13 @@ public:
 
     void concatLists(Value & v, size_t nrLists, Value * * lists, const PosIdx pos, std::string_view errorCtx);
 
-    /* Print statistics. */
+    /**
+     * Print statistics.
+     */
     void printStats();
 
-    /* Realise the given context, and return a mapping from the placeholders
+    /**
+     * Realise the given context, and return a mapping from the placeholders
      * used to construct the associated value to their final store path
      */
     [[nodiscard]] StringMap realiseContext(const PathSet & context);
@@ -551,11 +641,15 @@ struct DebugTraceStacker {
     DebugTrace trace;
 };
 
-/* Return a string representing the type of the value `v'. */
+/**
+ * @return A string representing the type of the value `v`.
+ */
 std::string_view showType(ValueType type);
 std::string showType(const Value & v);
 
-/* If `path' refers to a directory, then append "/default.nix". */
+/**
+ * If `path` refers to a directory, then append "/default.nix".
+ */
 Path resolveExprPath(Path path);
 
 struct InvalidPathError : EvalError

src/libexpr/flake/flake.hh

@@ -18,7 +18,8 @@ struct FlakeInput;
 
 typedef std::map<FlakeId, FlakeInput> FlakeInputs;
 
-/* FlakeInput is the 'Flake'-level parsed form of the "input" entries
+/**
+ * FlakeInput is the 'Flake'-level parsed form of the "input" entries
  * in the flake file.
  *
  * A FlakeInput is normally constructed by the 'parseFlakeInput'
@@ -42,7 +43,12 @@ typedef std::map<FlakeId, FlakeInput> FlakeInputs;
 struct FlakeInput
 {
     std::optional<FlakeRef> ref;
-    bool isFlake = true;  // true = process flake to get outputs, false = (fetched) static source path
+    /**
+     * true = process flake to get outputs
+     *
+     * false = (fetched) static source path
+     */
+    bool isFlake = true;
     std::optional<InputPath> follows;
     FlakeInputs overrides;
 };
@@ -56,23 +62,42 @@ struct ConfigFile
     void apply();
 };
 
-/* The contents of a flake.nix file. */
+/**
+ * The contents of a flake.nix file.
+ */
 struct Flake
 {
-    FlakeRef originalRef; // the original flake specification (by the user)
+    /**
-    FlakeRef resolvedRef; // registry references and caching resolved to the specific underlying flake
+     * The original flake specification (by the user)
-    FlakeRef lockedRef; // the specific local store result of invoking the fetcher
+     */
-    bool forceDirty = false; // pretend that 'lockedRef' is dirty
+    FlakeRef originalRef;
+    /**
+     * registry references and caching resolved to the specific underlying flake
+     */
+    FlakeRef resolvedRef;
+    /**
+     * the specific local store result of invoking the fetcher
+     */
+    FlakeRef lockedRef;
+    /**
+     * pretend that 'lockedRef' is dirty
+     */
+    bool forceDirty = false;
     std::optional<std::string> description;
     std::shared_ptr<const fetchers::Tree> sourceInfo;
     FlakeInputs inputs;
-    ConfigFile config; // 'nixConfig' attribute
+    /**
+     * 'nixConfig' attribute
+     */
+    ConfigFile config;
     ~Flake();
 };
 
 Flake getFlake(EvalState & state, const FlakeRef & flakeRef, bool allowLookup);
 
-/* Fingerprint of a locked flake; used as a cache key. */
+/**
+ * Fingerprint of a locked flake; used as a cache key.
+ */
 typedef Hash Fingerprint;
 
 struct LockedFlake
@@ -85,50 +110,72 @@ struct LockedFlake
 
 struct LockFlags
 {
-    /* Whether to ignore the existing lock file, creating a new one
+    /**
-       from scratch. */
+     * Whether to ignore the existing lock file, creating a new one
+     * from scratch.
+     */
     bool recreateLockFile = false;
 
-    /* Whether to update the lock file at all. If set to false, if any
+    /**
-       change to the lock file is needed (e.g. when an input has been
+     * Whether to update the lock file at all. If set to false, if any
-       added to flake.nix), you get a fatal error. */
+     * change to the lock file is needed (e.g. when an input has been
+     * added to flake.nix), you get a fatal error.
+     */
     bool updateLockFile = true;
 
-    /* Whether to write the lock file to disk. If set to true, if the
+    /**
-       any changes to the lock file are needed and the flake is not
+     * Whether to write the lock file to disk. If set to true, if the
-       writable (i.e. is not a local Git working tree or similar), you
+     * any changes to the lock file are needed and the flake is not
-       get a fatal error. If set to false, Nix will use the modified
+     * writable (i.e. is not a local Git working tree or similar), you
-       lock file in memory only, without writing it to disk. */
+     * get a fatal error. If set to false, Nix will use the modified
+     * lock file in memory only, without writing it to disk.
+     */
     bool writeLockFile = true;
 
-    /* Whether to use the registries to lookup indirect flake
+    /**
-       references like 'nixpkgs'. */
+     * Whether to use the registries to lookup indirect flake
+     * references like 'nixpkgs'.
+     */
     std::optional<bool> useRegistries = std::nullopt;
 
-    /* Whether to apply flake's nixConfig attribute to the configuration */
+    /**
+     * Whether to apply flake's nixConfig attribute to the configuration
+     */
 
     bool applyNixConfig = false;
 
-    /* Whether unlocked flake references (i.e. those without a Git
+    /**
-       revision or similar) without a corresponding lock are
+     * Whether unlocked flake references (i.e. those without a Git
-       allowed. Unlocked flake references with a lock are always
+     * revision or similar) without a corresponding lock are
-       allowed. */
+     * allowed. Unlocked flake references with a lock are always
+     * allowed.
+     */
     bool allowUnlocked = true;
 
-    /* Whether to commit changes to flake.lock. */
+    /**
+     * Whether to commit changes to flake.lock.
+     */
     bool commitLockFile = false;
 
-    /* The path to a lock file to read instead of the `flake.lock` file in the top-level flake */
+    /**
+     * The path to a lock file to read instead of the `flake.lock` file in the top-level flake
+     */
     std::optional<std::string> referenceLockFilePath;
 
-    /* The path to a lock file to write to instead of the `flake.lock` file in the top-level flake */
+    /**
+     * The path to a lock file to write to instead of the `flake.lock` file in the top-level flake
+     */
     std::optional<Path> outputLockFilePath;
 
-    /* Flake inputs to be overridden. */
+    /**
+     * Flake inputs to be overridden.
+     */
     std::map<InputPath, FlakeRef> inputOverrides;
 
-    /* Flake inputs to be updated. This means that any existing lock
+    /**
-       for those inputs will be ignored. */
+     * Flake inputs to be updated. This means that any existing lock
+     * for those inputs will be ignored.
+     */
     std::set<InputPath> inputUpdates;
 };
 

src/libexpr/flake/flakeref.hh

@@ -14,7 +14,8 @@ class Store;
 
 typedef std::string FlakeId;
 
-/* A flake reference specifies how to fetch a flake or raw source
+/**
+ * A flake reference specifies how to fetch a flake or raw source
  * (e.g. from a Git repository).  It is created from a URL-like syntax
  * (e.g. 'github:NixOS/patchelf'), an attrset representation (e.g. '{
  * type="github"; owner = "NixOS"; repo = "patchelf"; }'), or a local
@@ -33,14 +34,17 @@ typedef std::string FlakeId;
  * be lazy), but the fetcher can be invoked at any time via the
  * FlakeRef to ensure the store is populated with this input.
  */
-
 struct FlakeRef
 {
-    /* Fetcher-specific representation of the input, sufficient to
+    /**
-       perform the fetch operation. */
+     * Fetcher-specific representation of the input, sufficient to
+     * perform the fetch operation.
+     */
     fetchers::Input input;
 
-    /* sub-path within the fetched input that represents this input */
+    /**
+     * sub-path within the fetched input that represents this input
+     */
     Path subdir;
 
     bool operator==(const FlakeRef & other) const;

src/libexpr/flake/lockfile.hh

@@ -16,9 +16,11 @@ typedef std::vector<FlakeId> InputPath;
 
 struct LockedNode;
 
-/* A node in the lock file. It has outgoing edges to other nodes (its
+/**
-   inputs). Only the root node has this type; all other nodes have
+ * A node in the lock file. It has outgoing edges to other nodes (its
-   type LockedNode. */
+ * inputs). Only the root node has this type; all other nodes have
+ * type LockedNode.
+ */
 struct Node : std::enable_shared_from_this<Node>
 {
     typedef std::variant<ref<LockedNode>, InputPath> Edge;
@@ -28,7 +30,9 @@ struct Node : std::enable_shared_from_this<Node>
     virtual ~Node() { }
 };
 
-/* A non-root node in the lock file. */
+/**
+ * A non-root node in the lock file.
+ */
 struct LockedNode : Node
 {
     FlakeRef lockedRef, originalRef;
@@ -63,7 +67,9 @@ struct LockFile
 
     void write(const Path & path) const;
 
-    /* Check whether this lock file has any unlocked inputs. */
+    /**
+     * Check whether this lock file has any unlocked inputs.
+     */
     std::optional<FlakeRef> isUnlocked() const;
 
     bool operator ==(const LockFile & other) const;
@@ -74,7 +80,9 @@ struct LockFile
 
     static std::string diff(const LockFile & oldLocks, const LockFile & newLocks);
 
-    /* Check that every 'follows' input target exists. */
+    /**
+     * Check that every 'follows' input target exists.
+     */
     void check();
 };
 

src/libexpr/get-drvs.hh

@@ -26,7 +26,10 @@ private:
     mutable std::string outputName;
     Outputs outputs;
 
-    bool failed = false; // set if we get an AssertionError
+    /**
+     * Set if we get an AssertionError
+     */
+    bool failed = false;
 
     Bindings * attrs = nullptr, * meta = nullptr;
 
@@ -35,7 +38,10 @@ private:
     bool checkMeta(Value & v);
 
 public:
-    std::string attrPath; /* path towards the derivation */
+    /**
+     * path towards the derivation
+     */
+    std::string attrPath;
 
     DrvInfo(EvalState & state) : state(&state) { };
     DrvInfo(EvalState & state, std::string attrPath, Bindings * attrs);
@@ -47,8 +53,10 @@ public:
     StorePath requireDrvPath() const;
     StorePath queryOutPath() const;
     std::string queryOutputName() const;
-    /** Return the unordered map of output names to (optional) output paths.
+    /**
-     * The "outputs to install" are determined by `meta.outputsToInstall`. */
+     * Return the unordered map of output names to (optional) output paths.
+     * The "outputs to install" are determined by `meta.outputsToInstall`.
+     */
     Outputs queryOutputs(bool withPaths = true, bool onlyOutputsToInstall = false);
 
     StringSet queryMetaNames();
@@ -80,8 +88,10 @@ typedef std::list<DrvInfo> DrvInfos;
 #endif
 
 
-/* If value `v' denotes a derivation, return a DrvInfo object
+/**
-   describing it. Otherwise return nothing. */
+ * If value `v` denotes a derivation, return a DrvInfo object
+ * describing it. Otherwise return nothing.
+ */
 std::optional<DrvInfo> getDerivation(EvalState & state,
     Value & v, bool ignoreAssertionFailures);
 

src/libexpr/nixexpr.hh

@@ -22,7 +22,9 @@ MakeError(UndefinedVarError, Error);
 MakeError(MissingArgumentError, EvalError);
 MakeError(RestrictedPathError, Error);
 
-/* Position objects. */
+/**
+ * Position objects.
+ */
 struct Pos
 {
     uint32_t line;
@@ -133,7 +135,9 @@ class EvalState;
 struct StaticEnv;
 
 
-/* An attribute path is a sequence of attribute names. */
+/**
+ * An attribute path is a sequence of attribute names.
+ */
 struct AttrName
 {
     Symbol symbol;
@@ -213,11 +217,11 @@ struct ExprVar : Expr
        or function argument) or from a "with". */
     bool fromWith;
 
-    /* In the former case, the value is obtained by going `level'
+    /* In the former case, the value is obtained by going `level`
        levels up from the current environment and getting the
-       `displ'th value in that environment.  In the latter case, the
+       `displ`th value in that environment.  In the latter case, the
-       value is obtained by getting the attribute named `name' from
+       value is obtained by getting the attribute named `name` from
-       the set stored in the environment that is `level' levels up
+       the set stored in the environment that is `level` levels up
        from the current one.*/
     Level level;
     Displacement displ;

src/libexpr/primops.hh

@@ -23,9 +23,11 @@ struct RegisterPrimOp
     typedef std::vector<Info> PrimOps;
     static PrimOps * primOps;
 
-    /* You can register a constant by passing an arity of 0. fun
+    /**
-       will get called during EvalState initialization, so there
+     * You can register a constant by passing an arity of 0. fun
-       may be primops not yet added and builtins is not yet sorted. */
+     * will get called during EvalState initialization, so there
+     * may be primops not yet added and builtins is not yet sorted.
+     */
     RegisterPrimOp(
         std::string name,
         size_t arity,
@@ -38,10 +40,14 @@ struct RegisterPrimOp
    may wish to use them in limited contexts without globally enabling
    them. */
 
-/* Load a ValueInitializer from a DSO and return whatever it initializes */
+/**
+ * Load a ValueInitializer from a DSO and return whatever it initializes
+ */
 void prim_importNative(EvalState & state, const PosIdx pos, Value * * args, Value & v);
 
-/* Execute a program and parse its output */
+/**
+ * Execute a program and parse its output
+ */
 void prim_exec(EvalState & state, const PosIdx pos, Value * * args, Value & v);
 
 }

src/libexpr/symbol-table.hh

@@ -10,15 +10,11 @@
 
 namespace nix {
 
-/* Symbol table used by the parser and evaluator to represent and look
+/**
-   up identifiers and attributes efficiently.  SymbolTable::create()
+ * This class mainly exists to give us an operator<< for ostreams. We could also
-   converts a string into a symbol.  Symbols have the property that
+ * return plain strings from SymbolTable, but then we'd have to wrap every
-   they can be compared efficiently (using an equality test),
+ * instance of a symbol that is fmt()ed, which is inconvenient and error-prone.
-   because the symbol table stores only one copy of each string. */
+ */
-
-/* This class mainly exists to give us an operator<< for ostreams. We could also
-   return plain strings from SymbolTable, but then we'd have to wrap every
-   instance of a symbol that is fmt()ed, which is inconvenient and error-prone. */
 class SymbolStr
 {
     friend class SymbolTable;
@@ -47,6 +43,11 @@ public:
     friend std::ostream & operator <<(std::ostream & os, const SymbolStr & symbol);
 };
 
+/**
+ * Symbols have the property that they can be compared efficiently
+ * (using an equality test), because the symbol table stores only one
+ * copy of each string.
+ */
 class Symbol
 {
     friend class SymbolTable;
@@ -66,6 +67,10 @@ public:
     bool operator!=(const Symbol other) const { return id != other.id; }
 };
 
+/**
+ * Symbol table used by the parser and evaluator to represent and look
+ * up identifiers and attributes efficiently.
+ */
 class SymbolTable
 {
 private:
@@ -74,6 +79,9 @@ private:
 
 public:
 
+    /**
+     * converts a string into a symbol.
+     */
     Symbol create(std::string_view s)
     {
         // Most symbols are looked up more than once, so we trade off insertion performance

src/libexpr/value.hh

@@ -36,9 +36,11 @@ typedef enum {
     tFloat
 } InternalType;
 
-// This type abstracts over all actual value types in the language,
+/**
-// grouping together implementation details like tList*, different function
+ * This type abstracts over all actual value types in the language,
-// types, and types in non-normal form (so thunks and co.)
+ * grouping together implementation details like tList*, different function
+ * types, and types in non-normal form (so thunks and co.)
+ */
 typedef enum {
     nThunk,
     nInt,
@@ -70,38 +72,51 @@ class XMLWriter;
 typedef int64_t NixInt;
 typedef double NixFloat;
 
-/* External values must descend from ExternalValueBase, so that
+/**
+ * External values must descend from ExternalValueBase, so that
  * type-agnostic nix functions (e.g. showType) can be implemented
  */
 class ExternalValueBase
 {
     friend std::ostream & operator << (std::ostream & str, const ExternalValueBase & v);
     protected:
-    /* Print out the value */
+    /**
+     * Print out the value
+     */
     virtual std::ostream & print(std::ostream & str) const = 0;
 
     public:
-    /* Return a simple string describing the type */
+    /**
+     * Return a simple string describing the type
+     */
     virtual std::string showType() const = 0;
 
-    /* Return a string to be used in builtins.typeOf */
+    /**
+     * Return a string to be used in builtins.typeOf
+     */
     virtual std::string typeOf() const = 0;
 
-    /* Coerce the value to a string. Defaults to uncoercable, i.e. throws an
+    /**
+     * Coerce the value to a string. Defaults to uncoercable, i.e. throws an
      * error.
      */
     virtual std::string coerceToString(const Pos & pos, PathSet & context, bool copyMore, bool copyToStore) const;
 
-    /* Compare to another value of the same type. Defaults to uncomparable,
+    /**
+     * Compare to another value of the same type. Defaults to uncomparable,
      * i.e. always false.
      */
     virtual bool operator ==(const ExternalValueBase & b) const;
 
-    /* Print the value as JSON. Defaults to unconvertable, i.e. throws an error */
+    /**
+     * Print the value as JSON. Defaults to unconvertable, i.e. throws an error
+     */
     virtual nlohmann::json printValueAsJSON(EvalState & state, bool strict,
         PathSet & context, bool copyToStore = true) const;
 
-    /* Print the value as XML. Defaults to unevaluated */
+    /**
+     * Print the value as XML. Defaults to unevaluated
+     */
     virtual void printValueAsXML(EvalState & state, bool strict, bool location,
         XMLWriter & doc, PathSet & context, PathSet & drvsSeen,
         const PosIdx pos) const;
@@ -146,26 +161,28 @@ public:
         NixInt integer;
         bool boolean;
 
-        /* Strings in the evaluator carry a so-called `context' which
+        /**
-           is a list of strings representing store paths.  This is to
+         * Strings in the evaluator carry a so-called `context` which
-           allow users to write things like
+         * is a list of strings representing store paths.  This is to
+         * allow users to write things like
 
-             "--with-freetype2-library=" + freetype + "/lib"
+         *   "--with-freetype2-library=" + freetype + "/lib"
 
-           where `freetype' is a derivation (or a source to be copied
+         * where `freetype` is a derivation (or a source to be copied
-           to the store).  If we just concatenated the strings without
+         * to the store).  If we just concatenated the strings without
-           keeping track of the referenced store paths, then if the
+         * keeping track of the referenced store paths, then if the
-           string is used as a derivation attribute, the derivation
+         * string is used as a derivation attribute, the derivation
-           will not have the correct dependencies in its inputDrvs and
+         * will not have the correct dependencies in its inputDrvs and
-           inputSrcs.
+         * inputSrcs.
 
-           The semantics of the context is as follows: when a string
+         * The semantics of the context is as follows: when a string
-           with context C is used as a derivation attribute, then the
+         * with context C is used as a derivation attribute, then the
-           derivations in C will be added to the inputDrvs of the
+         * derivations in C will be added to the inputDrvs of the
-           derivation, and the other store paths in C will be added to
+         * derivation, and the other store paths in C will be added to
-           the inputSrcs of the derivations.
+         * the inputSrcs of the derivations.
 
-           For canonicity, the store paths should be in sorted order. */
+         * For canonicity, the store paths should be in sorted order.
+         */
         struct {
             const char * s;
             const char * * context; // must be in sorted order
@@ -197,8 +214,10 @@ public:
         NixFloat fpoint;
     };
 
-    // Returns the normal type of a Value. This only returns nThunk if the
+    /**
-    // Value hasn't been forceValue'd
+     * Returns the normal type of a Value. This only returns nThunk if
+     * the Value hasn't been forceValue'd
+     */
     inline ValueType type() const
     {
         switch (internalType) {
@@ -217,8 +236,10 @@ public:
         abort();
     }
 
-    /* After overwriting an app node, be sure to clear pointers in the
+    /**
-       Value to ensure that the target isn't kept alive unnecessarily. */
+     * After overwriting an app node, be sure to clear pointers in the
+     * Value to ensure that the target isn't kept alive unnecessarily.
+     */
     inline void clearValue()
     {
         app.left = app.right = 0;
@@ -366,9 +387,11 @@ public:
 
     PosIdx determinePos(const PosIdx pos) const;
 
-    /* Check whether forcing this value requires a trivial amount of
+    /**
-       computation. In particular, function applications are
+     * Check whether forcing this value requires a trivial amount of
-       non-trivial. */
+     * computation. In particular, function applications are
+     * non-trivial.
+     */
     bool isTrivial() const;
 
     NixStringContext getContext(const Store &);
@@ -414,7 +437,9 @@ typedef std::map<Symbol, ValueVector> ValueVectorMap;
 #endif
 
 
-/* A value allocated in traceable memory. */
+/**
+ * A value allocated in traceable memory.
+ */
 typedef std::shared_ptr<Value *> RootValue;
 
 RootValue allocRootValue(Value * v);

src/libexpr/value/context.hh

@@ -28,34 +28,37 @@ public:
 
 class Store;
 
-/* Plain opaque path to some store object.
+/**
-
+ * Plain opaque path to some store object.
-   Encoded as just the path: ‘<path>’.
+ *
-*/
+ * Encoded as just the path: ‘<path>’.
+ */
 struct NixStringContextElem_Opaque {
     StorePath path;
 
     GENERATE_CMP(NixStringContextElem_Opaque, me->path);
 };
 
-/* Path to a derivation and its entire build closure.
+/**
-
+ * Path to a derivation and its entire build closure.
-   The path doesn't just refer to derivation itself and its closure, but
+ *
-   also all outputs of all derivations in that closure (including the
+ * The path doesn't just refer to derivation itself and its closure, but
-   root derivation).
+ * also all outputs of all derivations in that closure (including the
-
+ * root derivation).
-   Encoded in the form ‘=<drvPath>’.
+ *
-*/
+ * Encoded in the form ‘=<drvPath>’.
+ */
 struct NixStringContextElem_DrvDeep {
     StorePath drvPath;
 
     GENERATE_CMP(NixStringContextElem_DrvDeep, me->drvPath);
 };
 
-/* Derivation output.
+/**
-
+ * Derivation output.
-   Encoded in the form ‘!<output>!<drvPath>’.
+ *
-*/
+ * Encoded in the form ‘!<output>!<drvPath>’.
+ */
 struct NixStringContextElem_Built {
     StorePath drvPath;
     std::string output;
@@ -84,11 +87,12 @@ struct NixStringContextElem : _NixStringContextElem_Raw {
         return static_cast<Raw &>(*this);
     }
 
-    /* Decode a context string, one of:
+    /**
-       - ‘<path>’
+     * Decode a context string, one of:
-       - ‘=<path>’
+     * - ‘<path>’
-       - ‘!<name>!<path>’
+     * - ‘=<path>’
-      */
+     * - ‘!<name>!<path>’
+     */
     static NixStringContextElem parse(const Store & store, std::string_view s);
     std::string to_string(const Store & store) const;
 };

src/libfetchers/fetchers.hh

@@ -21,14 +21,14 @@ struct Tree
 
 struct InputScheme;
 
-/* The Input object is generated by a specific fetcher, based on the
+/**
+ * The Input object is generated by a specific fetcher, based on the
  * user-supplied input attribute in the flake.nix file, and contains
  * the information that the specific fetcher needs to perform the
  * actual fetch.  The Input object is most commonly created via the
  * "fromURL()" or "fromAttrs()" static functions which are provided
  * the url or attrset specified in the flake file.
  */
-
 struct Input
 {
     friend struct InputScheme;
@@ -38,7 +38,9 @@ struct Input
     bool locked = false;
     bool direct = true;
 
-    /* path of the parent of this input, used for relative path resolution */
+    /**
+     * path of the parent of this input, used for relative path resolution
+     */
     std::optional<Path> parent;
 
 public:
@@ -56,27 +58,35 @@ public:
 
     Attrs toAttrs() const;
 
-    /* Check whether this is a "direct" input, that is, not
+    /**
-       one that goes through a registry. */
+     * Check whether this is a "direct" input, that is, not
+     * one that goes through a registry.
+     */
     bool isDirect() const { return direct; }
 
-    /* Check whether this is a "locked" input, that is,
+    /**
-       one that contains a commit hash or content hash. */
+     * Check whether this is a "locked" input, that is,
+     * one that contains a commit hash or content hash.
+     */
     bool isLocked() const { return locked; }
 
-    /* Check whether the input carries all necessary info required
+    /**
-       for cache insertion and substitution.
+     * Check whether the input carries all necessary info required
-       These fields are used to uniquely identify cached trees
+     * for cache insertion and substitution.
-       within the "tarball TTL" window without necessarily
+     * These fields are used to uniquely identify cached trees
-       indicating that the input's origin is unchanged. */
+     * within the "tarball TTL" window without necessarily
+     * indicating that the input's origin is unchanged.
+     */
     bool hasAllInfo() const;
 
     bool operator ==(const Input & other) const;
 
     bool contains(const Input & other) const;
 
-    /* Fetch the input into the Nix store, returning the location in
+    /**
-       the Nix store and the locked input. */
+     * Fetch the input into the Nix store, returning the location in
+     * the Nix store and the locked input.
+     */
     std::pair<Tree, Input> fetch(ref<Store> store) const;
 
     Input applyOverrides(
@@ -105,7 +115,8 @@ public:
 };
 
 
-/* The InputScheme represents a type of fetcher.  Each fetcher
+/**
+ * The InputScheme represents a type of fetcher.  Each fetcher
  * registers with nix at startup time.  When processing an input for a
  * flake, each scheme is given an opportunity to "recognize" that
  * input from the url or attributes in the flake file's specification

src/libmain/shared.hh

@@ -25,7 +25,9 @@ public:
 
 int handleExceptions(const std::string & programName, std::function<void()> fun);
 
-/* Don't forget to call initPlugins() after settings are initialized! */
+/**
+ * Don't forget to call initPlugins() after settings are initialized!
+ */
 void initNix();
 
 void parseCmdLine(int argc, char * * argv,
@@ -36,7 +38,9 @@ void parseCmdLine(const std::string & programName, const Strings & args,
 
 void printVersion(const std::string & programName);
 
-/* Ugh.  No better place to put this. */
+/**
+ * Ugh.  No better place to put this.
+ */
 void printGCWarning();
 
 class Store;
@@ -75,11 +79,15 @@ struct LegacyArgs : public MixCommonArgs
 };
 
 
-/* Show the manual page for the specified program. */
+/**
+ * Show the manual page for the specified program.
+ */
 void showManPage(const std::string & name);
 
-/* The constructor of this class starts a pager if stdout is a
+/**
-   terminal and $PAGER is set. Stdout is redirected to the pager. */
+ * The constructor of this class starts a pager if stdout is a
+ * terminal and $PAGER is set. Stdout is redirected to the pager.
+ */
 class RunPager
 {
 public:
@@ -110,28 +118,34 @@ struct PrintFreed
 };
 
 
-/* Install a SIGSEGV handler to detect stack overflows. */
+/**
+ * Install a SIGSEGV handler to detect stack overflows.
+ */
 void detectStackOverflow();
 
-/* Pluggable behavior to run in case of a stack overflow.
+/**
-
+ * Pluggable behavior to run in case of a stack overflow.
-   Default value: defaultStackOverflowHandler.
+ *
-
+ * Default value: defaultStackOverflowHandler.
-   This is called by the handler installed by detectStackOverflow().
+ *
-
+ * This is called by the handler installed by detectStackOverflow().
-   This gives Nix library consumers a limit opportunity to report the error
+ *
-   condition. The handler should exit the process.
+ * This gives Nix library consumers a limit opportunity to report the error
-   See defaultStackOverflowHandler() for a reference implementation.
+ * condition. The handler should exit the process.
-
+ * See defaultStackOverflowHandler() for a reference implementation.
-   NOTE: Use with diligence, because this runs in the signal handler, with very
+ *
-   limited stack space and a potentially a corrupted heap, all while the failed
+ * NOTE: Use with diligence, because this runs in the signal handler, with very
-   thread is blocked indefinitely. All functions called must be reentrant. */
+ * limited stack space and a potentially a corrupted heap, all while the failed
+ * thread is blocked indefinitely. All functions called must be reentrant.
+ */
 extern std::function<void(siginfo_t * info, void * ctx)> stackOverflowHandler;
 
-/* The default, robust implementation of stackOverflowHandler.
+/**
-
+ * The default, robust implementation of stackOverflowHandler.
-   Prints an error message directly to stderr using a syscall instead of the
+ *
-   logger. Exits the process immediately after. */
+ * Prints an error message directly to stderr using a syscall instead of the
+ * logger. Exits the process immediately after.
+ */
 void defaultStackOverflowHandler(siginfo_t * info, void * ctx);
 
 }

src/libstore/binary-cache-store.hh

@@ -46,6 +46,11 @@ struct BinaryCacheStoreConfig : virtual StoreConfig
         )"};
 };
 
+
+/**
+ * @note subclasses must implement at least one of the two
+ * virtual getFile() methods.
+ */
 class BinaryCacheStore : public virtual BinaryCacheStoreConfig,
     public virtual Store,
     public virtual LogStore
@@ -75,14 +80,15 @@ public:
         std::string && data,
         const std::string & mimeType);
 
-    /* Note: subclasses must implement at least one of the two
+    /**
-       following getFile() methods. */
+     * Dump the contents of the specified file to a sink.
-
+     */
-    /* Dump the contents of the specified file to a sink. */
     virtual void getFile(const std::string & path, Sink & sink);
 
-    /* Fetch the specified file and call the specified callback with
+    /**
-       the result. A subclass may implement this asynchronously. */
+     * Fetch the specified file and call the specified callback with
+     * the result. A subclass may implement this asynchronously.
+     */
     virtual void getFile(
         const std::string & path,
         Callback<std::optional<std::string>> callback) noexcept;

src/libstore/build-result.hh

@@ -12,9 +12,12 @@ namespace nix {
 
 struct BuildResult
 {
-    /* Note: don't remove status codes, and only add new status codes
+    /**
-       at the end of the list, to prevent client/server
+     * @note This is directly used in the nix-store --serve protocol.
-       incompatibilities in the nix-store --serve protocol. */
+     * That means we need to worry about compatability across versions.
+     * Therefore, don't remove status codes, and only add new status
+     * codes at the end of the list.
+     */
     enum Status {
         Built = 0,
         Substituted,
@@ -22,8 +25,10 @@ struct BuildResult
         PermanentFailure,
         InputRejected,
         OutputRejected,
-        TransientFailure, // possibly transient
+        /// possibly transient
-        CachedFailure, // no longer used
+        TransientFailure,
+        /// no longer used
+        CachedFailure,
         TimedOut,
         MiscFailure,
         DependencyFailed,
@@ -33,7 +38,12 @@ struct BuildResult
         NoSubstituters,
     } status = MiscFailure;
 
-    // FIXME: include entire ErrorInfo object.
+    /**
+     * Information about the error if the build failed.
+     *
+     * @todo This should be an entire ErrorInfo object, not just a
+     * string, for richer information.
+     */
     std::string errorMsg;
 
     std::string toString() const {
@@ -60,27 +70,39 @@ struct BuildResult
         return strStatus + ((errorMsg == "") ? "" : " : " + errorMsg);
     }
 
-    /* How many times this build was performed. */
+    /**
+     * How many times this build was performed.
+     */
     unsigned int timesBuilt = 0;
 
-    /* If timesBuilt > 1, whether some builds did not produce the same
+    /**
-       result. (Note that 'isNonDeterministic = false' does not mean
+     * If timesBuilt > 1, whether some builds did not produce the same
-       the build is deterministic, just that we don't have evidence of
+     * result. (Note that 'isNonDeterministic = false' does not mean
-       non-determinism.) */
+     * the build is deterministic, just that we don't have evidence of
+     * non-determinism.)
+     */
     bool isNonDeterministic = false;
 
-    /* The derivation we built or the store path we substituted. */
+    /**
+     * The derivation we built or the store path we substituted.
+     */
     DerivedPath path;
 
-    /* For derivations, a mapping from the names of the wanted outputs
+    /**
-       to actual paths. */
+     * For derivations, a mapping from the names of the wanted outputs
+     * to actual paths.
+     */
     DrvOutputs builtOutputs;
 
-    /* The start/stop times of the build (or one of the rounds, if it
+    /**
-       was repeated). */
+     * The start/stop times of the build (or one of the rounds, if it
+     * was repeated).
+     */
     time_t startTime = 0, stopTime = 0;
 
-    /* User and system CPU time the build took. */
+    /**
+     * User and system CPU time the build took.
+     */
     std::optional<std::chrono::microseconds> cpuUser, cpuSystem;
 
     bool success()

src/libstore/build/derivation-goal.hh

@@ -16,8 +16,10 @@ struct HookInstance;
 
 typedef enum {rpAccept, rpDecline, rpPostpone} HookReply;
 
-/* Unless we are repairing, we don't both to test validity and just assume it,
+/**
-   so the choices are `Absent` or `Valid`. */
+ * Unless we are repairing, we don't both to test validity and just assume it,
+ * so the choices are `Absent` or `Valid`.
+ */
 enum struct PathStatus {
     Corrupt,
     Absent,
@@ -27,11 +29,15 @@ enum struct PathStatus {
 struct InitialOutputStatus {
     StorePath path;
     PathStatus status;
-    /* Valid in the store, and additionally non-corrupt if we are repairing */
+    /**
+     * Valid in the store, and additionally non-corrupt if we are repairing
+     */
     bool isValid() const {
         return status == PathStatus::Valid;
     }
-    /* Merely present, allowed to be corrupt */
+    /**
+     * Merely present, allowed to be corrupt
+     */
     bool isPresent() const {
         return status == PathStatus::Corrupt
             || status == PathStatus::Valid;
@@ -46,59 +52,87 @@ struct InitialOutput {
 
 struct DerivationGoal : public Goal
 {
-    /* Whether to use an on-disk .drv file. */
+    /**
+     * Whether to use an on-disk .drv file.
+     */
     bool useDerivation;
 
-    /* The path of the derivation. */
+    /** The path of the derivation. */
     StorePath drvPath;
 
-    /* The goal for the corresponding resolved derivation */
+    /**
+     * The goal for the corresponding resolved derivation
+     */
     std::shared_ptr<DerivationGoal> resolvedDrvGoal;
 
-    /* The specific outputs that we need to build.  Empty means all of
+    /**
-       them. */
+     * The specific outputs that we need to build.  Empty means all of
+     * them.
+     */
     OutputsSpec wantedOutputs;
 
-    /* Mapping from input derivations + output names to actual store
+    /**
-       paths. This is filled in by waiteeDone() as each dependency
+     * Mapping from input derivations + output names to actual store
-       finishes, before inputsRealised() is reached, */
+     * paths. This is filled in by waiteeDone() as each dependency
+     * finishes, before inputsRealised() is reached.
+     */
     std::map<std::pair<StorePath, std::string>, StorePath> inputDrvOutputs;
 
-    /* Whether additional wanted outputs have been added. */
+    /**
+     * Whether additional wanted outputs have been added.
+     */
     bool needRestart = false;
 
-    /* Whether to retry substituting the outputs after building the
+    /**
-       inputs. This is done in case of an incomplete closure. */
+     * Whether to retry substituting the outputs after building the
+     * inputs. This is done in case of an incomplete closure.
+     */
     bool retrySubstitution = false;
 
-    /* Whether we've retried substitution, in which case we won't try
+    /**
-       again. */
+     * Whether we've retried substitution, in which case we won't try
+     * again.
+     */
     bool retriedSubstitution = false;
 
-    /* The derivation stored at drvPath. */
+    /**
+     * The derivation stored at drvPath.
+     */
     std::unique_ptr<Derivation> drv;
 
     std::unique_ptr<ParsedDerivation> parsedDrv;
 
-    /* The remainder is state held during the build. */
+    /**
+     * The remainder is state held during the build.
+     */
 
-    /* Locks on (fixed) output paths. */
+    /**
+     * Locks on (fixed) output paths.
+     */
     PathLocks outputLocks;
 
-    /* All input paths (that is, the union of FS closures of the
+    /**
-       immediate input paths). */
+     * All input paths (that is, the union of FS closures of the
+     * immediate input paths).
+     */
     StorePathSet inputPaths;
 
     std::map<std::string, InitialOutput> initialOutputs;
 
-    /* File descriptor for the log file. */
+    /**
+     * File descriptor for the log file.
+     */
     AutoCloseFD fdLogFile;
     std::shared_ptr<BufferedSink> logFileSink, logSink;
 
-    /* Number of bytes received from the builder's stdout/stderr. */
+    /**
+     * Number of bytes received from the builder's stdout/stderr.
+     */
     unsigned long logSize;
 
-    /* The most recent log lines. */
+    /**
+     * The most recent log lines.
+     */
     std::list<std::string> logTail;
 
     std::string currentLogLine;
@@ -106,10 +140,14 @@ struct DerivationGoal : public Goal
 
     std::string currentHookLine;
 
-    /* The build hook. */
+    /**
+     * The build hook.
+     */
     std::unique_ptr<HookInstance> hook;
 
-    /* The sort of derivation we are building. */
+    /**
+     * The sort of derivation we are building.
+     */
     DerivationType derivationType;
 
     typedef void (DerivationGoal::*GoalState)();
@@ -121,12 +159,16 @@ struct DerivationGoal : public Goal
 
     std::unique_ptr<Activity> act;
 
-    /* Activity that denotes waiting for a lock. */
+    /**
+     * Activity that denotes waiting for a lock.
+     */
     std::unique_ptr<Activity> actLock;
 
     std::map<ActivityId, Activity> builderActivities;
 
-    /* The remote machine on which we're building. */
+    /**
+     * The remote machine on which we're building.
+     */
     std::string machineName;
 
     DerivationGoal(const StorePath & drvPath,
@@ -143,10 +185,14 @@ struct DerivationGoal : public Goal
 
     void work() override;
 
-    /* Add wanted outputs to an already existing derivation goal. */
+    /**
+     * Add wanted outputs to an already existing derivation goal.
+     */
     void addWantedOutputs(const OutputsSpec & outputs);
 
-    /* The states. */
+    /**
+     * The states.
+     */
     void getDerivation();
     void loadDerivation();
     void haveDerivation();
@@ -160,28 +206,42 @@ struct DerivationGoal : public Goal
 
     void resolvedFinished();
 
-    /* Is the build hook willing to perform the build? */
+    /**
+     * Is the build hook willing to perform the build?
+     */
     HookReply tryBuildHook();
 
     virtual int getChildStatus();
 
-    /* Check that the derivation outputs all exist and register them
+    /**
-       as valid. */
+     * Check that the derivation outputs all exist and register them
+     * as valid.
+     */
     virtual DrvOutputs registerOutputs();
 
-    /* Open a log file and a pipe to it. */
+    /**
+     * Open a log file and a pipe to it.
+     */
     Path openLogFile();
 
-    /* Sign the newly built realisation if the store allows it */
+    /**
+     * Sign the newly built realisation if the store allows it
+     */
     virtual void signRealisation(Realisation&) {}
 
-    /* Close the log file. */
+    /**
+     * Close the log file.
+     */
     void closeLogFile();
 
-    /* Close the read side of the logger pipe. */
+    /**
+     * Close the read side of the logger pipe.
+     */
     virtual void closeReadPipes();
 
-    /* Cleanup hooks for buildDone() */
+    /**
+     * Cleanup hooks for buildDone()
+     */
     virtual void cleanupHookFinally();
     virtual void cleanupPreChildKill();
     virtual void cleanupPostChildKill();
@@ -191,30 +251,40 @@ struct DerivationGoal : public Goal
 
     virtual bool isReadDesc(int fd);
 
-    /* Callback used by the worker to write to the log. */
+    /**
+     * Callback used by the worker to write to the log.
+     */
     void handleChildOutput(int fd, std::string_view data) override;
     void handleEOF(int fd) override;
     void flushLine();
 
-    /* Wrappers around the corresponding Store methods that first consult the
+    /**
-       derivation.  This is currently needed because when there is no drv file
+     * Wrappers around the corresponding Store methods that first consult the
-       there also is no DB entry. */
+     * derivation.  This is currently needed because when there is no drv file
+     * there also is no DB entry.
+     */
     std::map<std::string, std::optional<StorePath>> queryPartialDerivationOutputMap();
     OutputPathMap queryDerivationOutputMap();
 
-    /* Update 'initialOutputs' to determine the current status of the
+    /**
-       outputs of the derivation. Also returns a Boolean denoting
+     * Update 'initialOutputs' to determine the current status of the
-       whether all outputs are valid and non-corrupt, and a
+     * outputs of the derivation. Also returns a Boolean denoting
-       'DrvOutputs' structure containing the valid and wanted
+     * whether all outputs are valid and non-corrupt, and a
-       outputs. */
+     * 'DrvOutputs' structure containing the valid and wanted
+     * outputs.
+     */
     std::pair<bool, DrvOutputs> checkPathValidity();
 
-    /* Aborts if any output is not valid or corrupt, and otherwise
+    /**
-       returns a 'DrvOutputs' structure containing the wanted
+     * Aborts if any output is not valid or corrupt, and otherwise
-       outputs. */
+     * returns a 'DrvOutputs' structure containing the wanted
+     * outputs.
+     */
     DrvOutputs assertPathValidity();
 
-    /* Forcibly kill the child process, if any. */
+    /**
+     * Forcibly kill the child process, if any.
+     */
     virtual void killChild();
 
     void repairClosure();

src/libstore/build/drv-output-substitution-goal.hh

@@ -11,24 +11,34 @@ namespace nix {
 
 class Worker;
 
-// Substitution of a derivation output.
+/**
-// This is done in three steps:
+ * Substitution of a derivation output.
-// 1. Fetch the output info from a substituter
+ * This is done in three steps:
-// 2. Substitute the corresponding output path
+ * 1. Fetch the output info from a substituter
-// 3. Register the output info
+ * 2. Substitute the corresponding output path
+ * 3. Register the output info
+ */
 class DrvOutputSubstitutionGoal : public Goal {
 
-    // The drv output we're trying to substitue
+    /**
+     * The drv output we're trying to substitue
+     */
     DrvOutput id;
 
-    // The realisation corresponding to the given output id.
+    /**
-    // Will be filled once we can get it.
+     * The realisation corresponding to the given output id.
+     * Will be filled once we can get it.
+     */
     std::shared_ptr<const Realisation> outputInfo;
 
-    /* The remaining substituters. */
+    /**
+     * The remaining substituters.
+     */
     std::list<ref<Store>> subs;
 
-    /* The current substituter. */
+    /**
+     * The current substituter.
+     */
     std::shared_ptr<Store> sub;
 
     struct DownloadState
@@ -39,7 +49,9 @@ class DrvOutputSubstitutionGoal : public Goal {
 
     std::shared_ptr<DownloadState> downloadState;
 
-    /* Whether a substituter failed. */
+    /**
+     * Whether a substituter failed.
+     */
     bool substituterFailed = false;
 
 public:

src/libstore/build/goal.hh

@@ -7,11 +7,15 @@
 
 namespace nix {
 
-/* Forward definition. */
+/**
+ * Forward definition.
+ */
 struct Goal;
 class Worker;
 
-/* A pointer to a goal. */
+/**
+ * A pointer to a goal.
+ */
 typedef std::shared_ptr<Goal> GoalPtr;
 typedef std::weak_ptr<Goal> WeakGoalPtr;
 
@@ -19,48 +23,72 @@ struct CompareGoalPtrs {
     bool operator() (const GoalPtr & a, const GoalPtr & b) const;
 };
 
-/* Set of goals. */
+/**
+ * Set of goals.
+ */
 typedef std::set<GoalPtr, CompareGoalPtrs> Goals;
 typedef std::set<WeakGoalPtr, std::owner_less<WeakGoalPtr>> WeakGoals;
 
-/* A map of paths to goals (and the other way around). */
+/**
+ * A map of paths to goals (and the other way around).
+ */
 typedef std::map<StorePath, WeakGoalPtr> WeakGoalMap;
 
 struct Goal : public std::enable_shared_from_this<Goal>
 {
     typedef enum {ecBusy, ecSuccess, ecFailed, ecNoSubstituters, ecIncompleteClosure} ExitCode;
 
-    /* Backlink to the worker. */
+    /**
+     * Backlink to the worker.
+     */
     Worker & worker;
 
-    /* Goals that this goal is waiting for. */
+    /**
+     * Goals that this goal is waiting for.
+     */
     Goals waitees;
 
-    /* Goals waiting for this one to finish.  Must use weak pointers
+    /**
-       here to prevent cycles. */
+     * Goals waiting for this one to finish.  Must use weak pointers
+     * here to prevent cycles.
+     */
     WeakGoals waiters;
 
-    /* Number of goals we are/were waiting for that have failed. */
+    /**
+     * Number of goals we are/were waiting for that have failed.
+     */
     size_t nrFailed = 0;
 
-    /* Number of substitution goals we are/were waiting for that
+    /**
-       failed because there are no substituters. */
+     * Number of substitution goals we are/were waiting for that
+     * failed because there are no substituters.
+     */
     size_t nrNoSubstituters = 0;
 
-    /* Number of substitution goals we are/were waiting for that
+    /**
-       failed because they had unsubstitutable references. */
+     * Number of substitution goals we are/were waiting for that
+     * failed because they had unsubstitutable references.
+     */
     size_t nrIncompleteClosure = 0;
 
-    /* Name of this goal for debugging purposes. */
+    /**
+     * Name of this goal for debugging purposes.
+     */
     std::string name;
 
-    /* Whether the goal is finished. */
+    /**
+     * Whether the goal is finished.
+     */
     ExitCode exitCode = ecBusy;
 
-    /* Build result. */
+    /**
+     * Build result.
+     */
     BuildResult buildResult;
 
-    /* Exception containing an error message, if any. */
+    /**
+     * Exception containing an error message, if any.
+     */
     std::optional<Error> ex;
 
     Goal(Worker & worker, DerivedPath path)
@@ -96,9 +124,11 @@ struct Goal : public std::enable_shared_from_this<Goal>
         return name;
     }
 
-    /* Callback in case of a timeout.  It should wake up its waiters,
+    /**
-       get rid of any running child processes that are being monitored
+     * Callback in case of a timeout.  It should wake up its waiters,
-       by the worker (important!), etc. */
+     * get rid of any running child processes that are being monitored
+     * by the worker (important!), etc.
+     */
     virtual void timedOut(Error && ex) = 0;
 
     virtual std::string key() = 0;

src/libstore/build/hook-instance.hh

@@ -8,16 +8,24 @@ namespace nix {
 
 struct HookInstance
 {
-    /* Pipes for talking to the build hook. */
+    /**
+     * Pipes for talking to the build hook.
+     */
     Pipe toHook;
 
-    /* Pipe for the hook's standard output/error. */
+    /**
+     * Pipe for the hook's standard output/error.
+     */
     Pipe fromHook;
 
-    /* Pipe for the builder's standard output/error. */
+    /**
+     * Pipe for the builder's standard output/error.
+     */
     Pipe builderOut;
 
-    /* The process ID of the hook. */
+    /**
+     * The process ID of the hook.
+     */
     Pid pid;
 
     FdSink sink;

src/libstore/build/local-derivation-goal.hh

@@ -10,49 +10,75 @@ struct LocalDerivationGoal : public DerivationGoal
 {
     LocalStore & getLocalStore();
 
-    /* User selected for running the builder. */
+    /**
+     * User selected for running the builder.
+     */
     std::unique_ptr<UserLock> buildUser;
 
-    /* The process ID of the builder. */
+    /**
+     * The process ID of the builder.
+     */
     Pid pid;
 
-    /* The cgroup of the builder, if any. */
+    /**
+     * The cgroup of the builder, if any.
+     */
     std::optional<Path> cgroup;
 
-    /* The temporary directory. */
+    /**
+     * The temporary directory.
+     */
     Path tmpDir;
 
-    /* The path of the temporary directory in the sandbox. */
+    /**
+     * The path of the temporary directory in the sandbox.
+     */
     Path tmpDirInSandbox;
 
-    /* Master side of the pseudoterminal used for the builder's
+    /**
-       standard output/error. */
+     * Master side of the pseudoterminal used for the builder's
+     * standard output/error.
+     */
     AutoCloseFD builderOut;
 
-    /* Pipe for synchronising updates to the builder namespaces. */
+    /**
+     * Pipe for synchronising updates to the builder namespaces.
+     */
     Pipe userNamespaceSync;
 
-    /* The mount namespace and user namespace of the builder, used to add additional
+    /**
-       paths to the sandbox as a result of recursive Nix calls. */
+     * The mount namespace and user namespace of the builder, used to add additional
+     * paths to the sandbox as a result of recursive Nix calls.
+     */
     AutoCloseFD sandboxMountNamespace;
     AutoCloseFD sandboxUserNamespace;
 
-    /* On Linux, whether we're doing the build in its own user
+    /**
-       namespace. */
+     * On Linux, whether we're doing the build in its own user
+     * namespace.
+     */
     bool usingUserNamespace = true;
 
-    /* Whether we're currently doing a chroot build. */
+    /**
+     * Whether we're currently doing a chroot build.
+     */
     bool useChroot = false;
 
     Path chrootRootDir;
 
-    /* RAII object to delete the chroot directory. */
+    /**
+     * RAII object to delete the chroot directory.
+     */
     std::shared_ptr<AutoDelete> autoDelChroot;
 
-    /* Whether to run the build in a private network namespace. */
+    /**
+     * Whether to run the build in a private network namespace.
+     */
     bool privateNetwork = false;
 
-    /* Stuff we need to pass to initChild(). */
+    /**
+     * Stuff we need to pass to initChild().
+     */
     struct ChrootPath {
         Path source;
         bool optional;
@@ -71,30 +97,35 @@ struct LocalDerivationGoal : public DerivationGoal
     SandboxProfile additionalSandboxProfile;
 #endif
 
-    /* Hash rewriting. */
+    /**
+     * Hash rewriting.
+     */
     StringMap inputRewrites, outputRewrites;
     typedef map<StorePath, StorePath> RedirectedOutputs;
     RedirectedOutputs redirectedOutputs;
 
-    /* The outputs paths used during the build.
+    /**
-
+     * The outputs paths used during the build.
-       - Input-addressed derivations or fixed content-addressed outputs are
+     *
-         sometimes built when some of their outputs already exist, and can not
+     * - Input-addressed derivations or fixed content-addressed outputs are
-         be hidden via sandboxing. We use temporary locations instead and
+     *   sometimes built when some of their outputs already exist, and can not
-         rewrite after the build. Otherwise the regular predetermined paths are
+     *   be hidden via sandboxing. We use temporary locations instead and
-         put here.
+     *   rewrite after the build. Otherwise the regular predetermined paths are
-
+     *   put here.
-       - Floating content-addressed derivations do not know their final build
+     *
-         output paths until the outputs are hashed, so random locations are
+     * - Floating content-addressed derivations do not know their final build
-         used, and then renamed. The randomness helps guard against hidden
+     *   output paths until the outputs are hashed, so random locations are
-         self-references.
+     *   used, and then renamed. The randomness helps guard against hidden
+     *   self-references.
      */
     OutputPathMap scratchOutputs;
 
-    /* Path registration info from the previous round, if we're
+    /**
-       building multiple times. Since this contains the hash, it
+     * Path registration info from the previous round, if we're
-       allows us to compare whether two rounds produced the same
+     * building multiple times. Since this contains the hash, it
-       result. */
+     * allows us to compare whether two rounds produced the same
+     * result.
+     */
     std::map<Path, ValidPathInfo> prevInfos;
 
     uid_t sandboxUid() { return usingUserNamespace ? (!buildUser || buildUser->getUIDCount() == 1 ? 1000 : 0) : buildUser->getUID(); }
@@ -102,25 +133,37 @@ struct LocalDerivationGoal : public DerivationGoal
 
     const static Path homeDir;
 
-    /* The recursive Nix daemon socket. */
+    /**
+     * The recursive Nix daemon socket.
+     */
     AutoCloseFD daemonSocket;
 
-    /* The daemon main thread. */
+    /**
+     * The daemon main thread.
+     */
     std::thread daemonThread;
 
-    /* The daemon worker threads. */
+    /**
+     * The daemon worker threads.
+     */
     std::vector<std::thread> daemonWorkerThreads;
 
-    /* Paths that were added via recursive Nix calls. */
+    /**
+     * Paths that were added via recursive Nix calls.
+     */
     StorePathSet addedPaths;
 
-    /* Realisations that were added via recursive Nix calls. */
+    /**
+     * Realisations that were added via recursive Nix calls.
+     */
     std::set<DrvOutput> addedDrvOutputs;
 
-    /* Recursive Nix calls are only allowed to build or realize paths
+    /**
-       in the original input closure or added via a recursive Nix call
+     * Recursive Nix calls are only allowed to build or realize paths
-       (so e.g. you can't do 'nix-store -r /nix/store/<bla>' where
+     * in the original input closure or added via a recursive Nix call
-       /nix/store/<bla> is some arbitrary path in a binary cache). */
+     * (so e.g. you can't do 'nix-store -r /nix/store/<bla>' where
+     * /nix/store/<bla> is some arbitrary path in a binary cache).
+     */
     bool isAllowed(const StorePath & path)
     {
         return inputPaths.count(path) || addedPaths.count(path);
@@ -138,55 +181,81 @@ struct LocalDerivationGoal : public DerivationGoal
 
     virtual ~LocalDerivationGoal() override;
 
-    /* Whether we need to perform hash rewriting if there are valid output paths. */
+    /**
+     * Whether we need to perform hash rewriting if there are valid output paths.
+     */
     bool needsHashRewrite();
 
-    /* The additional states. */
+    /**
+     * The additional states.
+     */
     void tryLocalBuild() override;
 
-    /* Start building a derivation. */
+    /**
+     * Start building a derivation.
+     */
     void startBuilder();
 
-    /* Fill in the environment for the builder. */
+    /**
+     * Fill in the environment for the builder.
+     */
     void initEnv();
 
-    /* Setup tmp dir location. */
+    /**
+     * Setup tmp dir location.
+     */
     void initTmpDir();
 
-    /* Write a JSON file containing the derivation attributes. */
+    /**
+     * Write a JSON file containing the derivation attributes.
+     */
     void writeStructuredAttrs();
 
     void startDaemon();
 
     void stopDaemon();
 
-    /* Add 'path' to the set of paths that may be referenced by the
+    /**
-       outputs, and make it appear in the sandbox. */
+     * Add 'path' to the set of paths that may be referenced by the
+     * outputs, and make it appear in the sandbox.
+     */
     void addDependency(const StorePath & path);
 
-    /* Make a file owned by the builder. */
+    /**
+     * Make a file owned by the builder.
+     */
     void chownToBuilder(const Path & path);
 
     int getChildStatus() override;
 
-    /* Run the builder's process. */
+    /**
+     * Run the builder's process.
+     */
     void runChild();
 
-    /* Check that the derivation outputs all exist and register them
+    /**
-       as valid. */
+     * Check that the derivation outputs all exist and register them
+     * as valid.
+     */
     DrvOutputs registerOutputs() override;
 
     void signRealisation(Realisation &) override;
 
-    /* Check that an output meets the requirements specified by the
+    /**
-       'outputChecks' attribute (or the legacy
+     * Check that an output meets the requirements specified by the
-       '{allowed,disallowed}{References,Requisites}' attributes). */
+     * 'outputChecks' attribute (or the legacy
+     * '{allowed,disallowed}{References,Requisites}' attributes).
+     */
     void checkOutputs(const std::map<std::string, ValidPathInfo> & outputs);
 
-    /* Close the read side of the logger pipe. */
+    /**
+     * Close the read side of the logger pipe.
+     */
     void closeReadPipes() override;
 
-    /* Cleanup hooks for buildDone() */
+    /**
+     * Cleanup hooks for buildDone()
+     */
     void cleanupHookFinally() override;
     void cleanupPreChildKill() override;
     void cleanupPostChildKill() override;
@@ -196,24 +265,36 @@ struct LocalDerivationGoal : public DerivationGoal
 
     bool isReadDesc(int fd) override;
 
-    /* Delete the temporary directory, if we have one. */
+    /**
+     * Delete the temporary directory, if we have one.
+     */
     void deleteTmpDir(bool force);
 
-    /* Forcibly kill the child process, if any. */
+    /**
+     * Forcibly kill the child process, if any.
+     */
     void killChild() override;
 
-    /* Kill any processes running under the build user UID or in the
+    /**
-       cgroup of the build. */
+     * Kill any processes running under the build user UID or in the
+     * cgroup of the build.
+     */
     void killSandbox(bool getStats);
 
-    /* Create alternative path calculated from but distinct from the
+    /**
-       input, so we can avoid overwriting outputs (or other store paths)
+     * Create alternative path calculated from but distinct from the
-       that already exist. */
+     * input, so we can avoid overwriting outputs (or other store paths)
+     * that already exist.
+     */
     StorePath makeFallbackPath(const StorePath & path);
-    /* Make a path to another based on the output name along with the
+
-       derivation hash. */
+    /**
-    /* FIXME add option to randomize, so we can audit whether our
+     * Make a path to another based on the output name along with the
-       rewrites caught everything */
+     * derivation hash.
+     *
+     * @todo Add option to randomize, so we can audit whether our
+     * rewrites caught everything
+     */
     StorePath makeFallbackPath(std::string_view outputName);
 };
 

src/libstore/build/substitution-goal.hh

@@ -11,38 +11,58 @@ class Worker;
 
 struct PathSubstitutionGoal : public Goal
 {
-    /* The store path that should be realised through a substitute. */
+    /**
+     * The store path that should be realised through a substitute.
+     */
     StorePath storePath;
 
-    /* The path the substituter refers to the path as. This will be
+    /**
-       different when the stores have different names. */
+     * The path the substituter refers to the path as. This will be
+     * different when the stores have different names.
+     */
     std::optional<StorePath> subPath;
 
-    /* The remaining substituters. */
+    /**
+     * The remaining substituters.
+     */
     std::list<ref<Store>> subs;
 
-    /* The current substituter. */
+    /**
+     * The current substituter.
+     */
     std::shared_ptr<Store> sub;
 
-    /* Whether a substituter failed. */
+    /**
+     * Whether a substituter failed.
+     */
     bool substituterFailed = false;
 
-    /* Path info returned by the substituter's query info operation. */
+    /**
+     * Path info returned by the substituter's query info operation.
+     */
     std::shared_ptr<const ValidPathInfo> info;
 
-    /* Pipe for the substituter's standard output. */
+    /**
+     * Pipe for the substituter's standard output.
+     */
     Pipe outPipe;
 
-    /* The substituter thread. */
+    /**
+     * The substituter thread.
+     */
     std::thread thr;
 
     std::promise<void> promise;
 
-    /* Whether to try to repair a valid path. */
+    /**
+     * Whether to try to repair a valid path.
+     */
     RepairFlag repair;
 
-    /* Location where we're downloading the substitute.  Differs from
+    /**
-       storePath when doing a repair. */
+     * Location where we're downloading the substitute.  Differs from
+     * storePath when doing a repair.
+     */
     Path destPath;
 
     std::unique_ptr<MaintainCount<uint64_t>> maintainExpectedSubstitutions,
@@ -51,7 +71,9 @@ struct PathSubstitutionGoal : public Goal
     typedef void (PathSubstitutionGoal::*GoalState)();
     GoalState state;
 
-    /* Content address for recomputing store path */
+    /**
+     * Content address for recomputing store path
+     */
     std::optional<ContentAddress> ca;
 
     void done(
@@ -65,16 +87,20 @@ public:
 
     void timedOut(Error && ex) override { abort(); };
 
+    /**
+     * We prepend "a$" to the key name to ensure substitution goals
+     * happen before derivation goals.
+     */
     std::string key() override
     {
-        /* "a$" ensures substitution goals happen before derivation
-           goals. */
         return "a$" + std::string(storePath.name()) + "$" + worker.store.printStorePath(storePath);
     }
 
     void work() override;
 
-    /* The states. */
+    /**
+     * The states.
+     */
     void init();
     void tryNext();
     void gotInfo();
@@ -82,7 +108,9 @@ public:
     void tryToRun();
     void finished();
 
-    /* Callback used by the worker to write to the log. */
+    /**
+     * Callback used by the worker to write to the log.
+     */
     void handleChildOutput(int fd, std::string_view data) override;
     void handleEOF(int fd) override;
 

src/libstore/build/worker.hh

@@ -17,24 +17,29 @@ struct DerivationGoal;
 struct PathSubstitutionGoal;
 class DrvOutputSubstitutionGoal;
 
-/* Workaround for not being able to declare a something like
+/**
-
+ * Workaround for not being able to declare a something like
-     class PathSubstitutionGoal : public Goal;
+ *
-
+ * ```c++
-   even when Goal is a complete type.
+ * class PathSubstitutionGoal : public Goal;
-
+ * ```
-   This is still a static cast. The purpose of exporting it is to define it in
+ * even when Goal is a complete type.
-   a place where `PathSubstitutionGoal` is concrete, and use it in a place where it
+ *
-   is opaque. */
+ * This is still a static cast. The purpose of exporting it is to define it in
+ * a place where `PathSubstitutionGoal` is concrete, and use it in a place where it
+ * is opaque.
+ */
 GoalPtr upcast_goal(std::shared_ptr<PathSubstitutionGoal> subGoal);
 GoalPtr upcast_goal(std::shared_ptr<DrvOutputSubstitutionGoal> subGoal);
 
 typedef std::chrono::time_point<std::chrono::steady_clock> steady_time_point;
 
 
-/* A mapping used to remember for each child process to what goal it
+/**
-   belongs, and file descriptors for receiving log data and output
+ * A mapping used to remember for each child process to what goal it
-   path creation commands. */
+ * belongs, and file descriptors for receiving log data and output
+ * path creation commands.
+ */
 struct Child
 {
     WeakGoalPtr goal;
@@ -42,14 +47,19 @@ struct Child
     std::set<int> fds;
     bool respectTimeouts;
     bool inBuildSlot;
-    steady_time_point lastOutput; /* time we last got output on stdout/stderr */
+    /**
+     * Time we last got output on stdout/stderr
+     */
+    steady_time_point lastOutput;
     steady_time_point timeStarted;
 };
 
 /* Forward definition. */
 struct HookInstance;
 
-/* The worker class. */
+/**
+ * The worker class.
+ */
 class Worker
 {
 private:
@@ -57,38 +67,58 @@ private:
     /* Note: the worker should only have strong pointers to the
        top-level goals. */
 
-    /* The top-level goals of the worker. */
+    /**
+     * The top-level goals of the worker.
+     */
     Goals topGoals;
 
-    /* Goals that are ready to do some work. */
+    /**
+     * Goals that are ready to do some work.
+     */
     WeakGoals awake;
 
-    /* Goals waiting for a build slot. */
+    /**
+     * Goals waiting for a build slot.
+     */
     WeakGoals wantingToBuild;
 
-    /* Child processes currently running. */
+    /**
+     * Child processes currently running.
+     */
     std::list<Child> children;
 
-    /* Number of build slots occupied.  This includes local builds and
+    /**
-       substitutions but not remote builds via the build hook. */
+     * Number of build slots occupied.  This includes local builds and
+     * substitutions but not remote builds via the build hook.
+     */
     unsigned int nrLocalBuilds;
 
-    /* Maps used to prevent multiple instantiations of a goal for the
+    /**
-       same derivation / path. */
+     * Maps used to prevent multiple instantiations of a goal for the
+     * same derivation / path.
+     */
     std::map<StorePath, std::weak_ptr<DerivationGoal>> derivationGoals;
     std::map<StorePath, std::weak_ptr<PathSubstitutionGoal>> substitutionGoals;
     std::map<DrvOutput, std::weak_ptr<DrvOutputSubstitutionGoal>> drvOutputSubstitutionGoals;
 
-    /* Goals waiting for busy paths to be unlocked. */
+    /**
+     * Goals waiting for busy paths to be unlocked.
+     */
     WeakGoals waitingForAnyGoal;
 
-    /* Goals sleeping for a few seconds (polling a lock). */
+    /**
+     * Goals sleeping for a few seconds (polling a lock).
+     */
     WeakGoals waitingForAWhile;
 
-    /* Last time the goals in `waitingForAWhile' where woken up. */
+    /**
+     * Last time the goals in `waitingForAWhile` where woken up.
+     */
     steady_time_point lastWokenUp;
 
-    /* Cache for pathContentsGood(). */
+    /**
+     * Cache for pathContentsGood().
+     */
     std::map<StorePath, bool> pathContentsGoodCache;
 
 public:
@@ -97,17 +127,25 @@ public:
     const Activity actDerivations;
     const Activity actSubstitutions;
 
-    /* Set if at least one derivation had a BuildError (i.e. permanent
+    /**
-       failure). */
+     * Set if at least one derivation had a BuildError (i.e. permanent
+     * failure).
+     */
     bool permanentFailure;
 
-    /* Set if at least one derivation had a timeout. */
+    /**
+     * Set if at least one derivation had a timeout.
+     */
     bool timedOut;
 
-    /* Set if at least one derivation fails with a hash mismatch. */
+    /**
+     * Set if at least one derivation fails with a hash mismatch.
+     */
     bool hashMismatch;
 
-    /* Set if at least one derivation is not deterministic in check mode. */
+    /**
+     * Set if at least one derivation is not deterministic in check mode.
+     */
     bool checkMismatch;
 
     Store & store;
@@ -129,16 +167,22 @@ public:
     uint64_t expectedNarSize = 0;
     uint64_t doneNarSize = 0;
 
-    /* Whether to ask the build hook if it can build a derivation. If
+    /**
-       it answers with "decline-permanently", we don't try again. */
+     * Whether to ask the build hook if it can build a derivation. If
+     * it answers with "decline-permanently", we don't try again.
+     */
     bool tryBuildHook = true;
 
     Worker(Store & store, Store & evalStore);
     ~Worker();
 
-    /* Make a goal (with caching). */
+    /**
+     * Make a goal (with caching).
+     */
 
-    /* derivation goal */
+    /**
+     * derivation goal
+     */
 private:
     std::shared_ptr<DerivationGoal> makeDerivationGoalCommon(
         const StorePath & drvPath, const OutputsSpec & wantedOutputs,
@@ -151,56 +195,80 @@ public:
         const StorePath & drvPath, const BasicDerivation & drv,
         const OutputsSpec & wantedOutputs, BuildMode buildMode = bmNormal);
 
-    /* substitution goal */
+    /**
+     * substitution goal
+     */
     std::shared_ptr<PathSubstitutionGoal> makePathSubstitutionGoal(const StorePath & storePath, RepairFlag repair = NoRepair, std::optional<ContentAddress> ca = std::nullopt);
     std::shared_ptr<DrvOutputSubstitutionGoal> makeDrvOutputSubstitutionGoal(const DrvOutput & id, RepairFlag repair = NoRepair, std::optional<ContentAddress> ca = std::nullopt);
 
-    /* Remove a dead goal. */
+    /**
+     * Remove a dead goal.
+     */
     void removeGoal(GoalPtr goal);
 
-    /* Wake up a goal (i.e., there is something for it to do). */
+    /**
+     * Wake up a goal (i.e., there is something for it to do).
+     */
     void wakeUp(GoalPtr goal);
 
-    /* Return the number of local build and substitution processes
+    /**
-       currently running (but not remote builds via the build
+     * Return the number of local build and substitution processes
-       hook). */
+     * currently running (but not remote builds via the build
+     * hook).
+     */
     unsigned int getNrLocalBuilds();
 
-    /* Registers a running child process.  `inBuildSlot' means that
+    /**
-       the process counts towards the jobs limit. */
+     * Registers a running child process.  `inBuildSlot` means that
+     * the process counts towards the jobs limit.
+     */
     void childStarted(GoalPtr goal, const std::set<int> & fds,
         bool inBuildSlot, bool respectTimeouts);
 
-    /* Unregisters a running child process.  `wakeSleepers' should be
+    /**
-       false if there is no sense in waking up goals that are sleeping
+     * Unregisters a running child process.  `wakeSleepers` should be
-       because they can't run yet (e.g., there is no free build slot,
+     * false if there is no sense in waking up goals that are sleeping
-       or the hook would still say `postpone'). */
+     * because they can't run yet (e.g., there is no free build slot,
+     * or the hook would still say `postpone`).
+     */
     void childTerminated(Goal * goal, bool wakeSleepers = true);
 
-    /* Put `goal' to sleep until a build slot becomes available (which
+    /**
-       might be right away). */
+     * Put `goal` to sleep until a build slot becomes available (which
+     * might be right away).
+     */
     void waitForBuildSlot(GoalPtr goal);
 
-    /* Wait for any goal to finish.  Pretty indiscriminate way to
+    /**
-       wait for some resource that some other goal is holding. */
+     * Wait for any goal to finish.  Pretty indiscriminate way to
+     * wait for some resource that some other goal is holding.
+     */
     void waitForAnyGoal(GoalPtr goal);
 
-    /* Wait for a few seconds and then retry this goal.  Used when
+    /**
-       waiting for a lock held by another process.  This kind of
+     * Wait for a few seconds and then retry this goal.  Used when
-       polling is inefficient, but POSIX doesn't really provide a way
+     * waiting for a lock held by another process.  This kind of
-       to wait for multiple locks in the main select() loop. */
+     * polling is inefficient, but POSIX doesn't really provide a way
+     * to wait for multiple locks in the main select() loop.
+     */
     void waitForAWhile(GoalPtr goal);
 
-    /* Loop until the specified top-level goals have finished. */
+    /**
+     * Loop until the specified top-level goals have finished.
+     */
     void run(const Goals & topGoals);
 
-    /* Wait for input to become available. */
+    /**
+     * Wait for input to become available.
+     */
     void waitForInput();
 
     unsigned int exitStatus();
 
-    /* Check whether the given valid path exists and has the right
+    /**
-       contents. */
+     * Check whether the given valid path exists and has the right
+     * contents.
+     */
     bool pathContentsGood(const StorePath & path);
 
     void markContentsGood(const StorePath & path);

src/libstore/crypto.hh

@@ -12,8 +12,10 @@ struct Key
     std::string name;
     std::string key;
 
-    /* Construct Key from a string in the format
+    /**
-       ‘<name>:<key-in-base64>’. */
+     * Construct Key from a string in the format
+     * ‘<name>:<key-in-base64>’.
+     */
     Key(std::string_view s);
 
     std::string to_string() const;
@@ -29,7 +31,9 @@ struct SecretKey : Key
 {
     SecretKey(std::string_view s);
 
-    /* Return a detached signature of the given string. */
+    /**
+     * Return a detached signature of the given string.
+     */
     std::string signDetached(std::string_view s) const;
 
     PublicKey toPublicKey() const;
@@ -53,8 +57,10 @@ private:
 
 typedef std::map<std::string, PublicKey> PublicKeys;
 
-/* Return true iff ‘sig’ is a correct signature over ‘data’ using one
+/**
-   of the given public keys. */
+ * @return true iff ‘sig’ is a correct signature over ‘data’ using one
+ * of the given public keys.
+ */
 bool verifyDetached(const std::string & data, const std::string & sig,
     const PublicKeys & publicKeys);
 

src/libstore/derivations.hh

@@ -258,8 +258,14 @@ struct DerivationType : _DerivationTypeRaw {
 
 struct BasicDerivation
 {
-    DerivationOutputs outputs; /* keyed on symbolic IDs */
+    /**
-    StorePathSet inputSrcs; /* inputs that are sources */
+     * keyed on symbolic IDs
+     */
+    DerivationOutputs outputs;
+    /**
+     * inputs that are sources
+     */
+    StorePathSet inputSrcs;
     std::string platform;
     Path builder;
     Strings args;
@@ -429,12 +435,12 @@ void operator |= (DrvHash::Kind & self, const DrvHash::Kind & other) noexcept;
  *
  * A fixed-output derivation is a derivation whose outputs have a
  * specified content hash and hash algorithm. (Currently they must have
- * exactly one output (`out'), which is specified using the `outputHash'
+ * exactly one output (`out`), which is specified using the `outputHash`
- * and `outputHashAlgo' attributes, but the algorithm doesn't assume
+ * and `outputHashAlgo` attributes, but the algorithm doesn't assume
  * this.) We don't want changes to such derivations to propagate upwards
  * through the dependency graph, changing output paths everywhere.
  *
- * For instance, if we change the url in a call to the `fetchurl'
+ * For instance, if we change the url in a call to the `fetchurl`
  * function, we do not want to rebuild everything depending on it---after
  * all, (the hash of) the file being downloaded is unchanged.  So the
  * *output paths* should not change. On the other hand, the *derivation

src/libstore/fs-accessor.hh

@@ -5,8 +5,10 @@
 
 namespace nix {
 
-/* An abstract class for accessing a filesystem-like structure, such
+/**
-   as a (possibly remote) Nix store or the contents of a NAR file. */
+ * An abstract class for accessing a filesystem-like structure, such
+ * as a (possibly remote) Nix store or the contents of a NAR file.
+ */
 class FSAccessor
 {
 public:
@@ -15,8 +17,17 @@ public:
     struct Stat
     {
         Type type = tMissing;
-        uint64_t fileSize = 0; // regular files only
+        /**
+         * regular files only
+         */
+        uint64_t fileSize = 0;
+        /**
+         * regular files only
+         */
         bool isExecutable = false; // regular files only
+        /**
+         * regular files only
+         */
         uint64_t narOffset = 0; // regular files only
     };
 

src/libstore/gc-store.hh

@@ -12,19 +12,20 @@ typedef std::unordered_map<StorePath, std::unordered_set<std::string>> Roots;
 
 struct GCOptions
 {
-    /* Garbage collector operation:
+    /**
-
+     * Garbage collector operation:
-       - `gcReturnLive': return the set of paths reachable from
+     *
-         (i.e. in the closure of) the roots.
+     * - `gcReturnLive`: return the set of paths reachable from
-
+     *   (i.e. in the closure of) the roots.
-       - `gcReturnDead': return the set of paths not reachable from
+     *
-         the roots.
+     * - `gcReturnDead`: return the set of paths not reachable from
-
+     *   the roots.
-       - `gcDeleteDead': actually delete the latter set.
+     *
-
+     * - `gcDeleteDead`: actually delete the latter set.
-       - `gcDeleteSpecific': delete the paths listed in
+     *
-          `pathsToDelete', insofar as they are not reachable.
+     * - `gcDeleteSpecific`: delete the paths listed in
-    */
+     *    `pathsToDelete`, insofar as they are not reachable.
+     */
     typedef enum {
         gcReturnLive,
         gcReturnDead,
@@ -34,28 +35,38 @@ struct GCOptions
 
     GCAction action{gcDeleteDead};
 
-    /* If `ignoreLiveness' is set, then reachability from the roots is
+    /**
-       ignored (dangerous!).  However, the paths must still be
+     * If `ignoreLiveness` is set, then reachability from the roots is
-       unreferenced *within* the store (i.e., there can be no other
+     * ignored (dangerous!).  However, the paths must still be
-       store paths that depend on them). */
+     * unreferenced *within* the store (i.e., there can be no other
+     * store paths that depend on them).
+     */
     bool ignoreLiveness{false};
 
-    /* For `gcDeleteSpecific', the paths to delete. */
+    /**
+     * For `gcDeleteSpecific`, the paths to delete.
+     */
     StorePathSet pathsToDelete;
 
-    /* Stop after at least `maxFreed' bytes have been freed. */
+    /**
+     * Stop after at least `maxFreed` bytes have been freed.
+     */
     uint64_t maxFreed{std::numeric_limits<uint64_t>::max()};
 };
 
 
 struct GCResults
 {
-    /* Depending on the action, the GC roots, or the paths that would
+    /**
-       be or have been deleted. */
+     * Depending on the action, the GC roots, or the paths that would
+     * be or have been deleted.
+     */
     PathSet paths;
 
-    /* For `gcReturnDead', `gcDeleteDead' and `gcDeleteSpecific', the
+    /**
-       number of bytes that would be or was freed. */
+     * For `gcReturnDead`, `gcDeleteDead` and `gcDeleteSpecific`, the
+     * number of bytes that would be or was freed.
+     */
     uint64_t bytesFreed = 0;
 };
 
@@ -64,21 +75,27 @@ struct GcStore : public virtual Store
 {
     inline static std::string operationName = "Garbage collection";
 
-    /* Add an indirect root, which is merely a symlink to `path' from
+    /**
-       /nix/var/nix/gcroots/auto/<hash of `path'>.  `path' is supposed
+     * Add an indirect root, which is merely a symlink to `path` from
-       to be a symlink to a store path.  The garbage collector will
+     * `/nix/var/nix/gcroots/auto/<hash of path>`.  `path` is supposed
-       automatically remove the indirect root when it finds that
+     * to be a symlink to a store path.  The garbage collector will
-       `path' has disappeared. */
+     * automatically remove the indirect root when it finds that
+     * `path` has disappeared.
+     */
     virtual void addIndirectRoot(const Path & path) = 0;
 
-    /* Find the roots of the garbage collector.  Each root is a pair
+    /**
-       (link, storepath) where `link' is the path of the symlink
+     * Find the roots of the garbage collector.  Each root is a pair
-       outside of the Nix store that point to `storePath'. If
+     * `(link, storepath)` where `link` is the path of the symlink
-       'censor' is true, privacy-sensitive information about roots
+     * outside of the Nix store that point to `storePath`. If
-       found in /proc is censored. */
+     * `censor` is true, privacy-sensitive information about roots
+     * found in `/proc` is censored.
+     */
     virtual Roots findRoots(bool censor) = 0;
 
-    /* Perform a garbage collection. */
+    /**
+     * Perform a garbage collection.
+     */
     virtual void collectGarbage(const GCOptions & options, GCResults & results) = 0;
 };
 

src/libstore/globals.hh

@@ -72,30 +72,46 @@ public:
 
     Path nixPrefix;
 
-    /* The directory where we store sources and derived files. */
+    /**
+     * The directory where we store sources and derived files.
+     */
     Path nixStore;
 
     Path nixDataDir; /* !!! fix */
 
-    /* The directory where we log various operations. */
+    /**
+     * The directory where we log various operations.
+     */
     Path nixLogDir;
 
-    /* The directory where state is stored. */
+    /**
+     * The directory where state is stored.
+     */
     Path nixStateDir;
 
-    /* The directory where system configuration files are stored. */
+    /**
+     * The directory where system configuration files are stored.
+     */
     Path nixConfDir;
 
-    /* A list of user configuration files to load. */
+    /**
+     * A list of user configuration files to load.
+     */
     std::vector<Path> nixUserConfFiles;
 
-    /* The directory where the main programs are stored. */
+    /**
+     * The directory where the main programs are stored.
+     */
     Path nixBinDir;
 
-    /* The directory where the man pages are stored. */
+    /**
+     * The directory where the man pages are stored.
+     */
     Path nixManDir;
 
-    /* File name of the socket the daemon listens to.  */
+    /**
+     * File name of the socket the daemon listens to.
+     */
     Path nixDaemonSocketFile;
 
     Setting<std::string> storeUri{this, getEnv("NIX_REMOTE").value_or("auto"), "store",
@@ -121,7 +137,9 @@ public:
         )",
         {"build-fallback"}};
 
-    /* Whether to show build log output in real time. */
+    /**
+     * Whether to show build log output in real time.
+     */
     bool verboseBuild = true;
 
     Setting<size_t> logLines{this, 10, "log-lines",
@@ -157,8 +175,10 @@ public:
         )",
         {"build-cores"}, false};
 
-    /* Read-only mode.  Don't copy stuff to the store, don't change
+    /**
-       the database. */
+     * Read-only mode.  Don't copy stuff to the store, don't change
+     * the database.
+     */
     bool readOnlyMode = false;
 
     Setting<std::string> thisSystem{
@@ -458,7 +478,9 @@ public:
         )",
         {"env-keep-derivations"}};
 
-    /* Whether to lock the Nix client and worker to the same CPU. */
+    /**
+     * Whether to lock the Nix client and worker to the same CPU.
+     */
     bool lockCPU;
 
     Setting<SandboxMode> sandboxMode{
@@ -997,8 +1019,10 @@ public:
 // FIXME: don't use a global variable.
 extern Settings settings;
 
-/* This should be called after settings are initialized, but before
+/**
-   anything else */
+ * This should be called after settings are initialized, but before
+ * anything else
+ */
 void initPlugins();
 
 void loadConfFile();
@@ -1008,12 +1032,16 @@ std::vector<Path> getUserConfigFiles();
 
 extern const std::string nixVersion;
 
-/* NB: This is not sufficient. You need to call initNix() */
+/**
+ * NB: This is not sufficient. You need to call initNix()
+ */
 void initLibStore();
 
-/* It's important to initialize before doing _anything_, which is why we
+/**
-   call upon the programmer to handle this correctly. However, we only add
+ * It's important to initialize before doing _anything_, which is why we
-   this in a key locations, so as not to litter the code. */
+ * call upon the programmer to handle this correctly. However, we only add
+ * this in a key locations, so as not to litter the code.
+ */
 void assertLibStoreInitialized();
 
 }

src/libstore/local-fs-store.hh

@@ -48,7 +48,9 @@ public:
     void narFromPath(const StorePath & path, Sink & sink) override;
     ref<FSAccessor> getFSAccessor() override;
 
-    /* Register a permanent GC root. */
+    /**
+     * Register a permanent GC root.
+     */
     Path addPermRoot(const StorePath & storePath, const Path & gcRoot);
 
     virtual Path getRealStoreDir() { return realStoreDir; }

src/libstore/local-store.hh

@@ -19,10 +19,14 @@
 namespace nix {
 
 
-/* Nix store and database schema version.  Version 1 (or 0) was Nix <=
+/**
-   0.7.  Version 2 was Nix 0.8 and 0.9.  Version 3 is Nix 0.10.
+ * Nix store and database schema version.
-   Version 4 is Nix 0.11.  Version 5 is Nix 0.12-0.16.  Version 6 is
+ *
-   Nix 1.0.  Version 7 is Nix 1.3. Version 10 is 2.0. */
+ * Version 1 (or 0) was Nix <=
+ * 0.7.  Version 2 was Nix 0.8 and 0.9.  Version 3 is Nix 0.10.
+ * Version 4 is Nix 0.11.  Version 5 is Nix 0.12-0.16.  Version 6 is
+ * Nix 1.0.  Version 7 is Nix 1.3. Version 10 is 2.0.
+ */
 const int nixSchemaVersion = 10;
 
 
@@ -51,30 +55,40 @@ class LocalStore : public virtual LocalStoreConfig, public virtual LocalFSStore,
 {
 private:
 
-    /* Lock file used for upgrading. */
+    /**
+     * Lock file used for upgrading.
+     */
     AutoCloseFD globalLock;
 
     struct State
     {
-        /* The SQLite database object. */
+        /**
+         * The SQLite database object.
+         */
         SQLite db;
 
         struct Stmts;
         std::unique_ptr<Stmts> stmts;
 
-        /* The last time we checked whether to do an auto-GC, or an
+        /**
-           auto-GC finished. */
+         * The last time we checked whether to do an auto-GC, or an
+         * auto-GC finished.
+         */
         std::chrono::time_point<std::chrono::steady_clock> lastGCCheck;
 
-        /* Whether auto-GC is running. If so, get gcFuture to wait for
+        /**
-           the GC to finish. */
+         * Whether auto-GC is running. If so, get gcFuture to wait for
+         * the GC to finish.
+         */
         bool gcRunning = false;
         std::shared_future<void> gcFuture;
 
-        /* How much disk space was available after the previous
+        /**
-           auto-GC. If the current available disk space is below
+         * How much disk space was available after the previous
-           minFree but not much below availAfterGC, then there is no
+         * auto-GC. If the current available disk space is below
-           point in starting a new GC. */
+         * minFree but not much below availAfterGC, then there is no
+         * point in starting a new GC.
+         */
         uint64_t availAfterGC = std::numeric_limits<uint64_t>::max();
 
         std::unique_ptr<PublicKeys> publicKeys;
@@ -97,11 +111,15 @@ private:
 
 public:
 
-    // Hack for build-remote.cc.
+    /**
+     * Hack for build-remote.cc.
+     */
     PathSet locksHeld;
 
-    /* Initialise the local store, upgrading the schema if
+    /**
-       necessary. */
+     * Initialise the local store, upgrading the schema if
+     * necessary.
+     */
     LocalStore(const Params & params);
     LocalStore(std::string scheme, std::string path, const Params & params);
 
@@ -110,7 +128,9 @@ public:
     static std::set<std::string> uriSchemes()
     { return {}; }
 
-    /* Implementations of abstract store API methods. */
+    /**
+     * Implementations of abstract store API methods.
+     */
 
     std::string getUri() override;
 
@@ -155,13 +175,19 @@ private:
 
     void createTempRootsFile();
 
-    /* The file to which we write our temporary roots. */
+    /**
+     * The file to which we write our temporary roots.
+     */
     Sync<AutoCloseFD> _fdTempRoots;
 
-    /* The global GC lock. */
+    /**
+     * The global GC lock.
+     */
     Sync<AutoCloseFD> _fdGCLock;
 
-    /* Connection to the garbage collector. */
+    /**
+     * Connection to the garbage collector.
+     */
     Sync<AutoCloseFD> _fdRootsSocket;
 
 public:
@@ -180,24 +206,30 @@ public:
 
     void collectGarbage(const GCOptions & options, GCResults & results) override;
 
-    /* Optimise the disk space usage of the Nix store by hard-linking
+    /**
-       files with the same contents. */
+     * Optimise the disk space usage of the Nix store by hard-linking
+     * files with the same contents.
+     */
     void optimiseStore(OptimiseStats & stats);
 
     void optimiseStore() override;
 
-    /* Optimise a single store path. Optionally, test the encountered
+    /**
-       symlinks for corruption. */
+     * Optimise a single store path. Optionally, test the encountered
+     * symlinks for corruption.
+     */
     void optimisePath(const Path & path, RepairFlag repair);
 
     bool verifyStore(bool checkContents, RepairFlag repair) override;
 
-    /* Register the validity of a path, i.e., that `path' exists, that
+    /**
-       the paths referenced by it exists, and in the case of an output
+     * Register the validity of a path, i.e., that `path` exists, that
-       path of a derivation, that it has been produced by a successful
+     * the paths referenced by it exists, and in the case of an output
-       execution of the derivation (or something equivalent).  Also
+     * path of a derivation, that it has been produced by a successful
-       register the hash of the file system contents of the path.  The
+     * execution of the derivation (or something equivalent).  Also
-       hash must be a SHA-256 hash. */
+     * register the hash of the file system contents of the path.  The
+     * hash must be a SHA-256 hash.
+     */
     void registerValidPath(const ValidPathInfo & info);
 
     void registerValidPaths(const ValidPathInfos & infos);
@@ -212,12 +244,16 @@ public:
 
     void addSignatures(const StorePath & storePath, const StringSet & sigs) override;
 
-    /* If free disk space in /nix/store if below minFree, delete
+    /**
-       garbage until it exceeds maxFree. */
+     * If free disk space in /nix/store if below minFree, delete
+     * garbage until it exceeds maxFree.
+     */
     void autoGC(bool sync = true);
 
-    /* Register the store path 'output' as the output named 'outputName' of
+    /**
-       derivation 'deriver'. */
+     * Register the store path 'output' as the output named 'outputName' of
+     * derivation 'deriver'.
+     */
     void registerDrvOutput(const Realisation & info) override;
     void registerDrvOutput(const Realisation & info, CheckSigsFlag checkSigs) override;
     void cacheDrvOutputMapping(
@@ -247,7 +283,9 @@ private:
 
     void invalidatePath(State & state, const StorePath & path);
 
-    /* Delete a path from the Nix store. */
+    /**
+     * Delete a path from the Nix store.
+     */
     void invalidatePathChecked(const StorePath & path);
 
     void verifyPath(const Path & path, const StringSet & store,
@@ -280,8 +318,10 @@ private:
     bool isValidPath_(State & state, const StorePath & path);
     void queryReferrers(State & state, const StorePath & path, StorePathSet & referrers);
 
-    /* Add signatures to a ValidPathInfo or Realisation using the secret keys
+    /**
-       specified by the ‘secret-key-files’ option. */
+     * Add signatures to a ValidPathInfo or Realisation using the secret keys
+     * specified by the ‘secret-key-files’ option.
+     */
     void signPathInfo(ValidPathInfo & info);
     void signRealisation(Realisation &);
 
@@ -311,18 +351,23 @@ typedef std::pair<dev_t, ino_t> Inode;
 typedef std::set<Inode> InodesSeen;
 
 
-/* "Fix", or canonicalise, the meta-data of the files in a store path
+/**
-   after it has been built.  In particular:
+ * "Fix", or canonicalise, the meta-data of the files in a store path
-   - the last modification date on each file is set to 1 (i.e.,
+ * after it has been built.  In particular:
-     00:00:01 1/1/1970 UTC)
+ *
-   - the permissions are set of 444 or 555 (i.e., read-only with or
+ * - the last modification date on each file is set to 1 (i.e.,
-     without execute permission; setuid bits etc. are cleared)
+ *   00:00:01 1/1/1970 UTC)
-   - the owner and group are set to the Nix user and group, if we're
+ *
-     running as root.
+ * - the permissions are set of 444 or 555 (i.e., read-only with or
-   If uidRange is not empty, this function will throw an error if it
+ *   without execute permission; setuid bits etc. are cleared)
-   encounters files owned by a user outside of the closed interval
+ *
-   [uidRange->first, uidRange->second].
+ * - the owner and group are set to the Nix user and group, if we're
-*/
+ *   running as root.
+ *
+ * If uidRange is not empty, this function will throw an error if it
+ * encounters files owned by a user outside of the closed interval
+ * [uidRange->first, uidRange->second].
+ */
 void canonicalisePathMetaData(
     const Path & path,
     std::optional<std::pair<uid_t, uid_t>> uidRange,

src/libstore/lock.hh

@@ -13,14 +13,18 @@ struct UserLock
 {
     virtual ~UserLock() { }
 
-    /* Get the first and last UID. */
+    /**
+     * Get the first and last UID.
+     */
     std::pair<uid_t, uid_t> getUIDRange()
     {
         auto first = getUID();
         return {first, first + getUIDCount() - 1};
     }
 
-    /* Get the first UID. */
+    /**
+     * Get the first UID.
+     */
     virtual uid_t getUID() = 0;
 
     virtual uid_t getUIDCount() = 0;
@@ -30,8 +34,10 @@ struct UserLock
     virtual std::vector<gid_t> getSupplementaryGIDs() = 0;
 };
 
-/* Acquire a user lock for a UID range of size `nrIds`. Note that this
+/**
-   may return nullptr if no user is available. */
+ * Acquire a user lock for a UID range of size `nrIds`. Note that this
+ * may return nullptr if no user is available.
+ */
 std::unique_ptr<UserLock> acquireUserLock(uid_t nrIds, bool useUserNamespace);
 
 bool useBuildUsers();

src/libstore/log-store.hh

@@ -10,8 +10,10 @@ struct LogStore : public virtual Store
 {
     inline static std::string operationName = "Build log storage and retrieval";
 
-    /* Return the build log of the specified store path, if available,
+    /**
-       or null otherwise. */
+     * Return the build log of the specified store path, if available,
+     * or null otherwise.
+     */
     std::optional<std::string> getBuildLog(const StorePath & path);
 
     virtual std::optional<std::string> getBuildLogExact(const StorePath & path) = 0;

src/libstore/nar-accessor.hh

@@ -10,24 +10,30 @@ namespace nix {
 
 struct Source;
 
-/* Return an object that provides access to the contents of a NAR
+/**
-   file. */
+ * Return an object that provides access to the contents of a NAR
+ * file.
+ */
 ref<FSAccessor> makeNarAccessor(std::string && nar);
 
 ref<FSAccessor> makeNarAccessor(Source & source);
 
-/* Create a NAR accessor from a NAR listing (in the format produced by
+/**
-   listNar()). The callback getNarBytes(offset, length) is used by the
+ * Create a NAR accessor from a NAR listing (in the format produced by
-   readFile() method of the accessor to get the contents of files
+ * listNar()). The callback getNarBytes(offset, length) is used by the
-   inside the NAR. */
+ * readFile() method of the accessor to get the contents of files
+ * inside the NAR.
+ */
 typedef std::function<std::string(uint64_t, uint64_t)> GetNarBytes;
 
 ref<FSAccessor> makeLazyNarAccessor(
     const std::string & listing,
     GetNarBytes getNarBytes);
 
-/* Write a JSON representation of the contents of a NAR (except file
+/**
-   contents). */
+ * Write a JSON representation of the contents of a NAR (except file
+ * contents).
+ */
 nlohmann::json listNar(ref<FSAccessor> accessor, const Path & path, bool recurse);
 
 }

src/libstore/nar-info-disk-cache.hh

@@ -43,8 +43,10 @@ public:
         const std::string & uri, const DrvOutput & id) = 0;
 };
 
-/* Return a singleton cache object that can be used concurrently by
+/**
-   multiple threads. */
+ * Return a singleton cache object that can be used concurrently by
+ * multiple threads.
+ */
 ref<NarInfoDiskCache> getNarInfoDiskCache();
 
 ref<NarInfoDiskCache> getTestNarInfoDiskCache(Path dbPath);

src/libstore/path-info.hh

@@ -19,8 +19,14 @@ struct SubstitutablePathInfo
 {
     std::optional<StorePath> deriver;
     StorePathSet references;
-    uint64_t downloadSize; /* 0 = unknown or inapplicable */
+    /**
-    uint64_t narSize; /* 0 = unknown */
+     * 0 = unknown or inapplicable
+     */
+    uint64_t downloadSize;
+    /**
+     * 0 = unknown
+     */
+    uint64_t narSize;
 };
 
 typedef std::map<StorePath, SubstitutablePathInfo> SubstitutablePathInfos;
@@ -30,35 +36,40 @@ struct ValidPathInfo
 {
     StorePath path;
     std::optional<StorePath> deriver;
-    // TODO document this
+    /**
+     * \todo document this
+     */
     Hash narHash;
     StorePathSet references;
     time_t registrationTime = 0;
     uint64_t narSize = 0; // 0 = unknown
     uint64_t id; // internal use only
 
-    /* Whether the path is ultimately trusted, that is, it's a
+    /**
-       derivation output that was built locally. */
+     * Whether the path is ultimately trusted, that is, it's a
+     * derivation output that was built locally.
+     */
     bool ultimate = false;
 
     StringSet sigs; // note: not necessarily verified
 
-    /* If non-empty, an assertion that the path is content-addressed,
+    /**
-       i.e., that the store path is computed from a cryptographic hash
+     * If non-empty, an assertion that the path is content-addressed,
-       of the contents of the path, plus some other bits of data like
+     * i.e., that the store path is computed from a cryptographic hash
-       the "name" part of the path. Such a path doesn't need
+     * of the contents of the path, plus some other bits of data like
-       signatures, since we don't have to trust anybody's claim that
+     * the "name" part of the path. Such a path doesn't need
-       the path is the output of a particular derivation. (In the
+     * signatures, since we don't have to trust anybody's claim that
-       extensional store model, we have to trust that the *contents*
+     * the path is the output of a particular derivation. (In the
-       of an output path of a derivation were actually produced by
+     * extensional store model, we have to trust that the *contents*
-       that derivation. In the intensional model, we have to trust
+     * of an output path of a derivation were actually produced by
-       that a particular output path was produced by a derivation; the
+     * that derivation. In the intensional model, we have to trust
-       path then implies the contents.)
+     * that a particular output path was produced by a derivation; the
-
+     * path then implies the contents.)
-       Ideally, the content-addressability assertion would just be a Boolean,
+     *
-       and the store path would be computed from the name component, ‘narHash’
+     * Ideally, the content-addressability assertion would just be a Boolean,
-       and ‘references’. However, we support many types of content addresses.
+     * and the store path would be computed from the name component, ‘narHash’
-    */
+     * and ‘references’. However, we support many types of content addresses.
+     */
     std::optional<ContentAddress> ca;
 
     bool operator == (const ValidPathInfo & i) const
@@ -69,27 +80,35 @@ struct ValidPathInfo
             && references == i.references;
     }
 
-    /* Return a fingerprint of the store path to be used in binary
+    /**
-       cache signatures. It contains the store path, the base-32
+     * Return a fingerprint of the store path to be used in binary
-       SHA-256 hash of the NAR serialisation of the path, the size of
+     * cache signatures. It contains the store path, the base-32
-       the NAR, and the sorted references. The size field is strictly
+     * SHA-256 hash of the NAR serialisation of the path, the size of
-       speaking superfluous, but might prevent endless/excessive data
+     * the NAR, and the sorted references. The size field is strictly
-       attacks. */
+     * speaking superfluous, but might prevent endless/excessive data
+     * attacks.
+     */
     std::string fingerprint(const Store & store) const;
 
     void sign(const Store & store, const SecretKey & secretKey);
 
-    /* Return true iff the path is verifiably content-addressed. */
+    /**
+     * @return true iff the path is verifiably content-addressed.
+     */
     bool isContentAddressed(const Store & store) const;
 
     static const size_t maxSigs = std::numeric_limits<size_t>::max();
 
-    /* Return the number of signatures on this .narinfo that were
+    /**
-       produced by one of the specified keys, or maxSigs if the path
+     * Return the number of signatures on this .narinfo that were
-       is content-addressed. */
+     * produced by one of the specified keys, or maxSigs if the path
+     * is content-addressed.
+     */
     size_t checkSignatures(const Store & store, const PublicKeys & publicKeys) const;
 
-    /* Verify a single signature. */
+    /**
+     * Verify a single signature.
+     */
     bool checkSignature(const Store & store, const PublicKeys & publicKeys, const std::string & sig) const;
 
     Strings shortRefs() const;

src/libstore/path-with-outputs.hh

@@ -6,13 +6,14 @@
 
 namespace nix {
 
-/* This is a deprecated old type just for use by the old CLI, and older
+/**
-   versions of the RPC protocols. In new code don't use it; you want
+ * This is a deprecated old type just for use by the old CLI, and older
-   `DerivedPath` instead.
+ * versions of the RPC protocols. In new code don't use it; you want
-
+ * `DerivedPath` instead.
-   `DerivedPath` is better because it handles more cases, and does so more
+ *
-   explicitly without devious punning tricks.
+ * `DerivedPath` is better because it handles more cases, and does so more
-*/
+ * explicitly without devious punning tricks.
+ */
 struct StorePathWithOutputs
 {
     StorePath path;
@@ -31,9 +32,11 @@ std::pair<std::string_view, StringSet> parsePathWithOutputs(std::string_view s);
 
 class Store;
 
-/* Split a string specifying a derivation and a set of outputs
+/**
-   (/nix/store/hash-foo!out1,out2,...) into the derivation path
+ * Split a string specifying a derivation and a set of outputs
-   and the outputs. */
+ * (/nix/store/hash-foo!out1,out2,...) into the derivation path
+ * and the outputs.
+ */
 StorePathWithOutputs parsePathWithOutputs(const Store & store, std::string_view pathWithOutputs);
 
 StorePathWithOutputs followLinksToStorePathWithOutputs(const Store & store, std::string_view pathWithOutputs);

src/libstore/pathlocks.hh

@@ -5,12 +5,16 @@
 
 namespace nix {
 
-/* Open (possibly create) a lock file and return the file descriptor.
+/**
-   -1 is returned if create is false and the lock could not be opened
+ * Open (possibly create) a lock file and return the file descriptor.
-   because it doesn't exist.  Any other error throws an exception. */
+ * -1 is returned if create is false and the lock could not be opened
+ * because it doesn't exist.  Any other error throws an exception.
+ */
 AutoCloseFD openLockFile(const Path & path, bool create);
 
-/* Delete an open lock file. */
+/**
+ * Delete an open lock file.
+ */
 void deleteLockFile(const Path & path, int fd);
 
 enum LockType { ltRead, ltWrite, ltNone };

src/libstore/profiles.hh

@@ -1,7 +1,7 @@
 #pragma once
 ///@file
 
-#include "types.hh"
+ #include "types.hh"
 #include "pathlocks.hh"
 
 #include <time.h>
@@ -24,9 +24,11 @@ struct Generation
 typedef std::list<Generation> Generations;
 
 
-/* Returns the list of currently present generations for the specified
+/**
-   profile, sorted by generation number. Also returns the number of
+ * Returns the list of currently present generations for the specified
-   the current generation. */
+ * profile, sorted by generation number. Also returns the number of
+ * the current generation.
+ */
 std::pair<Generations, std::optional<GenerationNumber>> findGenerations(Path profile);
 
 class LocalFSStore;
@@ -47,26 +49,32 @@ void deleteGenerationsOlderThan(const Path & profile, std::string_view timeSpec,
 
 void switchLink(Path link, Path target);
 
-/* Roll back a profile to the specified generation, or to the most
+/**
-   recent one older than the current. */
+ * Roll back a profile to the specified generation, or to the most
+ * recent one older than the current.
+ */
 void switchGeneration(
     const Path & profile,
     std::optional<GenerationNumber> dstGen,
     bool dryRun);
 
-/* Ensure exclusive access to a profile.  Any command that modifies
+/**
-   the profile first acquires this lock. */
+ * Ensure exclusive access to a profile.  Any command that modifies
+ * the profile first acquires this lock.
+ */
 void lockProfile(PathLocks & lock, const Path & profile);
 
-/* Optimistic locking is used by long-running operations like `nix-env
+/**
-   -i'.  Instead of acquiring the exclusive lock for the entire
+ * Optimistic locking is used by long-running operations like `nix-env
-   duration of the operation, we just perform the operation
+ * -i'.  Instead of acquiring the exclusive lock for the entire
-   optimistically (without an exclusive lock), and check at the end
+ * duration of the operation, we just perform the operation
-   whether the profile changed while we were busy (i.e., the symlink
+ * optimistically (without an exclusive lock), and check at the end
-   target changed).  If so, the operation is restarted.  Restarting is
+ * whether the profile changed while we were busy (i.e., the symlink
-   generally cheap, since the build results are still in the Nix
+ * target changed).  If so, the operation is restarted.  Restarting is
-   store.  Most of the time, only the user environment has to be
+ * generally cheap, since the build results are still in the Nix
-   rebuilt. */
+ * store.  Most of the time, only the user environment has to be
+ * rebuilt.
+ */
 std::string optimisticLockProfile(const Path & profile);
 
 /**

src/libstore/remote-store.hh

@@ -32,8 +32,10 @@ struct RemoteStoreConfig : virtual StoreConfig
         "Maximum age of a connection before it is closed."};
 };
 
-/* FIXME: RemoteStore is a misnomer - should be something like
+/**
-   DaemonStore. */
+ * \todo RemoteStore is a misnomer - should be something like
+ * DaemonStore.
+ */
 class RemoteStore : public virtual RemoteStoreConfig,
     public virtual Store,
     public virtual GcStore,
@@ -69,7 +71,9 @@ public:
     void querySubstitutablePathInfos(const StorePathCAMap & paths,
         SubstitutablePathInfos & infos) override;
 
-    /* Add a content-addressable store path. `dump` will be drained. */
+    /**
+     * Add a content-addressable store path. `dump` will be drained.
+     */
     ref<const ValidPathInfo> addCAToStore(
         Source & dump,
         std::string_view name,
@@ -77,7 +81,9 @@ public:
         const StorePathSet & references,
         RepairFlag repair);
 
-    /* Add a content-addressable store path. Does not support references. `dump` will be drained. */
+    /**
+     * Add a content-addressable store path. Does not support references. `dump` will be drained.
+     */
     StorePath addToStoreFromDump(Source & dump, std::string_view name,
         FileIngestionMethod method = FileIngestionMethod::Recursive, HashType hashAlgo = htSHA256, RepairFlag repair = NoRepair, const StorePathSet & references = StorePathSet()) override;
 

src/libstore/sqlite.hh

@@ -11,7 +11,9 @@ struct sqlite3_stmt;
 
 namespace nix {
 
-/* RAII wrapper to close a SQLite database automatically. */
+/**
+ * RAII wrapper to close a SQLite database automatically.
+ */
 struct SQLite
 {
     sqlite3 * db = 0;
@@ -23,7 +25,9 @@ struct SQLite
     ~SQLite();
     operator sqlite3 * () { return db; }
 
-    /* Disable synchronous mode, set truncate journal mode. */
+    /**
+     * Disable synchronous mode, set truncate journal mode.
+     */
     void isCache();
 
     void exec(const std::string & stmt);
@@ -31,7 +35,9 @@ struct SQLite
     uint64_t getLastInsertedRowId();
 };
 
-/* RAII wrapper to create and destroy SQLite prepared statements. */
+/**
+ * RAII wrapper to create and destroy SQLite prepared statements.
+ */
 struct SQLiteStmt
 {
     sqlite3 * db = 0;
@@ -43,7 +49,9 @@ struct SQLiteStmt
     ~SQLiteStmt();
     operator sqlite3_stmt * () { return stmt; }
 
-    /* Helper for binding / executing statements. */
+    /**
+     * Helper for binding / executing statements.
+     */
     class Use
     {
         friend struct SQLiteStmt;
@@ -56,7 +64,9 @@ struct SQLiteStmt
 
         ~Use();
 
-        /* Bind the next parameter. */
+        /**
+         * Bind the next parameter.
+         */
         Use & operator () (std::string_view value, bool notNull = true);
         Use & operator () (const unsigned char * data, size_t len, bool notNull = true);
         Use & operator () (int64_t value, bool notNull = true);
@@ -64,11 +74,15 @@ struct SQLiteStmt
 
         int step();
 
-        /* Execute a statement that does not return rows. */
+        /**
+         * Execute a statement that does not return rows.
+         */
         void exec();
 
-        /* For statements that return 0 or more rows. Returns true iff
+        /**
-           a row is available. */
+         * For statements that return 0 or more rows. Returns true iff
+         * a row is available.
+         */
         bool next();
 
         std::string getStr(int col);
@@ -82,8 +96,10 @@ struct SQLiteStmt
     }
 };
 
-/* RAII helper that ensures transactions are aborted unless explicitly
+/**
-   committed. */
+ * RAII helper that ensures transactions are aborted unless explicitly
+ * committed.
+ */
 struct SQLiteTxn
 {
     bool active = false;
@@ -125,8 +141,10 @@ MakeError(SQLiteBusy, SQLiteError);
 
 void handleSQLiteBusy(const SQLiteBusy & e);
 
-/* Convenience function for retrying a SQLite transaction when the
+/**
-   database is busy. */
+ * Convenience function for retrying a SQLite transaction when the
+ * database is busy.
+ */
 template<typename T, typename F>
 T retrySQLite(F && fun)
 {

src/libstore/store-api.hh

@@ -411,17 +411,17 @@ public:
     { unsupported("queryReferrers"); }
 
     /**
-     * @return all currently valid derivations that have `path' as an
+     * @return all currently valid derivations that have `path` as an
      * output.
      *
-     * (Note that the result of `queryDeriver()' is the derivation that
+     * (Note that the result of `queryDeriver()` is the derivation that
-     * was actually used to produce `path', which may not exist
+     * was actually used to produce `path`, which may not exist
      * anymore.)
      */
     virtual StorePathSet queryValidDerivers(const StorePath & path) { return {}; };
 
     /**
-     * Query the outputs of the derivation denoted by `path'.
+     * Query the outputs of the derivation denoted by `path`.
      */
     virtual StorePathSet queryDerivationOutputs(const StorePath & path);
 
@@ -513,7 +513,7 @@ public:
 
     /**
      * Like addToStore(), but the contents of the path are contained
-     * in `dump', which is either a NAR serialisation (if recursive ==
+     * in `dump`, which is either a NAR serialisation (if recursive ==
      * true) or simply the contents of a regular file (if recursive ==
      * false).
      * `dump` may be drained
@@ -634,8 +634,8 @@ public:
 
     /**
      * @return a string representing information about the path that
-     * can be loaded into the database using `nix-store --load-db' or
+     * can be loaded into the database using `nix-store --load-db` or
-     * `nix-store --register-validity'.
+     * `nix-store --register-validity`.
      */
     std::string makeValidityRegistration(const StorePathSet & paths,
         bool showDerivers, bool showHash);
@@ -715,12 +715,12 @@ public:
 
     /**
      * @param [out] out Place in here the set of all store paths in the
-     * file system closure of `storePath'; that is, all paths than can
+     * file system closure of `storePath`; that is, all paths than can
-     * be directly or indirectly reached from it. `out' is not cleared.
+     * be directly or indirectly reached from it. `out` is not cleared.
      *
      * @param flipDirection If true, the set of paths that can reach
-     * `storePath' is returned; that is, the closures under the
+     * `storePath` is returned; that is, the closures under the
-     * `referrers' relation instead of the `references' relation is
+     * `referrers` relation instead of the `references` relation is
      * returned.
      */
     virtual void computeFSClosure(const StorePathSet & paths,

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"

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(
+ * IF path points to a REGULAR FILE:
- *         [ ("type", "regular")
+ *   dump(path) = attrs(
- *         , ("contents", contents(path))
+ *     [ ("type", "regular")
- *         ])
+ *     , ("contents", contents(path))
+ *     ])
  *
- *     IF path points to a DIRECTORY:
+ * IF path points to a DIRECTORY:
- *       dump(path) = attrs(
+ *   dump(path) = attrs(
- *         [ ("type", "directory")
+ *     [ ("type", "directory")
- *         , ("entries", concat(map(f, sort(entries(path)))))
+ *     , ("entries", concat(map(f, sort(entries(path)))))
- *         ])
+ *     ])
- *         where f(fn) = attrs(
+ *     where f(fn) = attrs(
- *           [ ("name", fn)
+ *       [ ("name", fn)
- *           , ("file", dump(path + "/" + fn))
+ *       , ("file", dump(path + "/" + fn))
- *           ])
+ *       ])
  *
- *     where:
+ * where:
  *
- *       attrs(as) = concat(map(attr, as)) + encN(0)
+ *   attrs(as) = concat(map(attr, as)) + encN(0)
- *       attrs((a, b)) = encS(a) + encS(b)
+ *   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
 {

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;
 };
 

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,

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
+ * Print a message with the standard ErrorInfo format.
-   intervention or that need more explanation.  Use the 'print' macros for more
+ * In general, use these 'log' macros for reporting problems that may require user
-   lightweight status messages. */
+ * 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
+ * Print a string message if the current log level is at least the specified
-   arguments are evaluated lazily. */
+ * 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; \

src/libutil/thread-pool.hh

@@ -41,14 +41,14 @@ public:
     /**
      * Execute work items until the queue is empty.
      *
-	 * \note Note that work items are allowed to add new items to the
+     * \note Note that work items are allowed to add new items to the
-	 * queue; this is handled correctly.
+     * queue; this is handled correctly.
      *
-	 * Queue processing stops prematurely if any work item throws an
+     * Queue processing stops prematurely if any work item throws an
-	 * exception. This exception is propagated to the calling thread. If
+     * exception. This exception is propagated to the calling thread. If
-	 * multiple work items throw an exception concurrently, only one
+     * multiple work items throw an exception concurrently, only one
-	 * item is propagated; the others are printed on stderr and
+     * item is propagated; the others are printed on stderr and
-	 * otherwise ignored.
+     * otherwise ignored.
      */
     void process();
 

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
+ * @return An absolutized path, resolving paths relative to the
-   is also canonicalised. */
+ * 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
+ * Canonicalise a path by removing all `.` or `..` components and
-   components such that each component of the resulting path is *not*
+ * double or trailing slashes.  Optionally resolves all symlink
-   a symbolic link. */
+ * 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
+ * @return The directory part of the given canonical path, i.e.,
-   immediate child thereof (e.g., `/foo'), this means `/'
+ * everything before the final `/`.  If the path is the root or an
-   is returned.*/
+ * 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
+ * Delete a path; i.e., in the case of a directory, it is deleted
-   second variant returns the number of bytes and blocks freed. */
+ * 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
+ * Cause this thread to not share any FS attributes with the main
-   fail. */
+ * 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
+ * Convert a list of strings to a null-terminated vector of `char
-   list of strings. */
+ * *`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,
+ * Truncate a string to 'width' printable characters. If 'filterAll'
-   some escape sequences (such as colour setting) are copied but not
+ * is true, all ANSI escape sequences are filtered out. Otherwise,
-   included in the character count. Also, tabs are expanded to
+ * some escape sequences (such as colour setting) are copied but not
-   spaces. */
+ * 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,
+ * Remove common leading whitespace from the lines in the string
-   then we remove 3 spaces from the start of every line. */
+ * '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
+ * Get the prefix of 's' up to and excluding the next line break (LF
-   break. */
+ * 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
+ * A RAII class that causes the current thread to receive SIGUSR1 when
-   SIGINT to be multiplexed to multiple threads. */
+ * 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;