documented 80% of SimObject and finished SimSet.

added 'new' operator to operations list.

engine/source/console/console.h

@@ -827,8 +827,8 @@ public:
 
 // note: we would want to expand the following macro into (Doxygen) comments!
 // we can not do that with a macro.  these are here just as a reminder until completion
+#  define ConsoleMethodRootGroupBeginWithDocs(className)
 #  define ConsoleMethodGroupBeginWithDocs(className, superclassName)
-#  define ConsoleMethodGroupEndWithDocs(className)
 
 #  define ConsoleMethod(className,name,returnType,minArgs,maxArgs,usage1)                                                 \
       static inline returnType c##className##name(className *, S32, const char **argv);                                   \
@@ -869,6 +869,9 @@ public:
 #  define ConsoleMethodGroupEnd(className, groupName) \
       static ConsoleConstructor className##groupName##__GroupEnd(#className,#groupName,NULL);
 
+#  define ConsoleMethodRootGroupEndWithDocs(className)
+#  define ConsoleMethodGroupEndWithDocs(className)
+
 #else
 
 // These do nothing if we don't want doc information.

engine/source/console/scriptBinding.dox

@@ -1,10 +1,59 @@
-// Warning!  This file is not real C++ code!  It is designed to provide types and operators, etc.
-// that are needed by Doxygen to create a TorqueScript reference.  As long as the
-// #define PSEUDOCODE_FOR_DOXYGEN is not set while compiling, there will be no issues.
+//-----------------------------------------------------------------------------
+// Copyright (c) 2013 GarageGames, LLC
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to
+// deal in the Software without restriction, including without limitation the
+// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+// sell copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+// IN THE SOFTWARE.
+//-----------------------------------------------------------------------------
+
+// Warning!  This file is not real C++ code!
+// It is designed to provide types, operators, and more that are needed by Doxygen
+// to create a TorqueScript reference.
+
+// As long as this file ends in .dox, compilers should ignore it, but Doxygen won't.
+// This means the psuedo-code in here will not be seen by your compiler but it will
+// be seen by the Doxygen code parser.
+
+// Add any constructs here that you want to use to "fake-out" Doxygen while creating
+// the Torquescript doc.
+
+//-----------------------------------------------------
+// TorqueScript Functions
+//-----------------------------------------------
+
+// Most functions will be defined in _ScriptBinding.h files.
+// Here we are only defining a doxygen group, called TorqueScriptFunctions,
+// for all functions to live within.  This is necessary as Doxygen ignores global
+// functions unless they in a group.  But it also helps organize the "modules" page of
+// the Doxygen output.
+// Clusters of functions -- such as vector functions or event scheduling functions --
+// should be kept within a subgroup of the TorqueScriptFunction umbrella group.
+// As groups are created, in various _ScriptBinding.h files, they should be marked as
+// @ingroup TorqueScriptFunctions like so:
+//
+// /*! @defgroup VectorMathFunctions Vector Math
+//    @ingroup TorqueScriptFunctions
+//    @{
+// */
+//
+// <functions, functions, functions!>
+//
+// /*! @} */ // group VectorMathFunctions
 
-// Define a doxygen group for all TorqueScript functions to live within
-// Clusters of functions -- such as vector functions or event schedule functions --
-// should be kept within a subgroup of the TorqueScriptFunction umbrella group
 /*!
    @defgroup TorqueScriptFunctions Function Categories
 */
@@ -13,6 +62,12 @@
 // TorqueScript Data Types
 //-----------------------------------------------
 
+// "Define" and document generic data types here.  Doxygen does not really understand
+// how to define a language, so we need to fake it out with some C++ concept.  We will
+// use "typedef" as it seems the most innocuous.  Of course, typedef requires two arguments
+// so use "typedef type" then your data type.
+
+// Wrap all data types in a group.  This will help organize Doxygen's output "module" page.
 /*!
    @defgroup TorqueScriptTypes Data Types
       @{
@@ -121,6 +176,9 @@ typedef type Vector2;
 */
 typedef type Vector;
 
+/*! Void is actually not a real type.  It simply represents the absense of a type.
+*/
+typedef type Void;
 
 /*! @} */ // data types
 //-----------------------------------------------
@@ -131,6 +189,12 @@ typedef type Vector;
 // TorqueScript Operators
 //-----------------------------------------------
 
+// "Define" and document TorqueScript operators here.  Doxygen does not really understand
+// how to define a language, so we need to fake it out with some C++ concept.  As with
+// data types (above), we will use "typedef" as it seems the most innocuous.  Of course,
+// typedef requires two arguments so use "typedef type" then your operator.
+
+// Wrap all operators in a group.  This will help organize Doxygen's output "module" page.
 /*!
    @defgroup Operators Operators
    @{
@@ -206,6 +270,47 @@ typedef type NL;
 
 /*! @} */ // arithmetic operators
 
+/*! @defgroup constructionOperators Construction Operators
+	@{
+*/
+
+/*!	create a new object
+
+	@par Format
+	@code
+	%myID = new class([name])
+	{
+		[field = value;]
+		...
+	};
+	@endcode
+
+	@par Where
+	+ *myID* is the return ID that can be used to access the object in the form `%%myID.myFunction`.\n
+	+ `new` is the keyword telling the engine to create an instance of the following *class*.\n
+	+ *class* is any class declared in the engine or in script that has been derived from SimObject.\n
+	+ *name* (optional) is the object's name for referencing in the form `name.myFunction` (without % or $ before it).\n
+	+ *field* - You may initialize static or dynamic class fields here, one at a time.\n
+
+	@par Example
+	@code
+	// An SceneObject named 'Truck'
+	// with two static fields and one dynamic field to define
+	new SceneObject(Truck) 
+	{
+	   position = "0 0";
+	   size = "5 5";
+	   myField = 100;
+	};
+	
+	// A nameless object (tracked by a variable), with no fields to set
+	%myObject = new SimSet();
+	@endcode
+*/
+typedef type new;
+
+/*! @} */ // constructionOperators operators
+
 /*! @} */ // all operators
 //-----------------------------------------------
 // End TorqueScript Operators

engine/source/sim/simObject.cc

