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

base/task_scheduler/task_scheduler.h

 // Copyright 2016 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef BASE_TASK_SCHEDULER_TASK_SCHEDULER_H_
 #define BASE_TASK_SCHEDULER_TASK_SCHEDULER_H_
 
 #include <memory>
 #include <vector>
 
@@ skipping 90 matching lines @@
   // CreateAndSetSimpleTaskScheduler(), CreateAndSetDefaultTaskScheduler(), and
   // SetInstance() register a TaskScheduler to handle tasks posted through the
   // post_task.h API for this process. The registered TaskScheduler will only be
   // deleted when a new TaskScheduler is registered and is leaked on shutdown.
   // The methods must not be called when TaskRunners created by the previous
   // TaskScheduler are still alive. The methods are not thread-safe; proper
   // synchronization is required to use the post_task.h API after registering a
   // 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
   // failure. |worker_pool_params_vector| describes the worker pools to create.
   // |worker_pool_index_for_traits_callback| returns the index in |worker_pools|
   // of the worker pool in which a task with given traits should run.

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

To be consistent, add: For tests, prefer ... 

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

Done.

   static void CreateAndSetDefaultTaskScheduler(
       const std::vector<SchedulerWorkerPoolParams>& worker_pool_params_vector,
       const WorkerPoolIndexForTraitsCallback&
           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:
   friend class gin::V8Platform;
 
   // Returns the maximum number of non-single-threaded tasks posted with
   // |traits| that can run concurrently in this TaskScheduler.
   //
   // Do not use this method. To process n items, post n tasks that each process
   // 1 item rather than GetMaxConcurrentTasksWithTraitsDeprecated() tasks that
   // each process n/GetMaxConcurrentTasksWithTraitsDeprecated() items.
   //
   // TODO(fdoray): Remove this method. https://crbug.com/687264
   virtual int GetMaxConcurrentTasksWithTraitsDeprecated(
       const TaskTraits& traits) const = 0;
 };
 
 }  // namespace base
 
 #endif  // BASE_TASK_SCHEDULER_TASK_SCHEDULER_H_