[Annotations] Info above function definition in hover info

[Yamsha75]

Hi, I am trying to prepare docstrings for Multi Theft Auto: San Andreas Lua scripting API and I have multiple cases of a single function name having multiple signatures and, more importantly, a big differentiator of being "serverside" (run on server) and/or "clientside" (run on client). I would like to somehow emphasize this property for annotations for functions which are both "serverside" and "clientside". A "Resource" in MTA:SA can consist of multiple scripts for both serverside and clientside, sometimes even a single script file is used on both. Using only overloads is not the best solution here, unfortunately, because it does not convey which function definition is for which execution context.

Here are links to two example functions on MTA:SA wiki:
https://wiki.multitheftauto.com/wiki/BindKey - has four separate signatures: 2 for serverside and 2 for clientside
https://wiki.multitheftauto.com/wiki/SetCameraTarget - three separate signatues: 1 for serverside and 2 for clientside

Here's my attempt at creating docstrings for the second function, and a screenshot of it in VS Code:

--- **SERVERSIDE**
---
---@param thePlayer player # The player whose camera you wish to modify.
---@param target? player # The player who you want the camera to follow. If none is specified, the camera will target the player.
function setCameraTarget(thePlayer, target) end

--- **CLIENTSIDE**
---
---@overload fun(targetX: float, targetY: float, targetZ: float)
---@param target? player # The player who you want the local camera to follow.
function setCameraTarget(target) end

Being able to show the "SERVERSIDE" or "CLIENTSIDE" information above each function signature would be extremely helpful.

Could someone point me in the direction of implementing that in a PR (info which files I should modify, for example)? Perhaps something like ---@header <text> sounds good?

[carsakiller]

The way you have accomplished this here with markdown is really the only solution right now. There is no annotation tag for a heading or label, the way you mention. There is an @async annotation which might be similar to the functionality you are looking for but is obviously not meant for this purpose.

For implementing it yourself, you can try taking a look at

• dca751c
• 1a6e210
• e7996f5

Another thing you can do to make it stand out is to use markdown headings:

---## SERVER
---@param player player The player to target
function setCameraTarget(player) end

Just be careful as descriptions written after a heading will need an empty line of --- in between it and the heading or they will receive the heading's styling.

[Yamsha75]

Gotta admit, this is far too complicated for me to implement the feature I need 😞 This separation of abstraction between core/completion, core/hover, parser and vm is extremely difficult for me to wrap my head around. Maybe I'll try with a fresh mind another day.

[carsakiller]

It certainly isn't easy, I am yet to sit down and dig deep into the code and try implementing features myself. If at some point I do get a deep understanding of how it all works, I would like to add a page for contributing to the wiki.

[carsakiller]

Another thing we could take a look at is how you have your definition files set up. Presumably you have some files that provide annotations for the various client and server functions. These are hopefully also in separate files or folders, server.lua and client.lua or similar?

You may be able to set up your workspace so that it can emulate the environments as closely as possible, offering only the functions you will have access to in each respective environment.

Let me know what the situation is with the definition files and we may be able to sort this out 🙂

[Yamsha75]

Yeah I thought about that, but the issue is that Lua script files in case of MTA:SA are bundled into resources, which are basically catalogues with a meta file, defining used Lua script files. Each resource can include multiple client, server, and/or shared files. Shared meaning that a single script file is used both clientside and serverside. As you can imagine, splitting library into client and server is not the ideal solution.

[carsakiller]

Hmm, yeah, if they are in the same file, it wouldn't be possible to split the environment up unless you manually sort through the functions.