Reland "[TaskScheduler]: Add section to faq: when to annotate with Sc…

…opedBlockingCall."

This is a reland of 8aeb9cc

Original change's description:
> [TaskScheduler]: Add section to faq: when to annotate with ScopedBlockingCall.
> 
> Developpers are often wondering whether or not ScopedBlockingCall is redundant.
> 
> Change-Id: Ic7936ef805f43f7fc02d0ad3020c31d8364b099d
> Reviewed-on: https://chromium-review.googlesource.com/c/1271878
> Commit-Queue: Etienne Pierre-Doray <etiennep@chromium.org>
> Reviewed-by: François Doray <fdoray@chromium.org>
> Cr-Commit-Position: refs/heads/master@{#599626}

Change-Id: I0850821994e3b4a1b0c3bb238725bc28867d18f5
Reviewed-on: https://chromium-review.googlesource.com/c/1280281
Commit-Queue: Etienne Pierre-Doray <etiennep@chromium.org>
Reviewed-by: Gabriel Charette <gab@chromium.org>
Cr-Commit-Position: refs/heads/master@{#599952}

docs/threading_and_tasks_faq.md

@@ -70,10 +70,49 @@ If the task runs on a `DEDICATED SingleThreadTaskRunner`:
   `DEDICATED SingleThreadTaskRunner` won't run until your blocking task returns
   (they will never run if the blocking task never returns).
 
-`[base/threading/scoped_blocking_call.h](https://cs.chromium.org/chromium/src/base/threading/scoped_blocking_call.h)`
+[base/threading/scoped_blocking_call.h](https://cs.chromium.org/chromium/src/base/threading/scoped_blocking_call.h)
 explains the difference between `MAY_BLOCK ` and  `WILL_BLOCK` and gives
 examples of off-CPU blocking operations.
 
+### Do calls to blocking //base APIs need to be annotated with ScopedBlockingCall?
+
+No. All blocking //base APIs (e.g. base::ReadFileToString, base::File::Read,
+base::SysInfo::AmountOfFreeDiskSpace, base::WaitableEvent::Wait, etc.) have their
+own internal annotations. See
+[base/threading/scoped_blocking_call.h](https://cs.chromium.org/chromium/src/base/threading/scoped_blocking_call.h).
+
+### Can multiple ScopedBlockingCall be nested for the purpose of documentation?
+
+Nested `ScopedBlockingCall` are supported. Most of the time, the inner
+ScopedBlockingCalls will no-op (the exception is WILL_BLOCK nested in MAY_BLOCK).
+As such, it is permitted to add a ScopedBlockingCall in the scope where a function
+that is already annotated is called for documentation purposes.:
+
+```cpp
+Data GetDataFromNetwork() {
+  ScopedBlockingCall scoped_blocking_call(BlockingType::MAY_BLOCK);
+  // Fetch data from network.
+  ...
+  return data;
+}
+
+void ProcessDataFromNetwork() {
+  Data data;
+  {
+    // Document the blocking behavior with a ScopedBlockingCall.
+    // Permitted, but not required since GetDataFromNetwork() is itself annotated.
+    ScopedBlockingCall scoped_blocking_call(BlockingType::MAY_BLOCK);
+    data = GetDataFromNetwork();
+  }
+  CPUIntensiveProcessing(data);
+}
+```
+
+ However, CPU usage should always be minimal within the scope of
+`ScopedBlockingCall`. See
+[base/threading/scoped_blocking_call.h](https://cs.chromium.org/chromium/src/base/threading/scoped_blocking_call.h).
+
+
 ## Sequences
 
 ### How to migrate from SingleThreadTaskRunner to SequencedTaskRunner?