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.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.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.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 634a51c38..19fdfc1eb 100644
--- a/src/libstore/content-address.hh
+++ b/src/libstore/content-address.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <variant>
 #include "hash.hh"
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 a5731f18d..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"
diff --git a/src/libstore/derived-path.hh b/src/libstore/derived-path.hh
index 72dbcc128..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"
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 0b7c98ac9..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>
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 2730541c6..4ca6747b3 100644
--- a/src/libstore/path.hh
+++ b/src/libstore/path.hh
@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <string_view>
 
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.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.hh b/src/libstore/store-api.hh
index 194cbe6c4..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"
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.hh b/src/libutil/canon-path.hh
index 77f98775c..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;
@@ -107,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
@@ -128,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();
@@ -147,27 +159,37 @@ 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.
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 748d6043b..3c1d70294 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 ac372e03e..5948ad7ad 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 in the corresponding `.cc` file.
- **/
+ */
 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.hh b/src/libutil/hash.hh
index 38d09646e..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,35 +129,53 @@ 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. */
+/**
+ * And the reverse.
+ */
 std::string_view printHashType(HashType ht);
 
 
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 1a37aea9e..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"
@@ -217,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/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 afc1df98a..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/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/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"