Improve Doxygen API Reference documentation

include/reactphysics3d/collision/CollisionCallback.h

@@ -40,7 +40,6 @@ class ContactManifold;
 class CollisionBody;
 class Collider;
 class MemoryManager;
-class CollisionCallbackInfo;
 
 // Class CollisionCallback
 /**
@@ -55,7 +54,7 @@ class CollisionCallback {
 
         // Class ContactPoint
         /**
-         * This class represents a contact point between two bodies of the physics world.
+         * This class represents a contact point between two colliders of the physics world.
          */
         class ContactPoint {
 
@@ -78,21 +77,33 @@ class CollisionCallback {
                 ContactPoint(const ContactPoint& contactPoint) = default;
 
                 /// Assignment operator
-                ContactPoint& operator=(const ContactPoint& contactPoint) = default;
+                ContactPoint& operator=(const ContactPoint& contactPoint) = delete;
 
                 /// Destructor
                 ~ContactPoint() = default;
 
                 /// Return the penetration depth
+                /**
+                 * @return The penetration depth between the two colliders at this contact point
+                 */
                 decimal getPenetrationDepth() const;
 
                 /// Return the world-space contact normal
+                /**
+                 * @return The world-space contact normal
+                 */
                 const Vector3& getWorldNormal() const;
 
                 /// Return the contact point on the first collider in the local-space of the first collider
+                /**
+                 * @return The local-space contact point on the first collider
+                 */
                 const Vector3& getLocalPointOnCollider1() const;
 
                 /// Return the contact point on the second collider in the local-space of the second collider
+                /**
+                 * @return The local-space contact point on the second collider
+                 */
                 const Vector3& getLocalPointOnCollider2() const;
 
                 // -------------------- Friendship -------------------- //
@@ -102,7 +113,7 @@ class CollisionCallback {
 
         // Class ContactPair
         /**
-         * This class represents the contact between two bodies of the physics world.
+         * This class represents the contact between two colliders of the physics world.
          * A contact pair contains a list of contact points.
          */
         class ContactPair {
@@ -152,30 +163,52 @@ class CollisionCallback {
                 ContactPair(const ContactPair& contactPair) = default;
 
                 /// Assignment operator
-                ContactPair& operator=(const ContactPair& contactPair) = default;
+                ContactPair& operator=(const ContactPair& contactPair) = delete;
 
                 /// Destructor
                 ~ContactPair() = default;
 
                 /// Return the number of contact points in the contact pair
+                /**
+                 * @return The number of contact points in the contact pair
+                 */
                 uint getNbContactPoints() const;
 
                 /// Return a given contact point
+                /**
+                 * @param index Index of the contact point to retrieve
+                 * @return A contact point object
+                 */
                 ContactPoint getContactPoint(uint index) const;
 
                 /// Return a pointer to the first body in contact
+                /**
+                 * @return A pointer to the first colliding body of the pair
+                 */
                 CollisionBody* getBody1() const;
 
                 /// Return a pointer to the second body in contact
+                /**
+                 * @return A pointer to the second colliding body of the pair
+                 */
                 CollisionBody* getBody2() const;
 
                 /// Return a pointer to the first collider in contact (in body 1)
+                /**
+                 * @return A pointer to the first collider of the contact pair
+                 */
                 Collider* getCollider1() const;
 
                 /// Return a pointer to the second collider in contact (in body 2)
+                /**
+                 * @return A pointer to the second collider of the contact pair
+                 */
                 Collider* getCollider2() const;
 
                 /// Return the corresponding type of event for this contact pair
+                /**
+                 * @return The type of contact event for this contact pair
+                 */
                 EventType getEventType() const;
 
                 // -------------------- Friendship -------------------- //
@@ -235,9 +268,16 @@ class CollisionCallback {
                 // -------------------- Methods -------------------- //
 
                 /// Return the number of contact pairs
+                /**
+                 * @return The number of contact pairs
+                 */
                 uint getNbContactPairs() const;
 
                 /// Return a given contact pair
+                /**
+                 * @param index Index of the contact pair to retrieve
+                 * @return A contact pair object
+                 */
                 ContactPair getContactPair(uint index) const;
 
                 // -------------------- Friendship -------------------- //

include/reactphysics3d/engine/EventListener.h

@@ -34,11 +34,10 @@ namespace reactphysics3d {
 
 // Class EventListener
 /**
- * This class can be used to receive event callbacks from the physics engine.
+ * This class can be used to receive notifications about events that occur during the simulation.
  * In order to receive callbacks, you need to create a new class that inherits from
- * this one and you must override the methods you need. Then, you need to register your
+ * this one and you must override the methods that you need. Then, you will need to register your
- * new event listener class to the physics world using the PhysicsWorld::setEventListener()
+ * new event listener class to the physics world using the PhysicsWorld::setEventListener() method.
- * method.
  */
 class EventListener : public CollisionCallback {
 

include/reactphysics3d/engine/PhysicsWorld.h

@@ -78,7 +78,7 @@ class PhysicsWorld {
             /// Name of the world
             std::string worldName;
 
-            /// Gravity vector of the world
+            /// Gravity force vector of the world (in Newtons)
             Vector3 gravity;
 
             /// Distance threshold for two contact points for a valid persistent contact (in meters)
@@ -567,6 +567,9 @@ inline void PhysicsWorld::testOverlap(CollisionBody* body, OverlapCallback& over
 /// Use this method if you are not interested in contacts but if you simply want to know
 /// which bodies overlap. If you want to get the contacts, you need to use the
 /// testCollision() method instead.
+/**
+ * @param overlapCallback Pointer to the callback class to report overlap
+ */
 inline void PhysicsWorld::testOverlap(OverlapCallback& overlapCallback) {
     mCollisionDetection.testOverlap(overlapCallback);
 }
@@ -700,6 +703,9 @@ inline void PhysicsWorld::setEventListener(EventListener* eventListener) {
 
 // Return the number of CollisionBody in the physics world
 /// Note that even if a RigidBody is also a collision body, this method does not return the rigid bodies
+/**
+ * @return The number of collision bodies in the physics world
+ */
 inline uint PhysicsWorld::getNbCollisionBodies() const {
    return mCollisionBodies.size();
 }
@@ -733,6 +739,9 @@ inline CollisionBody* PhysicsWorld::getCollisionBody(uint index) {
 }
 
 // Return the number of RigidBody in the physics world
+/**
+ * @return The number of rigid bodies in the physics world
+ */
 inline uint PhysicsWorld::getNbRigidBodies() const {
    return mRigidBodies.size();
 }
@@ -766,16 +775,25 @@ inline RigidBody* PhysicsWorld::getRigidBody(uint index) {
 }
 
 // Return true if the debug rendering is enabled
+/**
+ * @return True if the debug rendering is enabled and false otherwise
+ */
 inline bool PhysicsWorld::getIsDebugRenderingEnabled() const {
     return mIsDebugRenderingEnabled;
 }
 
 // Set to true if debug rendering is enabled
+/**
+ * @param isEnabled True if you want to enable the debug rendering and false otherwise
+ */
 inline void PhysicsWorld::setIsDebugRenderingEnabled(bool isEnabled) {
     mIsDebugRenderingEnabled = isEnabled;
 }
 
 // Return a reference to the Debug Renderer of the world
+/**
+ * @return A reference to the DebugRenderer object of the world
+ */
 inline DebugRenderer& PhysicsWorld::getDebugRenderer() {
     return mDebugRenderer;
 }

include/reactphysics3d/utils/DebugRenderer.h

@@ -260,41 +260,67 @@ class DebugRenderer : public EventListener {
 };
 
 // Return the number of lines
+/**
+ * @return The number of lines in the array of lines to draw
+ */
 inline uint32 DebugRenderer::getNbLines() const {
 	return mLines.size();
 }
 
 // Return a reference to the list of lines
+/**
+ * @return The list of lines to draw
+ */
 inline const List<DebugRenderer::DebugLine>& DebugRenderer::getLines() const {
 	return mLines;
 }
 
 // Return a pointer to the array of lines
+/**
+ * @return A pointer to the first element of the lines array to draw
+ */
 inline const DebugRenderer::DebugLine* DebugRenderer::getLinesArray() const {
 	return &(mLines[0]);
 }
 
 // Return the number of triangles
+/**
+ * @return The number of triangles in the array of triangles to draw
+ */
 inline uint32 DebugRenderer::getNbTriangles() const {
 	return mTriangles.size();
 }
 
 // Return a reference to the list of triangles
+/**
+ * @return The list of triangles to draw
+ */
 inline const List<DebugRenderer::DebugTriangle>& DebugRenderer::getTriangles() const {
 	return mTriangles;
 }
 
 // Return a pointer to the array of triangles
+/**
+ * @return A pointer to the first element of the triangles array to draw
+ */
 inline const DebugRenderer::DebugTriangle* DebugRenderer::getTrianglesArray() const {
 	return &(mTriangles[0]);
 }
 
 // Return whether a debug item is displayed or not
+/**
+ * @param item A debug item
+ * @return True if the given debug item is being displayed and false otherwise
+ */
 inline bool DebugRenderer::getIsDebugItemDisplayed(DebugItem item) const {
 	return mDisplayedDebugItems & static_cast<uint32>(item);
 }
 
 // Set whether a debug info is displayed or not
+/**
+ * @param item A debug item to draw
+ * @param isDisplayed True if the given debug item has to be displayed and false otherwise
+ */
 inline void DebugRenderer::setIsDebugItemDisplayed(DebugItem item, bool isDisplayed) {
 	const uint32 itemFlag = static_cast<uint32>(item);
 	uint32 resetBit = ~(itemFlag);
@@ -305,11 +331,17 @@ inline void DebugRenderer::setIsDebugItemDisplayed(DebugItem item, bool isDispla
 }
 
 // Get the contact point sphere radius
+/**
+ * @return The radius of the sphere used to display a contact point
+ */
 inline decimal DebugRenderer::getContactPointSphereRadius() const {
     return mContactPointSphereRadius;
 }
 
 // Set the contact point sphere radius
+/**
+ * @param radius The radius of the sphere used to display a contact point
+ */
 inline void DebugRenderer::setContactPointSphereRadius(decimal radius) {
     assert(radius > decimal(0.0));
     mContactPointSphereRadius = radius;
@@ -317,11 +349,17 @@ inline void DebugRenderer::setContactPointSphereRadius(decimal radius) {
 
 
 // Return the length of contact normal
+/**
+ * @return The length of the contact normal to display
+ */
 inline decimal DebugRenderer::getContactNormalLength() const {
     return mContactNormalLength;
 }
 
 // Return the length of contact normal
+/**
+ * @param contactNormalLength The length of the contact normal to display
+ */
 inline void DebugRenderer::setContactNormalLength(decimal contactNormalLength) {
     mContactNormalLength = contactNormalLength;
 }

src/body/RigidBody.cpp

@@ -44,6 +44,9 @@ RigidBody::RigidBody(PhysicsWorld& world, Entity entity) : CollisionBody(world,
 }
 
 // Return the type of the body
+/**
+ * @return The type of rigid body (static, kinematic or dynamic)
+ */
 BodyType RigidBody::getType() const {
     return mWorld.mRigidBodyComponents.getBodyType(mEntity);
 }
@@ -136,7 +139,7 @@ decimal RigidBody::getMass() const {
 /// reset to zero at the end of each call of the PhyscisWorld::update() method.
 /// You can only apply a force to a dynamic body otherwise, this method will do nothing.
 /**
- * @param force The force to apply on the body
+ * @param force The force to apply on the body (in Newtons)
  * @param point The point where the force is applied (in local-space coordinates)
  */
 void RigidBody::applyForceAtLocalPosition(const Vector3& force, const Vector3& point) {
@@ -168,7 +171,7 @@ void RigidBody::applyForceAtLocalPosition(const Vector3& force, const Vector3& p
 /// reset to zero at the end of each call of the PhyscisWorld::update() method.
 /// You can only apply a force to a dynamic body otherwise, this method will do nothing.
 /**
- * @param force The force to apply on the body
+ * @param force The force to apply on the body (in Newtons)
  * @param point The point where the force is applied (in world-space coordinates)
  */
 void RigidBody::applyForceAtWorldPosition(const Vector3& force, const Vector3& point) {
@@ -192,6 +195,9 @@ void RigidBody::applyForceAtWorldPosition(const Vector3& force, const Vector3& p
 }
 
 // Return the local inertia tensor of the body (in body coordinates)
+/**
+ * @return A vector with the three values of the diagonal 3x3 matrix of the local-space inertia tensor
+ */
 const Vector3& RigidBody::getLocalInertiaTensor() const {
 
     return mWorld.mRigidBodyComponents.getLocalInertiaTensor(mEntity);
@@ -200,8 +206,7 @@ const Vector3& RigidBody::getLocalInertiaTensor() const {
 // Set the local inertia tensor of the body (in local-space coordinates)
 /// Note that an inertia tensor with a zero value on its diagonal is interpreted as infinite inertia.
 /**
- * @param inertiaTensorLocal The 3x3 inertia tensor matrix of the body in local-space
+ * @param inertiaTensorLocal A vector with the three values of the diagonal 3x3 matrix of the local-space inertia tensor
- *                           coordinates
  */
 void RigidBody::setLocalInertiaTensor(const Vector3& inertiaTensorLocal) {
 
@@ -223,7 +228,7 @@ void RigidBody::setLocalInertiaTensor(const Vector3& inertiaTensorLocal) {
 /// reset to zero at the end of each call of the PhyscisWorld::update() method.
 /// You can only apply a force to a dynamic body otherwise, this method will do nothing.
 /**
- * @param force The external force to apply on the center of mass of the body
+ * @param force The external force to apply on the center of mass of the body (in Newtons)
  */
 void RigidBody::applyForceToCenterOfMass(const Vector3& force) {
 
@@ -281,6 +286,9 @@ void RigidBody::setLocalCenterOfMass(const Vector3& centerOfMass) {
 }
 
 // Return the center of mass of the body (in local-space coordinates)
+/**
+ * @return The local-space position of the center of mass of the body
+ */
 const Vector3& RigidBody::getLocalCenterOfMass() const {
     return mWorld.mRigidBodyComponents.getCenterOfMassLocal(mEntity);
 }
@@ -550,7 +558,7 @@ void RigidBody::setMass(decimal mass) {
 /// returned collider to get and set information about the corresponding
 /// collision shape for that body.
 /**
- * @param collisionShape The collision shape of the new collider
+ * @param collisionShape A pointer to the collision shape of the new collider
  * @param transform The transformation of the collider that transforms the
  *        local-space of the collider into the local-space of the body
  * @return A pointer to the collider that has been created

src/collision/Collider.cpp

@@ -103,7 +103,10 @@ void Collider::setCollideWithMaskBits(unsigned short collideWithMaskBits) {
              std::to_string(collideWithMaskBits),  __FILE__, __LINE__);
 }
 
-// Set the local to parent body transform
+// Set the local to  body transform
+/**
+ * @param transform The transform from local-space of the collider into the local-space of the body
+ */
 void Collider::setLocalToBodyTransform(const Transform& transform) {
 
     mBody->mWorld.mCollidersComponents.setLocalToBodyTransform(mEntity, transform);
@@ -137,7 +140,7 @@ const AABB Collider::getWorldAABB() const {
 
 // Return a pointer to the collision shape
 /**
- * @return Pointer to the internal collision shape
+ * @return Pointer to the collision shape
  */
 CollisionShape* Collider::getCollisionShape() {
     return mBody->mWorld.mCollidersComponents.getCollisionShape(mEntity);
@@ -145,7 +148,7 @@ CollisionShape* Collider::getCollisionShape() {
 
 // Return a const pointer to the collision shape
 /**
- * @return Pointer to the internal collision shape
+ * @return Pointer to the collision shape
  */
 const CollisionShape* Collider::getCollisionShape() const {
     return mBody->mWorld.mCollidersComponents.getCollisionShape(mEntity);
@@ -158,8 +161,8 @@ int Collider::getBroadPhaseId() const {
 
 // Return the local to parent body transform
 /**
- * @return The transformation that transforms the local-space of the collision shape
+ * @return The transformation that transforms the local-space of the collider
- *         to the local-space of the parent body
+ *         to the local-space of the body
  */
 const Transform& Collider::getLocalToBodyTransform() const {
     return mBody->mWorld.mCollidersComponents.getLocalToBodyTransform(mEntity);
@@ -238,11 +241,17 @@ const Transform Collider::getLocalToWorldTransform() const {
 }
 
 // Return true if the collider is a trigger
+/**
+ * @return True if this collider is a trigger and false otherwise
+ */
 bool Collider::getIsTrigger() const {
    return mBody->mWorld.mCollidersComponents.getIsTrigger(mEntity);
 }
 
 // Set whether the collider is a trigger
+/**
+ * @param isTrigger True if you want to set this collider as a trigger and false otherwise
+ */
 void Collider::setIsTrigger(bool isTrigger) const {
    mBody->mWorld.mCollidersComponents.setIsTrigger(mEntity, isTrigger);
 }

src/collision/CollisionCallback.cpp

@@ -75,7 +75,7 @@ CollisionCallback::ContactPair::EventType CollisionCallback::ContactPair::getEve
     return EventType::ContactStart;
 }
 
-// CollisionCallbackInfo Constructor
+// Constructor
 CollisionCallback::CallbackData::CallbackData(List<reactphysics3d::ContactPair>* contactPairs, List<ContactManifold>* manifolds,
                                               List<reactphysics3d::ContactPoint>* contactPoints, List<reactphysics3d::ContactPair>& lostContactPairs, PhysicsWorld& world)
                       :mContactPairs(contactPairs), mContactManifolds(manifolds), mContactPoints(contactPoints), mLostContactPairs(lostContactPairs),