Fix most DoxyGen warnings

Helps with #11841.

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
-//! 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 <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 {
-using namespace std::filesystem;
-}
+namespace fs = 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)
 {