Merge remote-tracking branch 'upstream/master' into list-experimental-features

156 files changed, 1837 insertions, 837 deletions

diff --git a/src/libcmd/command-installable-value.hh b/src/libcmd/command-installable-value.hh
index 8e31a0b92..7880d4119 100644
--- a/src/libcmd/command-installable-value.hh
+++ b/src/libcmd/command-installable-value.hh
@@ -1,10 +1,20 @@
+#pragma once
+///@file
+
 #include "installable-value.hh"
 #include "command.hh"
 
 namespace nix {
 
+/**
+ * An InstallableCommand where the single positional argument must be an
+ * InstallableValue in particular.
+ */
 struct InstallableValueCommand : InstallableCommand
 {
+    /**
+     * Entry point to this command
+     */
     virtual void run(ref<Store> store, ref<InstallableValue> installable) = 0;
 
     void run(ref<Store> store, ref<Installable> installable) override;
diff --git a/src/libcmd/command.hh b/src/libcmd/command.hh
index dbc155b79..96236b987 100644
--- a/src/libcmd/command.hh
+++ b/src/libcmd/command.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "installable-value.hh"
 #include "args.hh"
diff --git a/src/libcmd/common-eval-args.hh b/src/libcmd/common-eval-args.hh
index 1ec800613..b69db11dd 100644
--- a/src/libcmd/common-eval-args.hh
+++ b/src/libcmd/common-eval-args.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "args.hh"
 
diff --git a/src/libcmd/editor-for.hh b/src/libcmd/editor-for.hh
index 8fbd08792..f752bd849 100644
--- a/src/libcmd/editor-for.hh
+++ b/src/libcmd/editor-for.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "types.hh"
 
diff --git a/src/libcmd/installable-attr-path.hh b/src/libcmd/installable-attr-path.hh
index c06132ec8..e9f0c33da 100644
--- a/src/libcmd/installable-attr-path.hh
+++ b/src/libcmd/installable-attr-path.hh
@@ -1,3 +1,6 @@
+#pragma once
+///@file
+
 #include "globals.hh"
 #include "installable-value.hh"
 #include "outputs-spec.hh"
diff --git a/src/libcmd/installable-derived-path.hh b/src/libcmd/installable-derived-path.hh
index 042878b91..e0b4f18b3 100644
--- a/src/libcmd/installable-derived-path.hh
+++ b/src/libcmd/installable-derived-path.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "installables.hh"
 
diff --git a/src/libcmd/installable-flake.hh b/src/libcmd/installable-flake.hh
index 313d2d7a3..afe64d977 100644
--- a/src/libcmd/installable-flake.hh
+++ b/src/libcmd/installable-flake.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "installable-value.hh"
 
diff --git a/src/libcmd/installable-value.hh b/src/libcmd/installable-value.hh
index 9e076cb10..bfb3bfeed 100644
--- a/src/libcmd/installable-value.hh
+++ b/src/libcmd/installable-value.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "installables.hh"
 #include "flake/flake.hh"
diff --git a/src/libcmd/installables.hh b/src/libcmd/installables.hh
index b6efc0f17..42d6c7c7c 100644
--- a/src/libcmd/installables.hh
+++ b/src/libcmd/installables.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "util.hh"
 #include "path.hh"
diff --git a/src/libcmd/legacy.hh b/src/libcmd/legacy.hh
index f503b0da3..357500a4d 100644
--- a/src/libcmd/legacy.hh
+++ b/src/libcmd/legacy.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <functional>
 #include <map>
diff --git a/src/libcmd/markdown.hh b/src/libcmd/markdown.hh
index 78320fcf5..a04d32a4f 100644
--- a/src/libcmd/markdown.hh
+++ b/src/libcmd/markdown.hh
@@ -1,3 +1,6 @@
+#pragma once
+///@file
+
 #include "types.hh"
 
 namespace nix {
diff --git a/src/libcmd/repl.hh b/src/libcmd/repl.hh
index dfccc93e7..731c8e6db 100644
--- a/src/libcmd/repl.hh
+++ b/src/libcmd/repl.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "eval.hh"
 
diff --git a/src/libexpr/attr-path.hh b/src/libexpr/attr-path.hh
index 117e0051b..d0d05b1a1 100644
--- a/src/libexpr/attr-path.hh
+++ b/src/libexpr/attr-path.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "eval.hh"
 
diff --git a/src/libexpr/attr-set.hh b/src/libexpr/attr-set.hh
index dcc73b506..3fe54408b 100644
--- a/src/libexpr/attr-set.hh
+++ b/src/libexpr/attr-set.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "nixexpr.hh"
 #include "symbol-table.hh"
diff --git a/src/libexpr/eval-cache.hh b/src/libexpr/eval-cache.hh
index c93e55b93..c90882edc 100644
--- a/src/libexpr/eval-cache.hh
+++ b/src/libexpr/eval-cache.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "sync.hh"
 #include "hash.hh"
diff --git a/src/libexpr/eval-inline.hh b/src/libexpr/eval-inline.hh
index f0da688db..f8ddd2acc 100644
--- a/src/libexpr/eval-inline.hh
+++ b/src/libexpr/eval-inline.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "eval.hh"
 
diff --git a/src/libexpr/eval.hh b/src/libexpr/eval.hh
index e4d5906bd..a1b54951e 100644
--- a/src/libexpr/eval.hh
+++ b/src/libexpr/eval.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "attr-set.hh"
 #include "types.hh"
diff --git a/src/libexpr/flake/flake.hh b/src/libexpr/flake/flake.hh
index 10301d8aa..3cb39d766 100644
--- a/src/libexpr/flake/flake.hh
+++ b/src/libexpr/flake/flake.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "types.hh"
 #include "flakeref.hh"
diff --git a/src/libexpr/flake/flakeref.hh b/src/libexpr/flake/flakeref.hh
index c4142fc20..23d19adb1 100644
--- a/src/libexpr/flake/flakeref.hh
+++ b/src/libexpr/flake/flakeref.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "types.hh"
 #include "hash.hh"
diff --git a/src/libexpr/flake/lockfile.hh b/src/libexpr/flake/lockfile.hh
index 02e9bdfbc..6512509c5 100644
--- a/src/libexpr/flake/lockfile.hh
+++ b/src/libexpr/flake/lockfile.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "flakeref.hh"
 
diff --git a/src/libexpr/function-trace.hh b/src/libexpr/function-trace.hh
index e9a2526bd..91439b0aa 100644
--- a/src/libexpr/function-trace.hh
+++ b/src/libexpr/function-trace.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "eval.hh"
 
diff --git a/src/libexpr/get-drvs.hh b/src/libexpr/get-drvs.hh
index bbd2d3c47..51ef7782a 100644
--- a/src/libexpr/get-drvs.hh
+++ b/src/libexpr/get-drvs.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "eval.hh"
 #include "path.hh"
diff --git a/src/libexpr/json-to-value.hh b/src/libexpr/json-to-value.hh
index 84bec4eba..3b8ec000f 100644
--- a/src/libexpr/json-to-value.hh
+++ b/src/libexpr/json-to-value.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "eval.hh"
 
diff --git a/src/libexpr/nixexpr.hh b/src/libexpr/nixexpr.hh
index 4a81eaa47..4079a7b24 100644
--- a/src/libexpr/nixexpr.hh
+++ b/src/libexpr/nixexpr.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <map>
 #include <vector>
diff --git a/src/libexpr/primops.cc b/src/libexpr/primops.cc
index 3641ee468..72faeada8 100644
--- a/src/libexpr/primops.cc
+++ b/src/libexpr/primops.cc
@@ -254,9 +254,16 @@ static RegisterPrimOp primop_import({
     .args = {"path"},
     // TODO turn "normal path values" into link below
     .doc = R"(
-      Load, parse and return the Nix expression in the file *path*. If
-      *path* is a directory, the file ` default.nix ` in that directory
-      is loaded. Evaluation aborts if the file doesn’t exist or contains
+      Load, parse and return the Nix expression in the file *path*.
+
+      The value *path* can be a path, a string, or an attribute set with an
+      `__toString` attribute or a `outPath` attribute (as derivations or flake
+      inputs typically have).
+
+      If *path* is a directory, the file `default.nix` in that directory
+      is loaded.
+
+      Evaluation aborts if the file doesn’t exist or contains
       an incorrect Nix expression. `import` implements Nix’s module
       system: you can put any Nix expression (such as a set or a
       function) in a separate file, and use it from Nix expressions in
diff --git a/src/libexpr/primops.hh b/src/libexpr/primops.hh
index 1cfb4356b..1c5ce219f 100644
--- a/src/libexpr/primops.hh
+++ b/src/libexpr/primops.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "eval.hh"
 
diff --git a/src/libexpr/symbol-table.hh b/src/libexpr/symbol-table.hh
index 288c15602..c97a0a2db 100644
--- a/src/libexpr/symbol-table.hh
+++ b/src/libexpr/symbol-table.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <list>
 #include <map>
diff --git a/src/libexpr/tests/libexpr.hh b/src/libexpr/tests/libexpr.hh
index 8534d9567..69c932f05 100644
--- a/src/libexpr/tests/libexpr.hh
+++ b/src/libexpr/tests/libexpr.hh
@@ -1,3 +1,6 @@
+#pragma once
+///@file
+
 #include <gtest/gtest.h>
 #include <gmock/gmock.h>
 
diff --git a/src/libexpr/tests/value/context.hh b/src/libexpr/tests/value/context.hh
index 54d21760e..c0bc97ba3 100644
--- a/src/libexpr/tests/value/context.hh
+++ b/src/libexpr/tests/value/context.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <rapidcheck/gen/Arbitrary.h>
 
diff --git a/src/libexpr/value-to-json.hh b/src/libexpr/value-to-json.hh
index 22f26b790..713356c7f 100644
--- a/src/libexpr/value-to-json.hh
+++ b/src/libexpr/value-to-json.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "nixexpr.hh"
 #include "eval.hh"
diff --git a/src/libexpr/value-to-xml.hh b/src/libexpr/value-to-xml.hh
index 506f32b6b..ace7ead0f 100644
--- a/src/libexpr/value-to-xml.hh
+++ b/src/libexpr/value-to-xml.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "nixexpr.hh"
 #include "eval.hh"
diff --git a/src/libexpr/value.hh b/src/libexpr/value.hh
index 508dbe218..bfae4ee94 100644
--- a/src/libexpr/value.hh
+++ b/src/libexpr/value.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <cassert>
 
diff --git a/src/libexpr/value/context.hh b/src/libexpr/value/context.hh
index 721563cba..d467b4f1d 100644
--- a/src/libexpr/value/context.hh
+++ b/src/libexpr/value/context.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "util.hh"
 #include "comparator.hh"
diff --git a/src/libfetchers/attrs.hh b/src/libfetchers/attrs.hh
index e41037633..1a14bb023 100644
--- a/src/libfetchers/attrs.hh
+++ b/src/libfetchers/attrs.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "types.hh"
 
diff --git a/src/libfetchers/cache.hh b/src/libfetchers/cache.hh
index 3763ee2a6..ae398d040 100644
--- a/src/libfetchers/cache.hh
+++ b/src/libfetchers/cache.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "fetchers.hh"
 
diff --git a/src/libfetchers/fetch-settings.hh b/src/libfetchers/fetch-settings.hh
index 4bc2d0e1a..6108a179c 100644
--- a/src/libfetchers/fetch-settings.hh
+++ b/src/libfetchers/fetch-settings.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "types.hh"
 #include "config.hh"
diff --git a/src/libfetchers/fetchers.hh b/src/libfetchers/fetchers.hh
index 95c0f5974..acdecea57 100644
--- a/src/libfetchers/fetchers.hh
+++ b/src/libfetchers/fetchers.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "types.hh"
 #include "hash.hh"
diff --git a/src/libfetchers/registry.hh b/src/libfetchers/registry.hh
index 260a2c460..f57ab1e6b 100644
--- a/src/libfetchers/registry.hh
+++ b/src/libfetchers/registry.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "types.hh"
 #include "fetchers.hh"
diff --git a/src/libmain/common-args.hh b/src/libmain/common-args.hh
index f180d83ce..e7ed0d934 100644
--- a/src/libmain/common-args.hh
+++ b/src/libmain/common-args.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "args.hh"
 
diff --git a/src/libmain/loggers.hh b/src/libmain/loggers.hh
index f3c759193..e5721420c 100644
--- a/src/libmain/loggers.hh
+++ b/src/libmain/loggers.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "types.hh"
 
diff --git a/src/libmain/progress-bar.cc b/src/libmain/progress-bar.cc
index 024259584..6600ec177 100644
--- a/src/libmain/progress-bar.cc
+++ b/src/libmain/progress-bar.cc
@@ -72,6 +72,7 @@ private:
         uint64_t corruptedPaths = 0, untrustedPaths = 0;
 
         bool active = true;
+        bool paused = false;
         bool haveUpdate = true;
     };
 
@@ -120,6 +121,18 @@ public:
         updateThread.join();
     }
 
+    void pause() override {
+        state_.lock()->paused = true;
+        writeToStderr("\r\e[K");
+    }
+
+    void resume() override {
+        state_.lock()->paused = false;
+        writeToStderr("\r\e[K");
+        state_.lock()->haveUpdate = true;
+        updateCV.notify_one();
+    }
+
     bool isVerbose() override
     {
         return printBuildLogs;
@@ -339,7 +352,7 @@ public:
         auto nextWakeup = std::chrono::milliseconds::max();
 
         state.haveUpdate = false;
-        if (!state.active) return nextWakeup;
+        if (state.paused || !state.active) return nextWakeup;
 
         std::string line;
 
diff --git a/src/libmain/progress-bar.hh b/src/libmain/progress-bar.hh
index 3a76f8448..c3c6e3833 100644
--- a/src/libmain/progress-bar.hh
+++ b/src/libmain/progress-bar.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "logging.hh"
 
diff --git a/src/libmain/shared.hh b/src/libmain/shared.hh
index 1715374a6..d915a4a65 100644
--- a/src/libmain/shared.hh
+++ b/src/libmain/shared.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "util.hh"
 #include "args.hh"
diff --git a/src/libstore/binary-cache-store.hh b/src/libstore/binary-cache-store.hh
index c1d08926d..5e52d7844 100644
--- a/src/libstore/binary-cache-store.hh
+++ b/src/libstore/binary-cache-store.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "crypto.hh"
 #include "store-api.hh"
diff --git a/src/libstore/build-result.hh b/src/libstore/build-result.hh
index a5749cf33..e50ddbb8c 100644
--- a/src/libstore/build-result.hh
+++ b/src/libstore/build-result.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "realisation.hh"
 #include "derived-path.hh"
diff --git a/src/libstore/build/derivation-goal.cc b/src/libstore/build/derivation-goal.cc
index 596034c0f..26faf8c8e 100644
--- a/src/libstore/build/derivation-goal.cc
+++ b/src/libstore/build/derivation-goal.cc
@@ -911,7 +911,11 @@ void DerivationGoal::buildDone()
                     msg += line;
                     msg += "\n";
                 }
-                msg += fmt("For full logs, run '" ANSI_BOLD "nix log %s" ANSI_NORMAL "'.",
+                auto nixLogCommand = experimentalFeatureSettings.isEnabled(Xp::NixCommand)
+                    ? "nix log"
+                    : "nix-store -l";
+                msg += fmt("For full logs, run '" ANSI_BOLD "%s %s" ANSI_NORMAL "'.",
+                    nixLogCommand,
                     worker.store.printStorePath(drvPath));
             }
 
diff --git a/src/libstore/build/derivation-goal.hh b/src/libstore/build/derivation-goal.hh
index 707e38b4b..f43ce22af 100644
--- a/src/libstore/build/derivation-goal.hh
+++ b/src/libstore/build/derivation-goal.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "parsed-derivations.hh"
 #include "lock.hh"
diff --git a/src/libstore/build/drv-output-substitution-goal.hh b/src/libstore/build/drv-output-substitution-goal.hh
index e4b044790..3b6620b76 100644
--- a/src/libstore/build/drv-output-substitution-goal.hh
+++ b/src/libstore/build/drv-output-substitution-goal.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "store-api.hh"
 #include "goal.hh"
diff --git a/src/libstore/build/goal.hh b/src/libstore/build/goal.hh
index 776eb86bc..924a8bbd5 100644
--- a/src/libstore/build/goal.hh
+++ b/src/libstore/build/goal.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "types.hh"
 #include "store-api.hh"
diff --git a/src/libstore/build/hook-instance.hh b/src/libstore/build/hook-instance.hh
index 9e8cff128..6bf60b297 100644
--- a/src/libstore/build/hook-instance.hh
+++ b/src/libstore/build/hook-instance.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "logging.hh"
 #include "serialise.hh"
diff --git a/src/libstore/build/local-derivation-goal.hh b/src/libstore/build/local-derivation-goal.hh
index c9ecc8828..1c4b4e3fe 100644
--- a/src/libstore/build/local-derivation-goal.hh
+++ b/src/libstore/build/local-derivation-goal.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "derivation-goal.hh"
 #include "local-store.hh"
diff --git a/src/libstore/build/personality.hh b/src/libstore/build/personality.hh
index 30e4f4062..91b730fab 100644
--- a/src/libstore/build/personality.hh
+++ b/src/libstore/build/personality.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <string>
 
diff --git a/src/libstore/build/substitution-goal.hh b/src/libstore/build/substitution-goal.hh
index a73f8e666..1add9eb14 100644
--- a/src/libstore/build/substitution-goal.hh
+++ b/src/libstore/build/substitution-goal.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "lock.hh"
 #include "store-api.hh"
diff --git a/src/libstore/build/worker.hh b/src/libstore/build/worker.hh
index 6d68d3cf1..d840b3b3f 100644
--- a/src/libstore/build/worker.hh
+++ b/src/libstore/build/worker.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "types.hh"
 #include "lock.hh"
diff --git a/src/libstore/builtins.hh b/src/libstore/builtins.hh
index 66597e456..d201fb3ac 100644
--- a/src/libstore/builtins.hh
+++ b/src/libstore/builtins.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "derivations.hh"
 
diff --git a/src/libstore/builtins/buildenv.hh b/src/libstore/builtins/buildenv.hh
index a018de3af..0923c2adb 100644
--- a/src/libstore/builtins/buildenv.hh
+++ b/src/libstore/builtins/buildenv.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "derivations.hh"
 #include "store-api.hh"
diff --git a/src/libstore/content-address.hh b/src/libstore/content-address.hh
index f6a6f5140..19fdfc1eb 100644
--- a/src/libstore/content-address.hh
+++ b/src/libstore/content-address.hh
@@ -1,48 +1,80 @@
 #pragma once
+///@file
 
 #include <variant>
 #include "hash.hh"
 
 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;
-  fixed-output derivations support multiple hash algorithms and 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().
-
-  * ‘fixed:<r?>:<ht>:<h>’: For paths computed by
-    makeFixedOutputPath() / addToStore().
-*/
+/**
+ * We've accumulated several types of content-addressed paths over the
+ * years; fixed-output derivations support multiple hash algorithms and
+ * 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 Store::makeTextPath() / Store::addTextToStore().
+ *
+ * - ‘fixed:<r?>:<ht>:<h>’: For paths computed by
+ *   Store::makeFixedOutputPath() / Store::addToStore().
+ */
 typedef std::variant<
-    TextHash, // for paths computed by makeTextPath() / addTextToStore
-    FixedOutputHash // for path computed by makeFixedOutputPath
+    TextHash,
+    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 +97,11 @@ struct FixedOutputHashMethod {
   HashType hashType;
 };
 
+/**
+ * Ways of content addressing but not a complete ContentAddress.
+ *
+ * A ContentAddress without a Hash.
+ */
 typedef std::variant<
     TextHashMethod,
     FixedOutputHashMethod
diff --git a/src/libstore/crypto.hh b/src/libstore/crypto.hh
index 03f85c103..a98f2a3b8 100644
--- a/src/libstore/crypto.hh
+++ b/src/libstore/crypto.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "types.hh"
 
diff --git a/src/libstore/daemon.hh b/src/libstore/daemon.hh
index 8c765615c..67340a05b 100644
--- a/src/libstore/daemon.hh
+++ b/src/libstore/daemon.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "serialise.hh"
 #include "store-api.hh"
diff --git a/src/libstore/derivations.hh b/src/libstore/derivations.hh
index 8456b29e7..e12bd2119 100644
--- a/src/libstore/derivations.hh
+++ b/src/libstore/derivations.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "path.hh"
 #include "types.hh"
@@ -17,42 +18,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
-   up being. */
+/**
+ * Floating-output derivations, whose output paths are content
+ * 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 +95,9 @@ typedef std::variant<
     DerivationOutputImpure
 > _DerivationOutputRaw;
 
+/**
+ * A single output of a BasicDerivation (and Derivation).
+ */
 struct DerivationOutput : _DerivationOutputRaw
 {
     using Raw = _DerivationOutputRaw;
@@ -75,9 +109,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
-       interface provided by BasicDerivation::outputsAndOptPaths */
+    /**
+     * \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 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 +129,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
-   be written. To calculate values of these types, see the corresponding
-   functions in BasicDerivation */
+/**
+ * These are analogues to the previous DerivationOutputs data type,
+ * but they also contains, for each output, the (optional) store
+ * 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 +200,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
-       network. Note that whether or not we actually sandbox the
-       derivation is controlled separately. Always true for non-CA
-       derivations. */
+    /**
+     * Whether the derivation is fully sandboxed. If false, the sandbox
+     * is opened up, e.g. the derivation has access to the network. Note
+     * that whether or not we actually sandbox the derivation is
+     * 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
-       is only false for derivations that have the attribute '__impure
-       = true'. */
+    /**
+     * Whether the derivation is expected to produce the same result
+     * every time, and therefore it only needs to be built once. This is
+     * 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
-       closure, or if fixed output.
+    /**
+     * Does the derivation knows its own output paths?
+     * Only true when there's no floating-ca derivation involved in the
+     * closure, or if fixed output.
      */
     bool hasKnownOutputPaths() const;
 
@@ -175,15 +255,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
-       into. */
+    /**
+     * Calculates the maps that contains all the DerivationOutputs, but
+     * 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 +277,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:
-
-       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. */
+    /**
+     * 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.
+     *
+     * 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
-       + output names to actual output store paths. */
+    /**
+     * Like the above, but instead of querying the Nix database for
+     * 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 +318,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.
-
-   This is usually <drv-name>-<output-name>, but is just <drv-name> when
-   the output name is "out". */
+/**
+ * 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".
+ */
 std::string outputPathName(std::string_view drvName, std::string_view outputName);
 
 
-// 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
-// output.
+/**
+ * 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
+ * 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.
-
-   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'
-   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'
-   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
-   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 regular derivations, it returns a single hash of the derivation
-   ATerm, after subderivations have been likewise expunged from that
-   derivation.
+/**
+ * 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
+ * exactly one output (`out'), which is specified using the `outputHash'
+ * 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'
+ * 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
+ * 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 regular derivations, it returns a single hash of the 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
-   derivation (modulo the self-references).
-
-   FIXME: what is the Hash in this map?
+/**
+ * Return a map associating each output to a hash that uniquely identifies its
+ * derivation (modulo the self-references).
+ *
+ * \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 +431,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.
-
-   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
-   itself, making the hash near-impossible to calculate. */
+/**
+ * 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
+ * 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.
-
-   It is used as a placeholder to allow derivations to refer to
-   content-addressed paths whose content --- and thus the path
-   themselves --- isn't yet known. This occurs when a derivation has a
-   dependency which is a CA derivation. */
+/**
+ * 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
+ * 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;
diff --git a/src/libstore/derived-path.hh b/src/libstore/derived-path.hh
index 9e0cce377..2155776b1 100644
--- a/src/libstore/derived-path.hh
+++ b/src/libstore/derived-path.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "util.hh"
 #include "path.hh"
@@ -105,7 +106,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 {
diff --git a/src/libstore/filetransfer.hh b/src/libstore/filetransfer.hh
index 07d58f53a..378c6ff78 100644
--- a/src/libstore/filetransfer.hh
+++ b/src/libstore/filetransfer.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "types.hh"
 #include "hash.hh"
@@ -87,39 +88,56 @@ struct FileTransfer
 {
     virtual ~FileTransfer() { }
 
-    /* Enqueue a data transfer request, returning a future to the result of
-       the download. The future may throw a FileTransferError
-       exception. */
+    /**
+     * Enqueue a data transfer request, returning a future to the result of
+     * the download. The future may throw a FileTransferError
+     * exception.
+     */
     virtual void enqueueFileTransfer(const FileTransferRequest & request,
         Callback<FileTransferResult> callback) = 0;
 
     std::future<FileTransferResult> enqueueFileTransfer(const FileTransferRequest & request);
 
-    /* Synchronously download a file. */
+    /**
+     * Synchronously download a file.
+     */
     FileTransferResult download(const FileTransferRequest & request);
 
-    /* Synchronously upload a file. */
+    /**
+     * Synchronously upload a file.
+     */
     FileTransferResult upload(const FileTransferRequest & request);
 
-    /* Download a file, writing its data to a sink. The sink will be
-       invoked on the thread of the caller. */
+    /**
+     * Download a file, writing its data to a sink. The sink will be
+     * invoked on the thread of the caller.
+     */
     void download(FileTransferRequest && request, Sink & sink);
 
     enum Error { NotFound, Forbidden, Misc, Transient, Interrupted };
 };
 
-/* Return a shared FileTransfer object. Using this object is preferred
-   because it enables connection reuse and HTTP/2 multiplexing. */
+/**
+ * @return a shared FileTransfer object.
+ *
+ * Using this object is preferred because it enables connection reuse
+ * and HTTP/2 multiplexing.
+ */
 ref<FileTransfer> getFileTransfer();
 
-/* Return a new FileTransfer object. */
+/**
+ * @return a new FileTransfer object
+ *
+ * Prefer getFileTransfer() to this; see its docs for why.
+ */
 ref<FileTransfer> makeFileTransfer();
 
 class FileTransferError : public Error
 {
 public:
     FileTransfer::Error error;
-    std::optional<std::string> response; // intentionally optional
+    /// intentionally optional
+    std::optional<std::string> response;
 
     template<typename... Args>
     FileTransferError(FileTransfer::Error error, std::optional<std::string> response, const Args & ... args);
diff --git a/src/libstore/fs-accessor.hh b/src/libstore/fs-accessor.hh
index c825e84f2..1c98a42d7 100644
--- a/src/libstore/fs-accessor.hh
+++ b/src/libstore/fs-accessor.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "types.hh"
 
diff --git a/src/libstore/gc-store.hh b/src/libstore/gc-store.hh
index b3cbbad74..17f043a63 100644
--- a/src/libstore/gc-store.hh
+++ b/src/libstore/gc-store.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "store-api.hh"
 
diff --git a/src/libstore/globals.hh b/src/libstore/globals.hh
index 299584f99..9b04c9e78 100644
--- a/src/libstore/globals.hh
+++ b/src/libstore/globals.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "types.hh"
 #include "config.hh"
diff --git a/src/libstore/local-fs-store.hh b/src/libstore/local-fs-store.hh
index 796e72045..1e7f31a09 100644
--- a/src/libstore/local-fs-store.hh
+++ b/src/libstore/local-fs-store.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "store-api.hh"
 #include "gc-store.hh"
diff --git a/src/libstore/local-store.hh b/src/libstore/local-store.hh
index 639772b36..2eaf451bf 100644
--- a/src/libstore/local-store.hh
+++ b/src/libstore/local-store.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "sqlite.hh"
 
diff --git a/src/libstore/lock.hh b/src/libstore/lock.hh
index 7f1934510..7be3ba314 100644
--- a/src/libstore/lock.hh
+++ b/src/libstore/lock.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "types.hh"
 
diff --git a/src/libstore/log-store.hh b/src/libstore/log-store.hh
index e4d95bab6..7aeec73b2 100644
--- a/src/libstore/log-store.hh
+++ b/src/libstore/log-store.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "store-api.hh"
 
diff --git a/src/libstore/machines.hh b/src/libstore/machines.hh
index 834626de9..1adeaf1f0 100644
--- a/src/libstore/machines.hh
+++ b/src/libstore/machines.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "types.hh"
 
diff --git a/src/libstore/make-content-addressed.hh b/src/libstore/make-content-addressed.hh
index c4a66ed41..2ce6ec7bc 100644
--- a/src/libstore/make-content-addressed.hh
+++ b/src/libstore/make-content-addressed.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "store-api.hh"
 
diff --git a/src/libstore/names.hh b/src/libstore/names.hh
index 3977fc6cc..d82b99bb4 100644
--- a/src/libstore/names.hh
+++ b/src/libstore/names.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <memory>
 
diff --git a/src/libstore/nar-accessor.hh b/src/libstore/nar-accessor.hh
index 7d998ae0b..940e537b6 100644
--- a/src/libstore/nar-accessor.hh
+++ b/src/libstore/nar-accessor.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <functional>
 
diff --git a/src/libstore/nar-info-disk-cache.hh b/src/libstore/nar-info-disk-cache.hh
index 4877f56d8..c596f2d71 100644
--- a/src/libstore/nar-info-disk-cache.hh
+++ b/src/libstore/nar-info-disk-cache.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "ref.hh"
 #include "nar-info.hh"
diff --git a/src/libstore/nar-info.hh b/src/libstore/nar-info.hh
index 01683ec73..3cae8e659 100644
--- a/src/libstore/nar-info.hh
+++ b/src/libstore/nar-info.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "types.hh"
 #include "hash.hh"
diff --git a/src/libstore/outputs-spec.hh b/src/libstore/outputs-spec.hh
index 46bc35ebc..5a726fe90 100644
--- a/src/libstore/outputs-spec.hh
+++ b/src/libstore/outputs-spec.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <cassert>
 #include <optional>
@@ -9,6 +10,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 +22,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 +35,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 +46,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 +64,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 +99,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);
 
diff --git a/src/libstore/parsed-derivations.hh b/src/libstore/parsed-derivations.hh
index bfb3857c0..71085a604 100644
--- a/src/libstore/parsed-derivations.hh
+++ b/src/libstore/parsed-derivations.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "derivations.hh"
 #include "store-api.hh"
diff --git a/src/libstore/path-info.hh b/src/libstore/path-info.hh
index a7fcbd232..b28bf751c 100644
--- a/src/libstore/path-info.hh
+++ b/src/libstore/path-info.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "crypto.hh"
 #include "path.hh"
diff --git a/src/libstore/path-regex.hh b/src/libstore/path-regex.hh
index 6893c3876..4f8dc4c1f 100644
--- a/src/libstore/path-regex.hh
+++ b/src/libstore/path-regex.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 namespace nix {
 
diff --git a/src/libstore/path-with-outputs.hh b/src/libstore/path-with-outputs.hh
index 5d25656a5..a845b0e5f 100644
--- a/src/libstore/path-with-outputs.hh
+++ b/src/libstore/path-with-outputs.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "path.hh"
 #include "derived-path.hh"
diff --git a/src/libstore/path.hh b/src/libstore/path.hh
index 1e5579b90..4ca6747b3 100644
--- a/src/libstore/path.hh
+++ b/src/libstore/path.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <string_view>
 
@@ -8,13 +9,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 +55,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 +78,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";
 
 }
diff --git a/src/libstore/pathlocks.hh b/src/libstore/pathlocks.hh
index 5e3a734b4..ba8f2749b 100644
--- a/src/libstore/pathlocks.hh
+++ b/src/libstore/pathlocks.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "util.hh"
 
diff --git a/src/libstore/profiles.hh b/src/libstore/profiles.hh
index 3cadd5c2a..6a5965390 100644
--- a/src/libstore/profiles.hh
+++ b/src/libstore/profiles.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "types.hh"
 #include "pathlocks.hh"
diff --git a/src/libstore/realisation.hh b/src/libstore/realisation.hh
index 48d0283de..a18cf2aa8 100644
--- a/src/libstore/realisation.hh
+++ b/src/libstore/realisation.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <variant>
 
diff --git a/src/libstore/references.hh b/src/libstore/references.hh
index 6f381f96c..52d71b333 100644
--- a/src/libstore/references.hh
+++ b/src/libstore/references.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "hash.hh"
 #include "path.hh"
diff --git a/src/libstore/remote-fs-accessor.hh b/src/libstore/remote-fs-accessor.hh
index 99f5544ef..e2673b6f6 100644
--- a/src/libstore/remote-fs-accessor.hh
+++ b/src/libstore/remote-fs-accessor.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "fs-accessor.hh"
 #include "ref.hh"
diff --git a/src/libstore/remote-store.hh b/src/libstore/remote-store.hh
index 999151239..f5f45f853 100644
--- a/src/libstore/remote-store.hh
+++ b/src/libstore/remote-store.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <limits>
 #include <string>
diff --git a/src/libstore/repair-flag.hh b/src/libstore/repair-flag.hh
index a13cda312..f412d6a20 100644
--- a/src/libstore/repair-flag.hh
+++ b/src/libstore/repair-flag.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 namespace nix {
 
diff --git a/src/libstore/s3-binary-cache-store.hh b/src/libstore/s3-binary-cache-store.hh
index bce828b11..c62ea5147 100644
--- a/src/libstore/s3-binary-cache-store.hh
+++ b/src/libstore/s3-binary-cache-store.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "binary-cache-store.hh"
 
diff --git a/src/libstore/s3.hh b/src/libstore/s3.hh
index cdb3e5908..f0aeb3bed 100644
--- a/src/libstore/s3.hh
+++ b/src/libstore/s3.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #if ENABLE_S3
 
diff --git a/src/libstore/serve-protocol.hh b/src/libstore/serve-protocol.hh
index 3f76baa82..553fd3a09 100644
--- a/src/libstore/serve-protocol.hh
+++ b/src/libstore/serve-protocol.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 namespace nix {
 
diff --git a/src/libstore/sqlite.hh b/src/libstore/sqlite.hh
index 1853731a2..86410f998 100644
--- a/src/libstore/sqlite.hh
+++ b/src/libstore/sqlite.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <functional>
 #include <string>
diff --git a/src/libstore/ssh-store-config.hh b/src/libstore/ssh-store-config.hh
index c4232df34..c27a5d00f 100644
--- a/src/libstore/ssh-store-config.hh
+++ b/src/libstore/ssh-store-config.hh
@@ -1,3 +1,6 @@
+#pragma once
+///@file
+
 #include "store-api.hh"
 
 namespace nix {
diff --git a/src/libstore/ssh.cc b/src/libstore/ssh.cc
index 69bfe3418..6f6deda51 100644
--- a/src/libstore/ssh.cc
+++ b/src/libstore/ssh.cc
@@ -1,4 +1,5 @@
 #include "ssh.hh"
+#include "finally.hh"
 
 namespace nix {
 
@@ -35,6 +36,9 @@ void SSHMaster::addCommonSSHOpts(Strings & args)
     }
     if (compress)
         args.push_back("-C");
+
+    args.push_back("-oPermitLocalCommand=yes");
+    args.push_back("-oLocalCommand=echo started");
 }
 
 std::unique_ptr<SSHMaster::Connection> SSHMaster::startCommand(const std::string & command)
@@ -49,6 +53,11 @@ std::unique_ptr<SSHMaster::Connection> SSHMaster::startCommand(const std::string
     ProcessOptions options;
     options.dieWithParent = false;
 
+    if (!fakeSSH && !useMaster) {
+        logger->pause();
+    }
+    Finally cleanup = [&]() { logger->resume(); };
+
     conn->sshPid = startProcess([&]() {
         restoreProcessContext();
 
@@ -86,6 +95,18 @@ std::unique_ptr<SSHMaster::Connection> SSHMaster::startCommand(const std::string
     in.readSide = -1;
     out.writeSide = -1;
 
+    // Wait for the SSH connection to be established,
+    // So that we don't overwrite the password prompt with our progress bar.
+    if (!fakeSSH && !useMaster) {
+        std::string reply;
+        try {
+            reply = readLine(out.readSide.get());
+        } catch (EndOfFile & e) { }
+
+        if (reply != "started")
+            throw Error("failed to start SSH connection to '%s'", host);
+    }
+
     conn->out = std::move(out.readSide);
     conn->in = std::move(in.writeSide);
 
@@ -109,6 +130,9 @@ Path SSHMaster::startMaster()
     ProcessOptions options;
     options.dieWithParent = false;
 
+    logger->pause();
+    Finally cleanup = [&]() { logger->resume(); };
+
     state->sshMaster = startProcess([&]() {
         restoreProcessContext();
 
@@ -117,11 +141,7 @@ Path SSHMaster::startMaster()
         if (dup2(out.writeSide.get(), STDOUT_FILENO) == -1)
             throw SysError("duping over stdout");
 
-        Strings args =
-            { "ssh", host.c_str(), "-M", "-N", "-S", state->socketPath
-            , "-o", "LocalCommand=echo started"
-            , "-o", "PermitLocalCommand=yes"
-            };
+        Strings args = { "ssh", host.c_str(), "-M", "-N", "-S", state->socketPath };
         if (verbosity >= lvlChatty)
             args.push_back("-v");
         addCommonSSHOpts(args);
diff --git a/src/libstore/ssh.hh b/src/libstore/ssh.hh
index dabbcedda..c86a8a986 100644
--- a/src/libstore/ssh.hh
+++ b/src/libstore/ssh.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "util.hh"
 #include "sync.hh"
diff --git a/src/libstore/store-api.cc b/src/libstore/store-api.cc
index b0ca1321c..60e87918a 100644
--- a/src/libstore/store-api.cc
+++ b/src/libstore/store-api.cc
@@ -1101,7 +1101,8 @@ std::map<StorePath, StorePath> copyPaths(
         return storePathForDst;
     };
 
-    uint64_t total = 0;
+    // total is accessed by each copy, which are each handled in separate threads
+    std::atomic<uint64_t> total = 0;
 
     for (auto & missingPath : sortedMissing) {
         auto info = srcStore.queryPathInfo(missingPath);
diff --git a/src/libstore/store-api.hh b/src/libstore/store-api.hh
index 2f4391c43..58d7b848e 100644
--- a/src/libstore/store-api.hh
+++ b/src/libstore/store-api.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "nar-info.hh"
 #include "realisation.hh"
@@ -55,7 +56,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 +82,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 +159,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 +212,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 +279,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
-       path and the cryptographic hash of the contents of srcPath. */
+    /**
+     * Preparatory part of addToStore().
+     *
+     * @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().
-
-       !!! Computation of the path should take the references given to
-       addTextToStore() into account, otherwise we have a (relatively
-       minor) security hole: a caller can register a source file with
-       bogus references.  If there are too many references, the path may
-       not be garbage collected when it has to be (not really a problem,
-       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
-       affected), but it has some backwards compatibility issues (the
-       hashing scheme changes), so I'm not doing that for now. */
+    /**
+     * Preparatory part of addTextToStore().
+     *
+     * !!! Computation of the path should take the references given to
+     * addTextToStore() into account, otherwise we have a (relatively
+     * minor) security hole: a caller can register a source file with
+     * bogus references.  If there are too many references, the path may
+     * not be garbage collected when it has to be (not really a problem,
+     * 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
+     * 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 +321,68 @@ protected:
 
 public:
 
-    /* If requested, substitute missing paths. This
-       implements nix-copy-closure's --use-substitutes
-       flag. */
+    /**
+     * If requested, substitute missing paths. This
+     * 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'
-       (i.e. you'll get /nix/store/<hash>-x rather than
-       /nix/store/<hash>-<name>). Use queryPathInfo() to obtain the
-       full store path. FIXME: should return a set of
-       std::variant<StorePath, HashPart> to get rid of this hack. */
+    /**
+     * Query the set of all valid paths. Note that for some store
+     * backends, the name part of store paths may be replaced by 'x'
+     * (i.e. you'll get /nix/store/<hash>-x rather than
+     * /nix/store/<hash>-<name>). Use queryPathInfo() to obtain the
+     * 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
-       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
-       the addToStore wouldn't fail until those dependencies are added. Also,
-       we don't really want to add the dependencies listed in a nar info we
-       don't trust anyyways.
-       */
+    /**
+     * Check whether the given valid path info is sufficiently attested, by
+     * 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
+     * the addToStore wouldn't fail until those dependencies are added. Also,
+     * 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 +402,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
-       derivation that was actually used to produce `path', which may
-       not exist anymore.) */
+    /**
+     * @return all currently valid derivations that have `path' as an
+     * output.
+     *
+     * (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
-       `std::nullopt`.  */
+    /**
+     * Query the mapping outputName => outputPath for the given
+     * 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
-       of the first succeeding substituter for each path will be
-       returned. If a path does not have substitute info, it's omitted
-       from the resulting ‘infos’ map. */
+    /**
+     * Query substitute info (i.e. references, derivers and download
+     * sizes) of a map of paths to their optional ca values. The info of
+     * the first succeeding substituter for each path will be returned.
+     * 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 +484,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.
-       The function object `filter' can be used to exclude files (see
-       libutil/archive.hh). */
+    /**
+     * Copy the contents of a path to the store and register the
+     * validity the resulting path.
+     *
+     * @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 +501,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
-       memory. */
+    /**
+     * Copy the contents of a path to the store and register the
+     * 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 ==
-       true) or simply the contents of a regular file (if recursive ==
-       false).
-       `dump` may be drained */
-    // FIXME: remove?
+    /**
+     * Like addToStore(), but the contents of the path are contained
+     * 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
+     *
+     * \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 +548,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
-       they are already valid, this is a no-op.  Otherwise, validity
-       can be reached in two ways.  First, if the output paths is
-       substitutable, then build the path that way.  Second, the
-       output paths can be created by running the builder, after
-       recursively building any sub-derivations. For inputs that are
-       not derivations, substitute them. */
+    /**
+     * For each path, if it's a derivation, build it.  Building a
+     * derivation means ensuring that the output paths are valid.  If
+     * they are already valid, this is a no-op.  Otherwise, validity
+     * can be reached in two ways.  First, if the output paths is
+     * substitutable, then build the path that way.  Second, the
+     * output paths can be created by running the builder, after
+     * 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
-       a build/substitution error, this function won't throw an
-       exception, but return a `BuildResult` containing an error
-       message. */
+    /**
+     * Like buildPaths(), but return a vector of \ref BuildResult
+     * BuildResults corresponding to each element in paths. Note that in
+     * case of a build/substitution error, this function won't throw an
+     * 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).
-
-       ‘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
-       would be calculated from writing this derivation to the store: it is OK
-       if it instead is that of a Derivation which would resolve to this (by
-       taking the outputs of it's input derivations and adding them as input
-       sources) such that the build time referenceable-paths are the same.
-
-       In the input-addressed case, we usually *do* use an "original"
-       unresolved derivations's path, as that is what will be used in the
-       `buildPaths` case. Also, the input-addressed output paths are verified
-       only by that contents of that specific unresolved derivation, so it is
-       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
-       used the proper output path.
-
-       In the content-addressed case, we want to always use the
-       resolved drv path calculated from the provided derivation. This serves
-       two purposes:
-
-         - It keeps the operation trustless, by ruling out a maliciously
-           invalid drv path corresponding to a non-resolution-equivalent
-           derivation.
-
-         - For the floating case in particular, it ensures that the derivation
-           to output mapping respects the resolution equivalence relation, so
-           one cannot choose different resolution-equivalent derivations to
-           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).
-    */
+    /**
+     * Build a single non-materialized derivation (i.e. not from an
+     * on-disk .drv file).
+     *
+     * @param drvPath This 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 would be calculated from writing this
+     * derivation to the store: it is OK if it instead is that of a
+     * Derivation which would resolve to this (by taking the outputs of
+     * it's input derivations and adding them as input sources) such
+     * that the build time referenceable-paths are the same.
+     *
+     * In the input-addressed case, we usually *do* use an "original"
+     * unresolved derivations's path, as that is what will be used in the
+     * buildPaths case. Also, the input-addressed output paths are verified
+     * only by that contents of that specific unresolved derivation, so it is
+     * 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
+     * used the proper output path.
+     *
+     * In the content-addressed case, we want to always use the resolved
+     * drv path calculated from the provided derivation. This serves two
+     * purposes:
+     *
+     *   - It keeps the operation trustless, by ruling out a maliciously
+     *     invalid drv path corresponding to a non-resolution-equivalent
+     *     derivation.
+     *
+     *   - For the floating case in particular, it ensures that the derivation
+     *     to output mapping respects the resolution equivalence relation, so
+     *     one cannot choose different resolution-equivalent derivations to
+     *     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
-       path). */
+    /**
+     * 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
+     * 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
-       `nix-store --register-validity'. */
+    /**
+     * @return a string representing information about the path that
+     * 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,
-       variable elements such as the registration time are
-       included. If ‘showClosureSize’ is true, the closure size of
-       each path is included. */
+    /**
+     * Write a JSON representation of store path metadata, such as the
+     * hash and the references.
+     *
+     * @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
-       the closure. */
+    /**
+     * @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 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
-       or indirectly reached from it.  `out' is not cleared.  If
-       `flipDirection' is true, the set of paths that can reach
-       `storePath' is returned; that is, the closures under the
-       `referrers' relation instead of the `references' relation is
-       returned. */
+    /**
+     * @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
+     * 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
+     * `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 +730,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
-       that will be substituted. */
+    /**
+     * 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 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
-       preloaded into the specified FS accessor to speed up subsequent
-       access. */
+    /**
+     * Import a sequence of NAR dumps created by exportPaths() into the
+     * Nix store. Optionally, the contents of the NARs are preloaded
+     * into the specified FS accessor to speed up subsequent access.
+     */
     StorePaths importPaths(Source & source, CheckSigsFlag checkSigs = CheckSigs);
 
     struct Stats
@@ -642,8 +779,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 +792,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 +825,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 +837,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 +852,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 +863,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.
-   if A is a reference of B, then A is copied before B), but the set
-   of store paths is not automatically closed; use copyClosure() for
-   that. Returns a map of what each path was copied to the dstStore
-   as. */
+/**
+ * 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. if
+ * A is a reference of B, then A is copied before B), but the set of
+ * store paths is not automatically closed; use copyClosure() for that.
+ *
+ * @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 +885,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 +902,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
-   as a (permanent) root. */
+/**
+ * Remove the temporary roots file for this process.  Any temporary
+ * 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:
-
-   * ‘local’: The Nix store in /nix/store and database in
-     /nix/var/nix/db, accessed directly.
-
-   * ‘daemon’: The Nix store accessed via a Unix domain socket
-     connection to nix-daemon.
-
-   * ‘unix://<path>’: The Nix store accessed via a Unix domain socket
-     connection to nix-daemon, with the socket located at <path>.
-
-   * ‘auto’ or ‘’: Equivalent to ‘local’ or ‘daemon’ depending on
-     whether the user has write access to the local Nix
-     store/database.
-
-   * ‘file://<path>’: A binary cache stored in <path>.
-
-   * ‘https://<path>’: A binary cache accessed via HTTP.
-
-   * ‘s3://<path>’: A writable binary cache stored on Amazon's Simple
-     Storage Service.
-
-   * ‘ssh://[user@]<host>’: A remote Nix store accessed by running
-     ‘nix-store --serve’ via SSH.
-
-   You can pass parameters to the store implementation by appending
-   ‘?key=value&key=value&...’ to the URI.
-*/
+/**
+ * @return a Store object to access the Nix store denoted by
+ * ‘uri’ (slight misnomer...).
+ *
+ * @param uri Supported values are:
+ *
+ * - ‘local’: The Nix store in /nix/store and database in
+ *   /nix/var/nix/db, accessed directly.
+ *
+ * - ‘daemon’: The Nix store accessed via a Unix domain socket
+ *   connection to nix-daemon.
+ *
+ * - ‘unix://<path>’: The Nix store accessed via a Unix domain socket
+ *   connection to nix-daemon, with the socket located at <path>.
+ *
+ * - ‘auto’ or ‘’: Equivalent to ‘local’ or ‘daemon’ depending on
+ *   whether the user has write access to the local Nix
+ *   store/database.
+ *
+ * - ‘file://<path>’: A binary cache stored in <path>.
+ *
+ * - ‘https://<path>’: A binary cache accessed via HTTP.
+ *
+ * - ‘s3://<path>’: A writable binary cache stored on Amazon's Simple
+ *   Storage Service.
+ *
+ * - ‘ssh://[user@]<host>’: A remote Nix store accessed by running
+ *   ‘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 +999,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 +1011,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);
diff --git a/src/libstore/store-cast.hh b/src/libstore/store-cast.hh
index ff62fc359..2473e72c5 100644
--- a/src/libstore/store-cast.hh
+++ b/src/libstore/store-cast.hh
@@ -1,9 +1,17 @@
 #pragma once
+///@file
 
 #include "store-api.hh"
 
 namespace nix {
 
+/**
+ * Helper to try downcasting a Store with a nice method if it fails.
+ *
+ * This is basically an alternative to the user-facing part of
+ * Store::unsupported that allows us to still have a nice message but
+ * better interface design.
+ */
 template<typename T>
 T & require(Store & store)
 {
diff --git a/src/libstore/tests/derived-path.hh b/src/libstore/tests/derived-path.hh
index 3bc812440..506f3ccb1 100644
--- a/src/libstore/tests/derived-path.hh
+++ b/src/libstore/tests/derived-path.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <rapidcheck/gen/Arbitrary.h>
 
diff --git a/src/libstore/tests/libstore.hh b/src/libstore/tests/libstore.hh
index 05397659b..ef93457b5 100644
--- a/src/libstore/tests/libstore.hh
+++ b/src/libstore/tests/libstore.hh
@@ -1,3 +1,6 @@
+#pragma once
+///@file
+
 #include <gtest/gtest.h>
 #include <gmock/gmock.h>
 
diff --git a/src/libstore/tests/outputs-spec.hh b/src/libstore/tests/outputs-spec.hh
index 2d455c817..ded331b33 100644
--- a/src/libstore/tests/outputs-spec.hh
+++ b/src/libstore/tests/outputs-spec.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <rapidcheck/gen/Arbitrary.h>
 
diff --git a/src/libstore/tests/path.hh b/src/libstore/tests/path.hh
index d7f1a8988..21cb62310 100644
--- a/src/libstore/tests/path.hh
+++ b/src/libstore/tests/path.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <rapidcheck/gen/Arbitrary.h>
 
diff --git a/src/libstore/uds-remote-store.hh b/src/libstore/uds-remote-store.hh
index caa452919..bd1dcb67c 100644
--- a/src/libstore/uds-remote-store.hh
+++ b/src/libstore/uds-remote-store.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "remote-store.hh"
 #include "local-fs-store.hh"
diff --git a/src/libstore/worker-protocol.hh b/src/libstore/worker-protocol.hh
index 87088a3ac..697dd2b8c 100644
--- a/src/libstore/worker-protocol.hh
+++ b/src/libstore/worker-protocol.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "store-api.hh"
 #include "serialise.hh"
@@ -14,6 +15,10 @@ namespace nix {
 #define GET_PROTOCOL_MINOR(x) ((x) & 0x00ff)
 
 
+/**
+ * Enumeration of all the request types for the "worker protocol", used
+ * by unix:// and ssh-ng:// stores.
+ */
 typedef enum {
     wopIsValidPath = 1,
     wopHasSubstitutes = 3,
@@ -74,7 +79,12 @@ typedef enum {
 class Store;
 struct Source;
 
-/* To guide overloading */
+/**
+ * Used to guide overloading
+ *
+ * See https://en.cppreference.com/w/cpp/language/adl for the broader
+ * concept of what is going on here.
+ */
 template<typename T>
 struct Phantom {};
 
@@ -103,18 +113,19 @@ MAKE_WORKER_PROTO(X_, Y_);
 #undef X_
 #undef Y_
 
-/* These use the empty string for the null case, relying on the fact
-   that the underlying types never serialize to the empty string.
-
-   We do this instead of a generic std::optional<T> instance because
-   ordinal tags (0 or 1, here) are a bit of a compatability hazard. For
-   the same reason, we don't have a std::variant<T..> instances (ordinal
-   tags 0...n).
-
-   We could the generic instances and then these as specializations for
-   compatability, but that's proven a bit finnicky, and also makes the
-   worker protocol harder to implement in other languages where such
-   specializations may not be allowed.
+/**
+ * These use the empty string for the null case, relying on the fact
+ * that the underlying types never serialize to the empty string.
+ *
+ * We do this instead of a generic std::optional<T> instance because
+ * ordinal tags (0 or 1, here) are a bit of a compatability hazard. For
+ * the same reason, we don't have a std::variant<T..> instances (ordinal
+ * tags 0...n).
+ *
+ * We could the generic instances and then these as specializations for
+ * compatability, but that's proven a bit finnicky, and also makes the
+ * worker protocol harder to implement in other languages where such
+ * specializations may not be allowed.
  */
 MAKE_WORKER_PROTO(, std::optional<StorePath>);
 MAKE_WORKER_PROTO(, std::optional<ContentAddress>);
diff --git a/src/libutil/abstract-setting-to-json.hh b/src/libutil/abstract-setting-to-json.hh
index 2d82b54e7..7b6c3fcb5 100644
--- a/src/libutil/abstract-setting-to-json.hh
+++ b/src/libutil/abstract-setting-to-json.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <nlohmann/json.hpp>
 #include "config.hh"
diff --git a/src/libutil/ansicolor.hh b/src/libutil/ansicolor.hh
index 38305e71c..54721649c 100644
--- a/src/libutil/ansicolor.hh
+++ b/src/libutil/ansicolor.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 namespace nix {
 
diff --git a/src/libutil/archive.hh b/src/libutil/archive.hh
index e42dea540..60e33dd40 100644
--- a/src/libutil/archive.hh
+++ b/src/libutil/archive.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "types.hh"
 #include "serialise.hh"
@@ -7,54 +8,71 @@
 namespace nix {
 
 
-/* dumpPath creates a Nix archive of the specified path.  The format
-   is as follows:
-
-   IF path points to a REGULAR FILE:
-     dump(path) = attrs(
-       [ ("type", "regular")
-       , ("contents", contents(path))
-       ])
-
-   IF path points to a DIRECTORY:
-     dump(path) = attrs(
-       [ ("type", "directory")
-       , ("entries", concat(map(f, sort(entries(path)))))
-       ])
-       where f(fn) = attrs(
-         [ ("name", fn)
-         , ("file", dump(path + "/" + fn))
-         ])
-
-   where:
-
-     attrs(as) = concat(map(attr, as)) + encN(0)
-     attrs((a, b)) = encS(a) + encS(b)
-
-     encS(s) = encN(len(s)) + s + (padding until next 64-bit boundary)
-
-     encN(n) = 64-bit little-endian encoding of n.
-
-     contents(path) = the contents of a regular file.
-
-     sort(strings) = lexicographic sort by 8-bit value (strcmp).
-
-     entries(path) = the entries of a directory, without `.' and
-     `..'.
-
-     `+' denotes string concatenation. */
-
-
+/**
+ * dumpPath creates a Nix archive of the specified path.
+ *
+ * @param path the file system data to dump. Dumping is recursive so if
+ * this is a directory we dump it and all its children.
+ *
+ * @param [out] sink The serialised archive is fed into this sink.
+ *
+ * @param filter Can be used to skip certain files.
+ *
+ * The format is as follows:
+ *
+ *     IF path points to a REGULAR FILE:
+ *       dump(path) = attrs(
+ *         [ ("type", "regular")
+ *         , ("contents", contents(path))
+ *         ])
+ *
+ *     IF path points to a DIRECTORY:
+ *       dump(path) = attrs(
+ *         [ ("type", "directory")
+ *         , ("entries", concat(map(f, sort(entries(path)))))
+ *         ])
+ *         where f(fn) = attrs(
+ *           [ ("name", fn)
+ *           , ("file", dump(path + "/" + fn))
+ *           ])
+ *
+ *     where:
+ *
+ *       attrs(as) = concat(map(attr, as)) + encN(0)
+ *       attrs((a, b)) = encS(a) + encS(b)
+ *
+ *       encS(s) = encN(len(s)) + s + (padding until next 64-bit boundary)
+ *
+ *       encN(n) = 64-bit little-endian encoding of n.
+ *
+ *       contents(path) = the contents of a regular file.
+ *
+ *       sort(strings) = lexicographic sort by 8-bit value (strcmp).
+ *
+ *       entries(path) = the entries of a directory, without `.' and
+ *       `..'.
+ *
+ *       `+' denotes string concatenation.
+ */
 void dumpPath(const Path & path, Sink & sink,
     PathFilter & filter = defaultPathFilter);
 
-/* Same as `void dumpPath()`, but returns the last modified date of the path */
+/**
+ * Same as dumpPath(), but returns the last modified date of the path.
+ */
 time_t dumpPathAndGetMtime(const Path & path, Sink & sink,
     PathFilter & filter = defaultPathFilter);
 
+/**
+ * Dump an archive with a single file with these contents.
+ *
+ * @param s Contents of the file.
+ */
 void dumpString(std::string_view s, Sink & sink);
 
-/* FIXME: fix this API, it sucks. */
+/**
+ * \todo Fix this API, it sucks.
+ */
 struct ParseSink
 {
     virtual void createDirectory(const Path & path) { };
@@ -68,8 +86,10 @@ struct ParseSink
     virtual void createSymlink(const Path & path, const std::string & target) { };
 };
 
-/* If the NAR archive contains a single file at top-level, then save
-   the contents of the file to `s'.  Otherwise barf. */
+/**
+ * If the NAR archive contains a single file at top-level, then save
+ * the contents of the file to `s'.  Otherwise barf.
+ */
 struct RetrieveRegularNARSink : ParseSink
 {
     bool regular = true;
@@ -97,7 +117,9 @@ void parseDump(ParseSink & sink, Source & source);
 
 void restorePath(const Path & path, Source & source);
 
-/* Read a NAR from 'source' and write it to 'sink'. */
+/**
+ * Read a NAR from 'source' and write it to 'sink'.
+ */
 void copyNAR(Source & source, Sink & sink);
 
 void copyPath(const Path & from, const Path & to);
diff --git a/src/libutil/args.hh b/src/libutil/args.hh
index 2969806dd..07d0d8eae 100644
--- a/src/libutil/args.hh
+++ b/src/libutil/args.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <iostream>
 #include <map>
@@ -18,16 +19,22 @@ class Args
 {
 public:
 
-    /* Parse the command line, throwing a UsageError if something goes
-       wrong. */
+    /**
+     * Parse the command line, throwing a UsageError if something goes
+     * wrong.
+     */
     void parseCmdline(const Strings & cmdline);
 
-    /* Return a short one-line description of the command. */
+    /**
+     * Return a short one-line description of the command.
+     */
     virtual std::string description() { return ""; }
 
     virtual bool forceImpureByDefault() { return false; }
 
-    /* Return documentation about this command, in Markdown format. */
+    /**
+     * Return documentation about this command, in Markdown format.
+     */
     virtual std::string doc() { return ""; }
 
 protected:
@@ -146,13 +153,17 @@ protected:
 
     std::set<std::string> hiddenCategories;
 
-    /* Called after all command line flags before the first non-flag
-       argument (if any) have been processed. */
+    /**
+     * Called after all command line flags before the first non-flag
+     * argument (if any) have been processed.
+     */
     virtual void initialFlagsProcessed() {}
 
-    /* Called after the command line has been processed if we need to generate
-       completions. Useful for commands that need to know the whole command line
-       in order to know what completions to generate. */
+    /**
+     * Called after the command line has been processed if we need to generate
+     * completions. Useful for commands that need to know the whole command line
+     * in order to know what completions to generate.
+     */
     virtual void completionHook() { }
 
 public:
@@ -166,7 +177,9 @@ public:
         expectedArgs.emplace_back(std::move(arg));
     }
 
-    /* Expect a string argument. */
+    /**
+     * Expect a string argument.
+     */
     void expectArg(const std::string & label, std::string * dest, bool optional = false)
     {
         expectArgs({
@@ -176,7 +189,9 @@ public:
         });
     }
 
-    /* Expect 0 or more arguments. */
+    /**
+     * Expect 0 or more arguments.
+     */
     void expectArgs(const std::string & label, std::vector<std::string> * dest)
     {
         expectArgs({
@@ -202,14 +217,19 @@ private:
     std::set<ExperimentalFeature> flagExperimentalFeatures;
 };
 
-/* A command is an argument parser that can be executed by calling its
-   run() method. */
+/**
+ * A command is an argument parser that can be executed by calling its
+ * run() method.
+ */
 struct Command : virtual public Args
 {
     friend class MultiCommand;
 
     virtual ~Command() { }
 
+    /**
+     * Entry point to the command
+     */
     virtual void run() = 0;
 
     typedef int Category;
@@ -221,8 +241,10 @@ struct Command : virtual public Args
 
 typedef std::map<std::string, std::function<ref<Command>()>> Commands;
 
-/* An argument parser that supports multiple subcommands,
-   i.e. ‘<command> <subcommand>’. */
+/**
+ * An argument parser that supports multiple subcommands,
+ * i.e. ‘<command> <subcommand>’.
+ */
 class MultiCommand : virtual public Args
 {
 public:
@@ -230,7 +252,9 @@ public:
 
     std::map<Command::Category, std::string> categories;
 
-    // Selected command, if any.
+    /**
+     * Selected command, if any.
+     */
     std::optional<std::pair<std::string, ref<Command>>> command;
 
     MultiCommand(const Commands & commands);
diff --git a/src/libutil/callback.hh b/src/libutil/callback.hh
index ef31794be..3710d1239 100644
--- a/src/libutil/callback.hh
+++ b/src/libutil/callback.hh
@@ -1,13 +1,16 @@
 #pragma once
+///@file
 
 #include <future>
 #include <functional>
 
 namespace nix {
 
-/* A callback is a wrapper around a lambda that accepts a valid of
-   type T or an exception. (We abuse std::future<T> to pass the value or
-   exception.) */
+/**
+ * A callback is a wrapper around a lambda that accepts a valid of
+ * type T or an exception. (We abuse std::future<T> to pass the value or
+ * exception.)
+ */
 template<typename T>
 class Callback
 {
diff --git a/src/libutil/canon-path.cc b/src/libutil/canon-path.cc
index b132b4262..ddf6db6d1 100644
--- a/src/libutil/canon-path.cc
+++ b/src/libutil/canon-path.cc
@@ -100,4 +100,30 @@ std::ostream & operator << (std::ostream & stream, const CanonPath & path)
     return stream;
 }
 
+std::string CanonPath::makeRelative(const CanonPath & path) const
+{
+    auto p1 = begin();
+    auto p2 = path.begin();
+
+    for (; p1 != end() && p2 != path.end() && *p1 == *p2; ++p1, ++p2) ;
+
+    if (p1 == end() && p2 == path.end())
+        return ".";
+    else if (p1 == end())
+        return std::string(p2.remaining);
+    else {
+        std::string res;
+        while (p1 != end()) {
+            ++p1;
+            if (!res.empty()) res += '/';
+            res += "..";
+        }
+        if (p2 != path.end()) {
+            if (!res.empty()) res += '/';
+            res += p2.remaining;
+        }
+        return res;
+    }
+}
+
 }
diff --git a/src/libutil/canon-path.hh b/src/libutil/canon-path.hh
index 9d5984584..76e48c4f2 100644
--- a/src/libutil/canon-path.hh
+++ b/src/libutil/canon-path.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <string>
 #include <optional>
@@ -8,28 +9,31 @@
 
 namespace nix {
 
-/* A canonical representation of a path. It ensures the following:
-
-   - It always starts with a slash.
-
-   - It never ends with a slash, except if the path is "/".
-
-   - A slash is never followed by a slash (i.e. no empty components).
-
-   - There are no components equal to '.' or '..'.
-
-   Note that the path does not need to correspond to an actually
-   existing path, and there is no guarantee that symlinks are
-   resolved.
-*/
+/**
+ * A canonical representation of a path. It ensures the following:
+ *
+ * - It always starts with a slash.
+ *
+ * - It never ends with a slash, except if the path is "/".
+ *
+ * - A slash is never followed by a slash (i.e. no empty components).
+ *
+ * - There are no components equal to '.' or '..'.
+ *
+ * Note that the path does not need to correspond to an actually
+ * existing path, and there is no guarantee that symlinks are
+ * resolved.
+ */
 class CanonPath
 {
     std::string path;
 
 public:
 
-    /* Construct a canon path from a non-canonical path. Any '.', '..'
-       or empty components are removed. */
+    /**
+     * Construct a canon path from a non-canonical path. Any '.', '..'
+     * or empty components are removed.
+     */
     CanonPath(std::string_view raw);
 
     explicit CanonPath(const char * raw)
@@ -44,9 +48,11 @@ public:
 
     static CanonPath root;
 
-    /* If `raw` starts with a slash, return
-       `CanonPath(raw)`. Otherwise return a `CanonPath` representing
-       `root + "/" + raw`. */
+    /**
+     * If `raw` starts with a slash, return
+     * `CanonPath(raw)`. Otherwise return a `CanonPath` representing
+     * `root + "/" + raw`.
+     */
     CanonPath(std::string_view raw, const CanonPath & root);
 
     bool isRoot() const
@@ -58,8 +64,10 @@ public:
     const std::string & abs() const
     { return path; }
 
-    /* Like abs(), but return an empty string if this path is
-       '/'. Thus the returned string never ends in a slash. */
+    /**
+     * Like abs(), but return an empty string if this path is
+     * '/'. Thus the returned string never ends in a slash.
+     */
     const std::string & absOrEmpty() const
     {
         const static std::string epsilon;
@@ -85,6 +93,9 @@ public:
         bool operator != (const Iterator & x) const
         { return remaining.data() != x.remaining.data(); }
 
+        bool operator == (const Iterator & x) const
+        { return !(*this != x); }
+
         const std::string_view operator * () const
         { return remaining.substr(0, slash); }
 
@@ -104,7 +115,9 @@ public:
 
     std::optional<CanonPath> parent() const;
 
-    /* Remove the last component. Panics if this path is the root.  */
+    /**
+     * Remove the last component. Panics if this path is the root.
+     */
     void pop();
 
     std::optional<std::string_view> dirOf() const
@@ -125,10 +138,12 @@ public:
     bool operator != (const CanonPath & x) const
     { return path != x.path; }
 
-    /* Compare paths lexicographically except that path separators
-       are sorted before any other character. That is, in the sorted order
-       a directory is always followed directly by its children. For
-       instance, 'foo' < 'foo/bar' < 'foo!'. */
+    /**
+     * Compare paths lexicographically except that path separators
+     * are sorted before any other character. That is, in the sorted order
+     * a directory is always followed directly by its children. For
+     * instance, 'foo' < 'foo/bar' < 'foo!'.
+     */
     bool operator < (const CanonPath & x) const
     {
         auto i = path.begin();
@@ -144,28 +159,42 @@ public:
         return i == path.end() && j != x.path.end();
     }
 
-    /* Return true if `this` is equal to `parent` or a child of
-       `parent`. */
+    /**
+     * Return true if `this` is equal to `parent` or a child of
+     * `parent`.
+     */
     bool isWithin(const CanonPath & parent) const;
 
     CanonPath removePrefix(const CanonPath & prefix) const;
 
-    /* Append another path to this one. */
+    /**
+     * Append another path to this one.
+     */
     void extend(const CanonPath & x);
 
-    /* Concatenate two paths. */
+    /**
+     * Concatenate two paths.
+     */
     CanonPath operator + (const CanonPath & x) const;
 
-    /* Add a path component to this one. It must not contain any slashes. */
+    /**
+     * Add a path component to this one. It must not contain any slashes.
+     */
     void push(std::string_view c);
 
     CanonPath operator + (std::string_view c) const;
 
-    /* Check whether access to this path is allowed, which is the case
-       if 1) `this` is within any of the `allowed` paths; or 2) any of
-       the `allowed` paths are within `this`. (The latter condition
-       ensures access to the parents of allowed paths.) */
+    /**
+     * Check whether access to this path is allowed, which is the case
+     * if 1) `this` is within any of the `allowed` paths; or 2) any of
+     * the `allowed` paths are within `this`. (The latter condition
+     * ensures access to the parents of allowed paths.)
+     */
     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`. */
+    std::string makeRelative(const CanonPath & path) const;
 };
 
 std::ostream & operator << (std::ostream & stream, const CanonPath & path);
diff --git a/src/libutil/cgroup.hh b/src/libutil/cgroup.hh
index d08c8ad29..574ae8e5b 100644
--- a/src/libutil/cgroup.hh
+++ b/src/libutil/cgroup.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #if __linux__
 
@@ -18,10 +19,12 @@ struct CgroupStats
     std::optional<std::chrono::microseconds> cpuUser, cpuSystem;
 };
 
-/* Destroy the cgroup denoted by 'path'. The postcondition is that
-   'path' does not exist, and thus any processes in the cgroup have
-   been killed. Also return statistics from the cgroup just before
-   destruction. */
+/**
+ * Destroy the cgroup denoted by 'path'. The postcondition is that
+ * 'path' does not exist, and thus any processes in the cgroup have
+ * been killed. Also return statistics from the cgroup just before
+ * destruction.
+ */
 CgroupStats destroyCgroup(const Path & cgroup);
 
 }
diff --git a/src/libutil/chunked-vector.hh b/src/libutil/chunked-vector.hh
index 0a4f0b400..d914e2542 100644
--- a/src/libutil/chunked-vector.hh
+++ b/src/libutil/chunked-vector.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <cstdint>
 #include <cstdlib>
@@ -7,20 +8,24 @@
 
 namespace nix {
 
-/* Provides an indexable container like vector<> with memory overhead
-   guarantees like list<> by allocating storage in chunks of ChunkSize
-   elements instead of using a contiguous memory allocation like vector<>
-   does. Not using a single vector that is resized reduces memory overhead
-   on large data sets by on average (growth factor)/2, mostly
-   eliminates copies within the vector during resizing, and provides stable
-   references to its elements. */
+/**
+ * Provides an indexable container like vector<> with memory overhead
+ * guarantees like list<> by allocating storage in chunks of ChunkSize
+ * elements instead of using a contiguous memory allocation like vector<>
+ * does. Not using a single vector that is resized reduces memory overhead
+ * on large data sets by on average (growth factor)/2, mostly
+ * eliminates copies within the vector during resizing, and provides stable
+ * references to its elements.
+ */
 template<typename T, size_t ChunkSize>
 class ChunkedVector {
 private:
     uint32_t size_ = 0;
     std::vector<std::vector<T>> chunks;
 
-    /* keep this out of the ::add hot path */
+    /**
+     * Keep this out of the ::add hot path
+     */
     [[gnu::noinline]]
     auto & addChunk()
     {
diff --git a/src/libutil/closure.hh b/src/libutil/closure.hh
index 779b9b2d5..16e3b93e4 100644
--- a/src/libutil/closure.hh
+++ b/src/libutil/closure.hh
@@ -1,3 +1,6 @@
+#pragma once
+///@file
+
 #include <set>
 #include <future>
 #include "sync.hh"
diff --git a/src/libutil/comparator.hh b/src/libutil/comparator.hh
index eecd5b819..2b5424b3d 100644
--- a/src/libutil/comparator.hh
+++ b/src/libutil/comparator.hh
@@ -1,6 +1,8 @@
 #pragma once
+///@file
 
-/* Awfull hacky generation of the comparison operators by doing a lexicographic
+/**
+ * Awful hacky generation of the comparison operators by doing a lexicographic
  * comparison between the choosen fields.
  *
  * ```
diff --git a/src/libutil/compression.hh b/src/libutil/compression.hh
index c470b82a5..3892831c2 100644
--- a/src/libutil/compression.hh
+++ b/src/libutil/compression.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "ref.hh"
 #include "types.hh"
diff --git a/src/libutil/compute-levels.hh b/src/libutil/compute-levels.hh
index 8ded295f9..093e7a915 100644
--- a/src/libutil/compute-levels.hh
+++ b/src/libutil/compute-levels.hh
@@ -1,3 +1,6 @@
+#pragma once
+///@file
+
 #include "types.hh"
 
 namespace nix {
diff --git a/src/libutil/config.hh b/src/libutil/config.hh
index 59a766034..a001056f7 100644
--- a/src/libutil/config.hh
+++ b/src/libutil/config.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <cassert>
 #include <map>
@@ -124,21 +125,21 @@ public:
     void reapplyUnknownSettings();
 };
 
-/* A class to simplify providing configuration settings. The typical
-   use is to inherit Config and add Setting<T> members:
-
-   class MyClass : private Config
-   {
-     Setting<int> foo{this, 123, "foo", "the number of foos to use"};
-     Setting<std::string> bar{this, "blabla", "bar", "the name of the bar"};
-
-     MyClass() : Config(readConfigFile("/etc/my-app.conf"))
-     {
-       std::cout << foo << "\n"; // will print 123 unless overridden
-     }
-   };
-*/
-
+/**
+ * A class to simplify providing configuration settings. The typical
+ * use is to inherit Config and add Setting<T> members:
+ *
+ * class MyClass : private Config
+ * {
+ *   Setting<int> foo{this, 123, "foo", "the number of foos to use"};
+ *   Setting<std::string> bar{this, "blabla", "bar", "the name of the bar"};
+ *
+ *   MyClass() : Config(readConfigFile("/etc/my-app.conf"))
+ *   {
+ *     std::cout << foo << "\n"; // will print 123 unless overridden
+ *   }
+ * };
+ */
 class Config : public AbstractConfig
 {
     friend class AbstractSetting;
@@ -228,7 +229,9 @@ protected:
     bool isOverridden() const { return overridden; }
 };
 
-/* A setting of type T. */
+/**
+ * A setting of type T.
+ */
 template<typename T>
 class BaseSetting : public AbstractSetting
 {
@@ -311,8 +314,10 @@ public:
     void operator =(const T & v) { this->assign(v); }
 };
 
-/* A special setting for Paths. These are automatically canonicalised
-   (e.g. "/foo//bar/" becomes "/foo/bar"). */
+/**
+ * A special setting for Paths. These are automatically canonicalised
+ * (e.g. "/foo//bar/" becomes "/foo/bar").
+ */
 class PathSetting : public BaseSetting<Path>
 {
     bool allowEmpty;
diff --git a/src/libutil/error.hh b/src/libutil/error.hh
index 0ebeaba61..eafc6a540 100644
--- a/src/libutil/error.hh
+++ b/src/libutil/error.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "suggestions.hh"
 #include "ref.hh"
@@ -54,20 +55,26 @@ typedef enum {
     lvlVomit
 } Verbosity;
 
-// the lines of code surrounding an error.
+/**
+ * The lines of code surrounding an error.
+ */
 struct LinesOfCode {
     std::optional<std::string> prevLineOfCode;
     std::optional<std::string> errLineOfCode;
     std::optional<std::string> nextLineOfCode;
 };
 
-/* An abstract type that represents a location in a source file. */
+/**
+ * An abstract type that represents a location in a source file.
+ */
 struct AbstractPos
 {
     uint32_t line = 0;
     uint32_t column = 0;
 
-    /* Return the contents of the source file. */
+    /**
+     * Return the contents of the source file.
+     */
     virtual std::optional<std::string> getSource() const
     { return std::nullopt; };
 
@@ -104,8 +111,10 @@ struct ErrorInfo {
 
 std::ostream & showErrorInfo(std::ostream & out, const ErrorInfo & einfo, bool showTrace);
 
-/* BaseError should generally not be caught, as it has Interrupted as
-   a subclass. Catch Error instead. */
+/**
+ * BaseError should generally not be caught, as it has Interrupted as
+ * a subclass. Catch Error instead.
+ */
 class BaseError : public std::exception
 {
 protected:
diff --git a/src/libutil/experimental-features.hh b/src/libutil/experimental-features.hh
index 1f1852705..7c2f872c5 100644
--- a/src/libutil/experimental-features.hh
+++ b/src/libutil/experimental-features.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "comparator.hh"
 #include "error.hh"
@@ -12,7 +13,7 @@ namespace nix {
  *
  * If you update this, don’t forget to also change the map defining their string
  * representation and documentation in the corresponding `.cc` file as well.
- **/
+ */
 enum struct ExperimentalFeature
 {
     CaDerivations,
diff --git a/src/libutil/finally.hh b/src/libutil/finally.hh
index dee2e8d2f..db654301f 100644
--- a/src/libutil/finally.hh
+++ b/src/libutil/finally.hh
@@ -1,6 +1,9 @@
 #pragma once
+///@file
 
-/* A trivial class to run a function at the end of a scope. */
+/**
+ * A trivial class to run a function at the end of a scope.
+ */
 template<typename Fn>
 class Finally
 {
diff --git a/src/libutil/fmt.hh b/src/libutil/fmt.hh
index e11426b88..727255b45 100644
--- a/src/libutil/fmt.hh
+++ b/src/libutil/fmt.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <boost/format.hpp>
 #include <string>
@@ -8,20 +9,25 @@
 namespace nix {
 
 
-/* Inherit some names from other namespaces for convenience. */
+/**
+ * Inherit some names from other namespaces for convenience.
+ */
 using boost::format;
 
 
-/* A variadic template that does nothing. Useful to call a function
-   for all variadic arguments but ignoring the result. */
+/**
+ * A variadic template that does nothing. Useful to call a function
+ * for all variadic arguments but ignoring the result.
+ */
 struct nop { template<typename... T> nop(T...) {} };
 
 
-/* A helper for formatting strings. ‘fmt(format, a_0, ..., a_n)’ is
-   equivalent to ‘boost::format(format) % a_0 % ... %
-   ... a_n’. However, ‘fmt(s)’ is equivalent to ‘s’ (so no %-expansion
-   takes place). */
-
+/**
+ * A helper for formatting strings. ‘fmt(format, a_0, ..., a_n)’ is
+ * equivalent to ‘boost::format(format) % a_0 % ... %
+ * ... a_n’. However, ‘fmt(s)’ is equivalent to ‘s’ (so no %-expansion
+ * takes place).
+ */
 template<class F>
 inline void formatHelper(F & f)
 {
diff --git a/src/libutil/git.hh b/src/libutil/git.hh
index cb13ef0e5..bf2b9a286 100644
--- a/src/libutil/git.hh
+++ b/src/libutil/git.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <string>
 #include <string_view>
@@ -8,21 +9,23 @@ namespace nix {
 
 namespace git {
 
-// A line from the output of `git ls-remote --symref`.
-//
-// These can be of two kinds:
-//
-// - Symbolic references of the form
-//
-//      ref: {target}	{reference}
-//
-//    where {target} is itself a reference and {reference} is optional
-//
-// - Object references of the form
-//
-//      {target}	{reference}
-//
-//    where {target} is a commit id and {reference} is mandatory
+/**
+ * A line from the output of `git ls-remote --symref`.
+ *
+ * These can be of two kinds:
+ *
+ * - Symbolic references of the form
+ *
+ *      ref: {target}	{reference}
+ *
+ *    where {target} is itself a reference and {reference} is optional
+ *
+ * - Object references of the form
+ *
+ *      {target}	{reference}
+ *
+ *    where {target} is a commit id and {reference} is mandatory
+ */
 struct LsRemoteRefLine {
     enum struct Kind {
         Symbolic,
diff --git a/src/libutil/hash.cc b/src/libutil/hash.cc
index d2fd0c15a..5735e4715 100644
--- a/src/libutil/hash.cc
+++ b/src/libutil/hash.cc
@@ -71,12 +71,13 @@ const std::string base16Chars = "0123456789abcdef";
 
 static std::string printHash16(const Hash & hash)
 {
-    char buf[hash.hashSize * 2];
+    std::string buf;
+    buf.reserve(hash.hashSize * 2);
     for (unsigned int i = 0; i < hash.hashSize; i++) {
-        buf[i * 2] = base16Chars[hash.hash[i] >> 4];
-        buf[i * 2 + 1] = base16Chars[hash.hash[i] & 0x0f];
+        buf.push_back(base16Chars[hash.hash[i] >> 4]);
+        buf.push_back(base16Chars[hash.hash[i] & 0x0f]);
     }
-    return std::string(buf, hash.hashSize * 2);
+    return buf;
 }
 
 
@@ -130,7 +131,7 @@ std::string Hash::to_string(Base base, bool includeType) const
         break;
     case Base64:
     case SRI:
-        s += base64Encode(std::string((const char *) hash, hashSize));
+        s += base64Encode(std::string_view((const char *) hash, hashSize));
         break;
     }
     return s;
@@ -403,7 +404,7 @@ HashType parseHashType(std::string_view s)
         throw UsageError("unknown hash algorithm '%1%'", s);
 }
 
-std::string printHashType(HashType ht)
+std::string_view printHashType(HashType ht)
 {
     switch (ht) {
     case htMD5: return "md5";
diff --git a/src/libutil/hash.hh b/src/libutil/hash.hh
index 00f70a572..be1fdba2a 100644
--- a/src/libutil/hash.hh
+++ b/src/libutil/hash.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "types.hh"
 #include "serialise.hh"
@@ -33,62 +34,86 @@ struct Hash
 
     HashType type;
 
-    /* Create a zero-filled hash object. */
+    /**
+     * Create a zero-filled hash object.
+     */
     Hash(HashType type);
 
-    /* Parse the hash from a string representation in the format
-       "[<type>:]<base16|base32|base64>" or "<type>-<base64>" (a
-       Subresource Integrity hash expression). If the 'type' argument
-       is not present, then the hash type must be specified in the
-       string. */
+    /**
+     * Parse the hash from a string representation in the format
+     * "[<type>:]<base16|base32|base64>" or "<type>-<base64>" (a
+     * Subresource Integrity hash expression). If the 'type' argument
+     * is not present, then the hash type must be specified in the
+     * string.
+     */
     static Hash parseAny(std::string_view s, std::optional<HashType> type);
 
-    /* Parse a hash from a string representation like the above, except the
-       type prefix is mandatory is there is no separate arguement. */
+    /**
+     * Parse a hash from a string representation like the above, except the
+     * type prefix is mandatory is there is no separate arguement.
+     */
     static Hash parseAnyPrefixed(std::string_view s);
 
-    /* Parse a plain hash that musst not have any prefix indicating the type.
-       The type is passed in to disambiguate. */
+    /**
+     * Parse a plain hash that musst not have any prefix indicating the type.
+     * The type is passed in to disambiguate.
+     */
     static Hash parseNonSRIUnprefixed(std::string_view s, HashType type);
 
     static Hash parseSRI(std::string_view original);
 
 private:
-    /* The type must be provided, the string view must not include <type>
-       prefix. `isSRI` helps disambigate the various base-* encodings. */
+    /**
+     * The type must be provided, the string view must not include <type>
+     * prefix. `isSRI` helps disambigate the various base-* encodings.
+     */
     Hash(std::string_view s, HashType type, bool isSRI);
 
 public:
-    /* Check whether two hash are equal. */
+    /**
+     * Check whether two hash are equal.
+     */
     bool operator == (const Hash & h2) const;
 
-    /* Check whether two hash are not equal. */
+    /**
+     * Check whether two hash are not equal.
+     */
     bool operator != (const Hash & h2) const;
 
-    /* For sorting. */
+    /**
+     * For sorting.
+     */
     bool operator < (const Hash & h) const;
 
-    /* Returns the length of a base-16 representation of this hash. */
+    /**
+     * Returns the length of a base-16 representation of this hash.
+     */
     size_t base16Len() const
     {
         return hashSize * 2;
     }
 
-    /* Returns the length of a base-32 representation of this hash. */
+    /**
+     * Returns the length of a base-32 representation of this hash.
+     */
     size_t base32Len() const
     {
         return (hashSize * 8 - 1) / 5 + 1;
     }
 
-    /* Returns the length of a base-64 representation of this hash. */
+    /**
+     * Returns the length of a base-64 representation of this hash.
+     */
     size_t base64Len() const
     {
         return ((4 * hashSize / 3) + 3) & ~3;
     }
 
-    /* Return a string representation of the hash, in base-16, base-32
-       or base-64. By default, this is prefixed by the hash type
-       (e.g. "sha256:"). */
+    /**
+     * Return a string representation of the hash, in base-16, base-32
+     * or base-64. By default, this is prefixed by the hash type
+     * (e.g. "sha256:").
+     */
     std::string to_string(Base base, bool includeType) const;
 
     std::string gitRev() const
@@ -104,36 +129,54 @@ public:
     static Hash dummy;
 };
 
-/* Helper that defaults empty hashes to the 0 hash. */
+/**
+ * Helper that defaults empty hashes to the 0 hash.
+ */
 Hash newHashAllowEmpty(std::string_view hashStr, std::optional<HashType> ht);
 
-/* Print a hash in base-16 if it's MD5, or base-32 otherwise. */
+/**
+ * Print a hash in base-16 if it's MD5, or base-32 otherwise.
+ */
 std::string printHash16or32(const Hash & hash);
 
-/* Compute the hash of the given string. */
+/**
+ * Compute the hash of the given string.
+ */
 Hash hashString(HashType ht, std::string_view s);
 
-/* Compute the hash of the given file. */
+/**
+ * Compute the hash of the given file.
+ */
 Hash hashFile(HashType ht, const Path & path);
 
-/* Compute the hash of the given path.  The hash is defined as
-   (essentially) hashString(ht, dumpPath(path)). */
+/**
+ * Compute the hash of the given path.  The hash is defined as
+ * (essentially) hashString(ht, dumpPath(path)).
+ */
 typedef std::pair<Hash, uint64_t> HashResult;
 HashResult hashPath(HashType ht, const Path & path,
     PathFilter & filter = defaultPathFilter);
 
-/* Compress a hash to the specified number of bytes by cyclically
-   XORing bytes together. */
+/**
+ * Compress a hash to the specified number of bytes by cyclically
+ * XORing bytes together.
+ */
 Hash compressHash(const Hash & hash, unsigned int newSize);
 
-/* Parse a string representing a hash type. */
+/**
+ * Parse a string representing a hash type.
+ */
 HashType parseHashType(std::string_view s);
 
-/* Will return nothing on parse error */
+/**
+ * Will return nothing on parse error
+ */
 std::optional<HashType> parseHashTypeOpt(std::string_view s);
 
-/* And the reverse. */
-std::string printHashType(HashType ht);
+/**
+ * And the reverse.
+ */
+std::string_view printHashType(HashType ht);
 
 
 union Ctx;
diff --git a/src/libutil/hilite.hh b/src/libutil/hilite.hh
index f8bdbfc55..2d5cf7c6f 100644
--- a/src/libutil/hilite.hh
+++ b/src/libutil/hilite.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <regex>
 #include <vector>
@@ -6,11 +7,13 @@
 
 namespace nix {
 
-/* Highlight all the given matches in the given string `s` by wrapping
-   them between `prefix` and `postfix`.
-
-   If some matches overlap, then their union will be wrapped rather
-   than the individual matches. */
+/**
+ * Highlight all the given matches in the given string `s` by wrapping
+ * them between `prefix` and `postfix`.
+ *
+ * If some matches overlap, then their union will be wrapped rather
+ * than the individual matches.
+ */
 std::string hiliteMatches(
     std::string_view s,
     std::vector<std::smatch> matches,
diff --git a/src/libutil/json-impls.hh b/src/libutil/json-impls.hh
index bd75748ad..b26163a04 100644
--- a/src/libutil/json-impls.hh
+++ b/src/libutil/json-impls.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "nlohmann/json_fwd.hpp"
 
diff --git a/src/libutil/json-utils.hh b/src/libutil/json-utils.hh
index b8a031227..eb00e954f 100644
--- a/src/libutil/json-utils.hh
+++ b/src/libutil/json-utils.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <nlohmann/json.hpp>
 
diff --git a/src/libutil/logging.hh b/src/libutil/logging.hh
index 59a707eef..576068c22 100644
--- a/src/libutil/logging.hh
+++ b/src/libutil/logging.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "types.hh"
 #include "error.hh"
@@ -72,6 +73,9 @@ public:
 
     virtual void stop() { };
 
+    virtual void pause() { };
+    virtual void resume() { };
+
     // Whether the logger prints the whole build log
     virtual bool isVerbose() { return false; }
 
@@ -214,7 +218,9 @@ extern Verbosity verbosity; /* suppress msgs > this */
 #define debug(args...) printMsg(lvlDebug, args)
 #define vomit(args...) printMsg(lvlVomit, args)
 
-/* if verbosity >= lvlWarn, print a message with a yellow 'warning:' prefix. */
+/**
+ * if verbosity >= lvlWarn, print a message with a yellow 'warning:' prefix.
+ */
 template<typename... Args>
 inline void warn(const std::string & fs, const Args & ... args)
 {
diff --git a/src/libutil/lru-cache.hh b/src/libutil/lru-cache.hh
index 6ef4a3e06..0e19517ed 100644
--- a/src/libutil/lru-cache.hh
+++ b/src/libutil/lru-cache.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <cassert>
 #include <map>
@@ -7,7 +8,9 @@
 
 namespace nix {
 
-/* A simple least-recently used cache. Not thread-safe. */
+/**
+ * A simple least-recently used cache. Not thread-safe.
+ */
 template<typename Key, typename Value>
 class LRUCache
 {
@@ -31,7 +34,9 @@ public:
 
     LRUCache(size_t capacity) : capacity(capacity) { }
 
-    /* Insert or upsert an item in the cache. */
+    /**
+     * Insert or upsert an item in the cache.
+     */
     void upsert(const Key & key, const Value & value)
     {
         if (capacity == 0) return;
@@ -39,7 +44,9 @@ public:
         erase(key);
 
         if (data.size() >= capacity) {
-            /* Retire the oldest item. */
+            /**
+             * Retire the oldest item.
+             */
             auto oldest = lru.begin();
             data.erase(*oldest);
             lru.erase(oldest);
@@ -63,14 +70,18 @@ public:
         return true;
     }
 
-    /* Look up an item in the cache. If it exists, it becomes the most
-       recently used item. */
+    /**
+     * Look up an item in the cache. If it exists, it becomes the most
+     * recently used item.
+     * */
     std::optional<Value> get(const Key & key)
     {
         auto i = data.find(key);
         if (i == data.end()) return {};
 
-        /* Move this item to the back of the LRU list. */
+        /**
+         * Move this item to the back of the LRU list.
+         */
         lru.erase(i->second.first.it);
         auto j = lru.insert(lru.end(), i);
         i->second.first.it = j;
diff --git a/src/libutil/monitor-fd.hh b/src/libutil/monitor-fd.hh
index 9518cf8aa..86d0115fc 100644
--- a/src/libutil/monitor-fd.hh
+++ b/src/libutil/monitor-fd.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <thread>
 #include <atomic>
diff --git a/src/libutil/namespaces.hh b/src/libutil/namespaces.hh
index e82379b9c..0b7eeb66c 100644
--- a/src/libutil/namespaces.hh
+++ b/src/libutil/namespaces.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 namespace nix {
 
diff --git a/src/libutil/pool.hh b/src/libutil/pool.hh
index d49067bb9..6247b6125 100644
--- a/src/libutil/pool.hh
+++ b/src/libutil/pool.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <functional>
 #include <limits>
@@ -11,33 +12,37 @@
 
 namespace nix {
 
-/* This template class implements a simple pool manager of resources
-   of some type R, such as database connections. It is used as
-   follows:
-
-     class Connection { ... };
-
-     Pool<Connection> pool;
-
-     {
-       auto conn(pool.get());
-       conn->exec("select ...");
-     }
-
-   Here, the Connection object referenced by ‘conn’ is automatically
-   returned to the pool when ‘conn’ goes out of scope.
-*/
-
+/**
+ * This template class implements a simple pool manager of resources
+ * of some type R, such as database connections. It is used as
+ * follows:
+ *
+ *   class Connection { ... };
+ *
+ *   Pool<Connection> pool;
+ *
+ *   {
+ *     auto conn(pool.get());
+ *     conn->exec("select ...");
+ *   }
+ *
+ * Here, the Connection object referenced by ‘conn’ is automatically
+ * returned to the pool when ‘conn’ goes out of scope.
+ */
 template <class R>
 class Pool
 {
 public:
 
-    /* A function that produces new instances of R on demand. */
+    /**
+     * A function that produces new instances of R on demand.
+     */
     typedef std::function<ref<R>()> Factory;
 
-    /* A function that checks whether an instance of R is still
-       usable. Unusable instances are removed from the pool. */
+    /**
+     * A function that checks whether an instance of R is still
+     * usable. Unusable instances are removed from the pool.
+     */
     typedef std::function<bool(const ref<R> &)> Validator;
 
 private:
diff --git a/src/libutil/ref.hh b/src/libutil/ref.hh
index 7d38b059c..af5f8304c 100644
--- a/src/libutil/ref.hh
+++ b/src/libutil/ref.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <memory>
 #include <exception>
@@ -6,8 +7,10 @@
 
 namespace nix {
 
-/* A simple non-nullable reference-counted pointer. Actually a wrapper
-   around std::shared_ptr that prevents null constructions. */
+/**
+ * A simple non-nullable reference-counted pointer. Actually a wrapper
+ * around std::shared_ptr that prevents null constructions.
+ */
 template<typename T>
 class ref
 {
diff --git a/src/libutil/regex-combinators.hh b/src/libutil/regex-combinators.hh
index 0b997b25a..87d6aa678 100644
--- a/src/libutil/regex-combinators.hh
+++ b/src/libutil/regex-combinators.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <string_view>
 
diff --git a/src/libutil/serialise.hh b/src/libutil/serialise.hh
index 7da5b07fd..2cf527023 100644
--- a/src/libutil/serialise.hh
+++ b/src/libutil/serialise.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <memory>
 
@@ -10,7 +11,9 @@ namespace boost::context { struct stack_context; }
 namespace nix {
 
 
-/* Abstract destination of binary data. */
+/**
+ * Abstract destination of binary data.
+ */
 struct Sink
 {
     virtual ~Sink() { }
@@ -18,7 +21,9 @@ struct Sink
     virtual bool good() { return true; }
 };
 
-/* Just throws away data. */
+/**
+ * Just throws away data.
+ */
 struct NullSink : Sink
 {
     void operator () (std::string_view data) override
@@ -32,8 +37,10 @@ struct FinishSink : virtual Sink
 };
 
 
-/* A buffered abstract sink. Warning: a BufferedSink should not be
-   used from multiple threads concurrently. */
+/**
+ * A buffered abstract sink. Warning: a BufferedSink should not be
+ * used from multiple threads concurrently.
+ */
 struct BufferedSink : virtual Sink
 {
     size_t bufSize, bufPos;
@@ -50,19 +57,25 @@ struct BufferedSink : virtual Sink
 };
 
 
-/* Abstract source of binary data. */
+/**
+ * Abstract source of binary data.
+ */
 struct Source
 {
     virtual ~Source() { }
 
-    /* Store exactly ‘len’ bytes in the buffer pointed to by ‘data’.
-       It blocks until all the requested data is available, or throws
-       an error if it is not going to be available.   */
+    /**
+     * Store exactly ‘len’ bytes in the buffer pointed to by ‘data’.
+     * It blocks until all the requested data is available, or throws
+     * an error if it is not going to be available.
+     */
     void operator () (char * data, size_t len);
 
-    /* Store up to ‘len’ in the buffer pointed to by ‘data’, and
-       return the number of bytes stored.  It blocks until at least
-       one byte is available. */
+    /**
+     * Store up to ‘len’ in the buffer pointed to by ‘data’, and
+     * return the number of bytes stored.  It blocks until at least
+     * one byte is available.
+     */
     virtual size_t read(char * data, size_t len) = 0;
 
     virtual bool good() { return true; }
@@ -73,8 +86,10 @@ struct Source
 };
 
 
-/* A buffered abstract source. Warning: a BufferedSource should not be
-   used from multiple threads concurrently. */
+/**
+ * A buffered abstract source. Warning: a BufferedSource should not be
+ * used from multiple threads concurrently.
+ */
 struct BufferedSource : Source
 {
     size_t bufSize, bufPosIn, bufPosOut;
@@ -88,12 +103,16 @@ struct BufferedSource : Source
     bool hasData();
 
 protected:
-    /* Underlying read call, to be overridden. */
+    /**
+     * Underlying read call, to be overridden.
+     */
     virtual size_t readUnbuffered(char * data, size_t len) = 0;
 };
 
 
-/* A sink that writes data to a file descriptor. */
+/**
+ * A sink that writes data to a file descriptor.
+ */
 struct FdSink : BufferedSink
 {
     int fd;
@@ -123,7 +142,9 @@ private:
 };
 
 
-/* A source that reads data from a file descriptor. */
+/**
+ * A source that reads data from a file descriptor.
+ */
 struct FdSource : BufferedSource
 {
     int fd;
@@ -149,7 +170,9 @@ private:
 };
 
 
-/* A sink that writes data to a string. */
+/**
+ * A sink that writes data to a string.
+ */
 struct StringSink : Sink
 {
     std::string s;
@@ -163,7 +186,9 @@ struct StringSink : Sink
 };
 
 
-/* A source that reads data from a string. */
+/**
+ * A source that reads data from a string.
+ */
 struct StringSource : Source
 {
     std::string_view s;
@@ -173,7 +198,9 @@ struct StringSource : Source
 };
 
 
-/* A sink that writes all incoming data to two other sinks. */
+/**
+ * A sink that writes all incoming data to two other sinks.
+ */
 struct TeeSink : Sink
 {
     Sink & sink1, & sink2;
@@ -186,7 +213,9 @@ struct TeeSink : Sink
 };
 
 
-/* Adapter class of a Source that saves all data read to a sink. */
+/**
+ * Adapter class of a Source that saves all data read to a sink.
+ */
 struct TeeSource : Source
 {
     Source & orig;
@@ -201,7 +230,9 @@ struct TeeSource : Source
     }
 };
 
-/* A reader that consumes the original Source until 'size'. */
+/**
+ * A reader that consumes the original Source until 'size'.
+ */
 struct SizedSource : Source
 {
     Source & orig;
@@ -219,7 +250,9 @@ struct SizedSource : Source
         return n;
     }
 
-    /* Consume the original source until no remain data is left to consume. */
+    /**
+     * Consume the original source until no remain data is left to consume.
+     */
     size_t drainAll()
     {
         std::vector<char> buf(8192);
@@ -232,7 +265,9 @@ struct SizedSource : Source
     }
 };
 
-/* A sink that that just counts the number of bytes given to it */
+/**
+ * A sink that that just counts the number of bytes given to it
+ */
 struct LengthSink : Sink
 {
     uint64_t length = 0;
@@ -243,7 +278,9 @@ struct LengthSink : Sink
     }
 };
 
-/* Convert a function into a sink. */
+/**
+ * Convert a function into a sink.
+ */
 struct LambdaSink : Sink
 {
     typedef std::function<void(std::string_view data)> lambda_t;
@@ -259,7 +296,9 @@ struct LambdaSink : Sink
 };
 
 
-/* Convert a function into a source. */
+/**
+ * Convert a function into a source.
+ */
 struct LambdaSource : Source
 {
     typedef std::function<size_t(char *, size_t)> lambda_t;
@@ -274,8 +313,10 @@ struct LambdaSource : Source
     }
 };
 
-/* Chain two sources together so after the first is exhausted, the second is
-   used */
+/**
+ * Chain two sources together so after the first is exhausted, the second is
+ * used
+ */
 struct ChainSource : Source
 {
     Source & source1, & source2;
@@ -289,8 +330,10 @@ struct ChainSource : Source
 
 std::unique_ptr<FinishSink> sourceToSink(std::function<void(Source &)> fun);
 
-/* Convert a function that feeds data into a Sink into a Source. The
-   Source executes the function as a coroutine. */
+/**
+ * Convert a function that feeds data into a Sink into a Source. The
+ * Source executes the function as a coroutine.
+ */
 std::unique_ptr<Source> sinkToSource(
     std::function<void(Sink &)> fun,
     std::function<void()> eof = []() {
@@ -376,7 +419,9 @@ Source & operator >> (Source & in, bool & b)
 Error readError(Source & source);
 
 
-/* An adapter that converts a std::basic_istream into a source. */
+/**
+ * An adapter that converts a std::basic_istream into a source.
+ */
 struct StreamToSourceAdapter : Source
 {
     std::shared_ptr<std::basic_istream<char>> istream;
@@ -399,13 +444,14 @@ struct StreamToSourceAdapter : Source
 };
 
 
-/* A source that reads a distinct format of concatenated chunks back into its
-   logical form, in order to guarantee a known state to the original stream,
-   even in the event of errors.
-
-   Use with FramedSink, which also allows the logical stream to be terminated
-   in the event of an exception.
-*/
+/**
+ * A source that reads a distinct format of concatenated chunks back into its
+ * logical form, in order to guarantee a known state to the original stream,
+ * even in the event of errors.
+ *
+ * Use with FramedSink, which also allows the logical stream to be terminated
+ * in the event of an exception.
+ */
 struct FramedSource : Source
 {
     Source & from;
@@ -450,11 +496,12 @@ struct FramedSource : Source
     }
 };
 
-/* Write as chunks in the format expected by FramedSource.
-
-   The exception_ptr reference can be used to terminate the stream when you
-   detect that an error has occurred on the remote end.
-*/
+/**
+ * Write as chunks in the format expected by FramedSource.
+ *
+ * The exception_ptr reference can be used to terminate the stream when you
+ * detect that an error has occurred on the remote end.
+ */
 struct FramedSink : nix::BufferedSink
 {
     BufferedSink & to;
@@ -487,17 +534,20 @@ struct FramedSink : nix::BufferedSink
     };
 };
 
-/* Stack allocation strategy for sinkToSource.
-   Mutable to avoid a boehm gc dependency in libutil.
-
-   boost::context doesn't provide a virtual class, so we define our own.
+/**
+ * Stack allocation strategy for sinkToSource.
+ * Mutable to avoid a boehm gc dependency in libutil.
+ *
+ * boost::context doesn't provide a virtual class, so we define our own.
  */
 struct StackAllocator {
     virtual boost::context::stack_context allocate() = 0;
     virtual void deallocate(boost::context::stack_context sctx) = 0;
 
-    /* The stack allocator to use in sinkToSource and potentially elsewhere.
-       It is reassigned by the initGC() method in libexpr. */
+    /**
+     * The stack allocator to use in sinkToSource and potentially elsewhere.
+     * It is reassigned by the initGC() method in libexpr.
+     */
     static StackAllocator *defaultAllocator;
 };
 
diff --git a/src/libutil/split.hh b/src/libutil/split.hh
index 87a23b13e..3b9b2b83b 100644
--- a/src/libutil/split.hh
+++ b/src/libutil/split.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <optional>
 #include <string_view>
@@ -7,10 +8,12 @@
 
 namespace nix {
 
-// If `separator` is found, we return the portion of the string before the
-// separator, and modify the string argument to contain only the part after the
-// separator. Otherwise, we return `std::nullopt`, and we leave the argument
-// string alone.
+/**
+ * If `separator` is found, we return the portion of the string before the
+ * separator, and modify the string argument to contain only the part after the
+ * separator. Otherwise, we return `std::nullopt`, and we leave the argument
+ * string alone.
+ */
 static inline std::optional<std::string_view> splitPrefixTo(std::string_view & string, char separator) {
     auto sepInstance = string.find(separator);
 
diff --git a/src/libutil/suggestions.hh b/src/libutil/suggestions.hh
index d54dd8e31..9abf5ee5f 100644
--- a/src/libutil/suggestions.hh
+++ b/src/libutil/suggestions.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "comparator.hh"
 #include "types.hh"
@@ -13,7 +14,8 @@ int levenshteinDistance(std::string_view first, std::string_view second);
  */
 class Suggestion {
 public:
-    int distance; // The smaller the better
+    /// The smaller the better
+    int distance;
     std::string suggestion;
 
     std::string to_string() const;
@@ -43,7 +45,9 @@ public:
 std::ostream & operator<<(std::ostream & str, const Suggestion &);
 std::ostream & operator<<(std::ostream & str, const Suggestions &);
 
-// Either a value of type `T`, or some suggestions
+/**
+ * Either a value of type `T`, or some suggestions
+ */
 template<typename T>
 class OrSuggestions {
 public:
diff --git a/src/libutil/sync.hh b/src/libutil/sync.hh
index e1d591d77..47e4512b1 100644
--- a/src/libutil/sync.hh
+++ b/src/libutil/sync.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <cstdlib>
 #include <mutex>
@@ -7,22 +8,22 @@
 
 namespace nix {
 
-/* This template class ensures synchronized access to a value of type
-   T. It is used as follows:
-
-     struct Data { int x; ... };
-
-     Sync<Data> data;
-
-     {
-       auto data_(data.lock());
-       data_->x = 123;
-     }
-
-   Here, "data" is automatically unlocked when "data_" goes out of
-   scope.
-*/
-
+/**
+ * This template class ensures synchronized access to a value of type
+ * T. It is used as follows:
+ *
+ *   struct Data { int x; ... };
+ *
+ *   Sync<Data> data;
+ *
+ *   {
+ *     auto data_(data.lock());
+ *     data_->x = 123;
+ *   }
+ *
+ * Here, "data" is automatically unlocked when "data_" goes out of
+ * scope.
+ */
 template<class T, class M = std::mutex>
 class Sync
 {
diff --git a/src/libutil/tarfile.hh b/src/libutil/tarfile.hh
index 4d9141fd4..24afb710a 100644
--- a/src/libutil/tarfile.hh
+++ b/src/libutil/tarfile.hh
@@ -1,3 +1,6 @@
+#pragma once
+///@file
+
 #include "serialise.hh"
 #include <archive.h>
 
@@ -14,7 +17,7 @@ struct TarArchive {
 
     TarArchive(const Path & path);
 
-    // disable copy constructor
+    /// disable copy constructor
     TarArchive(const TarArchive &) = delete;
 
     void close();
diff --git a/src/libutil/tests/canon-path.cc b/src/libutil/tests/canon-path.cc
index c1c5adadf..fc94ccc3d 100644
--- a/src/libutil/tests/canon-path.cc
+++ b/src/libutil/tests/canon-path.cc
@@ -107,15 +107,13 @@ namespace nix {
     }
 
     TEST(CanonPath, within) {
-        {
-            ASSERT_TRUE(CanonPath("foo").isWithin(CanonPath("foo")));
-            ASSERT_FALSE(CanonPath("foo").isWithin(CanonPath("bar")));
-            ASSERT_FALSE(CanonPath("foo").isWithin(CanonPath("fo")));
-            ASSERT_TRUE(CanonPath("foo/bar").isWithin(CanonPath("foo")));
-            ASSERT_FALSE(CanonPath("foo").isWithin(CanonPath("foo/bar")));
-            ASSERT_TRUE(CanonPath("/foo/bar/default.nix").isWithin(CanonPath("/")));
-            ASSERT_TRUE(CanonPath("/").isWithin(CanonPath("/")));
-        }
+        ASSERT_TRUE(CanonPath("foo").isWithin(CanonPath("foo")));
+        ASSERT_FALSE(CanonPath("foo").isWithin(CanonPath("bar")));
+        ASSERT_FALSE(CanonPath("foo").isWithin(CanonPath("fo")));
+        ASSERT_TRUE(CanonPath("foo/bar").isWithin(CanonPath("foo")));
+        ASSERT_FALSE(CanonPath("foo").isWithin(CanonPath("foo/bar")));
+        ASSERT_TRUE(CanonPath("/foo/bar/default.nix").isWithin(CanonPath("/")));
+        ASSERT_TRUE(CanonPath("/").isWithin(CanonPath("/")));
     }
 
     TEST(CanonPath, sort) {
@@ -127,29 +125,38 @@ namespace nix {
     }
 
     TEST(CanonPath, allowed) {
-        {
-            std::set<CanonPath> allowed {
-                CanonPath("foo/bar"),
-                CanonPath("foo!"),
-                CanonPath("xyzzy"),
-                CanonPath("a/b/c"),
-            };
-
-            ASSERT_TRUE (CanonPath("foo/bar").isAllowed(allowed));
-            ASSERT_TRUE (CanonPath("foo/bar/bla").isAllowed(allowed));
-            ASSERT_TRUE (CanonPath("foo").isAllowed(allowed));
-            ASSERT_FALSE(CanonPath("bar").isAllowed(allowed));
-            ASSERT_FALSE(CanonPath("bar/a").isAllowed(allowed));
-            ASSERT_TRUE (CanonPath("a").isAllowed(allowed));
-            ASSERT_TRUE (CanonPath("a/b").isAllowed(allowed));
-            ASSERT_TRUE (CanonPath("a/b/c").isAllowed(allowed));
-            ASSERT_TRUE (CanonPath("a/b/c/d").isAllowed(allowed));
-            ASSERT_TRUE (CanonPath("a/b/c/d/e").isAllowed(allowed));
-            ASSERT_FALSE(CanonPath("a/b/a").isAllowed(allowed));
-            ASSERT_FALSE(CanonPath("a/b/d").isAllowed(allowed));
-            ASSERT_FALSE(CanonPath("aaa").isAllowed(allowed));
-            ASSERT_FALSE(CanonPath("zzz").isAllowed(allowed));
-            ASSERT_TRUE (CanonPath("/").isAllowed(allowed));
-        }
+        std::set<CanonPath> allowed {
+            CanonPath("foo/bar"),
+            CanonPath("foo!"),
+            CanonPath("xyzzy"),
+            CanonPath("a/b/c"),
+        };
+
+        ASSERT_TRUE (CanonPath("foo/bar").isAllowed(allowed));
+        ASSERT_TRUE (CanonPath("foo/bar/bla").isAllowed(allowed));
+        ASSERT_TRUE (CanonPath("foo").isAllowed(allowed));
+        ASSERT_FALSE(CanonPath("bar").isAllowed(allowed));
+        ASSERT_FALSE(CanonPath("bar/a").isAllowed(allowed));
+        ASSERT_TRUE (CanonPath("a").isAllowed(allowed));
+        ASSERT_TRUE (CanonPath("a/b").isAllowed(allowed));
+        ASSERT_TRUE (CanonPath("a/b/c").isAllowed(allowed));
+        ASSERT_TRUE (CanonPath("a/b/c/d").isAllowed(allowed));
+        ASSERT_TRUE (CanonPath("a/b/c/d/e").isAllowed(allowed));
+        ASSERT_FALSE(CanonPath("a/b/a").isAllowed(allowed));
+        ASSERT_FALSE(CanonPath("a/b/d").isAllowed(allowed));
+        ASSERT_FALSE(CanonPath("aaa").isAllowed(allowed));
+        ASSERT_FALSE(CanonPath("zzz").isAllowed(allowed));
+        ASSERT_TRUE (CanonPath("/").isAllowed(allowed));
+    }
+
+    TEST(CanonPath, makeRelative) {
+        CanonPath d("/foo/bar");
+        ASSERT_EQ(d.makeRelative(CanonPath("/foo/bar")), ".");
+        ASSERT_EQ(d.makeRelative(CanonPath("/foo")), "..");
+        ASSERT_EQ(d.makeRelative(CanonPath("/")), "../..");
+        ASSERT_EQ(d.makeRelative(CanonPath("/foo/bar/xyzzy")), "xyzzy");
+        ASSERT_EQ(d.makeRelative(CanonPath("/foo/bar/xyzzy/bla")), "xyzzy/bla");
+        ASSERT_EQ(d.makeRelative(CanonPath("/foo/xyzzy/bla")), "../xyzzy/bla");
+        ASSERT_EQ(d.makeRelative(CanonPath("/xyzzy/bla")), "../../xyzzy/bla");
     }
 }
diff --git a/src/libutil/tests/hash.hh b/src/libutil/tests/hash.hh
index 9e9650e6e..1f9fa59ae 100644
--- a/src/libutil/tests/hash.hh
+++ b/src/libutil/tests/hash.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <rapidcheck/gen/Arbitrary.h>
 
diff --git a/src/libutil/thread-pool.hh b/src/libutil/thread-pool.hh
index b22e0d162..14b32279c 100644
--- a/src/libutil/thread-pool.hh
+++ b/src/libutil/thread-pool.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "sync.hh"
 #include "util.hh"
@@ -13,8 +14,10 @@ namespace nix {
 
 MakeError(ThreadPoolShutDown, Error);
 
-/* A simple thread pool that executes a queue of work items
-   (lambdas). */
+/**
+ * A simple thread pool that executes a queue of work items
+ * (lambdas).
+ */
 class ThreadPool
 {
 public:
@@ -23,19 +26,30 @@ public:
 
     ~ThreadPool();
 
-    // FIXME: use std::packaged_task?
+    /**
+     * An individual work item.
+     *
+     * \todo use std::packaged_task?
+     */
     typedef std::function<void()> work_t;
 
-    /* Enqueue a function to be executed by the thread pool. */
+    /**
+     * Enqueue a function to be executed by the thread pool.
+     */
     void enqueue(const work_t & t);
 
-    /* Execute work items until the queue is empty. Note that work
-       items are allowed to add new items to the queue; this is
-       handled correctly. Queue processing stops prematurely if any
-       work item throws an exception. This exception is propagated to
-       the calling thread. If multiple work items throw an exception
-       concurrently, only one item is propagated; the others are
-       printed on stderr and otherwise ignored. */
+    /**
+     * Execute work items until the queue is empty.
+     * 
+	 * \note Note that work items are allowed to add new items to the
+	 * queue; this is handled correctly.
+     *
+	 * Queue processing stops prematurely if any work item throws an
+	 * exception. This exception is propagated to the calling thread. If
+	 * multiple work items throw an exception concurrently, only one
+	 * item is propagated; the others are printed on stderr and
+	 * otherwise ignored.
+     */
     void process();
 
 private:
@@ -62,9 +76,11 @@ private:
     void shutdown();
 };
 
-/* Process in parallel a set of items of type T that have a partial
-   ordering between them. Thus, any item is only processed after all
-   its dependencies have been processed. */
+/**
+ * Process in parallel a set of items of type T that have a partial
+ * ordering between them. Thus, any item is only processed after all
+ * its dependencies have been processed.
+ */
 template<typename T>
 void processGraph(
     ThreadPool & pool,
diff --git a/src/libutil/topo-sort.hh b/src/libutil/topo-sort.hh
index 7418be5e0..a52811fbf 100644
--- a/src/libutil/topo-sort.hh
+++ b/src/libutil/topo-sort.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "error.hh"
 
diff --git a/src/libutil/types.hh b/src/libutil/types.hh
index 6bcbd7e1d..c86f52175 100644
--- a/src/libutil/types.hh
+++ b/src/libutil/types.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "ref.hh"
 
@@ -17,7 +18,9 @@ typedef std::set<std::string> StringSet;
 typedef std::map<std::string, std::string> StringMap;
 typedef std::map<std::string, std::string> StringPairs;
 
-/* Paths are just strings. */
+/**
+ * Paths are just strings.
+ */
 typedef std::string Path;
 typedef std::string_view PathView;
 typedef std::list<Path> Paths;
@@ -25,15 +28,19 @@ typedef std::set<Path> PathSet;
 
 typedef std::vector<std::pair<std::string, std::string>> Headers;
 
-/* Helper class to run code at startup. */
+/**
+ * Helper class to run code at startup.
+ */
 template<typename T>
 struct OnStartup
 {
     OnStartup(T && t) { t(); }
 };
 
-/* Wrap bools to prevent string literals (i.e. 'char *') from being
-   cast to a bool in Attr. */
+/**
+ * Wrap bools to prevent string literals (i.e. 'char *') from being
+ * cast to a bool in Attr.
+ */
 template<typename T>
 struct Explicit {
     T t;
@@ -45,21 +52,25 @@ struct Explicit {
 };
 
 
-/* This wants to be a little bit like rust's Cow type.
-   Some parts of the evaluator benefit greatly from being able to reuse
-   existing allocations for strings, but have to be able to also use
-   newly allocated storage for values.
-
-   We do not define implicit conversions, even with ref qualifiers,
-   since those can easily become ambiguous to the reader and can degrade
-   into copying behaviour we want to avoid. */
+/**
+ * This wants to be a little bit like rust's Cow type.
+ * Some parts of the evaluator benefit greatly from being able to reuse
+ * existing allocations for strings, but have to be able to also use
+ * newly allocated storage for values.
+ *
+ * We do not define implicit conversions, even with ref qualifiers,
+ * since those can easily become ambiguous to the reader and can degrade
+ * into copying behaviour we want to avoid.
+ */
 class BackedStringView {
 private:
     std::variant<std::string, std::string_view> data;
 
-    /* Needed to introduce a temporary since operator-> must return
-       a pointer. Without this we'd need to store the view object
-       even when we already own a string. */
+    /**
+     * Needed to introduce a temporary since operator-> must return
+     * a pointer. Without this we'd need to store the view object
+     * even when we already own a string.
+     */
     class Ptr {
     private:
         std::string_view view;
@@ -77,8 +88,10 @@ public:
     BackedStringView(const BackedStringView &) = delete;
     BackedStringView & operator=(const BackedStringView &) = delete;
 
-    /* We only want move operations defined since the sole purpose of
-       this type is to avoid copies. */
+    /**
+     * We only want move operations defined since the sole purpose of
+     * this type is to avoid copies.
+     */
     BackedStringView(BackedStringView && other) = default;
     BackedStringView & operator=(BackedStringView && other) = default;
 
diff --git a/src/libutil/url-parts.hh b/src/libutil/url-parts.hh
index d5e6a2736..98162b0f7 100644
--- a/src/libutil/url-parts.hh
+++ b/src/libutil/url-parts.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <string>
 #include <regex>
@@ -22,21 +23,22 @@ const static std::string segmentRegex = "(?:" + pcharRegex + "*)";
 const static std::string absPathRegex = "(?:(?:/" + segmentRegex + ")*/?)";
 const static std::string pathRegex = "(?:" + segmentRegex + "(?:/" + segmentRegex + ")*/?)";
 
-// A Git ref (i.e. branch or tag name).
-const static std::string refRegexS = "[a-zA-Z0-9][a-zA-Z0-9_.\\/-]*"; // FIXME: check
+/// A Git ref (i.e. branch or tag name).
+/// \todo check that this is correct.
+const static std::string refRegexS = "[a-zA-Z0-9@][a-zA-Z0-9_.\\/@-]*";
 extern std::regex refRegex;
 
-// Instead of defining what a good Git Ref is, we define what a bad Git Ref is
-// This is because of the definition of a ref in refs.c in https://github.com/git/git
-// See tests/fetchGitRefs.sh for the full definition
+/// Instead of defining what a good Git Ref is, we define what a bad Git Ref is
+/// This is because of the definition of a ref in refs.c in https://github.com/git/git
+/// See tests/fetchGitRefs.sh for the full definition
 const static std::string badGitRefRegexS = "//|^[./]|/\\.|\\.\\.|[[:cntrl:][:space:]:?^~\[]|\\\\|\\*|\\.lock$|\\.lock/|@\\{|[/.]$|^@$|^$";
 extern std::regex badGitRefRegex;
 
-// A Git revision (a SHA-1 commit hash).
+/// A Git revision (a SHA-1 commit hash).
 const static std::string revRegexS = "[0-9a-fA-F]{40}";
 extern std::regex revRegex;
 
-// A ref or revision, or a ref followed by a revision.
+/// A ref or revision, or a ref followed by a revision.
 const static std::string refAndOrRevRegex = "(?:(" + revRegexS + ")|(?:(" + refRegexS + ")(?:/(" + revRegexS + "))?))";
 
 const static std::string flakeIdRegexS = "[a-zA-Z][a-zA-Z0-9_-]*";
diff --git a/src/libutil/url.hh b/src/libutil/url.hh
index ddd673d65..d2413ec0e 100644
--- a/src/libutil/url.hh
+++ b/src/libutil/url.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "error.hh"
 
@@ -7,7 +8,8 @@ namespace nix {
 struct ParsedURL
 {
     std::string url;
-    std::string base; // URL without query/fragment
+    /// URL without query/fragment
+    std::string base;
     std::string scheme;
     std::optional<std::string> authority;
     std::string path;
@@ -28,7 +30,7 @@ std::map<std::string, std::string> decodeQuery(const std::string & query);
 
 ParsedURL parseURL(const std::string & url);
 
-/*
+/**
  * Although that’s not really standardized anywhere, an number of tools
  * use a scheme of the form 'x+y' in urls, where y is the “transport layer”
  * scheme, and x is the “application layer” scheme.
diff --git a/src/libutil/util.hh b/src/libutil/util.hh
index 5a3976d02..6c2706cc1 100644
--- a/src/libutil/util.hh
+++ b/src/libutil/util.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "types.hh"
 #include "error.hh"
diff --git a/src/libutil/xml-writer.hh b/src/libutil/xml-writer.hh
index 4c91adee6..74f53b7ca 100644
--- a/src/libutil/xml-writer.hh
+++ b/src/libutil/xml-writer.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <iostream>
 #include <string>
diff --git a/src/nix-env/nix-env.cc b/src/nix-env/nix-env.cc
index aa7ada37d..f076ffdb0 100644
--- a/src/nix-env/nix-env.cc
+++ b/src/nix-env/nix-env.cc
@@ -1387,6 +1387,8 @@ static int main_nix_env(int argc, char * * argv)
     {
         Strings opFlags, opArgs;
         Operation op = 0;
+        std::string opName;
+        bool showHelp = false;
         RepairFlag repair = NoRepair;
         std::string file;
 
@@ -1426,37 +1428,59 @@ static int main_nix_env(int argc, char * * argv)
             Operation oldOp = op;
 
             if (*arg == "--help")
-                showManPage("nix-env");
+                showHelp = true;
             else if (*arg == "--version")
                 op = opVersion;
-            else if (*arg == "--install" || *arg == "-i")
+            else if (*arg == "--install" || *arg == "-i") {
                 op = opInstall;
+                opName = "-install";
+            }
             else if (*arg == "--force-name") // undocumented flag for nix-install-package
                 globals.forceName = getArg(*arg, arg, end);
-            else if (*arg == "--uninstall" || *arg == "-e")
+            else if (*arg == "--uninstall" || *arg == "-e") {
                 op = opUninstall;
-            else if (*arg == "--upgrade" || *arg == "-u")
+                opName = "-uninstall";
+            }
+            else if (*arg == "--upgrade" || *arg == "-u") {
                 op = opUpgrade;
-            else if (*arg == "--set-flag")
+                opName = "-upgrade";
+            }
+            else if (*arg == "--set-flag") {
                 op = opSetFlag;
-            else if (*arg == "--set")
+                opName = arg->substr(1);
+            }
+            else if (*arg == "--set") {
                 op = opSet;
-            else if (*arg == "--query" || *arg == "-q")
+                opName = arg->substr(1);
+            }
+            else if (*arg == "--query" || *arg == "-q") {
                 op = opQuery;
+                opName = "-query";
+            }
             else if (*arg == "--profile" || *arg == "-p")
                 globals.profile = absPath(getArg(*arg, arg, end));
             else if (*arg == "--file" || *arg == "-f")
                 file = getArg(*arg, arg, end);
-            else if (*arg == "--switch-profile" || *arg == "-S")
+            else if (*arg == "--switch-profile" || *arg == "-S") {
                 op = opSwitchProfile;
-            else if (*arg == "--switch-generation" || *arg == "-G")
+                opName = "-switch-profile";
+            }
+            else if (*arg == "--switch-generation" || *arg == "-G") {
                 op = opSwitchGeneration;
-            else if (*arg == "--rollback")
+                opName = "-switch-generation";
+            }
+            else if (*arg == "--rollback") {
                 op = opRollback;
-            else if (*arg == "--list-generations")
+                opName = arg->substr(1);
+            }
+            else if (*arg == "--list-generations") {
                 op = opListGenerations;
-            else if (*arg == "--delete-generations")
+                opName = arg->substr(1);
+            }
+            else if (*arg == "--delete-generations") {
                 op = opDeleteGenerations;
+                opName = arg->substr(1);
+            }
             else if (*arg == "--dry-run") {
                 printInfo("(dry run; not doing anything)");
                 globals.dryRun = true;
@@ -1485,6 +1509,7 @@ static int main_nix_env(int argc, char * * argv)
 
         myArgs.parseCmdline(argvToStrings(argc, argv));
 
+        if (showHelp) showManPage("nix-env" + opName);
         if (!op) throw UsageError("no operation specified");
 
         auto store = openStore();
diff --git a/src/nix-env/user-env.hh b/src/nix-env/user-env.hh
index 10646f713..af45d2d85 100644
--- a/src/nix-env/user-env.hh
+++ b/src/nix-env/user-env.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "get-drvs.hh"
 
diff --git a/src/nix-store/dotgraph.hh b/src/nix-store/dotgraph.hh
index 73b8d06b9..4fd944080 100644
--- a/src/nix-store/dotgraph.hh
+++ b/src/nix-store/dotgraph.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "store-api.hh"
 
diff --git a/src/nix-store/graphml.hh b/src/nix-store/graphml.hh
index 78be8a367..bd3a4a37c 100644
--- a/src/nix-store/graphml.hh
+++ b/src/nix-store/graphml.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "store-api.hh"
 
diff --git a/src/nix-store/nix-store.cc b/src/nix-store/nix-store.cc
index 54479489f..a62cb874f 100644
--- a/src/nix-store/nix-store.cc
+++ b/src/nix-store/nix-store.cc
@@ -1024,62 +1024,104 @@ static int main_nix_store(int argc, char * * argv)
         Strings opFlags, opArgs;
         Operation op = 0;
         bool readFromStdIn = false;
+        std::string opName;
+        bool showHelp = false;
 
         parseCmdLine(argc, argv, [&](Strings::iterator & arg, const Strings::iterator & end) {
             Operation oldOp = op;
 
             if (*arg == "--help")
-                showManPage("nix-store");
+                showHelp = true;
             else if (*arg == "--version")
                 op = opVersion;
-            else if (*arg == "--realise" || *arg == "--realize" || *arg == "-r")
+            else if (*arg == "--realise" || *arg == "--realize" || *arg == "-r") {
                 op = opRealise;
-            else if (*arg == "--add" || *arg == "-A")
+                opName = "-realise";
+            }
+            else if (*arg == "--add" || *arg == "-A"){
                 op = opAdd;
-            else if (*arg == "--add-fixed")
+                opName = "-add";
+            }
+            else if (*arg == "--add-fixed") {
                 op = opAddFixed;
+                opName = arg->substr(1);
+            }
             else if (*arg == "--print-fixed-path")
                 op = opPrintFixedPath;
-            else if (*arg == "--delete")
+            else if (*arg == "--delete") {
                 op = opDelete;
-            else if (*arg == "--query" || *arg == "-q")
+                opName = arg->substr(1);
+            }
+            else if (*arg == "--query" || *arg == "-q") {
                 op = opQuery;
-            else if (*arg == "--print-env")
+                opName = "-query";
+            }
+            else if (*arg == "--print-env") {
                 op = opPrintEnv;
-            else if (*arg == "--read-log" || *arg == "-l")
+                opName = arg->substr(1);
+            }
+            else if (*arg == "--read-log" || *arg == "-l") {
                 op = opReadLog;
-            else if (*arg == "--dump-db")
+                opName = "-read-log";
+            }
+            else if (*arg == "--dump-db") {
                 op = opDumpDB;
-            else if (*arg == "--load-db")
+                opName = arg->substr(1);
+            }
+            else if (*arg == "--load-db") {
                 op = opLoadDB;
+                opName = arg->substr(1);
+            }
             else if (*arg == "--register-validity")
                 op = opRegisterValidity;
             else if (*arg == "--check-validity")
                 op = opCheckValidity;
-            else if (*arg == "--gc")
+            else if (*arg == "--gc") {
                 op = opGC;
-            else if (*arg == "--dump")
+                opName = arg->substr(1);
+            }
+            else if (*arg == "--dump") {
                 op = opDump;
-            else if (*arg == "--restore")
+                opName = arg->substr(1);
+            }
+            else if (*arg == "--restore") {
                 op = opRestore;
-            else if (*arg == "--export")
+                opName = arg->substr(1);
+            }
+            else if (*arg == "--export") {
                 op = opExport;
-            else if (*arg == "--import")
+                opName = arg->substr(1);
+            }
+            else if (*arg == "--import") {
                 op = opImport;
+                opName = arg->substr(1);
+            }
             else if (*arg == "--init")
                 op = opInit;
-            else if (*arg == "--verify")
+            else if (*arg == "--verify") {
                 op = opVerify;
-            else if (*arg == "--verify-path")
+                opName = arg->substr(1);
+            }
+            else if (*arg == "--verify-path") {
                 op = opVerifyPath;
-            else if (*arg == "--repair-path")
+                opName = arg->substr(1);
+            }
+            else if (*arg == "--repair-path") {
                 op = opRepairPath;
-            else if (*arg == "--optimise" || *arg == "--optimize")
+                opName = arg->substr(1);
+            }
+            else if (*arg == "--optimise" || *arg == "--optimize") {
                 op = opOptimise;
-            else if (*arg == "--serve")
+                opName = "-optimise";
+            }
+            else if (*arg == "--serve") {
                 op = opServe;
-            else if (*arg == "--generate-binary-cache-key")
+                opName = arg->substr(1);
+            }
+            else if (*arg == "--generate-binary-cache-key") {
                 op = opGenerateBinaryCacheKey;
+                opName = arg->substr(1);
+            }
             else if (*arg == "--add-root")
                 gcRoot = absPath(getArg(*arg, arg, end));
             else if (*arg == "--stdin" && !isatty(STDIN_FILENO))
@@ -1109,6 +1151,7 @@ static int main_nix_store(int argc, char * * argv)
             return true;
         });
 
+        if (showHelp) showManPage("nix-store" + opName);
         if (!op) throw UsageError("no operation specified");
 
         if (op != opDump && op != opRestore) /* !!! hack */
diff --git a/src/nix/flake.md b/src/nix/flake.md
index 8eaa41b96..d70f34eeb 100644
--- a/src/nix/flake.md
+++ b/src/nix/flake.md
@@ -221,11 +221,46 @@ Currently the `type` attribute can be one of the following:
   commit hash (`rev`). Note that unlike Git, GitHub allows fetching by
   commit hash without specifying a branch or tag.
 
+  You can also specify `host` as a parameter, to point to a custom GitHub
+  Enterprise server.
+
   Some examples:
 
   * `github:edolstra/dwarffs`
   * `github:edolstra/dwarffs/unstable`
   * `github:edolstra/dwarffs/d3f2baba8f425779026c6ec04021b2e927f61e31`
+  * `github:internal/project?host=company-github.example.org`
+
+* `gitlab`: Similar to `github`, is a more efficient way to fetch
+  GitLab repositories. The following attributes are required:
+
+  * `owner`: The owner of the repository.
+
+  * `repo`: The name of the repository.
+
+  Like `github`, these are downloaded as tarball archives.
+
+  The URL syntax for `gitlab` flakes is:
+
+  `gitlab:<owner>/<repo>(/<rev-or-ref>)?(\?<params>)?`
+
+  `<rev-or-ref>` works the same as `github`. Either a branch or tag name
+  (`ref`), or a commit hash (`rev`) can be specified.
+
+  Since GitLab allows for self-hosting, you can specify `host` as
+  a parameter, to point to any instances other than `gitlab.com`.
+
+  Some examples:
+
+  * `gitlab:veloren/veloren`
+  * `gitlab:veloren/veloren/master`
+  * `gitlab:veloren/veloren/80a4d7f13492d916e47d6195be23acae8001985a`
+  * `gitlab:openldap/openldap?host=git.openldap.org`
+
+  When accessing a project in a (nested) subgroup, make sure to URL-encode any
+  slashes, i.e. replace `/` with `%2F`:
+
+  * `gitlab:veloren%2Fdev/rfcs`
 
 * `sourcehut`: Similar to `github`, is a more efficient way to fetch
   SourceHut repositories. The following attributes are required:
@@ -317,6 +352,8 @@ The following attributes are supported in `flake.nix`:
   also contains some metadata about the inputs. These are:
 
   * `outPath`: The path in the Nix store of the flake's source tree.
+     This way, the attribute set can be passed to `import` as if it was a path,
+     as in the example above (`import nixpkgs`).
 
   * `rev`: The commit hash of the flake's repository, if applicable.
 
diff --git a/src/nix/run.hh b/src/nix/run.hh
index fed360158..97ddef19b 100644
--- a/src/nix/run.hh
+++ b/src/nix/run.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "store-api.hh"