From 377b8359faaec60aab8d5ade978ee5aca2c97506 Mon Sep 17 00:00:00 2001 From: jeromepl Date: Sat, 9 Sep 2017 23:18:46 -0400 Subject: [PATCH] docs: fix grammar and spelling mistakes --- DEVELOPER.md | 2 +- MODULE.md | 13 +++++----- NON-STANDARD-APIS.md | 19 +++++++------- README.md | 14 +++++----- STANDARD-APIS.md | 51 +++++++++++++++++-------------------- lib/closure/zone_externs.js | 18 ++++++------- lib/zone.ts | 42 +++++++++++++++--------------- 7 files changed, 77 insertions(+), 82 deletions(-) diff --git a/DEVELOPER.md b/DEVELOPER.md index 80b410331..5804d31e1 100644 --- a/DEVELOPER.md +++ b/DEVELOPER.md @@ -62,7 +62,7 @@ chmod u+x .git/hooks/pre-commit Webdriver Test -------------- -Now `zone.js` also support run webdriver e2e test. +`zone.js` also supports running webdriver e2e tests. 1. run locally diff --git a/MODULE.md b/MODULE.md index 4aa01c360..377f66fa9 100644 --- a/MODULE.md +++ b/MODULE.md @@ -1,9 +1,8 @@ # Modules -zone.js patches the async APIs which described above, but those patch will have some overhead, -from zone.js v0.8.9, you can choose which web API module you want to patch, for example, -the below samples show how to disable some modules, you just need to define some global variables -before load zone.js. +Starting from zone.js v0.8.9, you can choose which web API modules you want to patch as to reduce overhead introduced by the patching of these modules. For example, +the below samples show how to disable some modules. You just need to define a few global variables +before loading zone.js. ``` ``` -Below is the full list of current support modules. +Below is the full list of currently supported modules. - Common @@ -58,7 +57,7 @@ Below is the full list of current support modules. - on_property -you can also disable specified on_property by setting `__Zone_ignore_on_properties`, for example, +You can also disable specific on_properties by setting `__Zone_ignore_on_properties` as follows: for example, if you want to disable `window.onmessage` and `HTMLElement.prototype.onclick` from zone.js patching, you can do like this. @@ -79,7 +78,7 @@ you can do like this. - Angular(2+) -Angular use zone.js to manage async operations and decide when to perform change detection, so in Angular, +Angular uses zone.js to manage async operations and decide when to perform change detection. Thus, in Angular, the following APIs should be patched, otherwise Angular may not work as expected. 1. ZoneAwarePromise diff --git a/NON-STANDARD-APIS.md b/NON-STANDARD-APIS.md index 978735f4b..c78a6b2e1 100644 --- a/NON-STANDARD-APIS.md +++ b/NON-STANDARD-APIS.md @@ -1,10 +1,9 @@ # Zone.js's support for non standard apis -Zone.js patched most standard APIs so they can be in zone. such as DOM events listener, XMLHttpRequest in Browser - and EventEmitter, fs API in nodejs. +Zone.js patched most standard APIs such as DOM event listeners, XMLHttpRequest in Browser, EventEmitter and fs API in Node.js so they can be in zone. -But there are still a lot of non standard APIs are not patched by default, such as MediaQuery, Notification, - WebAudio and so on. We are adding the support to those APIs, and the progress will be updated here. +But there are still a lot of non standard APIs that are not patched by default, such as MediaQuery, Notification, + WebAudio and so on. We are adding support to those APIs, and our progress is updated here. ## Currently supported non standard Web APIs @@ -95,9 +94,9 @@ to load the patch, you should load in the following order. ## Usage By default, those APIs' support will not be loaded in zone.js or zone-node.js, -so if you want to load those API's support, you should load those files by yourself +so if you want to load those API's support, you should load those files by yourself. -for example, if you want to add MediaQuery patch, you should do like this. +For example, if you want to add MediaQuery patch, you should do like this: ``` @@ -107,7 +106,7 @@ for example, if you want to add MediaQuery patch, you should do like this. * rxjs `zone.js` also provide a `rxjs` patch to make sure rxjs Observable/Subscription/Operator run in correct zone. -for detail please refer to [pull request 843](https://github.com/angular/zone.js/pull/843), the following sample code describe the idea. +For details please refer to [pull request 843](https://github.com/angular/zone.js/pull/843). The following sample code describes the idea. ``` const constructorZone = Zone.current.fork({name: 'constructor'}); @@ -143,7 +142,7 @@ operatorZone.run(() => { }); ``` -currently basically all `rxjs` API include +Currently basically everything the `rxjs` API includes - Observable - Subscription @@ -151,11 +150,11 @@ currently basically all `rxjs` API include - Operators - Scheduler -are patched, so they will run in the correct zone. +is patched, so each asynchronous call will run in the correct zone. ## Usage. -for example, in angular application, you can load this patch in your `app.module.ts`. +For example, in an Angular application, you can load this patch in your `app.module.ts`. ``` import 'zone.js/dist/zone-patch-rxjs'; diff --git a/README.md b/README.md index a5b2dc5ab..d2ca6a3bc 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ Implements _Zones_ for JavaScript, inspired by [Dart](https://www.dartlang.org/a > If you're using zone.js via unpkg please provide a query param `?main=browser` `https://unpkg.com/zone.js?main=browser` -> If you're using the following library, make sure you import them first +> If you're using any of the following libraries, make sure you import them first > * 'newrelic' as it patches global.Promise before zone.js does > * 'async-listener' as it patches global.setTimeout, global.setInterval before zone.js does @@ -37,19 +37,19 @@ See this video from ng-conf 2014 for a detailed explanation: ## Standard API support zone.js patched most standard web APIs(such as DOM events, XMLHttpRequest...) and nodejs APIs -(EventEmitter,fs ...), for more details, please see [STANDARD-APIS.md](STANDARD-APIS.md) for -more details. +(EventEmitter,fs ...), for more details, please see [STANDARD-APIS.md](STANDARD-APIS.md). ## Non standard API support -And now we are adding support to some non standard APIs, such as MediaQuery, +We are adding support to some non standard APIs, such as MediaQuery and Notification. Please see [NON-STANDARD-APIS.md](NON-STANDARD-APIS.md) for more details. ## Modules -zone.js patches the async APIs which described above, but those patch will have some overhead, -from zone.js v0.8.9, you can choose which web API module you want to patch, for detail, please -see [MODULE.md](MODULE.md) for more details. +zone.js patches the async APIs described above, but those patches will have some overhead. +Starting from zone.js v0.8.9, you can choose which web API module you want to patch. +For more details, please +see [MODULE.md](MODULE.md). ## Promise A+ test passed [![Promises/A+ 1.1 compliant](https://promisesaplus.com/assets/logo-small.png)](https://promisesaplus.com/) diff --git a/STANDARD-APIS.md b/STANDARD-APIS.md index f6ef0f7a6..f658a1287 100644 --- a/STANDARD-APIS.md +++ b/STANDARD-APIS.md @@ -1,24 +1,22 @@ # Zone.js's support for standard apis -Zone.js patched most standard APIs so they can be in zone. such as DOM events listener, XMLHttpRequest in Browser - and EventEmitter, fs API in nodejs. +Zone.js patched most standard APIs such as DOM event listeners, XMLHttpRequest in Browser, EventEmitter and fs API in Node.js so they can be in zone. -In this document, all patched API will be listed here. +In this document, all patched API are listed. -for non standard API, please reference to [NON-STANDARD-APIS.md](NON-STANDARD-APIS.md) +For non-standard APIs, please see [NON-STANDARD-APIS.md](NON-STANDARD-APIS.md) -## Patch Mechanism +## Patch Mechanisms -There are several patch mechanism +There are several patch mechanisms -- wrap, wrap will make callback in zone, and application can receive onInvoke, onIntercept callback -- Task, just like javascript vm, application can receive onScheduleTask, onInvokeTask, onCancelTask, onHasTask callback +- wrap: makes callbacks run in zones, and makes applications able to receive onInvoke and onIntercept callbacks +- Task: just like in the JavaScript VM, applications can receive onScheduleTask, onInvokeTask, onCancelTask and onHasTask callbacks 1. MacroTask - 2. MicroTask + 2. MicroTask 3. EventTask -Now there are some APIs should be treated as Tasks, but still be patched in wrap way, they will be -patched as Task soon. +Some APIs which should be treated as Tasks, but are currently still patched in the wrap way. These will be patched as Tasks soon. ## Browser @@ -54,9 +52,9 @@ Web APIs EventTarget -- For browser support eventTarget, zone.js just patch EventTarget, so everything -inherit from EventTarget will also be patched. -- For browser does not support eventTarget, zone.js will patch the following APIs in the IDL +- For browsers supporting EventTarget, Zone.js just patches EventTarget, so everything that inherits +from EventTarget will also be patched. +- For browsers that do not support EventTarget, Zone.js will patch the following APIs in the IDL that inherit from EventTarget ||||| @@ -69,8 +67,7 @@ inherit from EventTarget will also be patched. |IDBRequest|IDBOpenDBRequest|IDBDatabase|IDBTransaction| |IDBCursor|DBIndex|WebSocket| -on properties, such as onclick, onreadystatechange, the following on properties will -be patched as EventTask, the following is the on properties zone.js patched +The following 'on' properties, such as onclick, onreadystatechange, are patched in Zone.js as EventTasks ||||| |---|---|---|---| @@ -104,28 +101,28 @@ be patched as EventTask, the following is the on properties zone.js patched | crypto | MacroTask | | | fs | MacroTask | all async methods are patched | -EventEmitter, addEventListener, prependEventListener, on, once will be patched as EventTask, and removeEventListener, -removeAllListeners will remove those eventTasks +EventEmitter, addEventListener, prependEventListener and 'on' will be patched once as EventTasks, and removeEventListener and +removeAllListeners will remove those EventTasks ## Electron -zone.js did not patch electron API, but in electron, both browser APIs and node APIs are patched, so -when you want to include zone.js in Electron, please use dist/zone-mix.js +Zone.js does not patch the Electron API, although in Electron both browser APIs and node APIs are patched, so +if you want to include Zone.js in Electron, please use dist/zone-mix.js ## ZoneAwareError -ZoneAwareError replace global Error, and it will add zone information to stack trace. -ZoneAwareError will also handle 'this' issue. -such as create an error without new, then this will be undefined in strict mode, and global in -non-strict mode. it will cause some issues and very difficult to detect. +ZoneAwareError replaces global Error, and adds zone information to stack trace. +ZoneAwareError also handles 'this' issue. +This type of issue would happen when creating an error without `new`: `this` would be `undefined` in strict mode, and `global` in +non-strict mode. It could cause some very difficult to detect issues. ```javascript const error = Error(); ``` -ZoneAwareError will make sure that `this` is ZoneAwareError even without new. +ZoneAwareError makes sure that `this` is ZoneAwareError even without new. ## ZoneAwarePromise -ZoneAwarePromise wrap the global Promise and make it in zone and run as microTask, -it also passes promise A+ tests. +ZoneAwarePromise wraps the global Promise and makes it run in zones as a MicroTask. +It also passes promise A+ tests. diff --git a/lib/closure/zone_externs.js b/lib/closure/zone_externs.js index a467aaa2b..1fdf456b8 100644 --- a/lib/closure/zone_externs.js +++ b/lib/closure/zone_externs.js @@ -178,7 +178,7 @@ var ZoneSpec = function() {}; ZoneSpec.prototype.name; /** - * @type {Object|undefined} A set of properties to be associated with Zone. Use [Zone.get] to retrive them. + * @type {Object|undefined} A set of properties to be associated with Zone. Use [Zone.get] to retrieve them. */ ZoneSpec.prototype.properties; @@ -266,21 +266,21 @@ var ZoneDelegate = function() {}; */ ZoneDelegate.prototype.zone; /** - * @param {!Zone} targetZone the [zone] which originally received the request. + * @param {!Zone} targetZone the [Zone] which originally received the request. * @param {!ZoneSpec} zoneSpec the argument passed into the `fork` method. * @returns {!Zone} the new forked zone */ ZoneDelegate.prototype.fork = function(targetZone, zoneSpec) {}; /** - * @param {!Zone} targetZone the [zone] which originally received the request. + * @param {!Zone} targetZone the [Zone] which originally received the request. * @param {!Function} callback the callback function passed into `wrap` function - * @param {string=} source the argument passed into the `warp` method. + * @param {string=} source the argument passed into the `wrap` method. * @returns {!Function} */ ZoneDelegate.prototype.intercept = function(targetZone, callback, source) {}; /** - * @param {Zone} targetZone the [zone] which originally received the request. + * @param {Zone} targetZone the [Zone] which originally received the request. * @param {!Function} callback the callback which will be invoked. * @param {?Object=} applyThis the argument passed into the `run` method. * @param {?Array=} applyArgs the argument passed into the `run` method. @@ -289,14 +289,14 @@ ZoneDelegate.prototype.intercept = function(targetZone, callback, source) {}; */ ZoneDelegate.prototype.invoke = function(targetZone, callback, applyThis, applyArgs, source) {}; /** - * @param {!Zone} targetZone the [zone] which originally received the request. - * @param {!Object} error the argument passed into the `handleerror` method. + * @param {!Zone} targetZone the [Zone] which originally received the request. + * @param {!Object} error the argument passed into the `handleError` method. * @returns {boolean} */ ZoneDelegate.prototype.handleError = function(targetZone, error) {}; /** - * @param {!Zone} targetZone the [zone] which originally received the request. - * @param {!Task} task the argument passed into the `scheduletask` method. + * @param {!Zone} targetZone the [Zone] which originally received the request. + * @param {!Task} task the argument passed into the `scheduleTask` method. * @returns {!Task} task */ ZoneDelegate.prototype.scheduleTask = function(targetZone, task) {}; diff --git a/lib/zone.ts b/lib/zone.ts index 2e4288a99..827abc965 100644 --- a/lib/zone.ts +++ b/lib/zone.ts @@ -75,7 +75,7 @@ * achieving the request. (Useful for unit testing, or tracking of requests). In some instances * such as `setTimeout` the wrapping of the wrapCallback and scheduling is done in the same * wrapCallback, but there are other examples such as `Promises` where the `then` wrapCallback is - * wrapped, but the execution of `then` in triggered by `Promise` scheduling `resolve` work. + * wrapped, but the execution of `then` is triggered by `Promise` scheduling `resolve` work. * * Fundamentally there are three kinds of tasks which can be scheduled: * @@ -99,14 +99,14 @@ * * [TimerTask]s represent work which will be done after some delay. (Sometimes the delay is * approximate such as on next available animation frame). Typically these methods include: - * `setTimeout`, `setImmediate`, `setInterval`, `requestAnimationFrame`, and all browser specif + * `setTimeout`, `setImmediate`, `setInterval`, `requestAnimationFrame`, and all browser specific * variants. * * * ### [EventTask] * * [EventTask]s represent a request to create a listener on an event. Unlike the other task - * events may never be executed, but typically execute more than once. There is no queue of + * events they may never be executed, but typically execute more than once. There is no queue of * events, rather their callbacks are unpredictable both in order and time. * * @@ -119,17 +119,17 @@ * rules. A child zone is expected to either: * * 1. Delegate the interception to a parent zone, and optionally add before and after wrapCallback - * hook.s - * 2) Or process the request itself without delegation. + * hooks. + * 2. Process the request itself without delegation. * - * Composability allows zones to keep their concerns clean. For example a top most zone may chose - * to handle error handling, while child zones may chose to do user action tracking. + * Composability allows zones to keep their concerns clean. For example a top most zone may choose + * to handle error handling, while child zones may choose to do user action tracking. * * * ## Root Zone * - * At the start the browser will run in a special root zone, which is configure to behave exactly - * like the platform, making any existing code which is not-zone aware behave as expected. All + * At the start the browser will run in a special root zone, which is configured to behave exactly + * like the platform, making any existing code which is not zone-aware behave as expected. All * zones are children of the root zone. * */ @@ -202,7 +202,7 @@ interface Zone { * Any exceptions thrown will be forwarded to [Zone.HandleError]. * * The invocation of `callback` can be intercepted by declaring [ZoneSpec.onInvoke]. The - * handling of exceptions can intercepted by declaring [ZoneSpec.handleError]. + * handling of exceptions can be intercepted by declaring [ZoneSpec.handleError]. * * @param callback The function to invoke. * @param applyThis @@ -282,7 +282,7 @@ interface Zone { interface ZoneType { /** - * @returns {Zone} Returns the current [Zone]. Returns the current zone. The only way to change + * @returns {Zone} Returns the current [Zone]. The only way to change * the current zone is by invoking a run() method, which will update the current zone for the * duration of the run method callback. */ @@ -370,8 +370,8 @@ interface ZoneSpec { * @param parentZoneDelegate Delegate which performs the parent [ZoneSpec] operation. * @param currentZone The current [Zone] where the current interceptor has been declared. * @param targetZone The [Zone] which originally received the request. - * @param delegate The argument passed into the `warp` method. - * @param source The argument passed into the `warp` method. + * @param delegate The argument passed into the `wrap` method. + * @param source The argument passed into the `wrap` method. */ onIntercept?: (parentZoneDelegate: ZoneDelegate, currentZone: Zone, targetZone: Zone, delegate: Function, @@ -449,9 +449,9 @@ interface ZoneSpec { * * A ZoneDelegate is needed because a child zone can't simply invoke a method on a parent zone. For * example a child zone wrap can't just call parent zone wrap. Doing so would create a callback - * which is bound to the parent zone. What we are interested is intercepting the callback before it - * is bound to any zone. Furthermore, we also need to pass the targetZone (zone which received the - * original request) to the delegate. + * which is bound to the parent zone. What we are interested in is intercepting the callback before + * it is bound to any zone. Furthermore, we also need to pass the targetZone (zone which received + * the original request) to the delegate. * * The ZoneDelegate methods mirror those of Zone with an addition of extra targetZone argument in * the method signature. (The original Zone which received the request.) Some methods are renamed @@ -459,7 +459,7 @@ interface ZoneSpec { * * - `wrap` => `intercept`: The `wrap` method delegates to `intercept`. The `wrap` method returns * a callback which will run in a given zone, where as intercept allows wrapping the callback - * so that additional code can be run before and after, but does not associated the callback + * so that additional code can be run before and after, but does not associate the callback * with the zone. * - `run` => `invoke`: The `run` method delegates to `invoke` to perform the actual execution of * the callback. The `run` method switches to new zone; saves and restores the `Zone.current`; @@ -534,7 +534,7 @@ interface TaskData { * frame becomes clean and before a VM yield. All [MicroTask]s execute in order of insertion * before VM yield and the next [MacroTask] is executed. * - [MacroTask] queue represents a set of tasks which are executed one at a time after each VM - * yield. The queue is order by time, and insertions can happen in any location. + * yield. The queue is ordered by time, and insertions can happen in any location. * - [EventTask] is a set of tasks which can at any time be inserted to the end of the [MacroTask] * queue. This happens when the event fires. * @@ -556,7 +556,7 @@ interface Task { source: string; /** - * The Function to be used by the VM on entering the [Task]. This function will delegate to + * The Function to be used by the VM upon entering the [Task]. This function will delegate to * [Zone.runTask] and delegate to `callback`. */ invoke: Function; @@ -575,7 +575,7 @@ interface Task { /** * Represents the default work which needs to be done to schedule the Task by the VM. * - * A zone may chose to intercept this function and perform its own scheduling. + * A zone may choose to intercept this function and perform its own scheduling. */ scheduleFn: (task: Task) => void; @@ -583,7 +583,7 @@ interface Task { * Represents the default work which needs to be done to un-schedule the Task from the VM. Not all * Tasks are cancelable, and therefore this method is optional. * - * A zone may chose to intercept this function and perform its own scheduling. + * A zone may chose to intercept this function and perform its own un-scheduling. */ cancelFn: (task: Task) => void;