Merge pull request #8111 from obsidiansystems/improve-internal-api-docs

Convert a bunch of comments in headers to Doxygen documentation

src/libstore/content-address.hh

@@ -5,44 +5,75 @@
 
 namespace nix {
 
+/**
+ * An enumeration of the ways we can serialize file system objects.
+ */
 enum struct FileIngestionMethod : uint8_t {
+    /**
+     * Flat-file hashing. Directly ingest the contents of a single file
+     */
     Flat = false,
+    /**
+     * Recursive (or NAR) hashing. Serializes the file-system object in Nix
+     * Archive format and ingest that
+     */
     Recursive = true
 };
 
+/**
+ * Somewhat obscure, used by \ref Derivation derivations and
+ * `builtins.toFile` currently.
+ */
 struct TextHash {
+    /**
+     * Hash of the contents of the text/file.
+     */
     Hash hash;
 };
 
-/// Pair of a hash, and how the file system was ingested
+/**
+ * For path computed by makeFixedOutputPath.
+ */
 struct FixedOutputHash {
+    /**
+     * How the file system objects are serialized
+     */
     FileIngestionMethod method;
+    /**
+     * Hash of that serialization
+     */
     Hash hash;
+
     std::string printMethodAlgo() const;
 };
 
-/*
+/**
-  We've accumulated several types of content-addressed paths over the years;
+ * We've accumulated several types of content-addressed paths over the
-  fixed-output derivations support multiple hash algorithms and serialisation
+ * years; fixed-output derivations support multiple hash algorithms and
-  methods (flat file vs NAR). Thus, ‘ca’ has one of the following forms:
+ * serialisation methods (flat file vs NAR). Thus, ‘ca’ has one of the
-
+ * following forms:
-  * ‘text:sha256:<sha256 hash of file contents>’: For paths
+ *
-    computed by makeTextPath() / addTextToStore().
+ * - ‘text:sha256:<sha256 hash of file contents>’: For paths
-
+ *   computed by Store::makeTextPath() / Store::addTextToStore().
-  * ‘fixed:<r?>:<ht>:<h>’: For paths computed by
+ *
-    makeFixedOutputPath() / addToStore().
+ * - ‘fixed:<r?>:<ht>:<h>’: For paths computed by
-*/
+ *   Store::makeFixedOutputPath() / Store::addToStore().
+ */
 typedef std::variant<
-    TextHash, // for paths computed by makeTextPath() / addTextToStore
+    TextHash,
-    FixedOutputHash // for path computed by makeFixedOutputPath
+    FixedOutputHash
 > ContentAddress;
 
-/* Compute the prefix to the hash algorithm which indicates how the files were
+/**
-   ingested. */
+ * Compute the prefix to the hash algorithm which indicates how the
+ * files were ingested.
+ */
 std::string makeFileIngestionPrefix(const FileIngestionMethod m);
 
-/* Compute the content-addressability assertion (ValidPathInfo::ca)
+/**
-   for paths created by makeFixedOutputPath() / addToStore(). */
+ * Compute the content-addressability assertion (ValidPathInfo::ca) for
+ * paths created by Store::makeFixedOutputPath() / Store::addToStore().
+ */
 std::string makeFixedOutputCA(FileIngestionMethod method, const Hash & hash);
 
 std::string renderContentAddress(ContentAddress ca);
@@ -65,6 +96,11 @@ struct FixedOutputHashMethod {
   HashType hashType;
 };
 
+/**
+ * Ways of content addressing but not a complete ContentAddress.
+ *
+ * A ContentAddress without a Hash.
+ */
 typedef std::variant<
     TextHashMethod,
     FixedOutputHashMethod

src/libstore/derivations.hh

@@ -17,42 +17,72 @@ class Store;
 
 /* Abstract syntax of derivations. */
 
-/* The traditional non-fixed-output derivation type. */
+/**
+ * The traditional non-fixed-output derivation type.
+ */
 struct DerivationOutputInputAddressed
 {
     StorePath path;
 };
 
-/* Fixed-output derivations, whose output paths are content addressed
+/**
-   according to that fixed output. */
+ * Fixed-output derivations, whose output paths are content
+ * addressed according to that fixed output.
+ */
 struct DerivationOutputCAFixed
 {
-    FixedOutputHash hash; /* hash used for expected hash computation */
+    /**
+     * hash used for expected hash computation
+     */
+    FixedOutputHash hash;
+
+    /**
+     * Return the \ref StorePath "store path" corresponding to this output
+     *
+     * @param drvName The name of the derivation this is an output of, without the `.drv`.
+     * @param outputName The name of this output.
+     */
     StorePath path(const Store & store, std::string_view drvName, std::string_view outputName) const;
 };
 
-/* Floating-output derivations, whose output paths are content addressed, but
+/**
-   not fixed, and so are dynamically calculated from whatever the output ends
+ * Floating-output derivations, whose output paths are content
-   up being. */
+ * addressed, but not fixed, and so are dynamically calculated from
+ * whatever the output ends up being.
+ * */
 struct DerivationOutputCAFloating
 {
-    /* information used for expected hash computation */
+    /**
+     * How the file system objects will be serialized for hashing
+     */
     FileIngestionMethod method;
+
+    /**
+     * How the serialization will be hashed
+     */
     HashType hashType;
 };
 
-/* Input-addressed output which depends on a (CA) derivation whose hash isn't
+/**
- * known yet.
+ * Input-addressed output which depends on a (CA) derivation whose hash
+ * isn't known yet.
  */
 struct DerivationOutputDeferred {};
 
-/* Impure output which is moved to a content-addressed location (like
+/**
-   CAFloating) but isn't registered as a realization.
+ * Impure output which is moved to a content-addressed location (like
+ * CAFloating) but isn't registered as a realization.
  */
 struct DerivationOutputImpure
 {
-    /* information used for expected hash computation */
+    /**
+     * How the file system objects will be serialized for hashing
+     */
     FileIngestionMethod method;
+
+    /**
+     * How the serialization will be hashed
+     */
     HashType hashType;
 };
 
@@ -64,6 +94,9 @@ typedef std::variant<
     DerivationOutputImpure
 > _DerivationOutputRaw;
 
+/**
+ * A single output of a BasicDerivation (and Derivation).
+ */
 struct DerivationOutput : _DerivationOutputRaw
 {
     using Raw = _DerivationOutputRaw;
@@ -75,9 +108,12 @@ struct DerivationOutput : _DerivationOutputRaw
     using Deferred = DerivationOutputDeferred;
     using Impure = DerivationOutputImpure;
 
-    /* Note, when you use this function you should make sure that you're passing
+    /**
-       the right derivation name. When in doubt, you should use the safer
+     * \note when you use this function you should make sure that you're
-       interface provided by BasicDerivation::outputsAndOptPaths */
+     * passing the right derivation name. When in doubt, you should use
+     * the safer interface provided by
+     * BasicDerivation::outputsAndOptPaths
+     */
     std::optional<StorePath> path(const Store & store, std::string_view drvName, std::string_view outputName) const;
 
     inline const Raw & raw() const {
@@ -92,26 +128,61 @@ struct DerivationOutput : _DerivationOutputRaw
 
 typedef std::map<std::string, DerivationOutput> DerivationOutputs;
 
-/* These are analogues to the previous DerivationOutputs data type, but they
+/**
-   also contains, for each output, the (optional) store path in which it would
+ * These are analogues to the previous DerivationOutputs data type,
-   be written. To calculate values of these types, see the corresponding
+ * but they also contains, for each output, the (optional) store
-   functions in BasicDerivation */
+ * path in which it would be written. To calculate values of these
+ * types, see the corresponding functions in BasicDerivation.
+ */
 typedef std::map<std::string, std::pair<DerivationOutput, std::optional<StorePath>>>
   DerivationOutputsAndOptPaths;
 
-/* For inputs that are sub-derivations, we specify exactly which
+/**
-   output IDs we are interested in. */
+ * For inputs that are sub-derivations, we specify exactly which
+ * output IDs we are interested in.
+ */
 typedef std::map<StorePath, StringSet> DerivationInputs;
 
+/**
+ * Input-addressed derivation types
+ */
 struct DerivationType_InputAddressed {
+    /**
+     * True iff the derivation type can't be determined statically,
+     * for instance because it (transitively) depends on a content-addressed
+     * derivation.
+    */
     bool deferred;
 };
 
+/**
+ * Content-addressed derivation types
+ */
 struct DerivationType_ContentAddressed {
+    /**
+     * Whether the derivation should be built safely inside a sandbox.
+     */
     bool sandboxed;
+    /**
+     * Whether the derivation's outputs' content-addresses are "fixed"
+     * or "floating.
+     *
+     *  - Fixed: content-addresses are written down as part of the
+     *    derivation itself. If the outputs don't end up matching the
+     *    build fails.
+     *
+     *  - Floating: content-addresses are not written down, we do not
+     *    know them until we perform the build.
+     */
     bool fixed;
 };
 
+/**
+ * Impure derivation type
+ *
+ * This is similar at buil-time to the content addressed, not standboxed, not fixed
+ * type, but has some restrictions on its usage.
+ */
 struct DerivationType_Impure {
 };
 
@@ -128,30 +199,38 @@ struct DerivationType : _DerivationTypeRaw {
     using ContentAddressed = DerivationType_ContentAddressed;
     using Impure = DerivationType_Impure;
 
-    /* Do the outputs of the derivation have paths calculated from their content,
+    /**
-       or from the derivation itself? */
+     * Do the outputs of the derivation have paths calculated from their
+     * content, or from the derivation itself?
+     */
     bool isCA() const;
 
-    /* Is the content of the outputs fixed a-priori via a hash? Never true for
+    /**
-       non-CA derivations. */
+     * Is the content of the outputs fixed <em>a priori</em> via a hash?
+     * Never true for non-CA derivations.
+     */
     bool isFixed() const;
 
-    /* Whether the derivation is fully sandboxed. If false, the
+    /**
-       sandbox is opened up, e.g. the derivation has access to the
+     * Whether the derivation is fully sandboxed. If false, the sandbox
-       network. Note that whether or not we actually sandbox the
+     * is opened up, e.g. the derivation has access to the network. Note
-       derivation is controlled separately. Always true for non-CA
+     * that whether or not we actually sandbox the derivation is
-       derivations. */
+     * controlled separately. Always true for non-CA derivations.
+     */
     bool isSandboxed() const;
 
-    /* Whether the derivation is expected to produce the same result
+    /**
-       every time, and therefore it only needs to be built once. This
+     * Whether the derivation is expected to produce the same result
-       is only false for derivations that have the attribute '__impure
+     * every time, and therefore it only needs to be built once. This is
-       = true'. */
+     * only false for derivations that have the attribute '__impure =
+     * true'.
+     */
     bool isPure() const;
 
-    /* Does the derivation knows its own output paths?
+    /**
-       Only true when there's no floating-ca derivation involved in the
+     * Does the derivation knows its own output paths?
-       closure, or if fixed output.
+     * Only true when there's no floating-ca derivation involved in the
+     * closure, or if fixed output.
      */
     bool hasKnownOutputPaths() const;
 
@@ -175,15 +254,21 @@ struct BasicDerivation
 
     bool isBuiltin() const;
 
-    /* Return true iff this is a fixed-output derivation. */
+    /**
+     * Return true iff this is a fixed-output derivation.
+     */
     DerivationType type() const;
 
-    /* Return the output names of a derivation. */
+    /**
+     * Return the output names of a derivation.
+     */
     StringSet outputNames() const;
 
-    /* Calculates the maps that contains all the DerivationOutputs, but
+    /**
-       augmented with knowledge of the Store paths they would be written
+     * Calculates the maps that contains all the DerivationOutputs, but
-       into. */
+     * augmented with knowledge of the Store paths they would be written
+     * into.
+     */
     DerivationOutputsAndOptPaths outputsAndOptPaths(const Store & store) const;
 
     static std::string_view nameFromPath(const StorePath & storePath);
@@ -191,23 +276,33 @@ struct BasicDerivation
 
 struct Derivation : BasicDerivation
 {
-    DerivationInputs inputDrvs; /* inputs that are sub-derivations */
+    /**
+     * inputs that are sub-derivations
+     */
+    DerivationInputs inputDrvs;
 
-    /* Print a derivation. */
+    /**
+     * Print a derivation.
+     */
     std::string unparse(const Store & store, bool maskOutputs,
         std::map<std::string, StringSet> * actualInputs = nullptr) const;
 
-    /* Return the underlying basic derivation but with these changes:
+    /**
-
+     * Return the underlying basic derivation but with these changes:
-       1. Input drvs are emptied, but the outputs of them that were used are
+     *
-          added directly to input sources.
+     * 1. Input drvs are emptied, but the outputs of them that were used
-
+     *    are added directly to input sources.
-       2. Input placeholders are replaced with realized input store paths. */
+     *
+     * 2. Input placeholders are replaced with realized input store
+     *    paths.
+     */
     std::optional<BasicDerivation> tryResolve(Store & store) const;
 
-    /* Like the above, but instead of querying the Nix database for
+    /**
-       realisations, uses a given mapping from input derivation paths
+     * Like the above, but instead of querying the Nix database for
-       + output names to actual output store paths. */
+     * realisations, uses a given mapping from input derivation paths +
+     * output names to actual output store paths.
+     */
     std::optional<BasicDerivation> tryResolve(
         Store & store,
         const std::map<std::pair<StorePath, std::string>, StorePath> & inputDrvOutputs) const;
@@ -222,81 +317,108 @@ struct Derivation : BasicDerivation
 
 class Store;
 
-/* Write a derivation to the Nix store, and return its path. */
+/**
+ * Write a derivation to the Nix store, and return its path.
+ */
 StorePath writeDerivation(Store & store,
     const Derivation & drv,
     RepairFlag repair = NoRepair,
     bool readOnly = false);
 
-/* Read a derivation from a file. */
+/**
+ * Read a derivation from a file.
+ */
 Derivation parseDerivation(const Store & store, std::string && s, std::string_view name);
 
-// FIXME: remove
+/**
+ * \todo Remove.
+ *
+ * Use Path::isDerivation instead.
+ */
 bool isDerivation(std::string_view fileName);
 
-/* Calculate the name that will be used for the store path for this
+/**
-   output.
+ * Calculate the name that will be used for the store path for this
-
+ * output.
-   This is usually <drv-name>-<output-name>, but is just <drv-name> when
+ *
-   the output name is "out". */
+ * This is usually <drv-name>-<output-name>, but is just <drv-name> when
+ * the output name is "out".
+ */
 std::string outputPathName(std::string_view drvName, std::string_view outputName);
 
 
-// The hashes modulo of a derivation.
+/**
-//
+ * The hashes modulo of a derivation.
-// Each output is given a hash, although in practice only the content-addressed
+ *
-// derivations (fixed-output or not) will have a different hash for each
+ * Each output is given a hash, although in practice only the content-addressed
-// output.
+ * derivations (fixed-output or not) will have a different hash for each
+ * output.
+ */
 struct DrvHash {
+    /**
+     * Map from output names to hashes
+     */
     std::map<std::string, Hash> hashes;
 
     enum struct Kind : bool {
-        // Statically determined derivations.
+        /**
-        // This hash will be directly used to compute the output paths
+         * Statically determined derivations.
+         * This hash will be directly used to compute the output paths
+         */
         Regular,
-        // Floating-output derivations (and their reverse dependencies).
+
+        /**
+         * Floating-output derivations (and their reverse dependencies).
+         */
         Deferred,
     };
 
+    /**
+     * The kind of derivation this is, simplified for just "derivation hash
+     * modulo" purposes.
+     */
     Kind kind;
 };
 
 void operator |= (DrvHash::Kind & self, const DrvHash::Kind & other) noexcept;
 
-/* Returns hashes with the details of fixed-output subderivations
+/**
-   expunged.
+ * Returns hashes with the details of fixed-output subderivations
-
+ * expunged.
-   A fixed-output derivation is a derivation whose outputs have a
+ *
-   specified content hash and hash algorithm. (Currently they must have
+ * A fixed-output derivation is a derivation whose outputs have a
-   exactly one output (`out'), which is specified using the `outputHash'
+ * specified content hash and hash algorithm. (Currently they must have
-   and `outputHashAlgo' attributes, but the algorithm doesn't assume
+ * exactly one output (`out'), which is specified using the `outputHash'
-   this.) We don't want changes to such derivations to propagate upwards
+ * and `outputHashAlgo' attributes, but the algorithm doesn't assume
-   through the dependency graph, changing output paths everywhere.
+ * 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'
+ *
-   function, we do not want to rebuild everything depending on it---after
+ * For instance, if we change the url in a call to the `fetchurl'
-   all, (the hash of) the file being downloaded is unchanged.  So the
+ * function, we do not want to rebuild everything depending on it---after
-   *output paths* should not change. On the other hand, the *derivation
+ * all, (the hash of) the file being downloaded is unchanged.  So the
-   paths* should change to reflect the new dependency graph.
+ * *output paths* should not change. On the other hand, the *derivation
-
+ * paths* should change to reflect the new dependency graph.
-   For fixed-output derivations, this returns a map from the name of
+ *
-   each output to its hash, unique up to the output's contents.
+ * For fixed-output derivations, this returns a map from the name of
-
+ * each output to its hash, unique up to the output's contents.
-   For regular derivations, it returns a single hash of the derivation
+ *
-   ATerm, after subderivations have been likewise expunged from that
+ * For regular derivations, it returns a single hash of the derivation
-   derivation.
+ * ATerm, after subderivations have been likewise expunged from that
+ * derivation.
  */
 DrvHash hashDerivationModulo(Store & store, const Derivation & drv, bool maskOutputs);
 
-/*
+/**
-   Return a map associating each output to a hash that uniquely identifies its
+ * Return a map associating each output to a hash that uniquely identifies its
-   derivation (modulo the self-references).
+ * derivation (modulo the self-references).
-
+ *
-   FIXME: what is the Hash in this map?
+ * \todo What is the Hash in this map?
  */
 std::map<std::string, Hash> staticOutputHashes(Store & store, const Derivation & drv);
 
-/* Memoisation of hashDerivationModulo(). */
+/**
+ * Memoisation of hashDerivationModulo().
+ */
 typedef std::map<StorePath, DrvHash> DrvHashes;
 
 // FIXME: global, though at least thread-safe.
@@ -308,21 +430,25 @@ struct Sink;
 Source & readDerivation(Source & in, const Store & store, BasicDerivation & drv, std::string_view name);
 void writeDerivation(Sink & out, const Store & store, const BasicDerivation & drv);
 
-/* This creates an opaque and almost certainly unique string
+/**
-   deterministically from the output name.
+ * This creates an opaque and almost certainly unique string
-
+ * deterministically from the output name.
-   It is used as a placeholder to allow derivations to refer to their
+ *
-   own outputs without needing to use the hash of a derivation in
+ * It is used as a placeholder to allow derivations to refer to their
-   itself, making the hash near-impossible to calculate. */
+ * own outputs without needing to use the hash of a derivation in
+ * itself, making the hash near-impossible to calculate.
+ */
 std::string hashPlaceholder(const std::string_view outputName);
 
-/* This creates an opaque and almost certainly unique string
+/**
-   deterministically from a derivation path and output name.
+ * This creates an opaque and almost certainly unique string
-
+ * deterministically from a derivation path and output name.
-   It is used as a placeholder to allow derivations to refer to
+ *
-   content-addressed paths whose content --- and thus the path
+ * It is used as a placeholder to allow derivations to refer to
-   themselves --- isn't yet known. This occurs when a derivation has a
+ * content-addressed paths whose content --- and thus the path
-   dependency which is a CA derivation. */
+ * themselves --- isn't yet known. This occurs when a derivation has a
+ * dependency which is a CA derivation.
+ */
 std::string downstreamPlaceholder(const Store & store, const StorePath & drvPath, std::string_view outputName);
 
 extern const Hash impureOutputHash;

src/libstore/derived-path.hh

@@ -105,7 +105,7 @@ using _BuiltPathRaw = std::variant<
 >;
 
 /**
- * A built path. Similar to a `DerivedPath`, but enriched with the corresponding
+ * A built path. Similar to a DerivedPath, but enriched with the corresponding
  * output path(s).
  */
 struct BuiltPath : _BuiltPathRaw {

src/libstore/outputs-spec.hh

@@ -9,6 +9,9 @@
 
 namespace nix {
 
+/**
+ * A non-empty set of outputs, specified by name
+ */
 struct OutputNames : std::set<std::string> {
     using std::set<std::string>::set;
 
@@ -18,6 +21,9 @@ struct OutputNames : std::set<std::string> {
         : std::set<std::string>(s)
     { assert(!empty()); }
 
+    /**
+     * Needs to be "inherited manually"
+     */
     OutputNames(std::set<std::string> && s)
         : std::set<std::string>(s)
     { assert(!empty()); }
@@ -28,6 +34,9 @@ struct OutputNames : std::set<std::string> {
     OutputNames() = delete;
 };
 
+/**
+ * The set of all outputs, without needing to name them explicitly
+ */
 struct AllOutputs : std::monostate { };
 
 typedef std::variant<AllOutputs, OutputNames> _OutputsSpecRaw;
@@ -36,7 +45,9 @@ struct OutputsSpec : _OutputsSpecRaw {
     using Raw = _OutputsSpecRaw;
     using Raw::Raw;
 
-    /* Force choosing a variant */
+    /**
+     * Force choosing a variant
+     */
     OutputsSpec() = delete;
 
     using Names = OutputNames;
@@ -52,14 +63,20 @@ struct OutputsSpec : _OutputsSpecRaw {
 
     bool contains(const std::string & output) const;
 
-    /* Create a new OutputsSpec which is the union of this and that. */
+    /**
+     * Create a new OutputsSpec which is the union of this and that.
+     */
     OutputsSpec union_(const OutputsSpec & that) const;
 
-    /* Whether this OutputsSpec is a subset of that. */
+    /**
+     * Whether this OutputsSpec is a subset of that.
+     */
     bool isSubsetOf(const OutputsSpec & outputs) const;
 
-    /* Parse a string of the form 'output1,...outputN' or
+    /**
-       '*', returning the outputs spec. */
+     * Parse a string of the form 'output1,...outputN' or '*', returning
+     * the outputs spec.
+     */
     static OutputsSpec parse(std::string_view s);
     static std::optional<OutputsSpec> parseOpt(std::string_view s);
 
@@ -81,8 +98,10 @@ struct ExtendedOutputsSpec : _ExtendedOutputsSpecRaw {
         return static_cast<const Raw &>(*this);
     }
 
-    /* Parse a string of the form 'prefix^output1,...outputN' or
+    /**
-       'prefix^*', returning the prefix and the extended outputs spec. */
+     * Parse a string of the form 'prefix^output1,...outputN' or
+     * 'prefix^*', returning the prefix and the extended outputs spec.
+     */
     static std::pair<std::string_view, ExtendedOutputsSpec> parse(std::string_view s);
     static std::optional<std::pair<std::string_view, ExtendedOutputsSpec>> parseOpt(std::string_view s);
 

src/libstore/path.hh

@@ -8,13 +8,22 @@ namespace nix {
 
 struct Hash;
 
+/**
+ * \ref StorePath "Store path" is the fundamental reference type of Nix.
+ * A store paths refers to a Store object.
+ *
+ * See glossary.html#gloss-store-path for more information on a
+ * conceptual level.
+ */
 class StorePath
 {
     std::string baseName;
 
 public:
 
-    /* Size of the hash part of store paths, in base-32 characters. */
+    /**
+     * Size of the hash part of store paths, in base-32 characters.
+     */
     constexpr static size_t HashLen = 32; // i.e. 160 bits
 
     constexpr static size_t MaxPathLen = 211;
@@ -45,8 +54,9 @@ public:
         return baseName != other.baseName;
     }
 
-    /* Check whether a file name ends with the extension for
+    /**
-       derivations. */
+     * Check whether a file name ends with the extension for derivations.
+     */
     bool isDerivation() const;
 
     std::string_view name() const
@@ -67,7 +77,10 @@ public:
 typedef std::set<StorePath> StorePathSet;
 typedef std::vector<StorePath> StorePaths;
 
-/* Extension of derivations in the Nix store. */
+/**
+ * The file extension of \ref Derivation derivations when serialized
+ * into store objects.
+ */
 const std::string drvExtension = ".drv";
 
 }

src/libstore/store-api.hh

@@ -55,7 +55,10 @@ namespace nix {
  */
 
 MakeError(SubstError, Error);
-MakeError(BuildError, Error); // denotes a permanent build failure
+/**
+ * denotes a permanent build failure
+ */
+MakeError(BuildError, Error);
 MakeError(InvalidPath, Error);
 MakeError(Unsupported, Error);
 MakeError(SubstituteGone, Error);
@@ -78,7 +81,9 @@ enum CheckSigsFlag : bool { NoCheckSigs = false, CheckSigs = true };
 enum SubstituteFlag : bool { NoSubstitute = false, Substitute = true };
 enum AllowInvalidFlag : bool { DisallowInvalid = false, AllowInvalid = true };
 
-/* Magic header of exportPath() output (obsolete). */
+/**
+ * Magic header of exportPath() output (obsolete).
+ */
 const uint32_t exportMagic = 0x4558494e;
 
 
@@ -153,17 +158,26 @@ protected:
 
     struct PathInfoCacheValue {
 
-        // Time of cache entry creation or update
+        /**
+         * Time of cache entry creation or update
+         */
         std::chrono::time_point<std::chrono::steady_clock> time_point = std::chrono::steady_clock::now();
 
-        // Null if missing
+        /**
+         * Null if missing
+         */
         std::shared_ptr<const ValidPathInfo> value;
 
-        // Whether the value is valid as a cache entry. The path may not exist.
+        /**
+         * Whether the value is valid as a cache entry. The path may not
+         * exist.
+         */
         bool isKnownNow();
 
-        // Past tense, because a path can only be assumed to exists when
+        /**
-        // isKnownNow() && didExist()
+         * Past tense, because a path can only be assumed to exists when
+         * isKnownNow() && didExist()
+         */
         inline bool didExist() {
           return value != nullptr;
         }
@@ -197,35 +211,53 @@ public:
 
     std::string printStorePath(const StorePath & path) const;
 
-    // FIXME: remove
+    /**
+     * Deprecated
+     *
+     * \todo remove
+     */
     StorePathSet parseStorePathSet(const PathSet & paths) const;
 
     PathSet printStorePathSet(const StorePathSet & path) const;
 
-    /* Display a set of paths in human-readable form (i.e., between quotes
+    /**
-       and separated by commas). */
+     * Display a set of paths in human-readable form (i.e., between quotes
+     * and separated by commas).
+     */
     std::string showPaths(const StorePathSet & paths);
 
-    /* Return true if ‘path’ is in the Nix store (but not the Nix
+    /**
-       store itself). */
+     * @return true if ‘path’ is in the Nix store (but not the Nix
+     * store itself).
+     */
     bool isInStore(PathView path) const;
 
-    /* Return true if ‘path’ is a store path, i.e. a direct child of
+    /**
-       the Nix store. */
+     * @return true if ‘path’ is a store path, i.e. a direct child of the
+     * Nix store.
+     */
     bool isStorePath(std::string_view path) const;
 
-    /* Split a path like /nix/store/<hash>-<name>/<bla> into
+    /**
-       /nix/store/<hash>-<name> and /<bla>. */
+     * Split a path like /nix/store/<hash>-<name>/<bla> into
+     * /nix/store/<hash>-<name> and /<bla>.
+     */
     std::pair<StorePath, Path> toStorePath(PathView path) const;
 
-    /* Follow symlinks until we end up with a path in the Nix store. */
+    /**
+     * Follow symlinks until we end up with a path in the Nix store.
+     */
     Path followLinksToStore(std::string_view path) const;
 
-    /* Same as followLinksToStore(), but apply toStorePath() to the
+    /**
-       result. */
+     * Same as followLinksToStore(), but apply toStorePath() to the
+     * result.
+     */
     StorePath followLinksToStorePath(std::string_view path) const;
 
-    /* Constructs a unique store path name. */
+    /**
+     * Constructs a unique store path name.
+     */
     StorePath makeStorePath(std::string_view type,
         std::string_view hash, std::string_view name) const;
     StorePath makeStorePath(std::string_view type,
@@ -246,33 +278,40 @@ public:
         const StorePathSet & references = {},
         bool hasSelfReference = false) const;
 
-    /* This is the preparatory part of addToStore(); it computes the
+    /**
-       store path to which srcPath is to be copied.  Returns the store
+     * Preparatory part of addToStore().
-       path and the cryptographic hash of the contents of srcPath. */
+     *
+     * @return the store path to which srcPath is to be copied
+     * and the cryptographic hash of the contents of srcPath.
+     */
     std::pair<StorePath, Hash> computeStorePathForPath(std::string_view name,
         const Path & srcPath, FileIngestionMethod method = FileIngestionMethod::Recursive,
         HashType hashAlgo = htSHA256, PathFilter & filter = defaultPathFilter) const;
 
-    /* Preparatory part of addTextToStore().
+    /**
-
+     * Preparatory part of addTextToStore().
-       !!! Computation of the path should take the references given to
+     *
-       addTextToStore() into account, otherwise we have a (relatively
+     * !!! Computation of the path should take the references given to
-       minor) security hole: a caller can register a source file with
+     * addTextToStore() into account, otherwise we have a (relatively
-       bogus references.  If there are too many references, the path may
+     * minor) security hole: a caller can register a source file with
-       not be garbage collected when it has to be (not really a problem,
+     * bogus references.  If there are too many references, the path may
-       the caller could create a root anyway), or it may be garbage
+     * not be garbage collected when it has to be (not really a problem,
-       collected when it shouldn't be (more serious).
+     * the caller could create a root anyway), or it may be garbage
-
+     * collected when it shouldn't be (more serious).
-       Hashing the references would solve this (bogus references would
+     *
-       simply yield a different store path, so other users wouldn't be
+     * Hashing the references would solve this (bogus references would
-       affected), but it has some backwards compatibility issues (the
+     * simply yield a different store path, so other users wouldn't be
-       hashing scheme changes), so I'm not doing that for now. */
+     * affected), but it has some backwards compatibility issues (the
+     * hashing scheme changes), so I'm not doing that for now.
+     */
     StorePath computeStorePathForText(
         std::string_view name,
         std::string_view s,
         const StorePathSet & references) const;
 
-    /* Check whether a path is valid. */
+    /**
+     * Check whether a path is valid.
+     */
     bool isValidPath(const StorePath & path);
 
 protected:
@@ -281,53 +320,68 @@ protected:
 
 public:
 
-    /* If requested, substitute missing paths. This
+    /**
-       implements nix-copy-closure's --use-substitutes
+     * If requested, substitute missing paths. This
-       flag. */
+     * implements nix-copy-closure's --use-substitutes
+     * flag.
+     */
     void substitutePaths(const StorePathSet & paths);
 
-    /* Query which of the given paths is valid. Optionally, try to
+    /**
-       substitute missing paths. */
+     * Query which of the given paths is valid. Optionally, try to
+     * substitute missing paths.
+     */
     virtual StorePathSet queryValidPaths(const StorePathSet & paths,
         SubstituteFlag maybeSubstitute = NoSubstitute);
 
-    /* Query the set of all valid paths. Note that for some store
+    /**
-       backends, the name part of store paths may be replaced by 'x'
+     * Query the set of all valid paths. Note that for some store
-       (i.e. you'll get /nix/store/<hash>-x rather than
+     * backends, the name part of store paths may be replaced by 'x'
-       /nix/store/<hash>-<name>). Use queryPathInfo() to obtain the
+     * (i.e. you'll get /nix/store/<hash>-x rather than
-       full store path. FIXME: should return a set of
+     * /nix/store/<hash>-<name>). Use queryPathInfo() to obtain the
-       std::variant<StorePath, HashPart> to get rid of this hack. */
+     * full store path. FIXME: should return a set of
+     * std::variant<StorePath, HashPart> to get rid of this hack.
+     */
     virtual StorePathSet queryAllValidPaths()
     { unsupported("queryAllValidPaths"); }
 
     constexpr static const char * MissingName = "x";
 
-    /* Query information about a valid path. It is permitted to omit
+    /**
-       the name part of the store path. */
+     * Query information about a valid path. It is permitted to omit
+     * the name part of the store path.
+     */
     ref<const ValidPathInfo> queryPathInfo(const StorePath & path);
 
-    /* Asynchronous version of queryPathInfo(). */
+    /**
+     * Asynchronous version of queryPathInfo().
+     */
     void queryPathInfo(const StorePath & path,
         Callback<ref<const ValidPathInfo>> callback) noexcept;
 
-    /* Query the information about a realisation. */
+    /**
+     * Query the information about a realisation.
+     */
     std::shared_ptr<const Realisation> queryRealisation(const DrvOutput &);
 
-    /* Asynchronous version of queryRealisation(). */
+    /**
+     * Asynchronous version of queryRealisation().
+     */
     void queryRealisation(const DrvOutput &,
         Callback<std::shared_ptr<const Realisation>> callback) noexcept;
 
 
-    /* Check whether the given valid path info is sufficiently attested, by
+    /**
-       either being signed by a trusted public key or content-addressed, in
+     * Check whether the given valid path info is sufficiently attested, by
-       order to be included in the given store.
+     * either being signed by a trusted public key or content-addressed, in
-
+     * order to be included in the given store.
-       These same checks would be performed in addToStore, but this allows an
+     *
-       earlier failure in the case where dependencies need to be added too, but
+     * These same checks would be performed in addToStore, but this allows an
-       the addToStore wouldn't fail until those dependencies are added. Also,
+     * earlier failure in the case where dependencies need to be added too, but
-       we don't really want to add the dependencies listed in a nar info we
+     * the addToStore wouldn't fail until those dependencies are added. Also,
-       don't trust anyyways.
+     * we don't really want to add the dependencies listed in a nar info we
-       */
+     * don't trust anyyways.
+     */
     virtual bool pathInfoIsUntrusted(const ValidPathInfo &)
     {
         return true;
@@ -347,53 +401,77 @@ protected:
 
 public:
 
-    /* Queries the set of incoming FS references for a store path.
+    /**
-       The result is not cleared. */
+     * Queries the set of incoming FS references for a store path.
+     * The result is not cleared.
+     */
     virtual void queryReferrers(const StorePath & path, StorePathSet & referrers)
     { unsupported("queryReferrers"); }
 
-    /* Return all currently valid derivations that have `path' as an
+    /**
-       output.  (Note that the result of `queryDeriver()' is the
+     * @return all currently valid derivations that have `path' as an
-       derivation that was actually used to produce `path', which may
+     * output.
-       not exist anymore.) */
+     *
+     * (Note that the result of `queryDeriver()' is the derivation that
+     * 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);
 
-    /* Query the mapping outputName => outputPath for the given derivation. All
+    /**
-       outputs are mentioned so ones mising the mapping are mapped to
+     * Query the mapping outputName => outputPath for the given
-       `std::nullopt`.  */
+     * derivation. All outputs are mentioned so ones mising the mapping
+     * are mapped to `std::nullopt`.
+     */
     virtual std::map<std::string, std::optional<StorePath>> queryPartialDerivationOutputMap(const StorePath & path);
 
-    /* Query the mapping outputName=>outputPath for the given derivation.
+    /**
-       Assume every output has a mapping and throw an exception otherwise. */
+     * Query the mapping outputName=>outputPath for the given derivation.
+     * Assume every output has a mapping and throw an exception otherwise.
+     */
     OutputPathMap queryDerivationOutputMap(const StorePath & path);
 
-    /* Query the full store path given the hash part of a valid store
+    /**
-       path, or empty if the path doesn't exist. */
+     * Query the full store path given the hash part of a valid store
+     * path, or empty if the path doesn't exist.
+     */
     virtual std::optional<StorePath> queryPathFromHashPart(const std::string & hashPart) = 0;
 
-    /* Query which of the given paths have substitutes. */
+    /**
+     * Query which of the given paths have substitutes.
+     */
     virtual StorePathSet querySubstitutablePaths(const StorePathSet & paths) { return {}; };
 
-    /* Query substitute info (i.e. references, derivers and download
+    /**
-       sizes) of a map of paths to their optional ca values. The info
+     * Query substitute info (i.e. references, derivers and download
-       of the first succeeding substituter for each path will be
+     * sizes) of a map of paths to their optional ca values. The info of
-       returned. If a path does not have substitute info, it's omitted
+     * the first succeeding substituter for each path will be returned.
-       from the resulting ‘infos’ map. */
+     * If a path does not have substitute info, it's omitted from the
+     * resulting ‘infos’ map.
+     */
     virtual void querySubstitutablePathInfos(const StorePathCAMap & paths,
         SubstitutablePathInfos & infos) { return; };
 
-    /* Import a path into the store. */
+    /**
+     * Import a path into the store.
+     */
     virtual void addToStore(const ValidPathInfo & info, Source & narSource,
         RepairFlag repair = NoRepair, CheckSigsFlag checkSigs = CheckSigs) = 0;
 
-    // A list of paths infos along with a source providing the content of the
+    /**
-    // associated store path
+     * A list of paths infos along with a source providing the content
+     * of the associated store path
+     */
     using PathsSource = std::vector<std::pair<ValidPathInfo, std::unique_ptr<Source>>>;
 
-    /* Import multiple paths into the store. */
+    /**
+     * Import multiple paths into the store.
+     */
     virtual void addMultipleToStore(
         Source & source,
         RepairFlag repair = NoRepair,
@@ -405,10 +483,14 @@ public:
         RepairFlag repair = NoRepair,
         CheckSigsFlag checkSigs = CheckSigs);
 
-    /* Copy the contents of a path to the store and register the
+    /**
-       validity the resulting path.  The resulting path is returned.
+     * Copy the contents of a path to the store and register the
-       The function object `filter' can be used to exclude files (see
+     * validity the resulting path.
-       libutil/archive.hh). */
+     *
+     * @return The resulting path is returned.
+     * @param filter This function can be used to exclude files (see
+     * libutil/archive.hh).
+     */
     virtual StorePath addToStore(
         std::string_view name,
         const Path & srcPath,
@@ -418,26 +500,33 @@ public:
         RepairFlag repair = NoRepair,
         const StorePathSet & references = StorePathSet());
 
-    /* Copy the contents of a path to the store and register the
+    /**
-       validity the resulting path, using a constant amount of
+     * Copy the contents of a path to the store and register the
-       memory. */
+     * validity the resulting path, using a constant amount of
+     * memory.
+     */
     ValidPathInfo addToStoreSlow(std::string_view name, const Path & srcPath,
         FileIngestionMethod method = FileIngestionMethod::Recursive, HashType hashAlgo = htSHA256,
         std::optional<Hash> expectedCAHash = {});
 
-    /* Like addToStore(), but the contents of the path are contained
+    /**
-       in `dump', which is either a NAR serialisation (if recursive ==
+     * Like addToStore(), but the contents of the path are contained
-       true) or simply the contents of a regular file (if recursive ==
+     * in `dump', which is either a NAR serialisation (if recursive ==
-       false).
+     * true) or simply the contents of a regular file (if recursive ==
-       `dump` may be drained */
+     * false).
-    // FIXME: remove?
+     * `dump` may be drained
+     *
+     * \todo remove?
+     */
     virtual StorePath addToStoreFromDump(Source & dump, std::string_view name,
         FileIngestionMethod method = FileIngestionMethod::Recursive, HashType hashAlgo = htSHA256, RepairFlag repair = NoRepair,
         const StorePathSet & references = StorePathSet())
     { unsupported("addToStoreFromDump"); }
 
-    /* Like addToStore, but the contents written to the output path is
+    /**
-       a regular file containing the given string. */
+     * Like addToStore, but the contents written to the output path is a
+     * regular file containing the given string.
+     */
     virtual StorePath addTextToStore(
         std::string_view name,
         std::string_view s,
@@ -458,140 +547,180 @@ public:
     virtual void registerDrvOutput(const Realisation & output, CheckSigsFlag checkSigs)
     { return registerDrvOutput(output); }
 
-    /* Write a NAR dump of a store path. */
+    /**
+     * Write a NAR dump of a store path.
+     */
     virtual void narFromPath(const StorePath & path, Sink & sink) = 0;
 
-    /* For each path, if it's a derivation, build it.  Building a
+    /**
-       derivation means ensuring that the output paths are valid.  If
+     * For each path, if it's a derivation, build it.  Building a
-       they are already valid, this is a no-op.  Otherwise, validity
+     * derivation means ensuring that the output paths are valid.  If
-       can be reached in two ways.  First, if the output paths is
+     * they are already valid, this is a no-op.  Otherwise, validity
-       substitutable, then build the path that way.  Second, the
+     * can be reached in two ways.  First, if the output paths is
-       output paths can be created by running the builder, after
+     * substitutable, then build the path that way.  Second, the
-       recursively building any sub-derivations. For inputs that are
+     * output paths can be created by running the builder, after
-       not derivations, substitute them. */
+     * recursively building any sub-derivations. For inputs that are
+     * not derivations, substitute them.
+     */
     virtual void buildPaths(
         const std::vector<DerivedPath> & paths,
         BuildMode buildMode = bmNormal,
         std::shared_ptr<Store> evalStore = nullptr);
 
-    /* Like `buildPaths()`, but return a vector of `BuildResult`s
+    /**
-       corresponding to each element in `paths`. Note that in case of
+     * Like buildPaths(), but return a vector of \ref BuildResult
-       a build/substitution error, this function won't throw an
+     * BuildResults corresponding to each element in paths. Note that in
-       exception, but return a `BuildResult` containing an error
+     * case of a build/substitution error, this function won't throw an
-       message. */
+     * exception, but return a BuildResult containing an error message.
+     */
     virtual std::vector<BuildResult> buildPathsWithResults(
         const std::vector<DerivedPath> & paths,
         BuildMode buildMode = bmNormal,
         std::shared_ptr<Store> evalStore = nullptr);
 
-    /* Build a single non-materialized derivation (i.e. not from an
+    /**
-       on-disk .drv file).
+     * Build a single non-materialized derivation (i.e. not from an
-
+     * on-disk .drv file).
-       ‘drvPath’ is used to deduplicate worker goals so it is imperative that
+     *
-       is correct. That said, it doesn't literally need to be store path that
+     * @param drvPath This is used to deduplicate worker goals so it is
-       would be calculated from writing this derivation to the store: it is OK
+     * imperative that is correct. That said, it doesn't literally need
-       if it instead is that of a Derivation which would resolve to this (by
+     * to be store path that would be calculated from writing this
-       taking the outputs of it's input derivations and adding them as input
+     * derivation to the store: it is OK if it instead is that of a
-       sources) such that the build time referenceable-paths are the same.
+     * Derivation which would resolve to this (by taking the outputs of
-
+     * it's input derivations and adding them as input sources) such
-       In the input-addressed case, we usually *do* use an "original"
+     * that the build time referenceable-paths are the same.
-       unresolved derivations's path, as that is what will be used in the
+     *
-       `buildPaths` case. Also, the input-addressed output paths are verified
+     * In the input-addressed case, we usually *do* use an "original"
-       only by that contents of that specific unresolved derivation, so it is
+     * unresolved derivations's path, as that is what will be used in the
-       nice to keep that information around so if the original derivation is
+     * buildPaths case. Also, the input-addressed output paths are verified
-       ever obtained later, it can be verified whether the trusted user in fact
+     * only by that contents of that specific unresolved derivation, so it is
-       used the proper output path.
+     * nice to keep that information around so if the original derivation is
-
+     * ever obtained later, it can be verified whether the trusted user in fact
-       In the content-addressed case, we want to always use the
+     * used the proper output path.
-       resolved drv path calculated from the provided derivation. This serves
+     *
-       two purposes:
+     * In the content-addressed case, we want to always use the resolved
-
+     * drv path calculated from the provided derivation. This serves two
-         - It keeps the operation trustless, by ruling out a maliciously
+     * purposes:
-           invalid drv path corresponding to a non-resolution-equivalent
+     *
-           derivation.
+     *   - It keeps the operation trustless, by ruling out a maliciously
-
+     *     invalid drv path corresponding to a non-resolution-equivalent
-         - For the floating case in particular, it ensures that the derivation
+     *     derivation.
-           to output mapping respects the resolution equivalence relation, so
+     *
-           one cannot choose different resolution-equivalent derivations to
+     *   - For the floating case in particular, it ensures that the derivation
-           subvert dependency coherence (i.e. the property that one doesn't end
+     *     to output mapping respects the resolution equivalence relation, so
-           up with multiple different versions of dependencies without
+     *     one cannot choose different resolution-equivalent derivations to
-           explicitly choosing to allow it).
+     *     subvert dependency coherence (i.e. the property that one doesn't end
-    */
+     *     up with multiple different versions of dependencies without
+     *     explicitly choosing to allow it).
+     */
     virtual BuildResult buildDerivation(const StorePath & drvPath, const BasicDerivation & drv,
         BuildMode buildMode = bmNormal);
 
-    /* Ensure that a path is valid.  If it is not currently valid, it
+    /**
-       may be made valid by running a substitute (if defined for the
+     * Ensure that a path is valid.  If it is not currently valid, it
-       path). */
+     * may be made valid by running a substitute (if defined for the
+     * path).
+     */
     virtual void ensurePath(const StorePath & path);
 
-    /* Add a store path as a temporary root of the garbage collector.
+    /**
-       The root disappears as soon as we exit. */
+     * Add a store path as a temporary root of the garbage collector.
+     * The root disappears as soon as we exit.
+     */
     virtual void addTempRoot(const StorePath & path)
     { debug("not creating temporary root, store doesn't support GC"); }
 
-    /* Return a string representing information about the path that
+    /**
-       can be loaded into the database using `nix-store --load-db' or
+     * @return a string representing information about the path that
-       `nix-store --register-validity'. */
+     * can be loaded into the database using `nix-store --load-db' or
+     * `nix-store --register-validity'.
+     */
     std::string makeValidityRegistration(const StorePathSet & paths,
         bool showDerivers, bool showHash);
 
-    /* Write a JSON representation of store path metadata, such as the
+    /**
-       hash and the references. If ‘includeImpureInfo’ is true,
+     * Write a JSON representation of store path metadata, such as the
-       variable elements such as the registration time are
+     * hash and the references.
-       included. If ‘showClosureSize’ is true, the closure size of
+     *
-       each path is included. */
+     * @param includeImpureInfo If true, variable elements such as the
+     * registration time are included.
+     *
+     * @param showClosureSize If true, the closure size of each path is
+     * included.
+     */
     nlohmann::json pathInfoToJSON(const StorePathSet & storePaths,
         bool includeImpureInfo, bool showClosureSize,
         Base hashBase = Base32,
         AllowInvalidFlag allowInvalid = DisallowInvalid);
 
-    /* Return the size of the closure of the specified path, that is,
+    /**
-       the sum of the size of the NAR serialisation of each path in
+     * @return the size of the closure of the specified path, that is,
-       the closure. */
+     * the sum of the size of the NAR serialisation of each path in the
+     * closure.
+     */
     std::pair<uint64_t, uint64_t> getClosureSize(const StorePath & storePath);
 
-    /* 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.
+     */
     virtual void optimiseStore() { };
 
-    /* Check the integrity of the Nix store.  Returns true if errors
+    /**
-       remain. */
+     * Check the integrity of the Nix store.
+     *
+     * @return true if errors remain.
+     */
     virtual bool verifyStore(bool checkContents, RepairFlag repair = NoRepair) { return false; };
 
-    /* Return an object to access files in the Nix store. */
+    /**
+     * @return An object to access files in the Nix store.
+     */
     virtual ref<FSAccessor> getFSAccessor()
     { unsupported("getFSAccessor"); }
 
-    /* Repair the contents of the given path by redownloading it using
+    /**
-       a substituter (if available). */
+     * Repair the contents of the given path by redownloading it using
+     * a substituter (if available).
+     */
     virtual void repairPath(const StorePath & path)
     { unsupported("repairPath"); }
 
-    /* Add signatures to the specified store path. The signatures are
+    /**
-       not verified. */
+     * Add signatures to the specified store path. The signatures are
+     * not verified.
+     */
     virtual void addSignatures(const StorePath & storePath, const StringSet & sigs)
     { unsupported("addSignatures"); }
 
     /* Utility functions. */
 
-    /* Read a derivation, after ensuring its existence through
+    /**
-       ensurePath(). */
+     * Read a derivation, after ensuring its existence through
+     * ensurePath().
+     */
     Derivation derivationFromPath(const StorePath & drvPath);
 
-    /* Read a derivation (which must already be valid). */
+    /**
+     * Read a derivation (which must already be valid).
+     */
     Derivation readDerivation(const StorePath & drvPath);
 
-    /* Read a derivation from a potentially invalid path. */
+    /**
+     * Read a derivation from a potentially invalid path.
+     */
     Derivation readInvalidDerivation(const StorePath & drvPath);
 
-    /* Place in `out' the set of all store paths in the file system
+    /**
-       closure of `storePath'; that is, all paths than can be directly
+     * @param [out] out Place in here the set of all store paths in the
-       or indirectly reached from it.  `out' is not cleared.  If
+     * file system closure of `storePath'; that is, all paths than can
-       `flipDirection' is true, the set of paths that can reach
+     * be directly or indirectly reached from it. `out' is not cleared.
-       `storePath' is returned; that is, the closures under the
+     *
-       `referrers' relation instead of the `references' relation is
+     * @param flipDirection If true, the set of paths that can reach
-       returned. */
+     * `storePath' is returned; that is, the closures under the
+     * `referrers' relation instead of the `references' relation is
+     * returned.
+     */
     virtual void computeFSClosure(const StorePathSet & paths,
         StorePathSet & out, bool flipDirection = false,
         bool includeOutputs = false, bool includeDerivers = false);
@@ -600,27 +729,34 @@ public:
         StorePathSet & out, bool flipDirection = false,
         bool includeOutputs = false, bool includeDerivers = false);
 
-    /* Given a set of paths that are to be built, return the set of
+    /**
-       derivations that will be built, and the set of output paths
+     * Given a set of paths that are to be built, return the set of
-       that will be substituted. */
+     * derivations that will be built, and the set of output paths that
+     * will be substituted.
+     */
     virtual void queryMissing(const std::vector<DerivedPath> & targets,
         StorePathSet & willBuild, StorePathSet & willSubstitute, StorePathSet & unknown,
         uint64_t & downloadSize, uint64_t & narSize);
 
-    /* Sort a set of paths topologically under the references
+    /**
-       relation.  If p refers to q, then p precedes q in this list. */
+     * Sort a set of paths topologically under the references
+     * relation.  If p refers to q, then p precedes q in this list.
+     */
     StorePaths topoSortPaths(const StorePathSet & paths);
 
-    /* Export multiple paths in the format expected by ‘nix-store
+    /**
-       --import’. */
+     * Export multiple paths in the format expected by ‘nix-store
+     * --import’.
+     */
     void exportPaths(const StorePathSet & paths, Sink & sink);
 
     void exportPath(const StorePath & path, Sink & sink);
 
-    /* Import a sequence of NAR dumps created by exportPaths() into
+    /**
-       the Nix store. Optionally, the contents of the NARs are
+     * Import a sequence of NAR dumps created by exportPaths() into the
-       preloaded into the specified FS accessor to speed up subsequent
+     * Nix store. Optionally, the contents of the NARs are preloaded
-       access. */
+     * into the specified FS accessor to speed up subsequent access.
+     */
     StorePaths importPaths(Source & source, CheckSigsFlag checkSigs = CheckSigs);
 
     struct Stats
@@ -642,8 +778,9 @@ public:
 
     const Stats & getStats();
 
-    /* Computes the full closure of of a set of store-paths for e.g.
+    /**
-       derivations that need this information for `exportReferencesGraph`.
+     * Computes the full closure of of a set of store-paths for e.g.
+     * derivations that need this information for `exportReferencesGraph`.
      */
     StorePathSet exportReferences(const StorePathSet & storePaths, const StorePathSet & inputPaths);
 
@@ -654,18 +791,24 @@ public:
      */
     std::optional<StorePath> getBuildDerivationPath(const StorePath &);
 
-    /* Hack to allow long-running processes like hydra-queue-runner to
+    /**
-       occasionally flush their path info cache. */
+     * Hack to allow long-running processes like hydra-queue-runner to
+     * occasionally flush their path info cache.
+     */
     void clearPathInfoCache()
     {
         state.lock()->pathInfoCache.clear();
     }
 
-    /* Establish a connection to the store, for store types that have
+    /**
-       a notion of connection. Otherwise this is a no-op. */
+     * Establish a connection to the store, for store types that have
+     * a notion of connection. Otherwise this is a no-op.
+     */
     virtual void connect() { };
 
-    /* Get the protocol version of this store or it's connection. */
+    /**
+     * Get the protocol version of this store or it's connection.
+     */
     virtual unsigned int getProtocol()
     {
         return 0;
@@ -681,7 +824,7 @@ public:
         return toRealPath(printStorePath(storePath));
     }
 
-    /*
+    /**
      * Synchronises the options of the client with those of the daemon
      * (a no-op when there’s no daemon)
      */
@@ -693,7 +836,13 @@ protected:
 
     Stats stats;
 
-    /* Unsupported methods. */
+    /**
+     * Helper for methods that are not unsupported: this is used for
+     * default definitions for virtual methods that are meant to be overriden.
+     *
+     * \todo Using this should be a last resort. It is better to make
+     * the method "virtual pure" and/or move it to a subclass.
+     */
     [[noreturn]] void unsupported(const std::string & op)
     {
         throw Unsupported("operation '%s' is not supported by store '%s'", op, getUri());
@@ -702,7 +851,9 @@ protected:
 };
 
 
-/* Copy a path from one store to another. */
+/**
+ * Copy a path from one store to another.
+ */
 void copyStorePath(
     Store & srcStore,
     Store & dstStore,
@@ -711,12 +862,14 @@ void copyStorePath(
     CheckSigsFlag checkSigs = CheckSigs);
 
 
-/* Copy store paths from one store to another. The paths may be copied
+/**
-   in parallel. They are copied in a topologically sorted order (i.e.
+ * Copy store paths from one store to another. The paths may be copied
-   if A is a reference of B, then A is copied before B), but the set
+ * in parallel. They are copied in a topologically sorted order (i.e. if
-   of store paths is not automatically closed; use copyClosure() for
+ * A is a reference of B, then A is copied before B), but the set of
-   that. Returns a map of what each path was copied to the dstStore
+ * store paths is not automatically closed; use copyClosure() for that.
-   as. */
+ *
+ * @return a map of what each path was copied to the dstStore as.
+ */
 std::map<StorePath, StorePath> copyPaths(
     Store & srcStore, Store & dstStore,
     const RealisedPath::Set &,
@@ -731,7 +884,9 @@ std::map<StorePath, StorePath> copyPaths(
     CheckSigsFlag checkSigs = CheckSigs,
     SubstituteFlag substitute = NoSubstitute);
 
-/* Copy the closure of `paths` from `srcStore` to `dstStore`. */
+/**
+ * Copy the closure of `paths` from `srcStore` to `dstStore`.
+ */
 void copyClosure(
     Store & srcStore, Store & dstStore,
     const RealisedPath::Set & paths,
@@ -746,52 +901,61 @@ void copyClosure(
     CheckSigsFlag checkSigs = CheckSigs,
     SubstituteFlag substitute = NoSubstitute);
 
-/* Remove the temporary roots file for this process.  Any temporary
+/**
-   root becomes garbage after this point unless it has been registered
+ * Remove the temporary roots file for this process.  Any temporary
-   as a (permanent) root. */
+ * root becomes garbage after this point unless it has been registered
+ * as a (permanent) root.
+ */
 void removeTempRoots();
 
 
-/* Resolve the derived path completely, failing if any derivation output
+/**
-   is unknown. */
+ * Resolve the derived path completely, failing if any derivation output
+ * is unknown.
+ */
 OutputPathMap resolveDerivedPath(Store &, const DerivedPath::Built &, Store * evalStore = nullptr);
 
 
-/* Return a Store object to access the Nix store denoted by
+/**
-   ‘uri’ (slight misnomer...). Supported values are:
+ * @return a Store object to access the Nix store denoted by
-
+ * ‘uri’ (slight misnomer...).
-   * ‘local’: The Nix store in /nix/store and database in
+ *
-     /nix/var/nix/db, accessed directly.
+ * @param uri Supported values are:
-
+ *
-   * ‘daemon’: The Nix store accessed via a Unix domain socket
+ * - ‘local’: The Nix store in /nix/store and database in
-     connection to nix-daemon.
+ *   /nix/var/nix/db, accessed directly.
-
+ *
-   * ‘unix://<path>’: The Nix store accessed via a Unix domain socket
+ * - ‘daemon’: The Nix store accessed via a Unix domain socket
-     connection to nix-daemon, with the socket located at <path>.
+ *   connection to nix-daemon.
-
+ *
-   * ‘auto’ or ‘’: Equivalent to ‘local’ or ‘daemon’ depending on
+ * - ‘unix://<path>’: The Nix store accessed via a Unix domain socket
-     whether the user has write access to the local Nix
+ *   connection to nix-daemon, with the socket located at <path>.
-     store/database.
+ *
-
+ * - ‘auto’ or ‘’: Equivalent to ‘local’ or ‘daemon’ depending on
-   * ‘file://<path>’: A binary cache stored in <path>.
+ *   whether the user has write access to the local Nix
-
+ *   store/database.
-   * ‘https://<path>’: A binary cache accessed via HTTP.
+ *
-
+ * - ‘file://<path>’: A binary cache stored in <path>.
-   * ‘s3://<path>’: A writable binary cache stored on Amazon's Simple
+ *
-     Storage Service.
+ * - ‘https://<path>’: A binary cache accessed via HTTP.
-
+ *
-   * ‘ssh://[user@]<host>’: A remote Nix store accessed by running
+ * - ‘s3://<path>’: A writable binary cache stored on Amazon's Simple
-     ‘nix-store --serve’ via SSH.
+ *   Storage Service.
-
+ *
-   You can pass parameters to the store implementation by appending
+ * - ‘ssh://[user@]<host>’: A remote Nix store accessed by running
-   ‘?key=value&key=value&...’ to the URI.
+ *   ‘nix-store --serve’ via SSH.
-*/
+ *
+ * You can pass parameters to the store implementation by appending
+ * ‘?key=value&key=value&...’ to the URI.
+ */
 ref<Store> openStore(const std::string & uri = settings.storeUri.get(),
     const Store::Params & extraParams = Store::Params());
 
 
-/* Return the default substituter stores, defined by the
+/**
-   ‘substituters’ option and various legacy options. */
+ * @return the default substituter stores, defined by the
+ * ‘substituters’ option and various legacy options.
+ */
 std::list<ref<Store>> getDefaultSubstituters();
 
 struct StoreFactory
@@ -834,8 +998,10 @@ struct RegisterStoreImplementation
 };
 
 
-/* Display a set of paths in human-readable form (i.e., between quotes
+/**
-   and separated by commas). */
+ * Display a set of paths in human-readable form (i.e., between quotes
+ * and separated by commas).
+ */
 std::string showPaths(const PathSet & paths);
 
 
@@ -844,7 +1010,9 @@ std::optional<ValidPathInfo> decodeValidPathInfo(
     std::istream & str,
     std::optional<HashResult> hashGiven = std::nullopt);
 
-/* Split URI into protocol+hierarchy part and its parameter set. */
+/**
+ * Split URI into protocol+hierarchy part and its parameter set.
+ */
 std::pair<std::string, Store::Params> splitUriAndParams(const std::string & uri);
 
 std::optional<ContentAddress> getDerivationCA(const BasicDerivation & drv);