Official TGE Documentation Feedback

#1 I would like, for each Torque C++ or TorqueScript function :

- a clear description of the parameters, with their units (think radian/degree) and their limits
- a clear description of their return values

- a clear description of the goal of that function

- some examples of uses

- a open space of discussion about this function (user's add-on to the documentation)


That's a start ! ;-)

Nicolas Buquet
www.buquet-net.com/cv/

#2 @Nicolas - Good start. Thanks for kicking off the thread =)

#3 For a great example of what online documentation should look like, take a look at the PHP docs. For example:

us.php.net/manual/en/function.explode.php

It shows everything you would need to know about the functions use, along with comments and a list of other functions in that category.

#4 Hehe, the typical case where you try to remember all those request you use to have, but cant remember nothing :)

For start, a clear definition of which engine versions are covered by a given article/doc page would help. In fact that would make easier the search for outdated parts.

And another idea: the main (downloadable) documentation cover this at some point, but a series of conceptual articles on how the engine works and what are the philosophies behind it, would had helped me a lot at their moment. Even now, after months and months of working with the engine, there are many dark areas for me, about whats the correct way of doing some given task.

#5 @Peter - I love the php.net online docs. They were invaluable to my learning of the language


@Novack - Good suggestions. Could you give me a specific example of a dark area you have come across?

#6 Another good example would be the TorqueScript Reference Guide v1.10.chm that Jaroslav Kurcik made.

#7 @mb - Awesome, good find!

#8 Novack brought up an interesting point, which i almost posted yesterday, but for some reason did not. Keeping the official documents updated and cleaned up. Perhaps making a tab for each engine version. I'm not saying the information is out dated or invalid, just seeing the date 2002, 2005 or version number 1.3.X is very uneasing, especially for someone who is new enough to need the official documents.

I love the resources, documents, and tdn articles, but seeing one that is up to 6 years old makes me not even want to waste the time reading as I have attempted to implement countless resources which suggested changes or functions that were no longer present in the new builds of the engine.

#9

Quote:This is your chance to talk until your face turns blue about what you want from the docs.

Hoooo, Boy.


Personally, I quite like doxygen. Torque has had real doxygen docs before and historically they were genuinely good and awesome and useful. Two minutes looking finds ideal documentation starting at line 85 or so in game/gameBase.cc, among many many other examples.

What I'd like to see is a new and improved doxygen config that isn't windows- or filesystem-position-specific, and then starting to get the doxygen documentation bulked out. Throw a working config file into the source distribution and let people generate this stuff! I created a new config file doxygen.html.cfg appropriate to a new version of doxygen, and changed a bunch of settings to my own personal liking. Things of note:
1) header.html, footer.html, torque.css are all really old and really out of date. Create new ones or just let doxygen do it's thing, personally I quite like it
2) enabling graphviz takes the running time from a minute and a half, to a couple hours... but graphviz is really pretty. It's off in the file I posted, just set HAVE_DOT to yes to use it.

Personally if I were ruling the world [and what I do on my own personal projects] is start by turning on all the warnings, setting QUIET=YES, and go through torque and correct all the warnings. My current project isn't anything like as big as torque, but doxygenning the docs for all ten thousand lines of code is completely silent, even with all warnings turned on.
Other things that are obviously lacking in torque that I've grown to find really useful are real \file descriptions for each file, and useful documentation for every item in enumerations.


The second thing I'd do is enjoy the ConsoleMethod and ConsoleFunction internal documentation mechanism to ensure that all functions and methods are correctly documented, then modify torque so that it's able to drop formatted documented versions of them.
console/consoleDoc.{cc,h}, lines 24-37 - it's all *there*, ready for someone to get big and brave and dump it as HTML instead of console text.

lefty:engine chunky$ grep -ri '\(ConsoleMethod\|ConsoleFunction\)' . | wc -l
1486
lefty:engine chunky$

