Update TaskScheduler docs to make it more obvious how a TaskScheduler should be put in place.

base/task_scheduler/task_scheduler.h

Index: base/task_scheduler/task_scheduler.h
diff --git a/base/task_scheduler/task_scheduler.h b/base/task_scheduler/task_scheduler.h
index 296e40bb8dffe3f8c35263b4f299130c9175b54a..72f4b2a3041b992057ce4874d9f7275c9c0fbc77 100644
--- a/base/task_scheduler/task_scheduler.h
+++ b/base/task_scheduler/task_scheduler.h
@@ -108,7 +108,8 @@ class BASE_EXPORT TaskScheduler {
   // new TaskScheduler.
 
   // Creates and sets a task scheduler with one worker pool that can have up to
-  // |max_threads| threads. CHECKs on failure.
+  // |max_threads| threads. CHECKs on failure. For tests, prefer
+  // base::test::ScopedTaskScheduler (ensures isolation).
   static void CreateAndSetSimpleTaskScheduler(int max_threads);
 
   // Creates and sets a task scheduler with custom worker pools. CHECKs on
@@ -121,12 +122,20 @@ class BASE_EXPORT TaskScheduler {
           worker_pool_index_for_traits_callback);
 
   // Registers |task_scheduler| to handle tasks posted through the post_task.h
-  // API for this process.
+  // API for this process. For tests, prefer base::test::ScopedTaskScheduler
+  // (ensures isolation).
   static void SetInstance(std::unique_ptr<TaskScheduler> task_scheduler);
 
   // Retrieve the TaskScheduler set via CreateAndSetDefaultTaskScheduler() or

[fdoray, 2017/02/24 16:53:37]

CreateAndSet(Simple|Default)TaskScheduler()

[gab, 2017/02/24 17:07:22]

Done.

   // SetInstance(). This should be used very rarely; most users of TaskScheduler
-  // should use the post_task.h API.
+  // should use the post_task.h API. In particular, refrain from doing
+  //   if (!TaskScheduler::GetInstance()) {
+  //     TaskScheduler::SetInstance(...);
+  //     base::PostTask(...);
+  //   }
+  // instead make sure to SetInstance() early in one determinstic place in the
+  // process' initialization phase.
+  // In doubt, consult with //base/task_scheduler/OWNERS.
   static TaskScheduler* GetInstance();
 
  private: