From 274fd06643b23866a301b83fa6a7181bc3b04e63 Mon Sep 17 00:00:00 2001
From: CaS <CaS@72102866-910b-0410-8b05-ffd578937521>
Date: Thu, 19 Apr 2001 09:19:48 +0000
Subject: [PATCH] Fully documented

git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@9621 72102866-910b-0410-8b05-ffd578937521
---
 Documentation/gsdoc/NSTask.gsdoc | 123 +++++++++++++++++++++++++++++--
 1 file changed, 118 insertions(+), 5 deletions(-)

diff --git a/Documentation/gsdoc/NSTask.gsdoc b/Documentation/gsdoc/NSTask.gsdoc
index 533a72356..0e7452fcd 100644
--- a/Documentation/gsdoc/NSTask.gsdoc
+++ b/Documentation/gsdoc/NSTask.gsdoc
@@ -17,125 +17,238 @@
         <declared>Foundation/NSTask.h</declared>
         <conform>NSObject</conform>
           <desc>
+	    The NSTask class provides a mechanism to run separate tasks
+	    under (limited) control of your program.
           </desc>
+
         <method type="NSTask*" factory="yes">
           <sel>launchedTaskWithLaunchPath:</sel>
           <arg type="NSString*">path</arg>
           <sel>arguments:</sel>
           <arg type="NSArray*">arguments</arg>
           <desc>
+	    Creates and launches a task, returning an autoreleased task object.
+	    Supplies the path to the executable and an array of argument.
+	    The task inherits the parents environment and I/O.
           </desc>
         </method>
+
         <method type="NSArray*">
           <sel>arguments</sel>
           <desc>
+	    Returns the arguments set for the task.
           </desc>
         </method>
+
         <method type="NSString*">
           <sel>currentDirectoryPath</sel>
           <desc>
+	    Returns the working directory set for the task.
           </desc>
         </method>
+
         <method type="NSDictionary*">
           <sel>environment</sel>
           <desc>
+	    Returns the environment set for the task.
           </desc>
         </method>
-        <method type="id">
-          <sel>init</sel>
-          <desc>
-          </desc>
-        </method>
+
         <method type="void">
           <sel>interrupt</sel>
           <desc>
+	    Sends an interrupt signal to the receiver and any subtasks.<br />
+	    If the task has not been launched, raises an
+	    NSInvalidArgumentException.<br /> 
+	    Has no effect on a task that has already terminated.<br />
+	    This is rather like the terminate method, but the child
+	    process may not choose to terminate in response to an interrupt.
           </desc>
         </method>
+
         <method type="BOOL">
           <sel>isRunning</sel>
           <desc>
+	    Checks to see if the task is currently running.
           </desc>
         </method>
+
         <method type="void">
           <sel>launch</sel>
           <desc>
+	    Launches the task.<br />
+	    Raises an NSInvalidArgumentException if the launch path is not
+	    set or if the subtask cannot be started for some reason
+	    (eg. the executable does not exist).
           </desc>
         </method>
+
         <method type="NSString*">
           <sel>launchPath</sel>
           <desc>
+	    Returns the launch path set for the task.
           </desc>
         </method>
+
         <method type="void">
           <sel>setArguments:</sel>
           <arg type="NSArray*">arguments</arg>
           <desc>
+	    Sets an array of arguments to be supplied to the task when it
+	    is launched.  The default is an empty array.  This method cannot
+	    be used after a task is launched ...
+	    it raises an NSInvalidArgumentException. 
           </desc>
         </method>
+
         <method type="void">
           <sel>setCurrentDirectoryPath:</sel>
           <arg type="NSString*">path</arg>
           <desc>
+	    Sets the home directory in which the task is to be run.
+	    The default is the parent processes directory. 
+	    This method cannot be used after a task is launched ...
+	    it raises an NSInvalidArgumentException. 
           </desc>
         </method>
+
         <method type="void">
           <sel>setEnvironment:</sel>
           <arg type="NSDictionary*">environmentDictionary</arg>
           <desc>
+	    Sets the environment variables for the task to be run.
+	    The default is the parent processes environment. 
+	    This method cannot be used after a task is launched ...
+	    it raises an NSInvalidArgumentException. 
           </desc>
         </method>
