Merge #7555 'vim-patch.sh, doc updates'

CONTRIBUTING.md

@@ -14,7 +14,7 @@ low-risk/isolated tasks:
 Developer guidelines
 --------------------
 
-- Nvim developers should read `:help dev-help`.
+- Nvim developers should read `:help dev`.
 - External UI developers should read `:help dev-ui`.
 
 Reporting problems
@@ -24,7 +24,7 @@ Reporting problems
 - Search [existing issues][github-issues] (including closed!)
 - Update Neovim to the latest version to see if your problem persists.
 - Disable plugins incrementally, to narrow down the cause of the issue.
-- When reporting a crash, include a stacktrace.
+- When reporting a crash, [include a stacktrace](https://github.com/neovim/neovim/wiki/Development-tips#backtrace-linux).
 - [Bisect][git-bisect] to the cause of a regression, if you are able. This is _extremely_ helpful.
 - Check `$NVIM_LOG_FILE`, if it exists.
 - Include `cmake --system-information` for **build** issues.
@@ -92,7 +92,7 @@ and [AppVeyor].
 - CI builds are compiled with [`-Werror`][gcc-warnings], so compiler warnings
   will fail the build.
 - If any tests fail, the build will fail.
-  See [Building Neovim#running-tests][wiki-run-tests] to run tests locally.
+  See [test/README.md#running-tests][run-tests] to run tests locally.
   Passing locally doesn't guarantee passing the CI build, because of the
   different compilers and platforms tested against.
 - CI runs [ASan] and other analyzers.
@@ -168,7 +168,7 @@ as context, use the `-W` argument as well.
 [hygiene]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
 [style-guide]: http://neovim.io/develop/style-guide.xml
 [ASan]: http://clang.llvm.org/docs/AddressSanitizer.html
-[wiki-run-tests]: https://github.com/neovim/neovim/wiki/Building-Neovim#running-tests
+[run-tests]: https://github.com/neovim/neovim/blob/master/test/README.md#running-tests
 [wiki-faq]: https://github.com/neovim/neovim/wiki/FAQ
 [review-checklist]: https://github.com/neovim/neovim/wiki/Code-review-checklist
 [3174]: https://github.com/neovim/neovim/issues/3174

README.md

@@ -14,7 +14,7 @@
 [![PVS-studio Check](https://neovim.io/doc/reports/pvs/badge.svg)](https://neovim.io/doc/reports/pvs)
 
 [![Debian CI](https://badges.debian.net/badges/debian/testing/neovim/version.svg)](https://buildd.debian.org/neovim)
-[![Downloads](https://img.shields.io/github/downloads/neovim/neovim/total.svg?maxAge=2592000)](https://github.com/neovim/neovim/releases/)
+[![Downloads](https://img.shields.io/github/downloads/neovim/neovim/total.svg?maxAge=2592001)](https://github.com/neovim/neovim/releases/)
 
 Neovim is a project that seeks to aggressively refactor Vim in order to:
 

runtime/doc/api.txt

@@ -60,8 +60,7 @@ External programs ("clients") can use the metadata to discover the |rpc-api|.
 API contract                                                     *api-contract*
 
 The API is made of functions and events. Clients call functions like those
-described at |api-global|, and may "attach" in order to receive rich events,
+described at |api-global|, and may "attach" to receive rich |ui-events|.
-described at |rpc-remote-ui|.
 
 As Nvim develops, its API may change only according the following "contract":
 
@@ -446,7 +445,11 @@ nvim_get_keymap({mode})                                    *nvim_get_keymap()*
                     Array of maparg()-like dictionaries describing mappings
 
 nvim_get_api_info()                                      *nvim_get_api_info()*
-                TODO: Documentation
+                Returns a 2-tuple (Array), where item 0 is the current channel
+                id and item 1 is the |api-metadata| map (Dictionary).
+
+                Return:~
+                    2-tuple [{channel-id}, {api-metadata}]
 
                 Attributes:~
                     {async}
@@ -477,6 +480,84 @@ nvim_call_atomic({calls})                                 *nvim_call_atomic()*
                     error ocurred, the values from all preceding calls will
                     still be returned.
 
+                                                     *nvim_parse_expression()*
+nvim_parse_expression({expr}, {flags}, {highlight})
+                Parse a VimL expression
+
+                Attributes:~
+                    {async}
+
+                Parameters:~
+                    {expr}       Expression to parse. Is always treated as a
+                                 single line.
+                    {flags}      Flags:  - "m" if multiple expressions in a
+                                 row are allowed (only the first one will be
+                                 parsed), - "E" if EOC tokens are not allowed
+                                 (determines whether they will stop parsing
+                                 process or be recognized as an
+                                 operator/space, though also yielding an
+                                 error). - "l" when needing to start parsing
+                                 with lvalues for ":let" or ":for". Common
+                                 flag sets: - "m" to parse like for ":echo". -
+                                 "E" to parse like for "<C-r>=". - empty
+                                 string for ":call". - "lm" to parse for
+                                 ":let".
+                    {highlight}  If true, return value will also include
+                                 "highlight" key containing array of 4-tuples
+                                 (arrays) (Integer, Integer, Integer, String),
+                                 where first three numbers define the
+                                 highlighted region and represent line,
+                                 starting column and ending column (latter
+                                 exclusive: one should highlight region
+                                 [start_col, end_col)).
+
+                Return:~
+                    AST: top-level dictionary holds keys "error": Dictionary
+                    with error, present only if parser saw some error.
+                    Contains the following keys: "message": String, error
+                    message in printf format, translated. Must contain exactly
+                    one "%.*s". "arg": String, error message argument. "len":
+                    Amount of bytes successfully parsed. With flags equal to
+                    "" that should be equal to the length of expr string.
+                    @note: “Sucessfully parsed” here means “participated in
+                    AST creation”, not “till the first error”. "ast": AST,
+                    either nil or a dictionary with these keys: "type": node
+                    type, one of the value names from ExprASTNodeType
+                    stringified without "kExprNode" prefix. "start": a pair
+                    [line, column] describing where node is “started” where
+                    "line" is always 0 (will not be 0 if you will be using
+                    nvim_parse_viml() on e.g. ":let", but that is not present
+                    yet). Both elements are Integers. "len": “length” of the
+                    node. This and "start" are there for debugging purposes
+                    primary (debugging parser and providing debug
+                    information). "children": a list of nodes described in
+                    top/"ast". There always is zero, one or two children, key
+                    will not be present if node has no children. Maximum
+                    number of children may be found in node_maxchildren array.
+                    Local values (present only for certain nodes): "scope": a
+                    single Integer, specifies scope for "Option" and
+                    "PlainIdentifier" nodes. For "Option" it is one of
+                    ExprOptScope values, for "PlainIdentifier" it is one of
+                    ExprVarScope values. "ident": identifier (without scope,
+                    if any), present for "Option", "PlainIdentifier",
+                    "PlainKey" and "Environment" nodes. "name": Integer,
+                    register name (one character) or -1. Only present for
+                    "Register" nodes. "cmp_type": String, comparison type, one
+                    of the value names from ExprComparisonType, stringified
+                    without "kExprCmp" prefix. Only present for "Comparison"
+                    nodes. "ccs_strategy": String, case comparison strategy,
+                    one of the value names from ExprCaseCompareStrategy,
+                    stringified without "kCCStrategy" prefix. Only present for
+                    "Comparison" nodes. "augmentation": String, augmentation
+                    type for "Assignment" nodes. Is either an empty string,
+                    "Add", "Subtract" or "Concat" for "=", "+=", "-=" or ".="
+                    respectively. "invert": Boolean, true if result of
+                    comparison needs to be inverted. Only present for
+                    "Comparison" nodes. "ivalue": Integer, integer value for
+                    "Integer" nodes. "fvalue": Float, floating-point value for
+                    "Float" nodes. "svalue": String, value for
+                    "SingleQuotedString" and "DoubleQuotedString" nodes.
+
 nvim__id({obj})                                                   *nvim__id()*
                 Returns object given as argument
 
@@ -717,9 +798,10 @@ nvim_buf_add_highlight({buffer}, {src_id}, {hl_group}, {line},
                                  or -1 for ungrouped highlight
                     {hl_group}   Name of the highlight group to use
                     {line}       Line to highlight (zero-indexed)
-                    {col_start}  Start of range of columns to highlight
+                    {col_start}  Start of (byte-indexed) column range to
-                    {col_end}    End of range of columns to highlight, or -1
+                                 highlight
-                                 to highlight to end of line
+                    {col_end}    End of (byte-indexed) column range to
+                                 highlight, or -1 to highlight to end of line
 
                 Return:~
                     The src_id that was used
@@ -953,9 +1035,6 @@ nvim_tabpage_is_valid({tabpage})                     *nvim_tabpage_is_valid()*
 ==============================================================================
 UI Functions                                                          *api-ui*
 
-remote_ui_disconnect()                                *remote_ui_disconnect()*
-                TODO: Documentation
-
 nvim_ui_attach({width}, {height}, {options})                *nvim_ui_attach()*
                 TODO: Documentation
 

runtime/doc/autocmd.txt

@@ -259,13 +259,12 @@ Name			triggered by ~
 |BufNew|		just after creating a new buffer
 
 |SwapExists|		detected an existing swap file
-|TermOpen|		when a terminal buffer is starting
+|TermOpen|		when a terminal job starts
-|TermClose|		when a terminal buffer ends
+|TermClose|		when a terminal job ends
 
 	Options
 |FileType|		when the 'filetype' option has been set
 |Syntax|		when the 'syntax' option has been set
-|TermChanged|		after the value of 'term' has changed
 |OptionSet|		after setting any option
 
 	Startup and exit
@@ -933,26 +932,20 @@ TabEnter			Just after entering a tab page. |tab-page|
 TabLeave			Just before leaving a tab page. |tab-page|
 				A WinLeave event will have been triggered
 				first.
-						 {Nvim} *TabNew*
+							*TabNew*
 TabNew				When creating a new tab page. |tab-page|
 				After WinEnter and before TabEnter.
-						 {Nvim} *TabNewEntered*
+							*TabNewEntered*
 TabNewEntered			After entering a new tab page. |tab-page|
 				After BufEnter.
-						 {Nvim} *TabClosed*
+							*TabClosed*
 TabClosed			After closing a tab page. <afile> can be used
 				for the tab page number.
-							*TermChanged*
+							*TermClose*
-TermChanged			After the value of 'term' has changed.  Useful
+TermClose			When a |terminal| job ends.
-				for re-loading the syntax file to update the
+							*TermOpen*
-				colors, fonts and other terminal-dependent
+TermOpen			When a |terminal| job is starting.  Can be
-				settings.  Executed for all loaded buffers.
+				used to configure the terminal buffer.
-						 {Nvim} *TermClose*
-TermClose			When a terminal buffer ends.
-						 {Nvim} *TermOpen*
-TermOpen			When a terminal buffer is starting.  This can
-				be used to configure the terminal emulator by
-				setting buffer variables. |terminal|
 							*TermResponse*
 TermResponse			After the response to |t_RV| is received from
 				the terminal.  The value of |v:termresponse|

runtime/doc/syntax.txt

@@ -4709,17 +4709,7 @@ ctermbg={color-nr}				*highlight-ctermbg*
 	"cterm".  For example, on some systems "cterm=bold ctermfg=3" gives
 	another color, on others you just get color 3.
 
-	For an xterm this depends on your resources, and is a bit
+	The following names are recognized, with the color number used:
-	unpredictable.	See your xterm documentation for the defaults.	The
-	colors for a color-xterm can be changed from the .Xdefaults file.
-	Unfortunately this means that it's not possible to get the same colors
-	for each user.
-
-	The MSDOS standard colors are fixed (in a console window), so these
-	have been used for the names.  But the meaning of color names in X11
-	are fixed, so these color settings have been used, to make the
-	highlighting settings portable (complicated, isn't it?).  The
-	following names are recognized, with the color number used:
 
 							*cterm-colors*
 	    NR-16   NR-8    COLOR NAME ~

runtime/doc/ui.txt

@@ -9,7 +9,7 @@ Nvim UI protocol							  *ui*
                                       Type |gO| to see the table of contents.
 
 ==============================================================================
-Introduction							     *ui-intro*
+UI Events							    *ui-events*
 
 GUIs can be implemented as external processes communicating with Nvim over the
 RPC API. The UI model consists of a terminal-like grid with a single,

runtime/doc/various.txt

@@ -207,21 +207,18 @@ 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| buffer.
+:te[rminal][!] [{cmd}]	Execute {cmd} with 'shell' in a new |terminal-emulator|
-			Equivalent to: >
+			buffer. Without {cmd}, start an interactive 'shell'.
-			      :enew
-			      :call termopen('{cmd}')
-<
-			See |termopen()|.
 
-			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
+			leave Terminal-mode. |CTRL-\_CTRL-N|
 
-			Creating the terminal buffer fails when changes have been
+			Fails if changes have been made to the current buffer,
-			made to the current buffer, unless 'hidden' is set.
+			unless 'hidden' is set.
 
 			To enter |Terminal-mode| automatically: >
-			      autocmd BufEnter term://* startinsert
+			      autocmd TermOpen * startinsert
-			      autocmd BufLeave term://* stopinsert
 <
 							*:!cmd* *:!* *E34*
 :!{cmd}			Execute {cmd} with 'shell'. See also |:terminal|.

runtime/doc/vim_diff.txt

@@ -302,7 +302,8 @@ Highlight groups:
   |hl-ColorColumn|, |hl-CursorColumn| are lower priority than most other
   groups
 
-The variable name "count" is no fallback for |v:count| anymore.
+VimL (Vim script) compatibility:
+  `count` does not alias to |v:count|
 
 ==============================================================================
 5. Missing legacy features				 *nvim-features-missing*

scripts/gen_api_vimdoc.py

@@ -45,6 +45,8 @@ if sys.version_info[0] < 3:
 doc_filename = 'api.txt'
 # String used to find the start of the generated part of the doc.
 section_start_token = '*api-global*'
+# Required prefix for API function names.
+api_func_name_prefix = 'nvim_'
 
 # Section name overrides.
 section_name = {
@@ -260,11 +262,11 @@ def parse_parblock(parent, width=62):
 def parse_source_xml(filename):
     """Collects API functions.
 
-    This returns two strings:
+    Returns two strings:
-      1. The API functions
+      1. API functions
-      2. The deprecated API functions
+      2. Deprecated API functions
 
-    The caller decides what to do with the deprecated documentation.
+    Caller decides what to do with the deprecated documentation.
     """
     global xrefs
     xrefs = set()
@@ -294,9 +296,8 @@ def parse_source_xml(filename):
         annotations = get_text(get_child(member, 'argsstring'))
         if annotations and ')' in annotations:
             annotations = annotations.rsplit(')', 1)[-1].strip()
-        # XXX: (doxygen 1.8.11) 'argsstring' only includes FUNC_ATTR_*
+        # XXX: (doxygen 1.8.11) 'argsstring' only includes attributes of
-        # attributes if the function signature is non-void.
+        # non-void functions.  Special-case void functions here.
-        # Force attributes here for such functions.
         if name == 'nvim_get_mode' and len(annotations) == 0:
             annotations += 'FUNC_API_ASYNC'
         annotations = filter(None, map(lambda x: annotation_map.get(x),
@@ -379,7 +380,7 @@ def parse_source_xml(filename):
 
         if 'Deprecated' in xrefs:
             deprecated_functions.append(func_doc)
-        else:
+        elif name.startswith(api_func_name_prefix):
             functions.append(func_doc)
 
         xrefs.clear()

scripts/vim-patch.sh

@@ -21,7 +21,8 @@ usage() {
   echo
   echo "Options:"
   echo "    -h                 Show this message and exit."
-  echo "    -l                 Show list of Vim patches missing from Neovim."
+  echo "    -l                 Show list of missing Vim patches."
+  echo "    -L                 Print missing Vim patches in machine-readable form."
   echo "    -p {vim-revision}  Download and generate the specified Vim patch."
   echo "                       vim-revision can be a version number '8.0.xxx'"
   echo "                       or a valid Git ref (hash, tag, etc.)."
@@ -147,6 +148,10 @@ preprocess_patch() {
   local na_src_testdir='Make_amiga.mak\|Make_dos.mak\|Make_ming.mak\|Make_vms.mms'
   2>/dev/null $nvim --cmd 'set dir=/tmp' +'g@^diff --git a/src/testdir/\<\%('${na_src_testdir}'\)\>@norm! d/\v(^diff)|%$
' +w +q "$file"
 
+  # Remove version.c #7555
+  local na_po='version.c'
+  2>/dev/null $nvim --cmd 'set dir=/tmp' +'g@^diff --git a/src/\<\%('${na_po}'\)\>@norm! d/\v(^diff)|%$
' +w +q "$file"
+
   # Remove some *.po files. #5622
   local na_po='sjiscorr.c\|ja.sjis.po\|ko.po\|pl.cp1250.po\|pl.po\|ru.cp1251.po\|uk.cp1251.po\|zh_CN.cp936.po\|zh_CN.po\|zh_TW.po'
   2>/dev/null $nvim --cmd 'set dir=/tmp' +'g@^diff --git a/src/po/\<\%('${na_po}'\)\>@norm! d/\v(^diff)|%$
' +w +q "$file"
@@ -318,15 +323,17 @@ submit_pr() {
   done
 }
 
+# Prints a newline-delimited list of Vim commits, for use by scripts.
 list_vim_patches() {
-  get_vim_sources
-
-  printf "\nVim patches missing from Neovim:\n"
-
   # Get missing Vim commits
   local vim_commits
   vim_commits="$(cd "${VIM_SOURCE_DIR}" && git log --reverse --format='%H' v8.0.0000..HEAD)"
 
+  # Find all "vim-patch:xxx" tokens in the Nvim git log.
+  local tokens
+  tokens="$(cd "${NVIM_SOURCE_DIR}" && git log -E --grep='vim-patch:[^ ]+' | grep 'vim-patch')"
+  tokens="$(for i in $tokens ; do echo "$i" | grep -E 'vim-patch:[^ ]{7}' | sed 's/.*\(vim-patch:[.0-9a-z]\+\).*/\1/' ; done)"
+
   local vim_commit
   for vim_commit in ${vim_commits}; do
     local is_missing
@@ -334,23 +341,31 @@ list_vim_patches() {
     # This fails for untagged commits (e.g., runtime file updates) so mask the return status
     vim_tag="$(cd "${VIM_SOURCE_DIR}" && git describe --tags --exact-match "${vim_commit}" 2>/dev/null)" || true
     if [[ -n "${vim_tag}" ]]; then
-      local patch_number="${vim_tag:5}" # Remove prefix like "v7.4."
+      # Vim version number (not commit hash).
-      patch_number="$(echo ${patch_number} | sed 's/^0*//g')" # Remove prefix "0"
+      local patch_number="${vim_tag:1}" # "v7.4.0001" => "7.4.0001"
-      # Tagged Vim patch, check version.c:
+      is_missing="$(echo "$tokens" | >/dev/null 2>&1 grep "vim\-patch:${patch_number}" && echo false || echo true)"
-      is_missing="$(sed -n '/static const int included_patches/,/}/p' "${NVIM_SOURCE_DIR}/src/nvim/version.c" |
-        grep -x -e "[[:space:]]*//[[:space:]]${patch_number} NA.*" -e "[[:space:]]*${patch_number}," >/dev/null && echo "false" || echo "true")"
       vim_commit="${vim_tag#v}"
-      if (cd "${VIM_SOURCE_DIR}" && git --no-pager  show --color=never --name-only "v${vim_commit}" 2>/dev/null) | grep -q ^runtime; then
-        vim_commit="${vim_commit} (+runtime)"
-      fi
     else
-      # Untagged Vim patch (e.g. runtime updates), check the Neovim git log:
+      # Untagged Vim patch (e.g. runtime updates).
-      is_missing="$(cd "${NVIM_SOURCE_DIR}" &&
+      is_missing="$(echo "$tokens" | >/dev/null 2>&1 grep "vim\-patch:${vim_commit:0:7}" && echo false || echo true)"
-        git log -1 --no-merges --grep="vim\-patch:${vim_commit:0:7}" --pretty=format:false)"
     fi
 
-    if [[ ${is_missing} != "false" ]]; then
+    if ! [ "$is_missing" = "false" ]; then
-      echo "  • ${vim_commit}"
+      echo "${vim_commit}"
+    fi
+  done
+}
+
+# Prints a human-formatted list of Vim commits, with instructional messages.
+show_vim_patches() {
+  get_vim_sources
+  printf "\nVim patches missing from Neovim:\n"
+
+  list_vim_patches | while read vim_commit; do
+    if (cd "${VIM_SOURCE_DIR}" && git --no-pager  show --color=never --name-only "v${vim_commit}" 2>/dev/null) | grep -q ^runtime; then
+      printf "  • ${vim_commit} (+runtime)\n"
+    else
+      printf "  • ${vim_commit}\n"
     fi
   done
 
@@ -461,13 +476,17 @@ review_pr() {
   clean_files
 }
 
-while getopts "hlp:P:g:r:s" opt; do
+while getopts "hlLp:P:g:r:s" opt; do
   case ${opt} in
     h)
       usage
       exit 0
       ;;
     l)
+      show_vim_patches
+      exit 0
+      ;;
+    L)
       list_vim_patches
       exit 0
       ;;

src/nvim/api/buffer.c

@@ -763,8 +763,8 @@ ArrayOf(Integer, 2) nvim_buf_get_mark(Buffer buffer, String name, Error *err)
 ///                   or -1 for ungrouped highlight
 /// @param hl_group   Name of the highlight group to use
 /// @param line       Line to highlight (zero-indexed)
-/// @param col_start  Start of range of columns to highlight
+/// @param col_start  Start of (byte-indexed) column range to highlight
-/// @param col_end    End of range of columns to highlight,
+/// @param col_end    End of (byte-indexed) column range to highlight,
 ///                   or -1 to highlight to end of line
 /// @param[out] err   Error details, if any
 /// @return The src_id that was used

src/nvim/api/vim.c

@@ -789,6 +789,10 @@ ArrayOf(Dictionary) nvim_get_keymap(String mode)
   return keymap_array(mode, NULL);
 }
 
+/// Returns a 2-tuple (Array), where item 0 is the current channel id and item
+/// 1 is the |api-metadata| map (Dictionary).
+///
+/// @returns 2-tuple [{channel-id}, {api-metadata}]
 Array nvim_get_api_info(uint64_t channel_id)
   FUNC_API_SINCE(1) FUNC_API_ASYNC FUNC_API_REMOTE_ONLY
 {
@@ -896,7 +900,9 @@ typedef struct {
   Object *ret_node_p;
 } ExprASTConvStackItem;
 
+///@cond DOXYGEN_NOT_A_FUNCTION
 typedef kvec_withinit_t(ExprASTConvStackItem, 16) ExprASTConvStack;
+///@endcond
 
 /// Parse a VimL expression
 ///

src/nvim/tui/tui.c

@@ -1529,7 +1529,7 @@ static void patch_terminfo_bugs(TUIData *data, const char *term,
         || iterm || iterm_pretending_xterm
         || teraterm    // per TeraTerm "Supported Control Functions" doco
         // Some linux-type terminals (such as console-terminal-emulator
-        // from the nosh toolset) implement implement the xterm extension.
+        // from the nosh toolset) implement the xterm extension.
         || (linuxvt && (xterm_version || (vte_version > 0) || colorterm)))) {
       data->unibi_ext.set_cursor_style =
         (int)unibi_add_ext_str(ut, "Ss", "\x1b[%p1%d q");

src/nvim/version.c

@@ -1012,7 +1012,7 @@ static const int included_patches[] = {
   247,
   // 246 NA
   245,
-  // 244,
+  // 244 NA
   243,
   242,
   // 241 NA
@@ -1041,7 +1041,7 @@ static const int included_patches[] = {
   218,
   // 217 NA
   // 216,
-  // 215,
+  // 215 NA
   // 214,
   // 213 NA
   // 212,

test/README.md

@@ -168,16 +168,13 @@ minutes](http://learnxinyminutes.com/docs/lua/).
   Do not silently skip the test with `if-else`. If a functional test depends on
   some external factor (e.g. the existence of `md5sum` on `$PATH`), *and* you
   can't mock or fake the dependency, then skip the test via `pending()` if the
-  external factor is missing. This ensures that the *total* test-count (success
+  external factor is missing. This ensures that the *total* test-count
-  + fail + error + pending) is the same in all environments.
+  (success + fail + error + pending) is the same in all environments.
     - *Note:* `pending()` is ignored if it is missing an argument _unless_ it is
-      [contained in an `it()`
+      [contained in an `it()` block](https://github.com/neovim/neovim/blob/d21690a66e7eb5ebef18046c7a79ef898966d786/test/functional/ex_cmds/grep_spec.lua#L11).
-      block](https://github.com/neovim/neovim/blob/d21690a66e7eb5ebef18046c7a79ef898966d786/test/functional/ex_cmds/grep_spec.lua#L11).
+      Provide empty function argument if the `pending()` call is outside of `it()`
-      Provide empty function argument if the `pending()` call is outside of
-      `it()`
       ([example](https://github.com/neovim/neovim/commit/5c1dc0fbe7388528875aff9d7b5055ad718014de#diff-bf80b24c724b0004e8418102f68b0679R18)).
-- Use `make testlint` for using the shipped luacheck program ([supported by
+- Use `make testlint` for using the shipped luacheck program ([supported by syntastic](https://github.com/scrooloose/syntastic/blob/d6b96c079be137c83009827b543a83aa113cc011/doc/syntastic-checkers.txt#L3546))
-  syntastic](https://github.com/scrooloose/syntastic/blob/d6b96c079be137c83009827b543a83aa113cc011/doc/syntastic-checkers.txt#L3546))
   to lint all tests.
 
 ### Where tests go