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, 26 insertions, 0 deletions

diff --git a/libbuild2/functions-project-name.cxx b/libbuild2/functions-project-name.cxx
index 4a8394d..23523f0 100644
--- a/libbuild2/functions-project-name.cxx
+++ b/libbuild2/functions-project-name.cxx
@@ -13,6 +13,12 @@ namespace build2
   {
     function_family f (m, "project_name");
 
+    // $string(<project-name>)
+    //
+    // Return the string representation of a project name. See also the
+    // `$variable()` function below.
+    //
+
     // Note that we must handle NULL values (relied upon by the parser
     // to provide conversion semantics consistent with untyped values).
     //
@@ -21,6 +27,14 @@ namespace build2
       return p != nullptr ? move (*p).string () : string ();
     };
 
+    // $base(<project-name>[, <extension>])
+    //
+    // Return the base part (without the extension) of a project name.
+    //
+    // If <extension> is specified, then only remove that extension. Note that
+    // <extension> should not include the dot and the comparison is always
+    // case-insensitive.
+    //
     f["base"] += [](project_name p, optional<string> ext)
     {
       return ext ? p.base (ext->c_str ()) : p.base ();
@@ -31,7 +45,19 @@ namespace build2
       return p.base (convert<string> (move (ext)).c_str ());
     };
 
+    // $extension(<project-name>)
+    //
+    // Return the extension part (without the dot) of a project name or empty
+    // string if there is no extension.
+    //
     f["extension"] += &project_name::extension;
+
+    // $variable(<project-name>)
+    //
+    // Return the string representation of a project name that is sanitized to
+    // be usable as a variable name. Specifically, `.`, `-`, and `+` are
+    // replaced with `_`.
+    //
     f["variable"]  += &project_name::variable;
 
     // Project name-specific overloads from builtins.