The Problem
As a Roblox developer, it is currently too hard to create in-depth documentation of Lua methods, modules, properties, and other entities.
The Request
For most programming languages, there are established conventions regarding code documentation, called DocBlocks. Lua does have LuaDoc, though I can not speak for its popularity. I am not actually requesting LuaDoc support in specific - literally anything will do, even if it only applies to Roblox.
Some features that I think should be implemented in order to sufficiently support code documentation within Roblox Studio:
Auto Completion for DocBlocks
In most IDEs, and for most languages, DocBlocks can be automatically generated to an extent that is almost usable without any further action by the user. For example, here is an example of Visual Studio Code autocompleting a JSDoc block:
While Visual Studio Code also provides a convenient tab-navigation system to allow users to quickly jump from one documentation element to another, this isn’t necessary - the barebones completion of the documentation alone would be massively helpful to developers.
DocBlock Validation
Studio should validate DocBlocks against the elements that they apply to when they are clearly invalid. Here are some examples of WebStorm highlighting invalid JavaScript JSDocs for obvious reasons:
Missing parameter description:
Mismatched parameter names:
Code Hints / Insights / DocBlock Presentation
This feature request is probably going to be associated with a separate feature request for basic code hints and insights. With the addition of DocBlocks, it would be quite helpful for Studio to also display them when the user is interacting with the documented element. For example:
Upon hover:
For a specific parameter while defining its arguments:
Closing Comments
If Roblox is able to address this issue, it would improve my development experience because code documentation is critical to maintaining large-scale projects over long periods of time. Currently, it is too tedious to do effectively:
- Without highlighting within the comments, it is quite challenging to both read and write any form of DocBlock comments correctly.
- Without autocompletion for DocBlocks, writing correctly them takes a non-insignificant amount of time.
- Without validation, mistakes or invalidity caused by changing code can go unnoticed.
I understand that this is a relatively large feature request, so please let me stress this above all else: literally anything would help, as we have absolutely no support for documentation in Studio right now. My guidelines here are merely a suggestion, but regardless of my recommendations, there’s a huge problem here that needs to be solved.
To the Studio engineers: let’s be honest, you know you’re using all of these features to code Roblox Studio itself. Can you imagine maintaining all of that code without them?