issue #2771: add comments

cocos2dx/physics/CCPhysicsBody.h

@@ -46,42 +46,126 @@ class PhysicsShapeEdgePolygon;
 class PhysicsShapeEdgeChain;
 
 class PhysicsBodyInfo;
-
+/**
+ * A body affect by physics.
+ * it can attach one or more shapes.
+ */
 class PhysicsBody : public Object//, public Clonable
 {
 public:
+    /**
+     * @brief Create a body contains a circle shape.
+     */
     static PhysicsBody* createCircle(float radius);
+    /**
+     * @brief Create a body contains a box shape.
+     */
     static PhysicsBody* createBox(Size size);
+    /**
+     * @brief Create a body contains a polygon shape.
+     * points is an array of Point structs defining a convex hull with a clockwise winding.
+     */
     static PhysicsBody* createPolygon(Point* points, int count);
     
+    /**
+     * @brief Create a body contains a EdgeSegment shape.
+     */
     static PhysicsBody* createEdgeSegment(Point a, Point b, float border = 1);
+    /**
+     * @brief Create a body contains a EdgeBox shape.
+     */
     static PhysicsBody* createEdgeBox(Size size, float border = 1);
+    /**
+     * @brief Create a body contains a EdgePolygon shape.
+     */
     static PhysicsBody* createEdgePolygon(Point* points, int count, float border = 1);
+    /**
+     * @brief Create a body contains a EdgeChain shape.
+     */
     static PhysicsBody* createEdgeChain(Point* points, int count, float border = 1);
     
+    /**
+     * @brief Attach a circle shape with body
+     */
     virtual PhysicsShapeCircle* addCircle(float radius, Point offset = Point(0, 0));
+    /**
+     * @brief Attach a box shape with body
+     */
     virtual PhysicsShapeBox* addBox(Size size, Point offset = Point(0, 0));
+    /**
+     * @brief Attach a polygon shape with body
+     */
     virtual PhysicsShapePolygon* addPolygon(Point* points, int count, Point offset = Point(0, 0));
     
+    /**
+     * @brief Attach a edge segment shape with body
+     */
     virtual PhysicsShapeEdgeSegment* addEdgeSegment(Point a, Point b, float border = 1);
+    /**
+     * @brief Attach a edge box shape with body
+     */
     virtual PhysicsShapeEdgeBox* addEdgeBox(Size size, float border = 1, Point offset = Point(0, 0));
+    /**
+     * @brief Attach a edge polygon shape with body
+     * points is an array of Point structs defining a convex hull with a clockwise winding.
+     */
     virtual PhysicsShapeEdgePolygon* addEdgePolygon(Point* points, int count, float border = 1);
+    /**
+     * @brief Attach a edge chain shape with body
+     * points is an array of Point structs defining a convex hull with a clockwise winding.
+     */
     virtual PhysicsShapeEdgeChain* addEdgeChain(Point* points, int count, float border = 1);
     
+    /**
+     * @brief Applies a immediate force to body.
+     */
     virtual void applyForce(Point force);
+    /**
+     * @brief Applies a immediate force to body.
+     */
     virtual void applyForce(Point force, Point offset);
+    /**
+     * @brief Applies a continuous force to body.
+     */
     virtual void applyImpulse(Point impulse);
+    /**
+     * @brief Applies a continuous force to body.
+     */
     virtual void applyImpulse(Point impulse, Point offset);
+    /**
+     * @brief Applies a torque force to body.
+     */
     virtual void applyTorque(float torque);
     
+    /*
+     * @brief get the body shapes.
+     */
     inline std::vector<PhysicsShape*>& getShapes() { return _shapes; }
+    /*
+     * @brief get the first body shapes.
+     */
     inline PhysicsShape* getShape() { return _shapes.size() >= 1 ? _shapes.front() : nullptr; }
+    /*
+     * @brief remove a shape from body
+     */
     void removeShape(PhysicsShape* shape);
+    /*
+     * @brief remove all shapes
+     */
     void removeAllShapes();
     
+    /*
+     * @brief get the world body added to.
+     */
     inline PhysicsWorld* getWorld() const { return _world; }
+    /*
+     * @brief get all joints the body have
+     */
     inline const std::vector<PhysicsJoint*>* getJoints() const { return &_joints; }
     
+    /*
+     * @brief get the sprite the body set to.
+     */
     inline Sprite* getOwner() const { return _owner; }
     
     void setCategoryBitmask(int bitmask);
@@ -91,16 +175,42 @@ public:
     void setCollisionBitmask(int bitmask);
     inline int getCollisionBitmask() const { return _collisionBitmask; }
     
+    /*
+     * @brief get the body position.
+     */
     Point getPosition() const;
+    /*
+     * @brief get the body rotation.
+     */
     float getRotation() const;
     
+    /*
+     * @brief test the body is dynamic or not.
+     * a dynamic body will effect with gravity.
+     */
     inline bool isDynamic() { return _dynamic; }
+    /*
+     * @brief set dynamic to body.
+     * a dynamic body will effect with gravity.
+     */
     void setDynamic(bool dynamic);
     
+    /*
+     * @brief set the body mass.
+     */
     void setMass(float mass);
+    /*
+     * @brief get the body mass.
+     */
     inline float getMass() { return _mass; }
     
+    /*
+     * @brief set angular damping.
+     */
     void setAngularDamping(float angularDamping);
+    /*
+     * @brief get angular damping.
+     */
     inline float getAngularDamping() { return _angularDamping; }
     
     //virtual Clonable* clone() const override;

cocos2dx/physics/CCPhysicsContact.h

@@ -38,12 +38,28 @@ class PhysicsWorld;
 
 class PhysicsContactInfo;
 
+/**
+ * @brief Contact infomation. it will created automatically when two shape contact with each other. and it will destoried automatically when two shape separated.
+ */
 class PhysicsContact
 {
 public:
+    /*
+     * @brief get contact shape A.
+     */
     inline PhysicsShape* getShapeA() { return _shapeA; }
+    /*
+     * @brief get contact shape B.
+     */
     inline PhysicsShape* getShapeB() { return _shapeB; }
+    /*
+     * @brief get data.
+     */
     inline void* getData() { return _data; }
+    /*
+     * @brief set data to contact. you must manage the memory yourself, Generally you can set data at contact begin, and distory it at contact end.
+     */
+    inline void setData(void* data) { _data = data; }
     
 private:
     static PhysicsContact* create(PhysicsShape* a, PhysicsShape* b);
@@ -62,6 +78,9 @@ private:
     friend class PhysicsWorld;
 };
 
+/*
+ * @brief presolve value generated when onContactPreSolve called.
+ */
 class PhysicsContactPreSolve
 {
 private:
@@ -74,6 +93,9 @@ private:
     friend class PhysicsWorld;
 };
 
+/*
+ * @brief postsolve value generated when onContactPostSolve called.
+ */
 class PhysicsContactPostSolve
 {
 private:
@@ -86,6 +108,9 @@ private:
     friend class PhysicsWorld;
 };
 
+/*
+ * @brief contact listener.
+ */
 class PhysicsContactListener
 {
 public:
@@ -93,10 +118,22 @@ public:
     virtual ~PhysicsContactListener();
     
 public:
+    /*
+     * @brief it will called at two shapes start to contact, and only call it once.
+     */
     std::function<bool(const PhysicsContact& contact)> onContactBegin;
+    /*
+     * @brief Two shapes are touching during this step. Return false from the callback to make world ignore the collision this step or true to process it normally. Additionally, you may override collision values, elasticity, or surface velocity values.
+     */
     std::function<bool(const PhysicsContact& contact, const PhysicsContactPreSolve& solve)> onContactPreSolve;
-    
+    /*
+     * @brief Two shapes are touching and their collision response has been processed. You can retrieve the collision impulse or kinetic energy at this time if you want to use it to calculate sound volumes or damage amounts. See cpArbiter for more info
+     */
     std::function<void(const PhysicsContact& contact, const PhysicsContactPostSolve& solve)> onContactPostSolve;
+    /*
+     * @brief it will called at two shapes separated, and only call it once.
+     * onContactBegin and onContactEnd will called in pairs.
+     */
     std::function<void(const PhysicsContact& contact)> onContactEnd;
 };
 

cocos2dx/physics/CCPhysicsJoint.h

@@ -37,6 +37,9 @@ class PhysicsBody;
 class PhysicsJointInfo;
 class PhysicsBodyInfo;
 
+/*
+ * @brief An PhysicsJoint object connects two physics bodies together.
+ */
 class PhysicsJoint : public Object
 {
 protected:
@@ -63,6 +66,9 @@ protected:
     friend class PhysicsBody;
 };
 
+/*
+ * @brief A fixed joint fuses the two bodies together at a reference point. Fixed joints are useful for creating complex shapes that can be broken apart later.
+ */
 class PhysicsJointFixed : public PhysicsJoint
 {
 public:
@@ -76,6 +82,9 @@ protected:
     virtual ~PhysicsJointFixed();
 };
 
+/*
+ * @brief A sliding joint allows the two bodies to slide along a chosen axis.
+ */
 class PhysicsJointSliding : public PhysicsJoint
 {
 public:
@@ -89,6 +98,9 @@ protected:
     virtual ~PhysicsJointSliding();
 };
 
+/*
+ * @brief A spring joint connects the two bodies with a spring whose length is the initial distance between the two bodies.
+ */
 class PhysicsJointSpring : public PhysicsJoint
 {
 public:
@@ -102,6 +114,9 @@ protected:
     virtual ~PhysicsJointSpring();
 };
 
+/*
+ * @brief A limit joint imposes a maximum distance between the two bodies, as if they were connected by a rope.
+ */
 class PhysicsJointLimit : public PhysicsJoint
 {
 public:
@@ -115,6 +130,9 @@ protected:
     virtual ~PhysicsJointLimit();
 };
 
+/*
+ * @brief A pin joint allows the two bodies to independently rotate around the anchor point as if pinned together.
+ */
 class PhysicsJointPin : public PhysicsJoint
 {
 public:

cocos2dx/physics/CCPhysicsShape.h

@@ -37,6 +37,9 @@ class PhysicsShapeInfo;
 class PhysicsBody;
 class PhysicsBodyInfo;
 
+/** 
+ * @brief A shape for body. You do not create PhysicsWorld objects directly, instead, you can view PhysicsBody to see how to create it.
+ */
 class PhysicsShape : public Object
 {
 public:
@@ -60,7 +63,7 @@ protected:
     bool init(PhysicsBody* body, Type type);
     
     /**
-     * PhysicsShape is PhysicsBody's friend class, but all the subclasses isn't. so this method is use for subclasses to catch the bodyInfo from PhysicsBody.
+     * @brief PhysicsShape is PhysicsBody's friend class, but all the subclasses isn't. so this method is use for subclasses to catch the bodyInfo from PhysicsBody.
      */
     PhysicsBodyInfo* bodyInfo() const;
     
@@ -68,7 +71,7 @@ protected:
     
 protected:
     PhysicsShape();
-    virtual ~PhysicsShape();
+    virtual ~PhysicsShape() = 0;
     
 protected:
     PhysicsBody* _body;
@@ -79,6 +82,7 @@ protected:
     friend class PhysicsBody;
 };
 
+/** A circle shape */
 class PhysicsShapeCircle : public PhysicsShape
 {
 protected:
@@ -92,6 +96,7 @@ protected:
     friend class PhysicsBody;
 };
 
+/** A box shape */
 class PhysicsShapeBox : public PhysicsShape
 {
 protected:
@@ -105,6 +110,7 @@ protected:
     friend class PhysicsBody;
 };
 
+/** A polygon shape */
 class PhysicsShapePolygon : public PhysicsShape
 {
 protected:
@@ -118,6 +124,7 @@ protected:
     friend class PhysicsBody;
 };
 
+/** A segment shape */
 class PhysicsShapeEdgeSegment : public PhysicsShape
 {
 protected:
@@ -131,6 +138,7 @@ protected:
     friend class PhysicsBody;
 };
 
+/** An edge box shape */
 class PhysicsShapeEdgeBox : public PhysicsShape
 {
 public:
@@ -146,6 +154,7 @@ protected:
     friend class PhysicsBody;
 };
 
+/** An edge polygon shape */
 class PhysicsShapeEdgePolygon : public PhysicsShape
 {
 public:
@@ -161,6 +170,7 @@ protected:
     friend class PhysicsBody;
 };
 
+/** a chain shape */
 class PhysicsShapeEdgeChain : public PhysicsShape
 {
 public:

cocos2dx/physics/CCPhysicsWorld.h

@@ -47,11 +47,17 @@ class Sprite;
 class Scene;
 class DrawNode;
 
+/**
+ * @brief An PhysicsWorld object simulates collisions and other physical properties. You do not create PhysicsWorld objects directly; instead, you can get it from an Scene object.
+ */
 class PhysicsWorld
 {
 public:
+    /** Adds a joint to the physics world.*/
     void addJoint(PhysicsJoint* joint);
+    /** Removes a joint from the physics world.*/
     void removeJoint(PhysicsJoint* joint);
+    /** Remove all joints from the physics world.*/
     void removeAllJoints();
     
     Array* getBodysAlongRay(Point start, Point end) const;
@@ -59,13 +65,19 @@ public:
     Array* getBodysInRect(Rect rect) const;
     Array* getAllBody() const;
     
+    /** Register a listener to receive contact callbacks*/
     inline void registerContactListener(PhysicsContactListener* delegate) { _listener = delegate; }
+    /** Unregister a listener. */
     inline void unregisterContactListener() { _listener = nullptr; }
     
+    /** get the gravity value */
     inline Point getGravity() { return _gravity; }
+    /** set the gravity value */
     void setGravity(Point gravity);
     
-    inline bool getDebugDraw() { return _debugDraw; }
+    /** test the debug draw is enabled */
+    inline bool isDebugDraw() { return _debugDraw; }
+    /** set the debug draw */
     inline void setDebugDraw(bool debugDraw) { _debugDraw = debugDraw; }
     
 protected:

samples/Cpp/TestCpp/Classes/PhysicsTest/PhysicsTest.cpp

@@ -52,7 +52,7 @@ void PhysicsTestLayer::toggleDebugCallback(Object* sender)
 #ifdef CC_USE_PHYSICS
     if (_scene != nullptr)
     {
-        _scene->getPhysicsWorld()->setDebugDraw(!_scene->getPhysicsWorld()->getDebugDraw());
+        _scene->getPhysicsWorld()->setDebugDraw(!_scene->getPhysicsWorld()->isDebugDraw());
     }
 #endif
 }