From 2109dedc473944dbb38756cd48d0c44f996304c4 Mon Sep 17 00:00:00 2001
From: Boris Kolpackov <boris@codesynthesis.com>
Date: Wed, 9 Aug 2023 08:54:37 +0200
Subject: 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.*().
---
 libbuild2/functions-process-path.cxx | 53 ++++++++++++++++++++++++++----------
 1 file changed, 38 insertions(+), 15 deletions(-)

(limited to 'libbuild2/functions-process-path.cxx')

diff --git a/libbuild2/functions-process-path.cxx b/libbuild2/functions-process-path.cxx
index 486a806..6746623 100644
--- a/libbuild2/functions-process-path.cxx
+++ b/libbuild2/functions-process-path.cxx
@@ -11,24 +11,47 @@ namespace build2
   void
   process_path_functions (function_map& m)
   {
-    {
-      function_family f (m, "process_path");
+    function_family f (m, "process_path");
+
+    // $recall(<process-path>)
+    //
+    // Return the recall path of an executable, that is, a path that is not
+    // necessarily absolute but which nevertheless can be used to re-run the
+    // executable in the current environment. This path, for example, could be
+    // used in diagnostics when printing the failing command line.
+    //
+
+    // As discussed in value_traits<process_path>, we always have recall.
+    //
+    f["recall"] += &process_path::recall;
 
-      // As discussed in value_traits<process_path>, we always have recall.
-      //
-      f["recall"] += &process_path::recall;
-      f["effect"] += [](process_path p)
-      {
-        return move (p.effect.empty () ? p.recall : p.effect);
-      };
-    }
 
+    // $effect(<process-path>)
+    //
+    // Return the effective path of an executable, that is, the absolute path
+    // to the executable that will also include any omitted extensions, etc.
+    //
+    f["effect"] += [] (process_path p)
     {
-      function_family f (m, "process_path_ex");
+      return move (p.effect.empty () ? p.recall : p.effect);
+    };
+
+    // $name(<process-path-ex>)
+    //
+    // Return the stable process name for diagnostics.
+    //
+    f["name"] += &process_path_ex::name;
+
+    // $checksum(<process-path-ex>)
+    //
+    // Return the executable checksum for change tracking.
+    //
+    f["checksum"] += &process_path_ex::checksum;
 
-      f["name"] += &process_path_ex::name;
-      f["checksum"] += &process_path_ex::checksum;
-      f["env_checksum"] += &process_path_ex::env_checksum;
-    }
+    // $env_checksum(<process-path-ex>)
+    //
+    // Return the environment checksum for change tracking.
+    //
+    f["env_checksum"] += &process_path_ex::env_checksum;
   }
 }
-- 
cgit v1.1