doc [ci skip] #10383

- test/README.md: document luassert `TableFormatLevel`
- CONTRIBUTING.md: absorb parts of the old "Development tips" wiki page

CONTRIBUTING.md

@@ -1,4 +1,5 @@
-# Contributing to Neovim
+Contributing to Neovim
+======================
 
 Getting started
 ---------------
@@ -11,6 +12,18 @@ low-risk/isolated tasks:
 - Fix bugs found by [Clang](#clang-scan-build), [PVS](#pvs-studio) or
   [Coverity](#coverity).
 
+Reporting problems
+------------------
+
+- [Check the FAQ][wiki-faq].
+- [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](https://github.com/neovim/neovim/wiki/FAQ#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-related issues.
+
 Developer guidelines
 --------------------
 
@@ -24,18 +37,6 @@ Developer guidelines
   make  # Nvim build system uses ninja automatically, if available.
   ```
 
-Reporting problems
-------------------
-
-- [Check the FAQ][wiki-faq].
-- [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](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-related issues.
-
 Pull requests (PRs)
 ---------------------
 
@@ -64,20 +65,10 @@ Pull requests (PRs)
 Pull requests have three stages: `[WIP]` (Work In Progress), `[RFC]` (Request
 For Comment) and `[RDY]` (Ready).
 
-- Untagged PRs are assumed to be `[RFC]`, i.e. you are requesting a review.
+- `[RFC]` is assumed by default, i.e. you are requesting a review.
-- Prepend `[WIP]` to the PR title if you are _not_ requesting feedback and the
+- Add `[WIP]` to the PR title if you are _not_ requesting feedback and the work
-  work is still in flux.
+  is still in flux.
-- Prepend `[RDY]` to the PR title if you are _done_ with the PR and are only
+- Add `[RDY]` if you are _done_ and only waiting on merge.
-  waiting on it to be merged.
-
-For example, a typical workflow is:
-
-1. You open a `[WIP]` PR where the work is _not_ ready for feedback, you just want to
-   let others know what you are doing.
-2. Once the PR is ready for review, you replace `[WIP]` in the title with `[RFC]`.
-   You may add fix up commits to address issues that come up during review.
-3. Once the PR is ready for merging, you rebase/squash your work appropriately and
-   then replace `[RFC]` in the title with `[RDY]`.
 
 ### Commit messages
 
@@ -106,19 +97,18 @@ and [AppVeyor].
 - CI runs [ASan] and other analyzers.
     - To run valgrind locally: `VALGRIND=1 make test`
     - To run Clang ASan/UBSan locally: `CC=clang make CMAKE_FLAGS="-DCLANG_ASAN_UBSAN=ON"`
-- The `lint` build ([#3174][3174]) checks modified lines _and their immediate
+- The [lint](#lint) build checks modified lines _and their immediate
-  neighbors_. This is to encourage incrementally updating the legacy style to
+  neighbors_, to encourage incrementally updating the legacy style to meet our
-  meet our style guidelines.
+  [style](#style). (See [#3174][3174] for background.)
 - [How to investigate QuickBuild failures](https://github.com/neovim/neovim/pull/4718#issuecomment-217631350)
-
+    - QuickBuild uses this invocation:
-QuickBuild uses this invocation:
+      ```
-
+      mkdir -p build/${params.get("buildType")} \
-    mkdir -p build/${params.get("buildType")} \
+      && cd build/${params.get("buildType")} \
-    && cd build/${params.get("buildType")} \
+      && cmake -G "Unix Makefiles" -DBUSTED_OUTPUT_TYPE=TAP -DCMAKE_BUILD_TYPE=${params.get("buildType")}
-    && cmake -G "Unix Makefiles" -DBUSTED_OUTPUT_TYPE=TAP -DCMAKE_BUILD_TYPE=${params.get("buildType")}
+      -DTRAVIS_CI_BUILD=ON ../.. && ${node.getAttribute("make", "make")}
-    -DTRAVIS_CI_BUILD=ON ../.. && ${node.getAttribute("make", "make")}
+      VERBOSE=1 nvim unittest-prereqs functionaltest-prereqs
-    VERBOSE=1 nvim unittest-prereqs functionaltest-prereqs
+      ```
-
 
 ### Clang scan-build
 
@@ -165,6 +155,41 @@ master build. To view the defects, just request access; you will be approved.
   git log --oneline --no-merges --grep coverity
   ```
 
+
+Coding
+------
+
+### Lint
+
+You can run the linter locally by:
+
+    make lint
+
+The lint step downloads the [master error list] and excludes them, so only lint
+errors related to the local changes are reported.
+
+You can lint a single file (but this will _not_ exclude legacy errors):
+
+    ./src/clint.py src/nvim/ops.c
+
+### Style
+
+The repo includes a `.clang-format` config file which (mostly) matches the
+[style-guide].  You can use `clang-format` to format code with the `gq`
+operator in Nvim:
+
+    if !empty(findfile('.clang-format', ';'))
+      setlocal formatprg=clang-format\ -style=file
+    endif
+
+### Navigate
+
+- Use **[universal-ctags](https://github.com/universal-ctags/ctags).**
+  ("Exuberant ctags", the typical `ctags` binary provided by your distro, is
+  unmaintained and won't recognize many function signatures in Neovim source.)
+- Explore the source code [on the web](https://sourcegraph.com/github.com/neovim/neovim).
+
+
 Reviewing
 ---------
 
@@ -203,3 +228,4 @@ as context, use the `-W` argument as well.
 [Merge a Vim patch]: https://github.com/neovim/neovim/wiki/Merging-patches-from-upstream-Vim
 [Clang report]: https://neovim.io/doc/reports/clang/
 [complexity:low]: https://github.com/neovim/neovim/issues?q=is%3Aopen+is%3Aissue+label%3Acomplexity%3Alow
+[master error list]: https://raw.githubusercontent.com/neovim/doc/gh-pages/reports/clint/errors.json

runtime/autoload/python3complete.vim

@@ -44,7 +44,7 @@
 "
 
 if !has('python3')
-    echo "Error: Required vim compiled with +python3"
+    echo 'Error: Requires python3 + pynvim.  :help provider-python'
     finish
 endif
 

runtime/autoload/pythoncomplete.vim

@@ -42,7 +42,7 @@
 "
 
 if !has('python')
-    echo "Error: Required vim compiled with +python"
+    echo 'Error: Requires python + pynvim.  :help provider-python'
     finish
 endif
 

runtime/doc/eval.txt

@@ -5351,10 +5351,11 @@ jobwait({ids}[, {timeout}])				*jobwait()*
 		Wait for a set of jobs to complete.
 
 		{ids} is a list of |job-id|s to wait for.
-		{timeout} is the maximum number of milliseconds to wait.
+		{timeout} is the maximum waiting time in milliseconds, -1
+		means forever.
 
-		Use zero {timeout} to check the status of a job: >
+		Timeout of 0 can be used to check the status of a job: >
-			let exited = jobwait([{job-id}], 0)[0] >= 0
+			let running = jobwait([{job-id}], 0)[0] == -1
 <
 		During jobwait() callbacks for jobs not in the {ids} list may
 		be invoked. The screen will not redraw unless |:redraw| is
@@ -8572,13 +8573,10 @@ timer_start({time}, {callback} [, {options}])
 		waiting for input.
 
 		{options} is a dictionary.  Supported entries:
-		   "repeat"	Number of times to repeat calling the
+		   "repeat"	Number of times to repeat the callback.
-				callback.  -1 means forever.  When not present
+				-1 means forever.  Default is 1.
-				the callback will be called once.
 				If the timer causes an error three times in a
-				row the repeat is cancelled.  This avoids that
+				row the repeat is cancelled.
-				Vim becomes unusable because of all the error
-				messages.
 
 		Example: >
 			func MyHandler(timer)
@@ -8586,8 +8584,7 @@ timer_start({time}, {callback} [, {options}])
 			endfunc
 			let timer = timer_start(500, 'MyHandler',
 				\ {'repeat': 3})
-<		This will invoke MyHandler() three times at 500 msec
+<		This invokes MyHandler() three times at 500 msec intervals.
-		intervals.
 
 timer_stop({timer})					*timer_stop()*
 		Stop a timer.  The timer callback will no longer be invoked.

runtime/doc/nvim_terminal_emulator.txt

@@ -129,7 +129,7 @@ Example: >
   input to the terminal.
 
 Use |jobwait()| to check if the terminal job has finished: >
-    let exited = jobwait([&channel], 0)[0] >= 0
+    let running = jobwait([&channel], 0)[0] == -1
 
 ==============================================================================
 :Termdebug plugin				*terminal-debug*

runtime/doc/options.txt

@@ -3210,7 +3210,7 @@ A jump table for the options with a short description can be found at |Q_op|.
 	so far, matches.  The matched string is highlighted.  If the pattern
 	is invalid or not found, nothing is shown.  The screen will be updated
 	often, this is only useful on fast terminals.
-<	Note that the match will be shown, but the cursor will return to its
+	Note that the match will be shown, but the cursor will return to its
 	original position when no match is found and when pressing <Esc>.  You
 	still need to finish the search command with <Enter> to move the
 	cursor to the match.

runtime/doc/provider.txt

@@ -57,14 +57,14 @@ If you run into problems, uninstall _both_ then install "pynvim" again: >
 
 PYTHON PROVIDER CONFIGURATION ~
 						*g:python_host_prog*
-Path to Python 2 interpreter. Setting this makes startup faster. Also useful
+Command to start Python 2 (executable, not directory). Setting this makes
-for working with virtualenvs.  >
+startup faster. Useful for working with virtualenvs.  >
-    let g:python_host_prog  = '/path/to/python'	  " Python 2
+    let g:python_host_prog  = '/path/to/python'
 <
 						*g:python3_host_prog*
-Path to Python 3 interpreter. Setting this makes startup faster. Also useful
+Command to start Python 3 (executable, not directory). Setting this makes
-for working with virtualenvs.  >
+startup faster. Useful for working with virtualenvs.  >
-    let g:python3_host_prog = '/path/to/python3'  " Python 3
+    let g:python3_host_prog = '/path/to/python3'
 <
 						*g:loaded_python_provider*
 To disable Python 2 support: >

src/clint.py

@@ -7,15 +7,14 @@
 # modification, are permitted provided that the following conditions are
 # met:
 #
-#    * Redistributions of source code must retain the above copyright
+#    * Redistributions of source code must retain the above copyright notice,
-# notice, this list of conditions and the following disclaimer.
+#      this list of conditions and the following disclaimer.
-#    * Redistributions in binary form must reproduce the above
+#    * Redistributions in binary form must reproduce the above copyright
-# copyright notice, this list of conditions and the following disclaimer
+#      notice, this list of conditions and the following disclaimer in the
-# in the documentation and/or other materials provided with the
+#      documentation and/or other materials provided with the distribution.
-# distribution.
+#    * Neither the name of Google Inc. nor the names of its contributors may be
-#    * Neither the name of Google Inc. nor the names of its
+#      used to endorse or promote products derived from this software without
-# contributors may be used to endorse or promote products derived from
+#      specific prior written permission.
-# this software without specific prior written permission.
 #
 # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT

src/nvim/eval.c

@@ -12076,6 +12076,14 @@ static void f_jobresize(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   rettv->vval.v_number = 1;
 }
 
+/// Builds a process argument vector from a VimL object (typval_T).
+///
+/// @param[in]  cmd_tv      VimL object
+/// @param[out] cmd         Returns the command or executable name.
+/// @param[out] executable  Returns `false` if argv[0] is not executable.
+///
+/// @returns Result of `shell_build_argv()` if `cmd_tv` is a String.
+///          Else, string values of `cmd_tv` copied to a (char **) list.
 static char **tv_to_argv(typval_T *cmd_tv, const char **cmd, bool *executable)
 {
   if (cmd_tv->v_type == VAR_STRING) {

test/README.md

@@ -26,7 +26,7 @@ available in this version` errors.
 - [Running tests](#running-tests)
 - [Writing tests](#writing-tests)
 - [Lint](#lint)
-- [Environment variables](#environment-variables)
+- [Configuration](#configuration)
 
 ---
 
@@ -246,95 +246,102 @@ Ignore the smallest applicable scope (e.g. inside a function, not at the top of
 the file).
 
 
-Environment variables
+Configuration
-=====================
+=============
+
+busted (luassert) by default does not print the full result of deeply-nested
+tables. But sometimes it's useful while debugging a test.
+
+    assert:set_parameter('TableFormatLevel', 1000000)
 
 Test behaviour is affected by environment variables. Currently supported 
 (Functional, Unit, Benchmarks) (when Defined; when set to _1_; when defined, 
 treated as Integer; when defined, treated as String; when defined, treated as 
 Number; !must be defined to function properly):
 
-`GDB` (F) (D): makes nvim instances to be run under `gdbserver`. It will be 
+- `GDB` (F) (D): makes nvim instances to be run under `gdbserver`. It will be
-accessible on `localhost:7777`: use `gdb build/bin/nvim`, type `target remote 
+  accessible on `localhost:7777`: use `gdb build/bin/nvim`, type `target remote
-:7777` inside.
+  :7777` inside.
 
-`GDBSERVER_PORT` (F) (I): overrides port used for `GDB`.
+- `GDBSERVER_PORT` (F) (I): overrides port used for `GDB`.
 
-`VALGRIND` (F) (D): makes nvim instances to be run under `valgrind`. Log files 
+- `VALGRIND` (F) (D): makes nvim instances to be run under `valgrind`. Log
-are named `valgrind-%p.log` in this case. Note that non-empty valgrind log may 
+  files are named `valgrind-%p.log` in this case. Note that non-empty valgrind
-fail tests. Valgrind arguments may be seen in `/test/functional/helpers.lua`. 
+  log may fail tests. Valgrind arguments may be seen in
-May be used in conjunction with `GDB`.
+  `/test/functional/helpers.lua`. May be used in conjunction with `GDB`.
 
-`VALGRIND_LOG` (F) (S): overrides valgrind log file name used for `VALGRIND`.
+- `VALGRIND_LOG` (F) (S): overrides valgrind log file name used for `VALGRIND`.
 
-`TEST_SKIP_FRAGILE` (F) (D): makes test suite skip some fragile tests.
+- `TEST_SKIP_FRAGILE` (F) (D): makes test suite skip some fragile tests.
 
-`NVIM_PROG`, `NVIM_PRG` (F) (S): override path to Neovim executable (default to 
+- `NVIM_PROG`, `NVIM_PRG` (F) (S): override path to Neovim executable (default
-`build/bin/nvim`).
+  to `build/bin/nvim`).
 
-`CC` (U) (S): specifies which C compiler to use to preprocess files. Currently 
+- `CC` (U) (S): specifies which C compiler to use to preprocess files.
-only compilers with gcc-compatible arguments are supported.
+  Currently only compilers with gcc-compatible arguments are supported.
 
-`NVIM_TEST_MAIN_CDEFS` (U) (1): makes `ffi.cdef` run in main process. This 
+- `NVIM_TEST_MAIN_CDEFS` (U) (1): makes `ffi.cdef` run in main process. This
-raises a possibility of bugs due to conflicts in header definitions, despite the 
+  raises a possibility of bugs due to conflicts in header definitions, despite
-counters, but greatly speeds up unit tests by not requiring `ffi.cdef` to do 
+  the counters, but greatly speeds up unit tests by not requiring `ffi.cdef` to
-parsing of big strings with C definitions.
+  do parsing of big strings with C definitions.
 
-`NVIM_TEST_PRINT_I` (U) (1): makes `cimport` print preprocessed, but not yet 
+- `NVIM_TEST_PRINT_I` (U) (1): makes `cimport` print preprocessed, but not yet
-filtered through `formatc` headers. Used to debug `formatc`. Printing is done 
+  filtered through `formatc` headers. Used to debug `formatc`. Printing is done
-with the line numbers.
+  with the line numbers.
 
-`NVIM_TEST_PRINT_CDEF` (U) (1): makes `cimport` print final lines which will be 
+- `NVIM_TEST_PRINT_CDEF` (U) (1): makes `cimport` print final lines which will
-then passed to `ffi.cdef`. Used to debug errors `ffi.cdef` happens to throw 
+  be then passed to `ffi.cdef`. Used to debug errors `ffi.cdef` happens to
-sometimes.
+  throw sometimes.
 
-`NVIM_TEST_PRINT_SYSCALLS` (U) (1): makes it print to stderr when syscall 
+- `NVIM_TEST_PRINT_SYSCALLS` (U) (1): makes it print to stderr when syscall
-wrappers are called and what they returned. Used to debug code which makes unit 
+  wrappers are called and what they returned. Used to debug code which makes
-tests be executed in separate processes.
+  unit tests be executed in separate processes.
 
-`NVIM_TEST_RUN_FAILING_TESTS` (U) (1): makes `itp` run tests which are known to 
+- `NVIM_TEST_RUN_FAILING_TESTS` (U) (1): makes `itp` run tests which are known
-fail (marked by setting third argument to `true`).
+  to fail (marked by setting third argument to `true`).
 
-`LOG_DIR` (FU) (S!): specifies where to seek for valgrind and ASAN log files.
+- `LOG_DIR` (FU) (S!): specifies where to seek for valgrind and ASAN log files.
 
-`NVIM_TEST_CORE_*` (FU) (S): a set of environment variables which specify where 
+- `NVIM_TEST_CORE_*` (FU) (S): a set of environment variables which specify
-to search for core files. Are supposed to be defined all at once.
+  where to search for core files. Are supposed to be defined all at once.
 
-`NVIM_TEST_CORE_GLOB_DIRECTORY` (FU) (S): directory where core files are 
+- `NVIM_TEST_CORE_GLOB_DIRECTORY` (FU) (S): directory where core files are
-located. May be `.`. This directory is then recursively searched for core files. 
+  located. May be `.`. This directory is then recursively searched for core
-Note: this variable must be defined for any of the following to have any effect.
+  files. Note: this variable must be defined for any of the following to have
+  any effect.
 
-`NVIM_TEST_CORE_GLOB_RE` (FU) (S): regular expression which must be matched by 
+- `NVIM_TEST_CORE_GLOB_RE` (FU) (S): regular expression which must be matched
-core files. E.g. `/core[^/]*$`. May be absent, in which case any file is 
+  by core files. E.g. `/core[^/]*$`. May be absent, in which case any file is
-considered to be matched.
+  considered to be matched.
 
-`NVIM_TEST_CORE_EXC_RE` (FU) (S): regular expression which excludes certain 
+- `NVIM_TEST_CORE_EXC_RE` (FU) (S): regular expression which excludes certain
-directories from searching for core files inside. E.g. use `^/%.deps$` to not 
+  directories from searching for core files inside. E.g. use `^/%.deps$` to not
-search inside `/.deps`. If absent, nothing is excluded.
+  search inside `/.deps`. If absent, nothing is excluded.
 
-`NVIM_TEST_CORE_DB_CMD` (FU) (S): command to get backtrace out of the debugger. 
+- `NVIM_TEST_CORE_DB_CMD` (FU) (S): command to get backtrace out of the
-E.g. `gdb -n -batch -ex "thread apply all bt full" "$_NVIM_TEST_APP" -c 
+  debugger. E.g. `gdb -n -batch -ex "thread apply all bt full"
-"$_NVIM_TEST_CORE"`. Defaults to the example command. This debug command may use 
+  "$_NVIM_TEST_APP" -c "$_NVIM_TEST_CORE"`. Defaults to the example command.
-environment variables `_NVIM_TEST_APP` (path to application which is being 
+  This debug command may use environment variables `_NVIM_TEST_APP` (path to
-debugged: normally either nvim or luajit) and `_NVIM_TEST_CORE` (core file to 
+  application which is being debugged: normally either nvim or luajit) and
-get backtrace from).
+  `_NVIM_TEST_CORE` (core file to get backtrace from).
 
-`NVIM_TEST_CORE_RANDOM_SKIP` (FU) (D): makes `check_cores` not check cores after 
+- `NVIM_TEST_CORE_RANDOM_SKIP` (FU) (D): makes `check_cores` not check cores
-approximately 90% of the tests. Should be used when finding cores is too hard 
+  after approximately 90% of the tests. Should be used when finding cores is
-for some reason. Normally (on OS X or when `NVIM_TEST_CORE_GLOB_DIRECTORY` is 
+  too hard for some reason. Normally (on OS X or when
-defined and this variable is not) cores are checked for after each test.
+  `NVIM_TEST_CORE_GLOB_DIRECTORY` is defined and this variable is not) cores
+  are checked for after each test.
 
-`NVIM_TEST_RUN_TESTTEST` (U) (1): allows running `test/unit/testtest_spec.lua` 
+- `NVIM_TEST_RUN_TESTTEST` (U) (1): allows running
-used to check how testing infrastructure works.
+  `test/unit/testtest_spec.lua` used to check how testing infrastructure works.
 
-`NVIM_TEST_TRACE_LEVEL` (U) (N): specifies unit tests tracing level: `0` 
+- `NVIM_TEST_TRACE_LEVEL` (U) (N): specifies unit tests tracing level: `0`
-disables tracing (the fastest, but you get no data if tests crash and there was 
+  disables tracing (the fastest, but you get no data if tests crash and there
-no core dump generated), `1` or empty/undefined leaves only C function cals and 
+  was no core dump generated), `1` or empty/undefined leaves only C function
-returns in the trace (faster then recording everything), `2` records all 
+  cals and returns in the trace (faster then recording everything), `2` records
-function calls, returns and lua source lines exuecuted.
+  all function calls, returns and lua source lines exuecuted.
 
-`NVIM_TEST_TRACE_ON_ERROR` (U) (1): makes unit tests yield trace on error in 
+- `NVIM_TEST_TRACE_ON_ERROR` (U) (1): makes unit tests yield trace on error in
-addition to regular error message.
+  addition to regular error message.
 
-`NVIM_TEST_MAXTRACE` (U) (N): specifies maximum number of trace lines to keep. 
+- `NVIM_TEST_MAXTRACE` (U) (N): specifies maximum number of trace lines to
-Default is 1024.
+  keep. Default is 1024.