Document Task and ExternalTask methods

diff --git a/source/externaltask.h b/source/externaltask.h
index 19ffe71e8fa4ff985a9c44805d608de351634cd4..cb8464beab873ef24146b49a5ab02bd6a9aaa21c 100644 (file)
--- a/source/externaltask.h
+++ b/source/externaltask.h
@@ -17,9 +17,9 @@ class ExternalTask: public Task
 public:
        enum Destination
        {
-               PASSTHROUGH,
-               CAPTURE,
-               IGNORE
+               PASSTHROUGH,  //< Do not touch the stream
+               CAPTURE,      //< Capture the stream
+               IGNORE        //< Redirect the stream to oblivion
        };
 
        typedef std::vector<std::string> Arguments;
@@ -50,8 +50,14 @@ private:
        Status do_wait(bool);
 
 public:
+       /// Sets destination for stdout.  Has no effect after the task is started.
        void set_stdout(Destination);
+
+       /// Sets destination for stderr.  Has no effect after the task is started.
        void set_stderr(Destination);
+
+       /** Returns captured output, if any.  This may be called while the task is
+       still running, but it will always return all output. */
        const std::string &get_output() const { return output; }
 
        /** Executes a command and captures its output.  Stderr is ignored, but if

diff --git a/source/task.h b/source/task.h
index 9cf2bac9081b7b2c8df1627342aa1dd14600d8ff..e7e37e3f04423d525afdf44e00a2e9c854c5c4b1 100644 (file)
--- a/source/task.h
+++ b/source/task.h
@@ -6,7 +6,8 @@
 
 /**
 Tasks are used to manage other programs and worker threads involved in the
-build process.  They are run asynchronously.
+build process.  They are run asynchronously by default, but a wait() method is
+provided should it be necessary to wait for a task to finish.
 */
 class Task
 {
@@ -25,9 +26,17 @@ protected:
 public:
        virtual ~Task() { }
 
+       /** Returns the command being executed for this task.  Only makes sense if
+       an external command is involved. */
        virtual std::string get_command() const = 0;
+
+       /// Starts the task.
        virtual void start() = 0;
+
+       /// Checks the status of the task and immediately returns.
        virtual Status check() = 0;
+
+       /// Waits for the task to finish and returns its final status.
        virtual Status wait() = 0;
 };