Merge pull request #87 from buchanae/state-docs

Improve task state docs

task_execution.proto

@@ -353,13 +353,44 @@ message OutputFileLog {
 //
 // Task states.
 enum State {
+
+  // The state of the task is unknown.
+  //
+  // This provides a safe default for messages where this field is missing,
+  // for example, so that a missing field does not accidentally imply that
+  // the state is QUEUED.
   UNKNOWN = 0;
+
+  // The task is queued.
   QUEUED = 1;
+
+  // The task has been assigned to a worker and is currently preparing to run.
+  // For example, the worker may be turning on, downloading input files, etc.
   INITIALIZING = 2;
+
+  // The task is running. Input files are downloaded and the first Executor
+  // has been started.
   RUNNING = 3;
+
+  // The task is paused.
+  //
+  // An implementation may have the ability to pause a task, but this is not required.
+  PAUSED = 4;
+
+  // The task has completed running. Executors have exited without error
+  // and output files have been successfully uploaded.
   COMPLETE = 5;
+
+  // The task encountered an error in one of the Executor processes. Generally,
+  // this means that an Executor exited with a non-zero exit code.
   EXECUTOR_ERROR = 6;
+
+  // The task was stopped due to a system error, but not from an Executor,
+  // for example an upload failed due to network issues, the worker's ran out
+  // of disk space, etc.
   SYSTEM_ERROR = 7;
+
+  // The task was canceled by the user.
   CANCELED = 8;
 }