Finish converting existing comments for internal API docs (#8146)

* Finish converting existing comments for internal API docs

99% of this was just reformatting existing comments. Only two exceptions:

- Expanded upon `BuildResult::status` compat note

- Split up file-level `symbol-table.hh` doc comments to get
  per-definition docs

Also fixed a few whitespace goofs, turning leading tabs to spaces and
removing trailing spaces.

Picking up from #8133

* Fix two things from comments

* Use triple-backtick not indent for `dumpPath`

* Convert GNU-style `\`..'` quotes to markdown style in API docs

This will render correctly.

3 files changed, 102 insertions, 43 deletions

diff --git a/src/libexpr/flake/flake.hh b/src/libexpr/flake/flake.hh
index b6f710288..c1d1b71e5 100644
--- a/src/libexpr/flake/flake.hh
+++ b/src/libexpr/flake/flake.hh
@@ -18,7 +18,8 @@ struct FlakeInput;
 
 typedef std::map<FlakeId, FlakeInput> FlakeInputs;
 
-/* FlakeInput is the 'Flake'-level parsed form of the "input" entries
+/**
+ * FlakeInput is the 'Flake'-level parsed form of the "input" entries
  * in the flake file.
  *
  * A FlakeInput is normally constructed by the 'parseFlakeInput'
@@ -42,7 +43,12 @@ typedef std::map<FlakeId, FlakeInput> FlakeInputs;
 struct FlakeInput
 {
     std::optional<FlakeRef> ref;
-    bool isFlake = true;  // true = process flake to get outputs, false = (fetched) static source path
+    /**
+     * true = process flake to get outputs
+     *
+     * false = (fetched) static source path
+     */
+    bool isFlake = true;
     std::optional<InputPath> follows;
     FlakeInputs overrides;
 };
@@ -56,23 +62,42 @@ struct ConfigFile
     void apply();
 };
 
-/* The contents of a flake.nix file. */
+/**
+ * The contents of a flake.nix file.
+ */
 struct Flake
 {
-    FlakeRef originalRef; // the original flake specification (by the user)
-    FlakeRef resolvedRef; // registry references and caching resolved to the specific underlying flake
-    FlakeRef lockedRef; // the specific local store result of invoking the fetcher
-    bool forceDirty = false; // pretend that 'lockedRef' is dirty
+    /**
+     * The original flake specification (by the user)
+     */
+    FlakeRef originalRef;
+    /**
+     * registry references and caching resolved to the specific underlying flake
+     */
+    FlakeRef resolvedRef;
+    /**
+     * the specific local store result of invoking the fetcher
+     */
+    FlakeRef lockedRef;
+    /**
+     * pretend that 'lockedRef' is dirty
+     */
+    bool forceDirty = false;
     std::optional<std::string> description;
     std::shared_ptr<const fetchers::Tree> sourceInfo;
     FlakeInputs inputs;
-    ConfigFile config; // 'nixConfig' attribute
+    /**
+     * 'nixConfig' attribute
+     */
+    ConfigFile config;
     ~Flake();
 };
 
 Flake getFlake(EvalState & state, const FlakeRef & flakeRef, bool allowLookup);
 
-/* Fingerprint of a locked flake; used as a cache key. */
+/**
+ * Fingerprint of a locked flake; used as a cache key.
+ */
 typedef Hash Fingerprint;
 
 struct LockedFlake
