runtime: Some nvim documentation fixes pointed by @oni-link

5 files changed, 32 insertions, 25 deletions

diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt
index 8f70279310..734202cd6c 100644
--- a/runtime/doc/autocmd.txt
+++ b/runtime/doc/autocmd.txt
@@ -303,7 +303,7 @@ Name			triggered by ~
 |InsertLeave|		when leaving Insert mode
 |InsertCharPre|		when a character was typed in Insert mode, before
 			inserting it
-|JobActivity|		when something interesting happen with a job
+|JobActivity|		when something interesting happens with a job
 
 |TextChanged|		after a change was made to the text in Normal mode
 |TextChangedI|		after a change was made to the text in Insert mode
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index bbd43f9b9a..ec2086e3eb 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -4019,7 +4019,12 @@ jobsend({job}, {data})					{Nvim} *jobsend()*
 jobstart({name}, {prog}[, {argv}])			{Nvim} *jobstart()*
 		Spawns {prog} as a job and associate it with the {name} string,
 		which will be used to match the "filename pattern" in
-		|JobActivity| events. See |job-control| for more information.
+		|JobActivity| events. It returns:
+		  - The job id on success, which is used by |jobsend()| and
+		    |jobstop()|
+		  - 0 when the job table is full or on invalid arguments
+		  - -1 when {prog} is not executable
+		See |job-control| for more information.
 
 jobstop({job})						{Nvim} *jobstop()*
 		Stop a job created with |jobstart| by sending a `SIGTERM`
@@ -5083,10 +5088,12 @@ rpcrequest({channel}, {method}[, {args}...])		 {Nvim} *rpcrequest()*
 
 rpcstart({prog}[, {argv}])				   {Nvim} *rpcstart()*
 		Spawns {prog} as a job(optionally passing the {argv} list),
-		and open a |msgpack-rpc| channel with the spawned process
-		stdin/stdout. Returns the channel id, which is used by
-		|rpcrequest()|, |rpcnotify()| and |rpcstop()|
-		It expects the rpc channel id as argument. Example: >
+		and opens a |msgpack-rpc| channel with the spawned process
+		stdin/stdout. It returns:
+		  - The channel id on success, which is used by |rpcrequest()|,
+		    |rpcnotify()| and |rpcstop()|
+		  - 0 on failure.
+		Example: >
 			:let rpc_chan = rpcstart('prog', ['arg1', 'arg2']) 
 
 rpcstop({channel})					    {Nvim} *rpcstop()*
diff --git a/runtime/doc/job_control.txt b/runtime/doc/job_control.txt
index c76b4f460b..49ee3889bc 100644
--- a/runtime/doc/job_control.txt
+++ b/runtime/doc/job_control.txt
@@ -66,14 +66,14 @@ nvim instance:
 <
 Here's what is happening:
 
-- Two bash instances are spawned |jobstart()| and their stdin/stdout/stderr
+- Two bash instances are spawned by |jobstart()| and their stdin/stdout/stderr
   are connected to nvim.
 - The first shell is idle, waiting to read commands from it's stdin
 - The second shell is passed the -c option to execute a command and exit. In
   our case, the command is a for loop that will print numbers and exit after
   a while.
 - The JobHandler function is called by the JobActivity autocommand(notice how
-  it the shell* pattern matches the `shell1` and `shell2` names passed to
+  the shell* pattern matches the `shell1` and `shell2` names passed to
   |jobstart()|), and it takes care of displaying stdout/stderr received from
   the shells.
 - The v:job_data is an array set by the JobActivity event. It has the
@@ -86,9 +86,9 @@ Here's what is happening:
 To send data to the job's stdin, one can use the |jobsend()| function, like
 this:
 >
-    :call jobsend(job1, 'ls\n')<cr>
-    :call jobsend(job1, 'invalid-command\n')<cr>
-    :call jobsend(job1, 'exit\n')<cr>
+    :call jobsend(job1, 'ls\n')
+    :call jobsend(job1, 'invalid-command\n')
+    :call jobsend(job1, 'exit\n')
 <
 A job may be killed at any time with the |jobstop()| function:
 >
diff --git a/runtime/doc/msgpack_rpc.txt b/runtime/doc/msgpack_rpc.txt
index 5e926b7318..eb15075d85 100644
--- a/runtime/doc/msgpack_rpc.txt
+++ b/runtime/doc/msgpack_rpc.txt
@@ -17,20 +17,20 @@ The Msgpack-RPC Interface to Nvim		  *msgpack-rpc*
 ==============================================================================
 1. Introduction						    *msgpack-rpc-intro*
 
