Alright, get ready, as this post is a bit long. It goes over several requested features as well as a few of my own.
Function Type Support
So, for starters, a few others mentioned it would be really nice if user documentation would also support function types, as currently there is no good way to do it.
However, adding on to what they said, beyond merely improving code organization, it would also add the additional functionality of documenting overloaded functions. As @MuffinHandler mentioned, it is currently not possible to do this.
For example, I currently have a module for creating CSG cones to model with and have begun documenting it. However, as you can see, it contains a single overloaded function for creating cones.
If documentation for function types were added, it would enabled the documentation of overloaded functions. As @Mauio64 and @vvv331 mentioned, it could be done over the type or within a type.
Example:
Note:
The ConeCreator type represents the type of the Module.
Links
It would also be beneficial to include the ability to link to other instances, such as above where I mention the [UnionOperation](https://create.roblox.com/docs/reference/engine/classes/UnionOperation) class, as it would allow users to quickly click on the related links and view the documentation of the linked objects in case they needed to. Perhaps through use of a
<link> tag or something.
I’m not quite sure how support for custom types could be linked, though I’m sure there’s a way.
Variables
As @Ohio_trouble350 mentioned, it would also be beneficial to be able to provide documentation for variables, as it could benefit both programmers while they are creating a program and the users of the program. It would especially help in areas where Object-Oriented Programming is used, as the objects of a class would get fleshed-out documentation that make it easier to use.
It would also be beneficial if documentation could also be done in-line with the variable for single-line comments. It makes the code more readable by having the description of the variable not getting in the way of defining new variables and thus having the variables closer together without interruption.
Example:
Special Annotations & Styling
Last but not least, special annotations for function or type documentation. Of course, the benefit the common annotations (
@param,
@return,
@error, ect.) would bring is evident. They would format the documentation so it would be easier to both read and write and improve developers quality of life due to not having to manually format the documentation. Last but not least, they can even be styled to
further enhance readability.
That isn’t to say that HTML tags aren’t useful in documentation, quite the opposite in fact. They can be, however, tedious to structure so that the documentation is easily readable.
Examples
IntelliJ JavaDoc Example
One good example of the styling that can be done with special annotations is how the IntelliJ IDE styles user documentation.
The annotation and markup tags — although no markup tags are in the image — are made to be bold and a slightly lighter color than the normal text, causing them to stand out without attracting all the attention. Then the variable, exception, and link names are made to be a different color, making them stand out from the rest of the text so they aren’t easily mistaken. Everything else is the same style, however, so it’s clear that it is description (i.e. - the actual content) while the other elements are mostly structure. And all of it fits within a neat block without the need for bulky html tags or whitespace to make it more readable, albeit the option is still there if needed.
When displaying the documentation in a tooltip, the tags help structure it and make it very readable.
As you can see, everything remains distinct, with the tags indenting their respective content text and separating it from the function description while the different coloring continues to separate the structure of the documentation from the description.
All in all, the styling and annotation tags make reading and writing the documentation a breeze.
Current Luau Documentation
The current user documentation, however, lacks distinction and could clearly benefit from adding styling and annotation tags to the documentation. Furthermore, while adding the markdown tags to format the documentation makes it more readable in the tooltip, it actively makes it less readable in the actual file.
Since the text lacks distinction, its poor readability is enhanced if the documentation is compacted.
Either way though, the tooltip is readable, although it would certainly benefit from annotations.
Potential Luau Documentation
What the documentation could look like with annotations — at least in the source code — is very simple and efficient. And it would look even better if styling was added.
The appearance of the comment/documentation block brackets doesn’t really matter since it could be anything.
One of the more interesting possibilities of special annotations is the embedded code example shown in the :WaitForChild documentation.
An interesting thing to point out is that the documentation tooltip that shows up from autocomplete seems to be just a little different than the tooltip from hovering over the method, the difference being that the code example part is missing in the latter.
Does the documentation for the built-in methods pull from different sources for the header and hover tooltip, or is it a difference in how the documentation is either processed or rendered?
Module Function Definition Hover Tooltip
This one is short and sweet. When hovering over a function that is also being defined as part of a module, the tooltip that shows the documentation doesn't show up. It would be beneficial if it did in this scenario so that the developer could quickly check how the documentation looks and make any necessary edits in an efficient manner.
Examples
Local Function Hover:
There was no difference whether it was a local or global function
Versus: Module Function Hover
As you can see, no tooltip pops up above. It does, however, pop up when the cursor is hovering over the function reference from the module:
There was no difference whether it was a module function or method
Summary
A list of the features/improvements mentioned:
- Support for documenting function types
- Support for links in documentation
- Support for variable documentation
- Support for in-line variable documentation
- Support for Special Annotations
- Module Function Definition Hover Tooltip
I know this is a lot, but I believe they are all features that would improve user documentation. This feature is already off to a great start, so keep up the good work!