@@ -71,6 +71,21 @@ SimObject::SimObject( const U8 namespaceLinkMask ) : mNSLinkMask( namespaceLinkM
 
 //---------------------------------------------------------------------------
 
+bool SimObject::isMethod( const char* methodName )
+{
+   if( !methodName || !methodName[0] )
+      return false;
+
+   StringTableEntry stname = StringTable->insert( methodName );
+
+   if( getNamespace() )
+      return ( getNamespace()->lookup( stname ) != NULL );
+
+   return false;
+}
+
+//---------------------------------------------------------------------------
+
 bool SimObject::registerObject()
 {
     AssertFatal( !mFlags.test( Added ), "reigsterObject - Object already registered!");
@@ -1311,3 +1326,65 @@ void SimObject::setSuperClassNamespace( const char *superClassNamespace )
    mSuperClassName = StringTable->insert( superClassNamespace );
    linkNamespaces();
 }
+
+static S32 QSORT_CALLBACK compareFields(const void* a,const void* b)
+{
+   const AbstractClassRep::Field* fa = *((const AbstractClassRep::Field**)a);
+   const AbstractClassRep::Field* fb = *((const AbstractClassRep::Field**)b);
+
+   return dStricmp(fa->pFieldname, fb->pFieldname);
+}
+
+void SimObject::dump()
+{
+   const AbstractClassRep::FieldList &list = getFieldList();
+   char expandedBuffer[4096];
+
+   Con::printf("Static Fields:");
+   Vector<const AbstractClassRep::Field *> flist(__FILE__, __LINE__);
+
+   for(U32 i = 0; i < (U32)list.size(); i++)
+      flist.push_back(&list[i]);
+
+   dQsort(flist.address(),flist.size(),sizeof(AbstractClassRep::Field *),compareFields);
+
+   for(Vector<const AbstractClassRep::Field *>::iterator itr = flist.begin(); itr != flist.end(); itr++)
+   {
+      const AbstractClassRep::Field* f = *itr;
+      if( f->type == AbstractClassRep::DepricatedFieldType ||
+          f->type == AbstractClassRep::StartGroupFieldType ||
+          f->type == AbstractClassRep::EndGroupFieldType) continue;
+
+      for(U32 j = 0; S32(j) < f->elementCount; j++)
+      {
+         // [neo, 07/05/2007 - #3000]
+         // Some objects use dummy vars and projected fields so make sure we call the get functions 
+         //const char *val = Con::getData(f->type, (void *) (((const char *)object) + f->offset), j, f->table, f->flag);                          
+         const char *val = (*f->getDataFn)( this, Con::getData(f->type, (void *) (((const char *)this) + f->offset), j, f->table, f->flag) );// + typeSizes[fld.type] * array1));
+
+         if(!val /*|| !*val*/)
+            continue;
+         if(f->elementCount == 1)
+            dSprintf(expandedBuffer, sizeof(expandedBuffer), "  %s = \"", f->pFieldname);
+         else
+            dSprintf(expandedBuffer, sizeof(expandedBuffer), "  %s[%d] = \"", f->pFieldname, j);
+         expandEscape(expandedBuffer + dStrlen(expandedBuffer), val);
+         Con::printf("%s\"", expandedBuffer);
+      }
+   }
+
+   Con::printf("Dynamic Fields:");
+   if(getFieldDictionary())
+      getFieldDictionary()->printFields(this);
+
+   Con::printf("Methods:");
+   Namespace *ns = getNamespace();
+   Vector<Namespace::Entry *> vec(__FILE__, __LINE__);
+
+   if(ns)
+      ns->getEntryList(&vec);
+
+   for(Vector<Namespace::Entry *>::iterator j = vec.begin(); j != vec.end(); j++)
+      Con::printf("  %s() - %s", (*j)->mFunctionName, (*j)->mUsage ? (*j)->mUsage : "");
+
+}

engine/source/sim/simObject.h

@@ -449,9 +449,6 @@ public:
     /// @name Initialization
     /// @{
 
-    ///added this so that you can print the entire class hierarchy, including script objects, 
-    //from the console or C++.
-    virtual void			dumpClassHierarchy();
     ///
     SimObject( const U8 namespaceLinkMask = LinkSuperClassName | LinkClassName );
     virtual ~SimObject();
@@ -723,6 +720,9 @@ public:
 
     /// @}
 
+	virtual void			dump();
+    virtual void			dumpClassHierarchy();
+
     static void initPersistFields();
     SimObject* clone( const bool copyDynamicFields );
     virtual void copyTo(SimObject* object);

tools/documentation/config/torque2DReference.cfg

@@ -1629,19 +1629,21 @@ 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            += ConsoleFunction(name,returnType,minArgs,maxArgs,usage1)=" "
+PREDEFINED            += ConsoleFunctionWithDocs(name,returnType,min,max,argString)=" "
 PREDEFINED            += ConsoleFunctionGroupEnd(groupName)=" "
 PREDEFINED            += ConsoleFunctionGroupEndWithDocs(groupName)=" "
 
-PREDEFINED            += ConsoleMethodBeginWithDocs(className)="class className { public:"
+PREDEFINED            += ConsoleMethodBeginWithDocs(className)=" "
 PREDEFINED            += ConsoleMethodGroupBegin(className,groupName,usage)=" "
-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 (...)"
-PREDEFINED            += ConsoleStaticMethodWithDocs(className,name,returnType,minArgs,maxArgs,argString)="static returnType className::name argString"
-PREDEFINED            += ConsoleMethodEndWithDocs(className)="};"
+PREDEFINED            += ConsoleMethodRootGroupBegin(className,groupName,usage)=" "
+PREDEFINED            += ConsoleMethod(className,name,returnType,minArgs,maxArgs,argString)=" "
+PREDEFINED            += ConsoleMethodWithDocs(className,name,returnType,minArgs,maxArgs,argString)=" "
+PREDEFINED            += ConsoleStaticMethod(className,name,returnType,minArgs,maxArgs,argString)=" "
+PREDEFINED            += ConsoleStaticMethodWithDocs(className,name,returnType,minArgs,maxArgs,argString)=" "
+PREDEFINED            += ConsoleMethodEndWithDocs(className)=" "
 PREDEFINED            += ConsoleMethodGroupEnd(className,groupName)=" "
+PREDEFINED            += ConsoleMethodRootGroupEnd(className,groupName)=" "
 
 PREDEFINED            += DefineConsoleType()=" "
 PREDEFINED            += ConsoleType()=" "

tools/documentation/config/torqueScriptReference.cfg

@@ -843,7 +843,7 @@ STRIP_CODE_COMMENTS    = NO
 # then for each documented function all documented
 # functions referencing it will be listed.
 
-REFERENCED_BY_RELATION = YES
+REFERENCED_BY_RELATION = NO
 
 # If the REFERENCES_RELATION tag is set to YES
 # then for each documented function all documented entities
@@ -1625,11 +1625,11 @@ INCLUDE_FILE_PATTERNS  =
 # Convert abstract types like ConsoleString into TorqueScript types
 
 PREDEFINED             = TORQUE_DEBUG
-PREDEFINED            += ConsoleString=string
-PREDEFINED            += ConsoleInt=int
-PREDEFINED            += ConsoleFloat=float
+PREDEFINED            += ConsoleString=String
+PREDEFINED            += ConsoleInt=Integer
+PREDEFINED            += ConsoleFloat=Float
 PREDEFINED            += ConsoleVoid=void
-PREDEFINED            += ConsoleBool=bool
+PREDEFINED            += ConsoleBool=Boolean
 
 # T2D
 # We have turned off our reference to a Torque2D tag file.  This means we can
@@ -1639,37 +1639,53 @@ PREDEFINED            += ConsoleBool=bool
 # simple (pseudo) classes for our TorqueScript class-like system (for instance SceneObject::)
 
 # TorqueScript methods
-# Temporarily, the unconverted ones
+# Temporarily, the unconverted ones (they don't end in "WithDocs") are still around.
+# We'll have them produce functions with (...) for the parameter set
+# Also, grouping of functions can no longer be done with these macros.  It will have to be done with comments
+# in the source code.
 
-# PREDEFINED            += ConsoleFunctionGroupBegin(groupName,usage)="namespace Functions { namespace groupName {"
-# PREDEFINED            += ConsoleFunctionGroupEnd(groupName)=" "
 PREDEFINED            += ConsoleFunctionGroupBegin(groupName,usage)=""
 PREDEFINED            += ConsoleFunctionGroupEnd(groupName)=""
-
 PREDEFINED            += ConsoleFunction(name,returnType,minArgs,maxArgs,usage1)="returnType name (...) "
 
 # The converted ones
+# Sadly, we cannot express a "module" or "group" of functions using macros.
+# This is because a group is created within comments and we cannot have a macro expand into comments.
+# (Maybe doxygen should provide this?)
+# Instead yhou must go in the code and put the following around your function group
+#
+# /*! @defgroup groupName
+#     @inGroup TorqueScriptFunctions
+#     @{
+# */
+#
+# ...
+#
+# /*! @} */
 
-PREDEFINED            += ConsoleFunctionGroupBeginWithDocs(groupName)="/*! @defgroup groupName \n\n @{ */"
-PREDEFINED            += ConsoleFunctionGroupEndWithDocs(groupName)="/*! @} */"
-
+# These won't work!  We'd have to expand them to comments, which doesn't work for macros, even in Doxygen.
+# PREDEFINED            += ConsoleFunctionGroupBeginWithDocs(groupName)=" "
+# PREDEFINED            += ConsoleFunctionGroupEndWithDocs(groupName)=" "
 PREDEFINED            += ConsoleFunctionWithDocs(name,returnType,min,max,argString)="returnType name argString "
 
 # TorqueScript "classes"
 # Temporarily, the unconverted ones
+# Temporarily, the unconverted ones (they don't end in "WithDocs") are still around.
+# We'll have them produce class with _TODO appended to the name, and methods with (...) for the parameter set
 
 # note: group begin/end not actually used but defined in Torque2D!
 PREDEFINED            += ConsoleMethodGroupBegin(className,groupName,usage)="class className { public:"
 PREDEFINED            += ConsoleMethodGroupEnd(className,groupName)="}; "
-
 PREDEFINED            += ConsoleMethod(className,name,returnType,minArgs,maxArgs,usage1)="class className##_TODO { public: returnType className::name (...); };"
 PREDEFINED            += ConsoleStaticMethod(className,name,returnType,minArgs,maxArgs,argString)="class className##_TODO { public: static returnType className::name (...); };"
 
 # The converted ones
+# There is a special "root" group wrapper used just for SimSet since it has no superclass.
 
 PREDEFINED            += ConsoleMethodGroupBeginWithDocs(className,superclassName)="class className : public superclassName { public:"
+PREDEFINED            += ConsoleMethodRootGroupBeginWithDocs(className)="class className { public:"
 PREDEFINED            += ConsoleMethodGroupEndWithDocs(className)="};"
-
+PREDEFINED            += ConsoleMethodRootGroupEndWithDocs(className)="};"
 PREDEFINED            += ConsoleMethodWithDocs(className,name,returnType,minArgs,maxArgs,argString)="returnType className::name argString"
 PREDEFINED            += ConsoleStaticMethodWithDocs(className,name,returnType,minArgs,maxArgs,argString)="static returnType className::name argString"