Support: Update documentation for Program functions

The docstrings were describing an older interface that has been replaced with
functions.

Also describe the performance characteristics of FindProgramByName() and
ExecuteAndWait() explaining when it's best to avoid them.

git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@196932 91177308-0d34-0410-b5e6-96231b3b80d8

diff --git a/include/llvm/Support/Program.h b/include/llvm/Support/Program.h
index 00571a4080162d1b19dd263a4f92fe34b99401ee..60b2181830630829201fb806157d6a5ba8e6ee3c 100644 (file)
--- a/include/llvm/Support/Program.h
+++ b/include/llvm/Support/Program.h
@@ -52,13 +52,16 @@ struct ProcessInfo {
   ProcessInfo();
 };
 
-  /// This static constructor (factory) will attempt to locate a program in
-  /// the operating system's file system using some pre-determined set of
-  /// locations to search (e.g. the PATH on Unix). Paths with slashes are
-  /// returned unmodified.
-  /// @returns A Path object initialized to the path of the program or a
-  /// Path object that is empty (invalid) if the program could not be found.
-  /// @brief Construct a Program by finding it by name.
+  /// This function attempts to locate a program in the operating
+  /// system's file system using some pre-determined set of locations to search
+  /// (e.g. the PATH on Unix). Paths with slashes are returned unmodified.
+  ///
+  /// It does not perform hashing as a shell would but instead stats each PATH
+  /// entry individually so should generally be avoided. Core LLVM library
+  /// functions and options should instead require fully specified paths.
+  ///
+  /// @returns A string containing the path of the program or an empty string if
+  /// the program could not be found.
   std::string FindProgramByName(const std::string& name);
 
   // These functions change the specified standard stream (stdin, stdout, or
@@ -72,7 +75,9 @@ struct ProcessInfo {
   /// invoked program will inherit the stdin, stdout, and stderr file
   /// descriptors, the environment and other configuration settings of the
   /// invoking program.
-  /// This function waits the program to finish.
+  /// This function waits for the program to finish, so should be avoided in
+  /// library functions that aren't expected to block. Consider using
+  /// ExecuteNoWait() instead.
   /// @returns an integer result code indicating the status of the program.
   /// A zero or positive value indicates the result code of the program.
   /// -1 indicates failure to execute