feature request: attach a `reason` parameter to `@nodiscard`

[thacuber2a03]

[!NOTE] I couldn't find an issue for this. sorry if there's a duplicate.

I propose updating the @nodiscard annotation to add a "reason" as to why not discard the value:

---@nodiscard [<reason>]

this would mirror Rust's #[must_use = "reason"] annotation.

example:

---Creates a new class that inherits from this one.
---@return Class
---@nodiscard This method returns the new class; it's pointless to immediately discard it.
function Object:extend()
  -- ...
end

discarding the output would then display the warning:

* [warning][Lua Diagnostics.][discard-returns]
  The return values of this function cannot be discarded:
  This method returns the new class; it's pointless to immediately discard it.

note the colon at the end of "discarded". if not given a reason, it would fall-back to the usual message, with "discarded" ending with a dot and no further explanation (yes, I'm aware that reason in the Object:extend example isn't exactly... professional 😅)

[thacuber2a03]

~~I'm up for implementing this feature, it would be cool to try haha~~ nevermind, I'm not used to the code

[tomlau10]

I'm up for implementing this feature, it would be cool to try haha

Actually this might be a good first issue 😂

There is an almost identical feature, but for @deprecated [reason]. Basically:

• the reason is stored in the comment field of a doc.deprecated parser.object
• and then vm.getDeprecated() is designed to return the binded doc.deprecated object of any parse.object (if there is any) https://github.com/LuaLS/lua-language-server/blob/759e8fbcce257a65ab469a49d5878286e9e7e089/script/vm/doc.lua#L130-L187
• finally this doc.deprecated is used in script/core/diagnostics/deprecated.lua https://github.com/LuaLS/lua-language-server/blob/759e8fbcce257a65ab469a49d5878286e9e7e089/script/core/diagnostics/deprecated.lua#L67-L69

---

I believe for @nodicard (doc.nodiscard), there is already a comment field parsed as well. So the only thing left is to refactor the vm.isNoDiscard() => vm.getNoDiscard():

• when doing memoization, cache the actual doc.nodiscard object into value._nodiscard
• and then return it directly if it exists, just like the local function getDeprecated() and vm.getDeprecated() in the above https://github.com/LuaLS/lua-language-server/blob/759e8fbcce257a65ab469a49d5878286e9e7e089/script/vm/doc.lua#L271-L312
• finally use its comment field (if any) to format the message in the script/core/diagnostics/discard-returns.lua https://github.com/LuaLS/lua-language-server/blob/759e8fbcce257a65ab469a49d5878286e9e7e089/script/core/diagnostics/discard-returns.lua#L22-L26

[CppCXY]

or you can choose the emmylua_ls(dev version support)

[thacuber2a03]

not sure... some annotations here aren't compatible with EmmyLua, and I don't quite want to have two language servers installed at a time, plus, I'm used to this one