--- a/doc/doxygen.conf Fri Jan 11 08:31:38 2008 -0800
+++ b/doc/doxygen.conf Thu Jan 10 07:31:40 2008 -0800
@@ -493,10 +493,12 @@
# 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
--- /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
+
+*/
--- /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
+
+*/
+
--- /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.
+ */
+
--- a/doc/main.txt Fri Jan 11 08:31:38 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
- */
--- /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
+ */
+
--- a/doc/tracing.h Fri Jan 11 08:31:38 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
--- a/src/common/packet.h Fri Jan 11 08:31:38 2008 -0800
+++ b/src/common/packet.h Thu Jan 10 07:31:40 2008 -0800
@@ -362,6 +362,7 @@
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
--- a/src/core/assert.h Fri Jan 11 08:31:38 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
*
--- a/src/core/callback.h Fri Jan 11 08:31:38 2008 -0800
+++ b/src/core/callback.h Thu Jan 10 07:31:40 2008 -0800
@@ -362,6 +362,7 @@
};
/**
+ * \ingroup core
* \defgroup MakeCallback MakeCallback
*
*/
--- a/src/core/default-value.h Fri Jan 11 08:31:38 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
*
*/
--- a/src/core/fatal-error.h Fri Jan 11 08:31:38 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
*
--- a/src/core/log.h Fri Jan 11 08:31:38 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
*
--- a/src/core/random-variable.h Fri Jan 11 08:31:38 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
*
*/
--- a/src/devices/wifi/wifi.h Fri Jan 11 08:31:38 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
--- a/src/internet-node/internet-node.h Fri Jan 11 08:31:38 2008 -0800
+++ b/src/internet-node/internet-node.h Thu Jan 10 07:31:40 2008 -0800
@@ -32,7 +32,7 @@
namespace ns3 {
/**
- * \defgroup InternetNode InternetNode
+ * \ingroup internetNode
*
* \section InternetNode Overview
*
--- a/src/mobility/mobility.h Fri Jan 11 08:31:38 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
--- a/utils/print-introspected-doxygen.cc Fri Jan 11 08:31:38 2008 -0800
+++ b/utils/print-introspected-doxygen.cc Thu Jan 10 07:31:40 2008 -0800
@@ -99,6 +99,7 @@
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 ();