Source Code Documentation

#1 I'm not sure what you mean - what are you looking for? I'm assuming not a reference, since doxygen (and now elixir) fulfill that role. A walk-through? A guide? Some sort of PDF version of the same thing?

We are striving to improve the docs but in this case, I really have no idea what direction you're hoping we'll go in with it. :) Can you clarify?

#2 My problem with the documentation is that many times, I will go into the C++ source code and find very little documentation on a particular subject. One such places that I ran into lately is the camera fields and how they are used. When I look at engine/game/camera.h (TGE 1.4), there is no documentation on the variables that exist in the file. They are mostly self-explanatory as to what they represent, but there are certain things that takes testing to find out. Like what are max and min values for a particular value, if any exists. Also, there are sometimes private classes and structs defined in classes that are defined, and used without an explanation.

Also, there are many times where instead of knowing how the objects work in concert, I feel like most of my time is spent trying to figure out how an object gets interacted with. I think what I'd like to be able to see is some type of flow control diagrams to specify how the engine expects to run when certain actions. Something I have done lately is create a flow (sequence) diagram for the startup of a game. I can email this to you (I don't have anywhere to post an image atm) to show you what I am talking about.

Basically, I am looking for something that explains how the engine is working that doesn't require me to dig though source code. Even if it is a high level explanation...

#3 I see what you mean. Well, TDN is the place where that stuff will live. As is, we don't have a lot of it (though it's beginning to accrue) because of the inherited nature of the Torque codebase - it came into our hands almost without comments, and has been gradually getting better over time. (Sometimes in leaps and bounds, too. :))

Can you take a look at Stephen Zepp's networking docs and see if that's more like what you're looking for, so we can at least confirm we're thinking about the same general notion? :)

#4 That is much more what I'm looking for, although in much more depth than the sequence diagram I created. I tried to take just the script-side approach to what happens when a game is initialized (based on the 1.4 release). I wish I had a web server that I could host this from, but the one that I had been using is now locked down for security purposes. I can email this to you if you would like to see it. Basically, Stephen Zepp's document that I saw what much less informal than a traditional sequence diagram. It had the information that I had been looking for, but the presentation is lacking (no insult to his docs, just looking for something more professional). If I get this image file hosted, I'll post back here.

#5 I actually agree with you--not being an artist (or even a presentation level artist), I didn't get the presentation feel I'd like myself! I'd love to have someone eventually re-organize into a more "visually" organized format for sure.

#6 I have recently started to hunker down with TGE to start implementing prototypes of some game play and encountered similar issues. The most frustrating thing I've run into is the utter lack of separation between docs of the base script library and the engine. Ken's books and most resources and threads assume we use the supplied scripts. While these supply a great base to build off of it leaves people with no knowledge of what design metaphors are dictated by design of the engine versus the base game logic that's built into the common scripts. I have no idea with out walking through ever script file and deciphering what it's doing if the things I want to eventually change are engine or script changes.

One great example of this is the mission download functions in scripts. Every tutorial and manual explains how the script functions interact with each other. I have found no documentation on how the engine handles this. What exposed script functions need to be called in what order to connect a client? What are all the events (callbacks) the engine triggers? Another piece I struggle with is things like movement and inventory. No where is there a clear indication if these functions are done through the engine or in scripting.

I'm not even looking for detail interaction diagrams (yet), but higher level component diagrams that would give me an overview of the entire solution. This kind of diagrams and documents would help new developers get to the right areas faster.

PS: This is not meant to be a slam at all. Just feedback on what kind of documentation I would find the most helpful first as a net new developer to TGE.

#7 @Craig: not trying to slam ya, I know it can be hard to know what authors put in as the search terms, but do you mean something like the TGE 1.3 Connection Sequence Overview?

#8 That's a good resource, thanks. It doesn't really hit what I would like to see though. As I think about it there are really two things I'm thinking about.

1) Engine guide from a scripting perspective.
This should have things a view of the give resource from a scripters perspective. Something with a heading like "Making a client connection to a server". It would tell you to create a connection object. It would tell you to call connect function. It would list the events (callbacks) that you should implement as results of calling the connect function. While I can gleam all this from reading sequence diagrams, it takes much more effort and can lead down rat holes. Also for the most part I don't need to know all the inner working of the engine in this level of documentation, only the interactions with the scripting world. I know there is a exposed script function document somewhere but last time I tried to get it all links where broken. It may be what I'm looking for.

