updated "how to write docs" page.

TorqueScriptDocs/html/md_documenting_ScriptPage.html

@@ -41,38 +41,15 @@
 <div class="title">Documenting TorqueScript </div>  </div>
 </div><!--header-->
 <div class="contents">
-<div class="textblock"><p>notes</p>
-<ul>
-<li>TDN docs expounded</li>
-<li>dox must have comments<ul>
-<li>cannot be md in the open</li>
-</ul>
-</li>
-<li>md is not comments<ul>
-<li>but can have "@" codes</li>
-</ul>
-</li>
-<li>pages<ul>
-<li>can be made with markdown naturally</li>
-<li>or with a comment block starting with @page</li>
-</ul>
-</li>
-</ul>
-<h2>Introduction</h2>
-<p>This references describes how the TorqueScript manual is created. It covers the tool used, the location of the docs source, and the process of adding or editing all the documentation types. The end goal is a single manual that can be referenced on-line or downloaded. The manual created contains information about classes and functions, and also information about operators, sub-systems, general information, etc.</p>
-<p>As a bit of background, TorqueScript is a scripting language written specifically for Torque. The compiling and running of the script code is a part of the engine itself. Our goal here is to extract just the internal documentation that refers to TorqueScript functions and classes (which are really "bindings" to C++ functions and classes), etc.</p>
-<p>The manual is created using <a href="doxygen.org">Doxygen</a>, so its helpful to get some experience with that tool and also to refer to its manual for documenting features. This reference only covers Doxygen lightly but probably enough to get started. It also covers our use of its high-level features to get what we want. For now, we'll just say that Doxygen is a feature-rich tool to extract documents out of a code base. Doxygen recognized specialed comment sections designed for this purse. These sections are explicity about return types from functions, code examples, and other features. The end result is an organized series of pages, like an index, but with descriptions and concepts explained and with links to each other as a cross-reference.</p>
-<blockquote class="doxtable">
-<p>Normally, Doxygen is used to create a cross-referenced document for a C++ code base. Note that our desire here is</p>
-<p></p>
-</blockquote>
-<p>to document a class and function binding library, along with the syntax, operators, types, etc. of TorqueScript. But Doxygen is so useful and capable that it was worth working out a way to use it for our purposes. As a matter of fact, we can also produce a Torque2D engine document from the same code base!</p>
-<p>The docs can be output in an HTML form, among many others including pdf or chm.</p>
+<div class="textblock"><h2>Introduction</h2>
+<p>This references describes how the TorqueScript manual is created. It covers the tool used, the location of the documentation text, and the process of adding or editing all the documentation types. The end result is a single manual that can be referenced on-line or downloaded, and that contains information about classes, functions, operators, sub-systems, general information, etc.</p>
+<p>As a bit of background, TorqueScript is a scripting language written specifically for Torque. The compiling and running of the script code is a part of the engine itself. Our goal here is to extract just the internal documentation that refers to TorqueScript.</p>
+<p>The manual is created using <a href="doxygen.org">Doxygen</a>, so its helpful to get some experience with that tool and also to refer to its manual for documenting features. This reference only covers Doxygen lightly but probably enough to get started. It also covers our use of its high-level features to get what we want. For now, we'll just say that Doxygen is a feature-rich tool to extract documents out of a code base. A C++ comment can be laced with special commands which Doxygen recognizes. These sections are explicity about return types from functions, code examples, and other features. The end result is an organized "manual" of pages, with the code explained and with cross-referenced links between the concepts. The docs can be output in many formats including HTML, pdf, and chm.</p>
 <h2>Documentation As an Ongoing Project</h2>
