New Wiki section

[serg3295]

There are several functions that are not described in the Wiki because they do not fit the classification of existing sections.
I suggest creating a new section in the Wiki, for example, "Tips & Tricks" in which it will be possible to describe these features.

The candidates are:

1. color support

2. Using VS Code setting to toggling inlay hints.

Quickly toggle inlay hints on/off by configuring editor.inlayHints.enabled. Setting values:

• on — Always show inlay hints
• offUnlessPressed — Hold ctrl+alt / ctrl+option to see inlay hints
• onUnlessPressed — Hold ctrl+alt / ctrl+option to hide inlay hints

Make sure to enable inline hints in the sumneko's extension -> "Lua.hint.enable": true

3. autocompletion

Is there a way to get suggestions when not pressing space though?

You need to set editor.acceptSuggestionOnEnter to off .

4. comments

issue455
issue526

---In description, there is an additional possibility of breaking line\
---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

• or use two spaces at the end of the line

5. something else ...

[carsakiller]

With how many ways there are to create a new line in a comment, I think it is best if we just mention the \ trick:

---First line\
---second line

<br> seems to work for me, but apparently shouldn't? Adding two spaces at the end of the line may be removed when formatting.

[serg3295]

What are your end of line characters set to? Is it possible VS Code is using CRLF while NeoVim is using LF and that is causing some discrepancies?

I use Linux Mint. End of line character in VS Code is LF.

[serg3295]

There shouldn't be 3 or more ways to add a new line, each with their own use cases and drawbacks.

Why not?
Wiki is not a specification of software requirements. If the wiki describes all the functionality provided by the program,
then everyone can choose a more convenient option for themselves.

[serg3295]

My suggestion:

--- description <br> | \ | two trailing spaces

---@param <name[?]> <type[|type...]> [description]
---@return <type> [<name> [comment] | [name] #<comment>]

[description] | <comment> ==>

"Line1 \nLine2 \nLine3" -- two spaces are before \n

or

"Line1<br>Line2<br>Line3"

[carsakiller]

everyone can choose a more convenient option for themselves.

I just don't think it is convenient to have so many different ways. You will either need to memorize what can be used where, or look it up on the wiki frequently. That is why I think there should be an issue created that just reduces it to two, or better, one method for adding a new line in annotations.

[serg3295]

I would also like to have only one method. However, this is difficult to implement.
Let's divide the problem into two parts.

1. Description.
   Currently, <br> tag, backslash and trailing spaces are used for line feed.

2. The long string syntax for param and return has its limitations.

Do you propose to forcibly exclude any of these options?

For different tasks, you may need various solutions.
Emmylua plugin for Intellij IDEA uses <br> tag, neovim and Zerobrane Studio doesn't handle backslash character.
Neovim displays both <br> and \ , but it doesn't need these characters at all.

[carsakiller]

As for the autocompletion in a table, I don't really like the solution of turning off editor.acceptSuggestionOnEnter. I have gotten used to pressing enter to accept suggestions, and I don't want to disable that feature for all of VS Code just so I can get suggestions when writing a table in Lua. I would like to see it fixed in a way that doesn't require an entry in the wiki to use. All other completions are intuitive and easy to get, why do I have to modify my global settings to receive completions in a table?

[serg3295]

You are right, there is no need to document this.

[carsakiller]

Updated wiki to include a Tips page, and a Formatting Annotations page.

[serg3295]

Link in Annotation section is broken:
.md
Annotations are prefixed with ---, like a Lua comment with one extra dash. To learn more, check out Formatting Annotations.