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.

llvm-svn: 196932

Author: atoker

llvm/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