--- a/src/buildings/doc/source/buildings-design.rst	Tue May 15 19:14:44 2012 +0200
+++ b/src/buildings/doc/source/buildings-design.rst	Tue May 15 19:25:01 2012 +0200
@@ -46,9 +46,32 @@
   * number of rooms in x-axis (default value 1)
   * number of rooms in y-axis (default value 1)
 
-By means of the number of rooms in x and y axis it is possible the definition of buildings where rooms are organized in grids, typical reference scenario for femto-cells in 3GPP called dual-strip.
+The Building class is based on the following assumptions:
+
+ * a buildings is represented as a rectangular parallelepiped (i.e., a box)
+ * the walls are parallel to the x, y, and z axis
+ * a building is divided into a grid of rooms, identified by the following parameters:
+ 
+   * number of floors 
+   * number of rooms along the x-axis
+   * number of rooms along the y-axis
 
-The ``Building`` class is included in ``BuildingsMobilityModel`` class, which inherits from the ns3 class ``MobilityModel`` and it is in charge of managing the standard mobility functionalities plus the building ones (e.g., floor and room of the node).
+ * the z axis is the vertical axis, i.e., floor numbers increase for increasing z axis values
+ * the x and y room indices start from 1 and increase along the x and y axis respectively
+ * all rooms in a building have equal size
+
+
+
+The BuildingsMobilityModel class
+++++++++++++++++++++++++++++++++
+
+The ``BuildingsMobilityModel`` class, which inherits from the ns3 class ``MobilityModel``, is in charge of managing the standard mobility functionalities plus providing information about the position of a node with respect to building. The information managed by ``BuildingsMobilityModel`` is:
+
+  * whether the node is indoor or outdoor
+  * if indoor:
+
+    * in which building the node is
+    * in which room the node is positioned (x, y and floor room indices)  
 
 The class ``BuildingsMobilityModel`` is used by ``BuildingsPropagationLossModel`` class, which inherits from the ns3 class ``PropagationLossModel`` and manages the pathloss computation of the single components and their composition according to the nodes' positions. Moreover, it implements also the shadowing, that is the loss due to obstacles in the main path (i.e., vegetation, buildings, etc.).
 

--- a/src/buildings/doc/source/buildings-testing.rst	Tue May 15 19:14:44 2012 +0200
+++ b/src/buildings/doc/source/buildings-testing.rst	Tue May 15 19:25:01 2012 +0200
@@ -37,8 +37,14 @@
 The test suite ``buildings-helper`` checks that the method ``BuildingsHelper::MakeAllInstancesConsistent ()`` works properly, i.e., that the BuildingsHelper is successful in locating if nodes are outdoor or indoor, and if indoor that they are located in the correct building, room and floor. Several test cases are provided with different buildings (having different size, position, rooms and floors) and different node positions. The test passes if each every node is located correctly.
 
 
-Pathloss tests
-~~~~~~~~~~~~~~
+BuildingPositionAllocator test
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The test suite ``building-position-allocator`` feature two test cases that check that respectively RandomRoomPositionAllocator and SameRoomPositionAllocator work properly. Each test cases involves a single 2x3x2 room building (total 12 rooms) at known coordinates and respectively 24 and 48 nodes. Both tests check that the number of nodes allocated in each room is the expected one and that the position of the nodes is also correct.
+
+
+Buildings Pathloss tests
+~~~~~~~~~~~~~~~~~~~~~~~~
 
 The test suite ``buildings-pathloss-model`` provides different unit tests that compare the expected results of the buildings pathloss module in specific scenarios with pre calculated values obtained offline with an Octave script (test/reference/buildings-pathloss.m). The tests are considered passed if the two values are equal up to a tolerance of 0.1, which is deemed appropriate for the typical usage of pathloss values (which are in dB).
 
@@ -96,8 +102,8 @@
 This test validates the outdoor to indoor transmissions for short distances. In this case the eNB is placed in the second floor of a residential building with walls made of concrete with windows and distances 500 meters from the outdoor UE (i.e., NLoS communication). Therefore the height gain has to be included in the pathloss evaluation.
 
 
