Getting complete TGB reference

#1 It can be found here or in the documentation folder in your TGB install directory.

#2 Thanks tom eastman for your link, maybe i try to look in your wiki link.
ohhh in my documentation folder i think it's not so complete.i found function onadd
doesn't exist.

#3 I don't think that TDN link has all the functions listed for every type of object... you can always do whateverobject.dump(); to view all functions and fields it contains in the console.

#4 Ok thank you very much joe rossi

#5 Dang, that's really useful! Thanks, Joe.

#6 The one in the documentation folder is more complete in some ways than the one on TDN.

#7 I've been struggling with the reference docs too. The trouble is, the one that gets installed locally doesn't tell you which parameters to functions are optional. The one on the wiki does, but it doesn't say what they will default to if you don't specify them. There also seems to be a lack of specification of ranges for some things. eg. mount allows you to specify a force used to bind one object to another, but doen't even hint at what values it expects to be given.

Is TGB designed to use SI units, for example?

Cheers,
Blame

#8 TGB doesn't use SI units. The type of TGB's units is simply "Unit" in the abstract sense.

The definitive source for documentation is the source code itself. You can always tell which args are optional by checking there. Something I try to do is update TDN every time I have to look something up in the source code. This helps the next guy who looks as well as saving me from having to look it up again. TDN is a wiki and is there for us to keep updated as a community.

#9 Hi Ben,

Thanks for your answer. I think the frustration comes from the fact that TGB is sold as two products, one including source code and one without. However, it feels like the source code is really a requirement because the documentation isn't complete enough without it.

Cheers,
Blame

#10 @Blame:

We definately appreciate the feedback on the docs and the suggestion to add a visual marking for the default args in the TGB Reference. However, I still cannot agree with this statement:

Quote:
TGB is sold as two products, one including source code and one without. However, it feels like the source code is really a requirement because the documentation isn't complete enough without it.

For one an alternate method to get the default args is using the .dump() command in the console... For example, create a static sprite, give it the name of "testSprite"... then type this command in the console:

testSprite.dump();

All fields and methods will be dumped out to the c onsole with all args (with default args marked). Another alternative is to type the function in the console... if you wanted to see the mount args then type this.

testSprite.mount();

It will spit out "wrong number of arguments" but then will give you the arg list defining the default args.

There is over 700 pages of documentation with TGB... with over 60 indivdual docs. The reference itself is over 300 pages covering almost every method and function in the engine. There are about 5 full game tutorials, about 16 feature tutorials and a handful of seperate reference docs covering spefics of TGB, Torque, and different technical elements.

Obviously the docs can always get better (and I assure you they are), though I still cannot agree t hat the source code would be a requirement and the "documentation isn't complete enough without it".

Again I appreciate your feedback and quite honestly take it. In fact I've been devoting my days, nights, and most weekends, to working on the "Torque Documentation Framework" that will help you find information about reference and glossary terms just about anywhere in the engine (see this for more details).

Though I appreciate your feedback I think your comment is more than just a little exageration.

#11 I agree with you, Matthew, with one caveat. The .dump() function lists the "description" arg which is developer defined in the code base. I have come across some of these which are incomplete or incorrect. So sometimes, even .dump() can be incomplete in its documentation.

#12 Very true Ben... In fact our future goal is to completely doxygen the TGB engine and dump out the reference doc completely from that, that way when any source changes are made to a function the coder will then update the doxygen comments.

Until then, however, every TGB Reference change has to be made by hand =0 Maybe we will get time to do a quick pass and visualize all of the default args in the include TGB Reference.

#13

Quote:Maybe we will get time to do a quick pass and visualize all of the default args in the include TGB Reference.

I love how now I know exactly what that means. I'll get right on it.

#14 Hi Matthew,

First of all, I apologise for the exaggeration and for complaining about incomplete documentation. I didn't mean to cause offence by it and I do realise that documenting a project is a huge and often thankless task. You are right that there is a massive amount of documentation available. I have also read your blog about the work you are doing on the documentation framework and I think it looks like a really good, helpful way to tie things together. I very much look forward to using that setup in future.

What isn't an exaggeration though, is that it does currently _feel_ "like the source code is really a requirement " because of the types of issue I mentioned. The different sources of documentation do vary in completeness and usability and some things, such as specifying what values unused parameters will take, are missing. These may be minor points when set against the scale of such a large and sophisticated system as TGB, but each one of them raises the bar to entry for new users. I imagine you would agree that every user who gives up as a beginner is a loss for the community as a whole.

However, having seen what you're working on I feel positive about where things are going and I wonder if I would have moaned at all if I'd got involved with torque script a few months in the future. :)

One further point: the dump() function looks very useful and will be another very helpful feature now that I know about it. It's also interesting that calling mount without parameters gives such output, yet calling it with the eight parameters specified in the TGB Reference.pdf gives the same error, but without the expected parameter list.

Maybe a useful addition to the documentation would be some kind of common misconceptions list or maybe a gotchas section. :)

Thanks for reading and for the help from all three of you.

Cheers,
Blame

#15 So far, Blame, there have only been 2 functions in the TGB Reference Doc that were missing the default markings (Mount being one of them). It's missing some functions too, but I'm working on it ;)

#16 I'm starting to feel like a right trouble maker. :)

#17 What program do I use to read the documentation in the Torque folder?

#18 Open the Documentation Overview.html file with your internet browser.

#19 What program do I use to read the documentation in the Torque folder?

#20 A web browser dude.