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.

1 files changed, 26 insertions, 15 deletions

diff --git a/src/libfetchers/fetchers.hh b/src/libfetchers/fetchers.hh
index acdecea57..498ad7e4d 100644
--- a/src/libfetchers/fetchers.hh
+++ b/src/libfetchers/fetchers.hh
@@ -21,14 +21,14 @@ struct Tree
 
 struct InputScheme;
 
-/* The Input object is generated by a specific fetcher, based on the
+/**
+ * The Input object is generated by a specific fetcher, based on the
  * user-supplied input attribute in the flake.nix file, and contains
  * the information that the specific fetcher needs to perform the
  * actual fetch.  The Input object is most commonly created via the
  * "fromURL()" or "fromAttrs()" static functions which are provided
  * the url or attrset specified in the flake file.
  */
-
 struct Input
 {
     friend struct InputScheme;
@@ -38,7 +38,9 @@ struct Input
     bool locked = false;
     bool direct = true;
 
-    /* path of the parent of this input, used for relative path resolution */
+    /**
+     * path of the parent of this input, used for relative path resolution
+     */
     std::optional<Path> parent;
 
 public:
@@ -56,27 +58,35 @@ public:
 
     Attrs toAttrs() const;
 
-    /* Check whether this is a "direct" input, that is, not
-       one that goes through a registry. */
+    /**
+     * Check whether this is a "direct" input, that is, not
+     * one that goes through a registry.
+     */
     bool isDirect() const { return direct; }
 
-    /* Check whether this is a "locked" input, that is,
-       one that contains a commit hash or content hash. */
+    /**
+     * Check whether this is a "locked" input, that is,
+     * one that contains a commit hash or content hash.
+     */
     bool isLocked() const { return locked; }
 
-    /* Check whether the input carries all necessary info required
-       for cache insertion and substitution.
-       These fields are used to uniquely identify cached trees
-       within the "tarball TTL" window without necessarily
-       indicating that the input's origin is unchanged. */
+    /**
+     * Check whether the input carries all necessary info required
+     * for cache insertion and substitution.
+     * These fields are used to uniquely identify cached trees
+     * within the "tarball TTL" window without necessarily
+     * indicating that the input's origin is unchanged.
+     */
     bool hasAllInfo() const;
 
     bool operator ==(const Input & other) const;
 
     bool contains(const Input & other) const;
 
-    /* Fetch the input into the Nix store, returning the location in
-       the Nix store and the locked input. */
+    /**
+     * Fetch the input into the Nix store, returning the location in
+     * the Nix store and the locked input.
+     */
     std::pair<Tree, Input> fetch(ref<Store> store) const;
 
     Input applyOverrides(
@@ -105,7 +115,8 @@ public:
 };
 
 
-/* The InputScheme represents a type of fetcher.  Each fetcher
+/**
+ * The InputScheme represents a type of fetcher.  Each fetcher
  * registers with nix at startup time.  When processing an input for a
  * flake, each scheme is given an opportunity to "recognize" that
  * input from the url or attributes in the flake file's specification