Fix most DoxyGen warnings

Helps with NixOS#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,19 +43,20 @@ INPUT                  = \
   @src@/libexpr/flake \
   @src@/libexpr-tests \
   @src@/libexpr-tests/value \
-  @src@/libexpr-test-support/test \
-  @src@/libexpr-test-support/test/value \
+  @src@/libexpr-test-support/tests \
+  @src@/libexpr-test-support/tests/value \
   @src@/libexpr/value \
   @src@/libfetchers \
   @src@/libmain \
   @src@/libstore \
   @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
- * @brief Create your own primops
+/** @defgroup primops Adding 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>’
-     * - ‘!<name>!<path>’
+     * - `<path>`
+     * - `=<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
-         * 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>