doc

- CMake features

8 files changed, 68 insertions, 66 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..78d08ac420 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
@@ -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
@@ -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..44c7bcf76b 100644
--- a/runtime/doc/if_pyth.txt
+++ b/runtime/doc/if_pyth.txt
@@ -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/various.txt b/runtime/doc/various.txt
index d78dd90f18..8f566056a1 100644
--- a/runtime/doc/various.txt
+++ b/runtime/doc/various.txt
@@ -218,8 +218,9 @@ g8			Print the hex values of the bytes used in the
 :sh[ell]		Removed. |vim-differences| {Nvim}
 
 						  *: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/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`.