2) Function mapping
Things like collision, movement, inventory, player animations, foot-step sounds etc. There are a lot of built in features of the starter.fps which I have no idea are hard coded into the engine itself or are implemented through script classes and datablock callbacks. This might not be necessary if I had #1 for how the engine interacts with scripting land for collisions and movement.

I'm not asking to find specific answers right now. I am slowly (relatively) making my way through the script functions and understanding this. I just wanted to share the feedback that things like the above being prevalent on the TDN start page for TGE would be incredibly useful. I have just started really engaging in working with Torque so many of these things might be available.

#9 @Craig: All good points, and things that are being developed in TDN as part of it's beta period. We do agree that these types of usage instructions can be critical for people not used to digging through code (as well as people that have the experience, but not necessarily the time for complex execution flows).

We've moved in this direction very strongly with TGB, and as things progress you will see more and more articles of this type in the TGE areas of TDN as well.

#10 I think one big problem, aside from the very sparse comments in certain key areas of the source code, is that everything under the "game" folder in the engine is, technically, part of a demo implementation of the Torque engine. This includes "high level" classes as player and vehicle, as well as classes most people consider "core", like GameConnection, GameBase and ShapeBase. The main loop is also located there (in main.cc).

Since there are massive amounts of functionality implemented in the game folder, it's hard to imagine building a game without using it. The demo is also a vital tool in learning how to use the engine.

But the demo itself is far from well documented, and is pretty complex too. People willing to learn more of the script side of things should be directed to the tutorial.base instead of the starter.fps. The tutorial.base use far less scripts to get things done, and is much easier to follow.

I think that creating a more documented tutorial.base (and adding a few extra functionality into it, all documented) could help a lot of newcomers.

I also think the creation of a more simple "game" folder, with very bare functionality (more importantly: a simplier demoPlayer) for educational purposes, could help a great deal. It could also be a good start up for creating games that deviate too much from the demo. But I am aware that it is a lot of work.

#11 @Manoel: That's a great point! I have never really thought about segmenting the c++ code into engine and game sections. I've always segmented game / engine code along the c++ vs script lines. When I get home tonight I'll take another gander through that particular set of code which may help me overall. That is an excellent example of what should be in a high level block diagram.

#12 My $0.02.

I'd love to see a high-level inventory of all the files and classes. Like in common\client\missionDownload.cs. The purpose of this file is... These routines get called during... These are usually overridden by file... Code block blah is dead...

We spend so much time trying to figure out what things were intended for as opposed to what their methods are. I think this is the main frustration when people flame the documentation. I mean, I could probably look up several ways to set a player's mass or even examples of different settings, but what does mass affect? Why does the bounding box get set in the player's datablock if nothing ever uses it? Ok, I probably broke that last one, but I'm speaking hypothetically here.

Probably a better example is in the GuiControls. Which ones disable properly or where does it say that a List Control requires a Scroller or something along those lines.

Anyway, the closest thing I've seen is Edward Maurina's work.

#13 That is something I would love to see too (related to James last post). There are many variables that effect players, vehicles, weapons, and such that I spend more time looking up the correct unit or range of valid values than actually dealing with trying to solve a particular problem I'm having.

A good example is 'mass'. I can trace the mass for a wheeledVehicle back to engine/game/shapeBase.h, but when I find the variable that stores the value, this is the comment I see:

...
   /// @name Physical Properties
   /// @{
   F32 mass;
   F32 drag;
   F32 density;
...

I have no way of telling what the unit value means. Is it in grams, kilograms, pounds? I can put in a printout to find the value that I have, or use the Torque editor, but I'm really at a loss if I want to do some math by hand to figure out why something isn't reacting correctly.

Another big place I find problems with this is when getting back either radians or degrees from an angle calculation...

#14 I just want to make sure that everyone understands the full depth and complexity of things, and the sheer size of TGE when it comes to this type of documentation...more than 500,000 lines of source code, hundreds of classes, and dozens of interacting systems and sub-systems.

TDN is one way to have this knowledge base grow--and one of the things we want to see is that as the community learns particular concepts/execution flows/what have you, they contribute back to the community by describing them in a TDN article.

#15 My $0.02

There's lots of places the Torque Documentation Really falls on it's knees. Two Key examples.

1) The first place people frequently turn is here: [url]http://www.garagegames.com/docs/tge/general/index.php [/url] After all it IS the official documentation. Yet in many places it is known to be: ambigous, under-detailed, outdated, flat-out wrong, or the author freely admits their taking a 'best-guess' and really have know idea what their talking about. (eg. Terrain Texture Editor