-<p>First, thanks in advance for any contribution to our collective knowledge to the TorqueScript docs! Besides our collective wisdom, there are also fertile bits of information over at the <a href="http://tdn.garagegames.com/wiki/TDN_Home">Torque Developer Network</a> (free login required) that could be yanked over.</p>
-<p>While many of the basics are done, there is always more to cover. Whether you know of tricks for creating better game loops with less, gotchas to avoid, or mistake in the docs that should be corrected, we could use your help. The goal of this project is to collect great information about Torque2D and get it into the source itself, where it will live with the code. The docs should include classes, functions, and even architectural design.</p>
+<p>First, thanks in advance for any contribution to our collective knowledge to the TorqueScript documention! There are also fertile bits of information over at the <a href="http://tdn.garagegames.com/wiki/TDN_Home">Torque Developer Network</a> (free login required) that could be yanked over. For instance, there are TDN sections for each <a href="http://tdn.garagegames.com/wiki/TGB/Reference">class</a>, and each <a href="http://docs.garagegames.com/tge/official/content/documentation/Reference/Console%20Functions/TorqueScript_Console_Functions_21.html">global function</a>, at least.</p>
+<p>While many of the basics are done, there is always more to cover. Whether you know of tricks for creating better game loops, gotchas to watch for, a bit of architecture that has gone undocumented, or anything else really, we could use your help. The goal of this project is to collect great information about Torque2D and get it into the source itself, where it will live with the code.</p>
 <h2>How to "Compile" the Torque2D Manual</h2>
-<p>If we want to see our docs as you go, the first thing you'll need is the ability to see the output from Doxygen as you make edits. Once you know how, this can be done in less than 10 seconds. Here are the steps:</p>
+<p>If we want to see our docs as we go, the first thing we'll need is the ability to see the output from Doxygen as we make edits. Once we know how, this can be done in less than 5 seconds. Here are the steps:</p>
 <ol type="1">
 <li>Go to the directory <code>Torque2D/tools/documentation</code> You should see, among files and directories<ul>
 <li><code>config</code> - a directory containing a few files that are used to tell Doxygen how to proceed.</li>
@@ -81,25 +58,21 @@
 </ul>
 </li>
 <li>Start a command line tool in the <code>documentation</code> directory. I use Windows PowerShell (which I open by clicking the Window's Start menu and typing "powershell" into the search box).</li>
-<li>Run Doxgyen from a command line feeding it the <code>config\torqueScriptReference.cfg</code> file. I also like to pipe the output to a file, as you see below. Doxygen is very verbose! <div class="fragment"><div class="line">&gt; .\doxygen.exe .\config\torqueScriptReference.cfg &gt; .\output\info-ts.log</div>
+<li>Run Doxgyen from a command line feeding it the <code>config\torqueScriptReference.cfg</code> file. I also like to pipe the output to a file, as you see below. Doxygen is very verbose! <div class="fragment"><div class="line">&gt; .\doxygen.exe config\torqueScriptReference.cfg &gt; output\info-ts.log</div>
 </div><!-- fragment --></li>
-<li>Afterwards, the directory <code>output/torqueScriptDocs</code> should have been produced, and inside of it, you should have both <code>html</code> and <code>xml</code> output. To see the results, click <code>html/index.html</code> to open it in a browser. Click around and get accusomted to the manual if you haven't already. As you make changes, "recompile" the manual and simply refresh in your browser to see the results.</li>
+<li>Afterwards, the directory <code>output/torqueScriptDocs</code> should have been produced, and inside of it, you should have both <code>html</code> and <code>xml</code> output. To see the results, click <code>html/index.html</code> to open it in a browser. Click around and get accustomed to the manual if you haven't already. As you make changes, "recompile" the manual and simply refresh in your browser to see the results.</li>
 </ol>
-<h2>About Doxygen "Compounds"</h2>
-<p>There are three Doxygen concepts &ndash; called "compounds" in Doxygen vernacular &ndash; that we use to document TorqueScript. These are symbols, modules, and pages. For us, "symbol" documents are materials attached directly to classes, member functions, and global functions. Here is <a class="el" href="classSimSet.html">SimSet</a> as an example of documented class methods that roll-up into a class page. The <a href="classes.html">list of classes</a> is built by Doxygen as well. This is the most common type of documentation by far. You write them in command-laced comments directly above the symbol.</p>
-<p>Then we use "module" documents &ndash; interchangeably called "group" documents in Doxygen vernacular &ndash; to keep together clusters of related global function, like vector math, string functions, or even string operators. Within each grouping, the bulk of the actual function documentation is also symbol documentation. If you go to the <a href="modules.html">modules</a> page, you will see all of the groups listed. Note that they mostly cover global functions, but also operators, data types, etc.</p>
-<p>Module documents are nice because they are a bit more free-form. You can also add any amount of extra documentation for the entire group. For instance, in the engine manual (not the TorqueScript one in this case), all the classes than form the Taml subsystem are kept in a group. But more importantly, a lengthy white paper on using the Taml module of Torque2D is kept within the group document as the "detailed description". The point is that module/group docs can have lots of connective information about a sub-sytem and still cross-reference with any symbols in your code.</p>
-<p>Finally, most rare of all we use Doxygen "pages" to write up information. Pages are the best bet when their content isn't really connected to the software architecture or any particular class or functions. This very document is an example. All the "loose" pages are kept under the <a href="pages.html">"related pages"</a> tab by Doxygen. Even though the pages aren't related to any one symbol of grouping, mentioning particular functions and other symbols will create cross references to those symbols.</p>
 <h2>About ScriptBinding and ScriptPage Files</h2>
-<p>In order to have Doxygen create two kinds of documents with only one code base, some cleverness was required. Without getting too deep here, documenting TorqueScript "the language binding" isn't the natural purpose of Doxygen! However, we were able to achieve a pretty strong manual just by using a few techniques. To keep you from getting confused &ndash; we hope it's not a problem, but better safe than sorry &ndash; this short section is a quick-and-dirty view of some of those techniques used. If something doesn't seem to work like you expected, this section may help.</p>
-<p>The main rule to follow here is that most TorqueScript documentation is in the ScriptBinding.h files. For instance, comments in <code>SimObject_ScriptBinding.h</code> are gleened by Doxygen, but not comments in <code>SimObject.h</code> or <code>SimObject.cpp</code>. Other docs may be in ScriptBinding.* or ScripPage.* files. Because the ScriptBinding.h files contain the TorqueScript binding functions and not the engine code, this is an ideal place to focus Doxygen to get only TorqueScript information. (Otherwise, it would try to add reference docs to engine-specific code as well. We show Doxygen the opposite docs when building a manual for the engine.)</p>
-<p>You may notice a few binding functions (ConsoleMethod(), ConsoleFunction(), etc.) not in the ScriptBindings. You may also notice that these don't produce docs yet. This is for the reason stated above. (The code is actively being re-arranged and is almost complete. For what it's worth, the idea of the ScriptBbinding files preceeds the new documentation.)</p>
-<p>The next rule is that .dox files are not read by C++ compilers but are read as if code files by Doxygen. The extension is specific to Doxygen as a matter of fact. Code and comments in these files are read (by Doxygen) as if live code, however. Hence they are a great place to put module/group documents that don't fit neatly in any one class or function group. The .dox files are often kept in the directory with the code they relate to. They will be found and read, wherever they are, by Doxgyen. If the .dox file is for TorqueScript it should contain <code>_ScriptPage.</code> in its name. Otherwise, it will be assumed to be a page for the engine instead.</p>
-<p>A second use of the .dox file was to create pseudo-code for TorqueScript &ndash; code that isn't really part of building the TorqueScript interpreter nor the engine but that Doxygen picks up and parses as if real code. Look at the file <code>Torque2D\engine\source\console\core_scriptBinding.dox</code> for a great place to create a list of TorqueScript operators (new, SPC, TAB, etc) and TorqueScript types (Integer, Boolean, String, Vector) that aren't real code but that help create a complete manual for TorqueScript.</p>
-<p>Finally, the "page" files are often kept as markdown (extension .md). Because a page file isn't related to any classes, functions, or whatever, its text does not need to be wrapped into a comment. Put differently, there is no need for doxygen commands (@param, @see, @defgroup, etc.) The text is pure markdown with a few exceptions which are probably Doxygen bugs, and some of those are listed at the end of this doc. By being pure markdown &ndash; that is without requiring a surrounding comment block &ndash; they are a little easier to manipulate. These pages can only show as single pages in the "Related Pages" tab of a Doxygen manual, so they are limited. And even though they aren't connected to any code symbols, they will link (automatically usually) to any symbols mentions.</p>
-<h2>Documenting Classes and Methods</h2>
-<p>As mentioned above, documenting symbols is by far the bulk of the good documentation. Each class, method, or function can have a description as complex as you want. (Also as stated above, the global functions will ultimately end up in a "module" section of the manual but the functions themselves are documented as symbols.) For methods and functions, you can (and should) explicitly state the parameters and return type. You can put example code with each symbol if it helps. Finally, we should probably keep a "see also" section for related methods and functions.</p>
-<p>Here is an edited version of comments for <a class="el" href="classSimObject.html#a929e1325a515b279faca90a65028782e">SimObject::getId()</a> as an example of how to accomplish several of these practices:</p>
+<p>We create two manuals with one Torque2D code base &ndash; one is an engine reference and the other is this TorqueScript language reference. This is unusual for Doxygen, and in order to have it create both, some cleverness was required. However, we were able to achieve a pretty strong manual just by using a few techniques.</p>
+<p>First, know that a file should be suffixed with <code>ScriptBinding.*</code> or <code>ScriptPage.*</code> to be included. We tell Doxygen to only read these files while creating the scripting manual (and vice-versa when creating the engine manual). As you may expect then, these specially-named files contain the TorqueScript-related functions and not the engine code. When Doxygen sees a file of code, it will add them to the doc, so it is important to not have Doxygen run on any file that you don't want documented at the time.</p>
+<p>As an example, most TorqueScript methods and functions are in files suffixed with <code>ScriptBinding.h</code>. Comments in <code>SimObject_ScriptBinding.h</code> are gleened by Doxygen, but not comments in <code>SimObject.h</code> or <code>SimObject.cpp</code>.</p>
+<blockquote class="doxtable">
+<p>You may notice a few binding functions (ConsoleMethod(), ConsoleFunction(), etc.) not in the ScriptBinding files. You may also notice that these don't produce docs. These are older bindings, which work but have not been updated to the new format. (For what it's worth, migrating them to ScriptBinding files isn't just for documentation purposes.)</p>
+<p></p>
+</blockquote>
+<h2>Documenting Classes, Methods, and Global Functions</h2>
+<p>Documenting code "symbols" is by far the bulk of the good documentation. Each class, method, or function can have a description as complex as you want. For methods and functions, you can (and hopefully will) explicitly state the parameters and return type. You can put example code with each symbol if it helps. Finally, we should probably keep a "see also" section for related methods and functions.</p>
+<p>Here is an edited version of comments for <a class="el" href="classSimObject.html#a929e1325a515b279faca90a65028782e">SimObject::getId()</a> as an example of how to accomplish several of these practices. Almost every type of symbol doc is included here:</p>
 <pre class="fragment">/*! get the unique numeric ID -- or "handle" -- of this object.
 
     @param param1 a pretend param for this call since there wasn't one :)
@@ -141,49 +114,54 @@ ConsoleMethodWithDocs(SimObject, getId, ConsoleInt, 2, 2, ())
 </pre><p>Knowing a bit about Doxygen does help, but you can get pretty far just trying the ideas above and experimenting. The following are several notes about the above example:</p>
 <ul>
 <li>The entire doxygen comment section is surrounded by <code>/*!</code> and <code>*/</code> comment enclosings. There are other options, but this author prefers to set these at beginning and end and then not have to decorate every line.</li>
+<li>This type of description is placed directly above the symbol it is documenting.</li>
 <li>We have a <code>@param</code>, <code>@return</code>, and <code>@see</code> (for "see also" sections). Those are easy.</li>
 <li>Any other text is just part of the detailed description.</li>
-<li>We can create "sections" just like the "param" and "return" sections by using <code>@par &lt;section&gt;</code> like we did with "@par Caveat". Just remember to start the paragraph immediately after that line.</li>
+<li>We can create "sections" just like the <code>param</code> and <code>return</code> sections by using <code>@par &lt;section&gt;</code> like we did with "@par Caveat". Just remember to start the paragraph immediately after that line.</li>
 <li>We also wanted to create a couple of examples so we start each one with "@par Example" and follow that with a block of code between "@code" and "@endcode".</li>
-<li>We can also use backticks "`" around a phrase to make it represent in-line code.</li>
-<li>Now in <em>real</em> code sections between "@code" and "@endcode" any text goes. But in regular text or even in in-line code sections, we have to use two percent signs to create one. This is because Doxygen sees percent as a "meta-character" and swallows it. To show a single percent, "escape" percent with two in a row.</li>
-<li>Note that I'm using "+" to start a list. You can use "*" or "-" just like in markdown. However, because some people like to have a "*" at the beginning of every line of comments, Doxygen likes to eat those up, so it's best to just avoid them. This author just prefers "+" to "-" for lists also.</li>
+<li>We can also use backticks around a phrase to make it represent in-line code.</li>
+<li>In Doxygen, percent <code>%</code> is a command character. TorqueScript is also full of <code>%</code> however. In code sections between "@code" and "@endcode" you won'th have a problem, but in regular text or even in in-line code sections, we have to use two percent signs to create one.</li>
+<li>Note that I'm using <code>+</code> to start a list. You can use <code>*</code> or <code>-</code> just like in markdown. However, because some people like to have a <code>*</code> at the beginning of every line of comments, Doxygen likes to eat those up, so it's best to just avoid them.</li>
 <li>Obvious function names and class names will be automatically cross-referenced. They are "obvious" when they have a camel case letter in them somewhere. If your function does not, try putting "::" in front of it or "()" after it. To reference something in another class, you have to use className::methodName. Doxygen explains all this in its docs. One last point though: let's suppose you want to avoid a link. Use "%" in front of the camel cased word that happens to be another class or function.</li>
 </ul>
 <h2>Documenting Global Function Groups</h2>
-<p>All of the global functions in TorqueScript are being documented into "groups." We also take advantage of Doxygen's ability to have subgroups here. All of the function groups are a subgroup of the TorqueScriptFunctions main group. (There are other main groups not related to global functions.)</p>
+<p>All of the global functions in TorqueScript are documented individually as described above. However, it is best to keep related functions clustered together. Doxygen provides the idea of a "group" (which is sometimes called a "module") to cluster things, so we use it to group global function categories. See the <a href="modules.html">modules</a> page for what we mean.</p>
+<p>We also take advantage of Doxygen's ability to have groups within groups to keep better organized. All of the categories groups are a subgroup of the <code>TorqueScriptFunctions</code> main group, as you might have noticed if you clicked the modules link above.</p>
 <p>To document a group of functions, let's suppose they are in the same file together. If they are not, we can modify the following formulas. Go to that file, say the console output functions in <code>output_ScriptBinding.h</code>. Near the top of the file, before any functions, tell Doxygen this will be a group as follows:</p>
 <pre class="fragment">/*! @defgroup ConsoleOutputFunctions Console Output
     @ingroup TorqueScriptFunctions
     @{
 */
-</pre><p>What this does is start a new group <code>ConsoleOutputFunctions</code> and also gives it the more human-readable name "Console Output". Then it puts this group within the <code>TorqueScriptFunctions</code> main group. And finally it starts the grou with ``.</p>
+</pre><p>What this does is start a new group <code>ConsoleOutputFunctions</code> and also gives it the more human-readable name "Console Output". Then it puts this group within the <code>TorqueScriptFunctions</code> main group. And finally it starts the group with "@{".</p>
 <p>Now go to the bottom of the file, somewhere after all the functions and put the following:</p>
 <pre class="fragment">/*! @} */ // group ConsoleOutputFunctions
 </pre><p>This line ends the group with "@}". The comment after that is just to be friendly.</p>
 <p>This should effectively put all the documented functions between "@{" and "@}" into a group together.</p>
