We were blessed to have the User Defined Function Documentation which made it super easy to understand what a function does right from the editor’s tooltip. However, this feature strictly applies to functions, and not to custom types which are equally as important in a typed environment!
Whenever we’re working with complex systems, we will often heavily rely on user-defined types (Types are so generic in Roblox because they can be used for OOP, protocols, and structs). While these types certainly help with intellisense’s autocomplete on certain keywords and beautiful the script’s structure, it doesn’t always communicate the intention. For example, a type might describe the shape of an object but not always why, or what assumptions that it may carry. In these cases, you’ll need to dig through external documentation, or search through its source to understand what the type fully represents.
I believe that implementing user defined documentation for types would improve scripting in a few ways:
- Being able to hover over a custom type and see a short description would make it immediately clear what the type’s role does (just like with Roblox’s own types!)
- User type documentation would thrive in collaborative environments where teams can easily understand what another developer’s type is for right there inline.
- When custom types carry their own documentation, you don’t need to go through a whole lecture on relatively large codebases if the types explain themselves (just like how function documentation helped with this too)
Take for example of this feature, where you could easily define:
--[[
Defines the parameters passed when scheduling a background task.
Used to defer operations outside of the main thread.
]]
type TaskContent = {
Id: string,
MaxRetries: number?,
Context: string?,
OnError: (string) -> (),
}
On its own, it’s not obvious what TaskContext is exactly for. We know that its the contents of a task, but why where how could it be used?
With documentation, it makes it immediately clear what TaskContent is about. With this feature you wouldn’t need to hunt for the type’s source, rather it’d be inline, just like how Roblox’s types currently work.
User Defined Type Documentation would be a huge plus to making Studio’s editor far more expressive, just as we could in Visual Studio Code (which many of the extensions support type documentation). I believe its a natural next step after the function documentation, one that’ll help developers to build and maintain larger, cleaner codebases!