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

Extend internal API docs, part 2

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;

src/libcmd/command.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "installable-value.hh"
 #include "args.hh"

src/libcmd/common-eval-args.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "args.hh"
 

src/libcmd/editor-for.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "types.hh"
 

src/libcmd/installable-attr-path.hh

@@ -1,3 +1,6 @@
+#pragma once
+///@file
+
 #include "globals.hh"
 #include "installable-value.hh"
 #include "outputs-spec.hh"

src/libcmd/installable-derived-path.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "installables.hh"
 

src/libcmd/installable-flake.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "installable-value.hh"
 

src/libcmd/installable-value.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "installables.hh"
 #include "flake/flake.hh"

src/libcmd/installables.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "util.hh"
 #include "path.hh"

src/libcmd/legacy.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <functional>
 #include <map>

src/libcmd/markdown.hh

@@ -1,3 +1,6 @@
+#pragma once
+///@file
+
 #include "types.hh"
 
 namespace nix {

src/libcmd/repl.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "eval.hh"
 

src/libexpr/attr-path.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "eval.hh"
 

src/libexpr/attr-set.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "nixexpr.hh"
 #include "symbol-table.hh"

src/libexpr/eval-cache.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "sync.hh"
 #include "hash.hh"

src/libexpr/eval-inline.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "eval.hh"
 

src/libexpr/eval.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "attr-set.hh"
 #include "types.hh"

src/libexpr/flake/flake.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "types.hh"
 #include "flakeref.hh"

src/libexpr/flake/flakeref.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "types.hh"
 #include "hash.hh"

src/libexpr/flake/lockfile.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "flakeref.hh"
 

src/libexpr/function-trace.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "eval.hh"
 

src/libexpr/get-drvs.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "eval.hh"
 #include "path.hh"

src/libexpr/json-to-value.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "eval.hh"
 

src/libexpr/nixexpr.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <map>
 #include <vector>

src/libexpr/primops.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "eval.hh"
 

src/libexpr/symbol-table.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <list>
 #include <map>

src/libexpr/tests/libexpr.hh

@@ -1,3 +1,6 @@
+#pragma once
+///@file
+
 #include <gtest/gtest.h>
 #include <gmock/gmock.h>
 

src/libexpr/tests/value/context.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <rapidcheck/gen/Arbitrary.h>
 

src/libexpr/value-to-json.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "nixexpr.hh"
 #include "eval.hh"

src/libexpr/value-to-xml.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "nixexpr.hh"
 #include "eval.hh"

src/libexpr/value.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <cassert>
 

src/libexpr/value/context.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "util.hh"
 #include "comparator.hh"

src/libfetchers/attrs.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "types.hh"
 

src/libfetchers/cache.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "fetchers.hh"
 

src/libfetchers/fetch-settings.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "types.hh"
 #include "config.hh"

src/libfetchers/fetchers.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "types.hh"
 #include "hash.hh"

src/libfetchers/registry.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "types.hh"
 #include "fetchers.hh"

src/libmain/common-args.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "args.hh"
 

src/libmain/loggers.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "types.hh"
 

src/libmain/progress-bar.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "logging.hh"
 

src/libmain/shared.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "util.hh"
 #include "args.hh"

src/libstore/binary-cache-store.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "crypto.hh"
 #include "store-api.hh"

src/libstore/build-result.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "realisation.hh"
 #include "derived-path.hh"

src/libstore/build/derivation-goal.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "parsed-derivations.hh"
 #include "lock.hh"

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

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "store-api.hh"
 #include "goal.hh"

src/libstore/build/goal.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "types.hh"
 #include "store-api.hh"

src/libstore/build/hook-instance.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "logging.hh"
 #include "serialise.hh"

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

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "derivation-goal.hh"
 #include "local-store.hh"

src/libstore/build/personality.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <string>
 

src/libstore/build/substitution-goal.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "lock.hh"
 #include "store-api.hh"

src/libstore/build/worker.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "types.hh"
 #include "lock.hh"

src/libstore/builtins.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "derivations.hh"
 

src/libstore/builtins/buildenv.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "derivations.hh"
 #include "store-api.hh"

src/libstore/content-address.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <variant>
 #include "hash.hh"

src/libstore/crypto.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "types.hh"
 

src/libstore/daemon.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "serialise.hh"
 #include "store-api.hh"

src/libstore/derivations.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "path.hh"
 #include "types.hh"

src/libstore/derived-path.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "util.hh"
 #include "path.hh"

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

src/libstore/fs-accessor.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "types.hh"
 

src/libstore/gc-store.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "store-api.hh"
 

src/libstore/globals.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "types.hh"
 #include "config.hh"

src/libstore/local-fs-store.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "store-api.hh"
 #include "gc-store.hh"

src/libstore/local-store.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "sqlite.hh"
 

src/libstore/lock.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "types.hh"
 

src/libstore/log-store.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "store-api.hh"
 

src/libstore/machines.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "types.hh"
 

src/libstore/make-content-addressed.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "store-api.hh"
 

src/libstore/names.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <memory>
 

src/libstore/nar-accessor.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <functional>
 

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

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "ref.hh"
 #include "nar-info.hh"

src/libstore/nar-info.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "types.hh"
 #include "hash.hh"

src/libstore/outputs-spec.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <cassert>
 #include <optional>

src/libstore/parsed-derivations.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "derivations.hh"
 #include "store-api.hh"

src/libstore/path-info.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "crypto.hh"
 #include "path.hh"

src/libstore/path-regex.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 namespace nix {
 

src/libstore/path-with-outputs.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "path.hh"
 #include "derived-path.hh"

src/libstore/path.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <string_view>
 

src/libstore/pathlocks.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "util.hh"
 

src/libstore/profiles.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "types.hh"
 #include "pathlocks.hh"

src/libstore/realisation.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <variant>
 

src/libstore/references.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "hash.hh"
 #include "path.hh"

src/libstore/remote-fs-accessor.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "fs-accessor.hh"
 #include "ref.hh"

src/libstore/remote-store.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <limits>
 #include <string>

src/libstore/repair-flag.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 namespace nix {
 

src/libstore/s3-binary-cache-store.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "binary-cache-store.hh"
 

src/libstore/s3.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #if ENABLE_S3
 

src/libstore/serve-protocol.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 namespace nix {
 

src/libstore/sqlite.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <functional>
 #include <string>

src/libstore/ssh-store-config.hh

@@ -1,3 +1,6 @@
+#pragma once
+///@file
+
 #include "store-api.hh"
 
 namespace nix {

src/libstore/ssh.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "util.hh"
 #include "sync.hh"

src/libstore/store-api.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "nar-info.hh"
 #include "realisation.hh"

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)
 {

src/libstore/tests/derived-path.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <rapidcheck/gen/Arbitrary.h>
 

src/libstore/tests/libstore.hh

@@ -1,3 +1,6 @@
+#pragma once
+///@file
+
 #include <gtest/gtest.h>
 #include <gmock/gmock.h>
 

src/libstore/tests/outputs-spec.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <rapidcheck/gen/Arbitrary.h>
 

src/libstore/tests/path.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <rapidcheck/gen/Arbitrary.h>
 

src/libstore/uds-remote-store.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include "remote-store.hh"
 #include "local-fs-store.hh"

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

src/libutil/abstract-setting-to-json.hh

@@ -1,4 +1,5 @@
 #pragma once
+///@file
 
 #include <nlohmann/json.hpp>
 #include "config.hh"