--- a/src/mobility/doc/mobility.rst	Fri Sep 21 13:48:41 2012 -0700
+++ b/src/mobility/doc/mobility.rst	Fri Sep 21 15:18:18 2012 -0700
@@ -148,14 +148,36 @@
    $ns at $time $node set Y_ Y1
    $ns at $time $node set Z_ Z1
 
+In the above, the initial positions are set using the ``set`` statements.
+Also, this ``set`` can be specified for a future time, such as in the
+last three statements above.  
+
+The command ``setdest`` instructs the simulation to start moving the 
+specified node towards the coordinate (x2, y2) at the specified time.
+Note that the node may never get to the destination, but will
+proceed towards the destination at the specified speed until it
+either reaches the destination (where it will pause), is set to 
+a new position (via ``set``), or sent on another course change
+(via ``setdest``).
+
+Note that in ns-3, movement along the Z dimension is not supported.
+
 Some examples of external tools that can export in this format include:
 
 - BonnMotion http://net.cs.uni-bonn.de/wg/cs/applications/bonnmotion/
+
+  - Some installation instructions for BonnMotion can be found here:  http://www.nsnam.org/wiki/index.php/HOWTO_use_ns-3_with_BonnMotion_mobility_generator_and_analysis_tool
+  - Documentation on using BonnMotion with ns-3 is posted here: http://www.ida.liu.se/~rikno/files/mobility_generation.pdf  
+
 - SUMO http://sourceforge.net/apps/mediawiki/sumo/index.php?title=Main_Page
 - TraNS http://trans.epfl.ch/
+- the ``setdest`` utility in ns-2, documented here: http://www.winlab.rutgers.edu/~zhibinwu/html/ns2_wireless_scene.htm
 
 A special Ns2MobilityHelper object can be used to parse these files
-and convert the statements into ns-3 mobility events.
+and convert the statements into ns-3 mobility events.  The underlying
+ConstantVelocityMobilityModel is used to model these movements.
+
+See below for additional usage instructions on this helper.
 
 Scope and Limitations
 =====================
@@ -217,6 +239,15 @@
 A MobilityHelper object may be reconfigured and reused for different
 NodeContainers during the configuration of an ns-3 scenario.
 
+Ns2MobilityHelper
+=================
+
+Two example programs are provided demonstrating the use of the
+ns-2 mobility helper:
+
+- ns2-mobility-trace.cc
+- bonnmotion-ns2-example.cc
+
 Use of Random Variables
 =======================
 
@@ -287,6 +318,7 @@
 - main-random-walk.cc
 - main-grid-topology.cc
 - ns2-mobility-trace.cc
+- ns2-bonnmotion.cc
 
 Validation
 **********

--- a/src/mobility/examples/ns2-mobility-trace.cc	Fri Sep 21 13:48:41 2012 -0700
+++ b/src/mobility/examples/ns2-mobility-trace.cc	Fri Sep 21 15:18:18 2012 -0700
@@ -19,17 +19,17 @@
  * Author: Martín Giachino <martin.giachino@gmail.com>
  *
  *
- * This example demonstrates the use of Ns2TransmobilityHelper class to work with mobility.
+ * This example demonstrates the use of Ns2MobilityHelper class to work with mobility.
  *
  * Detailed example description.
  *
  *  - intended usage: this should be used in order to load ns2 movement trace files into ns3.
  *  - behavior:
- *      - Ns2TransmobilityHelperTrace object is created, whith the specified trace file. At this moment, only
+ *      - Ns2MobilityHelperTrace object is created, whith the specified trace file. At this moment, only
  *      specify the file, and no movements are scheduled.
  *      - A log file is created, using the log file name argument.
  *      - A node container is created with the correct node number specified in the command line.
- *      - Use Install method of Ns2TransmobilityHelperTrace to set mobility to nodes. At this moment, file is
+ *      - Use Install method of Ns2MobilityHelperTrace to set mobility to nodes. At this moment, file is
  *      read line by line, and the movement is scheduled in the simulator.
  *      - A callback is configured, so each time a node changes its course a log message is printed.
  *  - expected output: example prints out messages generated by each read line from the ns2 movement trace file.
@@ -38,15 +38,15 @@
  *
  * Usage of ns2-mobility-trace:
  *
- *          ./waf --run "examples/mobility/ns2-mobility-trace \
- *                --traceFile=/home/mgiachino/ns-3-dev/examples/mobility/default.ns_movements
- *                 --nodeNum=2  --duration=100.0 --logFile=ns2-mobility-trace.log"
+ *  ./waf --run "ns2-mobility-trace \
+ *        --traceFile=src/mobility/examples/default.ns_movements
+ *        --nodeNum=2  --duration=100.0 --logFile=ns2-mobility-trace.log"
  *
- *          NOTE: ns2-traces-file could be an absolute or relative path. You could use the file default.ns_movements
- *                included in the same directory that the present file.
- *          NOTE 2: Number of nodes present in the trace file must match with the command line argument.
- *                  Note that you must know it before to be able to load it.
- *          NOTE 3: Duration must be a positive number. Note that you must know it before to be able to load it.
+ *  NOTE: ns2-traces-file could be an absolute or relative path. You could use the file default.ns_movements
+ *        included in the same directory that the present file.
+ *  NOTE 2: Number of nodes present in the trace file must match with the command line argument.
+ *          Note that you must know it before to be able to load it.
+ *  NOTE 3: Duration must be a positive number. Note that you must know it before to be able to load it.
  */
 
 
@@ -99,10 +99,10 @@
     {
       std::cout << "Usage of " << argv[0] << " :\n\n"
       "./waf --run \"ns2-mobility-trace"
-      " --traceFile=/home/mgiachino/ns-3-dev/examples/mobility/default.ns_movements"
-      " --nodeNum=2 --duration=100.0 --logFile=main-ns2-mob.log\" \n\n"
+      " --traceFile=src/mobility/examples/default.ns_movements"
+      " --nodeNum=2 --duration=100.0 --logFile=ns2-mob.log\" \n\n"
       "NOTE: ns2-traces-file could be an absolute or relative path. You could use the file default.ns_movements\n"
-      "      included in the same directory that the present file.\n\n"
+      "      included in the same directory of this example file.\n\n"
       "NOTE 2: Number of nodes present in the trace file must match with the command line argument and must\n"
       "        be a positive number. Note that you must know it before to be able to load it.\n\n"
       "NOTE 3: Duration must be a positive number. Note that you must know it before to be able to load it.\n\n";
@@ -117,8 +117,6 @@
   std::ofstream os;
   os.open (logFile.c_str ());
 
-
-
   // Create all nodes.
   NodeContainer stas;
   stas.Create (nodeNum);