//----------------------------------------------------------------------------- // 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, ) /// schedule() - object.schedule(time, command, ); /// 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 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. /// /// @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 /// /// Examples using addField /// /// @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.