Problem:
Many color schemes assume the Comment hl group is dim text and use it
for secondary text, decorations, or parts of UI. This is true for many
color schemes but not all.
Solution:
Introducing a new highlight group with a more specific meaning, similar
to Underlined or Ignore.
The new group links to Comment by default so the behavior is unchanged
for color schemes that don't define it.
Problem: Unable to emit a message with arbitrary kind.
Solution: Add a "kind" opts field to nvim_echo().
Use it to set the "list_cmd" kind for vim.show_pos().
Problem: Unpaired marks are shown with `filter.extmarks == true`, which
should only return visible highlights. Misleading `end_col`
included in `inspect_pos()` for unpaired mark; it is set to
`start_col + 1` which would be a visible highlight, which it is
not. Custom "is_here" filter used to get extmarks overlapping a
position.
Solution: Exclude unpaired highlight extmarks with `filter.extmarks == true`.
Set `end_col` to `start_col` for an unpaired mark. Supply
appropriate arguments to nvim_buf_get_extmarks() to return
overlapping extmarks; exclude marks whose end is at `{row, col}`
with `filter.extmarks == true`.
Problem: It is not obvious if a treesitter highlight priority shown in
`:Inspect` is higher or lower than the default.
Solution: Also print default priority (`vim.hl.priorities.treesitter`).
Add padding for better readability.
Problem: `:Inspect` does not show priority for treesitter highlights,
leading to confusion why sometimes earlier highlights override later
highlights.
Solution: Also print priority metadata if set.
An implication of this current approach is that `NVIM_API_LEVEL` should be
bumped when a new Lua function is added.
TODO(future): add a lint check which requires `@since` on all new functions.
ref #25416
- Added `@inlinedoc` so single use Lua types can be inlined into the
functions docs. E.g.
```lua
--- @class myopts
--- @inlinedoc
---
--- Documentation for some field
--- @field somefield integer
--- @param opts myOpts
function foo(opts)
end
```
Will be rendered as
```
foo(opts)
Parameters:
- {opts} (table) Object with the fields:
- somefield (integer) Documentation
for some field
```
- Marked many classes with with `@nodoc` or `(private)`.
We can eventually introduce these when we want to.
Problem:
The documentation flow (`gen_vimdoc.py`) has several issues:
- it's not very versatile
- depends on doxygen
- doesn't work well with Lua code as it requires an awkward filter script to convert it into pseudo-C.
- The intermediate XML files and filters makes it too much like a rube goldberg machine.
Solution:
Re-implement the flow using Lua, LPEG and treesitter.
- `gen_vimdoc.py` is now replaced with `gen_vimdoc.lua` and replicates a portion of the logic.
- `lua2dox.lua` is gone!
- No more XML files.
- Doxygen is now longer used and instead we now use:
- LPEG for comment parsing (see `scripts/luacats_grammar.lua` and `scripts/cdoc_grammar.lua`).
- LPEG for C parsing (see `scripts/cdoc_parser.lua`)
- Lua patterns for Lua parsing (see `scripts/luacats_parser.lua`).
- Treesitter for Markdown parsing (see `scripts/text_utils.lua`).
- The generated `runtime/doc/*.mpack` files have been removed.
- `scripts/gen_eval_files.lua` now instead uses `scripts/cdoc_parser.lua` directly.
- Text wrapping is implemented in `scripts/text_utils.lua` and appears to produce more consistent results (the main contributer to the diff of this change).
* 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>
feat(lsp)!: change semantic token highlighting
Change the default highlights used, and add more highlights per token.
Add an LspTokenUpdate event and a highlight_token function.
:Inspect now shows any highlights applied by token highlighting rules,
default or user-defined.
BREAKING CHANGE: change the default highlight groups used by semantic
token highlighting.
