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, 51 insertions, 32 deletions

diff --git a/src/libstore/path-info.hh b/src/libstore/path-info.hh
index b28bf751c..9af1309a0 100644
--- a/src/libstore/path-info.hh
+++ b/src/libstore/path-info.hh
@@ -19,8 +19,14 @@ struct SubstitutablePathInfo
 {
     std::optional<StorePath> deriver;
     StorePathSet references;
-    uint64_t downloadSize; /* 0 = unknown or inapplicable */
-    uint64_t narSize; /* 0 = unknown */
+    /**
+     * 0 = unknown or inapplicable
+     */
+    uint64_t downloadSize;
+    /**
+     * 0 = unknown
+     */
+    uint64_t narSize;
 };
 
 typedef std::map<StorePath, SubstitutablePathInfo> SubstitutablePathInfos;
@@ -30,35 +36,40 @@ struct ValidPathInfo
 {
     StorePath path;
     std::optional<StorePath> deriver;
-    // TODO document this
+    /**
+     * \todo document this
+     */
     Hash narHash;
     StorePathSet references;
     time_t registrationTime = 0;
     uint64_t narSize = 0; // 0 = unknown
     uint64_t id; // internal use only
 
-    /* Whether the path is ultimately trusted, that is, it's a
-       derivation output that was built locally. */
+    /**
+     * Whether the path is ultimately trusted, that is, it's a
+     * derivation output that was built locally.
+     */
     bool ultimate = false;
 
     StringSet sigs; // note: not necessarily verified
 
-    /* If non-empty, an assertion that the path is content-addressed,
-       i.e., that the store path is computed from a cryptographic hash
-       of the contents of the path, plus some other bits of data like
-       the "name" part of the path. Such a path doesn't need
-       signatures, since we don't have to trust anybody's claim that
-       the path is the output of a particular derivation. (In the
-       extensional store model, we have to trust that the *contents*
-       of an output path of a derivation were actually produced by
-       that derivation. In the intensional model, we have to trust
-       that a particular output path was produced by a derivation; the
-       path then implies the contents.)
-
-       Ideally, the content-addressability assertion would just be a Boolean,
-       and the store path would be computed from the name component, ‘narHash’
-       and ‘references’. However, we support many types of content addresses.
-    */
+    /**
+     * If non-empty, an assertion that the path is content-addressed,
+     * i.e., that the store path is computed from a cryptographic hash
+     * of the contents of the path, plus some other bits of data like
+     * the "name" part of the path. Such a path doesn't need
+     * signatures, since we don't have to trust anybody's claim that
+     * the path is the output of a particular derivation. (In the
+     * extensional store model, we have to trust that the *contents*
+     * of an output path of a derivation were actually produced by
+     * that derivation. In the intensional model, we have to trust
+     * that a particular output path was produced by a derivation; the
+     * path then implies the contents.)
+     *
+     * Ideally, the content-addressability assertion would just be a Boolean,
+     * and the store path would be computed from the name component, ‘narHash’
+     * and ‘references’. However, we support many types of content addresses.
+     */
     std::optional<ContentAddress> ca;
 
     bool operator == (const ValidPathInfo & i) const
@@ -69,27 +80,35 @@ struct ValidPathInfo
             && references == i.references;
     }
 
-    /* Return a fingerprint of the store path to be used in binary
-       cache signatures. It contains the store path, the base-32
-       SHA-256 hash of the NAR serialisation of the path, the size of
-       the NAR, and the sorted references. The size field is strictly
-       speaking superfluous, but might prevent endless/excessive data
-       attacks. */
+    /**
+     * Return a fingerprint of the store path to be used in binary
+     * cache signatures. It contains the store path, the base-32
+     * SHA-256 hash of the NAR serialisation of the path, the size of
+     * the NAR, and the sorted references. The size field is strictly
+     * speaking superfluous, but might prevent endless/excessive data
+     * attacks.
+     */
     std::string fingerprint(const Store & store) const;
 
     void sign(const Store & store, const SecretKey & secretKey);
 
-    /* Return true iff the path is verifiably content-addressed. */
+    /**
+     * @return true iff the path is verifiably content-addressed.
+     */
     bool isContentAddressed(const Store & store) const;
 
     static const size_t maxSigs = std::numeric_limits<size_t>::max();
 
-    /* Return the number of signatures on this .narinfo that were
-       produced by one of the specified keys, or maxSigs if the path
-       is content-addressed. */
+    /**
+     * Return the number of signatures on this .narinfo that were
+     * produced by one of the specified keys, or maxSigs if the path
+     * is content-addressed.
+     */
     size_t checkSignatures(const Store & store, const PublicKeys & publicKeys) const;
 
-    /* Verify a single signature. */
+    /**
+     * Verify a single signature.
+     */
     bool checkSignature(const Store & store, const PublicKeys & publicKeys, const std::string & sig) const;
 
     Strings shortRefs() const;