add document for physics

cocos/physics/CCPhysicsBody.h

@@ -47,99 +47,250 @@ typedef Vec2 Vect;
 
 const PhysicsMaterial PHYSICSBODY_MATERIAL_DEFAULT(0.1f, 0.5f, 0.5f);
 
+/**
+ * @addtogroup physics
+ * @{
+ */
+
 /**
  * A body affect by physics.
- * it can attach one or more shapes.
+ *
- * if you create body with createXXX, it will automatically compute mass and moment with density your specified(which is PHYSICSBODY_MATERIAL_DEFAULT by default, and the density value is 0.1f), and it based on the formular: mass = density * area.
+ * It can attach one or more shapes.
- * if you create body with createEdgeXXX, the mass and moment will be PHYSICS_INFINITY by default. and it's a static body.
+ * If you create body with createXXX, it will automatically compute mass and moment with density your specified(which is PHYSICSBODY_MATERIAL_DEFAULT by default, and the density value is 0.1f), and it based on the formular: mass = density * area.
- * you can change mass and moment with setMass() and setMoment(). and you can change the body to be dynamic or static by use function setDynamic().
+ * If you create body with createEdgeXXX, the mass and moment will be PHYSICS_INFINITY by default. And it's a static body.
+ * You can change mass and moment with setMass() and setMoment(). And you can change the body to be dynamic or static by use function setDynamic().
  */
 class CC_DLL PhysicsBody : public Ref
 {
 public:
-    /** create a body with defult mass and moment. */
+    /** 
+     Create a body with default mass and moment.
+     
+     This default mass value is 1.0.
+     This default moment value is 200.
+     @return  An autoreleased PhysicsBody object pointer.
+     */
     static PhysicsBody* create();
-    /** create a body with mass and defult moment. */
+   
+    /** 
+     Create a body with mass and default moment.
+     
+     @param mass This body's mass.
+     @return  An autoreleased PhysicsBody object pointer.
+     */
     static PhysicsBody* create(float mass);
-    /** create a body with mass and moment. */
+    
+    /** 
+     Create a body with mass and moment.
+     
+     @param mass This body's mass.
+     @param moment This body's moment.
+     @return  An autoreleased PhysicsBody object pointer.
+     */
     static PhysicsBody* create(float mass, float moment);
-    /** Create a body contains a circle shape. */
+    
+    /** 
+     Create a body contains a circle.
+     
+     @param   radius A float number, it is the circle's radius.
+     @param   material A PhysicsMaterial object, the default value is PHYSICSSHAPE_MATERIAL_DEFAULT.
+     @param   offset A Vec2 object, it is the offset from the body’s center of gravity in body local coordinates.
+     @return  An autoreleased PhysicsBody object pointer.
+     */
     static PhysicsBody* createCircle(float radius, const PhysicsMaterial& material = PHYSICSBODY_MATERIAL_DEFAULT, const Vec2& offset = Vec2::ZERO);
-    /** Create a body contains a box shape. */
+    /** 
+     * Create a body contains a box shape.
+     *
+     * @param   size Size contains this box's width and height.
+     * @param   material A PhysicsMaterial object, the default value is PHYSICSSHAPE_MATERIAL_DEFAULT.
+     * @param   offset A Vec2 object, it is the offset from the body’s center of gravity in body local coordinates.
+     * @return  An autoreleased PhysicsBody object pointer.
+     */
     static PhysicsBody* createBox(const Size& size, const PhysicsMaterial& material = PHYSICSBODY_MATERIAL_DEFAULT, const Vec2& offset = Vec2::ZERO);
+    
     /**
      * @brief Create a body contains a polygon shape.
-     * points is an array of Vec2 structs defining a convex hull with a clockwise winding.
+     *
+     * @param   points Points is an array of Vec2 structs defining a convex hull with a clockwise winding.
+     * @param   count An interger number, contains the count of the points array.
+     * @param   material A PhysicsMaterial object, the default value is PHYSICSSHAPE_MATERIAL_DEFAULT.
+     * @param   offset A Vec2 object, it is the offset from the body’s center of gravity in body local coordinates.
+     * @return  An autoreleased PhysicsBody object pointer.
      */
     static PhysicsBody* createPolygon(const Vec2* points, int count, const PhysicsMaterial& material = PHYSICSBODY_MATERIAL_DEFAULT, const Vec2& offset = Vec2::ZERO);
     
-    /** Create a body contains a EdgeSegment shape. */
+    /** 
+     Create a body contains a EdgeSegment shape. 
+     
+     * @param   a It's the edge's begin position.
+     * @param   b It's the edge's end position.
+     * @param   material A PhysicsMaterial object, the default value is PHYSICSSHAPE_MATERIAL_DEFAULT.
+     * @param   border It's a edge's border width.
+     * @return  An autoreleased PhysicsBody object pointer.
+     */
     static PhysicsBody* createEdgeSegment(const Vec2& a, const Vec2& b, const PhysicsMaterial& material = PHYSICSBODY_MATERIAL_DEFAULT, float border = 1);
-    /** Create a body contains a EdgeBox shape. */
+    
+    /** 
+     Create a body contains a EdgeBox shape. 
+
+     * @param   size Size contains this box's width and height.
+     * @param   material A PhysicsMaterial object, the default value is PHYSICSSHAPE_MATERIAL_DEFAULT.
+     * @param   border It's a edge's border width.
+     * @param   offset A Vec2 object, it is the offset from the body’s center of gravity in body local coordinates.
+     * @return  An autoreleased PhysicsBody object pointer.
+     */
     static PhysicsBody* createEdgeBox(const Size& size, const PhysicsMaterial& material = PHYSICSBODY_MATERIAL_DEFAULT, float border = 1, const Vec2& offset = Vec2::ZERO);
-    /** Create a body contains a EdgePolygon shape. */
+    
+    /** 
+     Create a body contains a EdgePolygon shape. 
+     
+     * @param   points Points is an array of Vec2 structs defining a convex hull with a clockwise winding.
+     * @param   count An interger number, contains the count of the points array.
+     * @param   material A PhysicsMaterial object, the default value is PHYSICSSHAPE_MATERIAL_DEFAULT.
+     * @param   border It's a edge's border width.
+     * @return  An autoreleased PhysicsBody object pointer.
+     */
     static PhysicsBody* createEdgePolygon(const Vec2* points, int count, const PhysicsMaterial& material = PHYSICSBODY_MATERIAL_DEFAULT, float border = 1);
-    /** Create a body contains a EdgeChain shape. */
+    
+    /** 
+     Create a body contains a EdgeChain shape.
+     
+     * @param   points A Vec2 object pointer, it contains an array of points.
+     * @param   count An interger number, contains the count of the points array.
+     * @param   material A PhysicsMaterial object, the default value is PHYSICSSHAPE_MATERIAL_DEFAULT.
+     * @param   border It's a edge's border width.
+     * @return  An autoreleased PhysicsBody object pointer.     
+     */
     static PhysicsBody* createEdgeChain(const Vec2* points, int count, const PhysicsMaterial& material = PHYSICSBODY_MATERIAL_DEFAULT, float border = 1);
     
-    /*
+    /**
-     * @brief add a shape to body
+     * @brief Add a shape to body.
-     * @param shape the shape to be added
+     * @param shape The shape to be added.
-     * @param addMassAndMoment if this is true, the shape's mass and moment will be added to body. the default is true
+     * @param addMassAndMoment If this is true, the shape's mass and moment will be added to body. The default is true.
+     * @return This shape's pointer if added success or nullptr if failed.
      */
     virtual PhysicsShape* addShape(PhysicsShape* shape, bool addMassAndMoment = true);
-    /*
+
-     * @brief remove a shape from body
+    /**
-     * @param shape the shape to be removed
+     * @brief Remove a shape from body.
-     * @param reduceMassAndMoment if this is true, the body mass and moment will be reduced by shape. the default is true
+     * @param shape Shape the shape to be removed.
+     * @param reduceMassAndMoment If this is true, the body mass and moment will be reduced by shape. The default is true.
      */
     void removeShape(PhysicsShape* shape, bool reduceMassAndMoment = true);
-    /*
+
-     * @brief remove a shape from body
+    /**
-     * @param tag the tag of the shape to be removed
+     * @brief Remove a shape from body.
-     * @param reduceMassAndMoment if this is true, the body mass and moment will be reduced by shape. the default is true
+     * @param tag The tag of the shape to be removed.
+     * @param reduceMassAndMoment If this is true, the body mass and moment will be reduced by shape. The default is true.
      */
     void removeShape(int tag, bool reduceMassAndMoment = true);
-    /* remove all shapes */
+    
+    /** 
+     Remove all shapes.
+     
+     * @param reduceMassAndMoment If this is true, the body mass and moment will be reduced by shape. The default is true.
+     */
     void removeAllShapes(bool reduceMassAndMoment = true);
-    /* get the body shapes. */
+
+    /**
+     Get the body shapes.
+
+     * @return A Vector<PhysicsShape*> object contains PhysicsShape pointer.
+     */
     inline const Vector<PhysicsShape*>& getShapes() const { return _shapes; }
-    /* get the first shape of the body shapes. */
+    
+    /** 
+     Get the first shape of the body shapes.
+     
+     @return The first shape in this body.
+     */
     inline PhysicsShape* getFirstShape() const { return _shapes.size() >= 1 ? _shapes.at(0) : nullptr; }
-    /* get the shape of the body. */
+
+    /** 
+     get the shape of the body. 
+     
+     @param   tag   An interger number that identifies a PhysicsShape object.
+     @return A PhysicsShape object pointer or nullptr if no shapes were found.
+     */
     PhysicsShape* getShape(int tag) const;
     
-    /** Applies a immediate force to body. */
+    /** 
+     Applies a continuous force to body.
+     
+     @param force The force is applies to this body.
+     */
     virtual void applyForce(const Vect& force);
-    /** Applies a immediate force to body. */
+    
+    /** 
+     Applies a continuous force to body.
+     
+     @param force The force is applies to this body.
+     @param offset A Vec2 object, it is the offset from the body’s center of gravity in world coordinates.
+     */
     virtual void applyForce(const Vect& force, const Vec2& offset);
-    /** reset all the force applied to body. */
+
+    /** 
+     reset all the force applied to body. 
+     */
     virtual void resetForces();
-    /** Applies a continuous force to body. */
+
+    /**
+     Applies a immediate force to body.
+     
+     @param impulse The impulse is applies to this body.
+     */
     virtual void applyImpulse(const Vect& impulse);
-    /** Applies a continuous force to body. */
+
+    /**
+     Applies a immediate force to body.
+     
+     @param impulse The impulse is applies to this body.
+     @param offset A Vec2 object, it is the offset from the body’s center of gravity in world coordinates.
+     */
     virtual void applyImpulse(const Vect& impulse, const Vec2& offset);
-    /** Applies a torque force to body. */
+    
+    /** 
+     Applies a torque force to body. 
+     
+     @param torque The torque is applies to this body.
+     */
     virtual void applyTorque(float torque);
     
-    /** set the velocity of a body */
+    /** 
+     Set the velocity of a body.
+
+     @param velocity The velocity is set to this body.
+     */
     virtual void setVelocity(const Vect& velocity);
-    /** get the velocity of a body */
+    
+    /** Get the velocity of a body. */
     virtual Vec2 getVelocity();
-    /** set the angular velocity of a body */
+    
+    /** 
+     Set the angular velocity of a body.
+     
+     @param velocity The angular velocity is set to this body.
+     */
     virtual void setAngularVelocity(float velocity);
-    /** get the angular velocity of a body at a local point */
+    
+    /** Get the angular velocity of a body at a local point.*/
     virtual Vec2 getVelocityAtLocalPoint(const Vec2& point);
+    
     /** get the angular velocity of a body at a world point */
     virtual Vec2 getVelocityAtWorldPoint(const Vec2& point);
+    
     /** get the angular velocity of a body */
     virtual float getAngularVelocity();
+    
     /** set the max of velocity */
     virtual void setVelocityLimit(float limit);
+    
     /** get the max of velocity */
     virtual float getVelocityLimit();
+    
     /** set the max of angular velocity */
     virtual void setAngularVelocityLimit(float limit);
+    
     /** get the max of angular velocity */
     virtual float getAngularVelocityLimit();
     
@@ -156,73 +307,108 @@ public:
     
     /**
      * A mask that defines which categories this physics body belongs to.
+     * 
      * Every physics body in a scene can be assigned to up to 32 different categories, each corresponding to a bit in the bit mask. You define the mask values used in your game. In conjunction with the collisionBitMask and contactTestBitMask properties, you define which physics bodies interact with each other and when your game is notified of these interactions.
-     * The default value is 0xFFFFFFFF (all bits set).
+     * @param bitmask An interger number, the default value is 0xFFFFFFFF (all bits set).
      */
     void setCategoryBitmask(int bitmask);
+    
     /** 
      * A mask that defines which categories of bodies cause intersection notifications with this physics body.
+     *
      * When two bodies share the same space, each body’s category mask is tested against the other body’s contact mask by performing a logical AND operation. If either comparison results in a non-zero value, an PhysicsContact object is created and passed to the physics world’s delegate. For best performance, only set bits in the contacts mask for interactions you are interested in.
-     * The default value is 0x00000000 (all bits cleared).
+     * @param bitmask An interger number, the default value is 0x00000000 (all bits cleared).
      */
     void setContactTestBitmask(int bitmask);
+    
     /**
      * A mask that defines which categories of physics bodies can collide with this physics body.
+     *
      * When two physics bodies contact each other, a collision may occur. This body’s collision mask is compared to the other body’s category mask by performing a logical AND operation. If the result is a non-zero value, then this body is affected by the collision. Each body independently chooses whether it wants to be affected by the other body. For example, you might use this to avoid collision calculations that would make negligible changes to a body’s velocity.
-     * The default value is 0xFFFFFFFF (all bits set).
+     * @param bitmask An interger number, the default value is 0xFFFFFFFF (all bits set).
      */
     void setCollisionBitmask(int bitmask);
-    /** Return bitmask of first shape, if there is no shape in body, return default value.(0xFFFFFFFF) */
+    
+    /** 
+     Return bitmask of first shape.
+     
+     * @return If there is no shape in body, return default value.(0xFFFFFFFF)
+     */
     int getCategoryBitmask() const;
-    /** Return bitmask of first shape, if there is no shape in body, return default value.(0x00000000) */
+    
+    /** 
+     Return bitmask of first shape.
+     
+     * @return If there is no shape in body, return default value.(0x00000000)
+     */
     int getContactTestBitmask() const;
-    /** Return bitmask of first shape, if there is no shape in body, return default value.(0xFFFFFFFF) */
+    
+    /** 
+     Return bitmask of first shape.
+     
+     @return If there is no shape in body, return default value.(0xFFFFFFFF)
+     */
     int getCollisionBitmask() const;
     
     /** 
-     * set the group of body
+     * Set the group of body.
-     * Collision groups let you specify an integral group index. You can have all fixtures with the same group index always collide (positive index) or never collide (negative index)
+     *
-     * it have high priority than bit masks
+     * Collision groups let you specify an integral group index. You can have all fixtures with the same group index always collide (positive index) or never collide (negative index).
+     * It have high priority than bit masks.
      */
     void setGroup(int group);
-    /** Return group of first shape, if there is no shape in body, return default value.(0) */
+    
+    /** 
+     Return group of first shape.
+     
+     @return If there is no shape in body, return default value.(0) 
+     */
     int getGroup() const;
     
     /** get the body position. */
     const Vec2& getPosition();
+    
     /** get the body rotation. */
     float getRotation();
     
     /** set body position offset, it's the position witch relative to node */
     void setPositionOffset(const Vec2& position);
+    
     /** get body position offset. */
     const Vec2& getPositionOffset() const { return _positionOffset; }
+    
     /** set body rotation offset, it's the rotation witch relative to node */
     void setRotationOffset(float rotation);
+    
     /** set the body rotation offset */
     float getRotationOffset() const { return _rotationOffset; }
     
     /**
-     * @brief test the body is dynamic or not.
+     * @brief Test the body is dynamic or not.
-     * a dynamic body will effect with gravity.
+     *
+     * A dynamic body will effect with gravity.
      */
     inline bool isDynamic() const { return _dynamic; }
     /**
-     * @brief set dynamic to body.
+     * @brief Set dynamic to body.
-     * a dynamic body will effect with gravity.
+     * 
+     * A dynamic body will effect with gravity.
      */
     void setDynamic(bool dynamic);
     
     /**
-     * @brief set the body mass.
+     * @brief Set the body mass.
-     * @note if you need add/subtract mass to body, don't use setMass(getMass() +/- mass), because the mass of body may be equal to PHYSICS_INFINITY, it will cause some unexpected result, please use addMass() instead.
+     *
+     * @attension If you need add/subtract mass to body, don't use setMass(getMass() +/- mass), because the mass of body may be equal to PHYSICS_INFINITY, it will cause some unexpected result, please use addMass() instead.
      */
     void setMass(float mass);
-    /** get the body mass. */
+    
+    /** Get the body mass. */
     inline float getMass() const { return _mass; }
     /**
-     * @brief add mass to body.
+     * @brief Add mass to body.
-     * if _mass(mass of the body) == PHYSICS_INFINITY, it remains.
+     *
+     * @param mass If _mass(mass of the body) == PHYSICS_INFINITY, it remains.
      * if mass == PHYSICS_INFINITY, _mass will be PHYSICS_INFINITY.
      * if mass == -PHYSICS_INFINITY, _mass will not change.
      * if mass + _mass <= 0, _mass will equal to MASS_DEFAULT(1.0)
@@ -231,73 +417,92 @@ public:
     void addMass(float mass);
     
     /**
-     * @brief set the body moment of inertia.
+     * @brief Set the body moment of inertia.
-     * @note if you need add/subtract moment to body, don't use setMoment(getMoment() +/- moment), because the moment of body may be equal to PHYSICS_INFINITY, it will cause some unexpected result, please use addMoment() instead.
+     *
+     * @note If you need add/subtract moment to body, don't use setMoment(getMoment() +/- moment), because the moment of body may be equal to PHYSICS_INFINITY, it will cause some unexpected result, please use addMoment() instead.
      */
     void setMoment(float moment);
-    /** get the body moment of inertia. */
+    
+    /** Get the body moment of inertia. */
     inline float getMoment() const { return _moment; }
+    
     /**
-     * @brief add moment of inertia to body.
+     * @brief Add moment of inertia to body.
-     * if _moment(moment of the body) == PHYSICS_INFINITY, it remains.
+     * 
+     * @param moment If _moment(moment of the body) == PHYSICS_INFINITY, it remains.
      * if moment == PHYSICS_INFINITY, _moment will be PHYSICS_INFINITY.
      * if moment == -PHYSICS_INFINITY, _moment will not change.
      * if moment + _moment <= 0, _moment will equal to MASS_DEFAULT(1.0)
      * other wise, moment = moment + _moment;
      */
     void addMoment(float moment);
+    
     /** get linear damping. */
     inline float getLinearDamping() const { return _linearDamping; }
+    
     /** 
-     * set linear damping.
+     * Set linear damping.
-     * it is used to simulate fluid or air friction forces on the body. 
+     *
-     * the value is 0.0f to 1.0f. 
+     * it is used to simulate fluid or air friction forces on the body.
+     * @param damping The value is 0.0f to 1.0f.
      */
     inline void setLinearDamping(float damping) { _linearDamping = damping; updateDamping(); }
-    /** get angular damping. */
+    
+    /** Get angular damping. */
     inline float getAngularDamping() const { return _angularDamping; }
     /**
-     * set angular damping.
+     * Set angular damping.
-     * it is used to simulate fluid or air friction forces on the body.
+     *
-     * the value is 0.0f to 1.0f.
+     * It is used to simulate fluid or air friction forces on the body.
+     * @param damping The value is 0.0f to 1.0f.
      */
     inline void setAngularDamping(float damping) { _angularDamping = damping; updateDamping(); }
     
-    /** whether the body is at rest */
+    /** Whether the body is at rest. */
     bool isResting() const;
+    
     /** set body to rest */
     void setResting(bool rest) const;
-    /** 
+
-     * whether the body is enabled
+    /**
-     * if the body it isn't enabled, it will not has simulation by world
+     * Whether the body is enabled.
+     *
+     * If the body it isn't enabled, it will not has simulation by world.
      */
     inline bool isEnabled() const { return _enabled; }
+    
     /**
-     * set the enable value.
+     * Set the enable value.
-     * if the body it isn't enabled, it will not has simulation by world
+     *
+     * If the body it isn't enabled, it will not has simulation by world.
      */
     void setEnable(bool enable);
     
-    /** whether the body can rotation */
+    /** Whether the body can rotation. */
     inline bool isRotationEnabled() const { return _rotationEnabled; }
-    /** set the body is allow rotation or not */
+    
+    /** Set the body is allow rotation or not */
     void setRotationEnable(bool enable);
     
-    /** whether this physics body is affected by the physics world’s gravitational force. */
+    /** Whether this physics body is affected by the physics world’s gravitational force. */
     inline bool isGravityEnabled() const { return _gravityEnabled; }
-    /** set the body is affected by the physics world's gravitational force or not. */
+    
+    /** Set the body is affected by the physics world's gravitational force or not. */
     void setGravityEnable(bool enable);
     
-    /** get the body's tag */
+    /** Get the body's tag. */
     inline int getTag() const { return _tag; }
-    /** set the body's tag */
+    
+    /** set the body's tag. */
     inline void setTag(int tag) { _tag = tag; }
     
-    /** convert the world point to local */
+    /** Convert the world point to local. */
     Vec2 world2Local(const Vec2& point);
-    /** convert the local point to world */
+    
+    /** Convert the local point to world. */
     Vec2 local2World(const Vec2& point);
 
+    /** Get the rigid body of chipmunk. */
     cpBody* getCPBody() { return _cpBody; }
     
 protected:
@@ -354,6 +559,8 @@ protected:
     friend class ProtectedNode;
 };
 
