TorqueEngine
/
Torque2D
zrcadlo https://github.com/TorqueGameEngines/Torque2D.git


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186
							<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Torque2D Reference: Console Auto-Documentation</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="t2d-stylesheet-extra.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr id="projectrow">
  <td id="projectalign">
   <div id="projectname">Torque2D Reference
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.8 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search/",'.html');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
/* @license-end */
</script>
<div id="main-nav"></div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<div id="MSearchResults">
<div class="SRPage">
<div id="SRIndex">
<div id="SRResults"></div>
<div class="SRStatus" id="Loading">Loading...</div>
<div class="SRStatus" id="Searching">Searching...</div>
<div class="SRStatus" id="NoMatches">No Matches</div>
</div>
</div>
</div>
</div>

</div><!-- top -->
<div><div class="header">
  <div class="headertitle"><div class="title">Console Auto-Documentation</div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><dl class="section see"><dt>See also</dt><dd>consoleDoc.cc</dd></dl>
<h1><a class="anchor" id="console_autodoc_using"></a>
Using Console Auto-Documentation</h1>
<p>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.</p>
<p>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.</p>
<dl class="section note"><dt>Note</dt><dd>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.</dd></dl>
<p>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.</p>
<h2><a class="anchor" id="console_autodoc_using_script"></a>
For the Scripter...</h2>
<p>Currently, there is no way to associate usage strings or other documentation with script code like you can with C++ code.</p>
<p>You can get a list of all the methods and fields of an object from any object which inherits from <a class="el" href="class_sim_object.html">SimObject</a> (ie, every object), as well as the documentation on those objects by using the dump() method from the console:</p>
<div class="fragment"><div class="line">==&gt;$foo = <span class="keyword">new</span> <a class="code hl_class" href="class_sim_object.html">SimObject</a>();</div>
<div class="line">==&gt;$foo.dump();</div>
<div class="line">Member Fields:</div>
<div class="line">Tagged Fields:</div>
<div class="line">Methods:</div>
<div class="line">  <span class="keyword">delete</span>() - obj.delete()</div>
<div class="line">  dump() - obj.<a class="code hl_function" href="class_sim_object.html#accd2600060dbaee3a3b41aed4034c63c">dump</a>()</div>
<div class="line">  getClassName() - obj.<a class="code hl_function" href="class_console_object.html#a45b489f436c9d32a63f9c3d62f66c892">getClassName</a>()</div>
<div class="line">  getGroup() - obj.<a class="code hl_function" href="class_sim_object.html#a8cd893920348a8bb5566e86b188bba37">getGroup</a>()</div>
<div class="line">  getId() - obj.<a class="code hl_function" href="class_sim_object.html#aa4a7bd634ae9f58bccb125fe45d86fc9">getId</a>()</div>
<div class="line">  getName() - obj.<a class="code hl_function" href="class_sim_object.html#afef631e435982063322597320f4c817f">getName</a>()</div>
<div class="line">  getType() - obj.<a class="code hl_function" href="class_sim_object.html#a604dfe76701f827f0d0787f1ec29b690">getType</a>()</div>
<div class="line">  save() - obj.<a class="code hl_function" href="class_sim_object.html#a86f7c64cb6f7eba36f8a6e391e29492f">save</a>(fileName, &lt;selectedOnly&gt;)</div>
<div class="line">  schedule() - <span class="keywordtype">object</span>.schedule(time, command, &lt;arg1...argN&gt;);</div>
<div class="line">  setName() - obj.setName(newName)</div>
<div class="ttc" id="aclass_console_object_html_a45b489f436c9d32a63f9c3d62f66c892"><div class="ttname"><a href="class_console_object.html#a45b489f436c9d32a63f9c3d62f66c892">ConsoleObject::getClassName</a></div><div class="ttdeci">const char * getClassName() const</div><div class="ttdef"><b>Definition</b> consoleObject.h:756</div></div>
<div class="ttc" id="aclass_sim_object_html"><div class="ttname"><a href="class_sim_object.html">SimObject</a></div><div class="ttdef"><b>Definition</b> simObject.h:234</div></div>
<div class="ttc" id="aclass_sim_object_html_a604dfe76701f827f0d0787f1ec29b690"><div class="ttname"><a href="class_sim_object.html#a604dfe76701f827f0d0787f1ec29b690">SimObject::getType</a></div><div class="ttdeci">U32 getType() const</div><div class="ttdef"><b>Definition</b> simObject.h:623</div></div>
<div class="ttc" id="aclass_sim_object_html_a86f7c64cb6f7eba36f8a6e391e29492f"><div class="ttname"><a href="class_sim_object.html#a86f7c64cb6f7eba36f8a6e391e29492f">SimObject::save</a></div><div class="ttdeci">virtual bool save(const char *pcFilePath, bool bOnlySelected=false)</div><div class="ttdoc">Save object as a TorqueScript File.</div><div class="ttdef"><b>Definition</b> simObject.cc:417</div></div>
<div class="ttc" id="aclass_sim_object_html_a8cd893920348a8bb5566e86b188bba37"><div class="ttname"><a href="class_sim_object.html#a8cd893920348a8bb5566e86b188bba37">SimObject::getGroup</a></div><div class="ttdeci">SimGroup * getGroup() const</div><div class="ttdef"><b>Definition</b> simObject.h:628</div></div>
<div class="ttc" id="aclass_sim_object_html_aa4a7bd634ae9f58bccb125fe45d86fc9"><div class="ttname"><a href="class_sim_object.html#aa4a7bd634ae9f58bccb125fe45d86fc9">SimObject::getId</a></div><div class="ttdeci">SimObjectId getId(void) const</div><div class="ttdef"><b>Definition</b> simObject.h:621</div></div>
<div class="ttc" id="aclass_sim_object_html_accd2600060dbaee3a3b41aed4034c63c"><div class="ttname"><a href="class_sim_object.html#accd2600060dbaee3a3b41aed4034c63c">SimObject::dump</a></div><div class="ttdeci">virtual void dump()</div><div class="ttdef"><b>Definition</b> simObject.cc:1504</div></div>
<div class="ttc" id="aclass_sim_object_html_afef631e435982063322597320f4c817f"><div class="ttname"><a href="class_sim_object.html#afef631e435982063322597320f4c817f">SimObject::getName</a></div><div class="ttdeci">const StringTableEntry getName(void) const</div><div class="ttdef"><b>Definition</b> simObject.h:624</div></div>
</div><!-- fragment --><p>In the <a class="el" href="namespace_torque.html">Torque</a> 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 <a class="el" href="class_console_logger.html">ConsoleLogger</a> object to output the documentation to a file, and look like this:</p>
<dl class="section note"><dt>Note</dt><dd>You may want to add this code, or code like it, to your project if you have rewritten the script code in common.</dd></dl>
<div class="fragment"><div class="line"><span class="comment">// Writes out all script functions to a file</span></div>
<div class="line">function writeOutFunctions() {</div>
<div class="line">   <span class="keyword">new</span> <a class="code hl_class" href="class_console_logger.html">ConsoleLogger</a>( logger, <span class="stringliteral">&quot;scriptFunctions.txt&quot;</span>, <span class="keyword">false</span> );</div>
<div class="line">   dumpConsoleFunctions();</div>
<div class="line">   logger.delete();</div>
<div class="line">}</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Writes out all script classes to a file</span></div>
<div class="line">function writeOutClasses() {</div>
<div class="line">   <span class="keyword">new</span> <a class="code hl_class" href="class_console_logger.html">ConsoleLogger</a>( logger, <span class="stringliteral">&quot;scriptClasses.txt&quot;</span>, <span class="keyword">false</span> );</div>
<div class="line">   dumpConsoleClasses();</div>
<div class="line">   logger.delete();</div>
<div class="line">}</div>
<div class="ttc" id="aclass_console_logger_html"><div class="ttname"><a href="class_console_logger.html">ConsoleLogger</a></div><div class="ttdef"><b>Definition</b> consoleLogger.h:33</div></div>
</div><!-- fragment --><h2><a class="anchor" id="console_autodoc_using_coder"></a>
For the C++ Coder...</h2>
<dl class="section note"><dt>Note</dt><dd><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.</dd></dl>
<p>There are four types of items which can be documented using the autodocumentation system:</p><ul>
<li><b>Fields</b>, which are defined using the addField() calls. They are documented by passing a string to the usage parameter.</li>
<li><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.</li>
<li><b>Method groups</b>, which are defined using beginCommandGroup(), endCommandGroup(), ConsoleMethodGroupEnd(), ConsoleMethodGroupBegin(), ConsoleFunctionGroupEnd(), and ConsoleFunctionGroupBegin().</li>
<li><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.</li>
</ul>
<p>You can use standard Doxygen commands in your comments, to make the documentation clearer. Of particular use are @returns, @param, @note, and @deprecated.</p>
<p><b>Examples using global definitions.</b></p>
<div class="fragment"><div class="line"><span class="comment">// Example of using Doxygen commands.</span></div>
<div class="line">ConsoleFunction(alxGetWaveLen, S32, 2, 2, <span class="stringliteral">&quot;(string filename)&quot;</span></div>
<div class="line">                <span class="stringliteral">&quot;Get length of a wave file\n\n&quot;</span></div>
<div class="line">                <span class="stringliteral">&quot;@param filename File to determine length of.\n&quot;</span></div>
<div class="line">                <span class="stringliteral">&quot;@returns Length in milliseconds.&quot;</span>)</div>
<div class="line"> </div>
<div class="line"><span class="comment">// A function group...</span></div>
<div class="line">ConsoleFunctionGroupBegin(Example, &quot;This is an example group! Notice that the name for the group&quot;</div>
<div class="line">                                   &quot;must be a valid identifier, due to limitations in the C preprocessor.&quot;);</div>
<div class="line"> </div>
<div class="line"><span class="comment">// ConsoleFunction definitions go here.</span></div>
<div class="line"> </div>
<div class="line">ConsoleFunctionGroupEnd(Example);</div>
<div class="line"> </div>
<div class="line"><span class="comment">// You can do similar things with methods...</span></div>
<div class="line">ConsoleMethodGroupBegin(<a class="code hl_class" href="class_sim_set.html">SimSet</a>, UsefulFuncs, &quot;Here are some useful functions involving a <a class="code hl_class" href="class_sim_set.html">SimSet</a>.&quot;);</div>
<div class="line">ConsoleMethod(<a class="code hl_class" href="class_sim_set.html">SimSet</a>, listObjects, <span class="keywordtype">void</span>, 2, 2, &quot;set.listObjects();&quot;)</div>
<div class="line">ConsoleMethodGroupEnd(<a class="code hl_class" href="class_sim_set.html">SimSet</a>, UsefulFuncs, &quot;Here are some more useful functions involving a <a class="code hl_class" href="class_sim_set.html">SimSet</a>.&quot;);</div>
<div class="ttc" id="aclass_sim_set_html"><div class="ttname"><a href="class_sim_set.html">SimSet</a></div><div class="ttdef"><b>Definition</b> simSet.h:102</div></div>
</div><!-- fragment --><p><b>Examples using addField</b></p>
<dl class="section note"><dt>Note</dt><dd>Using addCommand is strongly deprecated.</dd></dl>
<div class="fragment"><div class="line"><span class="comment">// Example of a field group.</span></div>
<div class="line">addGroup( <span class="stringliteral">&quot;Logging&quot;</span>, <span class="stringliteral">&quot;Things relating to logging.&quot;</span> );</div>
<div class="line">addField( <span class="stringliteral">&quot;level&quot;</span>,   TypeEnum,     Offset( mLevel,    <a class="code hl_class" href="class_console_logger.html">ConsoleLogger</a> ), 1, &amp;gLogLevelTable );</div>
<div class="line">endGroup( <span class="stringliteral">&quot;Logging&quot;</span> );</div>
</div><!-- fragment --><h1><a class="anchor" id="console_autodoc_makingdocs"></a>
How to Generate Console Docs</h1>
<p>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.</p>
<h1><a class="anchor" id="console_autodoc_internals"></a>
Console Auto-Documentation Internals</h1>
<p>The consoleDoc system works by inserting "hidden" entries in <a class="el" href="class_namespace.html">Namespace</a> and <a class="el" href="class_abstract_class_rep.html">AbstractClassRep</a>; 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 <a class="el" href="class_namespace.html">Namespace</a> hierarchy and the <a class="el" href="class_abstract_class_rep.html">AbstractClassRep</a> data and extract this "hidden" information, outputting it in a Doxygen-compatible format.</p>
<dl class="section note"><dt>Note</dt><dd>You can customize the output of the console documentation system by modifying these functions:<ul>
<li>printClassHeader()</li>
<li>printClassMethod()</li>
<li>printGroupStart()</li>
<li>printClassMember()</li>
<li>printGroupEnd()</li>
<li>printClassFooter()</li>
</ul>
</dd>
<dd>
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. </dd></dl>
</div></div><!-- contents -->
</div><!-- PageDoc -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by&#160;<a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.8
</small></address>
</body>
</html>