Fixed doxygen warnings.

Added a batch file to generate the Doxygen XML files needed for generating the Lua script bindings.
Added separate Visual Studio solution for the gameplay-luagen project.

gameplay-luagen/TODO.txt

@@ -25,7 +25,6 @@ Unsupported:
 
 Normal Priority List:
 =====================
-- Fix Doxygen warnings.
 - Fix memory leaks in gameplay-luagen and in generated code.
     - Add "@script{create}" to the appropriate gameplay functions.
     - Add "@script{own}" to array parameters that are owned by the function or class they are passed to?

gameplay-luagen/gameplay-luagen.doxyfile

@@ -52,7 +52,7 @@ PROJECT_LOGO           =
 # If a relative path is entered, it will be relative to the location 
 # where doxygen was started. If left blank the current directory will be used.
 
-OUTPUT_DIRECTORY       = ./gameplay-api
+OUTPUT_DIRECTORY       = ../gameplay-api
 
 # If the CREATE_SUBDIRS tag is set to YES, then doxygen will create 
 # 4096 sub-directories (in 2 levels) under the output directory of each output 
@@ -665,7 +665,7 @@ WARN_LOGFILE           =
 # directories like "/usr/src/myproject". Separate the files or directories 
 # with spaces.
 
-INPUT                  = ./gameplay/src
+INPUT                  = ../gameplay/src
 
 # This tag can be used to specify the character encoding of the source files 
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is 

gameplay-luagen/gameplay-luagen.sln

@@ -0,0 +1,20 @@
+
+Microsoft Visual Studio Solution File, Format Version 11.00
+# Visual Studio 2010
+Project("{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}") = "gameplay-luagen", "gameplay-luagen.vcxproj", "{CA137C5D-FDE1-4095-926A-59E8472504BF}"
+EndProject
+Global
+	GlobalSection(SolutionConfigurationPlatforms) = preSolution
+		Debug|Win32 = Debug|Win32
+		Release|Win32 = Release|Win32
+	EndGlobalSection
+	GlobalSection(ProjectConfigurationPlatforms) = postSolution
+		{CA137C5D-FDE1-4095-926A-59E8472504BF}.Debug|Win32.ActiveCfg = Debug|Win32
+		{CA137C5D-FDE1-4095-926A-59E8472504BF}.Debug|Win32.Build.0 = Debug|Win32
+		{CA137C5D-FDE1-4095-926A-59E8472504BF}.Release|Win32.ActiveCfg = Release|Win32
+		{CA137C5D-FDE1-4095-926A-59E8472504BF}.Release|Win32.Build.0 = Release|Win32
+	EndGlobalSection
+	GlobalSection(SolutionProperties) = preSolution
+		HideSolutionNode = FALSE
+	EndGlobalSection
+EndGlobal

gameplay-luagen/genxml.bat

@@ -0,0 +1 @@
+doxygen gameplay-luagen.doxyfile

gameplay/src/AnimationClip.h

@@ -231,7 +231,7 @@ public:
     /**
      * Adds an animation begin listener.
      * 
-     * Note: the given Lua function must have the same function signature as AnimationClip#Listener#animationEvent.
+     * Note: the given Lua function must have the same function signature as AnimationClip::Listener::animationEvent.
      *
      * @param function The Lua script function to be called when an AnimationClip begins.
      */
@@ -240,7 +240,7 @@ public:
     /**
      * Adds an animation end listener.
      * 
-     * Note: the given Lua function must have the same function signature as AnimationClip#Listener#animationEvent.
+     * Note: the given Lua function must have the same function signature as AnimationClip::Listener::animationEvent.
      *
      * @param function The Lua script function to be called when an AnimationClip ends.
      */
@@ -250,7 +250,7 @@ public:
      * Adds an animation listener to be called back at the specified eventTime during the playback 
      * of the AnimationClip.
      * 
-     * Note: the given Lua function must have the same function signature as AnimationClip#Listener#animationEvent.
+     * Note: the given Lua function must have the same function signature as AnimationClip::Listener::animationEvent.
      * 
      * @param function The Lua script function to be called when an AnimationClip reaches the 
      *      specified time in its playback.

