As a Roblox developer, I find myself having to constantly open up modules in order to remind myself of what exactly certain functions do, even if the methods in question have decently descriptive names. This isn’t really an issue for smaller modules, but it begins to present itself once you’ve created a substantially large one or if you just haven’t used it in a long while.
Addressing this issue would negate the need of having to constantly open up modules and scroll through them to find documentation comments.
In order to solve this time-consuming issue, my request is for a feature that would allow for documentation comments within our code, which intellisense should pick up on whenever accessing a module.
I would love to be able to add some sort of description comment above my methods that intellisense would then display, just like how methods such as ‘FindFirstChild’ do already.
Edit: This post has been edited slightly in order to account for the fact that the introduction of Luau has partially solved some of my problems here. Namely, the previous version of this post had a section about intellisense picking up on expected argument types. I’ve removed that part of the request.
This is a very late bump however I still see relevance in this thread.
Not only is this good for what OP points out (personal reference when coding), but it is also an excellent implementation for public / open source modules required via ID or inserted into games from external sources.
It’s a standard in many other languages, especially languages oriented to more formal or professional design (e.g. C#), to include summaries or docs of every function and property of your objects. I’ve always had a habit of putting docs down in my C# code and it feels quite awkward not being able to do that in Roblox.
I have released a couple open source modules already and I always have to include API docs somewhere on my github or in the thread I write for said modules. It would be a huge improvement to be able to pack that in stock with the code itself, especially given that it can be a hassle to some users to remember my github page or the thread page.
I hate to bump this thread so late but I really, really need this feature. It is frustrating to use a modular codebase because I can’t remember what each function does without having to open its module. Depending on where the module is stored, it can take me a lot of time to simply find it— and that’s with the Explorer search feature.
Please add custom intellisense. It would greatly speed up my development time and make my life significantly easier.
Bump, this should be added, a #1 needed feature for making modular code or functions. I struggle to find an alternative or way to have custom documentation comments for functions and module functions.
def lcm(a, b):
"""Compute the lowest common multiple of a and b"""
return a * b / gcd(a, b)
lcm(2, 16) #hovering over will show -> Compute the lowest common multiple of a and b
This will make my workflow uncomplicated, and more understandable with document comments to know what does what.
I was thinking something similar to TSDoc, since Luau is trying so hard to be that, might aswell add it’s comment format as well
--[[
**
* Takes two numbers and returns their sum
*
* @remarks
* This is literally just for addition, this function doesn't actually have any remarks
*
* @param a first input to sum
* @param b second input to sum
* @returns the sum of a and b
]]
function add(a: number, b: number): number
return a + b
end
this should seriously be added because if roblox actually wants to expand their ide so much there should be no reason why plugins on vscode are beating it.
Let’s be honest: Roblox Studio’s tooling will never truly beat external tooling. The script editor can get better, it can evolve. But there is simply no way Roblox Studio can beat an external editor. And that’s okay- the majority of Roblox scripters do not use Rojo. The “power users” (as @Kampfkarren put it) that use external tooling like Rojo, with all the benefits such as CI testing, are a minority of the scripters on the platform.
Roblox is trying to make the process for actually coding as simple as possible. You lose a lot of features when trying to do that, and a lot of tooling- that’s okay. Roblox is investing in making it as easy to develop as possible, while still retaining good tooling that keeps newer users powerful and engaged, good enough for them to become serious Roblox developers and make money for the platform.
Things like TSDoc might never be supported on Roblox, simply because it does not adhere to the last paragraph. While it’s beneficial, it can complicate the process for scripting. It can increase the learning curve for new users. If you are willing to take up configuration files, JSON, TOML files, all that, then I encourage you to use Rojo. Because Roblox doesn’t want any configuration. They don’t want complex version control, because that makes it harder for new users to learn.
You should also keep in mind that VSCode extensions are sometimes open-source and used by companies like Facebook, Google, Amazon, Apple, etc. etc- I don’t think Roblox will be getting that level of tooling any time soon.
I think with the autocomplete callback API and a tokeniser (please someone make this), we might be able to hackily make a documentation provider plugin
Docfile is part of the way there but its not context aware and it just matches autocompletes.
Adding documentation comments seems no more of a learning curve than learning typed Lua. It’s not something you need to add to your modules, it’s just an optional feature. I’m not saying Roblox’s ide has to be feature packed with things like extensions and configuration files, it’s just simple features like this are currently impossible and make developing much more counter-productive.
You already need comments for your code to be “good code”, for example a function that takes in a number by the name time doesn’t describe if it should be in seconds, milliseconds, since the epoch or relative to another time.
This just makes it so you can read your comments without having to go back and forth between scripts.
The example doesn’t require any markdown, doc formatting or types knowledge.
Its just:
--[[
Returns the first child of the Instance found with the given name.
(the 'Learn more' link is markdown and doc formatting, but I would just put it's contents here)
]]--
function Instance:FindFirstChild(name: string, recursive: boolean?): Instance
This feature request is just to show what you should already have when you need it. If you don’t have it already then it has no effect on you.
It doesn’t add another thing people need to do in order to have “good code”, it just makes this good practice easier to use.
Bumping this thread again, would love to have this feature. It would be amazing for collaborative projects that require other developers to access my modules without needing to open them and sift through all the code to find out what the parameters or methods do.
I really need this, and while we are at it, it would be nice to add support for tags like @deprecated, and @private or @internal which would tell the IDE to hide certain property or method from autocompletion and would throw an underline warning for the use of a method outside as it is marked private/internal.
--[[
Some outdated method that should be no longer used
@deprecated
]]
function Class:test()
end
Bumping. If not, all external IDE’s support documentations for your own things. I don’t understand what is with Roblox not allowing us doing so. I really don’t want to look at the source code 100 times just to understand what does what, I want straight and clear answer right in the middle of writing a method or constructor function or anything like it.
