From ccd72825dda1967b1c1502ff22ed5794725ce07c Mon Sep 17 00:00:00 2001
From: Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
Date: Tue, 6 May 2008 14:54:52 -0700
Subject: [PATCH] add dox doc

---
 src/common/packet.h     | 13 +++++--------
 src/common/tag-buffer.h |  6 ++++++
 src/common/tag.h        | 21 +++++++++++++++++++++
 3 files changed, 32 insertions(+), 8 deletions(-)

diff --git a/src/common/packet.h b/src/common/packet.h
index a2e241654..ec77dfc5a 100644
--- a/src/common/packet.h
+++ b/src/common/packet.h
@@ -98,7 +98,7 @@ private:
 /**
  * \brief network packets
  *
- * Each network packet contains a byte buffer, a list of tags, and
+ * Each network packet contains a byte buffer, a set of tags, and
  * metadata.
  *
  * - The byte buffer stores the serialized content of the headers and trailers 
@@ -107,13 +107,10 @@ private:
  * forces you to do this) which means that the content of a packet buffer
  * is expected to be that of a real packet.
  *
- * - The list of tags stores an arbitrarily large set of arbitrary 
- * user-provided data structures in the packet: only one instance of
- * each type of data structure is allowed in a list of tags. 
- * These tags typically contain per-packet cross-layer information or 
- * flow identifiers. Each tag stored in the tag list can be at most
- * 16 bytes big. Trying to attach bigger data structures will trigger
- * crashes at runtime.
+ * - Each tag tags a subset of the bytes in the packet byte buffer with the 
+ * information stored in the tag. A classic example of a tag is a FlowIdTag 
+ * which contains a flow id: the set of bytes tagged by this tag implicitely 
+ * belong to the attached flow id.
  *
  * - The metadata describes the type of the headers and trailers which
  * were serialized in the byte buffer. The maintenance of metadata is
diff --git a/src/common/tag-buffer.h b/src/common/tag-buffer.h
index 5c85b6a07..da1dcb13a 100644
--- a/src/common/tag-buffer.h
+++ b/src/common/tag-buffer.h
@@ -5,6 +5,12 @@
 
 namespace ns3 {
 
+/**
+ * \brief read and write tag data
+ *
+ * This class allows subclasses of the ns3::Tag base class
+ * to serialize and deserialize their data.
+ */
 class TagBuffer
 {
 public:
diff --git a/src/common/tag.h b/src/common/tag.h
index dcac0582f..b24af5932 100644
--- a/src/common/tag.h
+++ b/src/common/tag.h
@@ -7,13 +7,34 @@
 
 namespace ns3 {
 
+/**
+ * \brief tag a set of bytes in a packet
+ *
+ * New kinds of tags can be created by subclassing this base class.
+ */
 class Tag : public ObjectBase
 {
 public:
   static TypeId GetTypeId (void);
 
+  /**
+   * \returns the number of bytes required to serialize the data of the tag.
+   *
+   * This method is typically invoked by Packet::AddTag just prior to calling
+   * Tag::Serialize.
+   */
   virtual uint32_t GetSerializedSize (void) const = 0;
+  /**
+   * \param i the buffer to write data into.
+   *
+   * Write the content of the tag in the provided tag buffer.
+   */
   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.
+   */
   virtual void Deserialize (TagBuffer i) = 0;
 };