Torque Game Engine Documentation
TGE Version 1.5.2

Console Auto-Documentation

See also:: consoleDoc.cc

Using Console Auto-Documentation

There are on the order of three hundred functions exposed to the script language through the console. It is therefore extremely important that they be documented, but due to their number, it is difficult to maintain a seperate reference document.

Therefore, a simple documentation system has been built into the scripting engine. It was initially added by Mark Frohnmayer, and later enhanced by Ben Garney. The scripting engine supports grouping functions and methods, to help organize the several hundred functions, as well as associating a "usage string" with functions and groups.

Note:: The results of a console doc dump will vary depending on when you run it. If you run it, for example, while in the game menu, it won't output any data for the script-defined classes which are defined for gameplay. To get comprehensive documentation, you may need to write a special script that will get all your classes loaded into the scripting engine.

The console documentation system is designed to output a dump of the current state of the scripting engine in a format understandable by Doxygen. It does this by traversing the namespace/class hierarchy in memory at the time of the dump, and outputting psuedo-C++ code equivalent to this class hierarchy.

For the Scripter...

Currently, there is no way to associate usage strings or other documentation with script code like you can with C++ code.

You can get a list of all the methods and fields of an object from any object which inherits from SimObject (ie, every object), as well as the documentation on those objects by using the dump() method from the console:

 ==>$foo = new SimObject();
 ==>$foo.dump();
 Member Fields:
 Tagged Fields:
 Methods:
   delete() - obj.delete()
   dump() - obj.dump()
   getClassName() - obj.getClassName()
   getGroup() - obj.getGroup()
   getId() - obj.getId()
   getName() - obj.getName()
   getType() - obj.getType()
   save() - obj.save(fileName, <selectedOnly>)
   schedule() - object.schedule(time, command, <arg1...argN>);
   setName() - obj.setName(newName)

In the Torque example app, there are two functions defined in common\client\scriptDoc.cs which automate the process of dumping the documentation. They make use of the ConsoleLogger object to output the documentation to a file, and look like this:

Note:: You may want to add this code, or code like it, to your project if you have rewritten the script code in common.

 // Writes out all script functions to a file
 function writeOutFunctions() {
    new ConsoleLogger( logger, "scriptFunctions.txt", false );
    dumpConsoleFunctions();
    logger.delete();
 }
 
 // Writes out all script classes to a file
 function writeOutClasses() {
    new ConsoleLogger( logger, "scriptClasses.txt", false );
    dumpConsoleClasses();
    logger.delete();
 }

For the C++ Coder...

Note:: It is of the utmost important that you keep your usage strings up to date! Usage strings are the only way that a scripter has to know how to use the methods, functions, and variables you expose. Misleading, missing, or out of date documentation will make their lives much harder - and yours, too, because you'll have to keep explaining things to them! So make everyone's lives easier - keep your usage strings clear, concise, and up to date.

There are four types of items which can be documented using the autodocumentation system:

Fields, which are defined using the addField() calls. They are documented by passing a string to the usage parameter.
Field groups, which are defined using the beginGroup() and endGroup() calls. They are documented by passing a descriptive string to the usage parameter.
Method groups, which are defined using beginCommandGroup(), endCommandGroup(), ConsoleMethodGroupEnd(), ConsoleMethodGroupBegin(), ConsoleFunctionGroupEnd(), and ConsoleFunctionGroupBegin().
Methods and functions, which are defined using either SimObject::addCommand(), the ConsoleMethod() macro, or the ConsoleFunction() macro. Methods and functions are special in that the usage strings should be in a specific format, so that parameter information can be extracted from them and placed into the Doxygen output.

You can use standard Doxygen commands in your comments, to make the documentation clearer. Of particular use are @returns, @param, @note, and @deprecated.

Examples using global definitions.

    // Example of using Doxygen commands.
    ConsoleFunction(alxGetWaveLen, S32, 2, 2, "(string filename)"
                    "Get length of a wave file\n\n"
                    "@param filename File to determine length of.\n"
                    "@returns Length in milliseconds.")

    // A function group...
    ConsoleFunctionGroupBegin(Example, "This is an example group! Notice that the name for the group"
                                       "must be a valid identifier, due to limitations in the C preprocessor.");

    // ConsoleFunction definitions go here.

    ConsoleFunctionGroupEnd(Example);

    // You can do similar things with methods...
    ConsoleMethodGroupBegin(SimSet, UsefulFuncs, "Here are some useful functions involving a SimSet.");
    ConsoleMethod(SimSet, listObjects, void, 2, 2, "set.listObjects();")
    ConsoleMethodGroupEnd(SimSet, UsefulFuncs, "Here are some more useful functions involving a SimSet.");

Examples using addField

Note:: Using addCommand is strongly deprecated.

   // Example of a field group.
   addGroup( "Logging", "Things relating to logging." );
   addField( "level",   TypeEnum,     Offset( mLevel,    ConsoleLogger ), 1, &gLogLevelTable );
   endGroup( "Logging" );

How to Generate Console Docs

Console docs can be generated by running the dumpConsoleFunctions() and dumpConsoleClasses(), then running the output through Doxygen. There is an example Doxygen configuration file to do this in HEAD, at doc\doxygen\html\script_doxygen.html.cfg. Doxygen will parse the psuedo-C++ generated by the console doc code and produce a class hierarchy and documentation of the global namespace. You may need to tweak the paths in the configuration file slightly to reflect your individual setup.

Console Auto-Documentation Internals

The consoleDoc system works by inserting "hidden" entries in Namespace and AbstractClassRep; these hidden entries are assigned special type IDs so that they aren't touched by the standard name resolution code. At documentation creation time, the dumpConsole functions iterate through the Namespace hierarchy and the AbstractClassRep data and extract this "hidden" information, outputting it in a Doxygen-compatible format.

Note:

You can customize the output of the console documentation system by modifying these functions:

printClassHeader()
printClassMethod()
printGroupStart()
printClassMember()
printGroupEnd()
printClassFooter()

There was once support for 'overloaded' script functions; ie, script functions with multiple usage strings. Certain functions in the audio library used this. However, it was deemed too complex, and removed from the scripting engine. There are still some latent traces of it, however.