Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update mini.doc to LuaCATS #666

Open
2 tasks done
S1M0N38 opened this issue Jan 23, 2024 · 4 comments
Open
2 tasks done

Update mini.doc to LuaCATS #666

S1M0N38 opened this issue Jan 23, 2024 · 4 comments
Labels
feature-request Request for a feature to existing module mini.doc

Comments

@S1M0N38
Copy link

S1M0N38 commented Jan 23, 2024

Contributing guidelines

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.

@S1M0N38 S1M0N38 added the feature-request Request for a feature to existing module label Jan 23, 2024
@echasnovski
Copy link
Owner

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
Copy link
Author

S1M0N38 commented Jan 23, 2024

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
Copy link
Owner

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
Copy link
Owner

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:

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
feature-request Request for a feature to existing module mini.doc
Projects
None yet
Development

No branches or pull requests

2 participants