gameplay/src/Base.h

@@ -46,9 +46,9 @@ using std::modf;
 #define NULL     0
 #endif
 
-// Print logging (implemented per platform)
 namespace gameplay
 {
+/** Print logging (implemented per platform). */
 extern void printError(const char* format, ...);
 }
 
@@ -245,11 +245,17 @@ extern void printError(const char* format, ...);
 // Hardware buffer
 namespace gameplay
 {
+/** Vertex attribute. */
 typedef GLint VertexAttribute;
+/** Vertex buffer handle. */
 typedef GLuint VertexBufferHandle;
+/** Index buffer handle. */
 typedef GLuint IndexBufferHandle;
+/** Texture handle. */
 typedef GLuint TextureHandle;
+/** Frame buffer handle. */
 typedef GLuint FrameBufferHandle;
+/** Render buffer handle. */
 typedef GLuint RenderBufferHandle;
 }
 

gameplay/src/Bundle.h

@@ -388,7 +388,7 @@ private:
      * Reads the animation channel data at the current file position into the given animation
      * (with the given animation target and target attribute).
      * 
-     * Note: this is used by #loadNode(const char*, Scene*) and #readAnimationChannel(Scene*, Animation*, const char*).
+     * Note: this is used by Bundle::loadNode(const char*, Scene*) and Bundle::readAnimationChannel(Scene*, Animation*, const char*).
      * 
      * @param animation The animation to the load channel into.
      * @param id The ID of the animation that this channel is loaded into.

gameplay/src/Container.h

@@ -174,7 +174,7 @@ public:
     bool isScrollBarsAutoHide() const;
 
     /**
-     * @see AnimationTarget#getAnimation
+     * @see AnimationTarget::getAnimation
      */
     Animation* getAnimation(const char* id = NULL) const;
 
@@ -189,17 +189,17 @@ public:
     const char* getType() const;
 
     /**
-     * @see AnimationTarget#getAnimationPropertyComponentCount
+     * @see AnimationTarget::getAnimationPropertyComponentCount
      */
     virtual unsigned int getAnimationPropertyComponentCount(int propertyId) const;
 
     /**
-     * @see AnimationTarget#getAnimationProperty
+     * @see AnimationTarget::getAnimationProperty
      */
     virtual void getAnimationPropertyValue(int propertyId, AnimationValue* value);
 
     /**
-     * @see AnimationTarget#setAnimationProperty
+     * @see AnimationTarget::setAnimationProperty
      */
     virtual void setAnimationPropertyValue(int propertyId, AnimationValue* value, float blendWeight = 1.0f);
 
@@ -339,8 +339,34 @@ protected:
      */
     bool touchEventScroll(Touch::TouchEvent evt, int x, int y, unsigned int contactIndex);
 
+    /**
+     * Mouse scroll event callback.
+     *
+     * @param evt The mouse scroll event that occurred.
+     * @param x The x position of the scroll in pixels. Left edge is zero.
+     * @param y The y position of the scroll in pixels. Top edge is zero.
+     * @param wheelDelta The value change of the mouse's scroll wheel.
+     *
+     * @return Whether the scroll event was consumed by scrolling within this container.
+     *
+     * @see Mouse::MouseEvent
+     */
     bool mouseEventScroll(Mouse::MouseEvent evt, int x, int y, int wheelDelta);
 
