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, 39 insertions, 17 deletions

diff --git a/src/libstore/build-result.hh b/src/libstore/build-result.hh
index a12c599d9..27d1a1b6c 100644
--- a/src/libstore/build-result.hh
+++ b/src/libstore/build-result.hh
@@ -12,9 +12,12 @@ namespace nix {
 
 struct BuildResult
 {
-    /* Note: don't remove status codes, and only add new status codes
-       at the end of the list, to prevent client/server
-       incompatibilities in the nix-store --serve protocol. */
+    /**
+     * @note This is directly used in the nix-store --serve protocol.
+     * That means we need to worry about compatability across versions.
+     * Therefore, don't remove status codes, and only add new status
+     * codes at the end of the list.
+     */
     enum Status {
         Built = 0,
         Substituted,
@@ -22,8 +25,10 @@ struct BuildResult
         PermanentFailure,
         InputRejected,
         OutputRejected,
-        TransientFailure, // possibly transient
-        CachedFailure, // no longer used
+        /// possibly transient
+        TransientFailure,
+        /// no longer used
+        CachedFailure,
         TimedOut,
         MiscFailure,
         DependencyFailed,
@@ -33,7 +38,12 @@ struct BuildResult
         NoSubstituters,
     } status = MiscFailure;
 
-    // FIXME: include entire ErrorInfo object.
+    /**
+     * Information about the error if the build failed.
+     *
+     * @todo This should be an entire ErrorInfo object, not just a
+     * string, for richer information.
+     */
     std::string errorMsg;
 
     std::string toString() const {
@@ -60,27 +70,39 @@ struct BuildResult
         return strStatus + ((errorMsg == "") ? "" : " : " + errorMsg);
     }
 
-    /* How many times this build was performed. */
+    /**
+     * How many times this build was performed.
+     */
     unsigned int timesBuilt = 0;
 
-    /* If timesBuilt > 1, whether some builds did not produce the same
-       result. (Note that 'isNonDeterministic = false' does not mean
-       the build is deterministic, just that we don't have evidence of
-       non-determinism.) */
+    /**
+     * If timesBuilt > 1, whether some builds did not produce the same
+     * result. (Note that 'isNonDeterministic = false' does not mean
+     * the build is deterministic, just that we don't have evidence of
+     * non-determinism.)
+     */
     bool isNonDeterministic = false;
 
-    /* The derivation we built or the store path we substituted. */
+    /**
+     * The derivation we built or the store path we substituted.
+     */
     DerivedPath path;
 
-    /* For derivations, a mapping from the names of the wanted outputs
-       to actual paths. */
+    /**
+     * For derivations, a mapping from the names of the wanted outputs
+     * to actual paths.
+     */
     DrvOutputs builtOutputs;
 
-    /* The start/stop times of the build (or one of the rounds, if it
-       was repeated). */
+    /**
+     * The start/stop times of the build (or one of the rounds, if it
+     * was repeated).
+     */
     time_t startTime = 0, stopTime = 0;
 
-    /* User and system CPU time the build took. */
+    /**
+     * User and system CPU time the build took.
+     */
     std::optional<std::chrono::microseconds> cpuUser, cpuSystem;
 
     bool success()