Diagnostics: allow disabling EmmyLua luadoc annotations

[hinell]

How are you using the lua-language-server?

NeoVim

Which OS are you using?

Linux

What is the issue affecting?

Annotations

Expected Behaviour

Sorry for opening a "bug". This is actually a feature request. My proposal at #2369 was left unanswered.

I request to make it possible to disable emmylua specific luadoc annotations project-wide or file-wise (e.g. per file) entirely.

Motivation:

• Currently (as of lua-language-server v3.7.0):
  • Can't disable emmylua annotations by using diagnostics config
  • Can't disable them from "settings" either
• Not everyone is using emmylua; some are using incompatible tools like LDoc to generate docs

[Mark-LaCroix]

Yes! I am using LDoc and was confused that this extension doesn't support it, but also that it seems to force something else that I don't use.

I had assumed LDoc (for all its faults) was the currently preferred (only?) way to generate Lua documentation from code, and could also be used for code hinting. Is EmmyLua more common? Better? I'd not heard of it until now (which I'm sure is on me).

[CppCXY]

So let me tell you a story, the author of emmylua didn't hear of LDoc when he developed emmylua, and lua didn't have a decent plugin or IDE at the time. Later, sumneko lua introduced emmylua doc as the basic type system, and extended it to become today's LuaCats doc.
Since this plugin is so widely used, it has become the de facto standard.

We don't develop lua plugins to fit the needs of the community, but to meet our own development needs, and emmylua doc is more in line with actual development needs than LDoc.

I'm not urging you to change your doc format, but the odds are we won't provide support for LDoc.

[hinell]

I'm not urging you to change your doc format, but the odds are we won't provide support for LDoc.

Nobody is asking to add support for LDoc. Just allow us to disable LuaCats entirely in files or projects where LDoc is used.

[Mark-LaCroix]

So let me tell you a story,

Classic. 😆

I'd love LDoc support, but I'm not asking for it. Like the OP says, just an option to disable EmmyLua for people not using it would be nice.

I'm not personally tied to anything. If EmmyLua can produce HTML documentation then I'd be happy to switch. Is that possible?

[hinell]

@Mark-LaCroix Yeah, it's not the first time I see on github how maintainers misread OP.

If EmmyLua can produce HTML documentation

EmmyLua wasn't intended to generate docs AFAIK. That's the half of the problem though.

[CppCXY]

LuaCats doc support is not pluggable, it is the foundation of the whole plugin, all diagnostics and parsing are tied to it, so I think this is unlikely.
As for generating docs, lua-ls can be executed on the command line to generate docs in a format you can use, see the wiki for details.

[Mark-LaCroix]

@Mark-LaCroix Yeah, it's not the first time I see on github how maintainers misread OP.

That's FOSS for ya. I know from personal experience that it's hard to hear a request from a user and not assume that it's asking for more than it says. Beggars can't be choosers, and most users are beggars! It's a common and perfectly understandable misread.

lua-ls can be executed on the command line to generate docs in a format you can use, see the wiki for details.

Cool! It looks like it only supports Markdown and JSON, leaving the "last-mile" of providing functional UX to the user, and has no configuration options. Not anywhere close to a suitable LDoc competitor, but as has been said, that's not its goal.

LuaCats doc support is not pluggable, it is the foundation of the whole plugin

I guess, but I'm not using it and the plugin still works great for me in all other ways. I don't need to "unplug" it, just hide it. In the pantheon of "won't fix" this one is odd. LDoc isn't necessarily the answer (ideally it's to build out the existing docs generation feature), but I find it hard to believe that the intent of maintainers is to force users to pick between code-hinting and proper docs generation.

If someone where to propose a PR to address this in one way or another, would it be rejected on design grounds?

[sumneko]

My idea is to add an option: Only when the few characters at the beginning of the file are ---@meta, the LuaCats analysis will be performed.

But I am busy with other things recently, and you are welcome to propose PR.

[CppCXY]

The price of disabling it is to use it.
I think that when you look at the source code yourself and use it to make such changes, maybe you won't want to change it.

[hinell]

I observe that LuaCats repo has widely adopted EmmyLua tags.

Given that it's hardwired, is it possible to modify behavior of lua-lsp so as to suppress errors for a set of LDoc tags at low cost?

There is quite short list of tags on their LDoc web site. The major problem I face with lua-lsp tags currently is the overhelming list of errors for non-compatible tags (.e.g @module)

If someone where to propose a PR to address this in one way or another, would it be rejected on design grounds?

@Mark-LaCroix Well given that lua isn't a typed language LuaDocs are essential to a LSP implementation. Meaning that this may require a completely new language server implementation with tweakable tags... But if it can be done in a PR, well that would be nice.

[C3pa]

I've got a feeling this issue might be a xy problem. Is the motivation for disabling LuaCATS annotations to have a way to generate documentation (in some web-compatible format?) from source code? Why even use LuaLS in that case? What do you get from LuaLS if you disable its type annotation system?

[hinell]

@C3pa Well there is no way to suppress errors arising from incomptible luadoc tags.

Why even use LuaLS in that case?

That's my point above. It might require re-implementation of the entire LSP.

[C3pa]

I am still not getting your point. What features of the LSP are left after its type annotation system is disabled (if the type system potentially could be disabled)?

[hinell]

Feel free to reopen/ping this issue in case of PR or new LSP. Thanks.

[linrongbin16]

hi, not sure if I understand correctly, so now we have a way to disable the EmmyLua engine ? Does that mean we can both use ldoc to generate docs, and have LuaLs annotations working together?

Or is there a doc tool to auto-generate docs from lua-language-server annotations?

I also tried the LuaLs wiki - export docs, but the generated markdown docs are not good looking to me, not sure if there's a way to configure the style.

[CppCXY]

hi, not sure if I understand correctly, so now we have a way to disable the EmmyLua engine ? Does that mean we can both use ldoc to generate docs, and have LuaLs annotations working together?

The emmylua doc parser is the basis for sumneko lua, and cannot be disabled.

Or is there a doc tool to auto-generate docs from lua-language-server annotations?

luals can generate the doc in json format, and then process it yourself

[linrongbin16]

hi, not sure if I understand correctly, so now we have a way to disable the EmmyLua engine ? Does that mean we can both use ldoc to generate docs, and have LuaLs annotations working together?

The emmylua doc parser is the basis for sumneko lua, and cannot be disabled.

Or is there a doc tool to auto-generate docs from lua-language-server annotations?

luals can generate the doc in json format, and then process it yourself

got it, thanks for reply.

[linrongbin16]

hi, not sure if I understand correctly, so now we have a way to disable the EmmyLua engine ? Does that mean we can both use ldoc to generate docs, and have LuaLs annotations working together?

The emmylua doc parser is the basis for sumneko lua, and cannot be disabled.

Or is there a doc tool to auto-generate docs from lua-language-server annotations?

luals can generate the doc in json format, and then process it yourself

I actually tried a lot of solution for auto-generate docs from luals annotations.

there's a maintained sphinx-lua: https://github.com/boolangery/sphinx-lua.

It supports the EmmyLua annotations, but even EmmyLua itself is not enough for LuaLs now.

[CppCXY]

I actually tried a lot of solution for auto-generate docs from luals annotations.

there's a maintained sphinx-lua: https://github.com/boolangery/sphinx-lua.

It supports the EmmyLua annotations, but even EmmyLua itself is not enough for LuaLs now.

new issue please, as I said before, lua-language-server generates documents in json format, so you can build your own documents on top of that, and as far as I know there are no other third-party libraries that support parsing of luacats.