+    /**
+     * Mouse pointer event callback.
+     *
+     * @param mouse Whether to treat the event as a mouse event or a touch event.
+     * @param evt The pointer event (either a Mouse::MouseEvent or a Touch::TouchEvent).
+     * @param x The x position of the pointer event in pixels. Left edge is zero.
+     * @param y The y position of the pointer event in pixels. Top edge is zero.
+     * @param data The event's data (depends on whether it is a mouse event or a touch event).
+     *
+     * @return Whether the pointer event was consumed by this container.
+     * 
+     * @see Mouse::MouseEvent
+     * @see Touch::TouchEvent
+     */
     bool pointerEvent(bool mouse, char evt, int x, int y, int data);
 
     /**

gameplay/src/Control.h

@@ -723,7 +723,7 @@ public:
      * pass <code>Control::Listener::TOUCH | Control::Listener::RELEASE</code>
      * as the second parameter.
      * 
-     * Note: the given Lua function must have the same function signature as Control#Listener#controlEvent.
+     * Note: the given Lua function must have the same function signature as Control::Listener::controlEvent.
      *
      * @param function The name of the Lua script function to add as a listener callback.
      * @param eventFlags The events to listen for.
@@ -731,17 +731,17 @@ public:
     virtual void addListener(const char* function, int eventFlags);
 
     /**
-     * @see AnimationTarget#getAnimationPropertyComponentCount
+     * @see AnimationTarget::getAnimationPropertyComponentCount
      */
     virtual unsigned int getAnimationPropertyComponentCount(int propertyId) const;
 
     /**
-     * @see AnimationTarget#getAnimationProperty
+     * @see AnimationTarget::getAnimationProperty
      */
     virtual void getAnimationPropertyValue(int propertyId, AnimationValue* value);
 
     /**
-     * @see AnimationTarget#setAnimationProperty
+     * @see AnimationTarget::setAnimationProperty
      */
     virtual void setAnimationPropertyValue(int propertyId, AnimationValue* value, float blendWeight = 1.0f);
 

gameplay/src/Form.h

@@ -196,7 +196,7 @@ private:
      *
      * @return The next highest power of two after x, or x if it is already a power of two.
      */
-    static unsigned int nextPowerOfTwo(unsigned int v);
+    static unsigned int nextPowerOfTwo(unsigned int x);
 
     /**
      * Unproject a point (from a mouse or touch event) into the scene and then project it onto the form.

gameplay/src/Game.h

@@ -377,7 +377,7 @@ public:
      * Game time stops while the game is paused. A time offset of zero will fire the time event in the next frame.
      * 
      * Note: the given Lua function must take a single floating point number, which is the difference between the
-     * current game time and the target time (see @link{TimeListener#timeEvent}).
+     * current game time and the target time (see TimeListener::timeEvent).
      * 
      * @param timeOffset The number of game milliseconds in the future to schedule the event to be fired.
      * @param function The Lua script function that will receive the event.
@@ -498,6 +498,9 @@ private:
 
     /** 
      * Creates a Gamepad object from a .form file.
+     *
+     * @param gamepadId The gamepad id (typically equal to the corresponding player's number).
+     * @param gamepadFormPath The path to the .form file.
      */
     Gamepad* createGamepad(const char* gamepadId, const char* gamepadFormPath);
 

gameplay/src/Gamepad.h

@@ -112,14 +112,16 @@ private:
 
     /**
      * Constructor.
+     * 
+     * @param id The gamepad's id.
      */
     Gamepad(const char* id);
     
     /**
-     * Constructor.
-     * Create a gamepad from the specified formPath.
+     * Constructs a gamepad from the specified .form file.
      *
-     * @param formPath
+     * @param id The gamepad's id.
+     * @param formPath The path the the .form file.
      */ 
     Gamepad(const char* id, const char* formPath);
 

gameplay/src/Joystick.h

@@ -49,7 +49,7 @@ public:
      * Sets the region within which the joystick will be spontaneously created on a user's touch.
      * 
      * Note: This does not actually enable spontaneous joystick creation on touch input.
-     * To enable (or disable) absolute position explicitly, use #setAbsolute.
+     * To enable (or disable) absolute position explicitly, use setAbsolute(bool).
      * 
      * @param region The region to use.
      */
@@ -60,7 +60,7 @@ public:
      * 
      * Note: just because the returned region is not empty does not mean that it is necessarily
      * being used. If absolute positioning is not enabled, then it will be used (to check if
-     * absolute positioning is enabled, call #isAbsolute).
+     * absolute positioning is enabled, call isAbsolute()).
      * 
      * @return The region within which the joystick will be spontaneously created on a user's touch.
      */

gameplay/src/MaterialParameter.h

