beautify the dox output

doc/main.txt

@@ -10,7 +10,8 @@
  *     - 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. Contains an ipv4/udp model.
+ *     - 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:
@@ -20,8 +21,9 @@
  *    - debugging facilities: \ref debugging, \ref assert, \ref error
  *    - \ref randomvariable
  *    - \ref config
- *    - a class to handle automatic deletion of multiple sets of objects of different types: 
- *      ns3::ObjectContainer
+ *    - a base class for objects which need to support reference counting 
+ *      and QueryInterface: ns3::Interface and ns3::InterfaceId
+ *    - a smart-pointer class ns3::Ptr designed to work together with ns3::Interface
  *
  * The "simulator" module contains:
  *    - a time management class to hold a time and convert between various time units: ns3::Time
@@ -31,19 +33,25 @@
  *
  * The "common" module contains:
  *    - a packet class to create and manipulate simulation packets: ns3::Packet, ns3::Header, 
- *      and ns3::Trailer
+ *      and ns3::Trailer. This packet class also supports per-packet ns3::Tag which are
+ *      globs of data which can be attached to any packet.
  *    - a set of low-level trace facilities: \ref lowleveltracing
  *
  * The "node" module contains:
- *    - a ns3::Node base class and an ns3::InternetNode implementation which model
- *      network nodes.
- *    - a set of models contained in InternetNode: ns3::Ipv4, ns3::Udp, ns3::L3Demux,
- *      ns3::L3Protocol, ns3::Ipv4L4Demux, ns3::Ipv4L4Protocol, ns3::Ipv4Interface,
- *      ns3::DatagramSocket
+ *    - a ns3::INode 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.
- *    - an Arp model if the underlying NetDevice object needs it: ns3::ArpIpv4Interface
- *    - a set of traffic generation models: ns3::OnOffApplication
+ *    - models which abstract the application-layer API: ns3::Application,
+ *      ns3::Socket, ns3::ISocketFactory, and, ns3::IUdp
+ *
+ * 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 INode subclass. 
+ *    - and finally, a function used to instantiate nodes
+ *      which contain this implementation: ns3::MakeInternetNode
  *
  * The "devices" module contains:
  *    - a PointToPoint MAC device: ns3::PointToPointNetDevice, ns3::PointToPointChannel,

src/common/header.h

@@ -53,18 +53,18 @@ private:
   virtual uint32_t GetSerializedSize (void) const = 0;
 
   /**
-   * \param i the buffer iterator in which the protocol header
+   * \param start the buffer iterator in which the protocol header
    *    must serialize itself. This iterator identifies 
    *    the start of the buffer.
    */
-  virtual void SerializeTo (Buffer::Iterator i) const = 0;
+  virtual void SerializeTo (Buffer::Iterator start) const = 0;
   /**
-   * \param i the buffer iterator from which the protocol header must
+   * \param start the buffer iterator from which the protocol header must
    *    deserialize itself. This iterator identifies 
    *    the start of the buffer.
    * \returns the number of bytes read from the buffer
    */
-  virtual uint32_t DeserializeFrom (Buffer::Iterator i) = 0;
+  virtual uint32_t DeserializeFrom (Buffer::Iterator start) = 0;
 };
 
 }; // namespace ns3

src/common/trailer.h

@@ -53,18 +53,18 @@ private:
   virtual uint32_t GetSerializedSize (void) const = 0;
 
   /**
-   * \param i the buffer iterator in which the protocol trailer
+   * \param end the buffer iterator in which the protocol trailer
    *    must serialize itself. This iterator identifies 
    *    the end of the buffer.
    */
-  virtual void SerializeTo (Buffer::Iterator i) const = 0;
+  virtual void SerializeTo (Buffer::Iterator end) const = 0;
   /**
-   * \param i the buffer iterator from which the protocol trailer must
+   * \param end the buffer iterator from which the protocol trailer must
    *    deserialize itself. This iterator identifies 
    *    the end of the buffer.
    * \returns the number of bytes read from the buffer
    */
-  virtual uint32_t DeserializeFrom (Buffer::Iterator i) = 0;
+  virtual uint32_t DeserializeFrom (Buffer::Iterator end) = 0;
 };
 
 }; // namespace ns3

src/core/ptr.h

@@ -121,6 +121,7 @@ template <typename T, typename T1, typename T2, typename T3, typename T4, typena
 Ptr<T> MakeNewObject (T1 a1, T2 a2, T3 a3, T4 a4, T5 a5, T6 a6, T7 a7);
 
 /**
+ * \relates Ptr
  * \return the pointer managed by this smart pointer.
  *
  * The underlying refcount is not incremented prior
@@ -131,6 +132,7 @@ template <typename T>
 T * PeekPointer (const Ptr<T> &p);
 
 /**
+ * \relates Ptr
  * \return the pointer managed by this smart pointer.
  *
  * The underlying refcount is incremented prior

src/internet-node/internet-node.h

@@ -26,8 +26,15 @@
 
 namespace ns3 {
 
+/**
+ * \returns a newly-created Node which supports the Ipv4 interfaces
+ */
 Ptr<INode> MakeInternetNode (void);
 
