From 0aa50a0d3e5567e9295ecf4d7ba6d4b14fa73b9b Mon Sep 17 00:00:00 2001
From: Mikko Rasa <tdb@tdb.fi>
Date: Thu, 19 Jul 2012 13:52:12 +0300
Subject: [PATCH] Document Task and ExternalTask methods

---
 source/externaltask.h | 12 +++++++++---
 source/task.h         | 11 ++++++++++-
 2 files changed, 19 insertions(+), 4 deletions(-)

diff --git a/source/externaltask.h b/source/externaltask.h
index 19ffe71..cb8464b 100644
--- 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 9cf2bac..e7e37e3 100644
--- 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;
 };
 
-- 
2.45.2