@@ -184,17 +184,17 @@ public:
     void bindValue(Node* node, const char* binding);
 
     /**
-     * @see AnimationTarget#getAnimationPropertyComponentCount
+     * @see AnimationTarget::getAnimationPropertyComponentCount
      */
     unsigned int getAnimationPropertyComponentCount(int propertyId) const;
 
     /**
-     * @see AnimationTarget#getAnimationProperty
+     * @see AnimationTarget::getAnimationProperty
      */
     void getAnimationPropertyValue(int propertyId, AnimationValue* value);
 
     /**
-     * @see AnimationTarget#setAnimationProperty
+     * @see AnimationTarget::setAnimationProperty
      */
     void setAnimationPropertyValue(int propertyId, AnimationValue* value, float blendWeight = 1.0f);
 

gameplay/src/PhysicsCharacter.h

@@ -26,7 +26,7 @@ class PhysicsCharacter : public PhysicsGhostObject, public btActionInterface
 public:
 
     /**
-     * @see PhysicsCollisionObject#getType
+     * @see PhysicsCollisionObject::getType
      */
     PhysicsCollisionObject::Type getType() const;
 

gameplay/src/PhysicsCollisionObject.h

@@ -202,7 +202,7 @@ public:
     /**
      * Adds a collision listener for this collision object.
      * 
-     * Note: the given Lua function must match the function signature of PhysicsCollisionObject#CollisionListener#collisionEvent.
+     * Note: the given Lua function must match the function signature of PhysicsCollisionObject::CollisionListener::collisionEvent.
      * 
      * @param function The Lua script function to add as a listener callback.
      * @param object Optional collision object used to filter the collision event.
@@ -254,12 +254,12 @@ protected:
         virtual ~PhysicsMotionState();
 
         /**
-         * @see btMotionState#getWorldTransform
+         * @see btMotionState::getWorldTransform
          */
         virtual void getWorldTransform(btTransform &transform) const;
 
         /**
-         * @see btMotionState#setWorldTransform
+         * @see btMotionState::setWorldTransform
          */
         virtual void setWorldTransform(const btTransform &transform);
 

gameplay/src/PhysicsCollisionShape.h

@@ -76,11 +76,11 @@ public:
     private:
 
         /**
-         * Creates a PhysicsCollisionShape#Definition object from the given properties object (for the given node).
+         * Creates a PhysicsCollisionShape::Definition object from the given properties object (for the given node).
          * 
          * @param node The node to create the PhysicsCollisionShape::Definition object for.
-         * @param properties The properties object to create the PhysicsCollisionShape#Definition object from.
-         * @return A PhysicsCollisionShape#Definition object.
+         * @param properties The properties object to create the PhysicsCollisionShape::Definition object from.
+         * @return A PhysicsCollisionShape::Definition object.
          */
         static Definition* create(Node* node, Properties* properties);
 

gameplay/src/PhysicsController.h

@@ -156,7 +156,7 @@ public:
     /**
      * Adds a listener to the physics controller.
      * 
-     * Note: the given Lua function must have the same function signature as PhysicsController#Listener#statusEvent.
+     * Note: the given Lua function must have the same function signature as PhysicsController::Listener::statusEvent.
      * 
      * @param function The Lua script function to use as the listener callback.
      */

gameplay/src/PhysicsGhostObject.h

@@ -21,7 +21,7 @@ class PhysicsGhostObject : public PhysicsCollisionObject, public Transform::List
 public:
 
     /**
-     * @see PhysicsCollisionObject#getType
+     * @see PhysicsCollisionObject::getType
      */
     PhysicsCollisionObject::Type getType() const;
 

gameplay/src/PhysicsRigidBody.h

@@ -93,7 +93,7 @@ public:
     };
 
     /**
-     * @see PhysicsCollisionObject#getType
+     * @see PhysicsCollisionObject::getType
      */
     PhysicsCollisionObject::Type getType() const;
 
@@ -198,7 +198,7 @@ public:
 
     /**
      * Gets the gravity that affects the rigid body (this can
-     * be different from the global gravity; @see #setGravity).
+     * be different from the global gravity; @see setGravity(Vector3)).
      * 
      * @return The gravity.
      */

gameplay/src/ScreenDisplayer.h

