diff --git a/src/mobility/random-walk-2d-mobility-model.h b/src/mobility/random-walk-2d-mobility-model.h
index 42948a15c..3b5755a55 100644
--- a/src/mobility/random-walk-2d-mobility-model.h
+++ b/src/mobility/random-walk-2d-mobility-model.h
@@ -37,8 +37,10 @@ namespace ns3 {
  * Each instance moves with a speed and direction choosen at random
  * with the user-provided random variables until
  * either a fixed distance has been walked or until a fixed amount
- * of time.
- *
+ * of time. If we hit one of the boundaries (specified by a rectangle),
+ * of the model, we rebound on the boundary with a reflexive angle
+ * and speed. This model is often identified as a brownian motion
+ * model.
  */
 class RandomWalk2dMobilityModel : public MobilityModel 
 {
diff --git a/src/mobility/random-waypoint-mobility-model.h b/src/mobility/random-waypoint-mobility-model.h
index b6a5de1f4..74d46370a 100644
--- a/src/mobility/random-waypoint-mobility-model.h
+++ b/src/mobility/random-waypoint-mobility-model.h
@@ -38,7 +38,8 @@ namespace ns3 {
  *
  * The implementation of this model is not 2d-specific. i.e. if you provide
  * a 3d random waypoint position model to this mobility model, the model 
- * will still work.
+ * will still work. There is no 3d position allocator for now but it should
+ * be trivial to add one.
  */
 class RandomWaypointMobilityModel : public MobilityModel
 {
diff --git a/src/mobility/rectangle.cc b/src/mobility/rectangle.cc
index 1befebe01..6a0c5e221 100644
--- a/src/mobility/rectangle.cc
+++ b/src/mobility/rectangle.cc
@@ -86,6 +86,7 @@ Rectangle::GetClosestSide (const Vector &position) const
 Vector
 Rectangle::CalculateIntersection (const Vector &current, const Vector &speed) const
 {
+  NS_ASSERT (IsInside (current));
   double xMaxY = current.y + (this->xMax - current.x) / speed.x * speed.y;
   double xMinY = current.y + (this->xMin - current.x) / speed.x * speed.y;
   double yMaxX = current.x + (this->yMax - current.y) / speed.y * speed.x;
diff --git a/src/mobility/rectangle.h b/src/mobility/rectangle.h
index d49d5365b..fcc8fc1cb 100644
--- a/src/mobility/rectangle.h
+++ b/src/mobility/rectangle.h
@@ -53,13 +53,42 @@ public:
    * Create a zero-sized rectangle located at coordinates (0.0,0.0)
    */
   Rectangle ();
+  /**
+   * \param position the position to test.
+   * \returns true if the input position is located within the rectangle, 
+   *          false otherwise.
+   *
+   * This method compares only the x and y coordinates of the input position.
+   * It ignores the z coordinate.
+   */
   bool IsInside (const Vector &position) const;
+  /**
+   * \param position the position to test.
+   * \returns the side of the rectangle the input position is closest to.
+   *
+   * This method compares only the x and y coordinates of the input position.
+   * It ignores the z coordinate.
+   */
   Side GetClosestSide (const Vector &position) const;
+  /**
+   * \param current the current position
+   * \param speed the current speed
+   * \returns the intersection point between the rectangle and the current+speed vector.
+   *
+   * This method assumes that the current position is located _inside_
+   * the rectangle and checks for this with an assert.
+   * This method compares only the x and y coordinates of the input position
+   * and speed. It ignores the z coordinate.
+   */
   Vector CalculateIntersection (const Vector &current, const Vector &speed) const;
 
+  /* The x coordinate of the left bound of the rectangle */
   double xMin;
+  /* The x coordinate of the right bound of the rectangle */
   double xMax;
+  /* The y coordinate of the bottom bound of the rectangle */
   double yMin;
+  /* The y coordinate of the top bound of the rectangle */
   double yMax;
 };
 
diff --git a/src/mobility/vector.h b/src/mobility/vector.h
index 4bf1716d3..e3e3191aa 100644
--- a/src/mobility/vector.h
+++ b/src/mobility/vector.h
@@ -59,6 +59,11 @@ public:
   double z;
 };
 
+/**
+ * \param a one point
+ * \param b another point
+ * \returns the cartesian distance between a and b.
+ */
 double CalculateDistance (const Vector &a, const Vector &b);
 
 /**