consoleDoc.h

Detailed Description

  1
  2//-----------------------------------------------------------------------------
  3// Copyright (c) 2012 GarageGames, LLC
  4//
  5// Permission is hereby granted, free of charge, to any person obtaining a copy
  6// of this software and associated documentation files (the "Software"), to
  7// deal in the Software without restriction, including without limitation the
  8// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
  9// sell copies of the Software, and to permit persons to whom the Software is
 10// furnished to do so, subject to the following conditions:
 11//
 12// The above copyright notice and this permission notice shall be included in
 13// all copies or substantial portions of the Software.
 14//
 15// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 16// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 17// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 18// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 19// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 20// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 21// IN THE SOFTWARE.
 22//-----------------------------------------------------------------------------
 23
 24// This file exists solely to document consoleDoc.cpp
 25
 26/// @defgroup  script_autodoc Script Auto-Documentation
 27/// @ingroup   console_system Console System
 28///
 29/// @section script_autodoc_using        Using Script Auto-Documentation
 30///
 31/// There are on the order of three hundred functions exposed to the script language
 32/// through the console. It is therefore extremely important that they be documented,
 33/// but due to their number, it is difficult to maintain a seperate reference document.
 34/// 
 35/// Therefore, a simple documentation system has been built into the scripting engine. It
 36/// was initially added by Mark Frohnmayer, and later enhanced by Ben Garney. The
 37/// scripting engine supports grouping functions and methods, to help organize the 
 38/// several hundred functions, as well as associating a "usage string" with functions and
 39/// groups.
 40///
 41/// @note The results of a console doc dump will vary depending on when you run it. If
 42///       you run it, for example, while in the game menu, it won't output any data for
 43///       the script-defined classes which are defined for gameplay. To get comprehensive
 44///       documentation, you may need to write a special script that will get all your
 45///       classes loaded into the scripting engine.
 46///
 47/// The script documentation system is designed to output a dump of the current state
 48/// of the scripting engine in a format understandable by Doxygen. It does this by 
 49/// traversing the namespace/class hierarchy in memory at the time of the dump, and
 50/// outputting psuedo-C++ code equivalent to this class hierarchy.
 51/// 
 52/// @subsection script_autodoc_using_script For the Scripter...
 53///
 54/// Currently, there is no way to associate usage strings or other documentation with script code
 55/// like you can with C++ code.
 56///
 57/// You can get a list of all the methods and fields of an object from any object which inherits
 58/// from SimObject (ie, every object), as well as the documentation on those objects by using the
 59/// dump() method from the console:
 60///
 61/// @code
 62/// ==>$foo = new SimObject();
 63/// ==>$foo.dump();
 64/// Member Fields:
 65/// Tagged Fields:
 66/// Methods:
 67///   delete() - obj.delete()
 68///   dump() - obj.dump()
 69///   getClassName() - obj.getClassName()
 70///   getGroup() - obj.getGroup()
 71///   getId() - obj.getId()
 72///   getName() - obj.getName()
 73///   getType() - obj.getType()
 74///   save() - obj.save(fileName, <selectedOnly>)
 75///   schedule() - object.schedule(time, command, <arg1...argN>);
 76///   setName() - obj.setName(newName)
 77/// @endcode
 78///
 79/// In the Torque example app, there are two functions defined in common\\client\\scriptDoc.tscript
 80/// which automate the process of dumping the documentation. They make use of the ConsoleLogger
 81/// object to output the documentation to a file, and look like this:
 82///
 83/// @note You may want to add this code, or code like it, to your project if you have
 84///       rewritten the script code in common. 
 85///
 86/// @code
 87/// // Writes out all script functions to a file
 88/// function writeOutFunctions() {
 89///    new ConsoleLogger( logger, "ConsoleFunctions.txt", false );
 90///    dumpConsoleFunctions();
 91///    logger.delete();
 92/// }
 93/// 
 94/// // Writes out all script classes to a file
 95/// function writeOutClasses() {
 96///    new ConsoleLogger( logger, "scriptClasses.txt", false );
 97///    dumpConsoleClasses();
 98///    logger.delete();
 99/// }