+/** @} */
+
 NS_CC_END
 
 #endif // CC_USE_PHYSICS

cocos/physics/CCPhysicsContact.h

@@ -55,7 +55,14 @@ typedef struct CC_DLL PhysicsContactData
 }PhysicsContactData;
 
 /**
- * @brief Contact infomation. it will created automatically when two shape contact with each other. and it will destoried automatically when two shape separated.
+ * @addtogroup physics
+ * @{
+ */
+
+/**
+ * @brief Contact infomation. 
+ 
+ * It will created automatically when two shape contact with each other. And it will destoried automatically when two shape separated.
  */
 class CC_DLL PhysicsContact : public EventCustom
 {
@@ -70,21 +77,29 @@ public:
         SEPERATE
     };
     
-    /** get contact shape A. */
+    /** Get contact shape A. */
     inline PhysicsShape* getShapeA() const { return _shapeA; }
-    /** get contact shape B. */
+    
+    /** Get contact shape B. */
     inline PhysicsShape* getShapeB() const { return _shapeB; }
-    /** get contact data */
+    
+    /** Get contact data. */
     inline const PhysicsContactData* getContactData() const { return _contactData; }
-    /** get previous contact data */
+    
+    /** Get previous contact data */
     inline const PhysicsContactData* getPreContactData() const { return _preContactData; }
