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, 12 insertions, 6 deletions

diff --git a/src/libstore/binary-cache-store.hh b/src/libstore/binary-cache-store.hh
index 5e52d7844..49f271d24 100644
--- a/src/libstore/binary-cache-store.hh
+++ b/src/libstore/binary-cache-store.hh
@@ -46,6 +46,11 @@ struct BinaryCacheStoreConfig : virtual StoreConfig
         )"};
 };
 
+
+/**
+ * @note subclasses must implement at least one of the two
+ * virtual getFile() methods.
+ */
 class BinaryCacheStore : public virtual BinaryCacheStoreConfig,
     public virtual Store,
     public virtual LogStore
@@ -75,14 +80,15 @@ public:
         std::string && data,
         const std::string & mimeType);
 
-    /* Note: subclasses must implement at least one of the two
-       following getFile() methods. */
-
-    /* Dump the contents of the specified file to a sink. */
+    /**
+     * Dump the contents of the specified file to a sink.
+     */
     virtual void getFile(const std::string & path, Sink & sink);
 
-    /* Fetch the specified file and call the specified callback with
-       the result. A subclass may implement this asynchronously. */
+    /**
+     * Fetch the specified file and call the specified callback with
+     * the result. A subclass may implement this asynchronously.
+     */
     virtual void getFile(
         const std::string & path,
         Callback<std::optional<std::string>> callback) noexcept;