-Shadowing Test
-~~~~~~~~~~~~~~
+Buildings Shadowing Test
+~~~~~~~~~~~~~~~~~~~~~~~~
 
 The test suite ``buildings-shadowing-test`` is a unit test intended to verify the statistics distribution characteristics of the shadowing are the one expected. The shadowing is modeled according to a normal distribution with mean :math:`\mu = 0` and variable standard deviation :math:`\sigma`, according to models commonly used in literature.
 The test generates 10,000 samples of shadowing by subtracting the deterministic component from the total loss returned by the ``BuildingPathlossModel``. The mean and variance of the shadowing samples are then used to verify whether the 99% confidence interval is respected by the sequence generated by the simulator.

--- a/src/buildings/helper/building-position-allocator.cc	Tue May 15 19:14:44 2012 +0200
+++ b/src/buildings/helper/building-position-allocator.cc	Tue May 15 19:25:01 2012 +0200
@@ -128,11 +128,11 @@
       for (BuildingList::Iterator bit = BuildingList::Begin (); bit != BuildingList::End (); ++bit)
         {
           NS_LOG_LOGIC ("building " << (*bit)->GetId ());
-          for (uint32_t rx = 0; rx < (*bit)->GetNRoomsX (); ++rx)
+          for (uint32_t rx = 1; rx <= (*bit)->GetNRoomsX (); ++rx)
             {
-              for (uint32_t ry = 0; ry < (*bit)->GetNRoomsY (); ++ry)
+              for (uint32_t ry = 1; ry <= (*bit)->GetNRoomsY (); ++ry)
                 {
-                  for (uint32_t f = 0; f < (*bit)->GetNFloors (); ++f)
+                  for (uint32_t f = 1; f <= (*bit)->GetNFloors (); ++f)
                     {
                       RoomInfo i;
                       i.roomx = rx;
@@ -149,7 +149,7 @@
   uint32_t n = rand.GetInteger (0,m_roomListWithoutReplacement.size () - 1);
   RoomInfo r = m_roomListWithoutReplacement.at (n);      
   m_roomListWithoutReplacement.erase (m_roomListWithoutReplacement.begin () + n);  
-  NS_LOG_LOGIC ("considering room (" << r.roomx << ", " << r.roomy << ", " << r.floor << ")");
+  NS_LOG_LOGIC ("considering building " << r.b->GetId () << " room (" << r.roomx << ", " << r.roomy << ", " << r.floor << ")");
 
   Ptr<RandomBoxPositionAllocator> pa = CreateObject<RandomBoxPositionAllocator> ();
   UniformVariable v;
@@ -159,12 +159,12 @@
   double rdx =  (box.xMax - box.xMin) / r.b->GetNRoomsX ();
   double rdy =  (box.yMax - box.yMin) / r.b->GetNRoomsY ();
   double rdz =  (box.zMax - box.zMin) / r.b->GetNFloors ();
-  double x1 = box.xMin + rdx * r.roomx;
-  double x2 = box.xMin + rdx * (r.roomx + 1);
-  double y1 = box.yMin + rdy * r.roomy;
-  double y2 = box.yMin + rdy * (r.roomy + 1);
-  double z1 = box.zMin + rdz * r.floor;
-  double z2 = box.zMin + rdz * (r.floor + 1);
+  double x1 = box.xMin + rdx * (r.roomx - 1);
+  double x2 = box.xMin + rdx * r.roomx;
+  double y1 = box.yMin + rdy * (r.roomy -1);
+  double y2 = box.yMin + rdy * r.roomy;
+  double z1 = box.zMin + rdz * (r.floor - 1);
+  double z2 = box.zMin + rdz * r.floor;
   NS_LOG_LOGIC ("randomly allocating position in "
                 << " (" << x1 << "," << x2 << ") "
                 << "x (" << y1 << "," << y2 << ") "
@@ -247,12 +247,12 @@
   double rdx =  (box.xMax - box.xMin) / b->GetNRoomsX ();
   double rdy =  (box.yMax - box.yMin) / b->GetNRoomsY ();
   double rdz =  (box.zMax - box.zMin) / b->GetNFloors ();
-  double x1 = box.xMin + rdx * roomx;
-  double x2 = box.xMin + rdx * (roomx + 1);
-  double y1 = box.yMin + rdy * roomy;
-  double y2 = box.yMin + rdy * (roomy + 1);
-  double z1 = box.zMin + rdz * floor;
-  double z2 = box.zMin + rdz * (floor + 1);
+  double x1 = box.xMin + rdx * (roomx - 1);
+  double x2 = box.xMin + rdx * roomx;
+  double y1 = box.yMin + rdy * (roomy -1);
+  double y2 = box.yMin + rdy * roomy;
+  double z1 = box.zMin + rdz * (floor - 1);
+  double z2 = box.zMin + rdz * floor;
   NS_LOG_LOGIC ("randomly allocating position in "
                 << " (" << x1 << "," << x2 << ") "
                 << "x (" << y1 << "," << y2 << ") "

--- a/src/buildings/model/buildings-mobility-model.cc	Tue May 15 19:14:44 2012 +0200
+++ b/src/buildings/model/buildings-mobility-model.cc	Tue May 15 19:25:01 2012 +0200
@@ -24,6 +24,7 @@
 #include <ns3/buildings-mobility-model.h>
 #include <ns3/pointer.h>
 #include <ns3/log.h>
+#include <ns3/assert.h>
 
 NS_LOG_COMPONENT_DEFINE ("BuildingsMobilityModel");
 
@@ -111,10 +112,14 @@
   m_roomX = nroomx;
   m_roomY = nroomy;
   
-  if (!building->IsInside (m_helper.GetCurrentPosition ()))
-    {
-      NS_FATAL_ERROR ("Position of the node is inconsistent with building bounds");
-    }
+  NS_ASSERT_MSG (building->IsInside (m_helper.GetCurrentPosition ()), "Position of the node is outside of building bounds");
+  NS_ASSERT (m_roomX > 0);
+  NS_ASSERT (m_roomX <= building->GetNRoomsX ());
+  NS_ASSERT (m_roomY > 0);
+  NS_ASSERT (m_roomY <= building->GetNRoomsY ());
+  NS_ASSERT (m_nFloor > 0);
+  NS_ASSERT (m_nFloor <= building->GetNFloors ());
+
 }
 
 

--- a/src/buildings/model/buildings-mobility-model.h	Tue May 15 19:14:44 2012 +0200
+++ b/src/buildings/model/buildings-mobility-model.h	Tue May 15 19:25:01 2012 +0200
@@ -44,29 +44,75 @@
  * either indoor (e.g., houses, offices, etc.) and outdoor.
  * 
  */
-
-
 class BuildingsMobilityModel : public MobilityModel
 {
 public:
   static TypeId GetTypeId (void);
   BuildingsMobilityModel ();
 
+  /** 
+   * 
+   * \return true if the MobilityModel instance is indoor, false otherwise
+   */
   bool IsIndoor (void);
+
+  /** 
+   * 
+   * \return true if the MobilityModel instance is outdoor, false otherwise
+   */
   bool IsOutdoor (void);
 
+
+  /** 
+   * Mark this MobilityModel instance as indoor 
+   * 
+   * \param building the building into which the MobilityModel instance is located
+   */
   void SetIndoor (Ptr<Building> building);
+
+
+  /** 
+   * Mark this MobilityModel instance as indoor 
+   * 
+   * \param building the building into which the MobilityModel instance is located
+   * \param nfloor the floor number 1...nFloors at which the  MobilityModel instance is located
+   * \param nroomx the X room number 1...nRoomsX at which the  MobilityModel instance is located
+   * \param nroomy the Y room number 1...nRoomsY at which the  MobilityModel instance is located
+   */
   void SetIndoor (Ptr<Building> building, uint8_t nfloor, uint8_t nroomx, uint8_t nroomy);
+
+  /** 
+   * Mark this MobilityModel instance as outdoor 
+   * 
+   */
   void SetOutdoor (void);
 
   void SetFloorNumber (uint8_t nfloor);
   void SetRoomNumberX (uint8_t nroomx);
   void SetRoomNumberY (uint8_t nroomy);
 
+  /** 
+   * 
+   * \return 
+   */
   uint8_t GetFloorNumber (void);
+
+  /** 
+   * 
+   * \return 
+   */
   uint8_t GetRoomNumberX (void);
+
+  /** 
+   * 
+   * \return 
+   */
   uint8_t GetRoomNumberY (void);
 
+  /** 
+   * 
+   * \return 
+   */
   Ptr<Building> GetBuilding ();
 
 
@@ -80,9 +126,6 @@
 
   Ptr<Building> m_myBuilding;
   bool m_indoor;
-  /**
-  * floors numbering starts from 0 (basement)
-  */
   uint8_t m_nFloor;
   uint8_t m_roomX;
   uint8_t m_roomY;