@@ -85,50 +110,72 @@ struct LockedFlake
 
 struct LockFlags
 {
-    /* Whether to ignore the existing lock file, creating a new one
-       from scratch. */
+    /**
+     * Whether to ignore the existing lock file, creating a new one
+     * from scratch.
+     */
     bool recreateLockFile = false;
 
-    /* Whether to update the lock file at all. If set to false, if any
-       change to the lock file is needed (e.g. when an input has been
-       added to flake.nix), you get a fatal error. */
+    /**
+     * Whether to update the lock file at all. If set to false, if any
+     * change to the lock file is needed (e.g. when an input has been
+     * added to flake.nix), you get a fatal error.
+     */
     bool updateLockFile = true;
 
-    /* Whether to write the lock file to disk. If set to true, if the
-       any changes to the lock file are needed and the flake is not
-       writable (i.e. is not a local Git working tree or similar), you
-       get a fatal error. If set to false, Nix will use the modified
-       lock file in memory only, without writing it to disk. */
+    /**
+     * Whether to write the lock file to disk. If set to true, if the
+     * any changes to the lock file are needed and the flake is not
+     * writable (i.e. is not a local Git working tree or similar), you
+     * get a fatal error. If set to false, Nix will use the modified
+     * lock file in memory only, without writing it to disk.
+     */
     bool writeLockFile = true;
 
-    /* Whether to use the registries to lookup indirect flake
-       references like 'nixpkgs'. */
+    /**
+     * Whether to use the registries to lookup indirect flake
+     * references like 'nixpkgs'.
+     */
     std::optional<bool> useRegistries = std::nullopt;
 
-    /* Whether to apply flake's nixConfig attribute to the configuration */
+    /**
+     * Whether to apply flake's nixConfig attribute to the configuration
+     */
 
     bool applyNixConfig = false;
 
-    /* Whether unlocked flake references (i.e. those without a Git
-       revision or similar) without a corresponding lock are
-       allowed. Unlocked flake references with a lock are always
-       allowed. */
+    /**
+     * Whether unlocked flake references (i.e. those without a Git
+     * revision or similar) without a corresponding lock are
+     * allowed. Unlocked flake references with a lock are always
+     * allowed.
+     */
     bool allowUnlocked = true;
 
-    /* Whether to commit changes to flake.lock. */
+    /**
+     * Whether to commit changes to flake.lock.
+     */
     bool commitLockFile = false;
 
-    /* The path to a lock file to read instead of the `flake.lock` file in the top-level flake */
+    /**
+     * The path to a lock file to read instead of the `flake.lock` file in the top-level flake
+     */
     std::optional<std::string> referenceLockFilePath;
 
-    /* The path to a lock file to write to instead of the `flake.lock` file in the top-level flake */
+    /**
+     * The path to a lock file to write to instead of the `flake.lock` file in the top-level flake
+     */
     std::optional<Path> outputLockFilePath;
 
-    /* Flake inputs to be overridden. */
+    /**
+     * Flake inputs to be overridden.
+     */
     std::map<InputPath, FlakeRef> inputOverrides;
 
-    /* Flake inputs to be updated. This means that any existing lock
-       for those inputs will be ignored. */
+    /**
+     * Flake inputs to be updated. This means that any existing lock
+     * for those inputs will be ignored.
+     */
     std::set<InputPath> inputUpdates;
 };
 
diff --git a/src/libexpr/flake/flakeref.hh b/src/libexpr/flake/flakeref.hh
index 23d19adb1..a7c9208c0 100644
--- a/src/libexpr/flake/flakeref.hh
+++ b/src/libexpr/flake/flakeref.hh
@@ -14,7 +14,8 @@ class Store;
 
 typedef std::string FlakeId;
 
-/* A flake reference specifies how to fetch a flake or raw source
+/**
+ * A flake reference specifies how to fetch a flake or raw source
  * (e.g. from a Git repository).  It is created from a URL-like syntax
  * (e.g. 'github:NixOS/patchelf'), an attrset representation (e.g. '{
  * type="github"; owner = "NixOS"; repo = "patchelf"; }'), or a local
@@ -33,14 +34,17 @@ typedef std::string FlakeId;
  * be lazy), but the fetcher can be invoked at any time via the
  * FlakeRef to ensure the store is populated with this input.
  */
-
 struct FlakeRef
 {
-    /* Fetcher-specific representation of the input, sufficient to
-       perform the fetch operation. */
+    /**
+     * Fetcher-specific representation of the input, sufficient to
+     * perform the fetch operation.
+     */
     fetchers::Input input;
 
-    /* sub-path within the fetched input that represents this input */
+    /**
+     * sub-path within the fetched input that represents this input
+     */
     Path subdir;
 
     bool operator==(const FlakeRef & other) const;
diff --git a/src/libexpr/flake/lockfile.hh b/src/libexpr/flake/lockfile.hh
index 6512509c5..0ac731b5d 100644
--- a/src/libexpr/flake/lockfile.hh
+++ b/src/libexpr/flake/lockfile.hh
@@ -16,9 +16,11 @@ typedef std::vector<FlakeId> InputPath;
 
 struct LockedNode;
 
-/* A node in the lock file. It has outgoing edges to other nodes (its
-   inputs). Only the root node has this type; all other nodes have
-   type LockedNode. */
+/**
+ * A node in the lock file. It has outgoing edges to other nodes (its
+ * inputs). Only the root node has this type; all other nodes have
+ * type LockedNode.
+ */
 struct Node : std::enable_shared_from_this<Node>
 {
     typedef std::variant<ref<LockedNode>, InputPath> Edge;
@@ -28,7 +30,9 @@ struct Node : std::enable_shared_from_this<Node>
     virtual ~Node() { }
 };
 
-/* A non-root node in the lock file. */
+/**
+ * A non-root node in the lock file.
+ */
 struct LockedNode : Node
 {
     FlakeRef lockedRef, originalRef;
@@ -63,7 +67,9 @@ struct LockFile
 
     void write(const Path & path) const;
 
-    /* Check whether this lock file has any unlocked inputs. */
+    /**
+     * Check whether this lock file has any unlocked inputs.
+     */
     std::optional<FlakeRef> isUnlocked() const;
 
     bool operator ==(const LockFile & other) const;
@@ -74,7 +80,9 @@ struct LockFile
 
     static std::string diff(const LockFile & oldLocks, const LockFile & newLocks);
 
-    /* Check that every 'follows' input target exists. */
+    /**
+     * Check that every 'follows' input target exists.
+     */
     void check();
 };