# HG changeset patch
# User saiam
# Date 1228775604 0
# Node ID cb33eca69b299b235441b40e2e5934fa0f785929
# Parent  9f6a838d58c4d6d76745dee097a0423b27dcccfe
Updated PhysicsObject documentation

diff -r 9f6a838d58c4 -r cb33eca69b29 src/PhysicsObject.hh
--- a/src/PhysicsObject.hh	Mon Dec 08 22:28:51 2008 +0000
+++ b/src/PhysicsObject.hh	Mon Dec 08 22:33:24 2008 +0000
@@ -15,58 +15,84 @@
 
 // Type definitions
 typedef Vector Force;
-    
+
+/** Specifies possible object types. */
 enum ObjectType { PLAYER, PROJECTILE, ROPE };
 
+/** Specifies possible facing directions for objects. */
 enum FacingDirection {
     FACING_LEFT,
     FACING_RIGHT
 };
 
 /**
- * PhysicObject class. 
- *
- * A basic PhysicsObject class.
+ * PhysicObject class. Represents an object in the physics simulation.
  */
 class PhysicsObject {
 public:
+    /** Reference to PhysicsWorld. */
     PhysicsWorld &world;
 
 protected:
+    /** Object position. */
     Vector position;
+    /** Object position on previous physics tick. */
     Vector previousPosition;
+    /** Object velocity */
     Vector velocity;
+    /** Object mass. */
     float mass;
-    bool inAir; // Is the object "on the ground"
+    /** Tells if the object is "on the ground" */
+    bool inAir;
+    /** Object elasticity. */
     float collision_elasticity;
 
     // Attributes for players
-    float aim; // Aim direction (half circle)
-    FacingDirection facing; // Player facing
+    /** Aim angle in radians. */
+    float aim; 
+    /** Player facing. */
+    FacingDirection facing; 
 
+    /** Specifies if the player is alive (or dead). */
     bool alive;
+    /** True if player object should be removed from the game. */
     bool shouldDelete;
     
+    /** Type of the object */
     ObjectType type;
 
+    /** Pivot object for this object. */
     PhysicsObject *pivot;
 
+    /** 
+     * Class constructor
+     *
+     * @param world Reference to PhysicsWorld
+     * @param mass Object mass
+     * @param position Object position
+     * @param velocity Object velocity
+     * @param type Object type
+     * @param collision_elasticity Object elasticity
+     * @param enabled Is the object currently part of the simulation
+     */
     PhysicsObject (PhysicsWorld &world, float mass, Vector position, Vector velocity, ObjectType type, 
             float collision_elasticity, bool enabled = true);
     virtual ~PhysicsObject (void);
 
 
     /**
-     * Add force to the force queue to be applied on next tick.
+     * Apply a force to the object. The force is applied to the object
+     * on the next physics tick.
      *
      * @param force Force vector
      */
     void applyForce(Force force, TimeMS dt = PHYSICS_TICK_MS);
 
     /**
-     * Change player aim
+     * Change player aim. This function takes care that aim angle
+     * stays inside limits.
      *
-     * @param da Aim angle change
+     * @param da Aim angle change in radians
      */
     void changeAim(float da);
    
@@ -79,12 +105,13 @@
 
     /**
      * Makes the player jump in the air.
+     *
      * @param direction -1: jump left, 0: jump up, 1: jump right
      */
     void jump (int direction);
 
     /** 
-     * Handle ground-bounce
+     * Handle object bounce.
      *
      * @param normal Normal vector relative to which to bounce
      */
@@ -102,33 +129,40 @@
     virtual void updatePhysics (Vector position, Vector velocity, bool inAir, FacingDirection facing, float aim);
 
     /**
-     * Put object to the objects list so that its movement will be calculated.
+     * Put the object in the physics simulation. When the object is in
+     * the physics simulation it's movements will be calculated.
      */
     void enable (void);
 
     /**
-     * Remove object from the objects list but don't delete the object itself.
+     * Remove object from the objects physics simulation. When the
+     * object isn't in the physics simulation it won't be deleted but
+     * its movements will not be calculated.
      */
     void disable (void);
 
 private:
-    // Shape of the object. Edge points of the shape polygon.
+    /** Objects shape. Edgepoints of the polygon */
     std::vector<Vector> shape;
 
-    // Force queue that is emptied on every tick
+    /** Object force queue. The queue is emptied on every physics
+        tick.*/
     std::queue<std::pair<Force, TimeMS> > forceq;
 
     /**
      * Handle player movement and apply forces.
+     *
+     * @param dt Time intervall
      */
     void updatePosition (TimeMS dt);
 
-    // TODO: Should these be moved to PhysicsWorld?
     /**
      * Use RK4 to integrate the effects of force over a time interwall.
      *
      * @param force Force to integrate
      * @param dt Time intervall
+     * @param posAfterTick Reference to object postition after integration.
+     * @param velAfterTick Reference to object velocity after integration.
      */
     void integrate (Force force, TimeMS dt, Vector &posAfterTick, Vector &velAfterTick);
 
@@ -138,6 +172,7 @@
      * @param force Force
      * @param dt Time
      * @param d Previous derivative
+     * @return Derivative
      */
     Derivative evaluate (Force force, TimeMS dt, Derivative &d, const Vector &posAfterTick, const Vector &velAfterTick);
 
@@ -162,18 +197,23 @@
     /**
      * Define object behaviour on collisions.
      *
-     * XXX: make this pure-virtual
+     * @param collisionPoint Point of collision.
+     * @param other The other object we have collided with.
      */
     virtual void onCollision (Vector collisionPoint, PhysicsObject *other = NULL);
 
     /**
-     * Return the type of the physics object (player, projectile...)
+     * Get object type.
+     *
+     * @return Object type
      */
     ObjectType getType (void) const;
 
     /**
      * Checks if it is possible for the object to be in the given
      * location.
+     *
+     * @param loc Location
      */
     bool possibleLocation (Vector loc);
 
@@ -222,7 +262,7 @@
     /**
      * Set object shape.
      *
-     * @param shape Vector containing polygon poinst
+     * @param shape Vector containing polygon points
      */
     void setShape(std::vector<Vector> shape);
 
@@ -241,7 +281,9 @@
     float getAim() const;
 
     /**
-     * Returns facing+aim as a unit vector
+     * Get object direction.
+     *
+     * @return Unit vector to facing+aim
      */
     Vector getDirection (void) const;
 
@@ -250,18 +292,24 @@
      */
     void destroy (void);
 
-    /*
-     * Had the object been destroyed?
+    /**
+     * Check if the object is alive.
+     *
+     * @return Is the object alive?
      */
     bool isAlive (void);
     
     /**
-     * Delete ourselves if we've been destroyed and return true, else return false
+     * Tells the state of the object.
+     *
+     * @return True if object has been destroyed.
      */
     bool removeIfDestroyed (void);
 
     /**
-     * Sets this object's pivot to the given value, which will then exert a force on this object
+     * Set object pivot.
+     *
+     * @param pivot Pivot object
      */
     void setPivot (PhysicsObject *pivot);
 
@@ -269,20 +317,27 @@
      * Checks if object collides with other objects
      *
      * @param obj Other PhysicsObject
+     * @return Did we collide?
      */
     bool collides (const PhysicsObject &obj);
 
     /**
      * Compute the force that this object (as a pivot) exerts on the given object
+     *
+     * @param bob Othe object
+     * @return Force
      */
     virtual float getPivotForce (PhysicsObject *bob);
 
     /**
      * Update object in physics simulation.
+     *
+     * @param tick_length Length of the physics tick
      */
     virtual void tick (TimeMS tick_length);
 };
 
+/** Helper struct for the integration */
 struct Derivative {
     Vector dx; // Velocity
     Vector dv; // Acceleration