--- a/src/common/packet.h	Wed Sep 06 15:20:25 2006 +0200
+++ b/src/common/packet.h	Wed Sep 06 16:46:26 2006 +0200
@@ -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 @@
 {
     return m_tags.peek (tag);
 }
-template <typename T>
-bool Packet::updateTag (T const*tag)
-{
-    return m_tags.update (tag);
-}
-
 }; // namespace ns3
 
 #endif /* PACKET_H */