Doxygen organization
authorTom Henderson <tomh@tomh.org>
Thu, 10 Jan 2008 07:31:40 -0800
changeset 22170b4567d545de
parent 2216 9c209295b0b1
child 2218 b4d3f2e3b09a
child 2253 dfa0f692e38a
child 2289 78d28adb5c7c
Doxygen organization
doc/doxygen.conf
doc/howtos/howtos-callbacks.h
doc/howtos/howtos.h
doc/main.h
doc/main.txt
doc/modules
doc/tracing.h
src/common/packet.h
src/core/assert.h
src/core/callback.h
src/core/default-value.h
src/core/fatal-error.h
src/core/log.h
src/core/random-variable.h
src/devices/wifi/wifi.h
src/internet-node/internet-node.h
src/mobility/mobility.h
utils/print-introspected-doxygen.cc
     1.1 --- a/doc/doxygen.conf	Fri Jan 11 08:31:38 2008 -0800
     1.2 +++ b/doc/doxygen.conf	Thu Jan 10 07:31:40 2008 -0800
     1.3 @@ -493,10 +493,12 @@
     1.4  # directories like "/usr/src/myproject". Separate the files or directories 
     1.5  # with spaces.
     1.6  
     1.7 -INPUT                  = src \
     1.8 -                         doc/main.txt \
     1.9 +INPUT                  = doc/modules \
    1.10 +                         doc/main.h \
    1.11                           doc/introspected-doxygen.h \
    1.12 -                         doc/tracing.h 
    1.13 +                         doc/tracing.h \ 
    1.14 +                         doc/howtos/ \ 
    1.15 +                         src
    1.16  
    1.17  # This tag can be used to specify the character encoding of the source files that 
    1.18  # doxygen parses. Internally doxygen uses the UTF-8 encoding, which is also the default 
     2.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     2.2 +++ b/doc/howtos/howtos-callbacks.h	Thu Jan 10 07:31:40 2008 -0800
     2.3 @@ -0,0 +1,38 @@
     2.4 +/*!
     2.5 +\page callbacks Using ns-3 callbacks
     2.6 +\anchor howtos-callbacks
     2.7 +
     2.8 +\section null_callbacks Null Callbacks
     2.9 +
    2.10 +<b>Question:</b> The API I am using calls for using a callback (in the 
    2.11 +function signature), but I do not
    2.12 +want to provide one.  Is there a way to provide a null callback?
    2.13 +
    2.14 +<b>Answer:</b> Use the ns3::MakeNullCallback construct:
    2.15 +\code
    2.16 +template<typename R>
    2.17 +Callback< R, T1, T2, T3, T4, T5, T6 > ns3::MakeNullCallback (void)
    2.18 +\endcode
    2.19 +
    2.20 +Example usage:  The ns3::Socket class uses callbacks to indicate completion
    2.21 +of events such as a successful TCP connect().  These callbacks are set
    2.22 +in the following function:
    2.23 +\code
    2.24 +  void Socket::SetConnectCallback (Callback<void, Ptr<Socket> > connectionSucceeded,
    2.25 +                        Callback<void, Ptr<Socket> > connectionFailed,
    2.26 +                        Callback<void, Ptr<Socket> > halfClose);
    2.27 +
    2.28 +\endcode
    2.29 +But suppose you do not care about registering a callback for the 
    2.30 +halfClose event (but you want to register one for the 
    2.31 +connectionSucceeded and connectionFailed cases).  In that case, you
    2.32 +can pass a null callback as the third argument.  You just need to
    2.33 +pass a callback with the matching signature, as follows:
    2.34 +\code
    2.35 +  localSocket->SetConnectCallback (
    2.36 +  MakeCallback (&ConnectionSucceededCallback),
    2.37 +  MakeCallback (&ConnectionFailedCallback),
    2.38 +  MakeNullCallback<void, Ptr<Socket> > () );
    2.39 +\endcode
    2.40 +
    2.41 +*/
     3.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     3.2 +++ b/doc/howtos/howtos.h	Thu Jan 10 07:31:40 2008 -0800
     3.3 @@ -0,0 +1,17 @@
     3.4 +/*!
     3.5 +\page howtos ns-3 HOWTOs
     3.6 +\anchor howtos-anchor
     3.7 +
     3.8 +This is an organized set of frequently asked questions (FAQ) and HOWTOs
     3.9 +for ns-3.  This complements the following wiki pages:
    3.10 +
    3.11 +- <a href="http://www.nsnam.org/wiki/index.php/User_FAQ">User FAQ</a>
    3.12 +- <a href="http://www.nsnam.org/wiki/index.php/Developer_FAQ">Developer FAQ</a>
    3.13 +
    3.14 +Please consider contributing tips to either the wiki (yourself) or
    3.15 +by submitting a patch to this maintained documentation.
    3.16 +
    3.17 +- \subpage callbacks
    3.18 +
    3.19 +*/
    3.20 +
     4.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     4.2 +++ b/doc/main.h	Thu Jan 10 07:31:40 2008 -0800
     4.3 @@ -0,0 +1,61 @@
     4.4 +/**
     4.5 + * \mainpage ns-3 Documentation
     4.6 + *
     4.7 + * \section intro-sec Introduction
     4.8 + * <a href="http://www.nsnam.org/">ns-3</a> documentation is maintained using 
     4.9 + * <a href="http://www.doxygen.org">Doxygen</a>.
    4.10 + * Doxygen is typically used for 
    4.11 + * API documentation, and organizes such documentation across different
    4.12 + * modules.   This project uses Doxygen both for building the manual around 
    4.13 + * the API documentation,  and a separate GNU texinfo document is used for 
    4.14 + * the manual.
    4.15 + *
    4.16 + * The ns-3 project documentation is organized as follows:
    4.17 + *     - <b><a href="modules.html">modules</a></b>:  The "Modules" tab (above) 
    4.18 + *       organizes  all of the public API and supporting manual text 
    4.19 + *       along the  source code directory structure.   This forms the 
    4.20 + *       "ns-3 manual", and it is available in HTML and PDF forms.
    4.21 + *     - \ref howtos-anchor "HOWTOs": A set of HOWTOs and FAQs is
    4.22 + *       maintained on another Doxygen "Related Page" 
    4.23 + *     - <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>. 
    4.24 + *     - The <b><a href="http://www.nsnam.org/wiki/index.php/Main_Page">ns-3 wiki</a></b> 
    4.25 + *       contains additional user-contributed material.  Some wiki-contributed
    4.26 + *       material may migrate to and overlap with the Doxygen information.
    4.27 + *
    4.28 + * \section install-sec Building the Documentation
    4.29 + * 
    4.30 + * ns-3 requires Doxygen version 1.5.4 or greater to fully build all items,
    4.31 + * although earlier versions of Doxygen will mostly work.
    4.32 + * 
    4.33 + * Type "./waf check" followed by "./waf --doxygen" to build the documentation.
    4.34 + * There is a program that runs during "./waf check" that builds pieces of
    4.35 + * the documentation through introspection.  The doc/ directory contains
    4.36 + * configuration for Doxygen (doxygen.conf and main.txt).  The Doxygen 
    4.37 + * build process puts html files into the doc/html/ directory, and latex 
    4.38 + * filex into the doc/latex/ directory.
    4.39 + * 
    4.40 + * \section module-sec Module overview
    4.41 + *
    4.42 + * The ns-3 library is split across multiple modules:
    4.43 + *     - core: located in src/core and contains a number of facilities which
    4.44 + *       do not depend on any other module. Some of these facilities are
    4.45 + *       OS-dependent.
    4.46 + *     - simulator: located in src/simulator and contains event scheduling
    4.47 + *       facilities.
    4.48 + *     - common: located in src/common and contains facilities specific
    4.49 + *       to network simulations but shared by pretty much every model
    4.50 + *       of a network component.
    4.51 + *     - node: located in src/node. Defines the abstract interfaces which 
    4.52 + *       must be implemented by every node and more specifically, by ipv4 nodes.       
    4.53 + *     - devices: located in src/devices. Contains a set of MAC-level models
    4.54 + *
    4.55 + * More detail can be found in the <b><a href="modules.html">Modules</a></b>
    4.56 + * tab.
    4.57 + *
    4.58 + */
    4.59 +/**
    4.60 + * \namespace ns3
    4.61 + * \brief Every class exported by the ns3 library is enclosed in the
    4.62 + * ns3 namespace.
    4.63 + */
    4.64 +
     5.1 --- a/doc/main.txt	Fri Jan 11 08:31:38 2008 -0800
     5.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
     5.3 @@ -1,68 +0,0 @@
     5.4 -/**
     5.5 - * \mainpage An Introduction to ns-3
     5.6 - *
     5.7 - * The ns-3 library is split across multiple modules:
     5.8 - *     - core: located in src/core and contains a number of facilities which
     5.9 - *       do not depend on any other module. Some of these facilities are
    5.10 - *       OS-dependent.
    5.11 - *     - simulator: located in src/simulator and contains event scheduling
    5.12 - *       facilities.
    5.13 - *     - common: located in src/common and contains facilities specific
    5.14 - *       to network simulations but shared by pretty much every model
    5.15 - *       of a network component.
    5.16 - *     - node: located in src/node. Defines the abstract interfaces which 
    5.17 - *       must be implemented by every node and more specifically, by ipv4 nodes.       
    5.18 - *     - devices: located in src/devices. Contains a set of MAC-level models
    5.19 - *
    5.20 - * The "core" module contains:
    5.21 - *    - a Functor class: ns3::Callback
    5.22 - *    - an os-independent interface to get access to the elapsed wall clock time: ns3::SystemWallClockMs
    5.23 - *    - a class to register regression tests with the test manager: ns3::Test and ns3::TestManager
    5.24 - *    - debugging facilities: \ref logging, \ref assert, \ref error
    5.25 - *    - \ref randomvariable
    5.26 - *    - \ref config
    5.27 - *    - a base class for objects which need to support reference counting 
    5.28 - *      and QueryInterface: ns3::Object and ns3::InterfaceId
    5.29 - *    - a set of low-level trace facilities integrated in the ns3::Object system: \ref tracing
    5.30 - *    - a ns3::ComponentManager which can be used to manage the creation
    5.31 - *      of any object which derives from ns3::Object through an ns3::ClassId
    5.32 - *    - a smart-pointer class ns3::Ptr designed to work together with ns3::Object
    5.33 - *
    5.34 - * The "simulator" module contains:
    5.35 - *    - a time management class to hold a time and convert between various time units: ns3::Time
    5.36 - *    - a scheduler base class used to implement new simulation event schedulers: 
    5.37 - *      ns3::Scheduler and ns3::SchedulerFactory
    5.38 - *    - a simulator class used to create, schedule and cancel events: ns3::Simulator
    5.39 - *
    5.40 - * The "core" module contains:
    5.41 - *    - a packet class to create and manipulate simulation packets: ns3::Packet, ns3::Header, 
    5.42 - *      and ns3::Trailer. This packet class also supports per-packet ns3::Tag which are
    5.43 - *      globs of data which can be attached to any packet.
    5.44 - *
    5.45 - * The "node" module contains:
    5.46 - *    - a ns3::Node base class which should be subclassed by any new type of
    5.47 - *      network Node.
    5.48 - *    - models which abstract the MAC-layer from the IP layer protocols:
    5.49 - *      ns3::NetDevice and ns3::Channel.
    5.50 - *    - models which abstract the application-layer API: ns3::Application,
    5.51 - *      ns3::Socket, ns3::SocketFactory, and, ns3::Udp
    5.52 - *
    5.53 - * The "internet-node" module contains a set of classes which implement the
    5.54 - * APIs defined in the "node" module:
    5.55 - *    - an Ipv4/Udp stack with socket support
    5.56 - *    - an ARP module
    5.57 - *    - an InternetNode class which is a Node subclass. 
    5.58 - *
    5.59 - * The "devices" module contains:
    5.60 - *    - a PointToPoint MAC device: ns3::PointToPointNetDevice, ns3::PointToPointChannel,
    5.61 - *      and ns3::PointToPointTopology.
    5.62 - */
    5.63 -/**
    5.64 - * \namespace ns3
    5.65 - * \brief Every class exported by the ns3 library is enclosed in the
    5.66 - * ns3 namespace.
    5.67 - */
    5.68 -/**
    5.69 - * \defgroup constants Constants
    5.70 - * \brief Constants you can change
    5.71 - */
     6.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     6.2 +++ b/doc/modules	Thu Jan 10 07:31:40 2008 -0800
     6.3 @@ -0,0 +1,67 @@
     6.4 +/**
     6.5 + * @anchor modules_anchor
     6.6 + *
     6.7 + * @defgroup simulator Simulator
     6.8 + * The "simulator" module contains: 
     6.9 + *    - a time management class to hold a time and convert between various time units: ns3::Time 
    6.10 + *    - a scheduler base class used to implement new simulation event schedulers:       
    6.11 + *      ns3::Scheduler and ns3::SchedulerFactory 
    6.12 + *    - a simulator class used to create, schedule and cancel events: ns3::Simulator
    6.13 + *
    6.14 + * @defgroup core Core
    6.15 + * \brief The "core" module contains:
    6.16 + *    - a Functor class: ns3::Callback  
    6.17 + *    - an os-independent interface to get access to the elapsed wall clock time: ns3::SystemWallClockMs 
    6.18 + *    - a class to register regression tests with the test manager: ns3::Test and ns3::TestManager
    6.19 + *    - debugging facilities: \ref logging, \ref assert, \ref error
    6.20 + *    - \ref randomvariable
    6.21 + *    - \ref config
    6.22 + *    - a base class for objects which need to support reference counting
    6.23 + *      and QueryInterface: ns3::Object and ns3::InterfaceId 
    6.24 + *    - a set of low-level trace facilities integrated in the ns3::Object system: \ref tracing
    6.25 + *    - a ns3::ComponentManager which can be used to manage the creation
    6.26 + *      of any object which derives from ns3::Object through an ns3::ClassId 
    6.27 + *    - a smart-pointer class ns3::Ptr designed to work together with ns3::Object
    6.28 + *
    6.29 + * @defgroup common Common
    6.30 + * The "core" module contains: 
    6.31 + *    - a packet class to create and manipulate simulation packets: 
    6.32 + *      ns3::Packet, ns3::Header,  and ns3::Trailer. This packet class 
    6.33 + *      also supports per-packet ns3::Tag which are  globs of data 
    6.34 + *      which can be attached to any packet.
    6.35 + *
    6.36 + * @defgroup node Node
    6.37 + * The "node" module contains:
    6.38 + *    - a ns3::Node base class which should be subclassed by any new type of
    6.39 + *      network Node.
    6.40 + *    - models which abstract the MAC-layer from the IP layer protocols:
    6.41 + *      ns3::NetDevice and ns3::Channel. 
    6.42 + *    - models which abstract the application-layer API: ns3::Application,
    6.43 + *      ns3::Socket, ns3::SocketFactory, and, ns3::Udp
    6.44 + * 
    6.45 + *
    6.46 + * @defgroup devices Devices
    6.47 + * The "devices" module contains:
    6.48 + *    - a PointToPoint MAC device: ns3::PointToPointNetDevice, ns3::PointToPointChannel,
    6.49 + *      and ns3::PointToPointTopology.
    6.50 + *
    6.51 + * @defgroup internetNode InternetNode
    6.52 + * 
    6.53 + * The "internet-node" module contains a set of classes which implement the
    6.54 + * APIs defined in the "node" module:
    6.55 + *    - an Ipv4/Udp stack with socket support 
    6.56 + *    - an ARP module
    6.57 + *    - an InternetNode class which is a Node subclass.
    6.58 + *    
    6.59 + * @defgroup applications Applications
    6.60 + *
    6.61 + * @defgroup mobility Mobility
    6.62 + *
    6.63 + * @defgroup routing Routing
    6.64 + *
    6.65 + * @defgroup constants Constants
    6.66 + * @brief Constants you can change
    6.67 + *
    6.68 + * @defgroup contrib Contrib
    6.69 + */
    6.70 +
     7.1 --- a/doc/tracing.h	Fri Jan 11 08:31:38 2008 -0800
     7.2 +++ b/doc/tracing.h	Thu Jan 10 07:31:40 2008 -0800
     7.3 @@ -1,8 +1,10 @@
     7.4  /**
     7.5 + * \ingroup core
     7.6   * \defgroup TraceSourceList List of trace sources
     7.7   */
     7.8  
     7.9  /**
    7.10 + * \ingroup core
    7.11   * \defgroup tracing Tracing
    7.12   *
    7.13   * The flexibility of the ns-3 tracing system comes at the cost of quite
     8.1 --- a/src/common/packet.h	Fri Jan 11 08:31:38 2008 -0800
     8.2 +++ b/src/common/packet.h	Thu Jan 10 07:31:40 2008 -0800
     8.3 @@ -362,6 +362,7 @@
     8.4  std::ostream& operator<< (std::ostream& os, const Packet &packet);
     8.5  
     8.6  /**
     8.7 + * \ingroup common
     8.8   * \defgroup packetperf Packet Performance
     8.9   * The current implementation of the byte buffers and tag list is based
    8.10   * on COW (Copy On Write. An introduction to COW can be found in Scott 
     9.1 --- a/src/core/assert.h	Fri Jan 11 08:31:38 2008 -0800
     9.2 +++ b/src/core/assert.h	Thu Jan 10 07:31:40 2008 -0800
     9.3 @@ -28,6 +28,7 @@
     9.4  #include "breakpoint.h"
     9.5  
     9.6  /**
     9.7 + * \ingroup core
     9.8   * \defgroup assert Assert
     9.9   * \brief assert functions and macros
    9.10   *
    10.1 --- a/src/core/callback.h	Fri Jan 11 08:31:38 2008 -0800
    10.2 +++ b/src/core/callback.h	Thu Jan 10 07:31:40 2008 -0800
    10.3 @@ -362,6 +362,7 @@
    10.4  };
    10.5  
    10.6  /**
    10.7 + * \ingroup core
    10.8   * \defgroup MakeCallback MakeCallback
    10.9   *
   10.10   */
    11.1 --- a/src/core/default-value.h	Fri Jan 11 08:31:38 2008 -0800
    11.2 +++ b/src/core/default-value.h	Thu Jan 10 07:31:40 2008 -0800
    11.3 @@ -25,6 +25,7 @@
    11.4  #include "callback.h"
    11.5  
    11.6  /**
    11.7 + * \ingroup core
    11.8   * \defgroup config Simulation configuration
    11.9   *
   11.10   */
    12.1 --- a/src/core/fatal-error.h	Fri Jan 11 08:31:38 2008 -0800
    12.2 +++ b/src/core/fatal-error.h	Thu Jan 10 07:31:40 2008 -0800
    12.3 @@ -25,6 +25,7 @@
    12.4  #include <iostream>
    12.5  
    12.6  /**
    12.7 + * \ingroup core
    12.8   * \defgroup error Error
    12.9   * \brief fatal error handling
   12.10   *
    13.1 --- a/src/core/log.h	Fri Jan 11 08:31:38 2008 -0800
    13.2 +++ b/src/core/log.h	Thu Jan 10 07:31:40 2008 -0800
    13.3 @@ -25,6 +25,7 @@
    13.4  #include <iostream>
    13.5  
    13.6  /**
    13.7 + * \ingroup core
    13.8   * \defgroup logging Logging
    13.9   * \brief Logging functions and macros
   13.10   *
    14.1 --- a/src/core/random-variable.h	Fri Jan 11 08:31:38 2008 -0800
    14.2 +++ b/src/core/random-variable.h	Thu Jan 10 07:31:40 2008 -0800
    14.3 @@ -26,6 +26,7 @@
    14.4  #include <stdint.h>
    14.5  
    14.6  /**
    14.7 + * \ingroup core
    14.8   * \defgroup randomvariable Random Variable Distributions
    14.9   *
   14.10   */
    15.1 --- a/src/devices/wifi/wifi.h	Fri Jan 11 08:31:38 2008 -0800
    15.2 +++ b/src/devices/wifi/wifi.h	Thu Jan 10 07:31:40 2008 -0800
    15.3 @@ -1,4 +1,5 @@
    15.4  /**
    15.5 + * \ingroup devices
    15.6   * \defgroup Wifi Wifi Models
    15.7   *
    15.8   * \section Wifi Models
    16.1 --- a/src/internet-node/internet-node.h	Fri Jan 11 08:31:38 2008 -0800
    16.2 +++ b/src/internet-node/internet-node.h	Thu Jan 10 07:31:40 2008 -0800
    16.3 @@ -32,7 +32,7 @@
    16.4  namespace ns3 {
    16.5  
    16.6  /**
    16.7 - * \defgroup InternetNode InternetNode
    16.8 + * \ingroup internetNode
    16.9   *
   16.10   * \section InternetNode Overview
   16.11   *
    17.1 --- a/src/mobility/mobility.h	Fri Jan 11 08:31:38 2008 -0800
    17.2 +++ b/src/mobility/mobility.h	Thu Jan 10 07:31:40 2008 -0800
    17.3 @@ -1,5 +1,5 @@
    17.4  /**
    17.5 - * \defgroup mobility Mobility
    17.6 + * \addtogroup mobility Mobility
    17.7   *
    17.8   * The mobility support includes:
    17.9   *  - a set of mobility models which are used to track and maintain
    18.1 --- a/utils/print-introspected-doxygen.cc	Fri Jan 11 08:31:38 2008 -0800
    18.2 +++ b/utils/print-introspected-doxygen.cc	Thu Jan 10 07:31:40 2008 -0800
    18.3 @@ -99,6 +99,7 @@
    18.4  PrintDefaultValuesDoxygen (std::ostream &os)
    18.5  {
    18.6    os << "/// \\page ListOfDefaultValues The list of default values" << std::endl;
    18.7 +  os << "/// \\ingroup core" << std::endl;
    18.8    os << "/// \\defgroup ListOfDefaultValuesGroup The list of default values" << std::endl;
    18.9    os << "/// <ul>" << std::endl;
   18.10    for (DefaultValueList::Iterator i = DefaultValueList::Begin ();