@@ -25,21 +25,21 @@ public:
     ~ScreenDisplayer();
 
     /**
-     * Displays a screen using the {@link Game#renderOnce} mechanism for at least the given amount of time.
+     * Displays a screen using the Game::renderOnce() mechanism for at least the given amount of time.
      * 
-     * @param instance See {@link Game#renderOnce}.
-     * @param method See {@link Game#renderOnce}.
-     * @param cookie See {@link Game#renderOnce}.
+     * @param instance See Game::renderOnce().
+     * @param method See Game::renderOnce().
+     * @param cookie See Game::renderOnce().
      * @param time The minimum amount of time to display the screen (in milliseconds).
      */
     template <typename T> void run(T* instance, void (T::*method) (void*), void* cookie, unsigned long time);
 
     /**
-     * Starts a new screen displayer running; draws a screen using the {@link Game#renderOnce} mechanism for at least the given amount of time.
+     * Starts a new screen displayer running; draws a screen using the {@link Game::renderOnce} mechanism for at least the given amount of time.
      * 
      * Note: this is intended for use from Lua scripts.
      * 
-     * @param function See {@link Game#renderOnce(const char*)}.
+     * @param function See {@link Game::renderOnce(const char*)}.
      * @param time The minimum amount of time to display the screen (in milliseconds).
      */
     static void start(const char* function, unsigned long time);
