Documentation Reader - A Plugin for Scripters!

Resources Community Resources
, ,
#41

…That’s only mildly embarrassing.
Fixing now.

2 Likes
#42

Fixed.

2 Likes
#43

UPDATE

You can now add a “value-type” attribute to your parameters and return values. Here is an example in Rodocs:

--[[**
    Some function

    @param [t:number] bar Some random number
    @param addend Another number, but notice that the value type is not listed. That's because it is optional.

    @returns [t:number] The sum of the two numbers
**--]]
function foo(bar, addend)
    return bar + addend
end

For the XML style, please reference the help documents that can be brought up using the help button :slight_smile:

1 Like
#44

UPDATE

Now when you select a script, you will have the option to “Generate markup.” In the future, I plan to implement multiple markup languages, which will be another setting. For now, there is only Markdown.

This is a really awesome addition for GitHub repositories :smiley: Hopefully this helps to incentivize people to add Rodocs comments to their open source libraries since it will auto-generate Markdown now :slight_smile:

2 Likes
#45

One further update - I finally got around to making the plugin work with Studio themes with the new API.

#47

Reminder for the author of the plugin.

Also something that popped up in my mind. A field that states whether the function will yield or not.

1 Like
#48

I am considering removing the XML style documentation so as to make it easier to expand upon Rodocs. Is anyone opposed to this idea?

2 Likes
#49

You’ll get no objections from me. Before you do so however, how are you going about getting xml style elements and their attributes? I’m curious.

#50

I just documented my RbxWeb module with this, and it’s so much better now. This plugin is absolutely amazing if you dedicate the time to documenting all of your code.

image
image2573×1279 248 KB

I did notice a bug with the plugin where it wasn’t showing documentation until I refreshed my plugins. It wasn’t even showing an error either. I’ll update this comment with a picture of it if it happens again.
image

Edit:
Here’s the bug.

image
image445×655 824 Bytes

And I do have a module selected, with proper documentation.

image
image3440×772 1.2 MB

3 Likes
#51

This plugin is great, I’ve been documenting all my scripts with it. I have one thing to nitpick though; it only allows for one return value and even gives a warning in the output about it.

Having multiple doc tags of type returns is not allowed.

I find this silly because it’s natural for Lua functions to return multiple values, or a tuple.

1 Like
#52

I love this. The minute I start a new script, I’ll be using this to keep myself sane and productive. You are a lifesaver :joy:

#53

This is a great plugin, it has really helped keep me sane when working with large codebases. I do have two suggestions though. Firstly, could you consider adding a setting to hide the Swap and Help buttons (and maybe an option to move the Settings button to the reader)? My plugin bar is getting really cluttered and I want to minimize that as much as possible. I could edit the script, but I don’t want to miss out on any updates. Secondly, can you enable ClickableWhenViewportHidden on the toolbar buttons? (Sorry for the necro)

2 Likes
#54

Those are both great ideas :slight_smile: Thanks for the suggestions!

2 Likes
#56

Damn I really like this. A suggestion, is there any way for you to implement Inferred Tags like in luadoc, such as @name and @description.
I would really like to override names in my documentation because I write functions like tables, and it leads to situation where the documentation name does not accurately display what the code does.
For example,
image
listeners is a class, and connect and disconnect are the class’s functions. I would just like to override it so it can say
listeners instead of local listeners = {}
listeners:connect(func) instead of connect = function(self,func: listenerFunction) and etc.

#57

Gives an error when you try to generate markup. Please fix it.

#58

This is an overall helpful plugin. This has become part of the corporate workflow for both the entity I work for and the company I own due to it’s communicative nature to oncoming programmers.

To help us out, though, I do have a few things you could change/fix in the plugin to improve the experience of it.

Forgetting “- -” after the second “* *” means the plugin ignores documentation

I always document API using the newer format, which looks something like:

--[[**
documentation here

@returns api
**--]]

However, if I were to type the above like this,

--[[**
documentation here

@returns api
**]]

then the plugin does not document the API.

Not defining @param or @return means documentation is ignored.

If I were to document a method like below:

--[[**
documentation here
**--]]

the plugin will not display the documentation. To fix this, I have to put @returns void at the end.

Below is a screenshot of this issue:
image

Font size on API page is too small

image

This font size feels too compressed and crammed. Please increase the row height and font text size.

Details panes are not compatible with color theme of Studio

This picture shows the panes are in light mode, despite my Studio session being in dark mode.

image

That’s it from me. Great work on the plugin, and I hope to see these issues addressed!

2 Likes
#59

Thanks for the fantastic feedback! I will hope to make changes, including to reflect your comments, by the end of June.

2 Likes
#60

This plugin has been very helpful to me, especially now that I’m working with a team and need to write scripts that allow my team to interact with my systems. This saves us a bunch of time by avoiding needing to explain what each function does.

One thing that I would love to see though is different “syntax” colors for each specific property. What do I mean by that? Let us use the image attached below as an example:

image

When looking at it, everything looks the same, especially when looking at the parameters. I believe that it would be much better if there was some color differentiation between the parameter name, type, and the description. This could either be a separate theme or there by default. This will help me and my team speed up our workflow since it will be easy to differentiate the different types of parameters (especially in functions that have a lot of parameters).

Depending on how difficult and how possible it would be, removing all the types from arguments would also be awesome. In the picture above, you can see how I have set parameter types (e.x. Position: Vector2), so removal of the types would be awesome.

Nonetheless, this plugin is very helpful, especially when working with a team and are expected to share your functions and use functions that other team members have made. It really speeds up workflow as you do not need to open a script to see what functions you can use from there. Amazing work on this plugin!

1 Like
#61

This is a wonderful plugin that I’m using for any module I ever release!

I’d like to make a request. Some of my functions have optional arguements, and currently the only way to indicate whether or not something is required is to write as such in the @param description. Would it be possible to add an @required tag, to note parameters that the function will fail if they are missing? @required parameters would have their own category between the Description and Params flyouts, describing parameters that are vital to use of the function.

1 Like
#62

Have you thought about implementing a common annotation structure, something like EmmyLua? Not only would this reuse an already established style, but it is already used for intellisense in vscode, so it would inherently provide dual purpose should someone be happening to view an annotated lua file in the roblox ide, with your plugin enabled