Complete and cleanup function documentation in preparation for auto-extraction

Also:

- Move the $target.*() function family from functions-name.cxx to separate
  functions-target.cxx.

- Get rid of the separate $process_path_ex.*() family, merging it with
  $process_path.*().

1 files changed, 8 insertions, 7 deletions

diff --git a/libbuild2/functions-process.cxx b/libbuild2/functions-process.cxx
index bbcbbab..6faa798 100644
--- a/libbuild2/functions-process.cxx
+++ b/libbuild2/functions-process.cxx
@@ -450,12 +450,12 @@ namespace build2
 
     // $process.run(<prog>[ <args>...])
     //
-    // Run builtin or external program and return trimmed stdout.
+    // Run builtin or external program and return trimmed `stdout` output.
     //
     // Note that if the result of executing the program can be affected by
     // environment variables and this result can in turn affect the build
     // result, then such variables should be reported with the
-    // config.environment directive.
+    // `config.environment` directive.
     //
     // Note that this function is not pure and can only be called during the
     // load phase.
@@ -470,19 +470,20 @@ namespace build2
       return run_process (s, pp, strings ());
     };
 
-    // $process.run_regex(<prog>[ <args>...], <pat> [, <fmt>])
+    // $process.run_regex(<prog>[ <args>...], <pat>[, <fmt>])
     //
-    // Run builtin or external program and return stdout lines matched and
-    // optionally processed with regex.
+    // Run builtin or external program and return `stdout` output lines
+    // matched and optionally processed with a regular expression.
     //
     // Each line of stdout (including the customary trailing blank) is matched
     // (as a whole) against <pat> and, if successful, returned, optionally
-    // processed with <fmt>, as an element of a list.
+    // processed with <fmt>, as an element of a list. See the `$regex.*()`
+    // function family for details on regular expressions and format strings.
     //
     // Note that if the result of executing the program can be affected by
     // environment variables and this result can in turn affect the build
     // result, then such variables should be reported with the
-    // config.environment directive.
+    // `config.environment` directive.
     //
     // Note that this function is not pure and can only be called during the
     // load phase.