Merge #9335 from justinmk/doc

14 files changed, 94 insertions, 93 deletions

diff --git a/README.md b/README.md
index 0aa77b1e68..39d809002e 100644
--- a/README.md
+++ b/README.md
@@ -44,6 +44,15 @@ Features
 
 See [`:help nvim-features`][nvim-features] for the full list!
 
+Install from package
+--------------------
+
+Pre-built packages for Windows, macOS, and Linux are found on the
+[Releases](https://github.com/neovim/neovim/releases/) page.
+
+Managed packages are in [Homebrew], [Debian], [Ubuntu], [Fedora], [Arch Linux], [Gentoo],
+and [more](https://github.com/neovim/neovim/wiki/Installing-Neovim)!
+
 Install from source
 -------------------
 
@@ -55,26 +64,36 @@ To install to a non-default location, set `CMAKE_INSTALL_PREFIX`:
     make CMAKE_EXTRA_FLAGS="-DCMAKE_INSTALL_PREFIX=/full/path/"
     make install
 
-To list all targets:
-
-    cmake --build build --target help
-
-To skip "bundled" dependencies (`third-party/*`) define `USE_BUNDLED=NO`:
-
-    sudo apt install gperf libluajit-5.1-dev libunibilium-dev libmsgpack-dev libtermkey-dev libvterm-dev libjemalloc-dev
-    make USE_BUNDLED=NO
+To skip bundled (`third-party/*`) dependencies:
+
+1. Install the dependencies using a package manager.
+   ```
+   sudo apt install gperf luajit luarocks libuv1-dev libluajit-5.1-dev libunibilium-dev libmsgpack-dev libtermkey-dev libvterm-dev libjemalloc-dev
+   sudo luarocks build mpack
+   sudo luarocks build lpeg
+   sudo luarocks build inspect
+   ```
+2. Build with `USE_BUNDLED=OFF`:
+   ```
+   make CMAKE_BUILD_TYPE=RelWithDebInfo USE_BUNDLED=OFF
+   sudo make install
+   ```
+
+CMake features:
+
+- List all build targets:
+  ```
+  cmake --build build --target help
+  ```
+- Print all variable definitions:
+  ```
+  cmake -LAH
+  ```
+- `build/CMakeCache.txt` contains the resolved values of all CMake variables.
+- `build/compile_commands.json` shows the full compiler invocations for each translation unit.
 
 See the [Building Neovim](https://github.com/neovim/neovim/wiki/Building-Neovim) wiki page for details.
 
-Install from package
---------------------
-
-Pre-built packages for Windows, macOS, and Linux are found on the
-[Releases](https://github.com/neovim/neovim/releases/) page.
-
-Managed packages are in [Homebrew], [Debian], [Ubuntu], [Fedora], [Arch Linux], [Gentoo],
-and [more](https://github.com/neovim/neovim/wiki/Installing-Neovim)!
-
 Transitioning from Vim
 --------------------
 
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 7dab69df22..2520a15890 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -546,25 +546,24 @@ nvim_set_current_tabpage({tabpage})               *nvim_set_current_tabpage()*
                     {tabpage}  Tabpage handle
 
 nvim_create_namespace({name})                        *nvim_create_namespace()*
-                create a new namespace, or get one with an exisiting name
+                Creates a new namespace, or gets an existing one
 
-                Namespaces are currently used for buffer highlighting and
-                virtual text, see |nvim_buf_add_highlight| and
-                |nvim_buf_set_virtual_text|.
+                Namespaces are used for buffer highlights and virtual text,
+                see |nvim_buf_add_highlight()| and
+                |nvim_buf_set_virtual_text()|.
 
-                Namespaces can have a name of be anonymous. If `name` is a
-                non-empty string, and a namespace already exists with that
-                name,the existing namespace id is returned. If an empty string
-                is used, a new anonymous namespace is returned.
+                Namespaces can be named or anonymous. If `name` matches an
+                existing namespace, the associated id is returned. If `name`
+                is an empty string a new, anonymous namespace is created.
 
                 Parameters: ~
-                    {name}  Name of the namespace or empty string
+                    {name}  Namespace name or empty string
 
                 Return: ~
-                    the namespace id
+                    Namespace id
 
 nvim_get_namespaces()                                  *nvim_get_namespaces()*
-                Get existing named namespaces
+                Gets existing, non-anonymous namespaces
 
                 Return: ~
                     dict that maps from names to namespace ids.
diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt
index 2c919f9104..e244072c66 100644
--- a/runtime/doc/develop.txt
+++ b/runtime/doc/develop.txt
@@ -137,6 +137,13 @@ DOCUMENTATION						*dev-doc*
       "the user host terminal".
     - Use "tui-" to prefix help tags related to the host terminal, and "TUI"
       in prose if possible.
+- Docstrings: do not start parameter descriptions with "The" or "A" unless it
+  is critical to avoid ambiguity.
+      GOOD: >
+      /// @param dirname Path fragment before `pend`
+<      BAD: >
+      /// @param dirname The path fragment before `pend`
+<
 
 API							*dev-api*
 
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index 6dffd6f05e..e9579d5c86 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -1886,8 +1886,6 @@ v:termresponse	The escape sequence returned by the terminal for the DA
 
 					*v:testing* *testing-variable*
 v:testing	Must be set before using `test_garbagecollect_now()`.
-		Also, when set certain error messages won't be shown for 2
-		seconds. (e.g. "'dictionary' option is empty")
 
 				*v:this_session* *this_session-variable*
 v:this_session	Full filename of the last loaded or saved session file.  See
@@ -2781,7 +2779,7 @@ changenr()						*changenr()*
 		redo it is the number of the redone change.  After undo it is
 		one less than the number of the undone change.
 
-chanclose({id}[, {stream}])				{Nvim} *chanclose()*
+chanclose({id}[, {stream}])				*chanclose()*
 		Close a channel or a specific stream associated with it.
 		For a job, {stream} can be one of "stdin", "stdout",
 		"stderr" or "rpc" (closes stdin/stdout for a job started
@@ -2791,7 +2789,7 @@ chanclose({id}[, {stream}])				{Nvim} *chanclose()*
 		For a socket, there is only one stream, and {stream} should be
 		ommited.
 
-chansend({id}, {data})					{Nvim} *chansend()*
+chansend({id}, {data})					*chansend()*
 		Send data to channel {id}. For a job, it writes it to the
 		stdin of the process. For the stdio channel |channel-stdio|,
 		it writes to Nvim's stdout.  Returns the number of bytes
@@ -3822,8 +3820,7 @@ garbagecollect([{atexit}])				*garbagecollect()*
 
 		The garbage collection is not done immediately but only when
 		it's safe to perform.  This is when waiting for the user to
-		type a character.  To force garbage collection immediately use
-		|test_garbagecollect_now()|.
+		type a character.
 
 get({list}, {idx} [, {default}])			*get()*
 		Get item {idx} from |List| {list}.  When this item is not
@@ -5728,7 +5725,7 @@ mkdir({name} [, {path} [, {prot}]])
 		the new directory.  The default is 0755 (rwxr-xr-x: r/w for
 		the user readable for others).	Use 0700 to make it unreadable
 		for others.
-									{Nvim}
+
 		{prot} is applied for all parts of {name}.  Thus if you create
 		/tmp/foo/bar then /tmp/foo will be created with 0700. Example: >
 			:call mkdir($HOME . "/tmp/foo/bar", "p", 0700)
@@ -5771,7 +5768,7 @@ mode([expr])	Return a string that indicates the current mode.
 		"c" or "n".
 		Also see |visualmode()|.
 
-msgpackdump({list})				   {Nvim} *msgpackdump()*
+msgpackdump({list})					*msgpackdump()*
 		Convert a list of VimL objects to msgpack. Returned value is
 		|readfile()|-style list. Example: >
 			call writefile(msgpackdump([{}]), 'fname.mpack', 'b')
@@ -5786,7 +5783,7 @@ msgpackdump({list})				   {Nvim} *msgpackdump()*
 		4. Other strings are always dumped as BIN strings.
 		5. Points 3. and 4. do not apply to |msgpack-special-dict|s.
 
-msgpackparse({list})				   {Nvim} *msgpackparse()*
+msgpackparse({list})					*msgpackparse()*
 		Convert a |readfile()|-style list to a list of VimL objects.
 		Example: >
 			let fname = expand('~/.config/nvim/shada/main.shada')
@@ -6404,25 +6401,25 @@ round({expr})							*round()*
 			echo round(-4.5)
 <			-5.0
 
-rpcnotify({channel}, {event}[, {args}...])		  {Nvim} *rpcnotify()*
+rpcnotify({channel}, {event}[, {args}...])			*rpcnotify()*
 		Sends {event} to {channel} via |RPC| and returns immediately.
 		If {channel} is 0, the event is broadcast to all channels.
 		Example: >
 			:au VimLeave call rpcnotify(0, "leaving")
 
-rpcrequest({channel}, {method}[, {args}...])		 {Nvim} *rpcrequest()*
+rpcrequest({channel}, {method}[, {args}...])			*rpcrequest()*
 		Sends a request to {channel} to invoke {method} via
 		|RPC| and blocks until a response is received.
 		Example: >
 			:let result = rpcrequest(rpc_chan, "func", 1, 2, 3)
 
-rpcstart({prog}[, {argv}])				   {Nvim} *rpcstart()*
+rpcstart({prog}[, {argv}])					*rpcstart()*
 		Deprecated. Replace  >
 			:let id = rpcstart('prog', ['arg1', 'arg2'])
 <		with >
 			:let id = jobstart(['prog', 'arg1', 'arg2'], {'rpc': v:true})
 
-rpcstop({channel})					    {Nvim} *rpcstop()*
+rpcstop({channel})						*rpcstop()*
 		Deprecated. Instead use |jobstop()| to stop any job, and
 		chanclose(id, "rpc") to close RPC communication without
 		stopping the job. Use chanclose(id) to close any socket.
@@ -7889,7 +7886,7 @@ tempname()					*tempname()* *temp-file-name*
 		For MS-Windows forward slashes are used when the 'shellslash'
 		option is set or when 'shellcmdflag' starts with '-'.
 
-termopen({cmd}[, {opts}])			{Nvim} *termopen()*
+termopen({cmd}[, {opts}])			*termopen()*
 		Spawns {cmd} in a new pseudo-terminal session connected
 		to the current buffer.  {cmd} is the same as the one passed to
 		|jobstart()|.  This function fails if the current buffer is
@@ -7904,7 +7901,7 @@ termopen({cmd}[, {opts}])			{Nvim} *termopen()*
 		See |terminal| for more information.
 
 test_garbagecollect_now()			 *test_garbagecollect_now()*
-		Like garbagecollect(), but executed right away.  This must
+		Like |garbagecollect()|, but executed right away.  This must
 		only be called directly to avoid any structure to exist
 		internally, and |v:testing| must have been set before calling
 		any function.
diff --git a/runtime/doc/if_pyth.txt b/runtime/doc/if_pyth.txt
index 81a7816c93..2da2e5147b 100644
--- a/runtime/doc/if_pyth.txt
+++ b/runtime/doc/if_pyth.txt
@@ -6,7 +6,7 @@
 
 The Python Interface to Vim				*if_pyth* *python* *Python*
 
-See |provider-python| for more information. {Nvim}
+See |provider-python| for more information.
 
                                       Type |gO| to see the table of contents.
 
@@ -722,26 +722,5 @@ You can test what Python version is available with: >
 	  echo 'there is Python 3.x'
 	endif
 
-Note however, that if Python 2 and 3 are both available, but not loaded,
-these has() calls will try to load them.
-
-To avoid loading the dynamic library, only check if Vim was compiled with
-python support: >
-	if has('python_compiled')
-	  echo 'compiled with Python 2.x support'
-	  if has('python_dynamic')
-	    echo 'Python 2.x dynamically loaded'
-	  endif
-	endif
-  	if has('python3_compiled')
-	  echo 'compiled with Python 3.x support'
-	  if has('python3_dynamic')
-	    echo 'Python 3.x dynamically loaded'
-	  endif
-	endif
-
-This also tells you whether Python is dynamically loaded, which will fail if
-the runtime library cannot be found.
-
 ==============================================================================
  vim:tw=78:ts=8:noet:ft=help:norl:
diff --git a/runtime/doc/insert.txt b/runtime/doc/insert.txt
index 81eeae80ed..f22f90548b 100644
--- a/runtime/doc/insert.txt
+++ b/runtime/doc/insert.txt
@@ -1429,7 +1429,7 @@ automatically switch to HTML/CSS/JavaScript completion. Note: contrary to
 original HTML files completion of tags (and only tags) isn't context aware.
 
 
-RUBY						 *ft-ruby-omni* {Nvim}
+RUBY						 *ft-ruby-omni*
 
 NOTE: |compl-omni| for Ruby code requires |provider-ruby| to be installed.
 
diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index 9aaae6a527..534b2025cd 100644
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -459,7 +459,7 @@ For example, to use a modeline only for Vim 7.0:
 To use a modeline for Vim after version 7.2:
 	/* vim>702: set cole=2: */ ~
 There can be no blanks between "vim" and the ":".
-The modeline is ignored if {vers} does not fit in an integer. {Nvim}
+The modeline is ignored if {vers} does not fit in an integer.
 
 
 The number of lines that are checked can be set with the 'modelines' option.
@@ -908,13 +908,13 @@ A jump table for the options with a short description can be found at |Q_op|.
 	the newly created file).  Also see 'backupcopy' and |crontab|.
 
 						*'balloondelay'* *'bdlay'*
-'balloondelay' 'bdlay'	Removed. {Nvim}
+'balloondelay' 'bdlay'	Removed.
 
 			*'ballooneval'* *'beval'* *'noballooneval'* *'nobeval'*
-'ballooneval' 'beval'	Removed. {Nvim}
+'ballooneval' 'beval'	Removed.
 
 						*'balloonexpr'* *'bexpr'*
-'balloonexpr' 'bexpr'	Removed. {Nvim}
+'balloonexpr' 'bexpr'	Removed.
 
 						*'belloff'* *'bo'*
 'belloff' 'bo'		string	(default "all")
@@ -3475,7 +3475,7 @@ A jump table for the options with a short description can be found at |Q_op|.
 	help.  (Note that previously setting the global option to the empty
 	value did this, which is now deprecated.)
 	When the first character is ":", the command is invoked as a Vim
-	command prefixed with [count]. {Nvim}
+	command prefixed with [count].
 	When "man" or "man -s" is used, Vim will automatically translate
 	a [count] for the "K" command to a section number.
 	See |option-backslash| about including spaces and backslashes.
@@ -3795,7 +3795,7 @@ A jump table for the options with a short description can be found at |Q_op|.
 	set a time.  This is to be compatible with Nvi.
 
 						*'maxcombine'* *'mco'*
-'maxcombine' 'mco'	Removed. |vim-differences| {Nvim}
+'maxcombine' 'mco'	Removed. |vim-differences|
 	Nvim always displays up to 6 combining characters.  You can still edit
     text with more than 6 combining characters, you just can't see them.
     Use |g8| or |ga|.  See |mbyte-combining|.
@@ -6219,7 +6219,7 @@ A jump table for the options with a short description can be found at |Q_op|.
 	to be garbled (e.g., when it contains a CR or NL character).
 
 				     *'ttyfast'* *'tf'* *'nottyfast'* *'notf'*
-'ttyfast' 'tf'		Removed. |vim-differences| {Nvim}
+'ttyfast' 'tf'		Removed. |vim-differences|
 
 						*'undodir'* *'udir'* *E5003*
 'undodir' 'udir'	string	(default "$XDG_DATA_HOME/nvim/undo")
diff --git a/runtime/doc/starting.txt b/runtime/doc/starting.txt
index 82e73035d8..12794b6cc0 100644
--- a/runtime/doc/starting.txt
+++ b/runtime/doc/starting.txt
@@ -1025,7 +1025,7 @@ Use the "r" flag in 'shada' to specify for which files no marks should be
 remembered.
 
 MERGING							*shada-merging*
-									{Nvim}
+
 When writing ShaDa files with |:wshada| without bang or at regular exit 
 information in the existing ShaDa file is merged with information from current 
 Neovim instance.  For this purpose ShaDa files store timestamps associated 
@@ -1055,7 +1055,7 @@ with ShaDa entries.  Specifically the following is being done:
    Neovim instance which was last writing the file. |shada-%|
 
 COMPATIBILITY						*shada-compatibility*
-									{Nvim}
+
 ShaDa files are forward and backward compatible.  This means that
 
 1. Entries which have unknown type (i.e. that hold unidentified data) are 
diff --git a/runtime/doc/syntax.txt b/runtime/doc/syntax.txt
index 4c3c7d329a..684830b78d 100644
--- a/runtime/doc/syntax.txt
+++ b/runtime/doc/syntax.txt
@@ -4907,12 +4907,12 @@ DiffChange	diff mode: Changed line |diff.txt|
 DiffDelete	diff mode: Deleted line |diff.txt|
 							*hl-DiffText*
 DiffText	diff mode: Changed text within a changed line |diff.txt|
-						 {Nvim} *hl-EndOfBuffer*
+							*hl-EndOfBuffer*
 EndOfBuffer	filler lines (~) after the end of the buffer.
 		By default, this is highlighted like |hl-NonText|.
-						 {Nvim} *hl-TermCursor*
+							*hl-TermCursor*
 TermCursor	cursor in a focused terminal
-						 {Nvim} *hl-TermCursorNC*
+							*hl-TermCursorNC*
 TermCursorNC	cursor in an unfocused terminal
 							*hl-ErrorMsg*
 ErrorMsg	error messages on the command line
diff --git a/runtime/doc/various.txt b/runtime/doc/various.txt
index d78dd90f18..dbbafd1576 100644
--- a/runtime/doc/various.txt
+++ b/runtime/doc/various.txt
@@ -215,11 +215,12 @@ g8			Print the hex values of the bytes used in the
 			":normal" command without a range.
 
 						  *:sh* *:shell* *E371* *E360*
-:sh[ell]		Removed. |vim-differences| {Nvim}
+:sh[ell]		Removed. |vim-differences|
 
 						  *:terminal* *:te*
-:te[rminal][!] [{cmd}]	Execute {cmd} with 'shell' in a new |terminal-emulator|
-			buffer. Without {cmd}, start an interactive 'shell'.
+:te[rminal][!] [{cmd}]	Run {cmd} in a non-interactive 'shell' in a new
+			|terminal-emulator| buffer. Without {cmd}, start an
+			interactive 'shell'.
 
 			Type |i| to enter |Terminal-mode|, then keys are sent to
 			the job running in the terminal. Type <C-\><C-N> to
diff --git a/runtime/syntax/help.vim b/runtime/syntax/help.vim
index 972970f619..db5ad3728c 100644
--- a/runtime/syntax/help.vim
+++ b/runtime/syntax/help.vim
@@ -36,7 +36,6 @@ syn match helpNormal		"|||"
 syn match helpNormal		":|vim:|"	" for :help modeline
 syn match helpVim		"\<Vim version [0-9][0-9.a-z]*"
 syn match helpVim		"VIM REFERENCE.*"
-syn match helpVim		"\<Nvim\."
 syn match helpVim		"NVIM REFERENCE.*"
 syn match helpOption		"'[a-z]\{2,\}'"
 syn match helpOption		"'t_..'"
diff --git a/runtime/syntax/vim.vim b/runtime/syntax/vim.vim
index 5dc4f333e4..444b6d8d17 100644
--- a/runtime/syntax/vim.vim
+++ b/runtime/syntax/vim.vim
@@ -397,7 +397,7 @@ syn match	vimMenuBang	"!"	contained skipwhite nextgroup=@vimMenuList
 " Angle-Bracket Notation (tnx to Michael Geddes) {{{2
 " ======================
 syn case ignore
-syn match	vimNotation	"\%#=1\(\\\|<lt>\)\=<\([scamd]-\)\{0,4}x\=\(f\d\{1,2}\|[^ \t:]\|cr\|lf\|linefeed\|return\|k\=del\%[ete]\|bs\|backspace\|tab\|esc\|right\|left\|help\|undo\|insert\|ins\|mouse\|k\=home\|k\=end\|kplus\|kminus\|kdivide\|kmultiply\|kenter\|kpoint\|space\|k\=\(page\)\=\(\|down\|up\|k\d\>\)\)>" contains=vimBracket
+syn match	vimNotation	"\%#=1\(\\\|<lt>\)\=<\([scamd]-\)\{0,4}x\=\(f\d\{1,2}\|[^ \t:]\|cmd\|cr\|lf\|linefeed\|return\|k\=del\%[ete]\|bs\|backspace\|tab\|esc\|right\|left\|help\|undo\|insert\|ins\|mouse\|k\=home\|k\=end\|kplus\|kminus\|kdivide\|kmultiply\|kenter\|kpoint\|space\|k\=\(page\)\=\(\|down\|up\|k\d\>\)\)>" contains=vimBracket
 syn match	vimNotation	"\%#=1\(\\\|<lt>\)\=<\([scam2-4]-\)\{0,4}\(right\|left\|middle\)\(mouse\)\=\(drag\|release\)\=>"	contains=vimBracket
 syn match	vimNotation	"\%#=1\(\\\|<lt>\)\=<\(bslash\|plug\|sid\|space\|bar\|nop\|nul\|lt\)>"			contains=vimBracket
 syn match	vimNotation	'\(\\\|<lt>\)\=<C-R>[0-9a-z"%#:.\-=]'he=e-1				contains=vimBracket
diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c
index 4da61a30ef..ecfff1ea8f 100644
--- a/src/nvim/api/vim.c
+++ b/src/nvim/api/vim.c
@@ -905,17 +905,17 @@ void nvim_set_current_tabpage(Tabpage tabpage, Error *err)
   }
 }
 
-/// create a new namespace, or get one with an exisiting name
+/// Creates a new namespace, or gets an existing one
 ///
-/// Namespaces are currently used for buffer highlighting and virtual text, see
-/// |nvim_buf_add_highlight| and |nvim_buf_set_virtual_text|.
+/// Namespaces are used for buffer highlights and virtual text, see
+/// |nvim_buf_add_highlight()| and |nvim_buf_set_virtual_text()|.
 ///
-/// Namespaces can have a name of be anonymous. If `name` is a non-empty string,
-/// and a namespace already exists with that name,the existing namespace id is
-/// returned. If an empty string is used, a new anonymous namespace is returned.
+/// Namespaces can be named or anonymous. If `name` matches an existing
+/// namespace, the associated id is returned. If `name` is an empty string
+/// a new, anonymous namespace is created.
 ///
-/// @param name Name of the namespace or empty string
-/// @return the namespace id
+/// @param name Namespace name or empty string
+/// @return Namespace id
 Integer nvim_create_namespace(String name)
   FUNC_API_SINCE(5)
 {
@@ -931,7 +931,7 @@ Integer nvim_create_namespace(String name)
   return (Integer)id;
 }
 
-/// Get existing named namespaces
+/// Gets existing, non-anonymous namespaces
 ///
 /// @return dict that maps from names to namespace ids.
 Dictionary nvim_get_namespaces(void)
diff --git a/test/README.md b/test/README.md
index 1a5dc022f4..d3f421e8fc 100644
--- a/test/README.md
+++ b/test/README.md
@@ -205,7 +205,7 @@ Tests in `/test/unit` and `/test/functional` are divided into groups
 by the semantic component they are testing.
 
 - _Unit tests_
-  ([test/unit](https://github.com/neovim/neovim/tree/master/test/unit))  should
+  ([test/unit](https://github.com/neovim/neovim/tree/master/test/unit)) should
   match 1-to-1 with the structure of `src/nvim/`, because they are testing
   functions directly. E.g. unit-tests for `src/nvim/undo.c` should live in
   `test/unit/undo_spec.lua`.