From a5044dc7395fc92a25cedd7b2d4f93f6a6330632 Mon Sep 17 00:00:00 2001
From: Kapunahele Wong <kapunahelewong@gmail.com>
Date: Wed, 26 Feb 2020 16:41:59 -0500
Subject: [PATCH] docs: edit copy for tick() in testing and api docs (#35697)

Fixes #35696

PR Close #35697
---
 packages/core/testing/src/fake_async.ts | 65 ++++++++++++++++---------
 1 file changed, 41 insertions(+), 24 deletions(-)

diff --git a/packages/core/testing/src/fake_async.ts b/packages/core/testing/src/fake_async.ts
index 1c57da22c3819..5f0d1a014f4e0 100644
--- a/packages/core/testing/src/fake_async.ts
+++ b/packages/core/testing/src/fake_async.ts
@@ -26,21 +26,25 @@ export function resetFakeAsyncZone(): void {
 }
 
 /**
- * Wraps a function to be executed in the fakeAsync zone:
- * - microtasks are manually executed by calling `flushMicrotasks()`,
- * - timers are synchronous, `tick()` simulates the asynchronous passage of time.
+ * Wraps a function to be executed in the `fakeAsync` zone:
+ * - Microtasks are manually executed by calling `flushMicrotasks()`.
+ * - Timers are synchronous; `tick()` simulates the asynchronous passage of time.
  *
- * If there are any pending timers at the end of the function, an exception will be thrown.
+ * If there are any pending timers at the end of the function, an exception is thrown.
  *
- * Can be used to wrap inject() calls.
+ * Can be used to wrap `inject()` calls.
+ *
+ * @param fn The function that you want to wrap in the `fakeAysnc` zone.
  *
  * @usageNotes
  * ### Example
  *
  * {@example core/testing/ts/fake_async.ts region='basic'}
  *
- * @param fn
- * @returns The function wrapped to be executed in the fakeAsync zone
+ *
+ * @returns The function wrapped to be executed in the `fakeAsync` zone.
+ * Any arguments passed when calling this returned function will be passed through to the `fn`
+ * function in the parameters when it is called.
  *
  * @publicApi
  */
@@ -52,23 +56,36 @@ export function fakeAsync(fn: Function): (...args: any[]) => any {
 }
 
 /**
- * Simulates the asynchronous passage of time for the timers in the fakeAsync zone.
+ * Simulates the asynchronous passage of time for the timers in the `fakeAsync` zone.
  *
  * The microtasks queue is drained at the very start of this function and after any timer callback
  * has been executed.
  *
+ * @param millis The number of milliseconds to advance the virtual timer.
+ * @param tickOptions The options to pass to the `tick()` function.
+ *
  * @usageNotes
+ *
+ * The `tick()` option is a flag called `processNewMacroTasksSynchronously`,
+ * which determines whether or not to invoke new macroTasks.
+ *
+ * If you provide a `tickOptions` object, but do not specify a
+ * `processNewMacroTasksSynchronously` property (`tick(100, {})`),
+ * then `processNewMacroTasksSynchronously` defaults to true.
+ *
+ * If you omit the `tickOptions` parameter (`tick(100))`), then
+ * `tickOptions` defaults to `{processNewMacroTasksSynchronously: true}`.
+ *
  * ### Example
  *
  * {@example core/testing/ts/fake_async.ts region='basic'}
  *
- * @param millis, the number of millisecond to advance the virtual timer
- * @param tickOptions, the options of tick with a flag called
- * processNewMacroTasksSynchronously, whether to invoke the new macroTasks, by default is
- * false, means the new macroTasks will be invoked
- *
- * For example,
+ * The following example includes a nested timeout (new macroTask), and
+ * the `tickOptions` parameter is allowed to default. In this case,
+ * `processNewMacroTasksSynchronously` defaults to true, and the nested
+ * function is executed on each tick.
  *
+ * ```
  * it ('test with nested setTimeout', fakeAsync(() => {
  *   let nestedTimeoutInvoked = false;
  *   function funcWithNestedTimeout() {
@@ -80,10 +97,12 @@ export function fakeAsync(fn: Function): (...args: any[]) => any {
  *   tick();
  *   expect(nestedTimeoutInvoked).toBe(true);
  * }));
+ * ```
  *
- * in this case, we have a nested timeout (new macroTask), when we tick, both the
- * funcWithNestedTimeout and the nested timeout both will be invoked.
+ * In the following case, `processNewMacroTasksSynchronously` is explicitly
+ * set to false, so the nested timeout function is not invoked.
  *
+ * ```
  * it ('test with nested setTimeout', fakeAsync(() => {
  *   let nestedTimeoutInvoked = false;
  *   function funcWithNestedTimeout() {
@@ -95,9 +114,7 @@ export function fakeAsync(fn: Function): (...args: any[]) => any {
  *   tick(0, {processNewMacroTasksSynchronously: false});
  *   expect(nestedTimeoutInvoked).toBe(false);
  * }));
- *
- * if we pass the tickOptions with processNewMacroTasksSynchronously to be false, the nested timeout
- * will not be invoked.
+ * ```
  *
  *
  * @publicApi
@@ -113,12 +130,12 @@ export function tick(
 }
 
 /**
- * Simulates the asynchronous passage of time for the timers in the fakeAsync zone by
- * draining the macrotask queue until it is empty. The returned value is the milliseconds
- * of time that would have been elapsed.
+ * Simulates the asynchronous passage of time for the timers in the `fakeAsync` zone by
+ * draining the macrotask queue until it is empty.
  *
- * @param maxTurns
- * @returns The simulated time elapsed, in millis.
+ * @param maxTurns The maximum number of times the scheduler attempts to clear its queue before
+ *     throwing an error.
+ * @returns The simulated time elapsed, in milliseconds.
  *
  * @publicApi
  */