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

base/task_scheduler/post_task.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_POST_TASK_H_
 #define BASE_TASK_SCHEDULER_POST_TASK_H_
 
 #include <utility>
 
 #include "base/base_export.h"
 #include "base/bind.h"
 #include "base/callback.h"
 #include "base/location.h"
 #include "base/memory/ref_counted.h"
 #include "base/post_task_and_reply_with_result_internal.h"
 #include "base/sequenced_task_runner.h"
 #include "base/single_thread_task_runner.h"
 #include "base/task_runner.h"
 #include "base/task_scheduler/task_traits.h"
 #include "base/time/time.h"
 
 namespace base {
 
 // This is the preferred interface to post tasks to the TaskScheduler.
 //
-// TaskScheduler must have been registered for the current process via
-// TaskScheduler::SetInstance() before the functions below are valid.
-//
 // To post a simple one-off task with default traits:
 //     PostTask(FROM_HERE, Bind(...));
 //
 // To post a high priority one-off task to respond to a user interaction:
 //     PostTaskWithTraits(
 //         FROM_HERE,
 //         TaskTraits().WithPriority(TaskPriority::USER_BLOCKING),
 //         Bind(...));
 //
 // To post tasks that must run in sequence with default traits:
@@ skipping 16 matching lines @@
 //     (2) prefer inheriting the current priority to specifying their own, and
 //     (3) can either block shutdown or be skipped on shutdown
 //         (TaskScheduler implementation is free to choose a fitting default).
 // Explicit traits must be specified for tasks for which these loose
 // requirements are not sufficient.
 //
 // Tasks posted through functions below will run on threads owned by the
 // registered TaskScheduler (i.e. not on the main thread). Tasks posted through
 // functions below with a delay may be coalesced (i.e. delays may be adjusted to
 // reduce the number of wakeups and hence power consumption).
+//
+// Prerequisite: A TaskScheduler must have been registered for the current
+// process via TaskScheduler::SetInstance() before the functions below are
+// valid. Note: this is typically done in the main of each process and you most

[robliao, 2017/02/23 23:00:33]

Omit "Note:"

Maybe
This is typically done during the initialization phase in each process. If your
code is not running in this phase, you most likely don't have to worry about
this. You will encounter DCHECKs or nullptr dereferences if this is violated.
For tests...

[gab, 2017/02/23 23:39:57]

Done and also documented GetInstance() further to make it clear that
SetInstance() should be done in strictly one place.

+// likely don't have to worry about this if you're not in charge of the main for
+// your process (the failure mode isn't subtle either -- DCHECK or nullptr
+// crash -- so you'll find out quickly if this isn't the case). For tests,
+// prefer base::test::ScopedTaskScheduler.
 
 // Posts |task| to the TaskScheduler. Calling this is equivalent to calling
 // PostTaskWithTraits with plain TaskTraits.
 BASE_EXPORT void PostTask(const tracked_objects::Location& from_here,
                           const Closure& task);
 
 // Posts |task| to the TaskScheduler. |task| will not run before |delay|
 // expires. Calling this is equivalent to calling PostDelayedTaskWithTraits with
 // plain TaskTraits.
 //
@@ skipping 88 matching lines @@
 // CreateSequencedTaskRunnerWithTraits(). Only use this if you rely on a thread-
 // affine API (it might be safer to assume thread-affinity when dealing with
 // under-documented third-party APIs, e.g. other OS') or share data across tasks
 // using thread-local storage.
 BASE_EXPORT scoped_refptr<SingleThreadTaskRunner>
 CreateSingleThreadTaskRunnerWithTraits(const TaskTraits& traits);
 
 }  // namespace base
 
 #endif  // BASE_TASK_SCHEDULER_POST_TASK_H_