From 857a7312d015350c9637548310c7a187637d3ca4 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Sun, 9 Dec 2018 01:31:34 +0100 Subject: [PATCH] doc (#9288) - misc - doc: `:help config`. closes #9329 - cleanup test/README.md --- README.md | 2 +- runtime/doc/api.txt | 28 +++--- runtime/doc/starting.txt | 23 +++-- src/nvim/api/buffer.c | 3 +- test/README.md | 183 ++++++++++++++++++--------------------- 5 files changed, 109 insertions(+), 130 deletions(-) diff --git a/README.md b/README.md index fd89456a96..0aa77b1e68 100644 --- a/README.md +++ b/README.md @@ -86,7 +86,7 @@ Project layout ├─ ci/ build automation ├─ cmake/ build scripts ├─ runtime/ user plugins/docs - ├─ src/ application source code (see src/nvim/README.md) + ├─ src/nvim/ application source code (see src/nvim/README.md) │ ├─ api/ API subsystem │ ├─ eval/ VimL subsystem │ ├─ event/ event-loop subsystem diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 0219488088..7dab69df22 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -1138,7 +1138,7 @@ nvim_buf_add_highlight({buffer}, {ns_id}, {hl_group}, {line}, which returns a namespace id. Pass it in to this function as `ns_id` to add highlights to the namespace. All highlights in the same namespace can then be cleared with single call to - |nvim_buf_clear_highlight|. If the highlight never will be + |nvim_buf_clear_namespace|. If the highlight never will be deleted by an API call, pass `ns_id = -1`. As a shorthand, `ns_id = 0` can be used to create a new @@ -1162,20 +1162,21 @@ nvim_buf_add_highlight({buffer}, {ns_id}, {hl_group}, {line}, Return: ~ The ns_id that was used - *nvim_buf_clear_highlight()* -nvim_buf_clear_highlight({buffer}, {ns_id}, {line_start}, {line_end}) - Clears highlights and virtual text from a given source id and - range of lines + *nvim_buf_clear_namespace()* +nvim_buf_clear_namespace({buffer}, {ns_id}, {line_start}, {line_end}) + Clears namespaced objects, highlights and virtual text, from a + line range - To clear a source group in the entire buffer, pass in 0 and -1 + To clear the namespace in the entire buffer, pass in 0 and -1 to line_start and line_end respectively. Parameters: ~ {buffer} Buffer handle - {ns_id} Namespace to clear, or -1 to clear all. + {ns_id} Namespace to clear, or -1 to clear all + namespaces. {line_start} Start of range of lines to clear {line_end} End of range of lines to clear (exclusive) - or -1 to clear to end of file. + or -1 to clear to end of buffer. *nvim_buf_set_virtual_text()* nvim_buf_set_virtual_text({buffer}, {ns_id}, {line}, {chunks}, {opts}) @@ -1184,18 +1185,17 @@ nvim_buf_set_virtual_text({buffer}, {ns_id}, {line}, {chunks}, {opts}) By default (and currently the only option) the text will be placed after the buffer text. Virtual text will never cause reflow, rather virtual text will be truncated at the end of - the screen line. The virtual text will begin after one cell to - the right of the ordinary text, this will contain the |lcs- - eol| char if set, otherwise just be a space. + the screen line. The virtual text will begin one cell (|lcs- + eol| or space) after the ordinary text. Namespaces are used to support batch deletion/updating of virtual text. To create a namespace, use |nvim_create_namespace|. Virtual text is cleared using - |nvim_buf_clear_highlight|. The same `ns_id` can be used for + |nvim_buf_clear_namespace|. The same `ns_id` can be used for both virtual text and highlights added by |nvim_buf_add_highlight|, both can then be cleared with a - single call to |nvim_buf_clear_highlight|. If the virtual text - never will be cleared by an API call, pass `src_id = -1`. + single call to |nvim_buf_clear_namespace|. If the virtual text + never will be cleared by an API call, pass `ns_id = -1`. As a shorthand, `ns_id = 0` can be used to create a new namespace for the virtual text, the allocated id is then diff --git a/runtime/doc/starting.txt b/runtime/doc/starting.txt index 1da2441929..450d2967b4 100644 --- a/runtime/doc/starting.txt +++ b/runtime/doc/starting.txt @@ -410,20 +410,17 @@ accordingly. Vim proceeds in this order: 3. Execute Ex commands, from environment variables and/or files An environment variable is read as one Ex command line, where multiple - commands must be separated with '|' or "". - *init.vim* *vimrc* *exrc* - A file that contains initialization commands is called a "vimrc" file. - Each line in a vimrc file is executed as an Ex command line. It is - sometimes also referred to as "exrc" file. They are the same type of - file, but "exrc" is what Vi always used, "vimrc" is a Vim specific - name, "init.vim" is Neovim specific location for vimrc file. Also see - |vimrc-intro|. + commands must be separated with '|' or . + *config* *init.vim* *vimrc* *exrc* + A file that contains initialization commands is generically called + a "vimrc" or config file. Each line in a vimrc file is executed as an + Ex command line. See also |vimrc-intro| and |base-directories|. - Places for your personal initializations (see |base-directories|): - Unix $XDG_CONFIG_HOME/nvim/init.vim - (default for $XDG_CONFIG_HOME is ~/.config) - Windows $XDG_CONFIG_HOME/nvim/init.vim - (default for $XDG_CONFIG_HOME is ~/AppData/Local) + The Nvim config file is named "init.vim", located at: + Unix ~/.config/nvim/init.vim + Windows ~/AppData/Local/nvim/init.vim + Or if |$XDG_CONFIG_HOME| is defined: + $XDG_CONFIG_HOME/nvim/init.vim RECOMMENDATION: Put all your Vim configuration stuff in the $HOME/.config/nvim/ directory. That makes it easy to copy it to diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c index 29c8ea634a..5df0f0bb47 100644 --- a/src/nvim/api/buffer.c +++ b/src/nvim/api/buffer.c @@ -1027,8 +1027,7 @@ void nvim_buf_clear_highlight(Buffer buffer, /// By default (and currently the only option) the text will be placed after /// the buffer text. Virtual text will never cause reflow, rather virtual /// text will be truncated at the end of the screen line. The virtual text will -/// begin after one cell to the right of the ordinary text, this will contain -/// the |lcs-eol| char if set, otherwise just be a space. +/// begin one cell (|lcs-eol| or space) after the ordinary text. /// /// Namespaces are used to support batch deletion/updating of virtual text. /// To create a namespace, use |nvim_create_namespace|. Virtual text is diff --git a/test/README.md b/test/README.md index 0999f412ac..1a5dc022f4 100644 --- a/test/README.md +++ b/test/README.md @@ -1,27 +1,63 @@ Tests ===== -Tests are run by `/cmake/RunTests.cmake` file, using `busted`. +Tests are broadly divided into *unit tests* ([test/unit](https://github.com/neovim/neovim/tree/master/test/unit/)), +*functional tests* ([test/functional](https://github.com/neovim/neovim/tree/master/test/functional/)), +and *old tests* ([src/nvim/testdir/](https://github.com/neovim/neovim/tree/master/src/nvim/testdir/)). -For some failures, `.nvimlog` (or `$NVIM_LOG_FILE`) may provide insight. +- _Unit_ testing is achieved by compiling the tests as a shared library which is + loaded and called by [LuaJit FFI](http://luajit.org/ext_ffi.html). +- _Functional_ tests are driven by RPC, so they do not require LuaJit (as + opposed to Lua). + +You can learn the [key concepts of Lua in 15 minutes](http://learnxinyminutes.com/docs/lua/). +Use any existing test as a template to start writing new tests. + +Tests are run by `/cmake/RunTests.cmake` file, using `busted` (a Lua test-runner). +For some failures, `.nvimlog` (or `$NVIM_LOG_FILE`) may provide insight. + +Depending on the presence of binaries (e.g., `xclip`) some tests will be +ignored. You must compile with libintl to prevent `E319: The command is not +available in this version` errors. -Depending on the presence of binaries (e.g., `xclip`) some tests will be ignored. You must compile with libintl to prevent `E319: The command is not available in this version` errors. --- - [Running tests](#running-tests) -- [Unit tests](#unit-tests) +- [Writing tests](#writing-tests) - [Lint](#lint) - [Environment variables](#environment-variables) --- + +Layout +====== + +- `/test/benchmark` : benchmarks +- `/test/functional` : functional tests +- `/test/unit` : unit tests +- `/test/config` : contains `*.in` files which are transformed into `*.lua` + files using `configure_file` CMake command: this is for acessing CMake + variables in lua tests. +- `/test/includes` : include-files for use by luajit `ffi.cdef` C definitions + parser: normally used to make macros not accessible via this mechanism + accessible the other way. +- `/test/*/preload.lua` : modules preloaded by busted `--helper` option +- `/test/**/helpers.lua` : common utility functions for test code +- `/test/*/**/*_spec.lua` : actual tests. Files that do not end with + `_spec.lua` are libraries like `/test/**/helpers.lua`, except that they have + some common topic. +- `/src/nvim/testdir` : old tests (from Vim) + + Running tests -------------- +============= -## Executing Tests +Executing Tests +--------------- -To run all _non-legacy_ (unit + functional) tests: +To run all tests (except "old" tests): make test @@ -33,9 +69,32 @@ To run only _functional_ tests: make functionaltest ---- -## Filter Tests +Legacy tests +------------ + +To run all legacy Vim tests: + + make oldtest + +To run a *single* legacy test set `TEST_FILE`, for example: + + TEST_FILE=test_syntax.res make oldtest + +- The `.res` extension (instead of `.vim`) is required. +- Specify only the test file name, not the full path. + + +Debugging tests +--------------- + +You can set `$GDB` to [run tests under gdbserver](https://github.com/neovim/neovim/pull/1527). +And if `$VALGRIND` is set it will pass `--vgdb=yes` to valgrind instead of +starting gdbserver directly. + + +Filtering Tests +--------------- ### Filter by name @@ -85,58 +144,20 @@ To run only the tagged tests: TEST_TAG=foo make functionaltest -**NOTES**: +**NOTE:** -* Tags are mainly used for testing issues (ex: `#1234`), so use the following - method. * `TEST_FILE` is not a pattern string like `TEST_TAG` or `TEST_FILTER`. The given value to `TEST_FILE` must be a path to an existing file. -* Both `TEST_TAG` and `TEST_FILTER` filter tests by the strings from either - `it()` or `describe()` functions. +* Both `TEST_TAG` and `TEST_FILTER` filter tests by the string descriptions + found in `it()` and `describe()`. ---- -### Legacy +Writing tests +============= -To run all legacy (Vim) integration tests: - - make oldtest - -To run a *single* legacy test, run `make` with `TEST_FILE=test_name.res`. E.g. -to run `test_syntax.vim`: - - TEST_FILE=test_syntax.res make oldtest - -- The `.res` extension (instead of `.vim`) is required. -- Specify only the test file name, not the full path. - -### Functional tests - -`$GDB` can be set to [run tests under -gdbserver](https://github.com/neovim/neovim/pull/1527). If `$VALGRIND` is also -set, it will add the `--vgdb=yes` option to valgrind instead of -starting gdbserver directly. - -Unit tests +Guidelines ---------- -Tests are broadly divided into *unit tests* -([test/unit](https://github.com/neovim/neovim/tree/master/test/unit) directory) -and *functional tests* -([test/functional](https://github.com/neovim/neovim/tree/master/test/functional) -directory). Use any of the existing tests as a template to start writing new -tests. - -- _Unit_ testing is achieved by compiling the tests as a shared library which is - loaded and called by LuaJit [FFI](http://luajit.org/ext_ffi.html). -- _Functional_ tests are driven by RPC, so they do not require LuaJit (as - opposed to Lua). - -You can learn the [key concepts of Lua in 15 -minutes](http://learnxinyminutes.com/docs/lua/). - -## Guidelines for writing tests - - Consider [BDD](http://en.wikipedia.org/wiki/Behavior-driven_development) guidelines for organization and readability of tests. Describe what you're testing (and the environment if applicable) and create specs that assert its @@ -174,8 +195,14 @@ minutes](http://learnxinyminutes.com/docs/lua/). ([example](https://github.com/neovim/neovim/commit/5c1dc0fbe7388528875aff9d7b5055ad718014de#diff-bf80b24c724b0004e8418102f68b0679R18)). - Use `make testlint` for using the shipped luacheck program ([supported by syntastic](https://github.com/scrooloose/syntastic/blob/d6b96c079be137c83009827b543a83aa113cc011/doc/syntastic-checkers.txt#L3546)) to lint all tests. +- Really long `source([=[...]=])` blocks may break syntax highlighting. Try + `:syntax sync fromstart` to fix it. -### Where tests go +Where tests go +-------------- + +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 @@ -189,33 +216,9 @@ minutes](http://learnxinyminutes.com/docs/lua/). - Try to find an existing `test/functional/*/*_spec.lua` group that makes sense, before creating a new one. -## Checklist for migrating legacy tests - -**Note:** Only "old style" (`src/nvim/testdir/*.in`) legacy tests should be -converted. Please _do not_ convert "new style" Vim tests -(`src/nvim/testdir/*.vim`). -The "new style" Vim tests are faster than the old ones, and converting them -takes time and effort better spent elsewhere. - -- Remove the associated `test.in`, `test.out`, and `test.ok` files from - `src/nvim/testdir/`. -- Make sure the lua test ends in `_spec.lua`. -- Make sure the test count increases accordingly in the build log. -- Make sure the new test contains the same control characters (`^]`, ...) as the - old test. - - Instead of the actual control characters, use an equivalent textual - representation (e.g. `` instead of `^]`). The - `scripts/legacy2luatest.pl` script does some of these conversions - automatically. - -## Tips - -- Really long `source([=[...]=])` blocks may break syntax highlighting. Try - `:syntax sync fromstart` to fix it. - Lint ----- +==== `make lint` (and `make testlint`) runs [luacheck](https://github.com/mpeterv/luacheck) on the test code. @@ -229,29 +232,9 @@ http://luacheck.readthedocs.io/en/stable/warnings.html Ignore the smallest applicable scope (e.g. inside a function, not at the top of the file). -Layout ------- - -- `/test/benchmark` : benchmarks -- `/test/functional` : functional tests -- `/test/unit` : unit tests -- `/test/config` : contains `*.in` files which are transformed into `*.lua` - files using `configure_file` CMake command: this is for acessing CMake - variables in lua tests. -- `/test/includes` : include-files for use by luajit `ffi.cdef` C definitions - parser: normally used to make macros not accessible via this mechanism - accessible the other way. -- `/test/*/preload.lua` : modules preloaded by busted `--helper` option -- `/test/**/helpers.lua` : common utility functions for test code -- `/test/*/**/*_spec.lua` : actual tests. Files that do not end with - `_spec.lua` are libraries like `/test/**/helpers.lua`, except that they have - some common topic. - -Tests in `/test/unit` and `/test/functional` are normally divided into groups -by the semantic component they are testing. Environment variables ---------------------- +===================== Test behaviour is affected by environment variables. Currently supported (Functional, Unit, Benchmarks) (when Defined; when set to _1_; when defined,