--- a/src/common/packet-metadata.h	Wed Jun 27 20:51:07 2007 +0200
+++ b/src/common/packet-metadata.h	Thu Jun 28 11:07:38 2007 +0200
@@ -66,27 +66,71 @@
   static void PrintStats (void);
 
 private:
-  /**
-     head -(next)-> tail
-       ^             |
-        \---(prev)---|
-   */
   struct Data {
+    /* number of references to this struct Data instance. */
     uint16_t m_count;
+    /* size (in bytes) of m_data buffer below */
     uint16_t m_size;
+    /* max of the m_used field over all objects which 
+     * reference this struct Data instance */
     uint16_t m_dirtyEnd;
+    /* variable-sized buffer of bytes */
     uint8_t m_data[10];
   };
+  /* Note that since the next and prev fields are 16 bit integers
+     and since the value 0xffff is reserved to identify the 
+     fact that the end or the start of the list is reached,
+     only a limited number of elements can be stored in 
+     a m_data byte buffer.
+   */
   struct SmallItem {
+    /* offset (in bytes) from start of m_data buffer 
+       to next element in linked list. value is 0xffff 
+       if next element does not exist.
+    */
     uint16_t next;
+    /* offset (in bytes) from start of m_data buffer 
+       to previous element in linked list. value is 0xffff 
+       if previous element does not exist.
+     */
     uint16_t prev;
+    /* the high 31 bits of this field identify the 
+       type of the header or trailer represented by 
+       this item: the value zero represents payload.
+       If the low bit of this uid is one, an ExtraItem
+       structure follows this SmallItem structure.
+     */
     uint32_t typeUid;
+    /* the size (in bytes) of the header or trailer represented
+       by this element.
+     */
     uint32_t size;
+    /* this field tries to uniquely identify each header or 
+       trailer _instance_ while the typeUid field uniquely
+       identifies each header or trailer _type_. This field
+       is used to test whether two items are equal in the sense 
+       that they represent the same header or trailer instance.
+       That equality test is based on the typeUid and chunkUid
+       fields so, the likelyhood that two header instances 
+       share the same chunkUid _and_ typeUid is very small 
+       unless they are really representations of the same header
+       instance.
+     */
     uint16_t chunkUid;
   };
   struct ExtraItem {
+    /* offset (in bytes) from start of original header to 
+       the start of the fragment still present.
+     */
     uint32_t fragmentStart;
+    /* offset (in bytes) from start of original header to 
+       the end of the fragment still present.
+     */
     uint32_t fragmentEnd;
+    /* the packetUid of the packet in which this header or trailer
+       was first added. It could be different from the m_packetUid
+       field if the user has aggregated multiple packets into one.
+     */
     uint32_t packetUid;
   };
 
@@ -138,6 +182,11 @@
   static uint16_t m_chunkUid;
   
   struct Data *m_data;
+  /**
+     head -(next)-> tail
+       ^             |
+        \---(prev)---|
+   */
   uint16_t m_head;
   uint16_t m_tail;
   uint16_t m_used;