Packets: Add short documentation for most internal classes

[senf.git] / Packets / PacketData.hh

diff --git a/Packets/PacketData.hh b/Packets/PacketData.hh
index fee2c00..9ebe32e 100644 (file)
--- a/Packets/PacketData.hh
+++ b/Packets/PacketData.hh
@@ -140,9 +140,25 @@ namespace senf {
 
     class PacketParserBase;
 
+    /** \brief Invalid packet data access
+
+        This exception is signaled whenever an operation tries to access an out-of-bounds data
+        byte. If the packet has been implemented correctly, this signals a malformed packet.
+     */
     struct TruncatedPacketException : public std::exception
     { virtual char const * what() const throw() { return "truncated packet"; } };
 
+    /** \brief Re-validating data iterator
+
+        This class is a wrapper around a PacketData::iterator instance. It will revalidate the
+        iterator on every access. This keeps the iterator valid even when the data container is
+        resized and thereby possibly relocated. The iterator will always point to the byte at the
+        same offset from the packets beginning. If data is inserted before this iterators position,
+        the data pointed to will of course change.
+
+        For this to work, the safe_data_iterator must be initialized with the container to which the
+        iterator belongs. After this initialization it can be used like any other iterator.
+     */
     class safe_data_iterator
         : public boost::iterator_facade< safe_data_iterator,
                                          PacketData::value_type,
@@ -152,18 +168,29 @@ namespace senf {
     public:
         typedef PacketData::size_type size_type;
 
-        safe_data_iterator();
-        explicit safe_data_iterator(PacketData & data);
+        safe_data_iterator(); ///< Make uninitialized iterator
+        explicit safe_data_iterator(PacketData & data); 
+                                        ///< Construct iterator only setting the data container
         safe_data_iterator(PacketData & data, PacketData::iterator i);
+                                        ///< Initialize iterator to given position
         explicit safe_data_iterator(PacketParserBase const & parser);
+                                        ///< Initialize iterator from parser
+                                        /**< The iterator will point to the parsers start
+                                             position. */
 
-        safe_data_iterator & operator=(PacketData::iterator i);
+        safe_data_iterator & operator=(PacketData::iterator i); ///< Assign iterator
+                                        /**< The iteator \a i must be from the container wo which \c
+                                             this iterator has been initialized. */
         safe_data_iterator & operator=(PacketParserBase const & parser);
-        operator PacketData::iterator() const;
+                                        ///< Assign iterator from parser
+                                        /**< The iterator will point to the parser start
+                                             position. */
+
+        operator PacketData::iterator() const; ///< Convert to iterator
 
-        bool boolean_test() const;
+        bool boolean_test() const;      ///< Check, if iterator is initialized
 
-        PacketData & data() const;
+        PacketData & data() const;      ///< Access data container
 
     private:
         friend class boost::iterator_core_access;
@@ -186,8 +213,8 @@ namespace senf {
 
 ///////////////////////////////hh.e////////////////////////////////////////
 #endif
-#if !defined(HH_PacketData_DeclOnly) &&!defined(HH_PacketData_def)
-#define HH_PacketData_def
+#if !defined(SENF_PACKETS_DECL_ONLY) && !defined(HH_PacketData_i_)
+#define HH_PacketData_i_
 #include "PacketData.cci"
 //#include "PacketData.ct"
 #include "PacketData.cti"
@@ -204,7 +231,3 @@ namespace senf {
 // comment-column: 40
 // End:
 
-//  LocalWords:  Fraunhofer Institut fuer offene Kommunikationssysteme FOKUS de
-//  LocalWords:  Kompetenzzentrum Satelitenkommunikation SatCom Bund berlios dil
-//  LocalWords:  PacketData hh STL PacketInterpreterBase PacketInterpreter
-//  LocalWords:  ingroup Structors