Gain access to all of the hidden comment features used by official roblox api and more through custom html flags and markdown syntax in function comments.
API
<dep> = Adds the Enum.CompletionItemTag.Deprecated tag to your function response, marking it as deprecated (strikethrough).
[NOTE]: Marking a function as deprecated will hide the autocomplete response from the base scope. The only way to reference a deprecated function is by explicitly indexing it.
<doc>link</doc> = Adds an embeded documentation link to your comment.
[NOTE]: Unfortunately, Roblox will only embed links under their own domain at the moment.
``` = Treats everything in the comment under the flag as an official code sample, embedding it as such. (Not required to be closed, but will remove closing syntax if present)
[NOTE]: If your code sample has scopes, you must convert the indentation to spaces, as all tabs are filtered out when parsing through a code comment
Preceding Whitespace Before Line Break = Replaces the line break entirely, preventing your comment from being abruptly cut off
The current list of supported markdown syntax is: (Note that these are the only ones possible at this moment given the html tags roblox will embed)
**text** for bold text (<strong>)
*text* for italic text (<em>)
^text^ for Ëąá”á”á”ÊłËąá¶Êłá¶Šá”á” (<sup>)
`text` for code (<code>)
``` As a code sample marker
[NOTE]: Markdown blocks must be closed, incomplete markdown syntax will not be recognized. Use \ before markdown characters to use them normally (i.e \* or \**)
Added a markdown html flag to parse your comment for markdown syntax to automatically translate into the equivalent html block.
The current list of supported markdown syntax is: (Note that these are the only ones possible at this moment given the html tags roblox will embed)
**text** for bold text (<strong>)
*text* for italic text (<em>)
^text^ for Ëąá”á”á”ÊłËąá¶Êłá¶Šá”á” (<sup>)
`text` for code (<code>)
[Note]: Markdown blocks must be closed, incomplete markdown syntax will not be recognized. Use \ before markdown characters to use them normally (i.e \* or \**)
Furthermore, every custom html tag/block will remove a trailing line break following its invocation to allow for a common usage pattern where line breaks are immediately used after a tag/block for readability
This is awesome! While I liked how Roblox started showing user documentation for functions, I disliked how it included every line break, which made my comments look somewhat sloppy.
This plugin fixes this (with its <nb> tag), and will let me write descriptions that blend in better with Robloxâs official ones (ignoring my poor English nowadays). Honestly, this is how the feature shouldâve worked officially; The Markdown formatting makes it easier to read more detailed descriptions, and code examples could be useful for other people using community module resources.
I wish this didnât require a plugin at all, but your plugin fixed the issues I had with the official tooltips; Thank you for making this plugin, though!
Hey, just a tip! Instead of having to write (takes nil, returns vector2), you can actually type annotate a return value for a function!
local function getJoystickOffset(): (Vector2)
Yeah, itâs unfortunate this canât be done with Roblox by default.
Something else that would be useful that Roblox does is only give the description of the current argument as youâre writing it. Why canât we do this? No clue.
Another thing I noticed with this is that if you hover over a function rather than write it and view the autocomplete, the <.custom> and other tags show.
Unfortunately, the Script Editor API available to plugin developers doesnât include the ability to modify hover responses, or individual parameter responses. So until that happens the scope of this module will remain limited to autocomplete responses.
Glad to hear you appreciate the plugin!
As a quick tip, to improve the readability of your comment from the scope of its declaration and for those without this plugin, you can actually line break after invoking a tag, as the plugin will automatically filter out any immediate whitespace following a tag invocation.
Furthermore, the <cs> tag isnât a block that needs to be closed as, considering you can only embed 1 code comment, the rest of the comment following its invocation will be treated as part of it.
Moreover, the <nb> tag is applied after the code sample tag is processed, meaning that you arenât required to close an <nb> tag if unless you specifically want a paragraph to line break mid-way.
All to say that the intended use case of this plugin for a function comment like that is
--[[<custom><md>
**GetJoystickOffset** (takes nothing, returns `Vector2`)
<nb>
An alias for [module]:GetMoveVector(), ...
<cs>
local test = true
for i = 1, 10 do
print("Hello, world", i)
end
]]--
Ah, I didnât know the parser was that flexible. I updated the description to use this style and it does look neater. (I also replaced the placeholder code example.)
While editing the description, I removed the first line, since itâs redundant with Robloxâs larger built-in âheaderâ text. (It looks better like this, so it was a good idea!)
Originally, I would always write the functionâs name followed by the types it takes and returns, so I could refer to it when I went to use or edit a function in my ModuleScripts, but itâs pointless now that user-made functions show these detailed tooltips and I try to always specify variablesâ types when theyâre created.
Looks great! If you plan to release this to the public, Iâd recommend placing the tags in the way he recommended so that it looks cleaner and easier to ignore if the person reading does not own the plugin.
Markdown Code Samples would make sense if you could apply a code sample midway through a comment, but unfortunately, roblox only allows code sample embeds after the actual comment.
I initially opted for an html tag to convey the fact that all text under the tag would be converted into a code comment, but if you still prefer markdown embeds despite the nature of code comment embeds, I could simply make it so any text under a markdown code embed block is removed.
Furthermore, do you have any ideas for markdown syntax that could denote the <nb> html block?
You could always have the option for both. When you think about it logically, it takes less effort to type ``` even if you arenât making it public. If you are, most people who use resources know that the ``` syntax denotes a code block, making it easier for people without the plugin to understand itâs a code sample. Itâll also look cleaner to them. If you do decide to make this change, it would be nice if the closing ``` was removed from the documentation as well, just so we can include it to look better for non-plugin users.
Added the markdown code embed syntax (```) as a way to specify code samples.
As only 1 code sample is able to be embeded, the <cs> tag is processed first and will take priority over the markdown code embed syntax.
For those adamant on using closing tags for code samples (</cs> or ```) for the sake of consistency (despite the fact that the entire rest of the comment following a code sample tag is processed as the code sample), closing tags (and any preceding line breaks/whitespace) are now automatically filtered out of code samples.
In light of the limited reach of this plugin and some feedback regarding the intrusiveness of html tags on readability for those without the plugin, Iâve decided to reformat the API to offer the original functionality of the plugin with a greater focus on readability for those without the plugin.
Removed the need to preface your comment with a <custom> html flag, as all function comments (barring official ones) are automatically parsed
Markdown parsing is enabled by default in favor of markdown being the primary way to structure content
Removed the <nb>âŠ</nb> html block in light of this in favor of preceding whitespace being the intended way to specify line break removals
Removed the <cs>âŠ</cs> html block in favor of the markdown equivalent ```âŠ```
[Note]: The html tags <dep> and <doc>âŠ</doc> remain functional as flags
Optimized comment parsing and prevented redundant plugin reloading during playtests
This is awesome! While I liked how Roblox started showing user documentation for functions, 
I wish this didnât require a plugin at all, but your plugin fixed the issues I had with the official tooltips; Thank you for making this plugin, though!
