Problem: Any preceding luadocs block that define alias types with
`@alias` magic would be prepended to the documentation of functions
that follow, despite the "blank line" separator. For example:
```
--- @alias some.type.between.functions
--- Blah blah long documentation for alias
--- | "foo" # foo
--- | "bar" # bar
--- The documentation that should appear in vimdoc.
function M.function_to_include_in_doc()
...
end
```
then the vimdoc generated for `function_to_include_in_doc` would include
the text from the alias block (e.g., "Blah blah ... for alias").
Solution:
- refactor: Lua2DoxFilter should maintain its own internal state
`generics`, rather than carrying it as a parameter to local helper
functions.
- Add another boolean state `boolean_state` which represents whether
to ignore the current docstring block (magic lines). This flag will
be reset as soon as the block is end.
Note: As expected, there is no change at all in the current docs
generated, because we have been working around and writing luadoc
comments so that such erroneous docstring resulting from preceding
`@alias` blocks won't appear.
- Add section `VIM.LPEG` and `VIM.RE` to docs/lua.txt.
- Add `_meta/re.lua` which adds luadoc and type annotations, for the
vendored `vim.re` package.
- Fix minor style issues on `_meta/lpeg.lua` luadoc for better vimdocs
generation.
- Fix a bug on `gen_vimdoc` where non-helptags in verbatim code blocks
were parsed as helptags, affecting code examples on `vim.lpeg.Cf`,
etc.
- Also move the `vim.regex` section below so that it can be located
closer to `vim.lpeg` and `vim.re`.
Problem: Some lines in the generated vim doc are overflowing, not
correctly wrapped at 78 characters. This happens when docs body contains
several consecutive 'inline' elements generated by doxygen.
Solution: Take into account the current column offset of the last line,
and prepend some padding before doc_wrap().
Since some point INCLUDE_DEPRECATED stopped working as it is usually
turned off when generating an actual vimdoc. This commit fixes this
hidden feature back again (used for devel purposes only).
Problem: main() has too much logic implemented there, too difficult to
read.
Solution: Do more OOP, introduce `Section` dataclass that stores
information about a "section", with documentation and concrete examples
about what each field and variable would mean. Extract all the lines for
rendering a section into `section.render()` pulled out of `main()`.
Problem:
For function definitions to be included in the vimdoc (formatted) and
to be exported as mpack data (unformatted), we had two internal
representations of the same function/API metadata in duplicate;
one is FunctionDoc (which was previously a dict), and the other is
doxygen XML DOM from which vimdoc (functions sections) was generated.
Solution:
We should have a single path and unified data representation
(i.e. FunctionDoc) that contains all the metadata and information about
function APIs, from which both of mpack export and vimdoc are generated.
I.e., vimdocs are no longer generated directly from doxygen XML nodes,
but generated via:
(XML DOM Nodes) ------------> FunctionDoc ------> mpack (unformatted)
Recursive Internal |
Formatting Metadata +---> vimdoc (formatted)
This refactoring eliminates the hacky and ugly use of `fmt_vimhelp` in
`fmt_node_as_vimhelp()` and all other helper functions! This way,
`fmt_node_as_vimhelp()` can simplified as it no longer needs to handle
generating of function docs, which needs to be done only in the topmost
level of recursion.
There is no reason for this file to be in project root, which is crowded
as is. This also fits nicely part of the ongoing work towards gathering
as much of the documentation as possible into one place.
Style improvements:
1. Anonymous classes derived from `StructureLiteralType` should have a
better name. The class name can be also nested. Examples:
```diff
----@field serverInfo? anonym1
+---@field serverInfo? lsp._anonym1.serverInfo
```
```diff
----@field insertTextModeSupport? anonym26
+---@field insertTextModeSupport? lsp._anonym26.completionItem.insertTextModeSupport
```
2. Add one separate empty line before each `@field` definition. Without
these, empty lines the doc can look confusing because descriptions
also may contain empty lines. See `lsp.CompletionItem` for example:
```lua
---The kind of this completion item. Based of the kind
---an icon is chosen by the editor.
---@field kind? lsp.CompletionItemKind
---Tags for this completion item.
---
---@since 3.15.0
---@field tags? lsp.CompletionItemTag[]
```
It might feel like "Tags for this completion item" belongs to `kind`,
not `tags` due to the lack of separator blank lines. The following
(after this commit) should look much better:
```diff
---The kind of this completion item. Based of the kind
---an icon is chosen by the editor.
---@field kind? lsp.CompletionItemKind
+---
---Tags for this completion item.
---
---@since 3.15.0
---@field tags? lsp.CompletionItemTag[]
```
3. Escape some LSP-specific annotations that can't be recognized by
lua-ls. It'd be better to make them visible in LSP hover doc windows.
Example: `@sample ...`.
Fixes:
1. A type may extend from more than one base types (as well as mixin
types). Previously only the first base class was being considered,
resulting incomplete base classes for `@class` definitions.
Example: `InlayHintOptions` (should have both of `resolveProvider`
and `workDoneProgress`, the latter is from `WorkDoneProgressOptions`)
```diff
----@class lsp.InlayHintOptions
+---@class lsp.InlayHintOptions: lsp.WorkDoneProgressOptions
```
2. Remove `<200b>` (zero-width space) unicode characters.
3. Add the missing newline at EOF.
Problem: We have `P_(BOOL|NUM|STRING)` macros to represent an option's type, which is redundant because `OptValType` can already do that. The current implementation of option type flags is also too limited to allow adding multitype options in the future.
Solution: Remove `P_(BOOL|NUM|STRING)` and replace it with a new `type_flags` attribute in `vimoption_T`. Also do some groundwork for adding multitype options in the future.
Side-effects: Attempting to set an invalid keycode option (e.g. `set t_foo=123`) no longer gives an error.
Problem: Wiki contents are not discoverable and hard to maintain.
Solution: Move FAQ to runtime docs.
Co-authored-by: Christian Clason <c.clason@uni-graz.at>
- Improve CLI argument parsing, rejects invalid argument and commands as
early as possible. Also prints USAGE in the command line.
- No longer allows `--<outfile>`, use `--out <outfile>` instead.
- Print a little bit of verbose messages to better know what's going on
rather than remaining silent at all times.
- Add type annotation `gen_lsp._opt` to avoid type warnings.
Problem:
We don't enable stylua for many Lua scripts. Automating code-style is an
important tool for reducing time spent on accidental (non-essential)
complexity.
Solution:
- Enable lintlua for `scripts/` directory.
- Specify `call_parentheses = "Input"`, we should allow kwargs-style
function invocations.
Problem:
Numerous Vim 8.1 patches are listed by `vim-patch.sh -l`.
Solution:
Mark the following patches as N/A:
obviated by $NVIM env var:
vim-patch:8.1.0049 shell cannot tell running in a terminal window
vim-patch:8.1.0050 $VIM_TERMINAL is also set when not in a terminal window
'termwinkey' is not supported by Nvim:
vim-patch:8.1.0072 use of 'termwinkey' is inconsistent
Nvim handles STOP signal via libuv:
vim-patch:8.1.0304 no redraw when using a STOP signal on Vim and then CONT
vim-patch:8.1.0312 wrong type for flags used in signal handlers
Nvim does not have `parse_queued_messages`:
vim-patch:8.1.0367 getchar(1) no longer processes pending messages
N/A various:
vim-patch:8.1.1396 'wincolor' does not apply to lines below the buffer
vim-patch:8.1.1502 cannot play any sound
vim-patch:8.1.1515 memory leak reported for sound when build with EXITFREE
Nvim has extmarks instead of textprops:
vim-patch:8.1.0579 cannot attach properties to text
vim-patch:8.1.0582 text properties are not enabled
vim-patch:8.1.0634 text properties cannot cross line boundaries
vim-patch:8.1.0638 text property highlighting is off by one column
vim-patch:8.1.0639 text properties test fails on MS-Windows
vim-patch:8.1.0643 computing byte offset wrong
vim-patch:8.1.0654 when deleting a line text property flags are not adjusted
vim-patch:8.1.0655 when appending a line text property flags are not added
vim-patch:8.1.0663 text property display wrong when 'number' is set
vim-patch:8.1.0665 text property display wrong when 'spell' is set
vim-patch:8.1.0667 textprop test leaves file behind
vim-patch:8.1.0675 text property column in screen columns is not practical
vim-patch:8.1.0676 textprop screendump test fails
vim-patch:8.1.0681 text properties as not adjusted for deleted text
vim-patch:8.1.0682 text properties not adjusted when backspacing replaced text
vim-patch:8.1.0688 text properties are not restored by undo
vim-patch:8.1.0689 undo with text properties not tested
vim-patch:8.1.0690 setline() and setbufline() do not clear text properties
vim-patch:8.1.0691 text properties are not adjusted for :substitute
vim-patch:8.1.0694 when using text props may free memory that is not allocated
vim-patch:8.1.0703 compiler warnings with 64-bit compiler
vim-patch:8.1.0707 text property columns are not adjusted for changed indent
vim-patch:8.1.0970 text properties test fails when 'encoding' is not utf-8
vim-patch:8.1.1035 prop_remove() second argument is not optional
vim-patch:8.1.1276 cannot combine text properties with syntax highlighting
vim-patch:8.1.1278 missing change for "combine" field
vim-patch:8.1.1333 text properties don't always move after changes
vim-patch:8.1.1337 get empty text prop when splitting line just after text prop
vim-patch:8.1.1341 text properties are lost when joining lines
vim-patch:8.1.1343 text properties not adjusted for Visual block mode delete
vim-patch:8.1.1340 attributes from 'cursorline' overwrite textprop
vim-patch:8.1.1351 text property wrong after :substitute
vim-patch:8.1.1359 text property wrong after :substitute with backslash
vim-patch:8.1.1387 calling prop_add() in an empty buffer doesn't work
vim-patch:8.1.1388 errors when calling prop_remove() for an unloaded buffer
vim-patch:8.1.1463 gcc warns for uninitialized variable
N/A Nvim has buf_attach instead of "listeners":
vim-patch:8.1.1320 it is not possible to track changes to a buffer
vim-patch:8.1.1321 no docs or tests for listener functions
vim-patch:8.1.1326 no test for listener with partial
vim-patch:8.1.1328 no test for listener with undo operation
vim-patch:8.1.1332 cannot flush listeners without redrawing, mix of changes
vim-patch:8.1.1335 listener callback is called after inserting text
vim-patch:8.1.1419 listener callbacks may be called recursively
vim-patch:8.1.1486 a listener change is merged even when it adds a line
N/A build issues:
vim-patch:8.1.0601 a few compiler warnings
vim-patch:8.1.0612 cannot use two global runtime dirs with configure
vim-patch:8.1.0684 warnings from 64-bit compiler
vim-patch:8.1.1344 Coverity complains about possibly using a NULL pointer
vim-patch:8.1.1376 warnings for size_t/int mixups
vim-patch:8.1.1414 alloc() returning "char_u *" causes a lot of type casts
vim-patch:8.1.1508 sound keeps failing on Travis
vim-patch:8.1.1494 build failure
N/A terminal / job control patches:
vim-patch:8.1.0761 default value for brief_wait is wrong
vim-patch:8.1.0824 SunOS/Solaris has a problem with ttys
vim-patch:8.1.0845 having job_status() free the job causes problems
vim-patch:8.1.0870 Vim doesn't use the new ConPTY support in Windows 10
vim-patch:8.1.0880 MS-Windows: inconsistent selection of winpty/conpty
vim-patch:8.1.0890 pty allocation wrong if using file for out channel
vim-patch:8.1.0906 using clumsy way to get console window handle
vim-patch:8.1.0909 MS-Windows: using ConPTY even though it is not stable
vim-patch:8.1.0928 stray log function call
vim-patch:8.1.0940 MS-Windows console resizing not handled properly
vim-patch:8.1.1028 MS-Windows: memory leak when creating terminal fails
vim-patch:8.1.1265 when GPM mouse support is enabled double clicks do not work
vim-patch:8.1.1267 cannot check if GPM mouse support is working
N/A encoding patches:
vim-patch:8.1.0879 MS-Windows: temp name encoding can be wrong
vim-patch:8.1.0895 MS-Windows: dealing with temp name encoding not quite right
vim-patch:8.1.0918 MS-Windows: startup messages are not converted
vim-patch:8.1.1090 MS-Windows: modify_fname() has problems with some 'encoding'
N/A platform patches:
vim-patch:8.1.1103 MS-Windows: old API calls are no longer needed
N/A Lua patches:
vim-patch:8.1.1019 Lua: may garbage collect function reference in use
N/A Nvim has floating windows instead of popup window:
vim-patch:8.1.1329 plans for popup window support are spread out
vim-patch:8.1.1364 design for popup window support needs more details
vim-patch:8.1.1391 no popup window support
vim-patch:8.1.1400 using global pointer for tab-local popups is clumsy
vim-patch:8.1.1399 popup windows not adjusted when switching tabs
vim-patch:8.1.0062 popup menu broken if a callback changes the window layout
vim-patch:8.1.1405 "highlight" option of popup windows not supported
vim-patch:8.1.1406 popup_hide() and popup_show() not implemented yet
vim-patch:8.1.1407 popup_create() does not support text properties
vim-patch:8.1.1410 popup_move() is not implemented yet
vim-patch:8.1.1402 "timer" option of popup windows not supported
vim-patch:8.1.1408 PFL_HIDDEN conflicts with system header file
vim-patch:8.1.1420 popup window size only uses first line length
vim-patch:8.1.1421 drawing "~" line in popup window
vim-patch:8.1.1422 popup_getoptions() not implemented yet
vim-patch:8.1.1423 popup windows use options from current window and buffer
vim-patch:8.1.1426 no test for syntax highlight in popup window
vim-patch:8.1.1427 popup window screenshot test fails
vim-patch:8.1.1428 popup_atcursor() not implemented yet
vim-patch:8.1.1429 "pos" option of popup window not supported yet
vim-patch:8.1.1430 popup window option "wrap" not supported
vim-patch:8.1.1431 popup window listed as "Scratch"
vim-patch:8.1.1432 can't build with eval feature
vim-patch:8.1.1438 some commands cause trouble in a popup window
vim-patch:8.1.1441 popup window filter not yet implemented
vim-patch:8.1.1442 popup windows not considered when the Vim window is resized
vim-patch:8.1.1443 popup window padding and border not implemented yet
vim-patch:8.1.1444 not using double line characters for popup border
vim-patch:8.1.1445 popup window border highlight not implemented yet
vim-patch:8.1.1446 popup window callback not implemented yet
vim-patch:8.1.1447 not allowed to create an empty popup
vim-patch:8.1.1448 statusline is sometimes drawn on top of popup
vim-patch:8.1.1449 popup text truncated at end of screen
vim-patch:8.1.1450 popup window positioning wrong when using padding or borders
vim-patch:8.1.1451 CTRL-L does not clear screen with a popup window
vim-patch:8.1.1452 line and col property of popup windows not properly checked
vim-patch:8.1.1453 popup window "moved" property not implemented yet
vim-patch:8.1.1455 popup_atcursor() not completely implemented
vim-patch:8.1.1459 popup window border looks bad when 'ambiwidth' is "double"
vim-patch:8.1.1460 popup window border characters may be wrong
vim-patch:8.1.1416 popup_getposition() not implemented yet
vim-patch:8.1.1493 redrawing with popups is slow and causes flicker
vim-patch:8.1.1496 popup window height is not recomputed
vim-patch:8.1.1499 ruler not updated after popup window was removed
vim-patch:8.1.1511 matches in a popup window are not displayed properly
vim-patch:8.1.1513 all popup functionality is in functions, except :popupclear
vim-patch:8.1.1517 when a popup changes all windows are redrawn
vim-patch:8.1.1518 crash when setting 'columns' while a popup is visible
vim-patch:8.1.1520 popup windows are ignored when dealing with mouse position
vim-patch:8.1.1521 when a popup window is closed the buffer remains
vim-patch:8.1.1522 poup_notification() not implemented yet
vim-patch:8.1.1495 memory access error
vim-patch:8.1.1497 accessing memory beyond allocated space
N/A already applied:
vim-patch:8.1.1226 {not in Vi} remarks get in the way of useful help text
vim-patch:8.1.1280 remarks about functionality not in Vi clutters the help
We already have an extensive suite of static analysis tools we use,
which causes a fair bit of redundancy as we get duplicate warnings. PVS
is also prone to give false warnings which creates a lot of work to
identify and disable.
refactor!: `vim.lsp.inlay_hint()` -> `vim.lsp.inlay_hint.enable()`
Problem:
The LSP specification allows inlay hints to include tooltips, clickable
label parts, and code actions; but Neovim provides no API to query for
these.
Solution:
Add minimal viable extension point from which plugins can query for
inlay hints in a range, in order to build functionality on top of.
Possible Next Steps
---
- Add `virt_text_idx` field to `vim.fn.getmousepos()` return value, for
usage in mappings of `<LeftMouse>`, `<C-LeftMouse>`, etc
In cases where the generated files depend on changes to Nvim itself,
generating the files with an older version of Nvim will fail because
those changes are not present in the older version.
For example, if a new option is added then the generator script should
be run with the version of Nvim that contains the new option, or else
the generation will fail.
Co-authored-by: dundargoc <gocdundar@gmail.com>
- Move vimoption_T to option.h
- option_defs.h is for option-related types
- option_vars.h corresponds to Vim's option.h
- option_defs.h and option_vars.h don't include each other
Memoizes a function, using a custom function to hash the arguments.
Private for now until:
- There are other places in the codebase that could benefit from this
(e.g. LSP), but might require other changes to accommodate.
- Invalidation of the cache needs to be controllable. Using weak tables
is an acceptable invalidation policy, but it shouldn't be the only
one.
- I don't think the story around `hash_fn` is completely thought out. We
may be able to have a good default hash_fn by hashing each argument,
so basically a better 'concat'.
runtime(doc): documentation updates
This is a collection of various improvements to the help pages
closesvim/vim#12790596ad66d1d
Co-authored-by: Christian Brabandt <cb@256bit.org>
Co-authored-by: Houl <anwoku@yahoo.de>
Co-authored-by: Doug Kearns <dougkearns@gmail.com>
Co-authored-by: Adri Verhoef <a3@a3.xs4all.nl>
Problem: cannot distinguish Forth and Fortran *.f files
Solution: Add Filetype detection Code
Also add *.4th as a Forth filetype
closes: vim/vim#1225119a3bc3add
Don't remove filetype files from Vim patches:
- filetype.vim, script.vim, ft.vim usually contain useful changes
- script.vim and ft.vim don't even have their paths spelled correctly
Co-authored-by: Doug Kearns <dougkearns@gmail.com>
Problem: sidescrolloff and scrolloff options work slightly
different than other global-local options
Solution: Make it behave consistent for all global-local options
It was noticed, that sidescrolloff and scrolloff options behave
differently in comparison to other global-local window options like
'listchars'
So make those two behave like other global-local options. Also add some
extra documentation for a few special local-window options.
Add a few tests to make sure all global-local window options behave
similar
closes: vim/vim#12956closes: vim/vim#126434a8eb6e7a9
Co-authored-by: Christian Brabandt <cb@256bit.org>
Problem: luals returns stricter diagnostics with bundled luarc.json
Solution: Improve some function and type annotations:
* use recognized uv.* types
* disable diagnostic for global `vim` in shared.lua
* docs: don't start comment lines with taglink (otherwise LuaLS will interpret it as a type)
* add type alias for lpeg pattern
* fix return annotation for `vim.secure.trust`
* rename local Range object in vim.version (shadows `Range` in vim.treesitter)
* fix some "missing fields" warnings
* add missing required fields for test functions in eval.lua
* rename lsp meta files for consistency
* docs(options): take ownership of options.txt
- `src/nvim/options.lua` is now the source of truth
- generate runtime/lua/vim/_meta/options.lua
* fixup! zeer comments
* fixup! zeer comments (2)
* fixup! re-enable luacheck
* fixup! regen
Problem:
- Notifications are missing from `lsp.Methods`.
- Need a way to represent `$/` prefixed methods.
Solution:
- Generate notifications.
- Use "dollar_" prefix for `$/` methods.
Now that we "own" builtin.txt, we cant remove the repetitive mention of
Vimscript's UFCS syntax. It's noisy to mention this for each function,
and it's also not a Vimscript feature that should be encouraged.
Also change the builtin.txt heading to "NVIM REFERENCE MANUAL", which
indicates when a help file is Nvim-owned.
- eval.lua is now the source of truth.
- Formatting is much more consistent.
- Fixed Lua type generation for polymorphic functions (get(), etc).
- Removed "Overview" section from builtin.txt
- Can generate this if we really want it.
- Moved functions from sign.txt and testing.txt into builtin.txt.
- Removed the *timer* *timers* tags since libuv timers via vim.uv should be preferred.
- Removed the temp-file-name tag from tempname()
- Moved lueval() from lua.txt to builtin.txt.
* Fix indent
* fixup!
* fixup! fixup!
* fixup! better tag formatting
* fixup: revert changes no longer needed
* fixup! CI
---------
Co-authored-by: zeertzjq <zeertzjq@outlook.com>
When signature is a bit long or there are too many tags, the tags appear
before the signature's line. Don't include the line with tags in the
previous function' docs.
Also fix lint warnings.
* docs(lua): teach lua2dox how to table
* docs(lua): teach gen_vimdoc.py about local functions
No more need to mark local functions with @private
* docs(lua): mention @nodoc and @meta in dev-lua-doc
* fixup!
Co-authored-by: Justin M. Keyes <justinkz@gmail.com>
---------
Co-authored-by: Justin M. Keyes <justinkz@gmail.com>
Problem:
Lua functions that return multiple results are declared by using
multiple `@return` docstring directives. But the generated docs don't
make it obvious what this represents.
Solution:
- Generate a "Return (multiple)" heading for multiple-value functions.
- Fix `@note` directives randomly placed after `@return`.
Problem: some API functions that check textlock (usually those that can change
curwin or curbuf) can break the cmdwin.
Solution: make FUNC_API_CHECK_TEXTLOCK call text_locked() instead, which already
checks for textlock, cmdwin and `<expr>` status.
Add FUNC_API_TEXTLOCK_ALLOW_CMDWIN to allow such functions to be usable in the
cmdwin if they can work properly there; the opt-in nature of this attribute
should hopefully help mitigate future bugs.
Also fix a regression in #22634 that made functions checking textlock usable in
`<expr>` mappings, and rename FUNC_API_CHECK_TEXTLOCK to FUNC_API_TEXTLOCK.
Problem:
In the generated docs HTML there is too much whitespace before/after `<pre>`
blocks.
- In the old layout (fixed-width), all text in `.old-help-para` is formatted as
`white-space:pre`.
- In the new layout, when `<pre>` is at the end of a `<div>`, the margins of
both are redundant, causing too much space.
Solution:
- In the old layout, always remove `<pre>` margin.
- In the new layout, disable `<pre>` margin if it is the last child.
Enforce consistent terminology (defined in
`gen_help_html.lua:spell_dict`) for common misspellings.
This does not spellcheck English in general (perhaps a future TODO,
though it may be noisy).
- quickstart
- mark lsp.txt as `new_layout`
- remove lsp-handler documentation for notifications: they don't have
handlers because they don't have server responses.
Add automatic refresh and a public interface on top of #23736
* add on_reload, on_detach handlers in `enable()` buf_attach, and
LspDetach autocommand in case of manual detach
* unify `__buffers` and `hint_cache_by_buf`
* use callback bufnr in `on_lines` callback, bufstate: remove __index override
* move user-facing functions into vim.lsp.buf, unify enable/disable/toggle
Closes#18086
