As a developer I often want to write instructions for my team members in the place file directly so they can be conveniently accessed. Right now I make a ModuleScript, which means the entire document is green and we have an object that looks like it’s supposed to run but actually shouldn’t.
I want a Documentation object that you can open and write into like a script. It would have a Source property like a script too. But no syntax highlighting.
I don’t know how I’d feel about having a separate place to store documentation. That gets tedious real quick if you need to update code and then maintain doc in a different place. Some kind of javadoc/luadoc format would be nice though.
I would prefer if there was some kind of pane in Studio that would parse a script and all of its documentation, rip out the source code apart from objects/method calls, and then presents that to you in a pretty-printed way.
Seems like a great plugin idea for when that plugin UI feature is released.
Shouldn’t we just be able to attach .txt files? I mean, all the other game engines have it, and a .txt documentation file is practically a must for all unity asset store goods. They are also very easy to integrate, I mean, their just plain text files. I think this would help become more universal in a way.
Rarely would I flick between programming and reading documentation rather than having them side by side. It is extremely tedious to have to constantly go back and forth, memorizing the API just to be able to use it.
I certainly wouldn’t want this feature in the way it’s been proposed, your code should either contain documentation in a format which can be extracted and viewed separately, or there should be some external source to view the documentation on, such as a GitHub wiki.
This is a perfect use case for plugin GUIs and some form of luadoc as @buildthomas has suggested. Documentation can be kept consistent and viewed in a separate pane while programming.
How about just a full-screen editor for a StringValue? You could retain the simple editor, but have a second one where you double-click to open it up like a script.
I could see utility in this for READMEs, even though the green text never bothered me so much.
Sounds like a good plugin idea
It would be nice if we had something like Matlabs function documentation
Documentation isn’t just for programmers. Builders, designers, etc. need instructions too and it’s important to have a single documentation module for them or else they’d lose it. It makes sense to me that you would document a script inside itself, but that’s not the point of this object.
This object is not for programmers to document APIs, this is for anyone to write down instructions and workflows for working with the game in general. E.g. what to do to parse data into a lua table, regenerate terrain, how to set up joints so they work with the game, etc.
It could received some minimal syntax highlighting as a Markdown file:
# Title
Some **bold text** and `inline code`.
It might also be useful for embedding blobs of text, because right now we don’t have a good way to manage that other than putting it in a long string literal in some script. (Spellcheck?)
If you have to “flick back and forth between the code and the documentation” then the documentation probably isn’t good enough to actually help you out much in the first place. Good documentation works perfectly well stand-alone.
As for the suggestion: I don’t think it’s too important, but it would certainly be a nice-to-have. I think that an effective implementation would have the object bring up a markdown styled view of the contents when double clicked, with a right-click option to “edit” it bringing up a normal code editor. Almost everyone who does development of any kind is familiar with basic markdown formatting and it’s simple enough that you won’t end up with almost nobody using it like you might with some more complicated documentation system. Plus that generally works well for keeping nicely formatted TODO lists and other random text in a place.
I prefer putting this at the top of the script:
s = [[
text
]]
because it’s darker than green long comments.
Still would like black plz. support