Why is the reference documentation so lacking
by Derry Bryson · in Torque Game Engine · 07/31/2007 (9:42 pm) · 25 replies
Sorry, but i just don't understand. No offense to the community members here that contributed documentation intended.
Why is the reference documentation so lacking for TGE. As a programmer, I understand that tutorials, howto's, etc. are hard documents to write, but reference documents are not. Reference documents are tedious, but not actually hard to write, in fact, given the right tools they even write themselves sometimes. Why isn't there complete documentation for the global variables, functions, datablocks, and objects exposed in TorqueScript provided by Garage Games? Why do I have to rely on documentation provided by third parties who are only guessing in many cases?
Please help me to understand. I have placed this in a private section, so it will not affect your sales, and I have purchased your product.
Why is your documentation so lacking?
Why is the reference documentation so lacking for TGE. As a programmer, I understand that tutorials, howto's, etc. are hard documents to write, but reference documents are not. Reference documents are tedious, but not actually hard to write, in fact, given the right tools they even write themselves sometimes. Why isn't there complete documentation for the global variables, functions, datablocks, and objects exposed in TorqueScript provided by Garage Games? Why do I have to rely on documentation provided by third parties who are only guessing in many cases?
Please help me to understand. I have placed this in a private section, so it will not affect your sales, and I have purchased your product.
Why is your documentation so lacking?
#2
07/31/2007 (10:06 pm)
Thanks mb so much for your reply, and for the links you provided. I know you are really trying to help me the best you can. But, I hate to say it, I have been to everyone of those links. I have been to probably every link on this website ever.
#3
08/01/2007 (9:34 am)
Have you downloaded dOxygen and built your set of personal docs yet from the source?
#4
08/01/2007 (9:39 am)
@Stephen - No I haven't built the Doxygen docs, because I assumed what I generated would be the same as on the website. Am I wrong about that?
#5
08/01/2007 (10:29 am)
@Derry: I assumed the same at first, until I built my own. Trust me, everyone should be building their own Doxygen docs. The online version is very out of date, compared to what I built myself a week ago.
#6
The docs that Doxygen generates look something like:
www.garagegames.com/docs/tge/engine/index.php
Here's some more links that might help:
www.garagegames.com/developer/torque/tge/
tdn.garagegames.com/wiki/TorqueScript_Console_Functions
tdn.garagegames.com/wiki/TorqueScript_Quick_Reference
tork.beffy.de/index.php?option=com_frontpage&Itemid=1
08/01/2007 (10:37 am)
I felt the same way when I first purchased torque and thought a book should come with it. After a few days I decided to get the book 'game programmers guide to torque' and it was a great investment. It mainly focuses on scripting, not engine coding but it's a great book. The docs that Doxygen generates look something like:
www.garagegames.com/docs/tge/engine/index.php
Here's some more links that might help:
www.garagegames.com/developer/torque/tge/
tdn.garagegames.com/wiki/TorqueScript_Console_Functions
tdn.garagegames.com/wiki/TorqueScript_Quick_Reference
tork.beffy.de/index.php?option=com_frontpage&Itemid=1
#7
Is there some place we can find some documents on how to build the Torque dOxygen documents?
08/01/2007 (10:45 am)
After reading this thread, i decided once more to try and get dOxygen to work for me, but i guess im just stupid- i can not get it to work...Is there some place we can find some documents on how to build the Torque dOxygen documents?
#8
Download the installer for Doxygen and install it.
Then, click the Wizard button on the GUI front-end. Put in the project name and version (I did Torque Game Engine and 1.5.2) and select the source and target directories. I chose the engine directory. I also had it generate a framed document.
Next, save the configuration file.
Set the working directory to the bin directory wherever Doxygen installed.
Click start. Wait. Go to the output directory and load index.html into your browser.
08/01/2007 (11:00 am)
It had been a while, so I just redid it.Download the installer for Doxygen and install it.
Then, click the Wizard button on the GUI front-end. Put in the project name and version (I did Torque Game Engine and 1.5.2) and select the source and target directories. I chose the engine directory. I also had it generate a framed document.
Next, save the configuration file.
Set the working directory to the bin directory wherever Doxygen installed.
Click start. Wait. Go to the output directory and load index.html into your browser.
#9
That checkbox is under the "dot" panel.
08/01/2007 (11:04 am)
I also suggest checking the "CLASS_DIAGRAMS" box which will give you a very helpful class hierarchy diagram.That checkbox is under the "dot" panel.
#10
I was a bit tossed with that 'Step 3: Specify the directory from which to run doxygen'
One would think a program should not need informing where on the hard drive it is running from, so i was picking my project path...
08/01/2007 (11:19 am)
AH.. ok, got it- thanks. I was a bit tossed with that 'Step 3: Specify the directory from which to run doxygen'
One would think a program should not need informing where on the hard drive it is running from, so i was picking my project path...
#11
Doxygen for TGE 1.5.2 RAR
For the lazy people =)
08/01/2007 (11:31 am)
Doxygen for TGE 1.5.2 ZIPDoxygen for TGE 1.5.2 RAR
For the lazy people =)
#12
In other words, if you add new classes, change code flows, or otherwise modify stock for your project, you can immediate re-generate the dOxygen documentation, and it will now include the changes you made.
I can't really stress how beneficial this is to your project if you are diligent in source code documentation.
08/01/2007 (11:41 am)
While it's nice to have "pre-created" versions of the dOxygen documentation from stock, I'd like to reinforce that the true power of using dOxygen as the primary reference documentation source is that, if you as developers utilize the dOxygen documentation syntax, your code becomes self-documenting to the same level as your original self-documentation discipline.In other words, if you add new classes, change code flows, or otherwise modify stock for your project, you can immediate re-generate the dOxygen documentation, and it will now include the changes you made.
I can't really stress how beneficial this is to your project if you are diligent in source code documentation.
#13
I have my own working Doxygen file that contains info on every resource I've implemented and every change I've personally made. Saves me a lot of time on having to write external documentation over and over....and over...and over again...
08/01/2007 (11:46 am)
100% agree with Stephen. The files I've provided were generated just a few minutes ago. Indeed, they are based on the stock engine which can come in handy for people who haven't modified the engine (nor plan on it).I have my own working Doxygen file that contains info on every resource I've implemented and every change I've personally made. Saves me a lot of time on having to write external documentation over and over....and over...and over again...
#15
www.garagegames.com/docs/tge/engine/console_autodoc.php
08/01/2007 (11:59 am)
Here's something interesting I hadn't noticed before, it's a page documenting how you can generate some console reference documentation using some console functions and Doxygen:www.garagegames.com/docs/tge/engine/console_autodoc.php
#16
tdn.garagegames.com/wiki/TorqueScript_Console_Functions_2
dump(), metrics(), trace(), backtrace(), dumpConsoleClasses(), dumpConsoleFunctions() ... all good stuff.
08/01/2007 (12:53 pm)
Some more useful info for debugging and dumping classes to the console:tdn.garagegames.com/wiki/TorqueScript_Console_Functions_2
dump(), metrics(), trace(), backtrace(), dumpConsoleClasses(), dumpConsoleFunctions() ... all good stuff.
#18
As far as the resource I found to generate console reference docs from source, you say this is "very old and were used to produce current documention", yet I can't find any documentation like that generated on the website. Please point me to said docs and I'll be happy to eat my words.
08/04/2007 (12:14 pm)
@Berserk: I would agree that the docs that do exist are somewhat poorly organized making it difficult to find the docs you are looking for and making it even harder to find them again later, but that is not the real problem. The real problem is that they (Garage Games) seem to be depending on users to provide the documentation that they should be providing from the beginning. They have decided to use Doxygen to generate docs from the source, which is fine. Yet, the docs they provide are from 1.3.x. How hard is it to regenerate and post the current docs? Seem's like they (GG) can't even be bothered to do that, much less update the docs they have.As far as the resource I found to generate console reference docs from source, you say this is "very old and were used to produce current documention", yet I can't find any documentation like that generated on the website. Please point me to said docs and I'll be happy to eat my words.
#19
Luckily, plans have been put into motion to make things "all better" =). Ed Johnson and I are working on new documentation and tutorials, and TorqueSchool has finally launched. Also, based on my own speculation, I believe GG is working on documentation in some form or another.
08/04/2007 (4:03 pm)
Documentation on any level, for any product, is very difficult to generate. You are not the first to bring this up, and you will not be the last.Luckily, plans have been put into motion to make things "all better" =). Ed Johnson and I are working on new documentation and tutorials, and TorqueSchool has finally launched. Also, based on my own speculation, I believe GG is working on documentation in some form or another.
#20
www.garagegames.com/mg/forums/result.thread.php?qt=65594
08/04/2007 (5:50 pm)
Jaroslav Kurcik just put together an updated, searchable compiled windows help file which is pretty rad:www.garagegames.com/mg/forums/result.thread.php?qt=65594
Torque 3D Owner mb
tdn.garagegames.com/wiki/TorqueScript
tdn.garagegames.com/wiki/Torque_Console_Objects_TOC
tdn.garagegames.com/wiki/TorqueGameEngine
It's hard to find info when you don't really know what or where to look but there is a lot of docs on this site. I hope those above will help get you started.