That's a seriously beefy resource already prepared for someone determined to really make use of. Hell, no need to even write string wrangling in C++, just write a perl script to grep through the files and dump HTML output yourself. That way it'll even fit more neatly into an automated workflow. I guess if you were sufficiently determined, it'd be easy to use make and a C++ preprocessor to do all the work for you.


Next up, I'd really like tutorials for torque for C++ how to do stuff. Just simple stuff, like:
1) "I want to build my own spaceship from as low a level as might be reasonable for someone who doesn't want to start with a vehicle"
Then a doc explaining how to build up from a GameBase, as per the famous killerbunny advice.
2) "I want to build a new UI widget that does something new"
Something that springs to mind is an in-game overhead map. It's a simple-ish widget that you could build up in a tutorial kinda way.


On the whole, I think there's a lot of documentation that's *already there* in TGE, it's just a pain in the ass to get at. What's there is *good stuff*, y'all just need to start really making use of it again.

My overall feeling about TDN specifically is that it's trapped in a little world of almost-no-use. The people who'd need to access the documentation are the ones that aren't appropriate to writing it, and the people who'd be able to write the documentation are the really long term torque users who probably have better things to do than write documentation. My more specific issue with TDN is that when I do find content that's useful there, it isn't downloadable as a PDF or an html file.


... Well, you did *ask* me to talk until I was blue in the face.

