From 02f0294be09a2acf6b79ef88d9e8bcb231b99254 Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Tue, 12 Nov 2024 15:31:37 +0100 Subject: [PATCH 1/2] Fix most DoxyGen warnings Helps with #11841. --- src/external-api-docs/doxygen.cfg.in | 6 ++-- src/internal-api-docs/doxygen.cfg.in | 26 +++++++++++---- src/internal-api-docs/meson.build | 1 + src/libexpr-c/nix_api_expr.h | 2 +- src/libexpr-c/nix_api_value.h | 7 ++-- src/libexpr/eval.hh | 2 +- src/libexpr/nixexpr.hh | 2 +- src/libexpr/value/context.hh | 12 +++---- src/libfetchers/fetchers.cc | 10 ++++-- src/libstore-c/nix_api_store.h | 2 +- .../tests/derived-path.cc | 2 +- src/libstore-tests/serve-protocol.cc | 4 +++ src/libstore-tests/worker-protocol.cc | 4 +++ src/libstore/build/goal.hh | 10 +++--- src/libstore/build/worker.hh | 2 +- src/libstore/content-address.hh | 11 ++++--- .../length-prefixed-protocol-helper.hh | 32 +++++++++---------- src/libstore/machines.hh | 4 +-- src/libstore/outputs-spec.cc | 17 +++++++--- src/libstore/path.hh | 2 +- src/libstore/profiles.hh | 4 ++- src/libstore/serve-protocol-impl.hh | 7 ++-- src/libstore/ssh.hh | 2 +- src/libstore/store-api.hh | 8 ++--- src/libstore/store-dir-config.hh | 8 ++--- src/libstore/store-reference.hh | 22 ++++++------- src/libstore/worker-protocol-connection.hh | 12 +++---- src/libstore/worker-protocol-impl.hh | 7 ++-- src/libutil-c/nix_api_util.h | 2 +- .../tests/gtest-with-params.hh | 4 ++- src/libutil/args.cc | 3 -- src/libutil/args.hh | 2 +- src/libutil/checked-arithmetic.hh | 4 ++- src/libutil/file-content-address.hh | 2 +- src/libutil/file-system.cc | 4 +-- src/libutil/file-system.hh | 6 +--- src/libutil/git.hh | 2 +- src/libutil/json-utils.hh | 9 ++++-- src/libutil/std-hash.hh | 11 ++++--- src/libutil/tarfile.cc | 6 ++-- src/nix/eval.cc | 2 +- 41 files changed, 161 insertions(+), 124 deletions(-) diff --git a/src/external-api-docs/doxygen.cfg.in b/src/external-api-docs/doxygen.cfg.in index 7ae4c83df..8e235dae5 100644 --- a/src/external-api-docs/doxygen.cfg.in +++ b/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 diff --git a/src/internal-api-docs/doxygen.cfg.in b/src/internal-api-docs/doxygen.cfg.in index bf4c42d11..950497ca3 100644 --- a/src/internal-api-docs/doxygen.cfg.in +++ b/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/test/value \ + @src@/libexpr-test-support/tests \ + @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 diff --git a/src/internal-api-docs/meson.build b/src/internal-api-docs/meson.build index 54eb7e5dd..c0426621e 100644 --- a/src/internal-api-docs/meson.build +++ b/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', }, ) diff --git a/src/libexpr-c/nix_api_expr.h b/src/libexpr-c/nix_api_expr.h index 1764b49f3..e680f5ff1 100644 --- a/src/libexpr-c/nix_api_expr.h +++ b/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 */ diff --git a/src/libexpr-c/nix_api_value.h b/src/libexpr-c/nix_api_value.h index 044f68c9e..8a0813ebe 100644 --- a/src/libexpr-c/nix_api_value.h +++ b/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); diff --git a/src/libexpr/eval.hh b/src/libexpr/eval.hh index 7fe70af31..a1882dded 100644 --- a/src/libexpr/eval.hh +++ b/src/libexpr/eval.hh @@ -91,7 +91,7 @@ struct PrimOp const char * doc = nullptr; /** - * Add a trace item, `while calling the '' builtin` + * Add a trace item, while calling the `` builtin. * * This is used to remove the redundant item for `builtins.addErrorContext`. */ diff --git a/src/libexpr/nixexpr.hh b/src/libexpr/nixexpr.hh index bdf4e214a..948839bd9 100644 --- a/src/libexpr/nixexpr.hh +++ b/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. diff --git a/src/libexpr/value/context.hh b/src/libexpr/value/context.hh index 7f23cd3a4..d6791c6e4 100644 --- a/src/libexpr/value/context.hh +++ b/src/libexpr/value/context.hh @@ -28,7 +28,7 @@ struct NixStringContextElem { /** * Plain opaque path to some store object. * - * Encoded as just the path: ‘’. + * Encoded as just the 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 ‘=’. + * Encoded in the form `=`. */ struct DrvDeep { StorePath drvPath; @@ -50,7 +50,7 @@ struct NixStringContextElem { /** * Derivation output. * - * Encoded in the form ‘!!’. + * Encoded in the form `!!`. */ using Built = SingleDerivedPath::Built; @@ -68,9 +68,9 @@ struct NixStringContextElem { /** * Decode a context string, one of: - * - ‘’ - * - ‘=’ - * - ‘!!’ + * - `` + * - `=` + * - `!!` * * @param xpSettings Stop-gap to avoid globals during unit tests. */ diff --git a/src/libfetchers/fetchers.cc b/src/libfetchers/fetchers.cc index 5c06a6bcb..e15a460d0 100644 --- a/src/libfetchers/fetchers.cc +++ b/src/libfetchers/fetchers.cc @@ -475,7 +475,10 @@ namespace nlohmann { using namespace nix; -fetchers::PublicKey adl_serializer::from_json(const json & json) { +#ifndef DOXYGEN_SKIP + +fetchers::PublicKey adl_serializer::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::from_json(const json & return res; } -void adl_serializer::to_json(json & json, fetchers::PublicKey p) { +void adl_serializer::to_json(json & json, fetchers::PublicKey p) +{ json["type"] = p.type; json["key"] = p.key; } +#endif + } diff --git a/src/libstore-c/nix_api_store.h b/src/libstore-c/nix_api_store.h index 93208cb7c..282ccc285 100644 --- a/src/libstore-c/nix_api_store.h +++ b/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); diff --git a/src/libstore-test-support/tests/derived-path.cc b/src/libstore-test-support/tests/derived-path.cc index 091706dba..078615bbd 100644 --- a/src/libstore-test-support/tests/derived-path.cc +++ b/src/libstore-test-support/tests/derived-path.cc @@ -7,7 +7,7 @@ namespace rc { using namespace nix; -Gen Arbitrary::arbitrary() +Gen Arbitrary::arbitrary() { return gen::just(DerivedPath::Opaque { .path = *gen::arbitrary(), diff --git a/src/libstore-tests/serve-protocol.cc b/src/libstore-tests/serve-protocol.cc index 5171fea0f..3dbbf3879 100644 --- a/src/libstore-tests/serve-protocol.cc +++ b/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, diff --git a/src/libstore-tests/worker-protocol.cc b/src/libstore-tests/worker-protocol.cc index 1185c37f4..99b042d5b 100644 --- a/src/libstore-tests/worker-protocol.cc +++ b/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, diff --git a/src/libstore/build/goal.hh b/src/libstore/build/goal.hh index 9c6a40c84..1dd7ed525 100644 --- a/src/libstore/build/goal.hh +++ b/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(); diff --git a/src/libstore/build/worker.hh b/src/libstore/build/worker.hh index e083dbea6..f5e617208 100644 --- a/src/libstore/build/worker.hh +++ b/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 makePathSubstitutionGoal(const StorePath & storePath, RepairFlag repair = NoRepair, std::optional ca = std::nullopt); std::shared_ptr makeDrvOutputSubstitutionGoal(const DrvOutput & id, RepairFlag repair = NoRepair, std::optional ca = std::nullopt); diff --git a/src/libstore/content-address.hh b/src/libstore/content-address.hh index bb515013a..2b5d1296a 100644 --- a/src/libstore/content-address.hh +++ b/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:’ + * `text:sha256:` * * - `FixedIngestionMethod`: - * ‘fixed:::’ + * `fixed:::` */ struct ContentAddress { diff --git a/src/libstore/length-prefixed-protocol-helper.hh b/src/libstore/length-prefixed-protocol-helper.hh index 0cf950a47..7e977bbf1 100644 --- a/src/libstore/length-prefixed-protocol-helper.hh +++ b/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 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 using S = typename Inner::template Serialise; \ } @@ -60,9 +59,8 @@ template LENGTH_PREFIXED_PROTO_HELPER(Inner, std::tuple); template -#define _X std::map -LENGTH_PREFIXED_PROTO_HELPER(Inner, _X); -#undef _X +#define LENGTH_PREFIXED_PROTO_HELPER_X std::map +LENGTH_PREFIXED_PROTO_HELPER(Inner, LENGTH_PREFIXED_PROTO_HELPER_X); template std::vector diff --git a/src/libstore/machines.hh b/src/libstore/machines.hh index 983652d5f..b70ab9078 100644 --- a/src/libstore/machines.hh +++ b/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 & features) const; /** - * @return @Whether `mandatoryFeatures` is a subset of `features` + * @return Whether `mandatoryFeatures` is a subset of `features`. */ bool mandatoryMet(const std::set & features) const; diff --git a/src/libstore/outputs-spec.cc b/src/libstore/outputs-spec.cc index f5ecbd74b..b623a975c 100644 --- a/src/libstore/outputs-spec.cc +++ b/src/libstore/outputs-spec.cc @@ -153,7 +153,10 @@ namespace nlohmann { using namespace nix; -OutputsSpec adl_serializer::from_json(const json & json) { +#ifndef DOXYGEN_SKIP + +OutputsSpec adl_serializer::from_json(const json & json) +{ auto names = json.get(); if (names == StringSet({"*"})) return OutputsSpec::All {}; @@ -161,7 +164,8 @@ OutputsSpec adl_serializer::from_json(const json & json) { return OutputsSpec::Names { std::move(names) }; } -void adl_serializer::to_json(json & json, OutputsSpec t) { +void adl_serializer::to_json(json & json, OutputsSpec t) +{ std::visit(overloaded { [&](const OutputsSpec::All &) { json = std::vector({"*"}); @@ -172,8 +176,8 @@ void adl_serializer::to_json(json & json, OutputsSpec t) { }, t.raw); } - -ExtendedOutputsSpec adl_serializer::from_json(const json & json) { +ExtendedOutputsSpec adl_serializer::from_json(const json & json) +{ if (json.is_null()) return ExtendedOutputsSpec::Default {}; else { @@ -181,7 +185,8 @@ ExtendedOutputsSpec adl_serializer::from_json(const json & } } -void adl_serializer::to_json(json & json, ExtendedOutputsSpec t) { +void adl_serializer::to_json(json & json, ExtendedOutputsSpec t) +{ std::visit(overloaded { [&](const ExtendedOutputsSpec::Default &) { json = nullptr; @@ -192,4 +197,6 @@ void adl_serializer::to_json(json & json, ExtendedOutputsSp }, t.raw); } +#endif + } diff --git a/src/libstore/path.hh b/src/libstore/path.hh index 2380dc6a2..902262362 100644 --- a/src/libstore/path.hh +++ b/src/libstore/path.hh @@ -81,7 +81,7 @@ typedef std::set StorePathSet; typedef std::vector 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"; diff --git a/src/libstore/profiles.hh b/src/libstore/profiles.hh index b10a72330..33fcf04b3 100644 --- a/src/libstore/profiles.hh +++ b/src/libstore/profiles.hh @@ -1,6 +1,8 @@ #pragma once /** - * @file Implementation of Profiles. + * @file + * + * Implementation of Profiles. * * See the manual for additional information. */ diff --git a/src/libstore/serve-protocol-impl.hh b/src/libstore/serve-protocol-impl.hh index 6f3b177ac..099eade64 100644 --- a/src/libstore/serve-protocol-impl.hh +++ b/src/libstore/serve-protocol-impl.hh @@ -29,11 +29,10 @@ SERVE_USE_LENGTH_PREFIX_SERIALISER(template, std::vector) SERVE_USE_LENGTH_PREFIX_SERIALISER(template, std::set) SERVE_USE_LENGTH_PREFIX_SERIALISER(template, std::tuple) -#define COMMA_ , +#define SERVE_USE_LENGTH_PREFIX_SERIALISER_COMMA , SERVE_USE_LENGTH_PREFIX_SERIALISER( - template, - std::map) -#undef COMMA_ + template, + std::map) /** * Use `CommonProto` where possible. diff --git a/src/libstore/ssh.hh b/src/libstore/ssh.hh index 4097134d0..85be704ec 100644 --- a/src/libstore/ssh.hh +++ b/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. */ diff --git a/src/libstore/store-api.hh b/src/libstore/store-api.hh index 8288cfdf0..f45012061 100644 --- a/src/libstore/store-api.hh +++ b/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/-x rather than - * /nix/store/-). Use queryPathInfo() to obtain the + * backends, the name part of store paths may be replaced by `x` + * (i.e. you'll get `/nix/store/-x` rather than + * `/nix/store/-`). Use queryPathInfo() to obtain the * full store path. FIXME: should return a set of - * std::variant to get rid of this hack. + * `std::variant` to get rid of this hack. */ virtual StorePathSet queryAllValidPaths() { unsupported("queryAllValidPaths"); } diff --git a/src/libstore/store-dir-config.hh b/src/libstore/store-dir-config.hh index 64c0dd8b7..fd4332b91 100644 --- a/src/libstore/store-dir-config.hh +++ b/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/-/ into - * /nix/store/- and /. + * Split a path like `/nix/store/-/` into + * `/nix/store/-` and `/`. */ std::pair toStorePath(PathView path) const; diff --git a/src/libstore/store-reference.hh b/src/libstore/store-reference.hh index 459cea9c2..7100a1db0 100644 --- a/src/libstore/store-reference.hh +++ b/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://’: The Nix store accessed via a Unix domain socket - * connection to nix-daemon, with the socket located at . + * - `unix://`: The Nix store accessed via a Unix domain socket + * connection to nix-daemon, with the socket located at ``. * - * - ‘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://’: A binary cache stored in . + * - `file://`: A binary cache stored in ``. * - * - ‘https://’: A binary cache accessed via HTTP. + * - `https://`: A binary cache accessed via HTTP. * - * - ‘s3://’: A writable binary cache stored on Amazon's Simple + * - `s3://`: A writable binary cache stored on Amazon's Simple * Storage Service. * - * - ‘ssh://[user@]’: A remote Nix store accessed by running - * ‘nix-store --serve’ via SSH. + * - `ssh://[user@]`: 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 { diff --git a/src/libstore/worker-protocol-connection.hh b/src/libstore/worker-protocol-connection.hh index 9665067dd..c2f446db1 100644 --- a/src/libstore/worker-protocol-connection.hh +++ b/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> 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> handshake( diff --git a/src/libstore/worker-protocol-impl.hh b/src/libstore/worker-protocol-impl.hh index 026cc37bc..87398df90 100644 --- a/src/libstore/worker-protocol-impl.hh +++ b/src/libstore/worker-protocol-impl.hh @@ -29,11 +29,10 @@ WORKER_USE_LENGTH_PREFIX_SERIALISER(template, std::vector) WORKER_USE_LENGTH_PREFIX_SERIALISER(template, std::set) WORKER_USE_LENGTH_PREFIX_SERIALISER(template, std::tuple) -#define COMMA_ , +#define WORKER_USE_LENGTH_PREFIX_SERIALISER_COMMA , WORKER_USE_LENGTH_PREFIX_SERIALISER( - template, - std::map) -#undef COMMA_ + template, + std::map) /** * Use `CommonProto` where possible. diff --git a/src/libutil-c/nix_api_util.h b/src/libutil-c/nix_api_util.h index 6790a6964..43f9fa9dc 100644 --- a/src/libutil-c/nix_api_util.h +++ b/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 * @{ */ /** diff --git a/src/libutil-test-support/tests/gtest-with-params.hh b/src/libutil-test-support/tests/gtest-with-params.hh index 323a083fe..d72aec4fd 100644 --- a/src/libutil-test-support/tests/gtest-with-params.hh +++ b/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. */ diff --git a/src/libutil/args.cc b/src/libutil/args.cc index 4e87389d6..385b6cd34 100644 --- a/src/libutil/args.cc +++ b/src/libutil/args.cc @@ -91,9 +91,6 @@ struct Parser { /** * @brief Parse the next character(s) - * - * @param r - * @return std::shared_ptr */ virtual void operator()(std::shared_ptr & state, Strings & r) = 0; diff --git a/src/libutil/args.hh b/src/libutil/args.hh index 127a0809e..c30d6cef8 100644 --- a/src/libutil/args.hh +++ b/src/libutil/args.hh @@ -371,7 +371,7 @@ using Commands = std::map()>>; /** * An argument parser that supports multiple subcommands, - * i.e. ‘ ’. + * i.e. ` `. */ class MultiCommand : virtual public Args { diff --git a/src/libutil/checked-arithmetic.hh b/src/libutil/checked-arithmetic.hh index 55d6ad205..dcc6d86af 100644 --- a/src/libutil/checked-arithmetic.hh +++ b/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 diff --git a/src/libutil/file-content-address.hh b/src/libutil/file-content-address.hh index 0c584ea8a..226068387 100644 --- a/src/libutil/file-content-address.hh +++ b/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, diff --git a/src/libutil/file-system.cc b/src/libutil/file-system.cc index fd51d7d3c..2802bbf98 100644 --- a/src/libutil/file-system.cc +++ b/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; diff --git a/src/libutil/file-system.hh b/src/libutil/file-system.hh index eb3e4ec66..da864d500 100644 --- a/src/libutil/file-system.hh +++ b/src/libutil/file-system.hh @@ -126,8 +126,6 @@ std::optional 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. * diff --git a/src/libutil/git.hh b/src/libutil/git.hh index 1dbdb7335..1a6a7c333 100644 --- a/src/libutil/git.hh +++ b/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. */ diff --git a/src/libutil/json-utils.hh b/src/libutil/json-utils.hh index a61c9cada..546334e1e 100644 --- a/src/libutil/json-utils.hh +++ b/src/libutil/json-utils.hh @@ -91,12 +91,14 @@ namespace nlohmann { * round trip. We do that with a static assert. */ template -struct adl_serializer> { +struct adl_serializer> +{ /** * @brief Convert a JSON type to an `optional` treating * `null` as `std::nullopt`. */ - static void from_json(const json & json, std::optional & t) { + static void from_json(const json & json, std::optional & t) + { static_assert( nix::json_avoids_null::value, "null is already in use for underlying type's JSON"); @@ -109,7 +111,8 @@ struct adl_serializer> { * @brief Convert an optional type to a JSON type treating `std::nullopt` * as `null`. */ - static void to_json(json & json, const std::optional & t) { + static void to_json(json & json, const std::optional & t) + { static_assert( nix::json_avoids_null::value, "null is already in use for underlying type's JSON"); diff --git a/src/libutil/std-hash.hh b/src/libutil/std-hash.hh index c359d11ca..f99faac46 100644 --- a/src/libutil/std-hash.hh +++ b/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 -//! Nix hashing) +/** + * @file + * + * Hashing utilities for use with `std::unordered_map`, etc. (i.e. low + * level implementation logic, not domain logic like Nix hashing). + */ #include 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) {} diff --git a/src/libutil/tarfile.cc b/src/libutil/tarfile.cc index a8a22d283..397169757 100644 --- a/src/libutil/tarfile.cc +++ b/src/libutil/tarfile.cc @@ -8,9 +8,7 @@ namespace nix { -namespace fs { -using namespace std::filesystem; -} +namespace fs = std::filesystem; namespace { @@ -106,7 +104,7 @@ TarArchive::TarArchive(Source & source, bool raw, std::optional 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) { diff --git a/src/nix/eval.cc b/src/nix/eval.cc index 7811b77ed..a8c18fef6 100644 --- a/src/nix/eval.cc +++ b/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 recurse; From 37f4c71d1cea16cbcfc0080a7b25d549f14e39e7 Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Tue, 12 Nov 2024 21:10:01 +0100 Subject: [PATCH 2/2] Don't change nix::fs for now --- src/libutil/file-system.cc | 2 +- src/libutil/file-system.hh | 4 ++++ src/libutil/tarfile.cc | 4 +++- src/nix/eval.cc | 2 +- 4 files changed, 9 insertions(+), 3 deletions(-) diff --git a/src/libutil/file-system.cc b/src/libutil/file-system.cc index 2802bbf98..92996ea47 100644 --- a/src/libutil/file-system.cc +++ b/src/libutil/file-system.cc @@ -29,7 +29,7 @@ namespace nix { -namespace fs = std::filesystem; +namespace fs { using namespace std::filesystem; } /** * Treat the string as possibly an absolute path, by inspecting the diff --git a/src/libutil/file-system.hh b/src/libutil/file-system.hh index da864d500..4c08cdf58 100644 --- a/src/libutil/file-system.hh +++ b/src/libutil/file-system.hh @@ -126,6 +126,8 @@ std::optional maybeLstat(const Path & path); */ bool pathExists(const Path & path); +namespace fs { + /** * ``` * symlink_exists(p) = std::filesystem::exists(std::filesystem::symlink_status(p)) @@ -139,6 +141,8 @@ 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 diff --git a/src/libutil/tarfile.cc b/src/libutil/tarfile.cc index 397169757..e412930bb 100644 --- a/src/libutil/tarfile.cc +++ b/src/libutil/tarfile.cc @@ -8,7 +8,9 @@ namespace nix { -namespace fs = std::filesystem; +namespace fs { +using namespace std::filesystem; +} namespace { diff --git a/src/nix/eval.cc b/src/nix/eval.cc index a8c18fef6..7811b77ed 100644 --- a/src/nix/eval.cc +++ b/src/nix/eval.cc @@ -77,7 +77,7 @@ struct CmdEval : MixJSON, InstallableValueCommand, MixReadOnlyOption if (writeTo) { stopProgressBar(); - if (nix::symlink_exists(*writeTo)) + if (fs::symlink_exists(*writeTo)) throw Error("path '%s' already exists", writeTo->string()); std::function recurse;