LuaDoc parsed incorrectly

[LastTalon]

Describe the bug
Code with LuaDoc comments are being parsed in some way that is incorrect. I assume as some sort of other annotation that is not LuaDoc.

Expected behavior
Because LuaDoc is in the comments and is not Lua code I would expect that it wouldn't be parsed and marked as a warning.

Screenshots

Environment (please complete the following information):

• OS: Windows
• Client: VSCode

[LastTalon]

As a workaround I've disabled undefined-doc-param and undefined-doc-name in settings. However, this doesn't prevent the odd highlighting.

[sumneko]

The original annotation syntax is three horizontal bars. I can provide an option to turn off the compatibility of the annotation syntax with two horizontal bars. However, syntax coloring is static and cannot be turned off.

[LastTalon]

My code is not meant to be EmmyLua and I'm not familiar with that. I'm using LDoc with LuaDoc comments. Previous versions didn't have this syntax highlighting or problem. I've reverted to an earlier version to avoid this issue.

I'm not sure that its ideal to have both of these behaviors in the same extension.

[serg3295]

If I'm not mistaken, LuaDoc does not support parameters type (name only).
-- @param name comment
Thus, the -- @param in LuaDoc is not equivalent to the ---@param in EmmyLua.
IMO, using always sequence of three minus signs for EmmyLua syntax (as default) will allow to avoid conflict with LuaDoc.

In turn, -- @param will be considered as comment and LuaDoc interprets it correctly

[hinell]

EmmyLua is incompatible with LDoc and LuaDoc .

I think doc annotations parser should be configurable or dropped otherwise from this LSP.

I'm having issues with --- @module xyz tag - it always shows warning that I miss module name, when it's provided;

I would prefer to use LDoc anyway.

[hinell]

I made a feature request to make it possible to disable EmmyLua engine: #2369

[linrongbin16]

Is there a way to generate docs by ldoc from lua-language-server annotations?

I have met an error:

fileios.lua:16: ?: 'class' cannot have multiple values; {commons.FileLineReader,module}

Looks like ldoc doesn't recognize @class tag.

[hinell]

@linrongbin16 See my reply: #2391

[linrongbin16]

hi @hinell , thanks for reply.

1. in Diagnostics: allow disabling EmmyLua luadoc annotations #2391 reply, it seems there's a way to disable EmmyLua engine, I guess if I could disable EmmyLua engine, so I can write the annotations with -- prefix, then I can generate documents with ldoc? But in that way, I have to rewrite the whole project of mine.
2. actually all I want is auto-generate API references for my lua project (ldoc is not a must). I found there's an example here: LuaLs wiki - export docs, but after I tried it, I found the generated markdown file is not the style I want.... I guess I'm not going to use it.

[linrongbin16]

EmmyLua is incompatible with LDoc and LuaDoc .

I think doc annotations parser should be configurable or dropped otherwise from this LSP.

I'm having issues with --- @module xyz tag - it always shows warning that I miss module name, when it's provided;

I would prefer to use LDoc anyway.

@hinell now I'm fixing the @module error by disable the error in the .luarc.json:

{
  "diagnostics.disable": ["luadoc-miss-module-name"],
}

---

update: seems there's no way to use ldoc to generate docs for lua-language-server annotations, they're not compatible at all.

[hinell]

update: seems there's no way to use ldoc to generate docs for lua-language-server annotations, they're not compatible at all.

Yes. I've also been looking for a good Lua API doc generator, but there none. We have a lemmy-help but it's quite limited.

1. There is no full fledged and flexible api generator for LuaDoc (not just LDoc or EmmyLua) comments
2. LuaCats from Lua_ls isn't that bad (save to few flaws) but there is no sane doc generator;
3. Lua_ls doc generator is a bit overkill
4. If I have enough time I probably can write a universal Tree-Sitter-based extractor for various types of LuaDoc, but it ain't gonna happen soon; if anyone knows how to write TS grammars ping me out we can collaborate on that