Gary (-;

#10 TGE would greatly benefit with TorqueScript documentation similar to TGEA already has with version 1.7.0
C++ code documentation is secondary IMO because we can get doxygen to spill that information.

With just TorqeScript functions used to access the engine code, that is categorically presented in some meaningful way.. I believe it would do the entire community a great service.
example:
logic loops
if
then
else
switch

In this way, a prospective customer sees TorqueScript docs to help learn scripting for TGE while they use the demo and reduces the amount of confused questioning in the forums.

Just having TorqueScript functions and syntax to use it combined with smart categories for each function then also serves as a reference for the veteran scriptor as well.

I see no reason to rewrite docs that doxygen and a good C++ book can provide.

Oh yea...

Somebody rewrite the beginners getting started tutorial because generally it is very wordy and intentionally has the reader blindly typing in what they read, without explaining why.. specifically Gameone.png area of the tut and again the "whoops" part involving placement of the button created and checking againts various screen sizes, and again when the reader is told to enter LoadMyMission(); in the text area..without first explaining the need, the why and where..only to later discover the gameone.png was pre-made, and the main.cs file was pre-written to facilitate the tutorials purpose.
The method used is a blind guide hand-holding and hurries the readers through.... The end result of that tutorial leaves the beginners to think the engine is a copy paste and press the "Make Game" button sort of cheesy engines.

I have been tempted to submit a better written newbie guide but I'm still considered a noob myself. Sure I know the how and why, now, after near 4 months reading resources here at GG and experimenting with intention to break the engine in the process...but my studies are now fully focused on datablocks until I can spit out a definition, derive from it, and make it scream in submission ... all the data I like.

#11 Our problem with documentation is that our content creators (artists, designers, etc) don't have source licenses, and they're constantly fighting to get information from the site. There's a lot that's locked down to licensee only access for no real reason (as much of the information is in forums posts). We're continuing to build up our internal wiki and write our own documentation, but it's a real pain to write generic docs when that information should already be available.

Ideally, there would be an open, publicly-accessible per-discipline portal, ie:

* Art portal
* Scripting portal
* Mission design portal

Each of these would contain getting started guides and full pipeline reference all in one place for their discipline. I know there's a similar page up here, but so far it either hasn't actually contained useful information, or that information is locked away.

Also, we keep running into the 'Service Unavailable' error all over the site. Since what docs are available are all on the site, it's a really annoying issue to hit over and over.

#12 @Gary - That's the kind of rant I can read with a smile on my face, thanks =)

@Scott - Excellent points. Also, don't downplay anything you might create yourself. Some of the best tutorials are submitted by community members, regardless of what their level of experience is.

@Sim9 - Thanks for pointing out that artists and other content creators need some doc lovin' too. Their work and documentation are on the agenda as well.

#13 Glad I was of some use :-)

Gary (-;

#14 A basic example with descriptions of the parameters/syntax. If you have those then it helps to see what it's all about for script and engine. Here's an example that drove me crazy, and I think I have the hang of it now.....?
An engine example taken from your docs:
executef
Purpose Class method Con::executef() invokes a console callback function. // ok, sounds fine, now the example
static void processMasterServerQuery( U32 session )
{
...
Con::executef( 4, "onServerQueryStatus", "update", "Switching master servers...", "0" );
...
}

// end of example
....ok?.....what are all the parameters? do they mean something? Can they be strings or int's or char's or what? Is there a limit? What will with script part look like? how many parameters get passed into the scripts?

It's this sort of thing that has caused hours and hours of headache and time wasted, trying to find all those answers, which is usually found by piecing bits and pieces together from forum posts. You guys work on this day in and day out and just assume that we are on your level and know exactly what you mean....I think I need a "Torque code for dummies" book or something.......

Hope this helps.

#15 @DALO - Just want to clarify your feedback.

You are recommending more detailed information on the parameters for Con::executef(...), and not "onServerQueryStatus"...right?

#16 Correct, that was just one example I picked to illustrate the point that some descriptions just don't really mean anything. The docs for scripting are decent, but the engine docs are lacking and are puzzling.
Thx.

#17 @DALO - Got it. Thanks!

#18 Torque's documentation (or the lack thereof) has really been frustrating for me. I'm an above-average-skill-level user and have bought every book on the subject of Torque I can find. But I'm still spending a lot of time trying to find simple answers, because the simple answer is buried deep in the internet. So, I'm glad that someone is addressing the issue. But rather than just griping, let me offer some helpful ideas.

One, why isn't there a documentation Wiki? (Or is there and I just haven't found it yet.) Documentation from someone who managed to get it to work is better than no documentation, or severly outdated documentation. I mean, there IS the forums, but a Wiki where everything is together in one spot would be really nice. It could be a page for every script object that, for example, would have official documentation at the top, and then user documentation attached to it. I don't know if the user community is large enough to support this, but it seems like a good idea in theory any way. I know I for one, would consider posting answers once I found them. A Wiki could also allow users to point out which parts of the documentation remain unclear, allowing the documentation writers to know which areas need further work.

Two, functions/objects need their parameters properly documented, or they are all but useless. I think this is reiterating Dalo's point. But to add my own thoughts: data types are important in the documentation, but parameter RANGE is just as important. A function may be of type Integer, which tells me quite a bit, if I am familar with that type. But just because something is defined as an INT datatype and that datatype is a 4 byte signed number, doesn't mean that all possible values of the data type are valid for the function. It might be coded as that datatype and ignore, or worse blowup, on values that are negative or over positive 80, for example.

Also, UNITS are mandatory. I know that a lot of units in Torque are "flexible" and meant to be defined by the designers, but knowing the units that the designers had in mind can make a huge difference. For example, if a function takes an "impulse" parameter that is an integer, is the value in Newtons, Grams, Meters, or imaginary "made up" units that aren't a force/weight/distance? Something as simple as saying the value is in Newtons informs me that the function is thinking in terms of actual physics rather than simply moving the object a fixed distance (meters), for example. Which gives me a better idea of what the parameter actually does. Specifying meters instead of kilo-meters also gives me a better idea of the range of valid values.

Three, most documentation for coding doesn't make much sense to me when I read it. It's always been that way for me as a programmer. I can usually gather 10 times as much information from a very simple working code example than I can gather from a parameter list/syntax list. (Paramater definitions, on the other hand, are still a must.) I do see examples in the Torque documentation some times, but they are often incomplete or out of date (which points back to the Wiki idea).


Any ways, thanks for addressing the documentation issue!

#19 If you go to the Documentation item on the main menubar at the top of the site and select the first item on the list you will be taken to our user generated wiki: Torque Developer Network

#20 @Brennen Beck - Thanks for the feedback.

As Matt posted, check out the TDN as well since that will still be an platform for community driven documentation and tutorials.