-<h2>Documenting Operations, Types, etc.</h2>
-<p>Another type of module documentation is for non-functions. This includes TorqueScript types (String, Boolean, etc.) and operators (SPC, new, etc.).</p>
-<p>To do this, we are playing a bit of a trick. Remember that Doxygen was not created to document your language that you created (such as TorqueScript). What we will do is make a psuedo-code file full of pretend C++ constructs, called <code>Torque2D\engine\source\console\core_ScriptBinding.dox</code> The C++ compiler won't be interested, but when Doxygen sees the file it will parse it as real code.</p>
-<p>The solution we have employed is to have one special file located in the same directory as the TorqueScript interpreter code. C++ compilers will not bother to compile a .dox file but doxygen will read it. For all practical purposes, though, this is a C++ file in form.</p>
-<p>We will not go into the details here, but read that file and add to it to create lists of operators or types in groups.</p>
 <h2>Documenting Sub-Systems</h2>
-<p>Our final module type is sub-systems of the engine, such as Taml or the Module Manager, etc. Because these are not related to one specific class, they were placed in individual files with the .dox extension.</p>
-<p>While there are no examples of TorqueScript sub-systems documented yet, we can see an example of Torque2D engine docs for a sub-system. Check out <code>Torque2D\engine\source\persistence\taml\taml.dox</code> as an example.</p>
-<p>Note that the docs are currently kept close to the classes that form the system, if possible. Specifically, they are put in the same directory as the classes. The compiler will ignore files ending in .dox but Doxygen won't. In the case of the taml file, it is a mostly markdown formatted file. Section headers, URLs and other markdown data is present in standard form. However, the entire file (of markdown) is placed in a Doxygen comment block with <code>/*!</code> at the top and <code>*/</code> at the bottom. Then the block was marked as creating a "group" known as "tamlGroup" like so:</p>
+<p>A Sub-system is a collection of components, such as classes and functions, that work together to form a bigger whole. An example is the Taml module or the Module Manager. This is another great use of the "group" concept (see above for another example). This time, however, we want to write a description of the sub-system itself. Doxygen supports this by letting you document the group, as if it were a code symbol itself. These docs then become the "detailed description" portion of the group page.</p>
+<p>The question is where should all this text be placed? It isn't related directly to one class. The solution is to make a special file for the sub-system documentaion and place it near the other code to which it relates. Typically, the files (classes) that make up a sub-system are placed in a directory together, so this is often a great place for the sub-system "group" file.</p>
+<p>The file should end with <code>.dox</code> which is a special Doxygen file extension. Doxygen will read these files as if they were code, but the C++ compiler will not. (And remember, our files should also end in <code>ScriptPage.*</code> to be seen while building the scripting manual. Therefore, your file should be something like <code>mySubSystem_ScriptPage.dox</code>.</p>
+<p>While there are no examples of TorqueScript sub-systems documented yet, we can see an example for the Torque2D engine manual at <code>Torque2D\engine\source\persistence\taml\taml.dox</code>. (Note the lack of a ScriptPage suffix because this is not scripting docs!) In the case of the taml file, it is mostly a markdown formatted file. Section headers begin with #, and URLs and other markdown data are also marked appropriately.</p>
+<p>However, the entire file markdown file is placed in a Doxygen comment block with <code>/*!</code> at the top and <code>*/</code> at the bottom. The entire file effectively becomes a giant comment. We then add to the comment Doxygen commands to turn the entire file into a "group" description like so at the top:</p>
 <div class="fragment"><div class="line"><span class="comment">/*! @defgroup tamlGroup TAML Reference</span></div>
 <div class="line"><span class="comment">  ... the entire contents in markdown</span></div>
 <div class="line"><span class="comment">*/</span></div>
-</div><!-- fragment --><p>For a little cross-referencing sweetness, classes related to this sub-system were marked with the following comment</p>
+</div><!-- fragment --><p>For a little cross-referencing sweetness, classes related to this sub-system were marked with the following comment. This causes them to be included in the sub-system "group" and have a link each to the group description.</p>
 <div class="fragment"><div class="line"><span class="comment">/// @ingroup tamlGroup</span></div>
 <div class="line"><span class="comment"></span><span class="comment">/// @see tamlGroup</span></div>
-</div><!-- fragment --><p>This will bring a reference to the marked class into the module document.</p>
-<p>Again, this was done for an engine subsytem, but the same <em>could</em> be done for TorqueScript systems or modules.</p>
+</div><!-- fragment --><p>Again, this was done for an engine subsytem, but the same <em>could</em> be done for TorqueScript systems or modules.</p>
 <h2>Documenting General Information</h2>
-<p>Our final category of document is the "page" as described above. Two great examples page documentation are the Syntax Guide and the "how to" you are currently reading. To create these, simply create a markdown file (extension .md). The level-1 header of the file (the section header that starts with a single hash #), will be the name of the page in the final document.</p>
-<p>This markdown file should be suffixed with <code>_ScriptPage.*</code>, for instance "syntax_ScriptPage.md"</p>
+<p>Sometimes your docs are not really related to any one class, or even one sub-system. This page on creating documents is one example. The TorqueScript Syntax page is another.</p>
+<p>Doxygen provides one last concept we will talk about, called a "page." The way we keep pages is the most markdown-like and the least like Doxygen comments yet. To create these, simply create a markdown file (extension .md). The top header of the file (the section header that starts with a single hash #), will be the name of the page in the final document.</p>
+<p>As usual, this markdown file should be suffixed with <code>_ScriptPage.*</code>, for instance "syntax_ScriptPage.md"</p>
 <p>We try to keep the pages close to the code it relates to, but rememer "pages" tend to be unrelated to particular classes, modules, etc. Therefore the pages have been kept in the <code>Torque2D\engine\source\console</code> directory since it most represents the entire TorqueScript interpreter in general. For example this document is <code>documenting_ScriptPage.md</code> within the <code>console</code> directory.</p>
 <p>The content of the file requires no doxygen commands such as @defgroup or @param (although @code has come in useful as will be described in the appendix). It is read as pure markdown (with a few exceptions). Doxygen will successfully create links for any symbols is recongizes however. (To force the link off, put a percent % in front of the text.</p>
+<h2>Documenting Operations, Types, etc.</h2>
+<p><em>This topic is more advanced. You can possibly skip it.</em></p>
+<p>Another type of module documentation is for non-functions. This includes TorqueScript types (String, Boolean, etc.) and operators (SPC, new, etc.).</p>
+<p>To do this, we are playing a bit of a trick. Remember that Doxygen was not created to document your language that you created (such as TorqueScript). What we will do is make a psuedo-code file full of pretend C++ constructs, called <code>Torque2D\engine\source\console\core_ScriptBinding.dox</code> The C++ compiler won't be interested, but when Doxygen sees the file it will parse it as real code.</p>
+<p>The solution we have employed is to have one special file located in the same directory as the TorqueScript interpreter code. C++ compilers will not bother to compile a .dox file but doxygen will read it. For all practical purposes, though, this is a C++ file in form.</p>
+<p>We will not go into the details here, but read that file and add to it to create lists of operators or types in groups.</p>
 <h2>Converting "Old" Documents to "New"</h2>
 <p><em>If you read the appendix on how documenting TorqueScript is done with Doxygen, this may make more sense to you.</em></p>
 <p>You may find, from time to time, snippets of an older form of documentation for TorqueScript in the code base. One of the Appendices explains in more detail, but basically, documents used to be a "usage" string as part of a macro call like this:</p>
@@ -210,13 +188,25 @@ ConsoleMethodWithDocs(SimObject, getId, ConsoleInt, 2, 2, ())
 <ul>
 <li>GitHub flavored markdown provides for easier numbered lists. Simply start each item with <code>1.</code> and they will be re-numbered. However this does not work in Doxygen. Number each item correctly.</li>
 </ul>
+<ul>
+<li><b>Blockquotes</b> markdown lets you put a <code>&gt;</code> at the beginning of a paragraph. All the following lines will be part of one section of blockquotes. However, in Doxygen, you appears to need a <code>&gt;</code> after every new line.</li>
+</ul>
 <h2>Appendix B. How Documenting TorqueScript Works</h2>
 <p>For several years, Torque2D produced a TorqueScript manual in a different way than described in this reference.</p>
 <p>As a bit of back story, don't forget that we want to be able to produce a manual for Torque2D's C++ engine as well as produce a manual for TorqueScript. So running Doxygen on the code produced only the Torque2D manual. This is "as it should be."</p>
 <p>Back then, to create a TorqueScript manual one would compile Torque2D, and run it. From within the program one would call <a class="el" href="group__ConsoleDocFunctions.html#ga073aa7e25d9774f58ae9704084b732ad">dumpConsoleFunctions()</a> and other functions to produce a "psuedo-code" output file. The file was suspiciously like a program itself, complete with documentation of the "functions" and "classes". This file would then be run through Doxygen and viola!, a second reference manual was produced.</p>
 <p>The problem with using the above method had two specific drawbacks worth removing if possible. First, it required several steps &ndash; compiling the code, running it against some script calls, running Doxygen on the output of the dump &ndash; and so it was impractical to add and modify new docs as easily as Doxygen is designed to do.</p>
 <p>Second, the script documents had to be hidden from Doxygen on the normal pass lest it include confusing bits of information in the engine docs! To do so, the docs appeared in a (large) string for each TorqueScript call or class. This was harder to work with than simple comments. A less important issue, but still a real one, was the possibility that all these strings, compiled into the engine, could be expensive in space. (Though the strings could be skipped at compile time if TORQUE_SHIPPING was defined.)</p>
-<p>The new solution employed a different clever solution. Now, the TorqueScript function bindings are documented just like any other code &ndash; in comment sections with the code. And "compiling" the documents is no harder than running Doxygen on the code base. The way we get Doxygen to pick between documenting the engine or TorqueScript is that TorqueScript functions are in special files ending with <code>_ScriptBinding.*</code> or <code>_ScriptPage.*</code>. These files are skipped when creating docs for the engine. Likewise, they are the only files used when creating the script reference. </p>
+<p>The new solution employed a different clever solution. Now, the TorqueScript function bindings are documented just like any other code &ndash; in comment sections with the code. And "compiling" the documents is no harder than running Doxygen on the code base. The way we get Doxygen to pick between documenting the engine or TorqueScript is that TorqueScript functions are in special files ending with <code>_ScriptBinding.*</code> or <code>_ScriptPage.*</code>. These files are skipped when creating docs for the engine. Likewise, they are the only files used when creating the script reference.</p>
+<blockquote class="doxtable">
+<p>Normally, Doxygen is used to create a cross-referenced document for a C++ code base. Note that our desire here is to document a class and function binding library, along with the syntax, operators, types, etc. of TorqueScript. But Doxygen is so useful and capable that it was worth working out a way to use it for our purposes. As a matter of fact, we can also produce a Torque2D engine document from the same code base!</p>
+<p></p>
+</blockquote>
+<h2>Appendix C. Some Unusual Doxygen Facts</h2>
+<p>Doxygen tries to be a lot of things in a lot of formats, and this has sometimes caused odd edge-case bugs. This is a quick list of a few quirks I wanted to save somewhere:</p>
+<p>Of course, normally Doxygen data is saved in comments and the <code>@</code> commands are how you tell it about constructs from parameter lists to what group to put things in. But you can use markdown for many formatting commands like bold, lists, blockquotes, etc. (I don't think Doxygen has any other kind of formatting, except that you can use direct html apparently).</p>
+<p>Now a <code>.dox</code> file is read by Doxygen just like a source code file. The commands to Doxygen must be in comments, and you can even have source code in it (and we do) but the compiler won't see it. If you wanted to use an entire <code>.dox</code> file as one big description (and we do), you still need to encase the entire thing in a comment block.</p>
+<p>Finally <code>.md</code> files are an exception. Doxygen reads and uses the text in these without the comment blocks. This makes a natural "page" construct. I'm not sure any other construct can be created this way. However, if you sneak in an <code>@</code> command or two, those will work! (And doxygen isn't great at all markdown syntax, sadly.) In this way, you <em>could</em> put class info or group info inside of a <code>.md</code> perhaps. </p>
 </div></div><!-- contents -->
 <!-- start footer part -->
 <hr class="footer"/><address class="footer"><small>