+
         <method type="void">
           <sel>setLaunchPath:</sel>
           <arg type="NSString*">path</arg>
           <desc>
+	    Sets the path to the executable file to be run.
+	    There is no default for this - you must set the launch path.
+	    This method cannot be used after a task is launched ...
+	    it raises an NSInvalidArgumentException. 
           </desc>
         </method>
+
         <method type="void">
           <sel>setStandardError:</sel>
           <arg type="id">file</arg>
           <desc>
+	    Sets the standard error stream for the task.<br />
+	    This is normally a writable NSFileHandle object.
+	    If this is an NSPipe, the write end of the pipe is
+	    automatically closed on launching.<br />
+	    The default behavior is to inherit the parent processes
+	    stderr output.<br />
+	    This method cannot be used after a task is launched ...
+	    it raises an NSInvalidArgumentException. 
           </desc>
         </method>
+
         <method type="void">
           <sel>setStandardInput:</sel>
           <arg type="id">file</arg>
           <desc>
+	    Sets the standard input stream for the task.<br />
+	    This is normally a readable NSFileHandle object.
+	    If this is an NSPipe, the read end of the pipe is
+	    automatically closed on launching.<br />
+	    The default behavior is to inherit the parent processes
+	    stdin stream.<br />
+	    This method cannot be used after a task is launched ...
+	    it raises an NSInvalidArgumentException. 
           </desc>
         </method>
+
         <method type="void">
           <sel>setStandardOutput:</sel>
           <arg type="id">file</arg>
           <desc>
+	    Sets the standard output stream for the task.<br />
+	    This is normally a writable NSFileHandle object.
+	    If this is an NSPipe, the write end of the pipe is
+	    automatically closed on launching.<br />
+	    The default behavior is to inherit the parent processes
+	    stdout stream.<br />
+	    This method cannot be used after a task is launched ...
+	    it raises an NSInvalidArgumentException. 
           </desc>
         </method>
+
         <method type="id">
           <sel>standardError</sel>
           <desc>
+	    Returns the standard error stream for the task - an NSFileHandle
+	    unless an NSPipe was passed to setStandardError:
           </desc>
         </method>
+
         <method type="id">
           <sel>standardInput</sel>
           <desc>
+	    Returns the standard input stream for the task - an NSFileHandle
+	    unless an NSPipe was passed to setStandardInput:
           </desc>
         </method>
+
         <method type="id">
           <sel>standardOutput</sel>
           <desc>
+	    Returns the standard output stream for the task - an NSFileHandle
+	    unless an NSPipe was passed to setStandardOutput:
           </desc>
         </method>
+
         <method type="void">
           <sel>terminate</sel>
           <desc>
+	    Sends a terminate signal to the receiver and any subtasks.<br />
+	    If the task has not been launched, raises an
+	    NSInvalidArgumentException.<br /> 
+	    Has no effect on a task that has already terminated.<br />
+	    When a task temrinates, either due to this method being called,
+	    or normal termination, an NSTaskDidTerminateNotification is
+	    posted.
           </desc>
         </method>
+
         <method type="int">
           <sel>terminationStatus</sel>
           <desc>
+	    Returns the termination status of the task.<br />
+	    If the task has not completed running, raises an
+	    NSInvalidArgumentException.
           </desc>
         </method>
+
+        <method type="BOOL">
+          <sel>usePseudoTerminal</sel>
+          <desc>
+	    If the system supports it, this method sets the standard
+	    input, output, and error streams to a pseudo-terminal so
+	    that, when launched, the child task will act as if it was
+	    running interactively on a terminal.  The file handles
+	    can then be used to communicate with the child.<br />
+	    This method cannot be used after a task is launched ...
+	    it raises an NSInvalidArgumentException.<br />
+	    The standard input, output and error streams cannot be
+	    changed after calling this method.<br />
+	    The method returns YES on success, NO on failure.
+          </desc>
+	  <standards><GNUstep/><NotMacOS-X/><NotOpenStep/></standards>
+        </method>
+
         <method type="void">
           <sel>waitUntilExit</sel>
           <desc>
+	    Suspends the current thread until the task terminates, by
+	    waiting in NSRunLoop (NSDefaultRunLoopMode) for the task
+	    termination.<br />
+	    Returns immediately if the task is not running.
           </desc>
         </method>
       </class>