Regular comments (i.e. `-- comment`) shouldn't be included in documentation

[tmillr]

How are you using the lua-language-server?

NeoVim

Which OS are you using?

MacOS

What is the issue affecting?

Hover

Expected Behaviour

-- THIS IS NOT A DOC COMMENT
---This is a doc comment
local a = ''

Hovering a should show: This is a doc comment.

Actual Behaviour

-- THIS IS NOT A DOC COMMENT
local a = ''

Hovering a shows:

THIS IS NOT A DOC COMMENT
This is a doc comment

Reproduction steps

See above ^^^

Additional Notes

No response

Log File

No response

[TetraTheta]

This is really annoying me because I use comment to visually separate 'sections' like this:

--[[
##################
#     CONFIG     #
##################
]]
--
--
local function _MyFunction()
  -- This function doesn't have any documentation defined
end

But when I hover on _MyFunction(), I get unwanted documentation stuff

Something like this:

##################

CONFIG

##################

This is definitely not what I want.

In C#, documentation comment and normal comment have different 'syntax'. All documentation comment start with ///, and any normal comments start with // aren't included to the documentation.

In Java, documentation comment and normal comment are separated. Documentation comments are within /** docs */ while normal comments are within /* comments */. Same thing applies to JSDoc too.

---

Here is my suggestion.

