Modernized and User-Supported T2D Docs
by Charlie Patterson · in Torque 2D Professional · 05/02/2013 (9:10 am) · 7 replies
As everyone knows, extremely grokable docs can make or break a framework. This is especially true for ramping up newbs who often sit staring at a blank page and need a way to quickly ask "What does a SimSet do?" or "How do I move the camera?"
I wanted to start a quick thread about a new branch of T2D development. This branch is dedicated to a docs upgrade that makes it easier to contribute your knowledge into the code.
It's at torqueScriptDocs. More information will be forthcoming over the next week or two. But if you are the kind that likes to peek around and tinker, there it is!
As a teaser, here are 2 of the goals:
1) The TDN network has lots of data that is still valid (or close), but it's over on a wiki, and now there's a new wiki and there will always be even more wikis. :) Doxygen supports markdown now, so why not have TDN and other references pulled into the code and cross-referenced automatically?
Melv's new TAML reference has been slurped into a TAML.dox file and saved into the source now. Here is what the output looks like once you run doxygen (in this case it is showing on my copy of the T2D repo).
2) TorqueScript has the best docs of the T2D code. However they have classically been stored as a large string and stuffed into a macro. One of the downsides of this is that you can't verify your doc output until you re-compile the engine, run it with some scripted dump commands, THEN run doxygen, THEN verify your output. Frankly, I don't expect a lot of contributions to the docs coming in that way.
Now, however, you can update a TorqueScript function's comments as usual and then simply run doxygen to see the output. Here is an example script bind file that has been updated. And here is the output doing just fine.
I wanted to start a quick thread about a new branch of T2D development. This branch is dedicated to a docs upgrade that makes it easier to contribute your knowledge into the code.
It's at torqueScriptDocs. More information will be forthcoming over the next week or two. But if you are the kind that likes to peek around and tinker, there it is!
As a teaser, here are 2 of the goals:
1) The TDN network has lots of data that is still valid (or close), but it's over on a wiki, and now there's a new wiki and there will always be even more wikis. :) Doxygen supports markdown now, so why not have TDN and other references pulled into the code and cross-referenced automatically?
Melv's new TAML reference has been slurped into a TAML.dox file and saved into the source now. Here is what the output looks like once you run doxygen (in this case it is showing on my copy of the T2D repo).
2) TorqueScript has the best docs of the T2D code. However they have classically been stored as a large string and stuffed into a macro. One of the downsides of this is that you can't verify your doc output until you re-compile the engine, run it with some scripted dump commands, THEN run doxygen, THEN verify your output. Frankly, I don't expect a lot of contributions to the docs coming in that way.
Now, however, you can update a TorqueScript function's comments as usual and then simply run doxygen to see the output. Here is an example script bind file that has been updated. And here is the output doing just fine.
#2
05/02/2013 (10:52 pm)
Very nice. Is the end goal to replace all written content in the Github wiki with in-code documents, including tutorials? Or is this just for engine reference stuff?
#3
Right now, I'm thinking that all references should be in the docs, but not tutorials.
I think it's because they aren't as directly related to the code and, frankly, because there are lots of pictures and things in them. (Although refs should have pics when it fits.)
Also, the docs are generated through one pass of Doxygen. I'm sure tutorials can be worked out to fit in the same pass and in the same final doc, but it gets less natural.
05/03/2013 (7:13 am)
Hi @Mike, I saw the awesome reference material you wrote up. :) Very well done and a great tone!Right now, I'm thinking that all references should be in the docs, but not tutorials.
I think it's because they aren't as directly related to the code and, frankly, because there are lots of pictures and things in them. (Although refs should have pics when it fits.)
Also, the docs are generated through one pass of Doxygen. I'm sure tutorials can be worked out to fit in the same pass and in the same final doc, but it gets less natural.
#4
I made a document on "how to document". :) I hope I'm keeping it as simple as possible, but it probably needs another pass. It has all the techniques I'm using.
Meanwhile, and I hope you expected this, the document on "how to document" is, in the reference manual too!
You can see it here in my personal github wiki page.
The raw source page is in the torqueScriptDocs branch for now with all the rest of the update. The manual is at engine/source/console/documenting_ScriptPage.md. The display doesn't look normal, because github is seeing that it is markdown, and trying to show it outside of their source viewer. Ah well.
Lemme know what you think!
05/18/2013 (9:48 pm)
A quick update since I said I'd try to get some more info out.I made a document on "how to document". :) I hope I'm keeping it as simple as possible, but it probably needs another pass. It has all the techniques I'm using.
Meanwhile, and I hope you expected this, the document on "how to document" is, in the reference manual too!
You can see it here in my personal github wiki page.
The raw source page is in the torqueScriptDocs branch for now with all the rest of the update. The manual is at engine/source/console/documenting_ScriptPage.md. The display doesn't look normal, because github is seeing that it is markdown, and trying to show it outside of their source viewer. Ah well.
Lemme know what you think!
#5
I have checked in the new docs system for all platforms and compilers. The new stuff is still under "torqueScriptDocs" which is a branch off of "development".
The project required moving lots of console functions out of source code and into "ScriptBinding.h" files.
Now my testing has gone fine, but I could use some more eyes! If anybody can work on their projects but using this branch I'd be very grateful!
Have a good weekend!
Charlie
05/24/2013 (11:04 am)
A'ight. Anybody up for a holiday weekend project?! :)I have checked in the new docs system for all platforms and compilers. The new stuff is still under "torqueScriptDocs" which is a branch off of "development".
The project required moving lots of console functions out of source code and into "ScriptBinding.h" files.
Now my testing has gone fine, but I could use some more eyes! If anybody can work on their projects but using this branch I'd be very grateful!
Have a good weekend!
Charlie
#6
As part of my particle system review, I am in the process of adding missing TorqueScript bindings for some fields of ParticleAsset and ParticlePlayer.
When I submit a pull request, should it be according to the old way of doing a ConsoleMethod (pull request to dev branch) or the new way with ConsoleMethodWithDocs (pull request to torqueScriptDocs branch)? Or a pull request to both branches?
05/25/2013 (5:02 am)
Hi Charlie,As part of my particle system review, I am in the process of adding missing TorqueScript bindings for some fields of ParticleAsset and ParticlePlayer.
When I submit a pull request, should it be according to the old way of doing a ConsoleMethod (pull request to dev branch) or the new way with ConsoleMethodWithDocs (pull request to torqueScriptDocs branch)? Or a pull request to both branches?
#7
I believe, there is a 95% chance that the docs are going into the development branch and won't die off as an experimental branch, just so you know. I think it would already be integrated into development but for several complex changes in other branches that are on the way (spine, leap, etc).
My suggestions is to be a branch off of development and use the old way. It will all get updated when the docs branch is merged into development eventually.
05/26/2013 (4:48 pm)
Hi @Mike. Both would be overkill, but thanks for checking.I believe, there is a 95% chance that the docs are going into the development branch and won't die off as an experimental branch, just so you know. I think it would already be integrated into development but for several complex changes in other branches that are on the way (spine, leap, etc).
My suggestions is to be a branch off of development and use the old way. It will all get updated when the docs branch is merged into development eventually.
Employee Michael Perry
ZombieShortbus