+/**
+ * \param systemId a systemId for parallel simulations.
+ * \returns a newly-created Node which supports the Ipv4 interfaces
+ */
 Ptr<INode> MakeInternetNode (uint32_t systemId);
 
 } // namespace ns3

src/internet-node/ipv4-header.h

@@ -41,69 +41,102 @@ public:
    */
   static void EnableChecksums (void);
   /**
-   * \param size
+   * \param size the size of the payload in bytes
    */
   void SetPayloadSize (uint16_t size);
   /**
-   * \param identification
+   * \param identification the Identification field of IPv4 packets.
+   *
+   * By default, set to zero.
    */
   void SetIdentification (uint16_t identification);
   /**
-   * \param tos
+   * \param tos the 8 bits of Ipv4 TOS.
    */
   void SetTos (uint8_t tos);
   /**
-   *
+   * This packet is not the last packet of a fragmented ipv4 packet.
    */
   void SetMoreFragments (void);
   /**
-   *
+   * This packet is the last packet of a fragmented ipv4 packet.
    */
   void SetLastFragment (void);
   /**
-   *
+   * Don't fragment this packet: if you need to anyway, drop it.
    */
   void SetDontFragment (void);
   /**
-   *
+   * If you need to fragment this packet, you can do it.
    */
   void SetMayFragment (void);
   /**
-   * \param offset
+   * \param offset the ipv4 fragment offset
    */
   void SetFragmentOffset (uint16_t offset);
   /**
-   * \param ttl
+   * \param ttl the ipv4 TTL
    */
   void SetTtl (uint8_t ttl);
   /**
-   * \param num
+   * \param num the ipv4 protocol field
    */
   void SetProtocol (uint8_t num);
   /**
-   * \param source
+   * \param source the source of this packet
    */
   void SetSource (Ipv4Address source);
   /**
-   * \param destination
+   * \param destination the destination of this packet.
    */
   void SetDestination (Ipv4Address destination);
   /**
-   * \param 
+   * \returns the size of the payload in bytes
    */
-
-
   uint16_t GetPayloadSize (void) const;
+  /**
+   * \returns the identification field of this packet.
+   */
   uint16_t GetIdentification (void) const;
+  /**
+   * \returns the TOS field of this packet.
+   */
   uint8_t GetTos (void) const;
+  /**
+   * \returns true if this is the last fragment of a packet, false otherwise.
+   */
   bool IsLastFragment (void) const;
+  /**
+   * \returns true if this is this packet can be fragmented.
+   */  
   bool IsDontFragment (void) const;
+  /**
+   * \returns the offset of this fragment.
+   */
   uint16_t GetFragmentOffset (void) const;
+  /**
+   * \returns the TTL field of this packet
+   */
   uint8_t GetTtl (void) const;
+  /**
+   * \returns the protocol field of this packet
+   */
   uint8_t GetProtocol (void) const;
+  /**
+   * \returns the source address of this packet
+   */
   Ipv4Address GetSource (void) const;
+  /**
+   * \returns the destination address of this packet
+   */
   Ipv4Address GetDestination (void) const;
   
+  /**
+   * \returns true if the upv4 checksum is correct, false otherwise.
+   *
+   * If Ipv4Header::EnableChecksums has not been called prior to
+   * creating this packet, this method will always return true.
+   */
   bool IsChecksumOk (void) const;
 
 private:

src/internet-node/udp-header.h

@@ -40,6 +40,9 @@ public:
   UdpHeader ();
   virtual ~UdpHeader ();
 
+  /**
+   * \brief Enable checksum calculation for UDP (XXX currently has no effect)
+   */
   static void EnableChecksums (void);
   /**
    * \param port the destination port for this UdpHeader
@@ -58,10 +61,21 @@ public:
    */
   uint16_t GetDestination (void) const;
   /**
-   * \param size The payload size (XXX: in bytes?)
+   * \param size The payload size in bytes
    */
   void SetPayloadSize (uint16_t size);
 
+  /**
+   * \param source the ip source to use in the underlying
+   *        ip packet.
+   * \param destination the ip destination to use in the
+   *        underlying ip packet.
+   * \param protocol the protocol number to use in the underlying
+   *        ip packet.
+   *
+   * If you want to use udp checksums, you should call this
+   * method prior to adding the header to a packet.
+   */
   void InitializeChecksum (Ipv4Address source, 
                            Ipv4Address destination,
                            uint8_t protocol);