-    /** get data. */
+    
+    /** Get data. */
     inline void* getData() const { 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 seperate.
+     * @brief Set data to contact. 
+     
+     * You must manage the memory yourself, Generally you can set data at contact begin, and distory it at contact seperate.
      */
     inline void setData(void* data) { _data = data; }
-    /** get the event code */
+
+    /** Get the event code */
     EventCode getEventCode() const { return _eventCode; };
 
 private:
@@ -123,25 +138,25 @@ private:
     friend class PhysicsWorld;
 };
 
-/*
+/**
- * @brief presolve value generated when onContactPreSolve called.
+ * @brief Presolve value generated when onContactPreSolve called.
  */
 class CC_DLL PhysicsContactPreSolve
 {
 public:
-    /** get restitution between two bodies*/
+    /** Get restitution between two bodies.*/
     float getRestitution() const;
-    /** get friction between two bodies*/
+    /** Get friction between two bodies.*/
     float getFriction() const;
-    /** get surface velocity between two bodies*/
+    /** Get surface velocity between two bodies.*/
     Vec2 getSurfaceVelocity() const;
-    /** set the restitution*/
+    /** Set the restitution.*/
     void setRestitution(float restitution);
-    /** set the friction*/
+    /** Set the friction.*/
     void setFriction(float friction);
-    /** set the surface velocity*/
+    /** Set the surface velocity.*/
     void setSurfaceVelocity(const Vect& velocity);
-    /** ignore the rest of the contact presolve and postsolve callbacks */
+    /** Ignore the rest of the contact presolve and postsolve callbacks. */
     void ignore();
     
 private:
@@ -154,17 +169,17 @@ private:
     friend class EventListenerPhysicsContact;
 };
 
-/*
+/**
- * @brief postsolve value generated when onContactPostSolve called.
+ * @brief Postsolve value generated when onContactPostSolve called.
  */
 class CC_DLL PhysicsContactPostSolve
 {
 public:
-    /** get restitution between two bodies*/
+    /** Get restitution between two bodies.*/
     float getRestitution() const;
-    /** get friction between two bodies*/
+    /** Get friction between two bodies.*/
     float getFriction() const;
-    /** get surface velocity between two bodies*/
+    /** Get surface velocity between two bodies.*/
     Vec2 getSurfaceVelocity() const;
     
 private:
@@ -177,37 +192,44 @@ private:
     friend class EventListenerPhysicsContact;
 };
 
-/* contact listener. it will recive all the contact callbacks. */
+/** Contact listener. It will recive all the contact callbacks. */
 class CC_DLL EventListenerPhysicsContact : public EventListenerCustom
 {
 public:
-    /** create the listener */
+    /** Create the listener. */
     static EventListenerPhysicsContact* create();
+    
+    /** Check the listener is available.
+
+     *@return Ture if there's one available callback function at least, false if there's no one.
+     */
     virtual bool checkAvailable() override;
+    
+    /** Clone an object from this listener.*/
     virtual EventListenerPhysicsContact* clone() override;
     
 protected:
     /**
-     * it will be call when two body have contact.
+     * It will be call when two body have contact.
-     * if return false, it will not invoke callbacks
+     * if return false, it will not invoke callbacks.
      */
     virtual bool hitTest(PhysicsShape* shapeA, PhysicsShape* shapeB);
     
 public:
-    /*
+    /**
-     * @brief it will called at two shapes start to contact, and only call it once.
+     * @brief It will called at two shapes start to contact, and only call it once.
      */
     std::function<bool(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, restitution, or surface velocity values.
      */
     std::function<bool(PhysicsContact& contact, 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(PhysicsContact& contact, const PhysicsContactPostSolve& solve)> onContactPostSolve;
-    /*
+    /**
-     * @brief it will called at two shapes separated, and only call it once.
+     * @brief It will called at two shapes separated, and only call it once.
      * onContactBegin and onContactSeperate will called in pairs.
      */
     std::function<void(PhysicsContact& contact)> onContactSeperate;
@@ -223,13 +245,15 @@ protected:
     friend class PhysicsWorld;
 };
 
-/** this event listener only be called when bodyA and bodyB have contacts */
+/** This event listener only be called when bodyA and bodyB have contacts. */
 class CC_DLL EventListenerPhysicsContactWithBodies : public EventListenerPhysicsContact
 {
 public:
+    /** Create the listener. */
     static EventListenerPhysicsContactWithBodies* create(PhysicsBody* bodyA, PhysicsBody* bodyB);
     
     virtual bool hitTest(PhysicsShape* shapeA, PhysicsShape* shapeB) override;
+
     virtual EventListenerPhysicsContactWithBodies* clone() override;
     
 protected:
@@ -241,10 +265,11 @@ protected:
     virtual ~EventListenerPhysicsContactWithBodies();
 };
 
-/** this event listener only be called when shapeA and shapeB have contacts */
+/** This event listener only be called when shapeA and shapeB have contacts. */
 class CC_DLL EventListenerPhysicsContactWithShapes : public EventListenerPhysicsContact
 {
 public:
+    /** Create the listener. */
     static EventListenerPhysicsContactWithShapes* create(PhysicsShape* shapeA, PhysicsShape* shapeB);
     
     virtual bool hitTest(PhysicsShape* shapeA, PhysicsShape* shapeB) override;
@@ -259,10 +284,11 @@ protected:
     virtual ~EventListenerPhysicsContactWithShapes();
 };
 
-/** this event listener only be called when shapeA or shapeB is in the group your specified */
+/** This event listener only be called when shapeA or shapeB is in the group your specified */
 class CC_DLL EventListenerPhysicsContactWithGroup : public EventListenerPhysicsContact
 {
 public:
+    /** Create the listener. */
     static EventListenerPhysicsContactWithGroup* create(int group);
     
     virtual bool hitTest(PhysicsShape* shapeA, PhysicsShape* shapeB) override;
@@ -276,6 +302,8 @@ protected:
     virtual ~EventListenerPhysicsContactWithGroup();
 };
 
+/** @} */
+
 NS_CC_END
 
 #endif // CC_USE_PHYSICS

cocos/physics/CCPhysicsHelper.h

@@ -34,18 +34,51 @@
 
 NS_CC_BEGIN
 
+/**
+ * @addtogroup physics
+ * @{
+ */
+
+/**
+ * A physics helper class.
+ *
+ * Support for conversion between the chipmunk types and cocos types, eg: cpVect to Vec2, cpVect to Size, cpFloat to float.
+ */
 class PhysicsHelper
 {
 public:
+    /** Make cpVect type convert to Vec2 type. */
     static Vec2 cpv2point(const cpVect& vec) { return Vec2(vec.x, vec.y); }
+
+    /** Make Vec2 type convert to cpVect type. */
     static cpVect point2cpv(const Vec2& point) { return cpv(point.x, point.y); }
+    
+    /** Make cpVect type convert to Size type. */
     static Size cpv2size(const cpVect& vec) { return Size(vec.x, vec.y); }
+    
+    /** Make Size type convert to cpVect type. */
     static cpVect size2cpv(const Size& size) { return cpv(size.width, size.height); }
+    
+    /** Make cpFloat type convert to float type. */
     static float cpfloat2float(cpFloat f) { return f; }
+    
+    /** Make float type convert to cpFloat type. */
     static cpFloat float2cpfloat(float f) { return f; }
+    
+    /** Make Rect type convert to cpBB type. */
     static cpBB rect2cpbb(const Rect& rect) { return cpBBNew(rect.origin.x, rect.origin.y, rect.origin.x + rect.size.width, rect.origin.y + rect.size.height); }
+    
+    /** Make cpBB type convert to Rect type. */
     static Rect cpbb2rect(const cpBB& bb) { return Rect(bb.l, bb.b, bb.r -  bb.l, bb.t - bb.b); }
     
+    /** 
+     Make cpVect array convert to Vec2 array.
+     
+     @param cpvs The be converted object, it's a cpVect array.
+     @param out The coverted object, it's a Vec2 array.
+     @param count It's cpvs array length.
+     @return The out object's pointer.
+     */
     static Vec2* cpvs2points(const cpVect* cpvs, Vec2* out, int count)
     {
         for (int i = 0; i < count; ++i)
@@ -56,6 +89,14 @@ public:
         return out;
     }
     
+    /**
+     Make Vec2 array convert to cpVect array.
+     
+     @param points The be converted object, it's a Vec2 array.
+     @param out The coverted object, it's a cpVect array.
+     @param count It's points array length.
+     @return The out object's pointer.
+     */
     static cpVect* points2cpvs(const Vec2* points, cpVect* out, int count)
     {
         for (int i = 0; i < count; ++i)
@@ -67,6 +108,8 @@ public:
     }
 };
 
+/** @} */
+
 NS_CC_END
 
 #endif // CC_USE_PHYSICS

cocos/physics/CCPhysicsJoint.h

@@ -39,7 +39,12 @@ class Node;
 class PhysicsBody;
 class PhysicsWorld;
 
-/*
+/**
+ * @addtogroup physics
+ * @{
+ */
+
+/**
  * @brief An PhysicsJoint object connects two physics bodies together.
  */
 class CC_DLL PhysicsJoint
@@ -49,29 +54,56 @@ protected:
     virtual ~PhysicsJoint() = 0;
 
 public:
+    /**Get physics body a connected to this joint.*/
     inline PhysicsBody* getBodyA() const { return _bodyA; }
+    
+    /**Get physics body b connected to this joint.*/
     inline PhysicsBody* getBodyB() const { return _bodyB; }
+
+    /**Get the physics world.*/
     inline PhysicsWorld* getWorld() const { return _world; }
+    
+    /**
+     * Get this joint's tag.
+     *
+     * @return An interger number.
+     */
     inline int getTag() const { return _tag; }
+    
+    /**
+     * Set this joint's tag.
+     *
+     * @param tag An interger number that identifies a PhysicsJoint.
+     */
     inline void setTag(int tag) { _tag = tag; }
+    
+    /** Determines if the joint is enable. */
     inline bool isEnabled() const { return _enable; }
-    /** Enable/Disable the joint */
+
+    /** Enable/Disable the joint. */
     void setEnable(bool enable);
+    
+    /** Determines if the collsion is enable. */
     inline bool isCollisionEnabled() const { return _collisionEnable; }
-    /** Enable/disable the collision between two bodies */
+    
+    /** Enable/disable the collision between two bodies. */
     void setCollisionEnable(bool enable);
-    /** Remove the joint from the world */
+    
+    /** Remove the joint from the world. */
     void removeFormWorld();
 
-    /** Set the max force between two bodies */
+    /** Set the max force between two bodies. */
     void setMaxForce(float force);
-    /** Get the max force setting */
+    
+    /** Get the max force setting. */
     float getMaxForce() const { return _maxForce; }
 
 protected:
     bool init(PhysicsBody* a, PhysicsBody* b);
 
     bool initJoint();
+    
+    /** Create constraints for this type joint */
     virtual bool createConstraints() { return false; }
 
     std::vector<cpConstraint*> _cpConstraints;
@@ -92,12 +124,19 @@ protected:
     friend class PhysicsDebugDraw;
 };
 
-/*
+/**
 * @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 CC_DLL PhysicsJointFixed : public PhysicsJoint
 {
 public:
+    /** Create a fixed joint.
+     
+     @param a A is the body to connect.
+     @param b B is the body to connect.
+     @param anchr It's the pivot position.
+     @return A object pointer.
+     */
     static PhysicsJointFixed* construct(PhysicsBody* a, PhysicsBody* b, const Vec2& anchr);
 
     virtual bool createConstraints() override;
@@ -109,22 +148,54 @@ protected:
     Vec2 _anchr;
 };
 
