add dox doc

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

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:

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;
 };