From 86a45ff561f7d8fb512feeb22044e1bc32fb7926 Mon Sep 17 00:00:00 2001 From: JiaLiPassion Date: Wed, 4 Mar 2020 10:46:02 +0900 Subject: [PATCH] docs(zone.js): update coments of zone configuration API definition (#35849) PR Close #35849 --- .../zone.js/lib/zone.configurations.api.ts | 261 +++++++++--------- 1 file changed, 130 insertions(+), 131 deletions(-) diff --git a/packages/zone.js/lib/zone.configurations.api.ts b/packages/zone.js/lib/zone.configurations.api.ts index 454e757e76..4eaa4bb94b 100644 --- a/packages/zone.js/lib/zone.configurations.api.ts +++ b/packages/zone.js/lib/zone.configurations.api.ts @@ -7,16 +7,16 @@ */ /** - * Interface of zone.js configurations. + * Interface of `zone.js` configurations. * - * You can define the following configurations on the window/global object before - * importing `dist/zone.js` to change zone.js default behaviors. + * You can define the following configurations on the `window/global` object before + * importing `zone.js` to change `zone.js` default behaviors. */ interface ZoneGlobalConfigurations { /** * Disable the monkey patch of the `Node.js` `EventEmitter` API. * - * By default, the `zone.js` monkey patches the `Node.js` `EventEmitter` APIs to make async + * By default, `zone.js` monkey patches the `Node.js` `EventEmitter` APIs to make asynchronous * callbacks of those APIs in the same zone when scheduled. * * Consider the following example: @@ -37,8 +37,8 @@ interface ZoneGlobalConfigurations { * myEmitter.emit('event'); * ``` * - * If you set `__Zone_disable_EventEmtter = true` before importing zone.js, - * `zone.js` does not monkey patch the `EventEmitter` API and the above code + * If you set `__Zone_disable_EventEmitter = true` before importing `zone.js`, + * `zone.js` does not monkey patch the `EventEmitter` APIs and the above code * outputs 'an event occurred '. */ __Zone_disable_EventEmitter?: boolean; @@ -46,8 +46,8 @@ interface ZoneGlobalConfigurations { /** * Disable the monkey patch of the `Node.js` `fs` API. * - * By default, the `zone.js` monkey patches `Node.js` `fs` APIs to make async callbacks of those - * APIs in the same zone when scheduled. + * By default, `zone.js` monkey patches `Node.js` `fs` APIs to make asynchronous callbacks of + * those APIs in the same zone when scheduled. * * Consider the following example: * @@ -64,7 +64,7 @@ interface ZoneGlobalConfigurations { * }); * ``` * - * If you set `__Zone_disable_fs = true` before importing zone.js, + * If you set `__Zone_disable_fs = true` before importing `zone.js`, * `zone.js` does not monkey patch the `fs` API and the above code * outputs 'get stats occurred '. */ @@ -73,8 +73,8 @@ interface ZoneGlobalConfigurations { /** * Disable the monkey patch of the `Node.js` `timer` API. * - * By default, the `zone.js` monkey patches the `Node.js` `timer` APIs to make async callbacks of - * those APIs in the same zone when scheduled. + * By default, `zone.js` monkey patches the `Node.js` `timer` APIs to make asynchronous + * callbacks of those APIs in the same zone when scheduled. * * Consider the following example: * @@ -90,7 +90,7 @@ interface ZoneGlobalConfigurations { * }); * ``` * - * If you set `__Zone_disable_timers = true` before importing zone.js, + * If you set `__Zone_disable_timers = true` before importing `zone.js`, * `zone.js` does not monkey patch the `timer` APIs and the above code * outputs 'timeout '. */ @@ -116,7 +116,7 @@ interface ZoneGlobalConfigurations { * }); * ``` * - * If you set `__Zone_disable_nextTick = true` before importing zone.js, + * If you set `__Zone_disable_nextTick = true` before importing `zone.js`, * `zone.js` does not monkey patch the `process.nextTick()` API and the above code * outputs 'nextTick '. */ @@ -125,8 +125,8 @@ interface ZoneGlobalConfigurations { /** * Disable the monkey patch of the `Node.js` `crypto` API. * - * By default, `zone.js` monkey patches the `Node.js` `crypto` APIs to make async callbacks of - * those APIs in the same zone when called. + * By default, `zone.js` monkey patches the `Node.js` `crypto` APIs to make asynchronous callbacks + * of those APIs in the same zone when called. * * Consider the following example: * @@ -144,7 +144,7 @@ interface ZoneGlobalConfigurations { * }); * ``` * - * If you set `__Zone_disable_crypto = true` before importing zone.js, + * If you set `__Zone_disable_crypto = true` before importing `zone.js`, * `zone.js` does not monkey patch the `crypto` API and the above code * outputs 'crypto '. */ @@ -153,14 +153,14 @@ interface ZoneGlobalConfigurations { /** * Disable the monkey patch of the `Object.defineProperty()` API. * - * NOTE: this configuration is only available in the legacy bundle (dist/zone.js), this - * module is not available in the evergreen bundle (zone-evergreen.js). + * Note: This configuration is available only in the legacy bundle (dist/zone.js). This module is + * not available in the evergreen bundle (zone-evergreen.js). * - * In the legacy browser, by default, `zone.js` monkey patches `Object.defineProperty()` - * `Object.create()` to try to ensure all property's configurable to be true. This patch is only - * needed in some old mobile browsers. + * In the legacy browser, the default behavior of `zone.js` is to monkey patch + * `Object.defineProperty()` and `Object.create()` to try to ensure PropertyDescriptor parameter's + * configurable property to be true. This patch is only needed in some old mobile browsers. * - * If you set `__Zone_disable_defineProperty = true` before importing zone.js, + * If you set `__Zone_disable_defineProperty = true` before importing `zone.js`, * `zone.js` does not monkey patch the `Object.defineProperty()` API and does not * modify desc.configurable to true. * @@ -173,8 +173,9 @@ interface ZoneGlobalConfigurations { * NOTE: This configuration is only available in the legacy bundle (dist/zone.js), this * module is not available in the evergreen bundle (zone-evergreen.js). * - * In the legacy bundle, by default, `zone.js` monkey patches `registerElement()` API to make - * async callbacks of the API in the same zone when `registerElement()` is called. + * In the legacy browser, the default behavior of `zone.js` is to monkey patch the + * `registerElement()` API to make asynchronous callbacks of the API in the same zone when + * `registerElement()` is called. * * Consider the following example: * @@ -199,10 +200,10 @@ interface ZoneGlobalConfigurations { * }); * ``` * - * When those callbacks are invoked, those callbacks will be in the zone when + * When these callbacks are invoked, those callbacks will be in the zone when * `registerElement()` is called. * - * If you set `__Zone_disable_registerElement = true` before importing zone.js, + * If you set `__Zone_disable_registerElement = true` before importing `zone.js`, * `zone.js` does not monkey patch `registerElement()` API and the above code * outputs ''. */ @@ -214,9 +215,9 @@ interface ZoneGlobalConfigurations { * NOTE: This configuration is only available in the legacy bundle (dist/zone.js), this module * is not available in the evergreen bundle (zone-evergreen.js). * - * In some old browsers, the `EventTarget` is not available, so `zone.js` can not directly monkey - * patch the `EventTarget`, instead zone.js patches all known Html Elements' prototypes(such as - * HtmlDivElement). So the callback of the `addEventListener()` will be in the same zone when + * In some old browsers, the `EventTarget` is not available, so `zone.js` cannot directly monkey + * patch the `EventTarget`. Instead, `zone.js` patches all known HTML elements' prototypes (such + * as `HtmlDivElement`). The callback of the `addEventListener()` will be in the same zone when * the `addEventListener()` is called. * * Consider the following example: @@ -231,10 +232,10 @@ interface ZoneGlobalConfigurations { * }); * ``` * - * If you set `__Zone_disable_EventTargetLegacy = true` before importing zone.js - * in some old browsers (`EventTarget` not available). - * `zone.js` does not monkey patch all Html Elements APIs and the above code - * outputs 'clicked '. + * If you set `__Zone_disable_EventTargetLegacy = true` before importing `zone.js` + * In some old browsers, where `EventTarget` is not available, if you set + * `__Zone_disable_EventTargetLegacy = true` before importing `zone.js`, `zone.js` does not monkey + * patch all HTML element APIs and the above code outputs 'clicked '. */ __Zone_disable_EventTargetLegacy?: boolean; @@ -242,8 +243,8 @@ interface ZoneGlobalConfigurations { * Disable the monkey patch of the browser `timer` APIs. * * By default, `zone.js` monkey patches browser timer - * APIs(`setTimeout()`/`setInterval()`/`setImmediate()`) to make async callbacks of those APIs in - * the same zone when scheduled. + * APIs (`setTimeout()`/`setInterval()`/`setImmediate()`) to make asynchronous callbacks of those + * APIs in the same zone when scheduled. * * Consider the following example: * @@ -259,7 +260,7 @@ interface ZoneGlobalConfigurations { * }); * ``` * - * If you set `__Zone_disable_timers = true` before importing zone.js, + * If you set `__Zone_disable_timers = true` before importing `zone.js`, * `zone.js` does not monkey patch `timer` API and the above code * outputs 'timeout '. * @@ -269,8 +270,9 @@ interface ZoneGlobalConfigurations { /** * Disable the monkey patch of the browser `requestAnimationFrame()` API. * - * By default, zone.js monkey patches the browser `requestAnimationFrame()` API - * to make the async callback of the `requestAnimationFrame()` in the same zone when scheduled. + * By default, `zone.js` monkey patches the browser `requestAnimationFrame()` API + * to make the asynchronous callback of the `requestAnimationFrame()` in the same zone when + * scheduled. * * Consider the following example: * @@ -286,7 +288,7 @@ interface ZoneGlobalConfigurations { * }); * ``` * - * If you set `__Zone_disable_requestAnimationframe = true` before importing zone.js, + * If you set `__Zone_disable_requestAnimationFrame = true` before importing `zone.js`, * `zone.js` does not monkey patch the `requestAnimationFrame()` API and the above code * outputs 'raf '. */ @@ -301,8 +303,8 @@ interface ZoneGlobalConfigurations { /** * Disable the monkey patch of the browser `EventTarget` APIs. * - * By default, `zone.js` monkey patches EventTarget APIs. So the callbacks of the - * `addEventListener()` runs in the same zone when the `addEventListener()` is called. + * By default, `zone.js` monkey patches EventTarget APIs. The callbacks of the + * `addEventListener()` run in the same zone when the `addEventListener()` is called. * * Consider the following example: * @@ -316,7 +318,7 @@ interface ZoneGlobalConfigurations { * }); * ``` * - * If you set `__Zone_disable_EventTarget = true` before importing zone.js, + * If you set `__Zone_disable_EventTarget = true` before importing `zone.js`, * `zone.js` does not monkey patch EventTarget API and the above code * outputs 'clicked '. * @@ -326,8 +328,8 @@ interface ZoneGlobalConfigurations { /** * Disable the monkey patch of the browser onProperty APIs(such as onclick). * - * By default, zone.js monkey patches onXXX properties(such as onclick). So the callbacks of onXXX - * properties runs in the same zone when the onXXX properties is set. + * By default, `zone.js` monkey patches onXXX properties (such as onclick). The callbacks of onXXX + * properties run in the same zone when the onXXX properties is set. * * Consider the following example: * @@ -341,7 +343,7 @@ interface ZoneGlobalConfigurations { * }); * ``` * - * If you set `__Zone_disable_on_property = true` before importing zone.js, + * If you set `__Zone_disable_on_property = true` before importing `zone.js`, * `zone.js` does not monkey patch onXXX properties and the above code * outputs 'clicked '. * @@ -351,8 +353,8 @@ interface ZoneGlobalConfigurations { /** * Disable the monkey patch of the browser `customElements` APIs. * - * By default, zone.js monkey patches `customElements` APIs to make callbacks of the custom - * Element run in the same zone when the element is defined. + * By default, `zone.js` monkey patches `customElements` APIs to make callbacks run in the + * same zone when the `customElements.define()` is called. * * Consider the following example: * @@ -374,7 +376,7 @@ interface ZoneGlobalConfigurations { * All those callbacks defined in TestCustomElement runs in the zone when * the `customElements.define()` is called. * - * If you set `__Zone_disable_customElements = true` before importing zone.js, + * If you set `__Zone_disable_customElements = true` before importing `zone.js`, * `zone.js` does not monkey patch `customElements` APIs and the above code * runs inside zone. */ @@ -383,7 +385,7 @@ interface ZoneGlobalConfigurations { /** * Disable the monkey patch of the browser `XMLHttpRequest` APIs. * - * By default, zone.js monkey patches `XMLHttpRequest` APIs to make XMLHttpRequest act + * By default, `zone.js` monkey patches `XMLHttpRequest` APIs to make XMLHttpRequest act * as macroTask. * * Consider the following example: @@ -404,10 +406,10 @@ interface ZoneGlobalConfigurations { * }); * ``` * - * In this example, the instance of the `XMLHttpRequest` runs in the zone and acts as macroTask, - * so the output is 'task is scheduled macroTask, XMLHttpRequest.send, zone'. + * In this example, the instance of XMLHttpRequest runs in the zone and acts as a macroTask. The + * output is 'task is scheduled macroTask, XMLHttpRequest.send, zone'. * - * If you set __Zone_disable_XHR = true before importing zone.js, + * If you set `__Zone_disable_XHR = true` before importing `zone.js`, * `zone.js` does not monkey patch `XMLHttpRequest` APIs and the above onScheduleTask callback * will not be called. * @@ -417,7 +419,7 @@ interface ZoneGlobalConfigurations { /** * Disable the monkey patch of the browser geolocation APIs. * - * By default, Zone.js monkey patches geolcation APIs to make callbacks run in the same zone + * By default, `zone.js` monkey patches geolocation APIs to make callbacks run in the same zone * when those APIs are called. * * Consider the following examples: @@ -436,7 +438,7 @@ interface ZoneGlobalConfigurations { * }); * ``` * - * If set you `__Zone_disable_geolocation = true` before importing zone.js, + * If set you `__Zone_disable_geolocation = true` before importing `zone.js`, * `zone.js` does not monkey patch geolocation APIs and the above code * outputs 'getCurrentPosition '. * @@ -446,7 +448,7 @@ interface ZoneGlobalConfigurations { /** * Disable the monkey patch of the browser `canvas` APIs. * - * By default, Zone.js monkey patches `canvas` APIs to make callbacks run in the same zone when + * By default, `zone.js` monkey patches `canvas` APIs to make callbacks run in the same zone when * those APIs are called. * * Consider the following example: @@ -464,7 +466,7 @@ interface ZoneGlobalConfigurations { * }); * ``` * - * If you set `__Zone_disable_canvas = true` before importing zone.js, + * If you set `__Zone_disable_canvas = true` before importing `zone.js`, * `zone.js` does not monkey patch `canvas` APIs and the above code * outputs 'canvas.toBlob '. */ @@ -473,8 +475,8 @@ interface ZoneGlobalConfigurations { /** * Disable the `Promise` monkey patch. * - * By default, zone.js monkey patckes `Promise` APIs to make the `then()/catch()` callbacks in the - * same zone when those callbacks are called. + * By default, `zone.js` monkey patches `Promise` APIs to make the `then()/catch()` callbacks in + * the same zone when those callbacks are called. * * Consider the following examples: * @@ -491,7 +493,7 @@ interface ZoneGlobalConfigurations { * }); * ``` * - * If you set `__Zone_disable_ZoneAwarePromise = true` before importing zone.js, + * If you set `__Zone_disable_ZoneAwarePromise = true` before importing `zone.js`, * `zone.js` does not monkey patch `Promise` APIs and the above code * outputs 'promise then callback '. */ @@ -500,103 +502,100 @@ interface ZoneGlobalConfigurations { /** * Define event names that users don't want monkey patched by the `zone.js`. * - * By default, zone.js monkey patches `EventTarget.addEventListener()`, so the event listener - * callback runs in the zone when `addEventListener()` is called. + * By default, `zone.js` monkey patches EventTarget.addEventListener(). The event listener + * callback runs in the same zone when the addEventListener() is called. * - * But sometimes, users don't want all the event names use this patched version because it - * has performance impact. For example, in some cases, users want `scroll` or `mousemove` event - * listeners run with native `addEventListener()` for better performance. + * Sometimes, you don't want all of the event names used in this patched version because it + * impacts performance. For example, you might want `scroll` or `mousemove` event listeners to run + * the native `addEventListener()` for better performance. * * Users can achieve this goal by defining `__zone_symbol__UNPATCHED_EVENTS = ['scroll', - * 'mousemove'];` before imporing `zone.js`. + * 'mousemove'];` before importing `zone.js`. */ __zone_symbol__UNPATCHED_EVENTS?: boolean; /** * Define the event names of the passive listeners. * - * Now Angular doesn't support to add event listeners as passive very easily. User needs to use - * `elem.addEventListener('scroll', listener, {passive: true});` or implements their own - * EventManagerPlugin to do that. Angular may finally support new template syntax to support - * passive event, for now, this configuration allows the user to define the - * passive event names in zone.js configurations. + * To add passive event listeners, you can use `elem.addEventListener('scroll', listener, + * {passive: true});` or implement your own `EventManagerPlugin`. * - * User can define a global varibale like this. + * You can also define a global variable as follows: * * ``` * __zone_symbol__PASSIVE_EVENTS = ['scroll']; * ``` * - * to let all `scroll` event listeners passive. + * The preceding code makes all scroll event listeners passive. */ __zone_symbol__PASSIVE_EVENTS?: boolean; } /** - * Interface of zone.js test configurations. + * Interface of `zone-testing.js` test configurations. * - * You can define the following configurations on the `window` or `global` object before - * importing `dist/zone-testing.js` to change zone.js default behaviors in the test runner. + * You can define the following configurations on the `window` or `global` object before + * importing `zone-testing.js` to change `zone-testing.js` default behaviors in the test runner. */ interface ZoneTestConfigurations { /** - * Disable the jasmine integration. + * Disable the Jasmine integration. * - * In the zone-testing.js bundle, by default, zone monkey patches jasmine APIs - * to make jasmine APIs run in specified zone. + * In the `zone-testing.js` bundle, by default, `zone-testing.js` monkey patches Jasmine APIs + * to make Jasmine APIs run in specified zone. * - * 1. Make the `describe()`/`xdescribe()`/`fdescribe()` run in the syncTestZone. - * 2. Make the `it()`/`xit()`/`fit()`/`beforeEach()`/`afterEach()`/`beforeAll()`/`afterAll()` run - * in the ProxyZone. + * 1. Make the `describe()`/`xdescribe()`/`fdescribe()` methods run in the syncTestZone. + * 2. Make the `it()`/`xit()`/`fit()`/`beforeEach()`/`afterEach()`/`beforeAll()`/`afterAll()` + * methods run in the ProxyZone. * - * With this patch, `async()`/`fakeAsync()` can work with the jasmine runner. + * With this patch, `async()`/`fakeAsync()` can work with the Jasmine runner. * - * If you set `__Zone_disable_jasmine = true` before importing `dist/zone-testing.js`, - * `zone.js` does not monkey patch the jasmine APIs and the `async()`/`fakeAsync()` can not - * work with the jasmine runner any longer. + * If you set `__Zone_disable_jasmine = true` before importing `zone-testing.js`, + * `zone-testing.js` does not monkey patch the jasmine APIs and the `async()`/`fakeAsync()` cannot + * work with the Jasmine runner any longer. */ __Zone_disable_jasmine?: boolean; /** - * Disable the mocha integration. + * Disable the Mocha integration. * - * In the `zone-testing.js` bundle, by default, zone monkey patches the mocha APIs - * to make mocha APIs run in the specified zone. + * In the `zone-testing.js` bundle, by default, `zone-testing.js` monkey patches the Mocha APIs + * to make Mocha APIs run in the specified zone. * - * 1. Make the `describe()`/`xdescribe()`/`fdescribe()` run in the syncTestZone. - * 2. Make the `it()`/`xit()`/`fit()`/`beforeEach()`/`afterEach()`/`beforeAll()`/`afterAll()` run - * in the ProxyZone. + * 1. Make the `describe()`/`xdescribe()`/`fdescribe()` methods run in the syncTestZone. + * 2. Make the `it()`/`xit()`/`fit()`/`beforeEach()`/`afterEach()`/`beforeAll()`/`afterAll()` + * methods run in the ProxyZone. * - * With this patch, `async()`/`fakeAsync()` can work with the mocha runner. + * With this patch, `async()`/`fakeAsync()` can work with the Mocha runner. * - * If you set `__Zone_disable_mocha = true` before importing zone-testing.js, - * `zone.js` does not monkey patch the mocha APIs and the `async()/`fakeAsync()` can not - * work with the mocha runner any longer. + * If you set `__Zone_disable_mocha = true` before importing `zone-testing.js`, + * `zone-testing.js` does not monkey patch the Mocha APIs and the `async()/`fakeAsync()` can not + * work with the Mocha runner any longer. */ __Zone_disable_mocha?: boolean; /** - * Disable the jest integration. + * Disable the Jest integration. * - * In the zone-testing.js bundle, by default, zone monkey patches jest APIs - * to make jest APIs run in the specified zone. + * In the `zone-testing.js` bundle, by default, `zone-testing.js` monkey patches Jest APIs + * to make Jest APIs run in the specified zone. * - * 1. Make the `describe()`/`xdescribe()`/`fdescribe()` run in the syncTestZone. - * 2. Make the `it()`/`xit()`/`fit()`/`beforeEach()`/`afterEach()`/`before()`/`after()` run - * in the ProxyZone. + * 1. Make the `describe()`/`xdescribe()`/`fdescribe()` methods run in the syncTestZone. + * 2. Make the `it()`/`xit()`/`fit()`/`beforeEach()`/`afterEach()`/`before()`/`after()` methods + * run in the ProxyZone. * - * With this patch, `async()`/`fakeAsync()` can work with the jest runner. + * With this patch, `async()`/`fakeAsync()` can work with the Jest runner. * - * If you set `__Zone_disable_jest = true` before importing zone-testing.js, - * `zone.js` does not monkey patch the jest APIs and `async()`/`fakeAsync()` can not - * work with the jest runner any longer. + * If you set `__Zone_disable_jest = true` before importing `zone-testing.js`, + * `zone-testing.js` does not monkey patch the jest APIs and `async()`/`fakeAsync()` cannot + * work with the Jest runner any longer. */ __Zone_disable_jest?: boolean; /** * Disable monkey patch the jasmine clock APIs. * - * By default, zone-testing.js monkey patches the `jasmine.clock()` API, + * By default, `zone-testing.js` monkey patches the `jasmine.clock()` API, * so the `jasmine.clock()` can work with the `fakeAsync()/tick()` API. * * Consider the following example: @@ -618,18 +617,18 @@ interface ZoneTestConfigurations { * }); * ``` * - * So in the `fakeAsync()`, `jasmine.clock().tick()` works just like `tick()`. + * In the `fakeAsync()` method, `jasmine.clock().tick()` works just like `tick()`. * * If you set `__zone_symbol__fakeAsyncDisablePatchingClock = true` before importing - * zone-testing.js,`zone.js` does not monkey patch the `jasmine.clock()` APIs and the - * `jasmine.clock()` can not work with `fakeAsync()` any longer. + * `zone-testing.js`,`zone-testing.js` does not monkey patch the `jasmine.clock()` APIs and the + * `jasmine.clock()` cannot work with `fakeAsync()` any longer. */ __zone_symbol__fakeAsyncDisablePatchingClock?: boolean; /** * Enable auto running into `fakeAsync()` when installing the `jasmine.clock()`. * - * By default, zone-testing.js does not automatically run into `fakeAsync()` + * By default, `zone-testing.js` does not automatically run into `fakeAsync()` * if the `jasmine.clock().install()` is called. * * Consider the following example: @@ -651,11 +650,11 @@ interface ZoneTestConfigurations { * }); * ``` * - * So we still need to run `fakeAsync()` to make a test case in the `FakeAsyncTestZone`. + * You must run `fakeAsync()` to make test cases in the `FakeAsyncTestZone`. * * If you set `__zone_symbol__fakeAsyncAutoFakeAsyncWhenClockPatched = true` before importing - * zone-testing.js, `zone.js` can run test case automatically into the `FakeAsyncTestZone` without - * calling the `fakeAsync()`. + * `zone-testing.js`, `zone-testing.js` can run test case automatically in the + * `FakeAsyncTestZone` without calling the `fakeAsync()`. * * Consider the following example: * @@ -682,9 +681,9 @@ interface ZoneTestConfigurations { /** * Enable waiting for the unresolved promise in the `async()` test. * - * In the `async()` test, `AsyncTestZone` waits for all the async tasks to be finished. But if - * some promises never resolved, by default, `AsyncTestZone` does not wait and report unexpected - * result. + * In the `async()` test, `AsyncTestZone` waits for all the asynchronous tasks to finish. By + * default, if some promises remain unresolved, `AsyncTestZone` does not wait and reports that it + * received an unexpected result. * * Consider the following example: * @@ -693,45 +692,45 @@ interface ZoneTestConfigurations { * it('async with never resolved promise test', async(() => { * const p = new Promise(() => {}); * p.then(() => { - * // do some expection. + * // do some expectation. * }); * })) * }); * ``` * - * By default, this case passes, because the callback of `p.then()` does not - * be called, and the `async()` does not wait there, because p is an unresolved - * promise, so there is no pending async task. + * By default, this case passes, because the callback of `p.then()` is never called. Because `p` + * is an unresolved promise, there is no pending asynchronous task, which means the `async()` + * method does not wait. * * If you set `__zone_symbol__supportWaitUnResolvedChainedPromise = true`, the above case - * timeouts, becasue `async()` will wait for the unresolved promise. + * times out, because `async()` will wait for the unresolved promise. */ __zone_symbol__supportWaitUnResolvedChainedPromise?: boolean; } /** - * The interface of the zone runtime configurations. + * The interface of the `zone.js` runtime configurations. * - * Those configurations can be defined on the `Zone` object after + * These configurations can be defined on the `Zone` object after * importing zone.js to change behaviors. The differences between - * the `ZoneRuntimeConfigurations` and the `ZoneGlobalConfigurations` are + * the `ZoneRuntimeConfigurations` and the `ZoneGlobalConfigurations` are, * - * 1. the `ZoneGlobalConfigurations` need to be defined on the global/window object before - * importing `dist/zone.js`, the value of the configuration can not be changed at runtime. + * 1. `ZoneGlobalConfigurations` must be defined on the `global/window` object before importing + * `zone.js`. The value of the configuration cannot be changed at runtime. * - * 2. the `ZoneRuntimeConfigurations` need to be defined on Zone object after importing - * `dist/zone.js`, the value of the configuration canbe changed at runtime. + * 2. `ZoneRuntimeConfigurations` must be defined on the `Zone` object after importing `zone.js`. + * You can change the value of this configuration at runtime. * */ interface ZoneRuntimeConfigurations { /** - * Ignore outputing error to console when uncaught Promise error occurs. + * Ignore outputting errors to the console when uncaught Promise errors occur. * - * By default, if uncaught Promise error occurs, zone.js outputs the + * By default, if an uncaught Promise error occurs, `zone.js` outputs the * error to the console by calling `console.error()`. * * If you set `__zone_symbol__ignoreConsoleErrorUncaughtError = true`, `zone.js` does not output - * uncaught error to `console.error()`. + * the uncaught error to `console.error()`. */ __zone_symbol__ignoreConsoleErrorUncaughtError?: boolean; }