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

diff --git a/src/libstore/sqlite.hh b/src/libstore/sqlite.hh
index 86410f998..b735838ec 100644
--- a/src/libstore/sqlite.hh
+++ b/src/libstore/sqlite.hh
@@ -11,7 +11,9 @@ struct sqlite3_stmt;
 
 namespace nix {
 
-/* RAII wrapper to close a SQLite database automatically. */
+/**
+ * RAII wrapper to close a SQLite database automatically.
+ */
 struct SQLite
 {
     sqlite3 * db = 0;
@@ -23,7 +25,9 @@ struct SQLite
     ~SQLite();
     operator sqlite3 * () { return db; }
 
-    /* Disable synchronous mode, set truncate journal mode. */
+    /**
+     * Disable synchronous mode, set truncate journal mode.
+     */
     void isCache();
 
     void exec(const std::string & stmt);
@@ -31,7 +35,9 @@ struct SQLite
     uint64_t getLastInsertedRowId();
 };
 
-/* RAII wrapper to create and destroy SQLite prepared statements. */
+/**
+ * RAII wrapper to create and destroy SQLite prepared statements.
+ */
 struct SQLiteStmt
 {
     sqlite3 * db = 0;
@@ -43,7 +49,9 @@ struct SQLiteStmt
     ~SQLiteStmt();
     operator sqlite3_stmt * () { return stmt; }
 
-    /* Helper for binding / executing statements. */
+    /**
+     * Helper for binding / executing statements.
+     */
     class Use
     {
         friend struct SQLiteStmt;
@@ -56,7 +64,9 @@ struct SQLiteStmt
 
         ~Use();
 
-        /* Bind the next parameter. */
+        /**
+         * Bind the next parameter.
+         */
         Use & operator () (std::string_view value, bool notNull = true);
         Use & operator () (const unsigned char * data, size_t len, bool notNull = true);
         Use & operator () (int64_t value, bool notNull = true);
@@ -64,11 +74,15 @@ struct SQLiteStmt
 
         int step();
 
-        /* Execute a statement that does not return rows. */
+        /**
+         * Execute a statement that does not return rows.
+         */
         void exec();
 
-        /* For statements that return 0 or more rows. Returns true iff
-           a row is available. */
+        /**
+         * For statements that return 0 or more rows. Returns true iff
+         * a row is available.
+         */
         bool next();
 
         std::string getStr(int col);
@@ -82,8 +96,10 @@ struct SQLiteStmt
     }
 };
 
-/* RAII helper that ensures transactions are aborted unless explicitly
-   committed. */
+/**
+ * RAII helper that ensures transactions are aborted unless explicitly
+ * committed.
+ */
 struct SQLiteTxn
 {
     bool active = false;
@@ -125,8 +141,10 @@ MakeError(SQLiteBusy, SQLiteError);
 
 void handleSQLiteBusy(const SQLiteBusy & e);
 
-/* Convenience function for retrying a SQLite transaction when the
-   database is busy. */
+/**
+ * Convenience function for retrying a SQLite transaction when the
+ * database is busy.
+ */
 template<typename T, typename F>
 T retrySQLite(F && fun)
 {