Documentation Reader - A Plugin for Scripters!

plugin
lua
documentation

#21

HUGE UPDATE

This plugin is now onto version 1.1. The OP has been updated with images and details for the new version. But just a quick rundown:

  1. The UI has been updated. It now looks much more like Studio.
  2. There is now a settings menu!
  3. And the big one! You now have the option to use a much more concise comment formatting style that I am calling “Rodocs.” Rodocs will now become the default option for anyone who updates or installs the plugin. You can still change back to the “XML Style” comment format by simply opening the settings menu, which can be accessed from the plugin toolbar.

#22

By the way, credit to @Tiffblocks for the Roact Studio Widgets library I used for most of the new UI. Made my life so much easier and made the UI look so much better than I would have.


#23

Think you can add a feature to convert XML style to Rodocs?


#24

I was actually working on that already :blush:


#25
20:25:48.826 - Plugin_1836614749.Documentation Reader.DocReaderManager:31: attempt to index global 'plugin' (a nil value)
20:25:48.827 - Stack Begin
20:25:48.829 - Script 'Plugin_1836614749.Documentation Reader.DocReaderManager', Line 31 - field new
20:25:48.830 - Script 'Plugin_1836614749.Documentation Reader', Line 9
20:25:48.831 - Stack End

Are there docs I need to read to get it to work, or is this just a bug?


#26

A bug. Thank you for the stacktrace. I’ll fix it tonight.

The bug is fixed. I didn’t come across it because it only happens the first time the plugin is run on your instance of studio (or first time after you delete its settings file). It should be resolved now if you update :slight_smile:


#27

Doesn’t seem to work with nested functions. Example displayed in the picture below.


#28

It should work just fine… Could you ensure that your settings have “XML Style” enabled?


#29

Yep its enabled, and it is reading my other comment tags that are not nested.


#30

I’ll investigate now.

It has been fixed. Thank you for pointing this out.


#31

Thanks


#32

Unexpected tags cause errors; would probably be more sensible to just ignore the field if you don’t know how to parse it or issue a print into the output. Regardless of how you report the error, the rest of the documentation should be built up.

Errant documentation & stack trace
09:49:48.558 - Plugin_1836614749.Documentation Reader.Parser.Rodocs:66: attempt to index field '?' (a nil value)
09:49:48.559 - Stack Begin
09:49:48.560 - Script 'Plugin_1836614749.Documentation Reader.Parser.Rodocs', Line 66 - upvalue _getDocTagData
09:49:48.560 - Script 'Plugin_1836614749.Documentation Reader.Parser.Rodocs', Line 52 - method GetDocTags
09:49:48.561 - Script 'Plugin_1836614749.Documentation Reader.Parser', Line 71 - upvalue _getDocCommentData
09:49:48.562 - Script 'Plugin_1836614749.Documentation Reader.Parser', Line 57 - method ScanLuaContainer
09:49:48.563 - Script 'Plugin_1836614749.Documentation Reader.DocReaderManager', Line 74
09:49:48.565 - Stack End
--[[** @brief A function!
	
	A longer descreiption
	@param bar Some sort of parameter.
**--]]
function foo(bar)
	
end

#33

ANOTHER UPDATE

This has been added :smiley: And the OP has been updated to have an image of this update.

I agree - that’s why this update changed to accommodate that. Now if you have erroneous documentation comments, you’ll get a warning in your output every time you select the script in Explorer, but the rest of the comments should load properly regardless.


#34

Sweet, just updated and things are looking better!

Quick question:
confusing-text


#35

That means no description was loaded - I should probably change that to default to an empty string…


#36

Nice plugin ! I would love if I can say for example < type > and that the plugin will highlight the type :slight_smile: So that I can say @returns < int > or @returns < table >

Or even say
@param name < type >


#37

It’s an easy enough addition to make, but I’d need convincing on why this makes sense for a weakly typed language like Lua? Could you offer any examples of where this is useful?