Document TaskStatus::next vs. success

src/task_list/task_list.hpp

@@ -29,8 +29,14 @@ class TaskID;
 //! - these 4x declarations can be nested in TaskList if MGTaskList is derived
 
 // constants = return codes for functions working on individual Tasks and TaskList
-enum class TaskStatus {fail, success, next};
 enum class TaskListStatus {running, stuck, complete, nothing_to_do};
+enum class TaskStatus {fail, success, next};
+// success vs. next: They are different (only) when there are more than one MeshBlock per
+// node.  When a task returns “next”, then it processes the next Task in the same
+// MeshBlock; when it returns “success”, then the TaskList processes the next MeshBlock.
+// “next” should be used when you want to immediately start the next task, for example,
+// start sending the data just calculated in the previous task.  Otherwise, use “success”
+// to process MeshBlocks as evenly as possible.
 
 //----------------------------------------------------------------------------------------
 //! \class TaskID