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

diff --git a/src/libstore/build/substitution-goal.hh b/src/libstore/build/substitution-goal.hh
index 1add9eb14..c2b7fc95a 100644
--- a/src/libstore/build/substitution-goal.hh
+++ b/src/libstore/build/substitution-goal.hh
@@ -11,38 +11,58 @@ class Worker;
 
 struct PathSubstitutionGoal : public Goal
 {
-    /* The store path that should be realised through a substitute. */
+    /**
+     * The store path that should be realised through a substitute.
+     */
     StorePath storePath;
 
-    /* The path the substituter refers to the path as. This will be
-       different when the stores have different names. */
+    /**
+     * The path the substituter refers to the path as. This will be
+     * different when the stores have different names.
+     */
     std::optional<StorePath> subPath;
 
-    /* The remaining substituters. */
+    /**
+     * The remaining substituters.
+     */
     std::list<ref<Store>> subs;
 
-    /* The current substituter. */
+    /**
+     * The current substituter.
+     */
     std::shared_ptr<Store> sub;
 
-    /* Whether a substituter failed. */
+    /**
+     * Whether a substituter failed.
+     */
     bool substituterFailed = false;
 
-    /* Path info returned by the substituter's query info operation. */
+    /**
+     * Path info returned by the substituter's query info operation.
+     */
     std::shared_ptr<const ValidPathInfo> info;
 
-    /* Pipe for the substituter's standard output. */
+    /**
+     * Pipe for the substituter's standard output.
+     */
     Pipe outPipe;
 
-    /* The substituter thread. */
+    /**
+     * The substituter thread.
+     */
     std::thread thr;
 
     std::promise<void> promise;
 
-    /* Whether to try to repair a valid path. */
+    /**
+     * Whether to try to repair a valid path.
+     */
     RepairFlag repair;
 
-    /* Location where we're downloading the substitute.  Differs from
-       storePath when doing a repair. */
+    /**
+     * Location where we're downloading the substitute.  Differs from
+     * storePath when doing a repair.
+     */
     Path destPath;
 
     std::unique_ptr<MaintainCount<uint64_t>> maintainExpectedSubstitutions,
@@ -51,7 +71,9 @@ struct PathSubstitutionGoal : public Goal
     typedef void (PathSubstitutionGoal::*GoalState)();
     GoalState state;
 
-    /* Content address for recomputing store path */
+    /**
+     * Content address for recomputing store path
+     */
     std::optional<ContentAddress> ca;
 
     void done(
@@ -65,16 +87,20 @@ public:
 
     void timedOut(Error && ex) override { abort(); };
 
+    /**
+     * We prepend "a$" to the key name to ensure substitution goals
+     * happen before derivation goals.
+     */
     std::string key() override
     {
-        /* "a$" ensures substitution goals happen before derivation
-           goals. */
         return "a$" + std::string(storePath.name()) + "$" + worker.store.printStorePath(storePath);
     }
 
     void work() override;
 
-    /* The states. */
+    /**
+     * The states.
+     */
     void init();
     void tryNext();
     void gotInfo();
@@ -82,7 +108,9 @@ public:
     void tryToRun();
     void finished();
 
-    /* Callback used by the worker to write to the log. */
+    /**
+     * Callback used by the worker to write to the log.
+     */
     void handleChildOutput(int fd, std::string_view data) override;
     void handleEOF(int fd) override;