# HG changeset patch
# User Tom Henderson <tomh@tomh.org>
# Date 1199979100 28800
# Node ID 7d9ac47160040d2228ffd907093bbeb9fb5ed053
# Parent  9dda69de4ca79365e62028150460da7d2d3253a3
Doxygen reorg proposal

diff -r 9dda69de4ca7 -r 7d9ac4716004 doc/doxygen.conf
--- a/doc/doxygen.conf	Wed Jan 09 22:17:02 2008 -0800
+++ b/doc/doxygen.conf	Thu Jan 10 07:31:40 2008 -0800
@@ -493,10 +493,12 @@ WARN_LOGFILE           =
 # directories like "/usr/src/myproject". Separate the files or directories 
 # with spaces.
 
-INPUT                  = src \
-                         doc/main.txt \
+INPUT                  = doc/modules \
+                         doc/main.h \
                          doc/introspected-doxygen.h \
-                         doc/tracing.h 
+                         doc/tracing.h \ 
+                         doc/howtos/ \ 
+                         src
 
 # This tag can be used to specify the character encoding of the source files that 
 # doxygen parses. Internally doxygen uses the UTF-8 encoding, which is also the default 
diff -r 9dda69de4ca7 -r 7d9ac4716004 doc/howtos/howtos-callbacks.h
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/howtos/howtos-callbacks.h	Thu Jan 10 07:31:40 2008 -0800
@@ -0,0 +1,38 @@
+/*!
+\page callbacks Using ns-3 callbacks
+\anchor howtos-callbacks
+
+\section null_callbacks Null Callbacks
+
+<b>Question:</b> The API I am using calls for using a callback (in the 
+function signature), but I do not
+want to provide one.  Is there a way to provide a null callback?
+
+<b>Answer:</b> Use the ns3::MakeNullCallback construct:
+\code
+template<typename R>
+Callback< R, T1, T2, T3, T4, T5, T6 > ns3::MakeNullCallback (void)
+\endcode
+
+Example usage:  The ns3::Socket class uses callbacks to indicate completion
+of events such as a successful TCP connect().  These callbacks are set
+in the following function:
+\code
+  void Socket::SetConnectCallback (Callback<void, Ptr<Socket> > connectionSucceeded,
+                        Callback<void, Ptr<Socket> > connectionFailed,
+                        Callback<void, Ptr<Socket> > halfClose);
+
+\endcode
+But suppose you do not care about registering a callback for the 
+halfClose event (but you want to register one for the 
+connectionSucceeded and connectionFailed cases).  In that case, you
+can pass a null callback as the third argument.  You just need to
+pass a callback with the matching signature, as follows:
+\code
+  localSocket->SetConnectCallback (
+  MakeCallback (&ConnectionSucceededCallback),
+  MakeCallback (&ConnectionFailedCallback),
+  MakeNullCallback<void, Ptr<Socket> > () );
+\endcode
+
+*/
diff -r 9dda69de4ca7 -r 7d9ac4716004 doc/howtos/howtos.h
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/howtos/howtos.h	Thu Jan 10 07:31:40 2008 -0800
@@ -0,0 +1,17 @@
+/*!
+\page howtos ns-3 HOWTOs
+\anchor howtos-anchor
+
+This is an organized set of frequently asked questions (FAQ) and HOWTOs
+for ns-3.  This complements the following wiki pages:
+
+- <a href="http://www.nsnam.org/wiki/index.php/User_FAQ">User FAQ</a>
+- <a href="http://www.nsnam.org/wiki/index.php/Developer_FAQ">Developer FAQ</a>
+
+Please consider contributing tips to either the wiki (yourself) or
+by submitting a patch to this maintained documentation.
+
+- \subpage callbacks
+
+*/
+
diff -r 9dda69de4ca7 -r 7d9ac4716004 doc/main.h
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/main.h	Thu Jan 10 07:31:40 2008 -0800
@@ -0,0 +1,61 @@
+/**
+ * \mainpage ns-3 Documentation
+ *
+ * \section intro-sec Introduction
+ * <a href="http://www.nsnam.org/">ns-3</a> documentation is maintained using 
+ * <a href="http://www.doxygen.org">Doxygen</a>.
+ * Doxygen is typically used for 
+ * API documentation, and organizes such documentation across different
+ * modules.   This project uses Doxygen both for building the manual around 
+ * the API documentation,  and a separate GNU texinfo document is used for 
+ * the manual.
+ *
+ * The ns-3 project documentation is organized as follows:
+ *     - <b><a href="modules.html">modules</a></b>:  The "Modules" tab (above) 
+ *       organizes  all of the public API and supporting manual text 
+ *       along the  source code directory structure.   This forms the 
+ *       "ns-3 manual", and it is available in HTML and PDF forms.
+ *     - \ref howtos-anchor "HOWTOs": A set of HOWTOs and FAQs is
+ *       maintained on another Doxygen "Related Page" 
+ *     - <a href="http://www.nsnam.org/docs/tutorial/tutorial.html">tutorial</a>:  The ns-3 tutorial is a separate document maintained in <a href="http://www.gnu.org/software/texinfo/"> GNU Texinfo</a>. 
+ *     - The <b><a href="http://www.nsnam.org/wiki/index.php/Main_Page">ns-3 wiki</a></b> 
+ *       contains additional user-contributed material.  Some wiki-contributed
+ *       material may migrate to and overlap with the Doxygen information.
+ *
+ * \section install-sec Building the Documentation
+ * 
+ * ns-3 requires Doxygen version 1.5.4 or greater to fully build all items,
+ * although earlier versions of Doxygen will mostly work.
+ * 
+ * Type "./waf check" followed by "./waf --doxygen" to build the documentation.
+ * There is a program that runs during "./waf check" that builds pieces of
+ * the documentation through introspection.  The doc/ directory contains
+ * configuration for Doxygen (doxygen.conf and main.txt).  The Doxygen 
+ * build process puts html files into the doc/html/ directory, and latex 
+ * filex into the doc/latex/ directory.
+ * 
+ * \section module-sec Module overview
+ *
+ * The ns-3 library is split across multiple modules:
+ *     - core: located in src/core and contains a number of facilities which
+ *       do not depend on any other module. Some of these facilities are
+ *       OS-dependent.
+ *     - simulator: located in src/simulator and contains event scheduling
+ *       facilities.
+ *     - common: located in src/common and contains facilities specific
+ *       to network simulations but shared by pretty much every model
+ *       of a network component.
+ *     - node: located in src/node. Defines the abstract interfaces which 
+ *       must be implemented by every node and more specifically, by ipv4 nodes.       
+ *     - devices: located in src/devices. Contains a set of MAC-level models
+ *
+ * More detail can be found in the <b><a href="modules.html">Modules</a></b>
+ * tab.
+ *
+ */
+/**
+ * \namespace ns3
+ * \brief Every class exported by the ns3 library is enclosed in the
+ * ns3 namespace.
+ */
+
diff -r 9dda69de4ca7 -r 7d9ac4716004 doc/main.txt
--- a/doc/main.txt	Wed Jan 09 22:17:02 2008 -0800
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,68 +0,0 @@
-/**
- * \mainpage An Introduction to ns-3
- *
- * The ns-3 library is split across multiple modules:
- *     - core: located in src/core and contains a number of facilities which
- *       do not depend on any other module. Some of these facilities are
- *       OS-dependent.
- *     - simulator: located in src/simulator and contains event scheduling
- *       facilities.
- *     - common: located in src/common and contains facilities specific
- *       to network simulations but shared by pretty much every model
- *       of a network component.
- *     - node: located in src/node. Defines the abstract interfaces which 
- *       must be implemented by every node and more specifically, by ipv4 nodes.       
- *     - devices: located in src/devices. Contains a set of MAC-level models
- *
- * The "core" module contains:
- *    - a Functor class: ns3::Callback
- *    - an os-independent interface to get access to the elapsed wall clock time: ns3::SystemWallClockMs
- *    - a class to register regression tests with the test manager: ns3::Test and ns3::TestManager
- *    - debugging facilities: \ref logging, \ref assert, \ref error
- *    - \ref randomvariable
- *    - \ref config
- *    - a base class for objects which need to support reference counting 
- *      and QueryInterface: ns3::Object and ns3::InterfaceId
- *    - a set of low-level trace facilities integrated in the ns3::Object system: \ref tracing
- *    - a ns3::ComponentManager which can be used to manage the creation
- *      of any object which derives from ns3::Object through an ns3::ClassId
- *    - a smart-pointer class ns3::Ptr designed to work together with ns3::Object
- *
- * The "simulator" module contains:
- *    - a time management class to hold a time and convert between various time units: ns3::Time
- *    - a scheduler base class used to implement new simulation event schedulers: 
- *      ns3::Scheduler and ns3::SchedulerFactory
- *    - a simulator class used to create, schedule and cancel events: ns3::Simulator
- *
- * The "core" module contains:
- *    - a packet class to create and manipulate simulation packets: ns3::Packet, ns3::Header, 
- *      and ns3::Trailer. This packet class also supports per-packet ns3::Tag which are
- *      globs of data which can be attached to any packet.
- *
- * The "node" module contains:
- *    - a ns3::Node base class which should be subclassed by any new type of
- *      network Node.
- *    - models which abstract the MAC-layer from the IP layer protocols:
- *      ns3::NetDevice and ns3::Channel.
- *    - models which abstract the application-layer API: ns3::Application,
- *      ns3::Socket, ns3::SocketFactory, and, ns3::Udp
- *
- * The "internet-node" module contains a set of classes which implement the
- * APIs defined in the "node" module:
- *    - an Ipv4/Udp stack with socket support
- *    - an ARP module
- *    - an InternetNode class which is a Node subclass. 
- *
- * The "devices" module contains:
- *    - a PointToPoint MAC device: ns3::PointToPointNetDevice, ns3::PointToPointChannel,
- *      and ns3::PointToPointTopology.
- */
-/**
- * \namespace ns3
- * \brief Every class exported by the ns3 library is enclosed in the
- * ns3 namespace.
- */
-/**
- * \defgroup constants Constants
- * \brief Constants you can change
- */
diff -r 9dda69de4ca7 -r 7d9ac4716004 doc/modules
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/modules	Thu Jan 10 07:31:40 2008 -0800
@@ -0,0 +1,67 @@
+/**
+ * @anchor modules_anchor
+ *
+ * @defgroup simulator Simulator
+ * The "simulator" module contains: 
+ *    - a time management class to hold a time and convert between various time units: ns3::Time 
+ *    - a scheduler base class used to implement new simulation event schedulers:       
+ *      ns3::Scheduler and ns3::SchedulerFactory 
+ *    - a simulator class used to create, schedule and cancel events: ns3::Simulator
+ *
+ * @defgroup core Core
+ * \brief The "core" module contains:
+ *    - a Functor class: ns3::Callback  
+ *    - an os-independent interface to get access to the elapsed wall clock time: ns3::SystemWallClockMs 
+ *    - a class to register regression tests with the test manager: ns3::Test and ns3::TestManager
+ *    - debugging facilities: \ref logging, \ref assert, \ref error
+ *    - \ref randomvariable
+ *    - \ref config
+ *    - a base class for objects which need to support reference counting
+ *      and QueryInterface: ns3::Object and ns3::InterfaceId 
+ *    - a set of low-level trace facilities integrated in the ns3::Object system: \ref tracing
+ *    - a ns3::ComponentManager which can be used to manage the creation
+ *      of any object which derives from ns3::Object through an ns3::ClassId 
+ *    - a smart-pointer class ns3::Ptr designed to work together with ns3::Object
+ *
+ * @defgroup common Common
+ * The "core" module contains: 
+ *    - a packet class to create and manipulate simulation packets: 
+ *      ns3::Packet, ns3::Header,  and ns3::Trailer. This packet class 
+ *      also supports per-packet ns3::Tag which are  globs of data 
+ *      which can be attached to any packet.
+ *
+ * @defgroup node Node
+ * The "node" module contains:
+ *    - a ns3::Node base class which should be subclassed by any new type of
+ *      network Node.
+ *    - models which abstract the MAC-layer from the IP layer protocols:
+ *      ns3::NetDevice and ns3::Channel. 
+ *    - models which abstract the application-layer API: ns3::Application,
+ *      ns3::Socket, ns3::SocketFactory, and, ns3::Udp
+ * 
+ *
+ * @defgroup devices Devices
+ * The "devices" module contains:
+ *    - a PointToPoint MAC device: ns3::PointToPointNetDevice, ns3::PointToPointChannel,
+ *      and ns3::PointToPointTopology.
+ *
+ * @defgroup internetNode InternetNode
+ * 
+ * The "internet-node" module contains a set of classes which implement the
+ * APIs defined in the "node" module:
+ *    - an Ipv4/Udp stack with socket support 
+ *    - an ARP module
+ *    - an InternetNode class which is a Node subclass.
+ *    
+ * @defgroup applications Applications
+ *
+ * @defgroup mobility Mobility
+ *
+ * @defgroup routing Routing
+ *
+ * @defgroup constants Constants
+ * @brief Constants you can change
+ *
+ * @defgroup contrib Contrib
+ */
+
diff -r 9dda69de4ca7 -r 7d9ac4716004 doc/tracing.h
--- a/doc/tracing.h	Wed Jan 09 22:17:02 2008 -0800
+++ b/doc/tracing.h	Thu Jan 10 07:31:40 2008 -0800
@@ -1,8 +1,10 @@
 /**
+ * \ingroup core
  * \defgroup TraceSourceList List of trace sources
  */
 
 /**
+ * \ingroup core
  * \defgroup tracing Tracing
  *
  * The flexibility of the ns-3 tracing system comes at the cost of quite
diff -r 9dda69de4ca7 -r 7d9ac4716004 src/common/packet.h
--- a/src/common/packet.h	Wed Jan 09 22:17:02 2008 -0800
+++ b/src/common/packet.h	Thu Jan 10 07:31:40 2008 -0800
@@ -362,6 +362,7 @@ std::ostream& operator<< (std::ostream& 
 std::ostream& operator<< (std::ostream& os, const Packet &packet);
 
 /**
+ * \ingroup common
  * \defgroup packetperf Packet Performance
  * The current implementation of the byte buffers and tag list is based
  * on COW (Copy On Write. An introduction to COW can be found in Scott 
diff -r 9dda69de4ca7 -r 7d9ac4716004 src/core/assert.h
--- a/src/core/assert.h	Wed Jan 09 22:17:02 2008 -0800
+++ b/src/core/assert.h	Thu Jan 10 07:31:40 2008 -0800
@@ -28,6 +28,7 @@
 #include "breakpoint.h"
 
 /**
+ * \ingroup core
  * \defgroup assert Assert
  * \brief assert functions and macros
  *
diff -r 9dda69de4ca7 -r 7d9ac4716004 src/core/callback.h
--- a/src/core/callback.h	Wed Jan 09 22:17:02 2008 -0800
+++ b/src/core/callback.h	Thu Jan 10 07:31:40 2008 -0800
@@ -362,6 +362,7 @@ private:
 };
 
 /**
+ * \ingroup core
  * \defgroup MakeCallback MakeCallback
  *
  */
diff -r 9dda69de4ca7 -r 7d9ac4716004 src/core/default-value.h
--- a/src/core/default-value.h	Wed Jan 09 22:17:02 2008 -0800
+++ b/src/core/default-value.h	Thu Jan 10 07:31:40 2008 -0800
@@ -25,6 +25,7 @@
 #include "callback.h"
 
 /**
+ * \ingroup core
  * \defgroup config Simulation configuration
  *
  */
diff -r 9dda69de4ca7 -r 7d9ac4716004 src/core/fatal-error.h
--- a/src/core/fatal-error.h	Wed Jan 09 22:17:02 2008 -0800
+++ b/src/core/fatal-error.h	Thu Jan 10 07:31:40 2008 -0800
@@ -25,6 +25,7 @@
 #include <iostream>
 
 /**
+ * \ingroup core
  * \defgroup error Error
  * \brief fatal error handling
  *
diff -r 9dda69de4ca7 -r 7d9ac4716004 src/core/log.h
--- a/src/core/log.h	Wed Jan 09 22:17:02 2008 -0800
+++ b/src/core/log.h	Thu Jan 10 07:31:40 2008 -0800
@@ -25,6 +25,7 @@
 #include <iostream>
 
 /**
+ * \ingroup core
  * \defgroup logging Logging
  * \brief Logging functions and macros
  *
diff -r 9dda69de4ca7 -r 7d9ac4716004 src/core/random-variable.h
--- a/src/core/random-variable.h	Wed Jan 09 22:17:02 2008 -0800
+++ b/src/core/random-variable.h	Thu Jan 10 07:31:40 2008 -0800
@@ -26,6 +26,7 @@
 #include <stdint.h>
 
 /**
+ * \ingroup core
  * \defgroup randomvariable Random Variable Distributions
  *
  */
diff -r 9dda69de4ca7 -r 7d9ac4716004 src/devices/wifi/wifi.h
--- a/src/devices/wifi/wifi.h	Wed Jan 09 22:17:02 2008 -0800
+++ b/src/devices/wifi/wifi.h	Thu Jan 10 07:31:40 2008 -0800
@@ -1,4 +1,5 @@
 /**
+ * \ingroup devices
  * \defgroup Wifi Wifi Models
  *
  * \section Wifi Models
diff -r 9dda69de4ca7 -r 7d9ac4716004 src/internet-node/internet-node.h
--- a/src/internet-node/internet-node.h	Wed Jan 09 22:17:02 2008 -0800
+++ b/src/internet-node/internet-node.h	Thu Jan 10 07:31:40 2008 -0800
@@ -32,7 +32,7 @@ namespace ns3 {
 namespace ns3 {
 
 /**
- * \defgroup InternetNode InternetNode
+ * \ingroup internetNode
  *
  * \section InternetNode Overview
  *
diff -r 9dda69de4ca7 -r 7d9ac4716004 src/mobility/mobility.h
--- a/src/mobility/mobility.h	Wed Jan 09 22:17:02 2008 -0800
+++ b/src/mobility/mobility.h	Thu Jan 10 07:31:40 2008 -0800
@@ -1,5 +1,5 @@
 /**
- * \defgroup mobility Mobility
+ * \addtogroup mobility Mobility
  *
  * The mobility support includes:
  *  - a set of mobility models which are used to track and maintain
diff -r 9dda69de4ca7 -r 7d9ac4716004 utils/print-introspected-doxygen.cc
--- a/utils/print-introspected-doxygen.cc	Wed Jan 09 22:17:02 2008 -0800
+++ b/utils/print-introspected-doxygen.cc	Thu Jan 10 07:31:40 2008 -0800
@@ -99,6 +99,7 @@ PrintDefaultValuesDoxygen (std::ostream 
 PrintDefaultValuesDoxygen (std::ostream &os)
 {
   os << "/// \\page ListOfDefaultValues The list of default values" << std::endl;
+  os << "/// \\ingroup core" << std::endl;
   os << "/// \\defgroup ListOfDefaultValuesGroup The list of default values" << std::endl;
   os << "/// <ul>" << std::endl;
   for (DefaultValueList::Iterator i = DefaultValueList::Begin ();