Documentation should only consider comments start with --- (or ///) as documentation comment.

--- documentation
---documentation
-- comment
--comment
---------------------------------------- comment
----------------------------------------comment
--- -documentation
--- - documentation

--[[
doc:
documentation
]]

[flrgh]

Changing this behavior would be pretty disruptive IMO given it's been this way for so long. If this change is made I hope the current behavior can be retained via configuration.

[tmillr]

Changing this behavior would be pretty disruptive IMO given it's been this way for so long. If this change is made I hope the current behavior can be retained via configuration.

Maybe that's true, but this behavior makes little sense and is unprecedented (when considering other languages). In the environments I work in (e.g. Neovim and Neovim plugins), I don't see anyone depending on this. The whole point of having separate doc comments (which are not apart of standard Lua syntax) is for regular comments to not get picked up by the LSP. The whole point is this very distinction. I don't want my -- TODO comments to be visible in documentation, nor any other code comments. With the way it is currently, there is no way to comment on code without it being visible in documentation unless you place the comment far away from the relevant code. This is not good and not normal (and not how any other language handles documentation comments). It's definitely a bug in my opinion.

The only place I can think of where the current behavior might make sense is when you have a comment sandwich or something like this:

...
---doc comment
-- doc comment
---doc comment
...

[tmillr]

Changing this behavior would be pretty disruptive IMO given it's been this way for so long. If this change is made I hope the current behavior can be retained via configuration.

Can you provide an example of some public code which relies on this?

[MisteryDuck]

this has been bothering me for so long, too. It doesn't matter if that's the default behavior, just to have a toggle to change it would be nice

[tomlau10]

https://github.com/LuaLS/lua-language-server/issues/2764#issuecomment-2254913864

---[[
  documentation
]]

• This example is actually INVALID in lua, because the block comment is always prefixed with 2 dashes only => --[[
• When you write ---[[, it will becomes a single line comment. Because when parsing the line, the -- is not immediately followed by a [[
  • and then the next line (documentation) will just be parsed as code, but not part of the block comment.
  • same for the final ]] in the next next line

So if the proposed documentation way is to only consider lines that started with exactly 3 dashes ---, then there is no way to use block comment style. It can only be --[[ 😕

[tomlau10]

I don't want my -- TODO comments to be visible in documentation

I see your point. I never used the --doc to generate documentation before, and I just tried to use that in my project. In the generated markdown file, there are quite a number of TODO / FIXME in the output which I definitely don't want to include them if I am really creating a documentation file 🙈

[TetraTheta]

So if the proposed documentation way is to only consider lines that started with exactly 3 dashes ---, then there is no way to use block comment style. It can only be --[[ 😕

If then, we can consider a comment starts with 'marker' like docs: (or [docs]) as documentation comment and provide a config option for changing the marker.

---documentation
--- documentation
--- - documentation
--- -documentation
--[[
docs: documentation
]]
--docs: documentation
-- docs: documentation
--[[
docs:
documentation
]]

This... would be complicated, but to provide a way to define documentation from multi-line string, I think this would be the only way to do.

---

To simplify those things, the 'marker' can be defined to - and docs: to support both --- and --[[docs: situation.

[tomlau10]

From what I observed, the current behaviour is to treat continuous comments before the function / field as candidate documentation text. And during hover previewing, there are some more postprocessing here: https://github.com/LuaLS/lua-language-server/blob/2a48dee3f216992150f05e288fa6a439c864f0b8/script/core/hover/description.lua#L90-L99

I tried to add some print() there, the -- --[[/]] are already stripped from the text, i.e. the value of comment string do not have the prefix -- / --[[ or the suffix ]]

-- a
---b
--[[
a
b
c
]]
function d() end

output:

=====start
 a
=====finish
=====start
-b
=====finish
=====start
a
b
c

=====finish

---

To simplify those things, the 'marker' can be defined to -

This seems a great idea 👍 With the fact that --[[ / ]] are all stripped beforehand, actually we don't need a docs: marker, we can just use - as well! We can write it as:

--[[-
a
b
c
]]

output:

=====start
-
a
b
c

=====finish

• this way the comment value will be -\na\nb\nc\n => can still use the marker (which is a single dash -) logic to check with it 😄
• we can just have a config option say only treat triple dash comment as doc true/false
  • default = false for backward compatibility
  • set to true for new behaviour, and the logic is skipping comment lines that do not start with -, or start with 2 dashes (which means this line has at least 4 dashes ----you want this line to be comment but not doc)

---

some pseudo code

local function normalizeComment(comment, suri) 
  if not comment then
    return nil
  end
  if <config is true>
  and (comment:sub(1, 1) ~= '-' or comment:sub(1, 2) == '--')
  then
    -- skip as not exactly 3 dashes
    return nil
  end
  ... <the rest logic>

[TetraTheta]

we don't need a docs: marker, we can just use - as well!

(I'll call 'documentation comment' as LuaDoc for better understanding)

I'm not sure if firstcomer will understand --[[- will start LuaDoc intuitively. If official documentation includes some possible usage, I agree with that for using - only because people are told how to define LuaDoc by the documentation.

---

treat continuous comments before the function / field as candidate documentation text

I use GLuaFixer for linting/formatting, but I can't configure it to preserve blank line that I put intentionally. So, unfortunately, I can't put blank line to prevent LuaLS to treat non-LuaDoc comment as LuaDoc comment because those blank lines will be stripped out. :(

Before formatting:

-- my comment

local function a()
end

After formatting:

-- my comment
local function a()
end

Thank you for the detailed inspection and explanation!

[tomlau10]

If official documentation includes some possible usage

I just searched some existing documentation in the meta/ sub modules, it seems that all LuaDoc start with --- each line, and never use --[[ style 😂

For example this file: https://github.com/LuaCATS/love2d/blob/dad72a7eae31f35bf4c6529e5b81f6187b5b7377/library/love.lua

I guess more LuaDoc example usages can be found here: https://github.com/LuaCATS

[TetraTheta]

it seems that all LuaDoc start with --- each line, and never use --[[ style 😂

Great news! If then, we can just use - only for the 'marker'. I was worried about --[[-styled LuaDoc was used quite often, but it isn't!

Thank you for the research! :)

[firas-assaad]

Changing this behavior would be pretty disruptive IMO given it's been this way for so long. If this change is made I hope the current behavior can be retained via configuration.

Can you provide an example of some public code which relies on this?

I've been using -- in my code almost exclusively for functions. I agree with you that --- is much more logical and is in line with other languages, but I'd still call it a disruptive change because that's the way it worked before and I'm sure there are other people who depend on it.

Personally I don't mind updating my own code, but it's not always easy. If it's possible to make it configurable without complicating the LuaLS code then that would be ideal, even if it's a transitional thing and -- is no longer the default.

But I don't feel strongly about it either.

[CppCXY]

If used as a trailing comment, --- will appear very redundant:

[tomlau10]

I think it should be configurable, say there is a config Lua.doc.strictTripleDash = <boolean> Which means only consider comments that are strictly prefixed with 3 dashes as LuaDoc, not 2, neither 4 or more

• default is false => current behaviour, so it doesn't break anything
• set to true => new behaviour

Then everyone will be happy 😄

[tmillr]

If used as a trailing comment, --- will appear very redundant:

Using trailing comments for documentation is unusual in my opinion. Documentation comments usually go just above the thing that they are documenting. Also, it's only 1 extra character.

[flrgh]

Can you provide an example of some public code which relies on [the current behavior]?

I rely on this behavior because I work on lots of code that predates LuaLS and is not annotated with types. Documenting code with comments is nothing new, so it follows that code that is not annotated (in the LuaLS sense of the term) often has some form of informal doc string comment:

-- queries the database and returns a table of results or nil+error
-- NOTE: this can raise an exception if there's a network error
function fetch_rows(table_name, opts)
  -- [...]
end

I can't realistically expect to open a 10k line PR against a codebase like kong touching every Lua file and blowing up the git history just to make the codebase suit my personal development workflow. Since LuaLS does not currently differentiate between -- and ---, I can see doc strings like this example in my editor, which is very useful.

At a more philosophical level, I think the fact that LuaLS offers a lot of utility to the developer out-of-the-box without first requiring 100% buy-in to its specific flavor of annotation syntax* is a large factor in its success, so I hope we can preserve this quality.

---

* Throughout the history of Lua there have been several unsuccessful attempts at creating a widely-adopted type def/annotation standard for the language. As a result, nobody in my corner of the Lua-verse is excited to hear "check out this shiny new Lua dev tool" when it is immediately followed by "...just update all of your files to use this new annotation syntax to get started."

[sumneko]

I have also pondered this issue and plan to provide an option for it in the future, allowing the choice to switch to recognizing only ---.

[idbrii]

Some other examples of public projects not using ---. Maybe these would make good test cases?

Slab is a GUI system for love2d and its API uses block comments:

--[[
	Update

	Updates the input state ...

Batteries is a utility library for love2d and uses -- comments:

--convert hsv to rgb
--all components are 0-1, hue is fraction of a turn rather than degrees or radians
function colour.hsv_to_rgb(h, s, v)

baton is an input library for love2d and uses -- comments:

-- gets the value of a control or axis pair with deadzone applied
function Player:get(name)

Glad to hear it'd be an option!