From 59d0575864b29eca5b1fa387259e8f7af66cf78c Mon Sep 17 00:00:00 2001
From: Tom Henderson <tomh@tomh.org>
Date: Tue, 24 May 2011 20:54:20 -0700
Subject: [PATCH] Move aodv module description out of doxygen

---
 doc/models/Makefile         |   1 +
 doc/models/source/index.rst |   1 +
 src/aodv/doc/aodv.h         |  49 +------------
 src/aodv/doc/aodv.rst       | 134 ++++++++++++++++++++++++++++++++++++
 4 files changed, 137 insertions(+), 48 deletions(-)
 create mode 100644 src/aodv/doc/aodv.rst

diff --git a/doc/models/Makefile b/doc/models/Makefile
index 66787911c..54db973fb 100644
--- a/doc/models/Makefile
+++ b/doc/models/Makefile
@@ -20,6 +20,7 @@ SOURCES = \
 	source/routing.rst \
 	source/emulation-overview.rst \
 	source/support.rst \
+	$(SRC)/aodv/doc/aodv.rst \
 	$(SRC)/applications/doc/applications.rst \
 	$(SRC)/bridge/doc/bridge.rst \
 	$(SRC)/click/doc/click.rst \
diff --git a/doc/models/source/index.rst b/doc/models/source/index.rst
index 4acd718aa..a83257b52 100644
--- a/doc/models/source/index.rst
+++ b/doc/models/source/index.rst
@@ -20,6 +20,7 @@ This document is written in `reStructuredText <http://docutils.sourceforge.net/r
 
    organization
    animation
+   aodv
    applications
    bridge
    click
diff --git a/src/aodv/doc/aodv.h b/src/aodv/doc/aodv.h
index 37853a9ca..9aebb6cbc 100644
--- a/src/aodv/doc/aodv.h
+++ b/src/aodv/doc/aodv.h
@@ -31,55 +31,8 @@
 
 /**
  * \defgroup aodv AODV Routing
- * 
- * This model implements the base specification of the Ad hoc on demand distance vector (AODV)
- * protocol. Implementation is based on RFC3561.
- *
- * Class aodv::RoutingProtocol implements all functionality of service packet exchange and inherits Ipv4RoutingProtocol. 
- * Base class defines two virtual functions for packet routing and forwarding.  The first one,
- * RouteOutput(), is used for locally originated packets, and the second one, RouteInput(), is used for forwarding
- * and/or delivering received packets.
- *
- * Protocol operation depends on the many adjustable parameters. Parameters for this functionality are attributes of
- * aodv::RoutingProtocol. We support parameters, with their default values, from RFC and parameters that enable/disable
- * protocol features, such as broadcasting HELLO messages, broadcasting data packets and so on.
- *
- * AODV discovers routes on demand. Therefore, our AODV model  buffer all packets, while a route request packet (RREQ)
- * is disseminated. We implement a packet queue in aodv-rqueue.cc. Smart pointer to packet, Ipv4RoutingProtocol::ErrorCallback,
- * Ipv4RoutingProtocol::UnicastForwardCallback and IP header are stored in this queue. The packet queue implements garbage collection of old
- * packets and a queue size limit.
- *
- * Routing table implementation support garbage collection of old entries and state machine, defined in standard.
- * It implements as a STL map container. The key is a destination IP address.
- *
- * Some moments of protocol operation aren't described in RFC. This moments generally concern cooperation of different OSI model layers.
- * We use following heuristics:
- * 
- * 1) This AODV implementation can detect the presence of unidirectional links and avoid them if necessary.
- *    If the node we received a RREQ for is a neighbor we are probably facing a unidirectional link... 
- *    This heuristic is taken from AODV-UU implementation and can be disabled.
- *    
- * 2) Protocol operation strongly depends on broken link detection mechanism. We implements two such heuristics.
- *    First, this implementation support  HELLO messages. However HELLO messages are not a good way to do neighbor sensing
- *    in a wireless environment (at least not over 802.11). Therefore, you may experience bad performance when running over wireless.
- *    There are several reasons for this:
- *      -# HELLO messages are broadcasted. In 802.11, broadcasting is done at a lower bit rate than unicasting,
- *         thus HELLO messages travel further than data.
- *      -# HELLO messages are small, thus less prone to bit errors than data transmissions.
- *      -# Broadcast transmissions are not guaranteed to be bidirectional, unlike unicast transmissions.
- *    Second, we use layer 2 feedback when possible. Link considered to be broken, if frame transmission results in a transmission 
- *    failure for all retries. This mechanism meant for active links and work much more faster, than first method.
- *    Layer 2 feedback implementation relies on TxErrHeader trace source, currently it is supported in AdhocWifiMac only.
- *    
- * 3) Duplicate packet detection. We use special class DuplicatePacketDetection for this purpose.
- *
- * Following optional protocol optimizations aren't implemented:
- *  - Expanding ring search.
- *  - Local link repair.
- *  - RREP, RREQ and HELLO message extensions.
- * This techniques require direct access to IP header, which contradict assertion from AODV RFC that AODV works over UDP. Our model use UDP
- * for simplicity, but this disable us to implement protocol optimizations. We don't use low layer raw socket, because they are not portable.
  *
+ * This section documents the API of the ns-3 AODV module. For a generic functional description, please refer to the ns-3 manual.
  */
 
 #endif /* AODV_H */
diff --git a/src/aodv/doc/aodv.rst b/src/aodv/doc/aodv.rst
new file mode 100644
index 000000000..920a7304e
--- /dev/null
+++ b/src/aodv/doc/aodv.rst
@@ -0,0 +1,134 @@
+.. include:: replace.txt
+
+Ad Hoc On-Demand Distance Vector (AODV)
+---------------------------------------
+
+This model implements the base specification of the Ad Hoc On-Demand 
+Distance Vector (AODV) protocol. The implementation is based on 
+[rfc3561]_.
+
+The model was written by Elena Buchatskaia and Pavel Boyko of ITTP RAS,
+and is based on the ns-2 AODV model developed by the CMU/MONARCH group
+and optimized and tuned by Samir Das and Mahesh Marina, University of
+Cincinnati, and also on the AODV-UU implementation by Erik Nordström of 
+Uppsala University.
+
+Model Description
+*****************
+
+The source code for the AODV model lives in the directory `src/aodv`.
+
+Design
+++++++
+
+Class ``ns3::aodv::RoutingProtocol`` implements all functionality of 
+service packet exchange and inherits from ``ns3::Ipv4RoutingProtocol``.
+The base class defines two virtual functions for packet routing and 
+forwarding.  The first one, ``ns3::aodv::RouteOutput``, is used for 
+locally originated packets, and the second one, ``ns3::aodv::RouteInput``,
+is used for forwarding and/or delivering received packets.
+
+Protocol operation depends on many adjustable parameters. Parameters for 
+this functionality are attributes of ``ns3::aodv::RoutingProtocol``. 
+Parameter default values are drawn from the RFC and allow the 
+enabling/disabling protocol features, such as broadcasting HELLO messages, 
+broadcasting data packets and so on.
+
+AODV discovers routes on demand.  Therefore, the AODV model buffers all 
+packets while a route request packet (RREQ) is disseminated. 
+A packet queue is implemented in aodv-rqueue.cc. A smart pointer to 
+the packet, ``ns3::Ipv4RoutingProtocol::ErrorCallback``,
+``ns3::Ipv4RoutingProtocol::UnicastForwardCallback``, and the IP header 
+are stored in this queue. The packet queue implements garbage collection 
+of old packets and a queue size limit.
+
+The routing table implementation supports garbage collection of 
+old entries and state machine, defined in the standard.
+It is implemented as a STL map container. The key is a destination IP address.
+
+Some elements of protocol operation aren't described in the RFC. These 
+elements generally concern cooperation of different OSI model layers.
+The model uses the following heuristics:
+
+#. This AODV implementation can detect the presence of unidirectional 
+links and avoid them if necessary.  If the node the model receives an
+RREQ for is a neighbor, the cause may be a unidirectional link.
+This heuristic is taken from AODV-UU implementation and can be disabled.
+
+#. Protocol operation strongly depends on broken link detection mechanism. 
+The model implements two such heuristics.  First, this implementation 
+support HELLO messages. However HELLO messages are not a good way to 
+perform neighbor sensing in a wireless environment (at least not over 
+802.11). Therefore, one may experience bad performance when running over 
+wireless.  There are several reasons for this:
+##. HELLO messages are broadcasted. In 802.11, broadcasting is often done at a 
+lower bit rate than unicasting, thus HELLO messages can travel further 
+than unicast data.
+##. HELLO messages are small, thus less prone to bit errors than 
+data transmissions.
+##. Broadcast transmissions are not guaranteed to be bidirectional, 
+unlike unicast transmissions.  
+Second, we use layer 2 feedback when possible. Link are considered to be 
+broken if frame transmission results in a transmission failure for all 
+retries. This mechanism is meant for active links and works faster than
+the first method.
+
+The layer 2 feedback implementation relies on the ``TxErrHeader`` trace source, 
+currently supported in AdhocWifiMac only.
+
+Scope and Limitations
++++++++++++++++++++++
+
+The model is for IPv4 only.  The following optional protocol optimizations 
+are not implemented:
+#. Expanding ring search.
+#. Local link repair.
+#. RREP, RREQ and HELLO message extensions.
+
+These techniques require direct access to IP header, which contradicts
+the assertion from the AODV RFC that AODV works over UDP.  This model uses
+UDP for simplicity, hindering the ability to implement certain protocol 
+optimizations. The model doesn't use low layer raw sockets because they 
+are not portable.
+
+Future Work
++++++++++++
+
+No announced plans.
+
+References
+++++++++++
+
+
+.. [rfc3561] RFC 3561 *Ad hoc On-Demand Distance Vector (AODV) Routing*
+
+Usage
+*****
+
+Examples
+++++++++
+
+Helpers
++++++++
+
+Attributes
+++++++++++
+
+Tracing
++++++++
+
+Logging
++++++++
+
+Caveats
++++++++
+
+Validation
+**********
+
+Unit tests
+++++++++++
+
+Larger-scale performance tests
+++++++++++++++++++++++++++++++
+