Scripting is often done now with a large number of ModuleScripts communicating with functions. I, for one, quite like this approach. But I found it tedious to repeatedly open my ModuleScripts and scroll through the code just to remember exactly how I had named a function earlier in the week. So I decided to do something about it.
I introduce to you, Documentation Reader, a plugin meant to help game programmers keep track of their code.
This allows developers to use simple documentation comments in their scripts to render details into this plugin’s widget with a click!
To add documentation to a script, simply add comments where you’d like them in the following format:
Example code
--[[**
<description>
This is where you can write the description for your documentation comment
</description>
<parameter name = "bar">
This is where you can describe what your parameter is expecting and what it is used for
</parameter>
<returns>
This is where you can explain what your function returns
</returns>
**--]]
function foo(bar)
return bar + 1
end
--[[**
This is where you can write the description for your documentation comment
@param bar This is where you can describe what your parameter is expecting and what it is used for
@returns This is where you can explain what your function returns
**--]]
function foo(bar)
return bar + 1
end
Please note that all documentation tags are optional–you could create an empty documentation comment and it would work just fine.
To view documentation in a script, simply select the script you want to read about in the Explorer window. The Doc Reader window will display a list of buttons for every documentation comment that it finds. Just click on a button to read more details!
I know I wanted this, and I have seen at least one post in this forum asking for a similar feature as well. So I hope this is able to help developers!
And another note, anyone who would like to make comments or suggestions, please feel free to do so below. And if you would like to make a fork and send me the code changes, I am more than happy to read them and possibly merge it into the plugin’s source code!
I’d suggest changing the syntax to be a little more human-oriented. Some examples of other documentation engines:
Doxygen
Considered somewhat clunky, but is the gold standard for C++.
/*! \fn int read(int fd,char *buf,size_t count)
\brief Read bytes from a file descriptor.
\param fd The descriptor to read from.
\param buf The buffer to read into.
\param count The number of bytes to read.
*/
Rustdoc
This is one of the best documentation engines out there right now. Not only is the syntax easy to remember, use, and look at, but the generated web pages it creates are well linked and include a search bar.
impl Person {
/// Returns a person with the name given them
///
/// # Arguments
///
/// * `name` - A string slice that holds the name of the person
///
/// # Example
///
/// ```
/// // You can have rust code between fences inside the comments
/// // If you pass --test to Rustdoc, it will even test it for you!
/// use doc::Person;
/// let person = Person::new("name");
/// ```
pub fn new(name: &str) -> Person {
Person {
name: name.to_string(),
}
}
/// Gives a friendly hello!
///
/// Says "Hello, [name]" to the `Person` it is called on.
pub fn hello(& self) {
println!("Hello, {}!", self.name);
}
}
I think the buttons in the UI should probably be styled a bit more like Studio-native buttons. Maybe use ditch the btn_newWhite and color the background 238,238,238 and when hovered, go with a light blue color with a slightly darker border (similar to hovering buttons in e.g. the ribbon bar). Not a UI designer though.
Might also make sense to indent slightly and add a subtle grey background behind code snippets like Discourse does.
I may consider changing the syntax. I was trying to follow C#'s documentation comment style, as that is what I am most familiar with, though I do like the other two. But I am less likely to change that right now, unless I can find a way to offer both, as I don’t want to confuse people.
I am definitely planning to overhaul the UI in the next version, and I will probably go with the idea of closely matching Studio’s UI. I’m hoping to hear from some more artistically-inclined developers on ideas for the details page, as right now I’ll admit it is not good looking.
My first change, though, will be to move this into ModuleScripts. I built it all using just one script because I was unaware that plugins could be broken into multiple instances and uploaded. Doing it that way would definitely help me manage everything better - and I’d have a good reason to use the plugin as I work on it!
I have got a quite big module, and I easily have to continuosly check the source to remember what is the keyword that I have set, etc.
This should be a key tool to boost my workflow, if it wasn’t for one thing… I’m using LinkedSource because the modules should share the same source across quite some places
This means that in fact, I am unable to use said module normally. Not that is really your fault, after all it doesn’t seem that there is any actual API feature to read the contents of a LinkedSource. (somebody correct me if I’m wrong) I might create a feature request on this.
But that’s still a great job. Installed, left a favourite and a like.
I actually tried to look into how I could make this work for LinkedSource scripts and was unable to find anything, as well. If anyone does know of a way, I would very much so appreciate the help in adding that capability.
I hope the plugin can help you with other scripts, at least
If you’re taking suggestions for alternate documentation generators, there’s also luadoc style.
You start your comment block with three dashes, then it’s basically javadocs. However, I do admit I don’t the non-foldable aspect of it, as code folding is a feature I use all the time (plz fix, roblox). --[[** is a fine documentation block, though.
I probably wouldn’t use your style, as it’s super verbose and not so friendly for those who don’t have your parser plugin, but I would certainly switch over if it looked more like javadocs/doxygen.
I actually just finished an object based update for my data management system! I created a 100+ line guide with API documentation so that even beginners could easily manage, save and load data in their game with this system. I’ll probably use this documentation I wrote as a test for this plugin. Will install!
The UI now more closely matches Studio’s UI, the details page is marginally improved, and the entire code structure is vastly improved.
Summary
New list UI
New details UI
New script structure
As you may notice, the code is structured for more parsers - I have it set up to be ready to add more parsers, and I will likely add one that is similar to the C++ and Rust examples that @Tiffblocks showed, and perhaps also a LuaDoc one (wish I had known that that existed). My plan is to have a drop down list available whenever the current parser does not find any comments in the default style. I also want to add a settings widget for managing this, and perhaps other design components.
I don’t find the Plugin really useful “for me” because I can just write comments and read them from the Script but I know that it’s for people who want to read it in a separate place.
(I would recommend this plugins to my friends tho, they might find it Useful)
However if you can make a Bookmark Plugin that would be Extremely useful to me & hopefully everyone else, I am pretty sure we all have experience this.
You went for a lunch break and then when you came back you forgot what line you were at, so you have to scroll and find it, and it’s a real pain because it’s not just 100 lines of code, sometimes a few thousand lines of code.
Basically, what the Bookmark Plugin will do is when you make a Comment
-- "Bookmark Name"
or
-- "Bookmark" Continue here
it will show up in the Plugin screen and when you click on the Bookmark it will open the script and take you to that line. Simple but very very useful indeed.
A cool creation and a useful plugin but I can’t see myself using this as often as I would love to. I’ve stopped working in teams very slowly due to past issues and if it’s a game where only I see the game’s code, I don’t care too much for organization - I only organize code when I feel like I want to access my stuff easily.
10:34:47.968 - HTTP 403 (HTTP/1.1 403 Asset is not trusted for this place)
10:34:47.969 - Stack Begin
10:34:47.969 - Script 'Plugin_1836614749.Documentation Reader', Line 40
10:34:47.969 - Stack End
In a future update, I plan to actually make the script figure out the type of item in the next line. Though I will also add the ability to specify these values via tags. Right now, my plan is to determine type (such as function, table, or property) and name, but to allow for tags for both of those values to take precedence over the default loading capabilities. That update will come with a much better UI and some other upgrades.
Don’t expect it for a while - it’s quite a bit and I do have other projects.
Your plugin GUI constantly reopens every time I close it after a test, which is super annoying. I’ve had to edit your code to set initEnabled and overrideEnabledRestore to false. Can you make it a setting, please?
I didn’t make this an explicit setting. It now will default to opening the first time you open a place in Studio after installing, and then will have initEnabled and overrideEnabledRestore both set to false any time after that, making the “setting” just whether or not you had closed it before you last closed a place, just like every other Studio widget. If you update the plugin, it should work
