improve documentation and remove updateTag method

src/common/chunk.h

@@ -33,7 +33,11 @@ namespace ns3 {
  *
  * Every Protocol header which needs to be inserted and removed
  * from a Packet instance must derive from this abstract base class
- * and implement the private pure virtual methods defined here.
+ * and implement the private pure virtual methods listed below:
+ *   - ns3::Chunk::addTo
+ *   - ns3::Chunk::removeFrom
+ *   - ns3::Chunk::peekFrom
+ *   - ns3::Chunk::print
  */
 class Chunk {
 public:

src/common/packet.h

@@ -29,29 +29,140 @@
 
 namespace ns3 {
 
+/**
+ * \brief network packets
+ */
 class Packet {
 public:
     typedef Callback<void,uint8_t *,uint32_t> PacketReadWriteCallback;
+	/**
+	 * Create an empty packet.
+	 */
     Packet ();
+	/**
+	 * Create a packet with a zero-filled payload.
+	 * The memory necessary for the payload is not allocated:
+	 * it will be allocated at any later point if you attempt
+	 * to fragment this packet or to access the zero-filled
+	 * bytes.
+	 * 
+	 * \param size the size of the zero-filled payload
+	 */
     Packet (uint32_t size);
+	/**
+	 * Create a new packet which contains a fragment of the original
+	 * packet.
+	 *
+	 * \param start offset from start of packet to start of fragment to create
+	 * \param length length of fragment to create
+	 * \returns a fragment of the original packet
+	 */
     Packet createFragment (uint32_t start, uint32_t length) const;
+	/**
+	 * \returns the size in bytes of the packet (including the zero-filled
+	 *          initial payload)
+	 */
     uint32_t getSize (void) const;
+	/**
+	 * Add chunk to this packet. This method invokes the
+	 * ns3::Chunk::addTo method to request the chunk to serialize
+	 * itself in the packet buffer.
+	 *
+	 * \param chunk a pointer to the chunk to add to this packet.
+	 */
     void add (Chunk *chunk);
+	/**
+	 * Deserialize chunk from this packet. This method invokes the
+	 * ns3::Chunk::peekFrom method to request the chunk to deserialize
+	 * itself from the packet buffer. This method does not remove
+	 * the chunk from the buffer.
+	 *
+	 * \param chunk a pointer to the chunk to deserialize from the buffer
+	 */
     void peek (Chunk *chunk) const;
+	/**
+	 * Remove a deserialized chunk from the internal buffer.
+	 * This method invokes ns3::Chunk::removeFrom to complete
+	 * the work initiated by Packet::peek and ns3::Chunk::peekFrom.
+	 *
+	 * \param chunk a pointer to the chunk to remove from the internal buffer.
+	 */
     void remove (Chunk *chunk);
+	/**
+	 * Attach a tag to this packet. The tag is fully copied
+	 * in a packet-specific internal buffer. This operation 
+	 * is expected to be really fast.
+	 *
+	 * \param tag a pointer to the tag to attach to this packet.
+	 */
     template <typename T>
     void addTag (T const *tag);
+	/**
+	 * Remove a tag from this packet. The data stored internally
+	 * for this tag is copied in the input tag if an instance
+	 * of this tag type is present in the internal buffer. If this
+	 * tag type is not present, the input tag is not modified. 
+	 *
+	 * This operation can be potentially slow and might trigger
+	 * unexpectedly large memory allocations. It is thus
+	 * usually a better idea to create a copy of this packet,
+	 * and invoke removeAllTags on the copy to remove all 
+	 * tags rather than remove the tags one by one from a packet.
+	 *
+	 * \param tag a pointer to the tag to remove from this packet
+	 * \returns true if an instance of this tag type is stored
+	 *          in this packet, false otherwise.
+	 */
     template <typename T>
     bool removeTag (T *tag);
+	/**
+	 * Copy a tag stored internally to the input tag. If no instance
+	 * of this tag is present internally, the input tag is not modified.
+	 *
+	 * \param tag a pointer to the tag to read from this packet
+	 * \returns true if an instance of this tag type is stored
+	 *          in this packet, false otherwise.
+	 */
     template <typename T>
     bool peekTag (T *tag) const;
-    template <typename T>
-    bool updateTag (T const*tag);
+	/**
+	 * Remove all the tags stored in this packet. This operation is
+	 * much much faster than invoking removeTag n times.
+	 */
     void removeAllTags (void);
     void write (PacketReadWriteCallback callback) const;
+	/**
+	 * Concatenate the input packet at the end of the current
+	 * packet.
+	 *
+	 * \param packet packet to concatenate
+	 */
     void addAtEnd (Packet packet);
+	/**
+	 * Concatenate the fragment of the input packet identified
+	 * by the offset and size parameters at the end of the current
+	 * packet.
+	 *
+	 * \param packet to concatenate
+	 * \param offset offset of fragment to copy from the start of the input packet
+	 * \param size size of fragment of input packet to copy.
+	 */
     void addAtEnd (Packet packet, uint32_t offset, uint32_t size);
+	/** 
+	 * Remove size bytes from the end of the current packet
+	 * It is safe to remove more bytes that what is present in
+	 * the packet.
+	 *
+	 * \param size number of bytes from remove
+	 */
     void removeAtEnd (uint32_t size);
+	/** 
+	 * Remove size bytes from the start of the current packet.
+	 * It is safe to remove more bytes that what is present in
+	 * the packet.
+	 *
+	 * \param size number of bytes from remove
+	 */
     void removeAtStart (uint32_t size);
 
 private:
@@ -85,12 +196,6 @@ bool Packet::peekTag (T *tag) const
 {
     return m_tags.peek (tag);
 }
-template <typename T>
-bool Packet::updateTag (T const*tag)
-{
-    return m_tags.update (tag);
-}
-
 }; // namespace ns3
 
 #endif /* PACKET_H */

src/common/tags.cc

@@ -149,22 +149,6 @@ Tags::remove (uint32_t id)
     return true;
 }
 
-bool
-Tags::update (uint8_t const*buffer, uint32_t id)
-{
-    if (!remove (id)) {
-        return false;
-    }
-    struct TagData *newStart = allocData ();
-    newStart->m_count = 1;
-    newStart->m_next = 0;
-    newStart->m_id = id;
-    memcpy (newStart->m_data, buffer, Tags::SIZE);
-    newStart->m_next = m_next;
-    m_next = newStart;
-    return true;
-}
-
 void 
 Tags::prettyPrint (std::ostream &os)
 {

src/common/tags.h

@@ -46,9 +46,6 @@ public:
     template <typename T>
     bool peek (T *tag) const;
 
-    template <typename T>
-    bool update (T const*tag);
-
     void prettyPrint (std::ostream &os);
 
     inline void removeAll (void);
@@ -69,7 +66,6 @@ private:
     };
 
     bool remove (uint32_t id);
-    bool update (uint8_t const*buffer, uint32_t id);
     struct Tags::TagData *allocData (void);
     void freeData (struct TagData *data);
 
@@ -235,16 +231,6 @@ Tags::peek (T *tag) const
     return false;
 }
 
-template <typename T>
-bool
-Tags::update (T const*tag)
-{
-    assert (sizeof (T) <= Tags::SIZE);
-    uint8_t const*buf = reinterpret_cast<uint8_t const*> (tag);
-    return update (buf, TypeUid<T>::getUid ());
-}
-
-
 Tags::Tags ()
     : m_next ()
 {}