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, 37 insertions, 23 deletions

diff --git a/src/libmain/shared.hh b/src/libmain/shared.hh
index d915a4a65..7a9e83c6c 100644
--- a/src/libmain/shared.hh
+++ b/src/libmain/shared.hh
@@ -25,7 +25,9 @@ public:
 
 int handleExceptions(const std::string & programName, std::function<void()> fun);
 
-/* Don't forget to call initPlugins() after settings are initialized! */
+/**
+ * Don't forget to call initPlugins() after settings are initialized!
+ */
 void initNix();
 
 void parseCmdLine(int argc, char * * argv,
@@ -36,7 +38,9 @@ void parseCmdLine(const std::string & programName, const Strings & args,
 
 void printVersion(const std::string & programName);
 
-/* Ugh.  No better place to put this. */
+/**
+ * Ugh.  No better place to put this.
+ */
 void printGCWarning();
 
 class Store;
@@ -75,11 +79,15 @@ struct LegacyArgs : public MixCommonArgs
 };
 
 
-/* Show the manual page for the specified program. */
+/**
+ * Show the manual page for the specified program.
+ */
 void showManPage(const std::string & name);
 
-/* The constructor of this class starts a pager if stdout is a
-   terminal and $PAGER is set. Stdout is redirected to the pager. */
+/**
+ * The constructor of this class starts a pager if stdout is a
+ * terminal and $PAGER is set. Stdout is redirected to the pager.
+ */
 class RunPager
 {
 public:
@@ -110,28 +118,34 @@ struct PrintFreed
 };
 
 
-/* Install a SIGSEGV handler to detect stack overflows. */
+/**
+ * Install a SIGSEGV handler to detect stack overflows.
+ */
 void detectStackOverflow();
 
-/* Pluggable behavior to run in case of a stack overflow.
-
-   Default value: defaultStackOverflowHandler.
-
-   This is called by the handler installed by detectStackOverflow().
-
-   This gives Nix library consumers a limit opportunity to report the error
-   condition. The handler should exit the process.
-   See defaultStackOverflowHandler() for a reference implementation.
-
-   NOTE: Use with diligence, because this runs in the signal handler, with very
-   limited stack space and a potentially a corrupted heap, all while the failed
-   thread is blocked indefinitely. All functions called must be reentrant. */
+/**
+ * Pluggable behavior to run in case of a stack overflow.
+ *
+ * Default value: defaultStackOverflowHandler.
+ *
+ * This is called by the handler installed by detectStackOverflow().
+ *
+ * This gives Nix library consumers a limit opportunity to report the error
+ * condition. The handler should exit the process.
+ * See defaultStackOverflowHandler() for a reference implementation.
+ *
+ * NOTE: Use with diligence, because this runs in the signal handler, with very
+ * limited stack space and a potentially a corrupted heap, all while the failed
+ * thread is blocked indefinitely. All functions called must be reentrant.
+ */
 extern std::function<void(siginfo_t * info, void * ctx)> stackOverflowHandler;
 
-/* The default, robust implementation of stackOverflowHandler.
-
-   Prints an error message directly to stderr using a syscall instead of the
-   logger. Exits the process immediately after. */
+/**
+ * The default, robust implementation of stackOverflowHandler.
+ *
+ * Prints an error message directly to stderr using a syscall instead of the
+ * logger. Exits the process immediately after.
+ */
 void defaultStackOverflowHandler(siginfo_t * info, void * ctx);
 
 }