Fix most DoxyGen warnings

Helps with #11841.

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
-         * that is returned from a @ref Co-returning coroutine.
+         * Called by compiler generated code to construct the `Co`
+         * 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 [out] m The remainder of the string after the prefix.
+     * @param m A string that should begin with the
+     * 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>
-LENGTH_PREFIXED_PROTO_HELPER(Inner, _X);
-#undef _X
+#define LENGTH_PREFIXED_PROTO_HELPER_X std::map<K, V>
+LENGTH_PREFIXED_PROTO_HELPER(Inner, LENGTH_PREFIXED_PROTO_HELPER_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>,
-    std::map<K COMMA_ V>)
-#undef COMMA_
+    template<typename K SERVE_USE_LENGTH_PREFIX_SERIALISER_COMMA typename V>,
+    std::map<K SERVE_USE_LENGTH_PREFIX_SERIALISER_COMMA V>)
 
 /**
  * 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'
-     * (i.e. you'll get /nix/store/<hash>-x rather than
-     * /nix/store/<hash>-<name>). Use queryPathInfo() to obtain the
+     * backends, the name part of store paths may be replaced by `x`
+     * (i.e. you'll get `/nix/store/<hash>-x` rather than
+     * `/nix/store/<hash>-<name>`). Use queryPathInfo() to obtain the
      * full store path. FIXME: should return a set of
-     * std::variant<StorePath, HashPart> to get rid of this hack.
+     * `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
-     * /nix/store/<hash>-<name> and /<bla>.
+     * Split a path like `/nix/store/<hash>-<name>/<bla>` into
+     * `/nix/store/<hash>-<name>` and `/<bla>`.
      */
     std::pair<StorePath, Path> toStorePath(PathView path) const;
 

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
- *   connection to nix-daemon, with the socket located at <path>.
+ * - `unix://<path>`: The Nix store accessed via a Unix domain socket
+ *   connection to nix-daemon, with the socket located at `<path>`.
  *
- * - ‘auto’ or ‘’: Equivalent to ‘local’ or ‘daemon’ depending on
+ * - `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
- *   ‘nix-store --serve’ via SSH.
+ * - `ssh://[user@]<host>`: A remote Nix store accessed by running
+ *   `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>,
-    std::map<K COMMA_ V>)
-#undef COMMA_
+    template<typename K WORKER_USE_LENGTH_PREFIX_SERIALISER_COMMA typename V>,
+    std::map<K WORKER_USE_LENGTH_PREFIX_SERIALISER_COMMA V>)
 
 /**
  * Use `CommonProto` where possible.