Script Auto-Documentation

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.tscript 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, "ConsoleFunctions.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.

• 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",   TYPEID< ConsoleLogLevel >(),     Offset( mLevel,    ConsoleLogger ) );
endGroup( "Logging" );