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

Quoted string in the comment #2013

Closed
kosorin opened this issue Mar 17, 2023 · 9 comments
Closed

Quoted string in the comment #2013

kosorin opened this issue Mar 17, 2023 · 9 comments
Labels
bug Something isn't working

Comments

@kosorin
Copy link

kosorin commented Mar 17, 2023

How are you using the lua-language-server?

Visual Studio Code Extension (sumneko.lua)

Which OS are you using?

Linux

What is the issue affecting?

Annotations

Expected Behaviour

Show full comments.

"lorem ipsum" this is ignored
"dolor sit" this is ignored

Actual Behaviour

Comment for the @param that starts with a quoted string ignores everything after the string.

luevscodeerr

Reproduction steps

---"hello world" this is ok
---@param bar any "lorem ipsum" this is ignored
---@param baz any # "dolor sit" this is ignored
local function foo(bar, baz)
end

Additional Notes

No response

Log File

No response

@serg3295
Copy link
Contributor

Double quotes are used for inserting line breaks in the @param and @return

---using the backslash character at the end of the line.\
---In addition, in the lines `@param` and `@return`, you can use construction\
---"line1  \nline2  \n lineI" to break the line. Note the two spaces preceding `\n`
---@param name string "This is a very, very long string that needs to be split  \n into several lines,  \nsay three lines."
---@return boolean  "returns `true` if OK,  \nOtherwise returns `false`."
function foo(name) end

See discussion

@kosorin
Copy link
Author

kosorin commented Mar 17, 2023

So escaping the first double quote fixed it. I was confused because quoted string in the middle of the comment doesn't have to be treated specially:

---@param a any "lorem ipsum" this is ignored
---@param b any \"lorem ipsum" this is shown
---@param c any this "quoted string" is also shown
local function foo(a, b, c) end

@serg3295
Copy link
Contributor

Unfortunately, this feature is not documented in the wiki. It is still "Under Review" 😄

@C3pa
Copy link
Contributor

C3pa commented Mar 20, 2023

Interesting. You can also surround your quoted string in backticks ("`"). This is the result:
image.
In any case, the wiki needs to be updated.

@carsakiller
Copy link
Collaborator

Is someone able to summarize how newlines can be done, so I can add to the wiki? Last I remember hearing, there were drawbacks to each method (double space, backslash, <br>, etc.) so it was omitted from the wiki until a better solution could be implemented.

@sumneko sumneko added the bug Something isn't working label Mar 21, 2023
@serg3295
Copy link
Contributor

serg3295 commented Mar 21, 2023

All these methods are already implemented and work fine.

--- Line1[line_break]
--- LineN
line_break ::= <br> | \ | two trailing spaces

--- First line<br>
--- Second line
function Foo() end

--- First line\
--- Second line
function Foo1() end

-----------------------------------------------------------------
---@param <name[?]> <type[|type...]> [description]
description ::= "Line1  \nLine2  \nLineN" -- two spaces are before \n
or
description ::= "Line1<br>Line2<br>LineN"

---@param a string "a string<br>or another string"
---@param b string "a string  \nor another string"
function Foo2(a, b) end

-----------------------------------------------------------------

---@return <type> [<name> [comment] | [name] #<comment>]
<comment> ::= "Line1  \nLine2  \nLineN" -- two spaces are before \n
or
<comment> ::= "Line1<br>Line2<br>LineN"

---@return string "a string<br>or another string"
---@return string "a string  \nor another string"
function Foo3() end

@C3pa
Copy link
Contributor

C3pa commented Mar 21, 2023

Is someone able to summarize how newlines can be done, so I can add to the wiki? Last I remember hearing, there were drawbacks to each method (double space, backslash,
, etc.) so it was omitted from the wiki until a better solution could be implemented.

My go-to way to insert line breaks in annotation comments is to leave an empty line with just --.

image

@serg3295
Copy link
Contributor

An empty line with -- adds a new paragraph and the window increases significantly vertically.

@carsakiller
Copy link
Collaborator

Updated the wiki

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
bug Something isn't working
Projects
None yet
Development

No branches or pull requests

5 participants