New Script Editor Hover Tips and User-Defined Function Documentation

[LightningLion58]

@permanent_fixture

User-Defined Function Documentation

For user-defined functions, the Script Editor automatically extracts comments placed above the function definition and displays them in signature help, autocomplete, and the new hover tip. No formatting or special syntax is required.

Thank you for this!

This is a game changer for documenting our own work! (either for ourselves and for other people to use)

I agree with others regarding the addition of formatting, it would definitely be helpful!

If we can’t have formatting, it would be helpful to have @param and @return (and perhaps even @deprecated) tags.
It would allow developers to explain each parameter in detail, and explain what the method/function returns, and also if we can have the function crossed when it is marked as @deprecated. All these features stated above would definitely level up documentation on the platform.

Here’s an example (from Java):

[Real_Daytern (Daytern)]

With all these tips and reminders, developers will definitly reduce errors and iterations, means faster error detection. It would be interesting to see how much time is saved with updates like these and how many errors are caught earlier.

[Ohio_trouble350 (TheSilliestGoober)]

This has been needed for a looooong time!

Now we don’t have to go into our modules just to remember how to use them.

Can you add link support to these? (at least for links to the DevForum)

[uglyburger0]

Cool stuff, and some cool info here: you can use <code> & </code> in your comments. Can’t find anything else, but it makes it read a little nicer.

With this, are we hoping to see something akin to JSDoc in the future? Such as variable descriptions, author tags and whatnot?

[Iliuminatis (・ロ・)]

Open Documentation button is very useful, saves some time when needing to look up functions information.

[permanent_fixture]

User-defined comments are displayed as raw text for now (with some small support for formatting tags). We may support special annotations in the future! LuaDoc-like annotations have been discussed internally in the past.

[Dekkonot]

The community generally uses Moonwave for annotations, so it might be good to support that over LuaDoc. It’s a bit more work but it would integrate with what people are already using more.

[vvv331 (vvv)]

You gotta use a hacky work-around for this unfortunately.

type foo = {
	Function: typeof(--[[documentation goes here]]
		function() end)
}

this works but yeah this is really messy :
hopefully documenting types will be a thing in the future. I want to do either

--makes it string
type foo = (number) -> (string)

or

type foo = {
    --documenting like this
    bar: () -> () --... or like this?
}

[towerscripter1386 (Tower)]

This still needs some work. It seems to me that user-defined function types are not supported, and as mentioned in the post above, there is only a hacky way of doing it.

[swmaniac]

At present you should be able to use these HTML tags in the documentation tip:

<em> for italics.
<strong> for bold
<code> for code
<sup> for^superscript
<br> for line-breaks
<p> for paragraphs.

[gillern]

Types are still not highlighted differently from variable names!

[12345koip]

I have long awaited user-defined function documentation. Finally, it’s here! This will make workflow much easier and quicker.

[PeZsmistic]

+1 Still waiting for this. Makes code look like soup right now.

[isaac010901 (Tropical)]

“User-Defined Function Documentation”, Alright, y’all cooked with this one

[Army_newjeans (Izem)]

User-defined function documentation? Amazing!

[greenboo5]

If you style block comments like I do you end up with an extra “--” at the end of the user-documentation, it’d be nice if it wasn’t included!

[jackdotink (Jack)]

This is a really cool feature, however standard practice in luau docs tooling has been to use --- and --[=[]=] for doc comments. Hope you guys change to use this instead of fragmenting the ecosystem when so much documented code has already been written with tools like moonwave.

[Glitchifyed]

I have been waiting for the user-defined function documentation for years at this point! This is going to make my modules so much easier to explain and use.

On another note, are we going to be able to include code examples and external links to documentation like the Roblox API functions have here?

[nothing_1649 (gom_a)]

currently throwing an attribute between the comment and a function on different lines doesn’t show the comment, other than that this is what i’ve wanted for damn near a whole year

[drewbluewasabi (Drew)]

Does anybody here know if comments are still included in the runtime scripts? As-in they will be included in the finalized code and/or still take up memory.

I’ve been wondering for a long time due to luau’s non-compiled nature