Fix most DoxyGen warnings

Helps with #11841.

src/external-api-docs/doxygen.cfg.in

@@ -41,7 +41,7 @@ INPUT                  = \
   @src@/src/libutil-c \
   @src@/src/libexpr-c \
   @src@/src/libstore-c \
-  @src@/doc/external-api/README.md
+  @src@/src/external-api-docs/README.md
 
 FILE_PATTERNS = nix_api_*.h *.md
 
@@ -55,6 +55,8 @@ EXCLUDE_PATTERNS = *_internal.h
 GENERATE_TREEVIEW = YES
 OPTIMIZE_OUTPUT_FOR_C  = YES
 
-USE_MDFILE_AS_MAINPAGE = doc/external-api/README.md
+USE_MDFILE_AS_MAINPAGE = @src@/src/external-api-docs/README.md
 
+WARN_IF_UNDOCUMENTED = NO
+WARN_IF_INCOMPLETE_DOC = NO
 QUIET = YES

src/internal-api-docs/doxygen.cfg.in

@@ -43,8 +43,8 @@ INPUT                  = \
   @src@/libexpr/flake \
   @src@/libexpr-tests \
   @src@/libexpr-tests/value \
-  @src@/libexpr-test-support/test \
+  @src@/libexpr-test-support/tests \
-  @src@/libexpr-test-support/test/value \
+  @src@/libexpr-test-support/tests/value \
   @src@/libexpr/value \
   @src@/libfetchers \
   @src@/libmain \
@@ -52,10 +52,11 @@ INPUT                  = \
   @src@/libstore/build \
   @src@/libstore/builtins \
   @src@/libstore-tests \
-  @src@/libstore-test-support/test \
+  @src@/libstore-test-support/tests \
   @src@/libutil \
+  @src@/libutil/args \
   @src@/libutil-tests \
-  @src@/libutil-test-support/test \
+  @src@/libutil-test-support/tests \
   @src@/nix \
   @src@/nix-env \
   @src@/nix-store
@@ -83,7 +84,9 @@ EXPAND_ONLY_PREDEF     = YES
 # RECURSIVE has no effect here.
 # This tag requires that the tag SEARCH_INCLUDES is set to YES.
 
-INCLUDE_PATH           =
+INCLUDE_PATH           = \
+  @BUILD_ROOT@/src/libexpr/libnixexpr.so.p \
+  @BUILD_ROOT@/src/nix/nix.p \
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The
@@ -96,7 +99,18 @@ EXPAND_AS_DEFINED      = \
   DECLARE_COMMON_SERIALISER \
   DECLARE_WORKER_SERIALISER \
   DECLARE_SERVE_SERIALISER \
-  LENGTH_PREFIXED_PROTO_HELPER
+  LENGTH_PREFIXED_PROTO_HELPER \
+  LENGTH_PREFIXED_PROTO_HELPER_X \
+  WORKER_USE_LENGTH_PREFIX_SERIALISER \
+  WORKER_USE_LENGTH_PREFIX_SERIALISER_COMMA \
+  SERVE_USE_LENGTH_PREFIX_SERIALISER \
+  SERVE_USE_LENGTH_PREFIX_SERIALISER_COMMA \
+  COMMON_METHODS \
+  JSON_IMPL \
+  MakeBinOp
+
+PREDEFINED = DOXYGEN_SKIP
 
 WARN_IF_UNDOCUMENTED = NO
+WARN_IF_INCOMPLETE_DOC = NO
 QUIET = YES

src/internal-api-docs/meson.build

@@ -12,6 +12,7 @@ doxygen_cfg = configure_file(
   configuration : {
     'PROJECT_NUMBER': meson.project_version(),
     'OUTPUT_DIRECTORY' : meson.current_build_dir(),
+    'BUILD_ROOT' : meson.build_root(),
     'src' : fs.parent(fs.parent(meson.project_source_root())) / 'src',
   },
 )

src/libexpr-c/nix_api_expr.h

@@ -129,7 +129,7 @@ nix_err nix_value_call_multi(
  * @param[in] state The state of the evaluation.
  * @param[out] value The result of the function call.
  * @param[in] fn The Nix function to call.
- * @param[in] args The arguments to pass to the function.
+ * @param[in] ... The arguments to pass to the function.
  *
  * @see nix_value_call_multi
  */

src/libexpr-c/nix_api_value.h

@@ -77,8 +77,7 @@ typedef struct ExternalValue ExternalValue;
  */
 typedef struct nix_realised_string nix_realised_string;
 
-/** @defgroup primops
+/** @defgroup primops Adding primops
- * @brief Create your own primops
  * @{
  */
 /** @brief Function pointer for primops
@@ -252,7 +251,7 @@ int64_t nix_get_int(nix_c_context * context, const nix_value * value);
  * @param[in] value Nix value to inspect
  * @return reference to external, NULL in case of error
  */
-ExternalValue * nix_get_external(nix_c_context * context, nix_value *);
+ExternalValue * nix_get_external(nix_c_context * context, nix_value * value);
 
 /** @brief Get the ix'th element of a list
  *
@@ -423,7 +422,7 @@ nix_list_builder_insert(nix_c_context * context, ListBuilder * list_builder, uns
 /** @brief Free a list builder
  *
  * Does not fail.
- * @param[in] builder the builder to free
+ * @param[in] list_builder The builder to free.
  */
 void nix_list_builder_free(ListBuilder * list_builder);
 

src/libexpr/eval.hh

@@ -91,7 +91,7 @@ struct PrimOp
     const char * doc = nullptr;
 
     /**
-     * Add a trace item, `while calling the '<name>' builtin`
+     * Add a trace item, while calling the `<name>` builtin.
      *
      * This is used to remove the redundant item for `builtins.addErrorContext`.
      */

src/libexpr/nixexpr.hh

@@ -206,7 +206,7 @@ struct ExprSelect : Expr
     /**
      * Evaluate the `a.b.c` part of `a.b.c.d`. This exists mostly for the purpose of :doc in the repl.
      *
-     * @param[out] v The attribute set that should contain the last attribute name (if it exists).
+     * @param[out] attrs The attribute set that should contain the last attribute name (if it exists).
      * @return The last attribute name in `attrPath`
      *
      * @note This does *not* evaluate the final attribute, and does not fail if that's the only attribute that does not exist.

src/libexpr/value/context.hh

@@ -28,7 +28,7 @@ struct NixStringContextElem {
     /**
      * Plain opaque path to some store object.
      *
-     * Encoded as just the path: ‘<path>’.
+     * Encoded as just the path: `<path>`.
      */
     using Opaque = SingleDerivedPath::Opaque;
 
@@ -39,7 +39,7 @@ struct NixStringContextElem {
      * also all outputs of all derivations in that closure (including the
      * root derivation).
      *
-     * Encoded in the form ‘=<drvPath>’.
+     * Encoded in the form `=<drvPath>`.
      */
     struct DrvDeep {
         StorePath drvPath;
@@ -50,7 +50,7 @@ struct NixStringContextElem {
     /**
      * Derivation output.
      *
-     * Encoded in the form ‘!<output>!<drvPath>’.
+     * Encoded in the form `!<output>!<drvPath>`.
      */
     using Built = SingleDerivedPath::Built;
 
@@ -68,9 +68,9 @@ struct NixStringContextElem {
 
     /**
      * Decode a context string, one of:
-     * - ‘<path>’
+     * - `<path>`
-     * - ‘=<path>’
+     * - `=<path>`
-     * - ‘!<name>!<path>’
+     * - `!<name>!<path>`
      *
      * @param xpSettings Stop-gap to avoid globals during unit tests.
      */

src/libfetchers/fetchers.cc

@@ -475,7 +475,10 @@ namespace nlohmann {
 
 using namespace nix;
 
-fetchers::PublicKey adl_serializer<fetchers::PublicKey>::from_json(const json & json) {
+#ifndef DOXYGEN_SKIP
+
+fetchers::PublicKey adl_serializer<fetchers::PublicKey>::from_json(const json & json)
+{
     fetchers::PublicKey res = { };
     if (auto type = optionalValueAt(json, "type"))
         res.type = getString(*type);
@@ -485,9 +488,12 @@ fetchers::PublicKey adl_serializer<fetchers::PublicKey>::from_json(const json &
     return res;
 }
 
-void adl_serializer<fetchers::PublicKey>::to_json(json & json, fetchers::PublicKey p) {
+void adl_serializer<fetchers::PublicKey>::to_json(json & json, fetchers::PublicKey p)
+{
     json["type"] = p.type;
     json["key"] = p.key;
 }
 
+#endif
+
 }

src/libstore-c/nix_api_store.h

@@ -166,7 +166,7 @@ nix_store_get_version(nix_c_context * context, Store * store, nix_get_string_cal
  *
  * @param[out] context Optional, stores error information
  * @param[in] srcStore nix source store reference
- * @param[in] srcStore nix destination store reference
+ * @param[in] dstStore nix destination store reference
  * @param[in] path Path to copy
  */
 nix_err nix_store_copy_closure(nix_c_context * context, Store * srcStore, Store * dstStore, StorePath * path);

src/libstore-test-support/tests/derived-path.cc

@@ -7,7 +7,7 @@
 namespace rc {
 using namespace nix;
 
-Gen<DerivedPath::Opaque> Arbitrary<DerivedPath::Opaque>::arbitrary()
+Gen<SingleDerivedPath::Opaque> Arbitrary<SingleDerivedPath::Opaque>::arbitrary()
 {
     return gen::just(DerivedPath::Opaque {
         .path = *gen::arbitrary<StorePath>(),

src/libstore-tests/serve-protocol.cc

@@ -38,6 +38,8 @@ VERSIONED_CHARACTERIZATION_TEST(
         "oh no \0\0\0 what was that!",
     }))
 
+#ifndef DOXYGEN_SKIP
+
 VERSIONED_CHARACTERIZATION_TEST(
     ServeProtoTest,
     storePath,
@@ -84,6 +86,8 @@ VERSIONED_CHARACTERIZATION_TEST(
         },
     }))
 
+#endif
+
 VERSIONED_CHARACTERIZATION_TEST(
     ServeProtoTest,
     realisation,

src/libstore-tests/worker-protocol.cc

@@ -39,6 +39,8 @@ VERSIONED_CHARACTERIZATION_TEST(
         "oh no \0\0\0 what was that!",
     }))
 
+#ifndef DOXYGEN_SKIP
+
 VERSIONED_CHARACTERIZATION_TEST(
     WorkerProtoTest,
     storePath,
@@ -69,6 +71,8 @@ VERSIONED_CHARACTERIZATION_TEST(
         },
     }))
 
+#endif
+
 VERSIONED_CHARACTERIZATION_TEST(
     WorkerProtoTest,
     derivedPath_1_29,

src/libstore/build/goal.hh

@@ -107,7 +107,7 @@ protected:
 public:
 
     /**
-     * Suspend our goal and wait until we get @ref work()-ed again.
+     * Suspend our goal and wait until we get `work`-ed again.
      * `co_await`-able by @ref Co.
      */
     struct Suspend {};
@@ -192,7 +192,7 @@ public:
 
         bool await_ready() { return false; };
         /**
-         * When we `co_await` another @ref Co-returning coroutine,
+         * When we `co_await` another `Co`-returning coroutine,
          * we tell the caller of `caller_coroutine.resume()` to switch to our coroutine (@ref handle).
          * To make sure we return to the original coroutine, we set it as the continuation of our
          * coroutine. In @ref promise_type::final_awaiter we check if it's set and if so we return to it.
@@ -208,7 +208,7 @@ public:
     };
 
     /**
-     * Used on initial suspend, does the same as @ref std::suspend_always,
+     * Used on initial suspend, does the same as `std::suspend_always`,
      * but asserts that everything has been set correctly.
      */
     struct InitialSuspend {
@@ -269,8 +269,8 @@ public:
         };
 
         /**
-         * Called by compiler generated code to construct the @ref Co
+         * Called by compiler generated code to construct the `Co`
-         * that is returned from a @ref Co-returning coroutine.
+         * that is returned from a `Co`-returning coroutine.
          */
         Co get_return_object();
 

src/libstore/build/worker.hh

@@ -208,7 +208,7 @@ public:
         const OutputsSpec & wantedOutputs, BuildMode buildMode = bmNormal);
 
     /**
-     * @ref SubstitutionGoal "substitution goal"
+     * @ref PathSubstitutionGoal "substitution goal"
      */
     std::shared_ptr<PathSubstitutionGoal> makePathSubstitutionGoal(const StorePath & storePath, RepairFlag repair = NoRepair, std::optional<ContentAddress> ca = std::nullopt);
     std::shared_ptr<DrvOutputSubstitutionGoal> makeDrvOutputSubstitutionGoal(const DrvOutput & id, RepairFlag repair = NoRepair, std::optional<ContentAddress> ca = std::nullopt);

src/libstore/content-address.hh

@@ -97,8 +97,9 @@ struct ContentAddressMethod
      * were ingested, with the fixed output case not prefixed for back
      * compat.
      *
-     * @param [in] m A string that should begin with the prefix.
+     * @param m A string that should begin with the
-     * @param [out] m The remainder of the string after the prefix.
+     * prefix. On return, the remainder of the string after the
+     * prefix.
      */
     static ContentAddressMethod parsePrefix(std::string_view & m);
 
@@ -139,14 +140,14 @@ struct ContentAddressMethod
 /**
  * We've accumulated several types of content-addressed paths over the
  * years; fixed-output derivations support multiple hash algorithms and
- * serialisation methods (flat file vs NAR). Thus, ‘ca’ has one of the
+ * serialisation methods (flat file vs NAR). Thus, `ca` has one of the
  * following forms:
  *
  * - `TextIngestionMethod`:
- *   ‘text:sha256:<sha256 hash of file contents>’
+ *   `text:sha256:<sha256 hash of file contents>`
  *
  * - `FixedIngestionMethod`:
- *   ‘fixed:<r?>:<hash algorithm>:<hash of file contents>’
+ *   `fixed:<r?>:<hash algorithm>:<hash of file contents>`
  */
 struct ContentAddress
 {

src/libstore/length-prefixed-protocol-helper.hh

@@ -1,6 +1,8 @@
 #pragma once
 /**
- * @file Reusable serialisers for serialization container types in a
+ * @file
+ *
+ * Reusable serialisers for serialization container types in a
  * length-prefixed manner.
  *
  * Used by both the Worker and Serve protocols.
@@ -28,25 +30,22 @@ struct StoreDirConfig;
 template<class Inner, typename T>
 struct LengthPrefixedProtoHelper;
 
-/*!
- * \typedef LengthPrefixedProtoHelper::S
- *
- * Read this as simply `using S = Inner::Serialise;`.
- *
- * It would be nice to use that directly, but C++ doesn't seem to allow
- * it. The `typename` keyword needed to refer to `Inner` seems to greedy
- * (low precedence), and then C++ complains that `Serialise` is not a
- * type parameter but a real type.
- *
- * Making this `S` alias seems to be the only way to avoid these issues.
- */
-
 #define LENGTH_PREFIXED_PROTO_HELPER(Inner, T) \
     struct LengthPrefixedProtoHelper< Inner, T > \
     { \
         static T read(const StoreDirConfig & store, typename Inner::ReadConn conn); \
         static void write(const StoreDirConfig & store, typename Inner::WriteConn conn, const T & str); \
     private: \
+        /*! \
+         * Read this as simply `using S = Inner::Serialise;`. \
+         * \
+         * It would be nice to use that directly, but C++ doesn't seem to allow \
+         * it. The `typename` keyword needed to refer to `Inner` seems to greedy \
+         * (low precedence), and then C++ complains that `Serialise` is not a \
+         * type parameter but a real type. \
+         * \
+         * Making this `S` alias seems to be the only way to avoid these issues. \
+         */ \
         template<typename U> using S = typename Inner::template Serialise<U>; \
     }
 
@@ -60,9 +59,8 @@ template<class Inner, typename... Ts>
 LENGTH_PREFIXED_PROTO_HELPER(Inner, std::tuple<Ts...>);
 
 template<class Inner, typename K, typename V>
-#define _X std::map<K, V>
+#define LENGTH_PREFIXED_PROTO_HELPER_X std::map<K, V>
-LENGTH_PREFIXED_PROTO_HELPER(Inner, _X);
+LENGTH_PREFIXED_PROTO_HELPER(Inner, LENGTH_PREFIXED_PROTO_HELPER_X);
-#undef _X
 
 template<class Inner, typename T>
 std::vector<T>

src/libstore/machines.hh

@@ -32,12 +32,12 @@ struct Machine {
 
     /**
      * @return Whether `features` is a subset of the union of `supportedFeatures` and
-     * `mandatoryFeatures`
+     * `mandatoryFeatures`.
      */
     bool allSupported(const std::set<std::string> & features) const;
 
     /**
-     * @return @Whether `mandatoryFeatures` is a subset of `features`
+     * @return Whether `mandatoryFeatures` is a subset of `features`.
      */
     bool mandatoryMet(const std::set<std::string> & features) const;
 

src/libstore/outputs-spec.cc

@@ -153,7 +153,10 @@ namespace nlohmann {
 
 using namespace nix;
 
-OutputsSpec adl_serializer<OutputsSpec>::from_json(const json & json) {
+#ifndef DOXYGEN_SKIP
+
+OutputsSpec adl_serializer<OutputsSpec>::from_json(const json & json)
+{
     auto names = json.get<StringSet>();
     if (names == StringSet({"*"}))
         return OutputsSpec::All {};
@@ -161,7 +164,8 @@ OutputsSpec adl_serializer<OutputsSpec>::from_json(const json & json) {
         return OutputsSpec::Names { std::move(names) };
 }
 
-void adl_serializer<OutputsSpec>::to_json(json & json, OutputsSpec t) {
+void adl_serializer<OutputsSpec>::to_json(json & json, OutputsSpec t)
+{
     std::visit(overloaded {
         [&](const OutputsSpec::All &) {
             json = std::vector<std::string>({"*"});
@@ -172,8 +176,8 @@ void adl_serializer<OutputsSpec>::to_json(json & json, OutputsSpec t) {
     }, t.raw);
 }
 
-
+ExtendedOutputsSpec adl_serializer<ExtendedOutputsSpec>::from_json(const json & json)
-ExtendedOutputsSpec adl_serializer<ExtendedOutputsSpec>::from_json(const json & json) {
+{
     if (json.is_null())
         return ExtendedOutputsSpec::Default {};
     else {
@@ -181,7 +185,8 @@ ExtendedOutputsSpec adl_serializer<ExtendedOutputsSpec>::from_json(const json &
     }
 }
 
-void adl_serializer<ExtendedOutputsSpec>::to_json(json & json, ExtendedOutputsSpec t) {
+void adl_serializer<ExtendedOutputsSpec>::to_json(json & json, ExtendedOutputsSpec t)
+{
     std::visit(overloaded {
         [&](const ExtendedOutputsSpec::Default &) {
             json = nullptr;
@@ -192,4 +197,6 @@ void adl_serializer<ExtendedOutputsSpec>::to_json(json & json, ExtendedOutputsSp
     }, t.raw);
 }
 
+#endif
+
 }

src/libstore/path.hh

@@ -81,7 +81,7 @@ typedef std::set<StorePath> StorePathSet;
 typedef std::vector<StorePath> StorePaths;
 
 /**
- * The file extension of \ref Derivation derivations when serialized
+ * The file extension of \ref nix::Derivation derivations when serialized
  * into store objects.
  */
 constexpr std::string_view drvExtension = ".drv";

src/libstore/profiles.hh

@@ -1,6 +1,8 @@
 #pragma once
 /**
- * @file Implementation of Profiles.
+ * @file
+ *
+ * Implementation of Profiles.
  *
  * See the manual for additional information.
  */

src/libstore/serve-protocol-impl.hh

@@ -29,11 +29,10 @@ SERVE_USE_LENGTH_PREFIX_SERIALISER(template<typename T>, std::vector<T>)
 SERVE_USE_LENGTH_PREFIX_SERIALISER(template<typename T>, std::set<T>)
 SERVE_USE_LENGTH_PREFIX_SERIALISER(template<typename... Ts>, std::tuple<Ts...>)
 
-#define COMMA_ ,
+#define SERVE_USE_LENGTH_PREFIX_SERIALISER_COMMA ,
 SERVE_USE_LENGTH_PREFIX_SERIALISER(
-    template<typename K COMMA_ typename V>,
+    template<typename K SERVE_USE_LENGTH_PREFIX_SERIALISER_COMMA typename V>,
-    std::map<K COMMA_ V>)
+    std::map<K SERVE_USE_LENGTH_PREFIX_SERIALISER_COMMA V>)
-#undef COMMA_
 
 /**
  * Use `CommonProto` where possible.

src/libstore/ssh.hh

@@ -59,7 +59,7 @@ public:
     /**
      * @param command The command (arg vector) to execute.
      *
-     * @param extraSShArgs Extra args to pass to SSH (not the command to
+     * @param extraSshArgs Extra arguments to pass to SSH (not the command to
      * execute). Will not be used when "fake SSHing" to the local
      * machine.
      */

src/libstore/store-api.hh

@@ -260,11 +260,11 @@ public:
 
     /**
      * Query the set of all valid paths. Note that for some store
-     * backends, the name part of store paths may be replaced by 'x'
+     * backends, the name part of store paths may be replaced by `x`
-     * (i.e. you'll get /nix/store/<hash>-x rather than
+     * (i.e. you'll get `/nix/store/<hash>-x` rather than
-     * /nix/store/<hash>-<name>). Use queryPathInfo() to obtain the
+     * `/nix/store/<hash>-<name>`). Use queryPathInfo() to obtain the
      * full store path. FIXME: should return a set of
-     * std::variant<StorePath, HashPart> to get rid of this hack.
+     * `std::variant<StorePath, HashPart>` to get rid of this hack.
      */
     virtual StorePathSet queryAllValidPaths()
     { unsupported("queryAllValidPaths"); }

src/libstore/store-dir-config.hh

@@ -59,20 +59,20 @@ struct StoreDirConfig : public Config
     std::string showPaths(const StorePathSet & paths);
 
     /**
-     * @return true if ‘path’ is in the Nix store (but not the Nix
+     * @return true if *path* is in the Nix store (but not the Nix
      * store itself).
      */
     bool isInStore(PathView path) const;
 
     /**
-     * @return true if ‘path’ is a store path, i.e. a direct child of the
+     * @return true if *path* is a store path, i.e. a direct child of the
      * Nix store.
      */
     bool isStorePath(std::string_view path) const;
 
     /**
-     * Split a path like /nix/store/<hash>-<name>/<bla> into
+     * Split a path like `/nix/store/<hash>-<name>/<bla>` into
-     * /nix/store/<hash>-<name> and /<bla>.
+     * `/nix/store/<hash>-<name>` and `/<bla>`.
      */
     std::pair<StorePath, Path> toStorePath(PathView path) const;
 

src/libstore/store-reference.hh

@@ -13,31 +13,31 @@ namespace nix {
  *
  * Supported values are:
  *
- * - ‘local’: The Nix store in /nix/store and database in
+ * - `local`: The Nix store in /nix/store and database in
  *   /nix/var/nix/db, accessed directly.
  *
- * - ‘daemon’: The Nix store accessed via a Unix domain socket
+ * - `daemon`: The Nix store accessed via a Unix domain socket
  *   connection to nix-daemon.
  *
- * - ‘unix://<path>’: The Nix store accessed via a Unix domain socket
+ * - `unix://<path>`: The Nix store accessed via a Unix domain socket
- *   connection to nix-daemon, with the socket located at <path>.
+ *   connection to nix-daemon, with the socket located at `<path>`.
  *
- * - ‘auto’ or ‘’: Equivalent to ‘local’ or ‘daemon’ depending on
+ * - `auto` or ``: Equivalent to `local` or `daemon` depending on
  *   whether the user has write access to the local Nix
  *   store/database.
  *
- * - ‘file://<path>’: A binary cache stored in <path>.
+ * - `file://<path>`: A binary cache stored in `<path>`.
  *
- * - ‘https://<path>’: A binary cache accessed via HTTP.
+ * - `https://<path>`: A binary cache accessed via HTTP.
  *
- * - ‘s3://<path>’: A writable binary cache stored on Amazon's Simple
+ * - `s3://<path>`: A writable binary cache stored on Amazon's Simple
  *   Storage Service.
  *
- * - ‘ssh://[user@]<host>’: A remote Nix store accessed by running
+ * - `ssh://[user@]<host>`: A remote Nix store accessed by running
- *   ‘nix-store --serve’ via SSH.
+ *   `nix-store --serve` via SSH.
  *
  * You can pass parameters to the store type by appending
- * ‘?key=value&key=value&...’ to the URI.
+ * `?key=value&key=value&...` to the URI.
  */
 struct StoreReference
 {

src/libstore/worker-protocol-connection.hh

@@ -78,7 +78,7 @@ struct WorkerProto::BasicClientConnection : WorkerProto::BasicConnection
     /**
      * Establishes connection, negotiating version.
      *
-     * @return the minimum version supported by both sides and the set
+     * @return The minimum version supported by both sides and the set
      * of protocol features supported by both sides.
      *
      * @param to Taken by reference to allow for various error handling
@@ -87,9 +87,9 @@ struct WorkerProto::BasicClientConnection : WorkerProto::BasicConnection
      * @param from Taken by reference to allow for various error
      * handling mechanisms.
      *
-     * @param localVersion Our version which is sent over
+     * @param localVersion Our version which is sent over.
      *
-     * @param features The protocol features that we support
+     * @param supportedFeatures The protocol features that we support.
      */
     // FIXME: this should probably be a constructor.
     static std::tuple<Version, std::set<Feature>> handshake(
@@ -141,7 +141,7 @@ struct WorkerProto::BasicServerConnection : WorkerProto::BasicConnection
     /**
      * Establishes connection, negotiating version.
      *
-     * @return the version provided by the other side of the
+     * @return The version provided by the other side of the
      * connection.
      *
      * @param to Taken by reference to allow for various error handling
@@ -150,9 +150,9 @@ struct WorkerProto::BasicServerConnection : WorkerProto::BasicConnection
      * @param from Taken by reference to allow for various error
      * handling mechanisms.
      *
-     * @param localVersion Our version which is sent over
+     * @param localVersion Our version which is sent over.
      *
-     * @param features The protocol features that we support
+     * @param supportedFeatures The protocol features that we support.
      */
     // FIXME: this should probably be a constructor.
     static std::tuple<Version, std::set<Feature>> handshake(

src/libstore/worker-protocol-impl.hh

@@ -29,11 +29,10 @@ WORKER_USE_LENGTH_PREFIX_SERIALISER(template<typename T>, std::vector<T>)
 WORKER_USE_LENGTH_PREFIX_SERIALISER(template<typename T>, std::set<T>)
 WORKER_USE_LENGTH_PREFIX_SERIALISER(template<typename... Ts>, std::tuple<Ts...>)
 
-#define COMMA_ ,
+#define WORKER_USE_LENGTH_PREFIX_SERIALISER_COMMA ,
 WORKER_USE_LENGTH_PREFIX_SERIALISER(
-    template<typename K COMMA_ typename V>,
+    template<typename K WORKER_USE_LENGTH_PREFIX_SERIALISER_COMMA typename V>,
-    std::map<K COMMA_ V>)
+    std::map<K WORKER_USE_LENGTH_PREFIX_SERIALISER_COMMA V>)
-#undef COMMA_
 
 /**
  * Use `CommonProto` where possible.

src/libutil-c/nix_api_util.h

@@ -162,7 +162,7 @@ void nix_c_context_free(nix_c_context * context);
  */
 nix_err nix_libutil_init(nix_c_context * context);
 
-/** @defgroup settings
+/** @defgroup settings Nix configuration settings
  *  @{
  */
 /**

src/libutil-test-support/tests/gtest-with-params.hh

@@ -6,7 +6,9 @@
 // The lion's share of this code is copy pasted directly out of RapidCheck
 // headers, so the copyright is set accordingly.
 /**
- * @file Implements the ability to run a RapidCheck test under gtest with changed
+ * @file
+ *
+ * Implements the ability to run a RapidCheck test under gtest with changed
  * test parameters such as the number of tests to run. This is useful for
  * running very large numbers of the extremely cheap property tests.
  */

src/libutil/args.cc

@@ -91,9 +91,6 @@ struct Parser {
 
     /**
      * @brief Parse the next character(s)
-     *
-     * @param r
-     * @return std::shared_ptr<Parser>
      */
     virtual void operator()(std::shared_ptr<Parser> & state, Strings & r) = 0;
 

src/libutil/args.hh

@@ -371,7 +371,7 @@ using Commands = std::map<std::string, std::function<ref<Command>()>>;
 
 /**
  * An argument parser that supports multiple subcommands,
- * i.e. ‘<command> <subcommand>’.
+ * i.e. `<command> <subcommand>`.
  */
 class MultiCommand : virtual public Args
 {

src/libutil/checked-arithmetic.hh

@@ -1,6 +1,8 @@
 #pragma once
 /**
- * @file Checked arithmetic with classes that make it hard to accidentally make something an unchecked operation.
+ * @file
+ *
+ * Checked arithmetic with classes that make it hard to accidentally make something an unchecked operation.
  */
 
 #include <compare>

src/libutil/file-content-address.hh

@@ -65,7 +65,7 @@ void dumpPath(
 /**
  * Restore a serialisation of the given file system object.
  *
- * @TODO use an arbitrary `FileSystemObjectSink`.
+ * \todo use an arbitrary `FileSystemObjectSink`.
  */
 void restorePath(
     const Path & path,

src/libutil/file-system.cc

@@ -29,7 +29,7 @@
 
 namespace nix {
 
-namespace fs { using namespace std::filesystem; }
+namespace fs = std::filesystem;
 
 /**
  * Treat the string as possibly an absolute path, by inspecting the
@@ -501,7 +501,7 @@ void deletePath(const fs::path & path, uint64_t & bytesFreed)
 
 AutoDelete::AutoDelete() : del{false} {}
 
-AutoDelete::AutoDelete(const fs::path & p, bool recursive) : _path(p)
+AutoDelete::AutoDelete(const std::filesystem::path & p, bool recursive) : _path(p)
 {
     del = true;
     this->recursive = recursive;

src/libutil/file-system.hh

@@ -126,8 +126,6 @@ std::optional<struct stat> maybeLstat(const Path & path);
  */
 bool pathExists(const Path & path);
 
-namespace fs {
-
 /**
  *  ```
  *  symlink_exists(p) = std::filesystem::exists(std::filesystem::symlink_status(p))
@@ -141,8 +139,6 @@ inline bool symlink_exists(const std::filesystem::path & path) {
     return std::filesystem::exists(std::filesystem::symlink_status(path));
 }
 
-} // namespace fs
-
 /**
  * A version of pathExists that returns false on a permission error.
  * Useful for inferring default paths across directories that might not
@@ -227,7 +223,7 @@ void createDir(const Path & path, mode_t mode = 0755);
  * Set the access and modification times of the given path, not
  * following symlinks.
  *
- * @param accessTime Specified in seconds.
+ * @param accessedTime Specified in seconds.
  *
  * @param modificationTime Specified in seconds.
  *

src/libutil/git.hh

@@ -104,7 +104,7 @@ void parseTree(
 /**
  * Helper putting the previous three `parse*` functions together.
  *
- * @rootModeIfBlob How to interpret a root blob, for which there is no
+ * @param rootModeIfBlob How to interpret a root blob, for which there is no
  * disambiguating dir entry to answer that questino. If the root it not
  * a blob, this is ignored.
  */

src/libutil/json-utils.hh

@@ -91,12 +91,14 @@ namespace nlohmann {
  * round trip. We do that with a static assert.
  */
 template<typename T>
-struct adl_serializer<std::optional<T>> {
+struct adl_serializer<std::optional<T>>
+{
     /**
      * @brief Convert a JSON type to an `optional<T>` treating
      *        `null` as `std::nullopt`.
      */
-    static void from_json(const json & json, std::optional<T> & t) {
+    static void from_json(const json & json, std::optional<T> & t)
+    {
         static_assert(
             nix::json_avoids_null<T>::value,
             "null is already in use for underlying type's JSON");
@@ -109,7 +111,8 @@ struct adl_serializer<std::optional<T>> {
      *  @brief Convert an optional type to a JSON type  treating `std::nullopt`
      *         as `null`.
      */
-    static void to_json(json & json, const std::optional<T> & t) {
+    static void to_json(json & json, const std::optional<T> & t)
+    {
         static_assert(
             nix::json_avoids_null<T>::value,
             "null is already in use for underlying type's JSON");

src/libutil/std-hash.hh

@@ -1,14 +1,17 @@
 #pragma once
-
+/**
-//!@file Hashing utilities for use with unordered_map, etc. (ie low level implementation logic, not domain logic like
+ * @file
-//! Nix hashing)
+ *
+ * Hashing utilities for use with `std::unordered_map`, etc. (i.e. low
+ * level implementation logic, not domain logic like Nix hashing).
+ */
 
 #include <functional>
 
 namespace nix {
 
 /**
- * hash_combine() from Boost. Hash several hashable values together
+ * `hash_combine()` from Boost. Hash several hashable values together
  * into a single hash.
  */
 inline void hash_combine(std::size_t & seed) {}

src/libutil/tarfile.cc

@@ -8,9 +8,7 @@
 
 namespace nix {
 
-namespace fs {
+namespace fs = std::filesystem;
-using namespace std::filesystem;
-}
 
 namespace {
 
@@ -106,7 +104,7 @@ TarArchive::TarArchive(Source & source, bool raw, std::optional<std::string> com
         "Failed to open archive (%s)");
 }
 
-TarArchive::TarArchive(const fs::path & path)
+TarArchive::TarArchive(const std::filesystem::path & path)
     : archive{archive_read_new()}
     , buffer(defaultBufferSize)
 {

src/nix/eval.cc

@@ -77,7 +77,7 @@ struct CmdEval : MixJSON, InstallableValueCommand, MixReadOnlyOption
         if (writeTo) {
             stopProgressBar();
 
-            if (fs::symlink_exists(*writeTo))
+            if (nix::symlink_exists(*writeTo))
                 throw Error("path '%s' already exists", writeTo->string());
 
             std::function<void(Value & v, const PosIdx pos, const fs::path & path)> recurse;