fixup! Async.Promise: Fix/brush up the help document

Author: rhysd

doc/vital/Async/Promise.txt

@@ -51,7 +51,8 @@ https://www.ecma-international.org/publications/standards/Ecma-262.htm
 REQUIREMENTS				*Vital.Async.Promise-requirements*
 
 |Vital.Async.Promise| requires |lambda| and |timers| features.
-So Vim 8.0 or later is required. Recent version of Neovim also supports them.
+So Vim 8.0 or later is required. The recent version of Neovim also supports
+them.
 
 
 
@@ -74,9 +75,9 @@ Before explaining the detail of APIs, let's see actual examples.
   One of most simple asynchronous operation is a timer. It calls a specified
   callback when exceeding the timeout. "s:Promise.new" creates a new Promise
   object with given callback. In the callback, function "resolve" (and
-  "reject" if needed) is passed. When asynchronous operation is done (in this
-  case, when timer is expired), call "resolve" on success or call "reject" on
-  failure.
+  "reject" if needed) is passed. When the asynchronous operation is done (in
+  this case, when the timer is expired), call "resolve" on success or call
+  "reject" on failure.
 
 
 (2) Next tick				*Vital.Async.Promise-example-next-tick*
@@ -92,8 +93,9 @@ Before explaining the detail of APIs, let's see actual examples.
     \.catch({err -> execute('echom err', '')})
 <
   By giving 0 to |timer_start()| as timeout, it waits for "next tick". It's the
-  first time when Vim waits input. It means that Vim gives higher priority to
-  user input and executes the script (in callback of |timer_start()|) after.
+  first time when Vim waits for input. It means that Vim gives higher priority
+  to user input and executes the script (in the callback of |timer_start()|)
+  after.
 
 
 (3) Job				*Vital.Async.Promise-example-job*
@@ -120,26 +122,26 @@ Before explaining the detail of APIs, let's see actual examples.
   endfunction
 <
   |job| is a feature to run commands asynchronously. But it is a bit hard to use
-  because it requires callback. By wrapping it with Promise, it makes further
-  easier to use commands and handle errors asynchronously.
+  because it requires a callback. By wrapping it with Promise, it makes
+  further easier to use commands and handle errors asynchronously.
 
-  s:read() is just a helper fnction which reads all output of channel from
-  job. So it's not so important.
+  s:read() is just a helper function which reads all output of channel from
+  the job. So it's not so important.
 
   Important part is "return ..." in s:sh(). It creates a Promise which starts
   a job and resolves when the given command has done. It calls resolve() when
-  the command finished successfully with output from stdout, and calls
-  reject() when the command failed with output from stderr.
+  the command finished successfully with an output from stdout, and calls
+  reject() when the command failed with an output from stderr.
 
-  "ls -l" can be executed as following:
+  "ls -l" can be executed as follows:
 >
   call s:sh('ls', '-l')
         \.then({out -> execute('echo "Output: " . out', '')})
         \.catch({err -> execute('echo "Error: " . err', '')})
 <
-  As more complex example, following code clones 4 repositories and shows a
-  message when all of them has completed. When one of them fails, it shows an
-  error message without waiting other operations.
+  As the more complex example, following code clones 4 repositories and shows
+  a message when all of them has completed. When one of them fails, it shows
+  an error message without waiting for other operations.
 >
   call s:Promise.all([
   \  s:sh('git', 'clone', 'https://github.com/thinca/vim-quickrun.git'),
@@ -169,11 +171,11 @@ Before explaining the detail of APIs, let's see actual examples.
   \})
 <
   s:sh() and s:wait() are explained above. And .race() awaits one of given
-  Promise objects has finished.
+  Promise objects have finished.
 
   The .race() awaits either s:sh(...) or s:wait(...) has completed or failed.
   It means that it clones Vim repository from GitHub via git command, but if
