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

diff --git a/src/libstore/profiles.hh b/src/libstore/profiles.hh
index 6a5965390..4e1f42e83 100644
--- a/src/libstore/profiles.hh
+++ b/src/libstore/profiles.hh
@@ -1,7 +1,7 @@
 #pragma once
 ///@file
 
-#include "types.hh"
+ #include "types.hh"
 #include "pathlocks.hh"
 
 #include <time.h>
@@ -24,9 +24,11 @@ struct Generation
 typedef std::list<Generation> Generations;
 
 
-/* Returns the list of currently present generations for the specified
-   profile, sorted by generation number. Also returns the number of
-   the current generation. */
+/**
+ * Returns the list of currently present generations for the specified
+ * profile, sorted by generation number. Also returns the number of
+ * the current generation.
+ */
 std::pair<Generations, std::optional<GenerationNumber>> findGenerations(Path profile);
 
 class LocalFSStore;
@@ -47,26 +49,32 @@ void deleteGenerationsOlderThan(const Path & profile, std::string_view timeSpec,
 
 void switchLink(Path link, Path target);
 
-/* Roll back a profile to the specified generation, or to the most
-   recent one older than the current. */
+/**
+ * Roll back a profile to the specified generation, or to the most
+ * recent one older than the current.
+ */
 void switchGeneration(
     const Path & profile,
     std::optional<GenerationNumber> dstGen,
     bool dryRun);
 
-/* Ensure exclusive access to a profile.  Any command that modifies
-   the profile first acquires this lock. */
+/**
+ * Ensure exclusive access to a profile.  Any command that modifies
+ * the profile first acquires this lock.
+ */
 void lockProfile(PathLocks & lock, const Path & profile);
 
-/* Optimistic locking is used by long-running operations like `nix-env
-   -i'.  Instead of acquiring the exclusive lock for the entire
-   duration of the operation, we just perform the operation
-   optimistically (without an exclusive lock), and check at the end
-   whether the profile changed while we were busy (i.e., the symlink
-   target changed).  If so, the operation is restarted.  Restarting is
-   generally cheap, since the build results are still in the Nix
-   store.  Most of the time, only the user environment has to be
-   rebuilt. */
+/**
+ * Optimistic locking is used by long-running operations like `nix-env
+ * -i'.  Instead of acquiring the exclusive lock for the entire
+ * duration of the operation, we just perform the operation
+ * optimistically (without an exclusive lock), and check at the end
+ * whether the profile changed while we were busy (i.e., the symlink
+ * target changed).  If so, the operation is restarted.  Restarting is
+ * generally cheap, since the build results are still in the Nix
+ * store.  Most of the time, only the user environment has to be
+ * rebuilt.
+ */
 std::string optimisticLockProfile(const Path & profile);
 
 /**