-/*
+/**
 * @brief A limit joint imposes a maximum distance between the two bodies, as if they were connected by a rope.
 */
 class CC_DLL PhysicsJointLimit : public PhysicsJoint
 {
 public:
+    /** Create a limit joint.
+     
+     @param a A is the body to connect.
+     @param b B is the body to connect.
+     @param anchr1 Anchr1 is the anchor point on body a.
+     @param anchr2 Anchr2 is the anchor point on body b.
+     @return A object pointer.
+     */
     static PhysicsJointLimit* construct(PhysicsBody* a, PhysicsBody* b, const Vec2& anchr1, const Vec2& anchr2);
+    
+    /** Create a limit joint.
+     
+     @param a A is the body to connect.
+     @param b B is the body to connect.
+     @param anchr1 Anchr1 is the anchor point on body a.
+     @param anchr2 Anchr2 is the anchor point on body b.
+     @param min Define the allowed min distance of the anchor points.
+     @param max Define the allowed max distance of the anchor points.
+     @return A object pointer.
+     */
     static PhysicsJointLimit* construct(PhysicsBody* a, PhysicsBody* b, const Vec2& anchr1, const Vec2& anchr2, float min, float max);
 
+    /** Get the anchor point on body a.*/
     Vec2 getAnchr1() const;
+    
+    /** Set the anchor point on body a.*/
     void setAnchr1(const Vec2& anchr1);
+    
+    /** Get the anchor point on body b.*/
     Vec2 getAnchr2() const;
+    
+    /** Set the anchor point on body b.*/
     void setAnchr2(const Vec2& anchr2);
+    
+    /** Get the allowed min distance of the anchor points.*/
     float getMin() const;
+    /** Set the min distance of the anchor points.*/
     void setMin(float min);
+  
+    /** Get the allowed max distance of the anchor points.*/
     float getMax() const;
+    /** Set the max distance of the anchor points.*/
     void setMax(float max);
 
     virtual bool createConstraints() override;
@@ -139,13 +210,29 @@ protected:
     float _max;
 };
 
