From b0fd4d2e2aed73b50eb296142a1cf6fe49853c17 Mon Sep 17 00:00:00 2001
From: Tommaso Pecorella <tommaso.pecorella@unifi.it>
Date: Sun, 6 Nov 2011 17:46:16 +0100
Subject: [PATCH] Topology reader docs fixings

---
 doc/models/source/index.rst                   |  1 +
 src/topology-read/doc/topology.h              | 18 +-------
 src/topology-read/doc/topology.rst            | 45 +++++++++++++++++++
 .../helper/topology-reader-helper.h           |  2 +
 .../model/inet-topology-reader.h              |  3 +-
 .../model/orbis-topology-reader.h             |  3 +-
 .../model/rocketfuel-topology-reader.h        |  3 +-
 src/topology-read/model/topology-reader.h     | 12 +++++
 8 files changed, 67 insertions(+), 20 deletions(-)
 create mode 100644 src/topology-read/doc/topology.rst

diff --git a/doc/models/source/index.rst b/doc/models/source/index.rst
index 1e34722ba..fa7dd59c3 100644
--- a/doc/models/source/index.rst
+++ b/doc/models/source/index.rst
@@ -38,6 +38,7 @@ This document is written in `reStructuredText <http://docutils.sourceforge.net/r
    propagation
    simple
    statistics
+   topology
    uan
    wifi
    wimax
diff --git a/src/topology-read/doc/topology.h b/src/topology-read/doc/topology.h
index a0b74de1d..e8960dcf8 100644
--- a/src/topology-read/doc/topology.h
+++ b/src/topology-read/doc/topology.h
@@ -16,23 +16,7 @@
  * - ns3::InetTopologyReader for Inet 3.0 traces (http://topology.eecs.umich.edu/inet/)
  * - ns3::RocketfuelTopologyReader for Rocketfuel traces (http://www.cs.washington.edu/research/networking/rocketfuel/)
  *
- * An helper ns3::TopologyReaderHelper is provided to assist on trivial tasks.
- *
- * A good source for topology data is also Archipelago (http://www.caida.org/projects/ark/)
- *
- * The current Archipelago Measurements, monthly updated, are stored here:
- * http://data.caida.org/datasets/topology/ipv4.allpref24-aslinks/
- * (complete notation and triple data source, one for each working group)
- *
- * A different and more compact notation that signs only the AS-relationships is here:
- * http://www.caida.org/data/active/as-relationships/index.xml
- * (a sort of more Orbis-like format)
- *
- * The compact notation can be easily stripped down to a pure Orbis format, just removing
- * the double relationships (the compact format use one-way links, while Orbis use two-way
- * links) and pruning the 3rd parameter. Note that with the compact data Orbis can then be
- * used create a rescaled version of the topology, thus being the most effective way
- * (to my best knowledge) to make an internet-like topology.
+ * See the ns-3 modules manual for further informations.
  *
  * Examples can be found in the directory src/topology-read/examples/
  */
diff --git a/src/topology-read/doc/topology.rst b/src/topology-read/doc/topology.rst
new file mode 100644
index 000000000..5adebab0b
--- /dev/null
+++ b/src/topology-read/doc/topology.rst
@@ -0,0 +1,45 @@
+.. include:: replace.txt
+
+Topology Input Readers
+----------------------
+
+The topology modules aim at reading a topology file generated by an automatic topology generator.
+ 
+The process is divided in two steps:
+
+- running a topology generator to build a topology file
+- reading the topology file and build a ns-3 simulation
+ 
+Hence, model is focused on being able to read correctly the various topology formats.
+ 
+Currently there are three models:
+
+* ``ns3::OrbisTopologyReader`` for Orbis_ 0.7 traces 
+* ``ns3::InetTopologyReader`` for Inet_ 3.0 traces 
+* ``ns3::RocketfuelTopologyReader`` for Rocketfuel_ traces 
+ 
+An helper ``ns3::TopologyReaderHelper`` is provided to assist on trivial tasks.
+ 
+A good source for topology data is also Archipelago_.
+
+The current Archipelago Measurements_, monthly updated, are stored in the CAIDA website using 
+a complete notation and triple data source, one for each working group. 
+
+A different and more compact notation reporting only the AS-relationships (a sort of more 
+Orbis-like format) is here: as-relationships_.
+
+The compact notation can be easily stripped down to a pure Orbis format, just removing
+the double relationships (the compact format use one-way links, while Orbis use two-way
+links) and pruning the 3rd parameter. Note that with the compact data Orbis can then be
+used create a rescaled version of the topology, thus being the most effective way
+(to my best knowledge) to make an internet-like topology.
+
+Examples can be found in the directory ``src/topology-read/examples/``
+
+.. _Orbis: http://sysnet.ucsd.edu/~pmahadevan/topo_research/topo.html
+.. _Inet: http://topology.eecs.umich.edu/inet/
+.. _RocketFuel: http://www.cs.washington.edu/research/networking/rocketfuel/
+.. _Archipelago: http://www.caida.org/projects/ark/
+.. _Measurements: http://data.caida.org/datasets/topology/ipv4.allpref24-aslinks/
+.. _as-relationships: http://www.caida.org/data/active/as-relationships/index.xml
+
diff --git a/src/topology-read/helper/topology-reader-helper.h b/src/topology-read/helper/topology-reader-helper.h
index fd9d42ad7..c4bfbbee0 100644
--- a/src/topology-read/helper/topology-reader-helper.h
+++ b/src/topology-read/helper/topology-reader-helper.h
@@ -28,6 +28,8 @@
 namespace ns3 {
 
 /**
+ * \ingroup topology
+ *
  * \brief Helper class which makes it easier to configure and use a generic TopologyReader.
  */
 class TopologyReaderHelper
diff --git a/src/topology-read/model/inet-topology-reader.h b/src/topology-read/model/inet-topology-reader.h
index 3c7613ba3..31aa4a018 100644
--- a/src/topology-read/model/inet-topology-reader.h
+++ b/src/topology-read/model/inet-topology-reader.h
@@ -23,7 +23,6 @@
 #define INET_TOPOLOGY_READER_H
 
 #include "ns3/nstime.h"
-
 #include "topology-reader.h"
 
 namespace ns3 {
@@ -32,6 +31,8 @@ namespace ns3 {
 // ------------------------------------------------------------
 // --------------------------------------------
 /**
+ * \ingroup topology
+ *
  * \brief Topology file reader (Inet-format type).
  *
  * This class takes an input file in Inet format and extracts all
diff --git a/src/topology-read/model/orbis-topology-reader.h b/src/topology-read/model/orbis-topology-reader.h
index 50faf8f90..21b32cfc8 100644
--- a/src/topology-read/model/orbis-topology-reader.h
+++ b/src/topology-read/model/orbis-topology-reader.h
@@ -23,7 +23,6 @@
 #define ORBIS_TOPOLOGY_READER_H
 
 #include "ns3/nstime.h"
-
 #include "topology-reader.h"
 
 namespace ns3 {
@@ -32,6 +31,8 @@ namespace ns3 {
 // ------------------------------------------------------------
 // --------------------------------------------
 /**
+ * \ingroup topology
+ *
  * \brief Topology file reader (Orbis-format type).
  *
  * This class takes an input file in Orbis format and extracts all
diff --git a/src/topology-read/model/rocketfuel-topology-reader.h b/src/topology-read/model/rocketfuel-topology-reader.h
index c43716ba0..afb667db3 100644
--- a/src/topology-read/model/rocketfuel-topology-reader.h
+++ b/src/topology-read/model/rocketfuel-topology-reader.h
@@ -22,7 +22,6 @@
 #define ROCKETFUEL_TOPOLOGY_READER_H
 
 #include "ns3/nstime.h"
-
 #include "topology-reader.h"
 
 namespace ns3 {
@@ -31,6 +30,8 @@ namespace ns3 {
 // ------------------------------------------------------------
 // --------------------------------------------
 /**
+ * \ingroup topology
+ *
  * \brief Topology file reader (Rocketfuel-format type).
  *
  * http://www.cs.washington.edu/research/networking/rocketfuel/
diff --git a/src/topology-read/model/topology-reader.h b/src/topology-read/model/topology-reader.h
index 3b08968fc..47648902d 100644
--- a/src/topology-read/model/topology-reader.h
+++ b/src/topology-read/model/topology-reader.h
@@ -33,6 +33,8 @@
 namespace ns3 {
 
 /**
+ * \ingroup topology
+ *
  * \brief Interface for input file readers management.
  *
  * This interface perform the shared tasks among all possible input file readers.
@@ -52,8 +54,18 @@ public:
   class Link
   {
 public:
+  /**
+   * \brief Constant iterator to scan the map of link attributes.
+   */
     typedef std::map<std::string, std::string >::const_iterator ConstAttributesIterator;
 
+    /**
+     * \brief Constructor
+     * \param fromPtr Ptr to the node the link is orginating from
+     * \param fromName name of the node the link is orginating from
+     * \param toPtr Ptr to the node the link is directed to
+     * \param toName name of the node the link is directed to
+     */
     Link ( Ptr<Node> fromPtr, std::string fromName, Ptr<Node> toPtr, std::string toName );
 
     /**