feat: language support in ---@usage

[numToStr]

tl;dr: vimdoc syntax for language support in code-block is experimental and also not backward compatible. So, this might get delayed until nvim 0.9 is released. #65 (comment)

---

This adds support for associating a language for ---@usage tag which defaults to lua for every code block unless explicitly defined using the syntax below.

Emmylua

• Single line

---@usage [lang] `<code>`

• Multiline

---@usage [lang] [[
---
---@usage ]]

Help (vimdoc)

>{lang}

code...

<

Screenshot

[clason]

Don't do that! This is not backwards compatible (yet), as the legacy syntax file will not recognize these marked code blocks. The updated parser and queries are not bundled in core yet, either, and treesitter highlighting is not enabled by default (which is currently not planned).

You need to wait until Neovim 0.9 is released with official support (and even then, this drops compatibility with Neovim 0.8 and earlier).

[numToStr]

Thanks for the heads up @clason. I was tempted to add this as it makes help doc so much nicer to look at 😆. But I'll hold this untill 0.9 is released.

Although, I could make this opt-in for now. So if user wants to add a lang then they can, otherwise it will remain as it is. Emmylua syntax would look like this

• Single line

---@usage [lang] `<code>`

• Multiline

---@usage [lang] [[
---
---@usage ]]

[clason]

Hmm. Going by experience, if you hand people a gun, they will fire it at their feet at the earliest opportunity.

Yes, definitely make it opt-in (in any case, someone may want to give usage in Vimscript or Fennel), but even that I'd hold off until support is merged in master. After all, it may turn out that we need to abandon this or go back to the drawing board if it turns out that this breaks our tooling somewhere.

[numToStr]

After all, it may turn out that we need to abandon this or go back to the drawing board if it turns out that this breaks our tooling somewhere.

Yup, sounds fair. I'll put this on hold then and see how things are developing.

[numToStr]

It seems that the plugins have started to use this wbthomason/packer.nvim#1174 and there is a plan to backport the code block highlighting to the stable branch neovim/neovim#21514 so considering all this I am going ahead with merging the changes, but the release will only happen after backport PR is merged.