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, 127 insertions, 71 deletions

diff --git a/libbuild2/functions-path.cxx b/libbuild2/functions-path.cxx
index 020c8f4..4b114f5 100644
--- a/libbuild2/functions-path.cxx
+++ b/libbuild2/functions-path.cxx
@@ -198,8 +198,15 @@ namespace build2
   {
     function_family f (m, "path", &path_thunk);
 
-    // string
+    // $string(<paths>)
     //
+    // Return the traditional string representation of a path (or a list of
+    // string representations for a list of paths). In particular, for
+    // directory paths, the traditional representation does not include the
+    // trailing directory separator (except for the POSIX root directory). See
+    // `$representation()` below for the precise string representation.
+    //
+
     // Note that we must handle NULL values (relied upon by the parser
     // to provide conversion semantics consistent with untyped values).
     //
@@ -224,7 +231,12 @@ namespace build2
       return r;
     };
 
-    // posix_string
+    // $posix_string(<paths>)
+    // $path.posix_string(<untyped>)
+    //
+    // Return the traditional string representation of a path (or a list of
+    // string representations for a list of paths) using the POSIX directory
+    // separators (forward slashes).
     //
     f["posix_string"] += [](path p)     {return posix_string (move (p));};
     f["posix_string"] += [](dir_path p) {return posix_string (move (p));};
@@ -259,7 +271,13 @@ namespace build2
       return ns;
     };
 
-    // representation
+    // $representation(<paths>)
+    //
+    // Return the precise string representation of a path (or a list of string
+    // representations for a list of paths). In particular, for directory
+    // paths, the precise representation includes the trailing directory
+    // separator. See `$string()` above for the traditional string
+    // representation.
     //
     f["representation"] += [](path p) {return move (p).representation ();};
 
@@ -279,7 +297,12 @@ namespace build2
       return r;
     };
 
-    // posix_representation
+    // $posix_representation(<paths>)
+    // $path.posix_representation(<untyped>)
+    //
+    // Return the precise string representation of a path (or a list of string
+    // representations for a list of paths) using the POSIX directory
+    // separators (forward slashes).
     //
     f["posix_representation"] += [](path p)
     {
@@ -321,8 +344,14 @@ namespace build2
       return ns;
     };
 
-    // canonicalize
+    // $canonicalize(<paths>)
+    // $path.canonicalize(<untyped>)
+    //
+    // Canonicalize the path (or list of paths) by converting all the
+    // directory separators to the canonical form for the host platform. Note
+    // that multiple directory separators are not collapsed.
     //
+
     // @@ TODO: add ability to specify alternative separator.
     //
     f["canonicalize"] += [](path p)     {p.canonicalize (); return p;};
@@ -358,7 +387,13 @@ namespace build2
       return ns;
     };
 
-    // normalize
+    // $normalize(<paths>)
+    // $path.normalize(<untyped>)
+    //
+    // Normalize the path (or list of paths) by collapsing the `.` and `..`
+    // components if possible, collapsing multiple directory separators, and
+    // converting all the directory separators to the canonical form for the
+    // host platform.
     //
     f["normalize"] += [](path p)     {p.normalize (); return p;};
     f["normalize"] += [](dir_path p) {p.normalize (); return p;};
@@ -393,7 +428,16 @@ namespace build2
       return ns;
     };
 
-    // actualize
+    // $actualize(<paths>)
+    // $path.actualize(<untyped>)
+    //
+    // Actualize the path (or list of paths) by first normalizing it and then
+    // for host platforms with case-insensitive filesystems obtaining the
+    // actual spelling of the path.
+    //
+    // Note that only an absolute path can be actualized. If a path component
+    // does not exist, then its (and all subsequent) spelling is
+    // unchanged. This is a potentially expensive operation.
     //
     // Note that this function is not pure.
     //
@@ -434,11 +478,12 @@ namespace build2
       return ns;
     };
 
-    // $directory(<path>)
     // $directory(<paths>)
+    // $path.directory(<untyped>)
     //
-    // Return the directory part of the path or empty path if there is no
-    // directory. Directory of a root directory is an empty path.
+    // Return the directory part of a path (or a list of directory parts for a
+    // list of paths) or an empty path if there is no directory. A directory of
+    // a root directory is an empty path.
     //
     f["directory"] += &path::directory;
 
@@ -472,11 +517,12 @@ namespace build2
       return ns;
     };
 
-    // $root_directory(<path>)
     // $root_directory(<paths>)
+    // $path.root_directory(<untyped>)
     //
-    // Return the root directory of the path or empty path if the directory is
-    // not absolute.
+    // Return the root directory of a path (or a list of root directories for
+    // a list of paths) or an empty path if the specified path is not
+    // absolute.
     //
     f["root_directory"] += &path::root_directory;
 
@@ -510,17 +556,22 @@ namespace build2
       return ns;
     };
 
-    // $leaf(<path>)
-    //
-    f["leaf"] += &path::leaf;
-
-    // $leaf(<path>, <dir-path>)
+    // $leaf(<paths>)
+    // $path.leaf(<untyped>)
     // $leaf(<paths>, <dir-path>)
+    // $path.leaf(<untyped>, <dir-path>)
     //
-    // Return the path without the specified directory part. Return empty path
-    // if the paths are the same. Issue diagnostics and fail if the directory
-    // is not a prefix of the path. Note: expects both paths to be normalized.
+    // First form (one argument): return the last component of a path (or a
+    // list of last components for a list of paths).
     //
+    // Second form (two arguments): return a path without the specified
+    // directory part (or a list of paths without the directory part for a
+    // list of paths). Return an empty path if the paths are the same. Issue
+    // diagnostics and fail if the directory is not a prefix of the
+    // path. Note: expects both paths to be normalized.
+    //
+    f["leaf"] += &path::leaf;
+
     f["leaf"] += [](path p, dir_path d)
     {
       return leaf (p, move (d));
@@ -556,13 +607,13 @@ namespace build2
       return ns;
     };
 
-    // $relative(<path>, <dir-path>)
     // $relative(<paths>, <dir-path>)
+    // $path.relative(<untyped>, <dir-path>)
     //
-    // Return a path relative to the specified directory that is equivalent to
-    // the specified path. Issue diagnostics and fail if a relative path
-    // cannot be derived (for example, paths are on different drives on
-    // Windows).
+    // Return the path relative to the specified directory that is equivalent
+    // to the specified path (or a list of relative paths for a list of
+    // specified paths). Issue diagnostics and fail if a relative path cannot
+    // be derived (for example, paths are on different drives on Windows).
     //
     f["relative"] += [](path p, dir_path d)
     {
@@ -599,7 +650,11 @@ namespace build2
       return ns;
     };
 
-    // base
+    // $base(<paths>)
+    // $path.base(<untyped>)
+    //
+    // Return the base part (without the extension) of a path (or a list of
+    // base parts for a list of paths).
     //
     f["base"] += &path::base;
 
@@ -633,7 +688,11 @@ namespace build2
       return ns;
     };
 
-    // extension
+    // $extension(<path>)
+    // $path.extension(<untyped>)
+    //
+    // Return the extension part (without the dot) of a path or empty string
+    // if there is no extension.
     //
     f["extension"] += &extension;
 
@@ -643,32 +702,29 @@ namespace build2
     };
 
     // $size(<paths>)
-    // $size(<dir_paths>)
+    // $size(<path>)
+    //
+    // First form: return the number of elements in the paths sequence.
+    //
+    // Second form: return the number of characters (bytes) in the path. Note
+    // that for `dir_path` the result does not include the trailing directory
+    // separator (except for the POSIX root directory).
     //
-    // Return the number of elements in the sequence.
     //
     f["size"] += [] (paths v) {return v.size ();};
     f["size"] += [] (dir_paths v) {return v.size ();};
 
-    // $size(<path>)
-    // $size(<dir_path>)
-    //
-    // Return the number of characters (bytes) in the path. Note that for
-    // dir_path the result does not include the trailing directory separator
-    // (except for the POSIX root directory).
-    //
     f["size"] += [] (path v) {return v.size ();};
     f["size"] += [] (dir_path v) {return v.size ();};
 
-    // $sort(<paths> [, <flags>])
-    // $sort(<dir_paths> [, <flags>])
+    // $sort(<paths>[, <flags>])
     //
-    // Sort paths in ascending order. Note that on hosts with a case-
-    // insensitive filesystem the order is case-insensitive.
+    // Sort paths in ascending order. Note that on host platforms with a
+    // case-insensitive filesystem the order is case-insensitive.
     //
     // The following flags are supported:
     //
-    //   dedup - in addition to sorting also remove duplicates
+    //     dedup - in addition to sorting also remove duplicates
     //
     f["sort"] += [](paths v, optional<names> fs)
     {
@@ -691,11 +747,10 @@ namespace build2
     };
 
     // $find(<paths>, <path>)
-    // $find(<dir_paths>, <dir_path>)
     //
-    // Return true if the path sequence contains the specified path. Note that
-    // on hosts with a case-insensitive filesystem the comparison is
-    // case-insensitive.
+    // Return true if the paths sequence contains the specified path. Note
+    // that on host platforms with a case-insensitive filesystem the
+    // comparison is case-insensitive.
     //
     f["find"] += [](paths vs, value v)
     {
@@ -710,12 +765,11 @@ namespace build2
     };
 
     // $find_index(<paths>, <path>)
-    // $find_index(<dir_paths>, <dir_path>)
     //
-    // Return the index of the first element in the path sequence that is
-    // equal to the specified path or $size(<paths>) if none is found. Note
-    // that on hosts with a case-insensitive filesystem the comparison is
-    // case-insensitive.
+    // Return the index of the first element in the paths sequence that is
+    // equal to the specified path or `$size(paths)` if none is found. Note
+    // that on host platforms with a case-insensitive filesystem the
+    // comparison is case-insensitive.
     //
     f["find_index"] += [](paths vs, value v)
     {
@@ -729,34 +783,36 @@ namespace build2
       return i != vs.end () ? i - vs.begin () : vs.size ();
     };
 
-    // $path.match(<val>, <pat> [, <start>])
+    // $path.match(<entry>, <pattern>[, <start-dir>])
     //
-    // Match a filesystem entry name against a name pattern (both are strings),
-    // or a filesystem entry path against a path pattern. For the latter case
-    // the start directory may also be required (see below). The semantics of
-    // the pattern and name/entry arguments is determined according to the
+    // Match a filesystem entry name against a name pattern (both are
+    // strings), or a filesystem entry path against a path pattern. For the
+    // latter case the start directory may also be required (see below). The
+    // pattern is a shell-like wildcard pattern. The semantics of the
+    // <pattern> and <entry> arguments is determined according to the
     // following rules:
     //
-    // - The arguments must be of the string or path types, or be untyped.
+    // 1. The arguments must be of the string or path types, or be untyped.
     //
-    // - If one of the arguments is typed, then the other one must be of the
-    //   same type or be untyped. In the later case, an untyped argument is
-    //   converted to the type of the other argument.
+    // 2. If one of the arguments is typed, then the other one must be of the
+    // same type or be untyped. In the later case, an untyped argument is
+    // converted to the type of the other argument.
     //
-    // - If both arguments are untyped and the start directory is specified,
-    //   then the arguments are converted to the path type.
+    // 3. If both arguments are untyped and the start directory is specified,
+    // then the arguments are converted to the path type.
     //
-    // - If both arguments are untyped and the start directory is not
-    //   specified, then, if one of the arguments is syntactically a path (the
-    //   value contains a directory separator), convert them to the path type,
-    //   otherwise to the string type (match as names).
+    // 4. If both arguments are untyped and the start directory is not
+    // specified, then, if one of the arguments is syntactically a path (the
+    // value contains a directory separator), then they are converted to the
+    // path type, otherwise -- to the string type (match as names).
     //
-    // If pattern and entry paths are both either absolute or relative and
-    // non-empty, and the first pattern component is not a self-matching
-    // wildcard (doesn't contain ***), then the start directory is not
-    // required, and is ignored if specified. Otherwise, the start directory
-    // must be specified and be an absolute path.
+    // If pattern and entry paths are both either absolute or relative and not
+    // empty, and the first pattern component is not a self-matching wildcard
+    // (doesn't contain `***`), then the start directory is not required, and
+    // is ignored if specified. Otherwise, the start directory must be
+    // specified and be an absolute path.
     //
+
     // Name matching.
     //
     f[".match"] += [](string name, string pattern)