177 lines
8.6 KiB
C
Executable File
177 lines
8.6 KiB
C
Executable File
//-----------------------------------------------------------------------------
|
|
// Torque Game Engine
|
|
// Copyright (C) GarageGames.com, Inc.
|
|
//-----------------------------------------------------------------------------
|
|
|
|
// This file exists solely to document consoleDoc.cc
|
|
|
|
/// @page console_autodoc Console Auto-Documentation
|
|
///
|
|
/// @see consoleDoc.cc
|
|
///
|
|
/// @section console_autodoc_using 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.
|
|
///
|
|
/// @subsection console_autodoc_using_script 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:
|
|
///
|
|
/// @code
|
|
/// ==>$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)
|
|
/// @endcode
|
|
///
|
|
/// 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.
|
|
///
|
|
/// @code
|
|
/// // 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();
|
|
/// }
|
|
/// @endcode
|
|
///
|
|
/// @subsection console_autodoc_using_coder For the C++ Coder...
|
|
///
|
|
/// @note <b>It is of the utmost important that you keep your usage strings up to date!</b>
|
|
/// 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:
|
|
/// - <b>Fields</b>, which are defined using the addField() calls. They are documented
|
|
/// by passing a string to the usage parameter.
|
|
/// - <b>Field groups</b>, which are defined using the beginGroup() and endGroup() calls.
|
|
/// They are documented by passing a descriptive string to the usage parameter.
|
|
/// - <b>Method groups</b>, which are defined using beginCommandGroup(), endCommandGroup(),
|
|
/// ConsoleMethodGroupEnd(), ConsoleMethodGroupBegin(), ConsoleFunctionGroupEnd(), and
|
|
/// ConsoleFunctionGroupBegin().
|
|
/// - <b>Methods and functions</b>, 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.
|
|
///
|
|
/// <b>Examples using global definitions.</b>
|
|
///
|
|
/// @code
|
|
/// // 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.");
|
|
/// @endcode
|
|
///
|
|
/// <b>Examples using addField</b>
|
|
///
|
|
/// @note Using addCommand is strongly deprecated.
|
|
///
|
|
/// @code
|
|
/// // Example of a field group.
|
|
/// addGroup( "Logging", "Things relating to logging." );
|
|
/// addField( "level", TypeEnum, Offset( mLevel, ConsoleLogger ), 1, &gLogLevelTable );
|
|
/// endGroup( "Logging" );
|
|
/// @endcode
|
|
///
|
|
/// @section console_autodoc_makingdocs 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.
|
|
///
|
|
/// @section console_autodoc_internals 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()
|
|
///
|
|
/// @note 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.
|