If the author of the official documentation doesn't know, whtat chance do the rest of us stand?..

2) I just did a GG search for 'StringBuffer': The closest thing to documentation is an old blog by Ben. If you have a 1.4-dOxygen build, it is listed, but you get the following:

StringBuffer Class Reference
#include <stringBuffer.h>

List of all members.

Public Member Functions
 	StringBuffer (const StringBuffer &copy)
 	Copy constructor. Very important.
Detailed Description
Utility class to wrap string manipulation in a representation independent way.

Length does NOT include the null terminator.

The documentation for this class was generated from the following files:

    * C:/Torque/SDK-1.4/engine/core/stringBuffer.h
    * C:/Torque/SDK-1.4/engine/core/stringBuffer.cc

Generated on Tue Feb 21 13:53:26 2006 for Torque Game Engine by  doxygen 1.4.6-NO

Clearly this is a new(er) class, and the author didn't fully document it. I think this is a prime example of what annoys people, when it comes to Torque Docs.

#16 First I should apologize for not counting to 10 before my last post.

Second what is the overall model for Torque Documentation supposed to be? I would imagine somthing like this, but I'm really not sure:

---
First Time Introduction
0) Included Tutorial Base and good ReadMe's ( First-timer's answer to "I just paid $100 - what now?")

Primary Resources
(Note: these should compliment not copy each other)
1 ) Official Torque Documentation Guide - (High-level narrative explaining whats in Torque and how to use it)
2) dOxygen / Elixer - (Low Level technical details)

Secondary Resources
3) TDN - Wikki - (Semi-Interative medium, how-to's, tutorials, other community contributions to help fill in the gaps from above)
4) Other 3rd-Party Documentation

"Last Resort" Resources
5) The Forums - (Quick answers to specific problems)
---

Once people can effectivly search for an answer in that order, GG will probably save alot of time in answering forum posts. We've recently seen big improvements particularly with the addition of '0' and '3' but '1' and '2' are still weak (don't you have interns? :-P) and the whole idea could maybe be better marketed.

Ok, my $0.02 is up to about a $1.00 now, so I'll stop here. ;-)

#17 Hey guys,

Do keep in mind that we spend a big chunk of our time thinking about how to do better docs, make Torque easier for people to use, etc.

So we already have a TON of good ideas for how to improve things. :)

And the community has discussed it with us at length (in this and many other threads).

The big issue is not ideas, but time, and making sure that we understand what our community wants.

I am very excited to see so many people participating in this thread and bringing lots of good ideas to the table! If you really want to see some specific docs, I encourage you to go on TDN and start writing them. We are extremely busy with things like: finishing constructor, TSE development, preparing for GDC, bringing books on Torque to market, finishing T2D/TGB, working on our next round of game titles (both to fund more technology development AND to make sure that everything we sell has been used in making commercial titles :), doing the next round of website updates, and generally making GG rock yet harder.

We are working on doing all the docs we can but without putting half the company on it, we're only going to be able to keep up with new development. :) Discussions of development philosophy aside, the easiest way to get good docs is for the community to get involved.

It's also a fantastic way to learn about the engine. How do you think I've learned so much about Torque, despite not having been involved in any development at all until version 1.3?

And... in case you haven't noticed, the people in the community who are doing really good work are also the ones that are getting hired, involved with exciting projects, and so on. Ed wrote a lot of cool docs and now he's publishing a book. Melv wrote cool code and now he's a lead dev on T2D. This is not a case of GG getting something for nothing from the community - it's a symbiotic relationship. :)

#18 @Ben - I was going to make a joke about parasites, but couldn't come up with anything that didn't sound offensive. ;)

I'd love to see someone (not necessarily a GG'er) with more guts than I start bird's eye view of view of things in TDN and see where it goes. It is up to the rest of us to document, or perhaps highlight areas that we don't entirely understand that maybe GG doesn't know we don't understand, but in a more organized fashion than the forums.

Dang. It sure feels like I'm volunteering for something...

#19 Well, that answered a question I was about to post about TDN. My initial take on that was there was a more GG employee development behind the documentation (for TGE) that was going into TDN with community support to help flesh out parts that people thought were needed. I didn't realize that TDN was supposed to be mostly user contribution to the documentation.

#20 @Jon: It's both, but it's also..well, both!