100/// @endcode
101///
102/// @subsection script_autodoc_using_coder  For the C++ Coder...
103///
104/// @note <b>It is of the utmost important that you keep your usage strings up to date!</b>
105///       Usage strings are the only way that a scripter has to know how to use the methods,
106///       functions, and variables you expose. Misleading, missing, or out of date documentation
107///       will make their lives much harder - and yours, too, because you'll have to keep
108///       explaining things to them! So make everyone's lives easier - keep your usage strings
109///       clear, concise, and up to date.
110///
111/// There are four types of items which can be documented using the autodocumentation system: 
112///   - <b>Fields</b>, which are defined using the addField() calls. They are documented
113///     by passing a string to the usage parameter.
114///   - <b>Field groups</b>, which are defined using the beginGroup() and endGroup() calls.
115///     They are documented by passing a descriptive string to the usage parameter.
116///   - <b>Method groups</b>, which are defined using beginCommandGroup(), endCommandGroup(),
117///     ConsoleMethodGroupEnd(), ConsoleMethodGroupBegin(), ConsoleFunctionGroupEnd(), and
118///     ConsoleFunctionGroupBegin().
119///   - <b>Methods and functions</b>, which are defined using either SimObject::addCommand(),
120///     the ConsoleMethod() macro, or the ConsoleFunction() macro. Methods and functions are
121///     special in that the usage strings should be in a specific format, so
122///     that parameter information can be extracted from them and placed into the Doxygen
123///     output. 
124///
125/// You can use standard Doxygen commands in your comments, to make the documentation clearer.
126/// Of particular use are \@returns, \@param, \@note, and \@deprecated.
127///
128/// <b>Examples using global definitions.</b>
129///
130/// @code
131///    // Example of using Doxygen commands.
132///    ConsoleFunction(alxGetWaveLen, S32, 2, 2, "(string filename)"
133///                    "Get length of a wave file\n\n"
134///                    "@param filename File to determine length of.\n"
135///                    "@returns Length in milliseconds.")
136///
137///    // A function group...
138///    ConsoleFunctionGroupBegin(Example, "This is an example group! Notice that the name for the group"
139///                                       "must be a valid identifier, due to limitations in the C preprocessor.");
140///
141///    // ConsoleFunction definitions go here.
142///
143///    ConsoleFunctionGroupEnd(Example);
144///
145///    // You can do similar things with methods...
146///    ConsoleMethodGroupBegin(SimSet, UsefulFuncs, "Here are some useful functions involving a SimSet.");
147///    ConsoleMethod(SimSet, listObjects, void, 2, 2, "set.listObjects();")
148///    ConsoleMethodGroupEnd(SimSet, UsefulFuncs, "Here are some more useful functions involving a SimSet.");
149/// @endcode
150///
151/// <b>Examples using addField</b>
152///
153/// @note Using addCommand is strongly deprecated.
154///
155/// @code
156///   // Example of a field group.
157///   addGroup( "Logging", "Things relating to logging." );
158///   addField( "level",   TYPEID< ConsoleLogLevel >(),     Offset( mLevel,    ConsoleLogger ) );
159///   endGroup( "Logging" );
160/// @endcode
161///
162/// @section script_autodoc_makingdocs   How to Generate Script Docs
163///
164/// Script docs can be generated by running the dumpConsoleFunctions() and
165/// dumpConsoleClasses(), then running the output through Doxygen. There is an
166/// example Doxygen configuration file to do this at
167/// doc\\doxygen\\html\\script_doxygen.html.cfg. Doxygen will parse the psuedo-C++
168/// generated by the console doc code and produce a class hierarchy and documentation
169/// of the global namespace. You may need to tweak the paths in the configuration file
170/// slightly to reflect your individual setup.
171///
172/// @section script_autodoc_internals Script Auto-Documentation Internals
173/// 
174/// The consoleDoc system works by inserting "hidden" entries in Namespace and
175/// AbstractClassRep; these hidden entries are assigned special type IDs so that
176/// they aren't touched by the standard name resolution code. At documentation
177/// creation time, the dumpConsole functions iterate through the Namespace hierarchy
178/// and the AbstractClassRep data and extract this "hidden" information, outputting
179/// it in a Doxygen-compatible format.
180///
181/// @note You can customize the output of the console documentation system by modifying
182///       these functions:
183///            - printClassHeader()
184///            - printClassMethod()
185///            - printGroupStart()
186///            - printClassMember()
187///            - printGroupEnd()
188///            - printClassFooter()
189///
190/// @note There was once support for 'overloaded' script functions; ie, script functions
191///       with multiple usage strings. Certain functions in the audio library used this.
192///       However, it was deemed too complex, and removed from the scripting engine. There
193///       are still some latent traces of it, however.
194