Lines in annotations don't appear in order as written

[Arxareon]

Hey!

Descriptions, comment lines don't appear in order as written under any specified @param and @return description, they are displayed in bulk at the bottom. Also, the main function6object descriptions from the top line are also displayed below param and return value descriptions.

I've been using an older version of the extension (2.6.8), I updated it to see if issues I had with newer versions had been resolved since. Mostly, yes they have been and it works much faster than before so I'd like to stay - but the way I've been annotating stuff, it is a really annoying yet simple issue.

Here's an example (the detailed annotations of a function that gets and returns color values, unpacking them from the table provided):

---Returns the position values used by [Region:SetPoint(...)](https://wowpedia.fandom.com/wiki/API_ScriptRegionResizing_SetPoint) from a position table used by WidgetTools
---@param t? table Table containing parameters to call [Region:SetPoint(...)](https://wowpedia.fandom.com/wiki/API_ScriptRegionResizing_SetPoint) with
--- - **anchor**? [AnchorPoint](https://wowpedia.fandom.com/wiki/Anchors) *optional* — ***Default:*** "TOPLEFT"
--- - **relativeTo**? [Frame](https://wowpedia.fandom.com/wiki/API_CreateFrame#Frame_types)|string *optional* ― Frame reference or name | ***Default:*** UIParent if **t.relativePoint** ~= nil
--- - **relativePoint**? [AnchorPoint](https://wowpedia.fandom.com/wiki/Anchors) *optional* — ***Default:*** **t.anchor** if **t.relativeTo** ~= nil
--- - **offset**? table *optional*
---     - **x**? number *optional* — ***Default:*** 0
---     - **y**? number *optional* — ***Default:*** 0
---@return AnchorPoint anchor ***Default:*** "TOPLEFT"
--- - ***Note:*** Default to "TOPLEFT" when an invalid input is provided.
---@return Frame|nil? relativeTo ***Default:*** UIParent if **t.relativePoint** ~= nil
---@return AnchorPoint|nil? relativePoint ***Default:*** **t.anchor** if **t.relativeTo** ~= nil
---@return number? offsetX ***Default:*** 0
---@return number? offsetY ***Default:*** 0

I expect the entire text to appear as such (as it used to with the old extension version I've been using) when mousing over the function:

However, now it appears like so:

If it is the intended way of displaying annotations, that's fine - I assume some people prefer it this way but I do prefer and expect it to be displayed as it used to be, all lines rendered in order as written. If this is the case, please add a setting so everyone can specify the annotation rendering behavior to meet their preference.

[Arxareon]

Addressing the elephant in the room: @class & @field.

I realize the monstrous and sacrilegious examples given above could, and indeed should be replaced by class, field definition annotations and I should bite the bullet and go through my long code and clean it up - and I most probably will.

However, I still would like to keep the issue open for one reason: I like leaving notes, not field definitions just plain notes or code examples that are meant for only one parameter or return value, not the whole function. For those, I still would expect them to be displayed in order under their respective @param or @return lines. The option for this "classic" annotation display order would still be very welcome.

---

To summarize:

I'm missing a functionality that's usual for C# for instance, where we can add remarks and example to to specific parameters or the return value. I was able to get by when comment lines in these annotations appeared in order - any additional lines right after a @param would appear under it on mouseover or when using the function as well, but in the new version of the extension they don't.

Either the ordering could be optionally changed from the new smart way to the dumb they appear in the order of being written, or, a new way could be established where we can use and assign hypothetical @remarks or @notes and @example tags to specific parameters and return values which should ideally support and recognize multiple comment lines (an example code presented for a parameter would likely take up multiple rows, or there could be multiple points in remarks/notes) to achieve the same effect but done in a smart way.

[Arxareon]

https://github.com/LuaLS/lua-language-server/issues/2390#issuecomment-1783969290

✅ Solution:

As mentioned in the referenced comment above, if functions are not used as value types but defined as named functions (like so: local function f() end or function t.f() end when part of a table), all annotations work as expected - lines a rendered in order.

[Arxareon]

I was too hasty with the closure.

Using @class and @field annotations, any additional comment lines after field descriptions don't appear in tooltips.

---@field path? string Path to the specific texture file relative to the root directory of the specific WoW client
--- - ***Note:*** The use of "/" as separator is recommended (Example: Interface/AddOns/AddonNameKey/Textures/TextureImage.tga).
--- - ***Note:*** **File format:** Texture files must be in JPEG (no transparency, not recommended), PNG, TGA or BLP format.
--- - ***Note:*** **Size:** Texture files must have powers of 2 dimensions to be handled by the WoW client.

appears as, with the note lines written under the specific field description (and above the next field description) missing: