[Platform API] Add comment about non-nestable tasks

Clarify when we should use PostTask vs PostNonNestableTask.

Change-Id: I2b69dc4d4b6de4079dcab05e8b5c3b1f77cbbe2c
Reviewed-on: https://chromium-review.googlesource.com/c/v8/v8/+/2253852
Commit-Queue: Marja Hölttä <marja@chromium.org>
Reviewed-by: Shu-yu Guo <syg@chromium.org>
Reviewed-by: Ulan Degenbaev <ulan@chromium.org>
Cr-Commit-Position: refs/heads/master@{#68475}

include/v8-platform.h

@@ -80,6 +80,14 @@ class TaskRunner {
    * implementation takes ownership of |task|. The |task| cannot be nested
    * within other task executions.
    *
+   * Tasks which shouldn't be interleaved with JS execution must be posted with
+   * |PostNonNestableTask| or |PostNonNestableDelayedTask|. This is because the
+   * embedder may process tasks in a callback which is called during JS
+   * execution.
+   *
+   * In particular, tasks which execute JS must be non-nestable, since JS
+   * execution is not allowed to nest.
+   *
    * Requires that |TaskRunner::NonNestableTasksEnabled()| is true.
    */
   virtual void PostNonNestableTask(std::unique_ptr<Task> task) {}
@@ -98,6 +106,14 @@ class TaskRunner {
    * implementation takes ownership of |task|. The |task| cannot be nested
    * within other task executions.
    *
+   * Tasks which shouldn't be interleaved with JS execution must be posted with
+   * |PostNonNestableTask| or |PostNonNestableDelayedTask|. This is because the
+   * embedder may process tasks in a callback which is called during JS
+   * execution.
+   *
+   * In particular, tasks which execute JS must be non-nestable, since JS
+   * execution is not allowed to nest.
+   *
    * Requires that |TaskRunner::NonNestableDelayedTasksEnabled()| is true.
    */
   virtual void PostNonNestableDelayedTask(std::unique_ptr<Task> task,