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, 50 insertions, 20 deletions

diff --git a/src/libstore/build/goal.hh b/src/libstore/build/goal.hh
index 924a8bbd5..f4bf6f38b 100644
--- a/src/libstore/build/goal.hh
+++ b/src/libstore/build/goal.hh
@@ -7,11 +7,15 @@
 
 namespace nix {
 
-/* Forward definition. */
+/**
+ * Forward definition.
+ */
 struct Goal;
 class Worker;
 
-/* A pointer to a goal. */
+/**
+ * A pointer to a goal.
+ */
 typedef std::shared_ptr<Goal> GoalPtr;
 typedef std::weak_ptr<Goal> WeakGoalPtr;
 
@@ -19,48 +23,72 @@ struct CompareGoalPtrs {
     bool operator() (const GoalPtr & a, const GoalPtr & b) const;
 };
 
-/* Set of goals. */
+/**
+ * Set of goals.
+ */
 typedef std::set<GoalPtr, CompareGoalPtrs> Goals;
 typedef std::set<WeakGoalPtr, std::owner_less<WeakGoalPtr>> WeakGoals;
 
-/* A map of paths to goals (and the other way around). */
+/**
+ * A map of paths to goals (and the other way around).
+ */
 typedef std::map<StorePath, WeakGoalPtr> WeakGoalMap;
 
 struct Goal : public std::enable_shared_from_this<Goal>
 {
     typedef enum {ecBusy, ecSuccess, ecFailed, ecNoSubstituters, ecIncompleteClosure} ExitCode;
 
-    /* Backlink to the worker. */
+    /**
+     * Backlink to the worker.
+     */
     Worker & worker;
 
-    /* Goals that this goal is waiting for. */
+    /**
+     * Goals that this goal is waiting for.
+     */
     Goals waitees;
 
-    /* Goals waiting for this one to finish.  Must use weak pointers
-       here to prevent cycles. */
+    /**
+     * Goals waiting for this one to finish.  Must use weak pointers
+     * here to prevent cycles.
+     */
     WeakGoals waiters;
 
-    /* Number of goals we are/were waiting for that have failed. */
+    /**
+     * Number of goals we are/were waiting for that have failed.
+     */
     size_t nrFailed = 0;
 
-    /* Number of substitution goals we are/were waiting for that
-       failed because there are no substituters. */
+    /**
+     * Number of substitution goals we are/were waiting for that
+     * failed because there are no substituters.
+     */
     size_t nrNoSubstituters = 0;
 
-    /* Number of substitution goals we are/were waiting for that
-       failed because they had unsubstitutable references. */
+    /**
+     * Number of substitution goals we are/were waiting for that
+     * failed because they had unsubstitutable references.
+     */
     size_t nrIncompleteClosure = 0;
 
-    /* Name of this goal for debugging purposes. */
+    /**
+     * Name of this goal for debugging purposes.
+     */
     std::string name;
 
-    /* Whether the goal is finished. */
+    /**
+     * Whether the goal is finished.
+     */
     ExitCode exitCode = ecBusy;
 
-    /* Build result. */
+    /**
+     * Build result.
+     */
     BuildResult buildResult;
 
-    /* Exception containing an error message, if any. */
+    /**
+     * Exception containing an error message, if any.
+     */
     std::optional<Error> ex;
 
     Goal(Worker & worker, DerivedPath path)
@@ -96,9 +124,11 @@ struct Goal : public std::enable_shared_from_this<Goal>
         return name;
     }
 
-    /* Callback in case of a timeout.  It should wake up its waiters,
-       get rid of any running child processes that are being monitored
-       by the worker (important!), etc. */
+    /**
+     * Callback in case of a timeout.  It should wake up its waiters,
+     * get rid of any running child processes that are being monitored
+     * by the worker (important!), etc.
+     */
     virtual void timedOut(Error && ex) = 0;
 
     virtual std::string key() = 0;