-The primary means of controlling a running nvim instance is through
+The primary means of controlling a running Nvim instance is through
 MessagePack-RPC, a messaging protocol that uses the MessagePack serialization
 format: https://github.com/msgpack/msgpack/blob/7498cf3/spec.md.
 From now on, we'll be referring to the protocol as msgpack-rpc.
 
 At this point, only plugins use msgpack-rpc, but eventually even user
 interaction will be achieved through the protocol, since user interfaces will
-be separate programs that control a headless nvim instance.
+be separate programs that control a headless Nvim instance.
 
 This is what can be achieved by connecting to the msgpack-rpc interface:
 
-- Call any nvim API function
-- Listen for nvim events
-- Receive remote calls from nvim
+- Call any Nvim API function
+- Listen for Nvim events
+- Receive remote calls from Nvim
 
 Nvim's msgpack-rpc interface can be seen as a more powerful version of Vim's
 `clientserver` feature.
@@ -69,7 +69,7 @@ python and the pyyaml/msgpack-python pip packages):
 
 There are four ways to open msgpack-rpc streams to nvim:
 
-1. Through nvim's stdin/stdout when started with the `--embed` option. This
+1. Through nvim's stdin/stdout when started with the `--embed` option. This is
    how other programs can embed nvim.
 
 2. Through stdin/stdout of a program spawned by the |rpcstart()| function.
@@ -122,7 +122,7 @@ functions can be called interactively:
 Nvim is still alpha and there's no in-depth documentation explaining how to
 properly implement a client library. The python client(neovim pip package)
 will be always up-to-date with the latest API changes, so it's source code is
-best documentation currently available. There are some guidelines however:
+the best documentation currently available. There are some guidelines however:
 
 - Separate the transport layer from the rest of the library(See
   |msgpack-rpc-connecting| for details of how a client can connect to nvim).
@@ -134,7 +134,7 @@ best documentation currently available. There are some guidelines however:
 - Use a fiber/coroutine library for the language you are implementing a client
   for. These greatly simplify concurrency and allow the library to expose a
   blocking API on top of a non-blocking event loop without the complexity
-  that comes with preemptive multi-tasking.
+  that comes with preemptive multitasking.
 - Don't assume anything about the order that responses to msgpack-rpc requests
   will arrive.
 - Clients should expect to receive msgpack-rpc requests, which need to be
@@ -159,7 +159,7 @@ around C99 standard types). The types can be split into two groups:
 
 - Basic types that map natively to msgpack(and probably have a default
   representation in msgpack-supported programming languages)
-- Special Nvim types that map to msgpack ext with custom type codes.
+- Special Nvim types that map to msgpack EXT with custom type codes.
 
 Basic type mapping: 
 
@@ -171,7 +171,7 @@ String				  -> msgpack binary
 Array				  -> msgpack array
 Dictionary			  -> msgpack map
 
-Special Nvim types that use msgpack ext:
+Special Nvim types that use msgpack EXT:
 
 Buffer				  -> enum value kObjectTypeBuffer
 Window				  -> enum value kObjectTypeWindow
@@ -231,7 +231,7 @@ Four functions related to msgpack-rpc are available to vimscript:
 - |rpcstart()|: Similarly to |jobstart()|, this will spawn a co-process with
   it's standard handles connected to Nvim, the difference is that it's not
   possible to process raw data to/from the process stdin/stdout/stderr(Since
-  the job's stdin/stdout combo are used as a msgpack channgel that is
+  the job's stdin/stdout combo are used as a msgpack channel that is
   processed directly by Nvim C code).
 - |rpcstop()|: Same as |jobstop()|, but operates on handles returned by
   |rpcstart().|
diff --git a/runtime/doc/nvim_intro.txt b/runtime/doc/nvim_intro.txt
index 8989f35a79..d3aa459ba2 100644
--- a/runtime/doc/nvim_intro.txt
+++ b/runtime/doc/nvim_intro.txt
@@ -6,9 +6,9 @@
 
 Introduction to Nvim						   *nvim-intro*
 
-This is an introduction new Nvim users. It is meant for experienced Vim users
-that want to get started with Nvim. For a basic introduction to Vim, see
-|help.txt|.
+This is an introduction to Vim users that are just getting started with Nvim.
+It is not meant for Vim beginners. For a basic introduction to Vim,
+see |help.txt|.
 
 For now, it is just an index with the most relevant topics/features that
 differentiate Nvim from Vim: