doxygen updates

src/common/packet.h

@@ -42,7 +42,7 @@ class TagIterator
 {
 public:
   /**
-   * Identifies a set tag and a set of bytes within a packet
+   * Identifies a tag and a set of bytes within a packet
    * to which the tag applies.
    */
   class Item

src/common/pcap-writer.h

@@ -51,17 +51,35 @@ public:
 
   /**
    * Write a pcap header in the output file which specifies
-   * that the content of the file will Packets with
+   * that the content of the file will be Packets with
    * Ethernet/LLC/SNAP encapsulation. This method should
    * be invoked before ns3::PcapWriter::writePacket and after
    * ns3::PcapWriter::open.
    */
   void WriteEthernetHeader (void);
 
+  /**
+   * Write a pcap header in the output file which specifies
+   * that the content of the file will be IPv4 Packets. This 
+   * method should be invoked before ns3::PcapWriter::WritePacket 
+   * and after ns3::PcapWriter::Open.
+   */
   void WriteIpHeader (void);
 
+  /**
+   * Write a pcap header in the output file which specifies
+   * that the content of the file will be 802.11 Packets. This 
+   * method should be invoked before ns3::PcapWriter::WritePacket 
+   * and after ns3::PcapWriter::Open.
+   */
   void WriteWifiHeader (void);
 
+  /**
+   * Write a pcap header in the output file which specifies
+   * that the content of the file will be ppp Packets. This 
+   * method should be invoked before ns3::PcapWriter::WritePacket 
+   * and after ns3::PcapWriter::Open.
+   */
   void WritePppHeader (void);
 
   /**

src/common/tag-buffer.h

@@ -38,28 +38,106 @@ namespace ns3 {
  * \brief read and write tag data
  *
  * This class allows subclasses of the ns3::Tag base class
- * to serialize and deserialize their data.
+ * to serialize and deserialize their data through a stream-like
+ * API. This class keeps track of the "current" point in the
+ * buffer and advances that "current" point everytime data is 
+ * written. The in-memory format of the data written by 
+ * this class is unspecified.
+ *
+ * If the user attempts to write more data in the buffer than 
+ * he allocated with Tag::GetSerializedSize, he will trigger
+ * an NS_ASSERT error.
  */
 class TagBuffer
 {
 public:
   TagBuffer (uint8_t *start, uint8_t *end);
   void TrimAtEnd (uint32_t trim);
-
-  TAG_BUFFER_INLINE void WriteU8 (uint8_t v);
-  TAG_BUFFER_INLINE void WriteU16 (uint16_t v);
-  TAG_BUFFER_INLINE void WriteU32 (uint32_t v);
-  void WriteU64 (uint64_t v);
-  void WriteDouble (double v);
-  void Write (const uint8_t *buffer, uint32_t size);
-  TAG_BUFFER_INLINE uint8_t  ReadU8 (void);
-  TAG_BUFFER_INLINE uint16_t ReadU16 (void);
-  TAG_BUFFER_INLINE uint32_t ReadU32 (void);
-  uint64_t ReadU64 (void);
-  double ReadDouble (void);
-  void Read (uint8_t *buffer, uint32_t size);
-
   void CopyFrom (TagBuffer o);
+
+  /**
+   * \param v the value to write
+   *
+   * Write one byte and advance the "current" point by one.
+   */
+  TAG_BUFFER_INLINE void WriteU8 (uint8_t v);
+  /**
+   * \param v the value to write
+   *
+   * Write two bytes and advance the "current" point by two.
+   */
+  TAG_BUFFER_INLINE void WriteU16 (uint16_t v);
+  /**
+   * \param v the value to write
+   *
+   * Write four bytes and advance the "current" point by four.
+   */
+  TAG_BUFFER_INLINE void WriteU32 (uint32_t v);
+  /**
+   * \param v the value to write
+   *
+   * Write eight bytes and advance the "current" point by eight.
+   */
+  void WriteU64 (uint64_t v);
+  /**
+   * \param v the value to write
+   *
+   * Write a double and advance the "current" point by the size of the
+   * data written.
+   */
+  void WriteDouble (double v);
+  /**
+   * \param buffer a pointer to data to write
+   * \param size the size of the data to write
+   *
+   * Write all the input data and advance the "current" point by the size of the
+   * data written.
+   */
+  void Write (const uint8_t *buffer, uint32_t size);
+  /**
+   * \returns the value read
+   *
+   * Read one byte, advance the "current" point by one,
+   * and return the value read.
+   */
+  TAG_BUFFER_INLINE uint8_t  ReadU8 (void);
+  /**
+   * \returns the value read
+   *
+   * Read two bytes, advance the "current" point by two,
+   * and return the value read.
+   */
+  TAG_BUFFER_INLINE uint16_t ReadU16 (void);
+  /**
+   * \returns the value read
+   *
+   * Read four bytes, advance the "current" point by four,
+   * and return the value read.
+   */
+  TAG_BUFFER_INLINE uint32_t ReadU32 (void);
+  /**
+   * \returns the value read
+   *
+   * Read eight bytes, advance the "current" point by eight,
+   * and return the value read.
+   */
+  uint64_t ReadU64 (void);
+  /**
+   * \returns the value read
+   *
+   * Read a double, advance the "current" point by the size
+   * of the data read, and, return the value read.
+   */
+  double ReadDouble (void);
+  /**
+   * \param buffer a pointer to the buffer where data should be
+   * written.
+   * \param size the number of bytes to read.
+   *
+   * Read the number of bytes requested, advance the "current"
+   * point by the number of bytes read, return.
+   */
+  void Read (uint8_t *buffer, uint32_t size);
 private:
   
   uint8_t *m_current;

src/common/tag.h

@@ -49,12 +49,16 @@ public:
    * \param i the buffer to write data into.
    *
    * Write the content of the tag in the provided tag buffer.
+   * DO NOT attempt to write more bytes than you requested
+   * with Tag::GetSerializedSize.
    */
   virtual void Serialize (TagBuffer i) const = 0;
   /**
    * \param i the buffer to read data from.
    *
    * Read the content of the tag from the provided tag buffer.
+   * DO NOT attempt to read more bytes than you wrote with
+   * Tag::Serialize.
    */
   virtual void Deserialize (TagBuffer i) = 0;
 };