doc: improve AsyncWorker docs (#571)

PR-URL:  #571
Reviewed-By: NickNaso <[email protected]>
Reviewed-By: Michael Dawson <[email protected]>
Reviewed-By: Gabriel Schulhof <[email protected]>

doc/async_worker.md

@@ -7,8 +7,8 @@ operation.
 
 Once created, execution is requested by calling `Napi::AsyncWorker::Queue`. When
 a thread is available for execution the `Napi::AsyncWorker::Execute` method will
-be invoked.  Once `Napi::AsyncWorker::Execute` completes either
-`Napi::AsyncWorker::OnOK` or `Napi::AsyncWorker::OnError` will be invoked.  Once
+be invoked. Once `Napi::AsyncWorker::Execute` completes either
+`Napi::AsyncWorker::OnOK` or `Napi::AsyncWorker::OnError` will be invoked. Once
 the `Napi::AsyncWorker::OnOK` or `Napi::AsyncWorker::OnError` methods are
 complete the `Napi::AsyncWorker` instance is destructed.
 
@@ -38,7 +38,7 @@ void Napi::AsyncWorker::Queue();
 ### Cancel
 
 Cancels queued work if it has not yet been started. If it has already started
-executing, it cannot be cancelled.  If cancelled successfully neither
+executing, it cannot be cancelled. If cancelled successfully neither
 `OnOK` nor `OnError` will be called.
 
 ```cpp
@@ -90,14 +90,14 @@ void Napi::AsyncWorker::SetError(const std::string& error);
 
 ### Execute
 
-This method is used to execute some tasks out of the **event loop** on a libuv
+This method is used to execute some tasks outside of the **event loop** on a libuv
 worker thread. Subclasses must implement this method and the method is run on
-a thread other than that running the main event loop.  As the method is not
+a thread other than that running the main event loop. As the method is not
 running on the main event loop, it must avoid calling any methods from node-addon-api
 or running any code that might invoke JavaScript. Instead, once this method is
 complete any interaction through node-addon-api with JavaScript should be implemented
-in the `Napi::AsyncWorker::OnOK` method which runs on the main thread and is
-invoked when the `Napi::AsyncWorker::Execute` method completes.
+in the `Napi::AsyncWorker::OnOK` method and `Napi::AsyncWorker::OnError` which run
+on the main thread and are invoked when the `Napi::AsyncWorker::Execute` method completes.
 
 ```cpp
 virtual void Napi::AsyncWorker::Execute() = 0;
@@ -106,18 +106,19 @@ virtual void Napi::AsyncWorker::Execute() = 0;
 ### OnOK
 
 This method is invoked when the computation in the `Execute` method ends.
-The default implementation runs the Callback optionally provided when the AsyncWorker class
-was created. The callback will by default receive no arguments. To provide arguments,
-override the `GetResult()` method.
+The default implementation runs the `Callback` optionally provided when the
+`AsyncWorker` class was created. The `Callback` will by default receive no
+arguments. The arguments to the `Callback` can be provided by overriding the
+`GetResult()` method.
 
 ```cpp
 virtual void Napi::AsyncWorker::OnOK();
 ```
 ### GetResult
 
-This method returns the arguments passed to the Callback invoked by the default
+This method returns the arguments passed to the `Callback` invoked by the default
 `OnOK()` implementation. The default implementation returns an empty vector,
-providing no arguments to the Callback.
+providing no arguments to the `Callback`.
 
 ```cpp
 virtual std::vector<napi_value> Napi::AsyncWorker::GetResult(Napi::Env env);
@@ -128,7 +129,7 @@ virtual std::vector<napi_value> Napi::AsyncWorker::GetResult(Napi::Env env);
 This method is invoked after `Napi::AsyncWorker::Execute` completes if an error
 occurs while `Napi::AsyncWorker::Execute` is running and C++ exceptions are
 enabled or if an error was set through a call to `Napi::AsyncWorker::SetError`.
-The default implementation calls the callback provided when the `Napi::AsyncWorker`
+The default implementation calls the `Callback` provided when the `Napi::AsyncWorker`
 class was created, passing in the error as the first parameter.
 
 ```cpp
@@ -172,7 +173,7 @@ explicit Napi::AsyncWorker(const Napi::Function& callback, const char* resource_
 
 - `[in] callback`: The function which will be called when an asynchronous
 operations ends. The given function is called from the main event loop thread.
-- `[in] resource_name`: Null-terminated strings that represents the
+- `[in] resource_name`: Null-terminated string that represents the
 identifier for the kind of resource that is being provided for diagnostic
 information exposed by the async_hooks API.
 
@@ -189,7 +190,7 @@ explicit Napi::AsyncWorker(const Napi::Function& callback, const char* resource_
 
 - `[in] callback`: The function which will be called when an asynchronous
 operations ends. The given function is called from the main event loop thread.
-- `[in] resource_name`:  Null-terminated strings that represents the
+- `[in] resource_name`: Null-terminated string that represents the
 identifier for the kind of resource that is being provided for diagnostic
 information exposed by the async_hooks API.
 - `[in] resource`: Object associated with the asynchronous operation that
@@ -224,7 +225,7 @@ explicit Napi::AsyncWorker(const Napi::Object& receiver, const Napi::Function& c
 - `[in] receiver`: The `this` object passed to the called function.
 - `[in] callback`: The function which will be called when an asynchronous
 operations ends. The given function is called from the main event loop thread.
-- `[in] resource_name`:  Null-terminated strings that represents the
+- `[in] resource_name`: Null-terminated string that represents the
 identifier for the kind of resource that is being provided for diagnostic
 information exposed by the async_hooks API.
 
@@ -242,7 +243,7 @@ explicit Napi::AsyncWorker(const Napi::Object& receiver, const Napi::Function& c
 - `[in] receiver`: The `this` object passed to the called function.
 - `[in] callback`: The function which will be called when an asynchronous
 operations ends. The given function is called from the main event loop thread.
-- `[in] resource_name`:  Null-terminated strings that represents the
+- `[in] resource_name`: Null-terminated string that represents the
 identifier for the kind of resource that is being provided for diagnostic
 information exposed by the async_hooks API.
 - `[in] resource`: Object associated with the asynchronous operation that
@@ -274,7 +275,7 @@ explicit Napi::AsyncWorker(Napi::Env env, const char* resource_name);
 ```
 
 - `[in] env`: The environment in which to create the `Napi::AsyncWorker`.
-- `[in] resource_name`: Null-terminated strings that represents the
+- `[in] resource_name`: Null-terminated string that represents the
 identifier for the kind of resource that is being provided for diagnostic
 information exposed by the async_hooks API.
 
@@ -290,7 +291,7 @@ explicit Napi::AsyncWorker(Napi::Env env, const char* resource_name, const Napi:
 ```
 
 - `[in] env`: The environment in which to create the `Napi::AsyncWorker`.
-- `[in] resource_name`:  Null-terminated strings that represents the
+- `[in] resource_name`: Null-terminated string that represents the
 identifier for the kind of resource that is being provided for diagnostic
 information exposed by the async_hooks API.
 - `[in] resource`: Object associated with the asynchronous operation that
@@ -333,7 +334,7 @@ function runs in the background out of the **event loop** thread and at the end
 the `Napi::AsyncWorker::OnOK` or `Napi::AsyncWorker::OnError` function will be
 called and are executed as part of the event loop.
 
-The code below show a basic example of `Napi::AsyncWorker` the implementation:
+The code below shows a basic example of `Napi::AsyncWorker` the implementation:
 
 ```cpp
 #include<napi.h>
@@ -371,7 +372,7 @@ the work on the `Napi::AsyncWorker::Execute` method is done the
 `Napi::AsyncWorker::OnOk` method is called and the results return back to
 JavaScript invoking the stored callback with its associated environment.
 
-The following code shows an example on how to create and use an `Napi::AsyncWorker`
+The following code shows an example of how to create and use an `Napi::AsyncWorker`.
 
 ```cpp
 #include<napi.h>
@@ -382,7 +383,7 @@ The following code shows an example on how to create and use an `Napi::AsyncWork
 use namespace Napi;
 
 Value Echo(const CallbackInfo& info) {
-    // You need to check the input data here
+    // You need to validate the arguments here.
     Function cb = info[1].As<Function>();
     std::string in = info[0].As<String>();
     EchoWorker* wk = new EchoWorker(cb, in);