X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=senf%2FPackets%2FPacket.hh;h=25d0f56a4227934fee280876819e9a9e2f25c329;hb=a0b6f53e5c464c6b84fed30a67fcce32da81012d;hp=00b00f712a8854f90f5fe7619a0632819c456f3c;hpb=3a3350157a52c268d5082a4aac4aba643417071f;p=senf.git

diff --git a/senf/Packets/Packet.hh b/senf/Packets/Packet.hh
index 00b00f7..25d0f56 100644
--- a/senf/Packets/Packet.hh
+++ b/senf/Packets/Packet.hh
@@ -171,7 +171,8 @@ namespace senf {
         // conversion constructors
 
         template <class PacketType>
-        Packet(ConcretePacket<PacketType> packet); ///< Copy-construct Packet from ConcretePacket
+        Packet(ConcretePacket<PacketType> const & packet);
+                                        ///< Copy-construct Packet from ConcretePacket
                                         /**< This constructor allows to convert an arbitrary
                                              ConcretePacket into a general Packet, loosing the
                                              protocol specific interface. */
@@ -242,7 +243,7 @@ namespace senf {
 
 
         Packet      first() const;      ///< Return first packet in chain
-        template <class OtherPacket> OtherPacket first() const; 
+        template <class OtherPacket> OtherPacket first() const;
                                         ///< Return first packet in chain and cast
                                         /**< \throws std::bad_cast if the first() packet is not of
                                              type \a OtherPacket */
@@ -296,7 +297,7 @@ namespace senf {
                                              the packet chain after \c this packet with a clone of
                                              \a packet and will replace the raw data of the payload
                                              of \c this with the raw data of \a packet. \c this
-                                             packet will not share any date with \a packet.
+                                             packet will not share any data with \a packet.
                                              \returns Packet handle to the cloned \a packet, placed
                                                  after \c this in the packet/header/interpreter
                                                  chain. */
@@ -489,9 +490,9 @@ namespace senf {
         ///@}
 
     protected:
-        explicit Packet(PacketInterpreterBase::ptr packet);
+        explicit Packet(PacketInterpreterBase::ptr const & packet);
 
-        PacketInterpreterBase::ptr ptr() const;
+        PacketInterpreterBase::ptr const & ptr() const;
 
     private:
         Packet checkNext() const;
@@ -519,15 +520,20 @@ namespace senf {
 
         \li The create() family of constructors will create completely new packets.
         \li The createAfter() family of constructors will create new packets (with new data for the
-            packet) \e after a given existing packet.
-        \li The createBefore()  family of constructors will create new packets (again with new data)
-            \e before a given existing packet.
+            packet) \e after a given existing packet <em>thereby destroying and overwriting  any
+            possibly existing packets and data after the given packet</em>.
+        \li The createBefore() family of constructors will create new packets (again with new data)
+            \e before a given existing packet <em>thereby destroying and overwriting any possibly
+            existing packets and data before the given packet</em>.
+        \li The createInsertBefore() family of constructors will create new packets \e before a
+            given packet \e inserting them into the packet chain after any existing packets before
+            the given packet.
 
         Whereas create() will create a completely new packet with it's own chain and data storage,
-        createAfter() and createBefore() extend a packet with additional
+        createAfter(), createBefore() and createInsertBefore() extend a packet with additional
         headers/interpreters. createAfter() will set the payload of the given packet to the new
-        packet whereas createBefore() will create a new packet with the existing packet as it's
-        payload.
+        packet whereas createBefore() and createInsertBefore() will create a new packet with the
+        existing packet as it's payload.
 
         createAfter() differs from Packet::parseNextAs() in that the former creates a new packet \e
         replacing any possibly existing data whereas the latter will interpret the already \e
@@ -679,16 +685,33 @@ namespace senf {
                                              state. It will be prepended as previous
                                              header/interpreter before \a packet in that packets
                                              interpreter chain.
+                                             \warning This constructor will destroy any existing
+                                                 headers before \a packet and replace them with the
+                                                 new header.
                                              \param[in] packet Packet to prepend new packet to. */
         static ConcretePacket createBefore(Packet const & packet, senf::NoInit_t);
                                         ///< Create uninitialized empty packet before \a packet
                                         /**< Creates a completely empty and uninitialized packet. It
                                              will be prepended as previous header/interpreter before
                                              \a packet in that packets interpreter chain.
+                                             \warning This constructor will destroy any existing
+                                                 headers before \a packet and replace them with the
+                                                 new header.
                                              \param[in] packet Packet to prepend new packet to. */
 
         static ConcretePacket createInsertBefore(Packet const & packet);
+                                        ///< Insert default initialized packet before \a packet
+                                        /**< The new packet header will be initialized to it' s
+                                             default empty state. It will be inserted into the
+                                             packet chain before \a packet.
+                                             \param[in] packet Packet before which to insert the new
+                                                 packet */
         static ConcretePacket createInsertBefore(Packet const & packet, senf::NoInit_t);
+                                        ///< Insert uninitialized empty packet before \a packet
+                                        /**< Inserts a completely empty and unitialized packet
+                                             before \a packet into the header/interpreter chain.
+                                             \param[in] packet Packet before which to insert the new
+                                                 packet */
 
         // Create a clone of the current packet
 
@@ -730,7 +753,7 @@ namespace senf {
     private:
         typedef PacketInterpreter<PacketType> interpreter;
 
-        ConcretePacket(typename interpreter::ptr packet_);
+        ConcretePacket(typename interpreter::ptr const & packet_);
 
         typename interpreter::ptr ptr() const;