-  it exceeds 10 seconds, it does not wait the clone operation anymore.
+  it exceeds 10 seconds, it does not wait for the clone operation anymore.
 
   By adding .then() and giving the result value (v:false or v:true here), you
   can know whether the asynchronous operation was timed out or not in
@@ -223,10 +225,10 @@ new({executor})				*Vital.Async.Promise.new()*
 
 	{executor} is a |Funcref| which represents how to create a Promise
 	object. It is called _synchronously_. It receives two functions as
-	parameters. First parameter is "resolve". It accepts one or zero
+	parameters. The first parameter is "resolve". It accepts one or zero
 	argument. By calling it in {executor}, new() returns a fulfilled
-	Promise object. Second parameter is "reject". It also accepts one or
-	zero argument. By calling it in {executor}, new() returns rejected
+	Promise object. The second parameter is "reject". It also accepts one
+	or zero argument. By calling it in {executor}, new() returns rejected
 	Promise object.
 >
 	  " Fulfilled Promise object with 42
@@ -236,9 +238,9 @@ new({executor})				*Vital.Async.Promise.new()*
 	  let p = Promise.new({_, reject -> reject('ERROR!')})
 	  let p = Promise.new({-> execute('throw "ERROR!"')})
 <
-	When other Promise object is passed to "resolve" or "reject" function
-	call, new() returns a pending Promise object which awaits until the
-	given other Promise object has finished.
+	When another Promise object is passed to "resolve" or "reject"
+	function call, new() returns a pending Promise object which awaits
+	until the given other Promise object has finished.
 
 	If an exception is thrown in {executor}, new() returns a rejected
 	Promise object with the exception.
@@ -285,16 +287,16 @@ reject([{value}])			*Vital.Async.Promise.reject()*
 <
 all({promises})				*Vital.Async.Promise.all()*
 
-	Creates a Promise object which awaits until all of {promises} has
-	completed. It resolves the Promise object with a list of results of
-	{promises} as following:
+	Creates a Promise object which awaits all of {promises} has completed.
+	It resolves the Promise object with a list of results of {promises} as
+	following:
 >
 	  call Promise.all([Promise.resolve(1), Promise.resolve('foo')])
 	  \.then({arr -> execute('echo arr', '')})
 	  " It shows [1, 'foo']
 <
-	If one of them is rejected, it does not await for other
-	Promise objects and the Promise object is rejected immediately.
+	If one of them is rejected, it does not await other Promise objects
+	and the Promise object is rejected immediately.
 
 >
 	  call Promise.all([Promise.resolve(1), Promise.reject('ERROR!')])
@@ -404,8 +406,8 @@ asynchronous operation. It represents one of following states:
 
 {promise}.catch([{onRejected}])		*Vital.Async.Promise-Promise.catch()*
 
-	It is a shortcut function of calling .then() where first argument is
-	|v:null|.
+	It is a shortcut function of calling .then() where the first argument
+	is |v:null|.
 >
 	  " Followings are equal
 	  call Promise.reject('ERROR').then(v:null, {msg -> execute('echo msg', '')})
@@ -416,7 +418,7 @@ Exception Object			*Vital.Async.Promise-objects-Exception*
 
 Exception object represents an exception of Vim script. Since Vim script's
 |v:exception| is a |String| value and a stack trace of the exception is
-separated to |v:throwpoint| variable, it does not fit to Promise API.
+separated to |v:throwpoint| variable, it does not fit Promise API.
 So we need to define our own exception object. It is passed to {onRejected}
 parameter of .then() or .catch() method.
 
@@ -433,8 +435,8 @@ Example:
   " {'exception': 'Vim(return):E691: ...', 'throwpoint': '...'}
 <
 Exception object has two fields; "exception" and "throwpoint".
-"exception" is a error message. It's corresponding to |v:exception|. And
-"throwpoint" is a stack trace of caught exception. It's corresponding to
+"exception" is an error message. It's corresponding to |v:exception|. And
+"throwpoint" is a stack trace of the caught exception. It's corresponding to
 |v:throwpoint|.
 
 ==============================================================================