re-instated the layout file for torqueScript docs

several subtle changes such as adding collapsible diagrams to the t2d docs

engine/source/2d/core/Vector2_ScriptBinding.h

@@ -30,7 +30,6 @@
 
 //-----------------------------------------------------------------------------
 
-/*! Vector2 math functions. */
 ConsoleFunctionGroupBeginWithDocs(Vector2Math)
 
 //-----------------------------------------------------------------------------

engine/source/sim/simBase_ScriptBinding.h

@@ -26,7 +26,6 @@
 
 //-----------------------------------------------------------------------------
 
-/*! Functions relating to Sim. */
 ConsoleFunctionGroupBeginWithDocs( SimFunctions );
 
 //-----------------------------------------------------------------------------
@@ -77,10 +76,10 @@ ConsoleFunctionWithDocs(isObject, ConsoleBool, 2, 2, ( handle ) )
 /*! cancel a previously scheduled event
 	@param eventID The numeric ID of a previously scheduled event.
 	@return No return value.
-	@sa getEventTimeLeft, getScheduleDuration, getTimeSinceStart, isEventPending, schedule, obj.schedule
+	@sa getEventTimeLeft, getScheduleDuration, getTimeSinceStart, isEventPending, schedule, Class::SceneObject::schedule
 
 	@par From Engine
-	@copydoc Sim::cancelEvent
+	@sa Sim::cancelEvent
 */
 ConsoleFunctionWithDocs(cancel,ConsoleVoid,2,2, ( eventID ) )
 {
@@ -94,7 +93,7 @@ ConsoleFunctionWithDocs(cancel,ConsoleVoid,2,2, ( eventID ) )
 	@sa cancel, getEventTimeLeft, getScheduleDuration, getTimeSinceStart, schedule, obj.schedule
 
 	@par From Engine
-	@copydoc Sim::isEventPending
+	@sa Sim::isEventPending
 */
 ConsoleFunctionWithDocs(isEventPending, ConsoleBool, 2, 2, ( eventID ) )
 {

tools/documentation/config/torque2DReference.cfg

@@ -999,7 +999,7 @@ HTML_TIMESTAMP         = YES
 # documentation will contain sections that can be hidden and shown after the
 # page has loaded.
 
-HTML_DYNAMIC_SECTIONS  = NO
+HTML_DYNAMIC_SECTIONS  = YES
 
 # With HTML_INDEX_NUM_ENTRIES one can control the preferred number of
 # entries shown in the various tree structured indices initially; the user

tools/documentation/config/torqueScriptReference-layout.xml

@@ -4,30 +4,42 @@
   <navindex>
     <tab type="mainpage" visible="yes" title=""/>
     <tab type="pages" visible="yes" title="" intro=""/>
-
-    <!--
-		TorqueScript has lots of (non-class) functions, in categories such as "audio", "math", etc.
-	    To output these in categories, use a group/module per category.
-		  * Use @defGroup per category, such as "audio", "math", etc.
-		Then change the module page name from "modules" to "TorqueScript Functions".
-
-		Each module will really be a category of functions, so each group link goes to a page representing
-		a category of the functions.
-
-		Note: "module" or "group" as defined by doxygen is just a grouping mechanism (both words are interchanged 
-		in the manual).  "Modules" are not a language feature like "namespace" or "class".
-		This will be our only use of module/group concept for TorqueScript documentation.
-		Note: global functions won't even show up without being wrapped in a group/module or other trick, anyway.
+    <tab type="modules" visible="yes" title="" intro=""/>
+	<!-- T2D: we are hiding the "real" Namespaces tab.  See notes in our "fake" Namespaces tab below.
+	     If we could, we'd rename the concept of "Namespace" to "Functions" to get what we want.
+		 Instead we have simply made invisible all namespace-related tabs so they won't show
+		 in any cross-references.
 	-->
-    <tab type="modules" visible="yes" title="TorqueScript Functions" intro="A reference of all (non-class) functions, grouped by category."/>
-    <tab type="namespaces" visible="yes" title="">
-      <tab type="namespacelist" visible="yes" title="" intro=""/>
-      <tab type="namespacemembers" visible="yes" title="" intro=""/>
+    <tab type="namespaces" visible="no" title="Namespaces">
+      <tab type="namespacelist" visible="no" title="Functions by Category" intro="A list of all functions organized by category"/>
+      <tab type="namespacemembers" visible="no" title="All Function" intro="A list of all functions from all categories"/>
     </tab>
-    <tab type="classes" visible="yes" title="">
-      <tab type="classindex" visible="$ALPHABETICAL_INDEX" title="A-Z"/>
-      <tab type="hierarchy" visible="$CLASS_HIERARCHY_INDEX" title="Hierarchy"/>
+	<!-- We are making a global functions page.  Global functions are actually functions
+		 in the pseudo-namespace "Functions".
+	-->
+	<tab type="user" title="Functions" url="namespaceFunctions.html"/>
+	<!-- T2D: we are hiding the "real" Classes tab.  See notes in our "fake" Classes tab below -->
+    <tab type="classes" visible="no" title="">
+      <tab type="classindex" visible="$ALPHABETICAL_INDEX" title="Classes A-Z"/>
+      <tab type="hierarchy" visible="yes" title="Classes Hierarchy"/>
+      <tab type="classlist" visible="no" title="" intro=""/>
+      <tab type="classmembers" visible="no" title="" intro=""/>
     </tab>
+	<!-- T2D: note that we made invisible the *real* "Classes" tab and then made our own.
+	     The reason is that the real Classes tab defaults to the "Class List" sub tab, which
+		 we don't want (more below).
+		 So why not just turn off the "classlist" tab so it doesn't show by default?  Tried it, but
+		 doxygen shows that tab by default anyway.  Even though it is "invisible" in the index.
+		 
+		 Why do we want to hide the class list tab anyway?  It shows classes within namespaces.
+		 Since we are using namespaces to hide our TorqueScript classes/functions from the related
+		 Torque2D classes/functions (using namespaces "Functions" and "Class"), this list of classes
+		 in namespaces looked confusing.
+	-->
+	<tab type="usergroup" title="Classes">
+		<tab type="user" url="classes.html" title="Classes A-Z"/>
+		<tab type="user" url="hierarchy.html" title="Classes Hierarchy"/>		
+    </tab>		
     <tab type="files" visible="yes" title="">
       <tab type="filelist" visible="yes" title="" intro=""/>
       <tab type="globals" visible="yes" title="" intro=""/>
@@ -46,8 +58,10 @@
       <publictypes title=""/>
       <publicslots title=""/>
       <signals title=""/>
+	  <!-- T2D: rename "Public Methods Function" to be just "Methods" for TorqueScript -->
       <publicmethods title="Methods"/>
       <publicstaticmethods title=""/>
+	  <!-- T2D: rename "Public Attributes" to be just "Fields" for TorqueScript -->
       <publicattributes title="Fields"/>
       <publicstaticattributes title=""/>
       <protectedtypes title=""/>
@@ -79,6 +93,7 @@
       <typedefs title=""/>
       <enums title=""/>
       <constructors title=""/>
+	  <!-- T2D: rename "Public Method Functions" to be just "Methods" for TorqueScript -->
       <functions title="Methods"/>
       <related title=""/>
       <variables title=""/>
@@ -91,10 +106,13 @@
   </class>
 
   <!-- Layout definition for a namespace page -->
+  <!-- T2D: we will make namespaces look like "function categories" which
+       hold sets of global TorqueScript functions.  This is simply a hack.
+  -->
   <namespace>
     <briefdescription visible="yes"/>
     <memberdecl>
-      <nestednamespaces visible="yes" title=""/>
+      <nestednamespaces visible="yes" title="Function Categories"/>
       <classes visible="yes" title=""/>
       <typedefs title=""/>
       <enums title=""/>

tools/documentation/config/torqueScriptReference.cfg

@@ -608,7 +608,7 @@ FILE_VERSION_FILTER    =
 # You can optionally specify a file name after the option, if omitted
 # DoxygenLayout.xml will be used as the name of the layout file.
 
-LAYOUT_FILE            =
+LAYOUT_FILE            = config/torqueScriptReference-layout.xml
 
 # The CITE_BIB_FILES tag can be used to specify one or more bib files
 # containing the references data. This must be a list of .bib files. The
@@ -919,6 +919,7 @@ HTML_FILE_EXTENSION    = .html
 # have to redo this when upgrading to a newer version of doxygen or when
 # changing the value of configuration settings such as GENERATE_TREEVIEW!
 
+# HTML_HEADER            = config/torqueScriptReference-header.html
 HTML_HEADER            =
 
 # The HTML_FOOTER tag can be used to specify a personal HTML footer for
@@ -1160,7 +1161,7 @@ ECLIPSE_DOC_ID         = org.doxygen.Project
 # navigation tree you can set this option to NO if you already set
 # GENERATE_TREEVIEW to YES.
 
-DISABLE_INDEX          = YES
+DISABLE_INDEX          = NO
 
 # The GENERATE_TREEVIEW tag is used to specify whether a tree-like index
 # structure should be generated to display hierarchical information.
@@ -1609,15 +1610,26 @@ PREDEFINED            += ConsoleVoid=void
 PREDEFINED            += ConsoleBool=bool
 
 # T2D
-# * need a namespace to guard classes or global functions from being hidden (due to the same name (for a different meaning) in the engine)
+# note: need a namespace to keep classes and global functions from being
+# hidden in the doc (due to the same name (for a different but related meaning) in the engine).
 
 PREDEFINED            += ConsoleFunctionGroupBegin(groupName,usage)=" "
-PREDEFINED            += ConsoleFunctionGroupBeginWithDocs(groupName)="namespace Global { namespace groupName {"
+PREDEFINED            += ConsoleFunctionGroupBeginWithDocs(groupName)="namespace Functions { namespace groupName {"
 PREDEFINED            += ConsoleFunction(name,returnType,minArgs,maxArgs,usage1)="returnType name (...) "
 PREDEFINED            += ConsoleFunctionWithDocs(name,returnType,min,max,argString)="returnType name argString "
 PREDEFINED            += ConsoleFunctionGroupEnd(groupName)=" "
 PREDEFINED            += ConsoleFunctionGroupEndWithDocs(groupName)="}; };"
 
+# T2D
+# note: we need a namespace to keep classes from being hidden in the output.
+# This is because we use a tag to connect us with the Torque2D docs so we can
+# reference them, like Scene::foo.  However, we don't want the symbols from Torque2D
+# dumping in our TorqueScript doc which would happen if we left on ALLEXTERNALS,
+# so we turned that off.  But, a side effect of turning off ALLEXTERNALS is that if we have
+# a TorqueScript object named Scene, it will not show because Doxygen sees Scene in the tag file
+# and "hides" it.  Therefore, we need a "different" Scene in TorqueScript so we use
+# namespace Class { Scene }.
+
 PREDEFINED            += ConsoleMethodGroupBegin(className,groupName,usage)=" "
 PREDEFINED            += ConsoleMethodBeginWithDocs(className)="namespace Class { class className { public:"
 PREDEFINED            += ConsoleMethod(className,name,returnType,minArgs,maxArgs,argString)="returnType className::name (...)"