-/*
+/**
 * @brief A pin joint allows the two bodies to independently rotate around the anchor point as if pinned together.
 */
 class CC_DLL PhysicsJointPin : public PhysicsJoint
 {
 public:
+    /** Create a pin joint.
+     
+     @param a A is the body to connect.
+     @param b B is the body to connect.
+     @param pivot It's the pivot position.
+     @return A object pointer.
+     */
     static PhysicsJointPin* construct(PhysicsBody* a, PhysicsBody* b, const Vec2& pivot);
+
+    /** Create a pin joint.
+     
+     @param a A is the body to connect.
+     @param b B is the body to connect.
+     @param anchr1 Anchr1 is the anchor point on body a.
+     @param anchr2 Anchr2 is the anchor point on body b.
+     @return A object pointer.
+     */
     static PhysicsJointPin* construct(PhysicsBody* a, PhysicsBody* b, const Vec2& anchr1, const Vec2& anchr2);
 
     virtual bool createConstraints() override;
@@ -163,9 +250,19 @@ protected:
 class CC_DLL PhysicsJointDistance : public PhysicsJoint
 {
 public:
+    /** Create a fixed distance joint.
+     
+     @param a A is the body to connect.
+     @param b B is the body to connect.
+     @param anchr1 Anchr1 is the anchor point on body a.
+     @param anchr2 Anchr2 is the anchor point on body b.
+     @return A object pointer.
+     */
     static PhysicsJointDistance* construct(PhysicsBody* a, PhysicsBody* b, const Vec2& anchr1, const Vec2& anchr2);
 
+    /** Get the distance of the anchor points.*/
     float getDistance() const;
+    /** Set the distance of the anchor points.*/
     void setDistance(float distance);
     virtual bool createConstraints() override;
 
@@ -181,17 +278,48 @@ protected:
 class CC_DLL PhysicsJointSpring : public PhysicsJoint
 {
 public:
+    /** Create a fixed distance joint.
+     
+     @param a A is the body to connect.
+     @param b B is the body to connect.
+     @param anchr1 Anchr1 is the anchor point on body a.
+     @param anchr2 Anchr2 is the anchor point on body b.
+     @param stiffness It's the spring constant.
+     @param damping It's how soft to make the damping of the spring.
+     @return A object pointer.
+     */
     static PhysicsJointSpring* construct(PhysicsBody* a, PhysicsBody* b, const Vec2& anchr1, const Vec2& anchr2, float stiffness, float damping);
+
+    /** Get the anchor point on body a.*/
     Vec2 getAnchr1() const;
+
+    /** Set the anchor point on body a.*/
     void setAnchr1(const Vec2& anchr1);
+
+    /** Get the anchor point on body b.*/
     Vec2 getAnchr2() const;
+
+    /** Set the anchor point on body b.*/
     void setAnchr2(const Vec2& anchr2);
+    
+    /** Get the distance of the anchor points.*/
     float getRestLength() const;
+    
+    /** Set the distance of the anchor points.*/
     void setRestLength(float restLength);
+    
+    /** Get the spring constant.*/
     float getStiffness() const;
+    
+    /** Set the spring constant.*/
     void setStiffness(float stiffness);
+    
+    /** Get the spring soft constant.*/
     float getDamping() const;
+    
+    /** Set the spring soft constant.*/
     void setDamping(float damping);
+    
     virtual bool createConstraints() override;
 
 protected:
@@ -204,18 +332,39 @@ protected:
     float _damping;
 };
 
-/** Attach body a to a line, and attach body b to a dot */
+/** Attach body a to a line, and attach body b to a dot. */
 class CC_DLL PhysicsJointGroove : public PhysicsJoint
 {
 public:
+    /** Create a groove joint.
+     
+     @param a A is the body to connect.
+     @param b B is the body to connect.
+     @param grooveA The line begin position.
+     @param grooveB The line end position.
+     @param anchr2 Anchr2 is the anchor point on body b.
+     @return A object pointer.
+     */
     static PhysicsJointGroove* construct(PhysicsBody* a, PhysicsBody* b, const Vec2& grooveA, const Vec2& grooveB, const Vec2& anchr2);
 
+    /** Get the line begin position*/
     Vec2 getGrooveA() const;
+
+    /** Set the line begin position*/
     void setGrooveA(const Vec2& grooveA);
+    
+    /** Get the line end position*/
     Vec2 getGrooveB() const;
+    
+    /** Set the line end position*/
     void setGrooveB(const Vec2& grooveB);
+    
+    /** Get the anchor point on body b.*/
     Vec2 getAnchr2() const;
+    
+    /** Set the anchor point on body b.*/
     void setAnchr2(const Vec2& anchr2);
+    
     virtual bool createConstraints() override;
 
 protected:
@@ -227,18 +376,38 @@ protected:
     Vec2 _anchr2;
 };
 
-/** Likes a spring joint, but works with rotary */
+/** Likes a spring joint, but works with rotary. */
 class CC_DLL PhysicsJointRotarySpring : public PhysicsJoint
 {
 public:
+    /** Create a damped rotary spring joint.
+     
+     @param a A is the body to connect.
+     @param b B is the body to connect.
+     @param stiffness It's the spring constant.
+     @param damping It's how soft to make the damping of the spring.
+     @return A object pointer.
+     */
     static PhysicsJointRotarySpring* construct(PhysicsBody* a, PhysicsBody* b, float stiffness, float damping);
 
+    /** Get the relative angle in radians from the body a to b.*/
     float getRestAngle() const;
+
+    /** Set the relative angle in radians from the body a to b.*/
     void setRestAngle(float restAngle);
+
+    /** Get the spring constant.*/
     float getStiffness() const;
+    
+    /** Set the spring constant.*/
     void setStiffness(float stiffness);
+    
+    /** Get the spring soft constant.*/
     float getDamping() const;
+
+    /** Set the spring soft constant.*/
     void setDamping(float damping);
+    
     virtual bool createConstraints() override;
 
 protected:
@@ -249,17 +418,40 @@ protected:
     float _damping;
 };
 
-/** Likes a limit joint, but works with rotary */
+/** Likes a limit joint, but works with rotary. */
 class CC_DLL PhysicsJointRotaryLimit : public PhysicsJoint
 {
 public:
+    /** Create a limit rotary joint.
+     
+     @param a A is the body to connect.
+     @param b B is the body to connect.
+     @param min It's min rotation limit in radians.
+     @param max It's max rotation limit in radians.
+     @return A object pointer.
+     */
     static PhysicsJointRotaryLimit* construct(PhysicsBody* a, PhysicsBody* b, float min, float max);
+
+    /** Create a limit rotary joint.
+     
+     @param a A is the body to connect.
+     @param b B is the body to connect.
+     @return A object pointer.
+     */
     static PhysicsJointRotaryLimit* construct(PhysicsBody* a, PhysicsBody* b);
 
+    /** Get the min rotation limit.*/
     float getMin() const;
+    
+    /** Set the min rotation limit.*/
     void setMin(float min);
+    
+    /** Get the max rotation limit.*/
     float getMax() const;
+    
+    /** Set the max rotation limit.*/
     void setMax(float max);
+    
     virtual bool createConstraints() override;
 
 protected:
@@ -274,13 +466,32 @@ protected:
 class CC_DLL PhysicsJointRatchet : public PhysicsJoint
 {
 public:
+    /** Create a ratchet joint.
+     
+     @param a A is the body to connect.
+     @param b B is the body to connect.
+     @param phase Phase is the initial offset to use when deciding where the ratchet angles are.
+     @param ratchet Ratchet is the distance between “clicks”.
+     @return A object pointer.
+     */
     static PhysicsJointRatchet* construct(PhysicsBody* a, PhysicsBody* b, float phase, float ratchet);
 
+    /** Get the ratchet angle.*/
     float getAngle() const;
+    
+    /** Set the ratchet angle.*/
     void setAngle(float angle);
+    
+    /** Get the initial offset.*/
     float getPhase() const;
+    
+    /** Set the initial offset.*/
     void setPhase(float phase);
+    
+    /** Get the distance between “clicks”.*/
     float getRatchet() const;
+
+    /** Set the distance between “clicks”.*/
     void setRatchet(float ratchet);
     virtual bool createConstraints() override;
 
@@ -296,11 +507,26 @@ protected:
 class CC_DLL PhysicsJointGear : public PhysicsJoint
 {
 public:
+    /** Create a gear joint.
+     
+     @param a A is the body to connect.
+     @param b B is the body to connect.
+     @param phase Phase is the initial angular offset of the two bodies.
+     @param ratio Ratio is always measured in absolute terms.
+     @return A object pointer.
+     */
     static PhysicsJointGear* construct(PhysicsBody* a, PhysicsBody* b, float phase, float ratio);
 
+    /** Get the angular offset of the two bodies.*/
     float getPhase() const;
+    
+    /** Set the angular offset of the two bodies.*/
     void setPhase(float phase);
+    
+    /** Get the ratio.*/
     float getRatio() const;
+    
+    /** Set the ratio.*/
     void setRatio(float ratchet);
 
     virtual bool createConstraints() override;
@@ -313,13 +539,23 @@ protected:
     float _ratio;
 };
 
-/** Keeps the relative angular velocity of a pair of bodies constant */
+/** Keeps the relative angular velocity of a pair of bodies constant. */
 class CC_DLL PhysicsJointMotor : public PhysicsJoint
 {
 public:
+    /** Create a motor joint.
+     
+     @param a A is the body to connect.
+     @param b B is the body to connect.
+     @param rate Rate is the desired relative angular velocity.
+     @return A object pointer.
+     */
     static PhysicsJointMotor* construct(PhysicsBody* a, PhysicsBody* b, float rate);
 
+    /** Get the relative angular velocity.*/
     float getRate() const;
+    
+    /** Set the relative angular velocity.*/
     void setRate(float rate);
     virtual bool createConstraints() override;
 
@@ -330,6 +566,8 @@ protected:
     float _rate;
 };
 
+/** @} */
+
 NS_CC_END
 
 #endif // CC_USE_PHYSICS

cocos/physics/CCPhysicsShape.h

@@ -58,6 +58,11 @@ typedef struct CC_DLL PhysicsMaterial
 
 const PhysicsMaterial PHYSICSSHAPE_MATERIAL_DEFAULT;
 
+/**
+ *  @addtogroup physics
+ *  @{
+ */
+
 /**
  * @brief A shape for body. You do not create PhysicsWorld objects directly, instead, you can view PhysicsBody to see how to create it.
  */
@@ -77,74 +82,246 @@ public:
     };
     
 public:
-    /** Get the body that this shape attaches */
+    /** 
+     * Get the body that this shape attaches.
+     *
+     * @return A PhysicsBody object pointer.
+     */
     inline PhysicsBody* getBody() const { return _body; }
-    /** Return the type of this shape */
+    
+    /** 
+     * Return this shape's type.
+     *
+     * @return A Type object.
+     */
     inline Type getType() const { return _type; }
-    /** return the area of this shape */
+
+    /**
+     * Return this shape's area.
+     *
+     * @return A float number.
+     */
     inline float getArea() const { return _area; }
-    /** get moment */
+    
+    /**
+     * Get this shape's moment.
+     *
+     * @return A float number.
+     */
     inline float getMoment() const { return _moment; }
-    /** Set moment, it will change the body's moment this shape attaches */
+    
+    /**
+     * Set this shape's moment.
+     *
+     * It will change the body's moment this shape attaches.
+     *
+     * @param moment A float number.
+     */
     void setMoment(float moment);
+    
+    /**
+     * Set this shape's tag.
+     *
+     * @param tag An interger number that identifies a shape object.
+     */
     inline void setTag(int tag) { _tag = tag; }
+    
+    /**
+     * Get this shape's tag.
+     *
+     * @return An interger number.
+     */
     inline int getTag() const { return _tag; }
     
-    /** get mass */
+    /**
+     * Get the mass of this shape.
+     *
+     * @return A float number.
+     */
     inline float getMass() const { return _mass; }
-    /** Set mass, it will change the body's mass this shape attaches */
+    
+    /**
+     * Set this shape's mass.
+     *
+     * It will change the body's mass this shape attaches.
+     *
+     * @param mass A float number.
+     */
     void setMass(float mass);
+    
+    /**
+     * Get this shape's density.
+     *
+     * @return A float number.
+     */
     inline float getDensity() const { return _material.density; }
+    
+    /**
+     * Set this shape's density.
+     *
+     * It will change the body's mass this shape attaches.
+     *
+     * @param density A float number.
+     */
     void setDensity(float density);
+    
+    /**
+     * Get this shape's restitution.
+     *
+     * @return A float number.
+     */
     inline float getRestitution() const { return _material.restitution; }
+    
+    /**
+     * Set this shape's restitution.
+     *
+     * It will change the shape's elasticity.
+     *
+     * @param restitution A float number.
+     */
     void setRestitution(float restitution);
+    
+    /**
+     * Get this shape's friction.
+     *
+     * @return A float number.
+     */
     inline float getFriction() const { return _material.friction; }
+    
+    /**
+     * Set this shape's friction.
+     *
+     * It will change the shape's friction.
+     *
+     * @param friction A float number.
+     */
     void setFriction(float friction);
+    
+    /**
+     * Get this shape's PhysicsMaterial object.
+     *
+     * @return A PhysicsMaterial object reference.
+     */
     const PhysicsMaterial& getMaterial() const { return _material; }
+    
+    /**
+     * Set this shape's material.
+     *
+     * It will change the shape's mass, elasticity and friction.
+     *
+     * @param material A PhysicsMaterial object.
+     */
     void setMaterial(const PhysicsMaterial& material);
     
-    /** Calculate the default moment value */
+    /** 
+     * Calculate the default moment value.
+     * 
+     * This function should be overrided in inherit classes.
+     * @return A float number, equals 0.0.
+     */
     virtual float calculateDefaultMoment() { return 0.0f; }
-    /** Get offset */
+    
+    /**
+     * Get this shape's position offset.
+     *
+     * This function should be overrided in inherit classes.
+     * @return A Vec2 object.
+     */
     virtual Vec2 getOffset() { return Vec2::ZERO; }
-    /** Get center of this shape */
+    
+    /**
+     * Get this shape's center position.
+     *
+     * This function should be overrided in inherit classes.
+     * @return A Vec2 object.
+     */
     virtual Vec2 getCenter() { return getOffset(); }
-    /** Test point is in shape or not */
+    
+    /** 
+     * Test point is inside this shape or not.
+     *
+     * @param point A Vec2 object.
+     * @return A bool object.
+     */
     bool containsPoint(const Vec2& point) const;
     
-    /** move the points to the center */
+    /** 
+     * Move the points to the center.
+     * 
+     * @param points A Vec2 object pointer.
+     * @param count An interger number.
+     * @param center A Vec2 object, default value is Vec2(0,0).
+     */
     static void recenterPoints(Vec2* points, int count, const Vec2& center = Vec2::ZERO);
-    /** get center of the polyon points */
+
+    /**
+     * Get center of the polyon points.
+     *
+     * @param points A Vec2 object pointer.
+     * @param count An interger number.
+     * @return A Vec2 object.
+     */
     static Vec2 getPolyonCenter(const Vec2* points, int count);
     
     /**
-     * A mask that defines which categories this physics body belongs to.
+     * Set a mask that defines which categories this physics body belongs to.
+     *
      * Every physics body in a scene can be assigned to up to 32 different categories, each corresponding to a bit in the bit mask. You define the mask values used in your game. In conjunction with the collisionBitMask and contactTestBitMask properties, you define which physics bodies interact with each other and when your game is notified of these interactions.
-     * The default value is 0xFFFFFFFF (all bits set).
+     * @param bitmask An interger number, the default value is 0xFFFFFFFF (all bits set).
      */
     inline void setCategoryBitmask(int bitmask) { _categoryBitmask = bitmask; }
+    
+    /**
+     * Get a mask that defines which categories this physics body belongs to.
+     *
+     * @return An interger number.
+     */
     inline int getCategoryBitmask() const { return _categoryBitmask; }
+    
+    
     /**
      * A mask that defines which categories of bodies cause intersection notifications with this physics body.
+     *
      * When two bodies share the same space, each body’s category mask is tested against the other body’s contact mask by performing a logical AND operation. If either comparison results in a non-zero value, an PhysicsContact object is created and passed to the physics world’s delegate. For best performance, only set bits in the contacts mask for interactions you are interested in.
-     * The default value is 0x00000000 (all bits cleared).
+     * @param bitmask An interger number, the default value is 0x00000000 (all bits cleared).
      */
     inline void setContactTestBitmask(int bitmask) { _contactTestBitmask = bitmask; }
+    
+    /**
+     * Get a mask that defines which categories of bodies cause intersection notifications with this physics body.
+     *
+     * @return An interger number.
+     */
     inline int getContactTestBitmask() const { return _contactTestBitmask; }
+
     /**
      * A mask that defines which categories of physics bodies can collide with this physics body.
+     *
      * When two physics bodies contact each other, a collision may occur. This body’s collision mask is compared to the other body’s category mask by performing a logical AND operation. If the result is a non-zero value, then this body is affected by the collision. Each body independently chooses whether it wants to be affected by the other body. For example, you might use this to avoid collision calculations that would make negligible changes to a body’s velocity.
-     * The default value is 0xFFFFFFFF (all bits set).
+     * @param bitmask An interger number, the default value is 0xFFFFFFFF (all bits set).
      */
     inline void setCollisionBitmask(int bitmask) { _collisionBitmask = bitmask; }
+    
+    /**
+     * Get a mask that defines which categories of physics bodies can collide with this physics body.
+     *
+     * @return An interger number.
+     */
     inline int getCollisionBitmask() const { return _collisionBitmask; }
     
     /**
-     * set the group of body
+     * Set the group of body.
-     * Collision groups let you specify an integral group index. You can have all fixtures with the same group index always collide (positive index) or never collide (negative index)
+     *
-     * it have high priority than bit masks
+     * Collision groups let you specify an integral group index. You can have all fixtures with the same group index always collide (positive index) or never collide (negative index).
+     * @param group An interger number, it have high priority than bit masks.
      */
     void setGroup(int group);
+    
+    /**
+     * Get the group of body.
+     *
+     * @return An interger number.
+     */
     inline int getGroup() { return _group; }
     
 protected:
@@ -186,17 +363,57 @@ protected:
     friend class PhysicsDebugDraw;
 };
 
-/** A circle shape */
+/** A circle shape. */
 class CC_DLL PhysicsShapeCircle : public PhysicsShape
 {
 public:
+    /**
+     * Creates a PhysicsShapeCircle with specified value.
+     *
+     * @param   radius A float number, it is the circle's radius.
+     * @param   material A PhysicsMaterial object, the default value is PHYSICSSHAPE_MATERIAL_DEFAULT.
+     * @param   offset A Vec2 object, it is the offset from the body’s center of gravity in body local coordinates.
+     * @return  An autoreleased PhysicsShapeCircle object pointer.
+     */
     static PhysicsShapeCircle* create(float radius, const PhysicsMaterial& material = PHYSICSSHAPE_MATERIAL_DEFAULT, const Vec2& offset = Vec2(0, 0));
+    
+    /**
+     * Calculate the area of a circle with specified radius.
+     *
+     * @param radius A float number
+     * @return A float number
+     */
     static float calculateArea(float radius);
+    
+    /**
+     * Calculate the moment of a circle with specified value.
+     *
+     * @param mass A float number
+     * @param radius A float number
+     * @param offset A Vec2 object, it is the offset from the body’s center of gravity in body local coordinates.
+     * @return A float number
+     */
     static float calculateMoment(float mass, float radius, const Vec2& offset = Vec2::ZERO);
     
+    /**
+     * Calculate the moment for a circle.
+     *
+     * @return A float number.
+     */
     virtual float calculateDefaultMoment() override;
     
+    /**
+     * Get the circle's radius.
+     *
+     * @return A float number.
+     */
     float getRadius() const;
+    
+    /**
+     * Get this circle's position offset.
+     *
+     * @return A Vec2 object.
+     */
     virtual Vec2 getOffset() override;
     
 protected:
@@ -209,19 +426,75 @@ protected:
     virtual ~PhysicsShapeCircle();
 };
 
-/** A polygon shape */
+/** A polygon shape. */
 class CC_DLL PhysicsShapePolygon : public PhysicsShape
 {
 public:
+    /**
+     * Creates a PhysicsShapePolygon with specified value.
+     *
+     * @param   points A Vec2 object pointer, it is an array of Vec2.
+     * @param   count An interger number, contains the count of the points array.
+     * @param   material A PhysicsMaterial object, the default value is PHYSICSSHAPE_MATERIAL_DEFAULT.
+     * @param   offset A Vec2 object, it is the offset from the body’s center of gravity in body local coordinates.
+     * @return  An autoreleased PhysicsShapePolygon object pointer.
+     */
     static PhysicsShapePolygon* create(const Vec2* points, int count, const PhysicsMaterial& material = PHYSICSSHAPE_MATERIAL_DEFAULT, const Vec2& offset = Vec2::ZERO);
+    
+    /**
+     * Calculate the area of a polygon with specified value.
+     *
+     * @param   points A Vec2 object pointer, it is an array of Vec2.
+     * @param   count An interger number, contains the count of the points array.
+     * @return A float number.
+     */
     static float calculateArea(const Vec2* points, int count);
+    
+    /**
+     * Calculate the moment of a polygon with specified value.
+     *
+     * @param mass A float number
+     * @param   points A Vec2 object pointer, it is an array of Vec2.
+     * @param   count An interger number, contains the count of the points array.
+     * @param offset A Vec2 object, it is the offset from the body’s center of gravity in body local coordinates.
+     * @return A float number
+     */
     static float calculateMoment(float mass, const Vec2* points, int count, const Vec2& offset = Vec2::ZERO);
     
+    /**
+     * Calculate the moment for a polygon.
+     *
+     * @return A float number.
+     */
     float calculateDefaultMoment() override;
     
+    /**
+     * Get a point of this polygon's points array.
+     *
+     * @param i A index of this polygon's points array.
+     * @return A point value.
+     */
     Vec2 getPoint(int i) const;
+    
+    /**
+     * Get this polygon's points array.
+     *
+     * @param outPoints A Vec2 array pointer.
+     */
     void getPoints(Vec2* outPoints) const;
+    
+    /**
+     * Get this polygon's points array count.
+     *
+     * @preturn An interger number.
+     */
     int getPointsCount() const;
+    
+    /**
+     * Get this polygon's center position.
+     *
+     * @return A Vec2 object.
+     */
     virtual Vec2 getCenter() override;
 protected:
     bool init(const Vec2* points, int count, const PhysicsMaterial& material = PHYSICSSHAPE_MATERIAL_DEFAULT, const Vec2& offset = Vec2::ZERO);
@@ -233,13 +506,32 @@ protected:
     virtual ~PhysicsShapePolygon();
 };
 
-/** A box shape */
+/** A box shape. */
 class CC_DLL PhysicsShapeBox : public PhysicsShapePolygon
 {
 public:
+    /**
+     * Creates a PhysicsShapeBox with specified value.
+     *
+     * @param   size Size contains this box's width and height.
+     * @param   material A PhysicsMaterial object, the default value is PHYSICSSHAPE_MATERIAL_DEFAULT.
+     * @param   offset A Vec2 object, it is the offset from the body’s center of gravity in body local coordinates.
+     * @return  An autoreleased PhysicsShapeBox object pointer.
+     */
     static PhysicsShapeBox* create(const Size& size, const PhysicsMaterial& material = PHYSICSSHAPE_MATERIAL_DEFAULT, const Vec2& offset = Vec2::ZERO);
     
+    /**
+     * Get this box's width and height.
+     *
+     * @preturn An Size object.
+     */
     Size getSize() const;
+    
+    /**
+     * Get this box's position offset.
+     *
+     * @return A Vec2 object.
+     */
     virtual Vec2 getOffset() override { return getCenter(); }
     
 protected:
@@ -250,14 +542,40 @@ protected:
     virtual ~PhysicsShapeBox();
 };
 
-/** A segment shape */
+/** A segment shape. */
 class CC_DLL PhysicsShapeEdgeSegment : public PhysicsShape
 {
 public:
+    /**
+     * Creates a PhysicsShapeEdgeSegment with specified value.
+     *
+     * @param   a It's the edge's begin position.
+     * @param   b It's the edge's end position.
+     * @param   material A PhysicsMaterial object, the default value is PHYSICSSHAPE_MATERIAL_DEFAULT.
+     * @param   border It's a edge's border width.
+     * @return  An autoreleased PhysicsShapeEdgeSegment object pointer.
+     */
     static PhysicsShapeEdgeSegment* create(const Vec2& a, const Vec2& b, const PhysicsMaterial& material = PHYSICSSHAPE_MATERIAL_DEFAULT, float border = 1);
     
+    /**
+     * Get this edge's begin position.
+     *
+     * @return A Vec2 object.
+     */
     Vec2 getPointA() const;
+    
+    /**
+     * Get this edge's end position.
+     *
+     * @return A Vec2 object.
+     */
     Vec2 getPointB() const;
+    
+    /**
+     * Get this edge's center position.
+     *
+     * @return A Vec2 object.
+     */
     virtual Vec2 getCenter() override;
     
 protected:
@@ -271,13 +589,40 @@ protected:
     friend class PhysicsBody;
 };
 
-/** An edge polygon shape */
+/** An edge polygon shape. */
 class CC_DLL PhysicsShapeEdgePolygon : public PhysicsShape
 {
 public:
+    /**
+     * Creates a PhysicsShapeEdgePolygon with specified value.
+     *
+     * @param   points A Vec2 object pointer, it contains an array of points.
+     * @param   count An interger number, contains the count of the points array.
+     * @param   material A PhysicsMaterial object, the default value is PHYSICSSHAPE_MATERIAL_DEFAULT.
+     * @param   border It's a edge's border width.
+     * @return  An autoreleased PhysicsShapeEdgePolygon object pointer.
+     */
     static PhysicsShapeEdgePolygon* create(const Vec2* points, int count, const PhysicsMaterial& material = PHYSICSSHAPE_MATERIAL_DEFAULT, float border = 1);
+    
+    /**
+     * Get this polygon's center position.
+     *
+     * @return A Vec2 object.
+     */
     virtual Vec2 getCenter() override;
+    
+    /**
+     * Get this polygon's points array.
+     *
+     * @param outPoints A Vec2 array pointer.
+     */
     void getPoints(Vec2* outPoints) const;
+    
+    /**
+     * Get this polygon's points array count.
+     *
+     * @preturn An interger number.
+     */
     int getPointsCount() const;
     
 protected:
@@ -291,11 +636,26 @@ protected:
     friend class PhysicsBody;
 };
 
-/** An edge box shape */
+/** An edge box shape. */
 class CC_DLL PhysicsShapeEdgeBox : public PhysicsShapeEdgePolygon
 {
 public:
+    /**
+     * Creates a PhysicsShapeEdgeBox with specified value.
+     *
+     * @param   size Size contains this box's width and height.
+     * @param   material A PhysicsMaterial object, the default value is PHYSICSSHAPE_MATERIAL_DEFAULT.
+     * @param   border It's a edge's border width.
+     * @param   offset A Vec2 object, it is the offset from the body’s center of gravity in body local coordinates.
+     * @return  An autoreleased PhysicsShapeEdgeBox object pointer.
+     */
     static PhysicsShapeEdgeBox* create(const Size& size, const PhysicsMaterial& material = PHYSICSSHAPE_MATERIAL_DEFAULT, float border = 0, const Vec2& offset = Vec2::ZERO);
+    
+    /**
+     * Get this box's position offset.
+     *
+     * @return A Vec2 object.
+     */
     virtual Vec2 getOffset() override { return getCenter(); }
     
 protected:
@@ -308,13 +668,40 @@ protected:
     friend class PhysicsBody;
 };
 
-/** a chain shape */
+/** A chain shape. */
 class CC_DLL PhysicsShapeEdgeChain : public PhysicsShape
 {
 public:
+    /**
+     * Creates a PhysicsShapeEdgeChain with specified value.
+     *
+     * @param   points A Vec2 object pointer, it contains an array of points.
+     * @param   count An interger number, contains the count of the points array.
+     * @param   material A PhysicsMaterial object, the default value is PHYSICSSHAPE_MATERIAL_DEFAULT.
+     * @param   border It's a edge's border width.
+     * @return  An autoreleased PhysicsShapeEdgeChain object pointer.
+     */
     static PhysicsShapeEdgeChain* create(const Vec2* points, int count, const PhysicsMaterial& material = PHYSICSSHAPE_MATERIAL_DEFAULT, float border = 1);
+    
+    /**
+     * Get this chain's center position.
+     *
+     * @return A Vec2 object.
+     */
     virtual Vec2 getCenter() override;
+    
+    /**
+     * Get this chain's points array.
+     *
+     * @param outPoints A Vec2 array pointer.
+     */
     void getPoints(Vec2* outPoints) const;
+    
+    /**
+     * Get this chain's points array count.
+     *
+     * @preturn An interger number.
+     */
     int getPointsCount() const;
     
 protected:
@@ -328,6 +715,8 @@ protected:
     friend class PhysicsBody;
 };
 
+/** @} */
+
 NS_CC_END
 
 #endif // CC_USE_PHYSICS

cocos/physics/CCPhysicsWorld.h

@@ -389,7 +389,10 @@ protected:
     friend class PhysicsDebugDraw;
 };
 
-
+/** A physics helper class. Draw physics shape, joint in debug mode. 
+ 
+ *  You do not create PhysicsDebugDraw objects directly; Instead, you can activate it by PhysicsWorld::setDebugDrawMask.
+ */
 class CC_DLL PhysicsDebugDraw
 {
 protected: