LuaDoc parsed incorrectly

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

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

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.

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.

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

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.~~

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

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.

@linrongbin16

@linrongbin16 See my reply: #2391

@hinell

hi @hinell , thanks for reply.

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.
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.

@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 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.

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.

There is no full fledged and flexible api generator for LuaDoc (not just LDoc or EmmyLua) comments
LuaCats from Lua_ls isn't that bad (save to few flaws) but there is no sane doc generator;
Lua_ls doc generator is a bit overkill
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

I have written lunardoc as work done on this issue. It can generate a Lua taglet and a MediaWiki doclet, but much more work needs to be done.

Navigation Menu

Repository navigation

LuaDoc parsed incorrectly #392

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

LuaDoc parsed incorrectly #392

Description

Activity

LastTalon commented on Feb 16, 2021

sumneko commented on Feb 18, 2021

LastTalon commented on Feb 18, 2021

serg3295 commented on Feb 18, 2021

hinell commented on Oct 14, 2023

hinell commented on Oct 14, 2023

linrongbin16 commented on Dec 13, 2023

hinell commented on Dec 13, 2023

linrongbin16 commented on Dec 13, 2023

linrongbin16 commented on Dec 13, 2023

hinell commented on Dec 14, 2023

zm-develops commented on Apr 4, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions