moving TS functions from Doxygen "groups" to pseudo-namespaces. This is an attempt to re-use the least number of concepts and we need namespaces. Functions may have worked in a group but classes will not. the reason is that the same class name will be seen in the engine via the tag file and confuse things.

also for engine docs, override a few "function-like macros" from the engine which heartily confuse doxygen.  (a semi-colon on the end of macro calls would probably work but that's a lot of files to touch)

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

@@ -30,22 +30,16 @@
 
 //-----------------------------------------------------------------------------
 
-ConsoleFunctionGroupBegin( Vector2Math, "Vector2 math functions.");
-
-/*!	@addtogroup Vector2Math
-	two-element vectors engine functions
-	@{
-*/
+/*! Vector2 math functions. */
+ConsoleFunctionGroupBeginWithDocs(Vector2Math)
 
 //-----------------------------------------------------------------------------
 
-/*! Add two 2D Vectors.
-	Returns v1+v2
-
-	@see Scene::createMotorJoint
+/*! Add two 2-Vectors.
+	@return v1+v2
 
 	\par From Engine
-	@copydoc Scene::createMotorJoint
+	@see Vector2::operator+
 */
 ConsoleFunctionWithDocs( Vector2Add, ConsoleString, 3, 3, (Vector2 v1, Vector2 v2) )
 {
@@ -65,12 +59,10 @@ ConsoleFunctionWithDocs( Vector2Add, ConsoleString, 3, 3, (Vector2 v1, Vector2 v
 //-----------------------------------------------------------------------------
 
 /*! Subtract two 2D Vectors.
-    Returns v1-v2
-
-	@see Scene::createMotorJoint
+    @return v1-v2
 
 	\par From Engine
-	@copydoc Scene::createMotorJoint
+	@see Vector2::operator-(Vector2)
 */
 ConsoleFunctionWithDocs( Vector2Sub, ConsoleString, 3, 3,(Vector2 v1, Vector2 v2))
 {
@@ -88,15 +80,12 @@ ConsoleFunctionWithDocs( Vector2Sub, ConsoleString, 3, 3,(Vector2 v1, Vector2 v2
 }
 
 //-----------------------------------------------------------------------------
-// The absolute difference between two 2D Vectors.
-//-----------------------------------------------------------------------------
-
-/*! Returns abs(v1-v2)
 
-	@see Scene::createMotorJoint
+/*! Absolute difference of two 2-Vectors
+	@return abs(v1-v2)
 
 	\par From Engine
-	@copydetails Scene::createMotorJoint
+	@see Vector2::absolute
 */
 ConsoleFunctionWithDocs( Vector2Abs, ConsoleString, 3, 3, (Vector2 v1, Vector2 v2) )
 {
@@ -114,9 +103,10 @@ ConsoleFunctionWithDocs( Vector2Abs, ConsoleString, 3, 3, (Vector2 v1, Vector2 v
 }
 
 //-----------------------------------------------------------------------------
-// Multiply two 2D Vectors (Not Dot-Product!)
-//-----------------------------------------------------------------------------
-ConsoleFunction( Vector2Mult, ConsoleString, 3, 3, "(Vector2 v1, Vector2 v2) - Returns v1 mult v2.")
+/*! Multiply two 2D Vectors (Not Dot-Product!)
+	@return v1 mult v2.
+*/
+ConsoleFunctionWithDocs( Vector2Mult, ConsoleString, 3, 3, (Vector2 v1, Vector2 v2))
 {
     // Check Parameters.
     if (Utility::mGetStringElementCount(argv[1]) < 2 ||Utility::mGetStringElementCount(argv[2]) < 2 )
@@ -132,9 +122,13 @@ ConsoleFunction( Vector2Mult, ConsoleString, 3, 3, "(Vector2 v1, Vector2 v2) - R
 }
 
 //-----------------------------------------------------------------------------
-// Scale a 2D Vector.
-//-----------------------------------------------------------------------------
-ConsoleFunction( Vector2Scale, ConsoleString, 3, 3, "(Vector2 v1, scale) - Returns v1 scaled by scale.")
+/*! Scale a 2D Vector.
+	@return v1 scaled by scale.
+
+	\par From Engine
+	@see Vector2::operator*
+*/
+ConsoleFunctionWithDocs( Vector2Scale, ConsoleString, 3, 3, (Vector2 v1, scale))
 {
     // Check Parameters.
     if (Utility::mGetStringElementCount(argv[1]) < 2 )
@@ -151,9 +145,13 @@ ConsoleFunction( Vector2Scale, ConsoleString, 3, 3, "(Vector2 v1, scale) - Retur
 }
 
 //-----------------------------------------------------------------------------
-// Normalize a 2D Vector.
-//-----------------------------------------------------------------------------
-ConsoleFunction( Vector2Normalize, ConsoleString, 2, 2, "(Vector2 v1) - Returns Normalized v1.")
+/*! Normalize a 2D Vector.
+	@return Normalized v1.
+
+	\par From Engine
+	@see Vector2::Normalize
+*/
+ConsoleFunctionWithDocs( Vector2Normalize, ConsoleString, 2, 2, (Vector2 v1))
 {
     // Check Parameters.
     if (Utility::mGetStringElementCount(argv[1]) < 2 )
@@ -168,9 +166,13 @@ ConsoleFunction( Vector2Normalize, ConsoleString, 2, 2, "(Vector2 v1) - Returns
 }
 
 //-----------------------------------------------------------------------------
-// Dot-Product of two 2D Vectors.
-//-----------------------------------------------------------------------------
-ConsoleFunction(Vector2Dot, ConsoleFloat, 3, 3, "(Vector2 v1, Vector2 v2) - Returns dot-product of v1 and v2.")
+/*! Dot-Product of two 2D Vectors.
+	@return dot-product of v1 and v2.
+
+	\par From Engine
+	@see Vector2::dot
+*/
+ConsoleFunctionWithDocs(Vector2Dot, ConsoleFloat, 3, 3, (Vector2 v1, Vector2 v2))
 {
     // Check Parameters.
     if (Utility::mGetStringElementCount(argv[1]) < 2 ||Utility::mGetStringElementCount(argv[2]) < 2 )
@@ -186,9 +188,11 @@ ConsoleFunction(Vector2Dot, ConsoleFloat, 3, 3, "(Vector2 v1, Vector2 v2) - Retu
 }
 
 //-----------------------------------------------------------------------------
-// Equality of two 2D Points.
-//-----------------------------------------------------------------------------
-ConsoleFunction( Vector2Compare, ConsoleBool, 3, 4, "(Vector2 p1, Vector2 p2, [epsilon]) - Compares points p1 and p2 with optional difference (epsilon).")
+/*! Equality of two 2D Points.
+	Compares points p1 and p2 with optional difference (epsilon).
+	@return true if equal
+*/
+ConsoleFunctionWithDocs( Vector2Compare, ConsoleBool, 3, 4, (Vector2 p1, Vector2 p2, [epsilon]))
 {
     // Check Parameters.
     if (Utility::mGetStringElementCount(argv[1]) < 2 ||Utility::mGetStringElementCount(argv[2]) < 2 )
@@ -211,9 +215,10 @@ ConsoleFunction( Vector2Compare, ConsoleBool, 3, 4, "(Vector2 p1, Vector2 p2, [e
 }
 
 //-----------------------------------------------------------------------------
-// Distance between two 2D Points.
-//-----------------------------------------------------------------------------
-ConsoleFunction( Vector2Distance, ConsoleFloat, 3, 3, "(Vector2 p1, Vector2 p2) - Returns the distance between points p1 and p2.")
+/*! Distance between two 2D Points.
+	@return the distance between points p1 and p2
+*/
+ConsoleFunctionWithDocs( Vector2Distance, ConsoleFloat, 3, 3, (Vector2 p1, Vector2 p2))
 {
     // Check Parameters.
     if (Utility::mGetStringElementCount(argv[1]) < 2 ||Utility::mGetStringElementCount(argv[2]) < 2 )
@@ -229,9 +234,10 @@ ConsoleFunction( Vector2Distance, ConsoleFloat, 3, 3, "(Vector2 p1, Vector2 p2)
 }
 
 //-----------------------------------------------------------------------------
-// Angle between two 2D Vectors.
-//-----------------------------------------------------------------------------
-ConsoleFunction( Vector2AngleBetween, ConsoleFloat, 3, 3, "(Vector2 v1, Vector2 v2) - Returns the angle between v1 and v2.")
+/*! Angle between two 2D Vectors.
+	@return the angle between v1 and v2.
+*/
+ConsoleFunctionWithDocs( Vector2AngleBetween, ConsoleFloat, 3, 3, (Vector2 v1, Vector2 v2))
 {
     // Check Parameters.
     if (Utility::mGetStringElementCount(argv[1]) < 2 ||Utility::mGetStringElementCount(argv[2]) < 2 )
@@ -250,9 +256,10 @@ ConsoleFunction( Vector2AngleBetween, ConsoleFloat, 3, 3, "(Vector2 v1, Vector2
 }
 
 //-----------------------------------------------------------------------------
-// Angle from one point to another.
-//-----------------------------------------------------------------------------
-ConsoleFunction( Vector2AngleToPoint, ConsoleFloat, 3, 3, "(Vector2 p1, Vector2 p1) - Returns the angle from p1 to p2.")
+/*! Angle from one point to another.
+	@return the angle from p1 to p2.
+*/
+ConsoleFunctionWithDocs( Vector2AngleToPoint, ConsoleFloat, 3, 3, (Vector2 p1, Vector2 p1))
 {
     // Check Parameters.
     if (Utility::mGetStringElementCount(argv[1]) < 2 ||Utility::mGetStringElementCount(argv[2]) < 2 )
@@ -269,12 +276,14 @@ ConsoleFunction( Vector2AngleToPoint, ConsoleFloat, 3, 3, "(Vector2 p1, Vector2
 }
 
 //-----------------------------------------------------------------------------
-// Vector from angle and magnitude.
+/*! Vector from angle and magnitude.
+	Calculates a direction from an angle and magnitude.
+    @param angle The angle of the direction.
+    @param magnitude The magnitude of the direction.
+    @return No return value.
+*/
 //-----------------------------------------------------------------------------
-ConsoleFunction( Vector2Direction, ConsoleString, 3, 3,   "(F32 angle, F32 magnitude) - Calculates a direction from an angle and magnitude.\n"
-                                                        "@param angle The angle of the direction.\n"
-                                                        "@param magnitude The magnitude of the direction.\n"
-                                                        "@return No return value.")
+ConsoleFunctionWithDocs( Vector2Direction, ConsoleString, 3, 3, (F32 angle, F32 magnitude))
 {
     // Fetch angle.
     const F32 angle = mDegToRad(dAtof(argv[1]));
@@ -289,9 +298,13 @@ ConsoleFunction( Vector2Direction, ConsoleString, 3, 3,   "(F32 angle, F32 magni
 }
 
 //-----------------------------------------------------------------------------
-// Length of a 2D Vector.
-//-----------------------------------------------------------------------------
-ConsoleFunction( Vector2Length, ConsoleFloat, 2, 2, "(Vector2 v1) - Returns the length of v1.")
+/*! Length of a 2D Vector.
+	@return the length of v1.
+
+	\par From Engine
+	@see Vector2::Length
+*/
+ConsoleFunctionWithDocs( Vector2Length, ConsoleFloat, 2, 2, (Vector2 v1))
 {
     // Check Parameters.
     if (Utility::mGetStringElementCount(argv[1]) < 2 )
@@ -306,9 +319,14 @@ ConsoleFunction( Vector2Length, ConsoleFloat, 2, 2, "(Vector2 v1) - Returns the
 }
 
 //-----------------------------------------------------------------------------
-// Inverse of a 2D Vector.
+/*! Inverse of a 2D Vector.
+	@return the inverse of v1.
+
+	\par From Engine
+	@see Vector2::operator-()
+*/
 //-----------------------------------------------------------------------------
-ConsoleFunction( Vector2Inverse, ConsoleString, 2, 2, "(Vector2 v1) - Returns the inverse of v1.")
+ConsoleFunctionWithDocs( Vector2Inverse, ConsoleString, 2, 2, (Vector2 v1))
 {
     // Check Parameters.
     if (Utility::mGetStringElementCount(argv[1]) < 2 )
@@ -323,9 +341,10 @@ ConsoleFunction( Vector2Inverse, ConsoleString, 2, 2, "(Vector2 v1) - Returns th
 }
 
 //-----------------------------------------------------------------------------
-// Inverse X component of a 2D Vector.
-//-----------------------------------------------------------------------------
-ConsoleFunction( Vector2InverseX, ConsoleString, 2, 2, "(Vector2 v1) - Returns the inverse of the v1 X component.")
+/*! Inverse X component of a 2D Vector.
+	@return the inverse of the v1 X component.
+*/
+ConsoleFunctionWithDocs( Vector2InverseX, ConsoleString, 2, 2, (Vector2 v1))
 {
     // Check Parameters.
     if (Utility::mGetStringElementCount(argv[1]) < 2 )
@@ -341,9 +360,10 @@ ConsoleFunction( Vector2InverseX, ConsoleString, 2, 2, "(Vector2 v1) - Returns t
 }
 
 //-----------------------------------------------------------------------------
-// Inverse Y component of a 2D Vector.
-//-----------------------------------------------------------------------------
-ConsoleFunction( Vector2InverseY, ConsoleString, 2, 2, "(Vector2 v1) - Returns the inverse of the v1 Y component.")
+/*! Inverse Y component of a 2D Vector.
+	@return the inverse of the v1 Y component.
+*/
+ConsoleFunctionWithDocs( Vector2InverseY, ConsoleString, 2, 2, (Vector2 v1))
 {
     // Check Parameters.
     if (Utility::mGetStringElementCount(argv[1]) < 2 )
@@ -359,9 +379,10 @@ ConsoleFunction( Vector2InverseY, ConsoleString, 2, 2, "(Vector2 v1) - Returns t
 }
 
 //-----------------------------------------------------------------------------
-// Normalize Rectangle (two 2D Vectors) with relation to each other.
-//-----------------------------------------------------------------------------
-ConsoleFunction( Vector2AreaNormalize, ConsoleString, 3, 3, "(Vector2 v1, Vector2 v2) - Returns Normalize rectangle of v1 and v2.")
+/*! Normalize Rectangle (two 2D Vectors) with relation to each other.
+	@return Normalize rectangle of v1 and v2.
+*/
+ConsoleFunctionWithDocs( Vector2AreaNormalize, ConsoleString, 3, 3, (Vector2 v1, Vector2 v2))
 {
     // Check Parameters.
     if (Utility::mGetStringElementCount(argv[1]) < 2 ||Utility::mGetStringElementCount(argv[2]) < 2 )
@@ -387,9 +408,6 @@ ConsoleFunction( Vector2AreaNormalize, ConsoleString, 3, 3, "(Vector2 v1, Vector
     return pBuffer;
 }
 
-
 //-----------------------------------------------------------------------------
 
-/*!	@} */
-
-ConsoleFunctionGroupEnd( Vector2Math );
+ConsoleFunctionGroupEndWithDocs( Vector2Math );

engine/source/console/console.h

@@ -797,6 +797,9 @@ public:
 #  define ConsoleFunctionGroupBegin(groupName, usage) \
       static ConsoleConstructor gConsoleFunctionGroup##groupName##__GroupBegin(NULL,#groupName,usage);
 
+#  define ConsoleFunctionGroupBeginWithDocs(groupName) \
+      static ConsoleConstructor gConsoleFunctionGroup##groupName##__GroupBegin(NULL,#groupName,"");
+
 #  define ConsoleFunction(name,returnType,minArgs,maxArgs,usage1)                         \
       static returnType c##name(SimObject *, S32, const char **argv);                     \
       static ConsoleConstructor g##name##obj(NULL,#name,c##name,usage1,minArgs,maxArgs);  \
@@ -810,6 +813,9 @@ public:
 #  define ConsoleFunctionGroupEnd(groupName) \
       static ConsoleConstructor gConsoleFunctionGroup##groupName##__GroupEnd(NULL,#groupName,NULL);
 
+#  define ConsoleFunctionGroupEndWithDocs(groupName) \
+      static ConsoleConstructor gConsoleFunctionGroup##groupName##__GroupEnd(NULL,#groupName,NULL);
+
 // Console method macros
 #  define ConsoleNamespace(className, usage) \
       static ConsoleConstructor className##__Namespace(#className, usage);

engine/source/sim/simBase_ScriptBinding.h

@@ -26,12 +26,8 @@
 
 //-----------------------------------------------------------------------------
 
-ConsoleFunctionGroupBegin ( SimFunctions, "Functions relating to Sim.");
-
-/*!	@addtogroup SimFunctions
-	simulation engine functions
-	@{
-*/
+/*! Functions relating to Sim. */
+ConsoleFunctionGroupBeginWithDocs( SimFunctions );
 
 //-----------------------------------------------------------------------------
 
@@ -184,6 +180,4 @@ ConsoleFunctionWithDocs(schedule, ConsoleInt, 4, 0, ( t , objID || 0 , functionN
 
 //-----------------------------------------------------------------------------
 
-/*!	@} */
-
-ConsoleFunctionGroupEnd( SimFunctions );
+ConsoleFunctionGroupEndWithDocs( SimFunctions );

tools/documentation/config/torque2DReference.cfg

@@ -453,7 +453,7 @@ CASE_SENSE_NAMES       = NO
 # will show members with their full class and namespace scopes in the
 # documentation. If set to YES the scope will be hidden.
 
-HIDE_SCOPE_NAMES       = NO
+HIDE_SCOPE_NAMES       = YES
 
 # If the SHOW_INCLUDE_FILES tag is set to YES (the default) then Doxygen
 # will put a list of the files that are included by a file in the documentation
@@ -666,7 +666,7 @@ WARN_FORMAT            = "$file:$line: $text"
 # and error messages should be written. If left blank the output is written
 # to stderr.
 
-WARN_LOGFILE           = "warn.log"
+WARN_LOGFILE           = output/warn-t2d.log
 
 #---------------------------------------------------------------------------
 # configuration options related to the input files
@@ -713,10 +713,11 @@ EXCLUDE                = ../../engine/source/persistence/rapidjson
 EXCLUDE               += ../../engine/source/delegates
 EXCLUDE               += ../../engine/source/platformWin32
 EXCLUDE               += ../../engine/source/platformOSX
-EXCLUDE               += ../../engine/source/platformX86Unix
+EXCLUDE               += ../../engine/source/platformX86UNIX
 EXCLUDE               += ../../engine/source/platformiOS
 EXCLUDE               += ../../engine/source/testing/googleTest
 EXCLUDE               += ../../engine/source/box2d
+EXCLUDE               += ../../engine/source/console/cmdgram.cc
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
 # directories that are symbolic links (a Unix file system feature) are excluded
@@ -1611,9 +1612,11 @@ INCLUDE_FILE_PATTERNS  =
 
 PREDEFINED             = TORQUE_DEBUG
 PREDEFINED            += ConsoleFunctionGroupBegin(groupName,usage)=" "
+PREDEFINED            += ConsoleFunctionGroupBeginWithDocs(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)=" "
 
 PREDEFINED            += ConsoleMethodBeginWithDocs(className)="class className { public:"
 PREDEFINED            += ConsoleMethodGroupBegin(className,groupName,usage)=" "
@@ -1624,6 +1627,10 @@ PREDEFINED            += ConsoleStaticMethodWithDocs(className,name,returnType,m
 PREDEFINED            += ConsoleMethodEndWithDocs(className)="};"
 PREDEFINED            += ConsoleMethodGroupEnd(className,groupName)=" "
 
+PREDEFINED            += DefineConsoleType()=" "
+PREDEFINED            += ConsoleType()=" "
+PREDEFINED            += ConsoleSetType()=" "
+PREDEFINED            += ConsoleGetType()=" "
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then
 # this tag can be used to specify a list of macro names that should be expanded.
@@ -1661,7 +1668,7 @@ TAGFILES               =
 # When a file name is specified after GENERATE_TAGFILE, doxygen will create
 # a tag file that is based on the input files it reads.
 
-GENERATE_TAGFILE       = t2d.tag
+GENERATE_TAGFILE       = Torque2D.tag
 
 # If the ALLEXTERNALS tag is set to YES all external classes will be listed
 # in the class index. If set to NO only the inherited external classes

tools/documentation/config/torqueScriptReference.cfg

@@ -667,7 +667,7 @@ WARN_FORMAT            = "$file:$line: $text"
 # and error messages should be written. If left blank the output is written
 # to stderr.
 
-WARN_LOGFILE           = "warn.log"
+WARN_LOGFILE           = output/warn-ts.log
 
 #---------------------------------------------------------------------------
 # configuration options related to the input files
@@ -837,7 +837,7 @@ REFERENCED_BY_RELATION = YES
 # then for each documented function all documented entities
 # called/used by that function will be listed.
 
-REFERENCES_RELATION    = YES
+REFERENCES_RELATION    = NO
 
 # If the REFERENCES_LINK_SOURCE tag is set to YES (the default)
 # and SOURCE_BROWSER tag is set to YES, then the hyperlinks from
@@ -1605,13 +1605,17 @@ PREDEFINED            += ConsoleFloat=float
 PREDEFINED            += ConsoleVoid=void
 PREDEFINED            += ConsoleBool=bool
 
+# notes: need a namespace to guard classes or global functions from being hidden (due to the same name (for a different meaning) in the engine)
+
 PREDEFINED            += ConsoleFunctionGroupBegin(groupName,usage)=" "
+PREDEFINED            += ConsoleFunctionGroupBeginWithDocs(groupName)="namespace Global { 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)="}; };"
 
 PREDEFINED            += ConsoleMethodGroupBegin(className,groupName,usage)=" "
-PREDEFINED            += ConsoleMethodBeginWithDocs(className)="namespace TorqueScript { class className { public:"
+PREDEFINED            += ConsoleMethodBeginWithDocs(className)="namespace Class { class className { public:"
 PREDEFINED            += ConsoleMethod(className,name,returnType,minArgs,maxArgs,argString)="returnType className::name (...)"
 PREDEFINED            += ConsoleMethodWithDocs(className,name,returnType,minArgs,maxArgs,argString)="returnType className::name argString"
 PREDEFINED            += ConsoleStaticMethod(className,name,returnType,minArgs,maxArgs,argString)="static returnType className::name (...)"
@@ -1651,7 +1655,7 @@ SKIP_FUNCTION_MACROS   = YES
 # NOT include the path). If a tag file is not located in the directory in which
 # doxygen is run, you must also specify the path to the tagfile here.
 
-TAGFILES               = t2d.tag=../../torque2D/html
+TAGFILES               = Torque2D.tag=../../torque2D/html
 
 # When a file name is specified after GENERATE_TAGFILE, doxygen will create
 # a tag file that is based on the input files it reads.