Update mini.doc to LuaCATS

[S1M0N38]

Contributing guidelines

• I have read CONTRIBUTING.md
• I have read CODE_OF_CONDUCT.md

Module(s)

mini.doc

Description

LuaLS/lua-language-server is the most used implementation Language server for Lua. One of its features are annotations implemented as LuaCATS (Lua Comment And Type System). As stated in their docs:

LuaCATS annotations are no longer cross-compatible with EmmyLua annotations as of v3

The current implementation of mini.doc try to parse EmmyLua-like annotations. Compare to EmmyLua annoation, LuaCATS define a precise specification for annotation.

For instance, the mini.doc :help section mentions:

Hooks for sections which supposed to have "type-like" data ('@field',
'@param', '@return', '@type') automatically enclose first found
"type-like" word and its neighbor characters in '(<type>)' (expect
false positives). Algorithm is far from being 100% correct ...

Conversely, the @param annotation supported by LuaLS/lua-language-server is explicitly defined as:

---@param <name[?]> <type[|type...]> [description]

In this format, the type directly follows the parameter name, eliminating the need for heuristic searches for the type. Additionally, this format simplifies the integration of user-defined types into help.txt.

---

While I could develop my own hooks to adhere to the LuaCATS specification (skill permitting), I believe that aligning with a dominant and well-documented standard would be more advantageous for the community.

[echasnovski]

Thanks for the suggestion!

On first glance, this makes sense. Having some strict rules from 'lua-language-server' is good. I'll look into it (not very soon, I am afraid).

[S1M0N38]

I'll give a shot as well. Instead of manually parse annotations line (the one starting with ---) a viable approach is to use the json produce by the command for docs generation

./lua-language-server --doc=path/to/lua/workspace

I know that it's a bit against the mini.doc philosophy (few dependencies as possible, here we depend on lua LSP) but this should ensure perfect annotations parsing. So it "just" remains to convert json to proper vim documentation for :help

[echasnovski]

I know that it's a bit against the mini.doc philosophy (few dependencies as possible, here we depend on lua LSP) but this should ensure perfect annotations parsing. So it "just" remains to convert json to proper vim documentation for :help

No, that is definitely against 'mini.nvim' design. Everything will be parsed without external dependencies.

[echasnovski]

Let's use this as a tracking issue to gather other similar suggestions for 'mini.doc' improvements that are related to LuaCATS specifications.

In particular:

• Omit ---@field private and ---@field protected fields in the output. See [mini.doc] Support hiding fields marked as private/protected #668 for more info.
• Support multiple ---@return statements to behave similarly to multiple ---@param and indicate several returned values (instead of currently suggested ...). For more info see docs(icons): update get documentation to document all return values #1027.
• Make ---@module modify function name by replacing (where it makes sense) the returned variable name (usually M) with module name. For more info and examples see [mini.doc] Add support for ---@module annotations #1227.