@@ -66,14 +66,14 @@ template <typename T> void ScreenDisplayer::run(T* instance, void (T::*method) (
 }
 
 /**
- * Displays a screen using the {@link Game#renderOnce} mechanism for at least the given amount
+ * Displays a screen using the {@link gameplay::Game::renderOnce} mechanism for at least the given amount
  * of time. This function is intended to be called at the beginning of a block of code that is be 
  * executed while the screen is displayed (i.e. Game#initialize). This function will block 
  * at the end of the block of code in which it is called for the amount of time that has not yet elapsed.
  * 
- * @param instance See {@link Game#renderOnce}.
- * @param method See {@link Game#renderOnce}.
- * @param cookie See {@link Game#renderOnce}.
+ * @param instance See {@link gameplay::Game::renderOnce}.
+ * @param method See {@link gameplay::Game::renderOnce}.
+ * @param cookie See {@link gameplay::Game::renderOnce}.
  * @param time The minimum amount of time to display the screen (in milliseconds).
  */
 #define displayScreen(instance, method, cookie, time) \

gameplay/src/ScriptController.h

@@ -53,19 +53,31 @@ public:
      */
     template<typename T> T executeFunction(const char* func, const char* args, ...);
 
-    // Template specializations.
+    /** Template specialization. */
     template<> void executeFunction<void>(const char* func, const char* args, ...);
+    /** Template specialization. */
     template<> bool executeFunction<bool>(const char* func, const char* args, ...);
+    /** Template specialization. */
     template<> char executeFunction<char>(const char* func, const char* args, ...);
+    /** Template specialization. */
     template<> short executeFunction<short>(const char* func, const char* args, ...);
+    /** Template specialization. */
     template<> int executeFunction<int>(const char* func, const char* args, ...);
+    /** Template specialization. */
     template<> long executeFunction<long>(const char* func, const char* args, ...);
+    /** Template specialization. */
     template<> unsigned char executeFunction<unsigned char>(const char* func, const char* args, ...);
+    /** Template specialization. */
     template<> unsigned short executeFunction<unsigned short>(const char* func, const char* args, ...);
+    /** Template specialization. */
     template<> unsigned int executeFunction<unsigned int>(const char* func, const char* args, ...);
+    /** Template specialization. */
     template<> unsigned long executeFunction<unsigned long>(const char* func, const char* args, ...);
+    /** Template specialization. */
     template<> float executeFunction<float>(const char* func, const char* args, ...);
+    /** Template specialization. */
     template<> double executeFunction<double>(const char* func, const char* args, ...);
+    /** Template specialization. */
     template<> std::string executeFunction<std::string>(const char* func, const char* args, ...);
 
     /**
@@ -74,7 +86,9 @@ public:
      */
     struct Type
     {
+        /** Constructor. */
         explicit Type(const char* type) : type(type) {}
+        /** The name of the type. */
         const char* type;
     };
 
@@ -214,6 +228,7 @@ public:
      * Gets a string for the given stack index.
      * 
      * @param index The stack index.
+     * @param isStdString Whether the string being retrieved is a std::string object or not.
      * @return The string or <code>NULL</code>.
      * @script{ignore}
      */
@@ -459,7 +474,7 @@ public:
      * Registers the given library with Lua.
      * 
      * @param name The name of the library from within Lua.
-     * @param function The library function mapping (Lua function names to C++ functions).
+     * @param functions The library function mapping (Lua function names to C++ functions).
      * @script{ignore}
      */
     void registerLibrary(const char* name, const luaL_Reg* functions);

gameplay/src/ScriptListener.h

@@ -28,7 +28,7 @@ class ScriptListener : public AnimationClip::Listener, public PhysicsCollisionOb
     friend class Transform;
 
 public:
-    /** @see AnimationClip#Listener */
+    /** @see AnimationClip::Listener */
     void animationEvent(AnimationClip* clip, AnimationClip::Listener::EventType type);
         
     /** @see PhysicsCollisionObject::CollisionListener */

gameplay/src/SpriteBatch.h

@@ -322,7 +322,7 @@ private:
      * @param u2 Texture coordinate.
      * @param v2 Texture coordinate.
      * @param color The color to tint the sprite. Use white for no tint.
-     * @param clip The clip rectangle.
+     * @param vertices The vertices to draw.
      */
     void addSprite(float x, float y, float width, float height, float u1, float v1, float u2, float v2, const Vector4& color, SpriteBatch::SpriteVertex* vertices);
 
@@ -339,6 +339,7 @@ private:
      * @param v2 Texture coordinate.
      * @param color The color to tint the sprite. Use white for no tint.
      * @param clip The clip rectangle.
+     * @param vertices The vertices to draw.
      */
     void addSprite(float x, float y, float width, float height, float u1, float v1, float u2, float v2, const Vector4& color, const Rectangle& clip, SpriteBatch::SpriteVertex* vertices);
 

gameplay/src/ThemeStyle.h

@@ -137,17 +137,17 @@ private:
         const Theme::UVs& getCursorUVs() const;
 
         /**
-         * @see AnimationTarget#getAnimationPropertyComponentCount
+         * @see AnimationTarget::getAnimationPropertyComponentCount
          */
         unsigned int getAnimationPropertyComponentCount(int propertyId) const;
 
         /**
-         * @see AnimationTarget#getAnimationProperty
+         * @see AnimationTarget::getAnimationProperty
          */
         void getAnimationPropertyValue(int propertyId, AnimationValue* value);
 
         /**
-         * @see AnimationTarget#setAnimationProperty
+         * @see AnimationTarget::setAnimationProperty
          */
         void setAnimationPropertyValue(int propertyId, AnimationValue* value, float blendWeight = 1.0f);
        

gameplay/src/Transform.h

@@ -739,7 +739,7 @@ public:
     /**
      * Adds a transform listener.
      *
-     * Note: the given Lua function must match the function signature of Transform#Listener#transformChanged.
+     * Note: the given Lua function must match the function signature of Transform::Listener::transformChanged.
      * 
      * @param function The Lua script function to add as a listener callback.
      * @param cookie An optional long value that is passed to the specified listener when it is called.
@@ -754,17 +754,17 @@ public:
     void removeListener(const char* function);
     
     /**
-     * @see AnimationTarget#getAnimationPropertyComponentCount
+     * @see AnimationTarget::getAnimationPropertyComponentCount
      */
     unsigned int getAnimationPropertyComponentCount(int propertyId) const;
 
     /**
-     * @see AnimationTarget#getAnimationProperty
+     * @see AnimationTarget::getAnimationProperty
      */
     void getAnimationPropertyValue(int propertyId, AnimationValue* value);
 
     /**
-     * @see AnimationTarget#setAnimationProperty
+     * @see AnimationTarget::setAnimationProperty
      */
     void setAnimationPropertyValue(int propertyId, AnimationValue* value, float blendWeight = 1.0f);