Packets: Document Parse_List, Parse_ListB and Parse_ListN

Packets/PacketRegistry.ih

@@ -35,7 +35,8 @@
 namespace senf {
 namespace detail {
     
-    /** \brief Internal
+    /** \brief Internal: Registry entry implementation for a specific packet type
+
         \internal
      */
     template <class PacketType>

Packets/ParseArray.cti

@@ -20,7 +20,8 @@
 // Free Software Foundation, Inc.,
 // 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 
-// Definition of inline template functions
+/** \file
+    \brief ParseArray inline template implementation */
 
 #include "ParseArray.ih"
 

Packets/ParseArray.hh

@@ -20,6 +20,9 @@
 // Free Software Foundation, Inc.,
 // 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 
+/** \file
+    \brief ParseArray public header */
+
 #ifndef HH_ParseArray_
 #define HH_ParseArray_ 1
 

Packets/ParseArray.ih

@@ -20,6 +20,9 @@
 // Free Software Foundation, Inc.,
 // 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 
+/** \file
+    \brief ParseArray internal header */
+
 #ifndef IH_ParseArray_
 #define IH_ParseArray_ 1
 

Packets/ParseInt.hh

@@ -20,6 +20,9 @@
 // Free Software Foundation, Inc.,
 // 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 
+/** \file
+    \brief ParseInt public header */
+
 #ifndef HH_ParseInt_
 #define HH_ParseInt_ 1
 

Packets/ParseInt.ih

@@ -20,6 +20,9 @@
 // Free Software Foundation, Inc.,
 // 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 
+/** \file
+    \brief ParseInt internal header */
+
 #ifndef IH_ParseInt_
 #define IH_ParseInt_ 1
 

Packets/ParseList.hh

@@ -39,7 +39,23 @@ namespace senf {
     template <class ListPolicy>
     class Parse_List_Container;
 
-    /** \brief
+    /** \brief Arbitrary sequential element collection
+
+        A List is a sequential collection of elements. The element type is given as an arbitrary
+        parser. The list is more flexible than a vector: It is not limited to fixed-size elements
+        and it might not have direct access to the size of the collection. 
+
+        The cost is however, that a List is only a model of an STL forward sequence. The parser
+        provides a reduced interface to this sequence, the container wrapper provides the complete
+        interface.
+
+        Pare_List makes use of a policy template argument, \a ListPolicy, to customize the way the
+        list is laid out. This policy is given quite some freedom in the list
+        implementation. It is however important, that list elements <em>always follow each other
+        without padding</em> (if padding is needed, it needs to be part of the element parser).
+
+        \see ExampleListPolicy
+        \ingroup parsecollection
       */
     template <class ListPolicy>
     class Parse_List 
@@ -49,6 +65,9 @@ namespace senf {
     public:
         Parse_List(data_iterator i, state_type s);
         Parse_List(ListPolicy policy, data_iterator i, state_type s);
+                                        ///< Additional policy specific constructor
+                                        /**< This constructor may be used, if the policy needs
+                                             additional parameters. */
 
         size_type bytes() const;
         void init() const;
@@ -84,7 +103,7 @@ namespace senf {
         template <class Policy> friend class Parse_List_Container;
     };
 
-    /** \brief Exmaple of a list policy. ONLY FOR EXPOSITION.
+    /** \brief Example of a list policy. ONLY FOR EXPOSITION.
         
         This class shows the interface which must be implemented by a list policy. It is not a list
         policy only a declaration of the interface:
@@ -125,7 +144,7 @@ namespace senf {
         \endcode
 
         If necessary, you may use a different policy in the container_type. The ListPolicy must
-        define the elements bytes(), size() and init(), the container policy needs all theese and
+        define the elements bytes(), size() and init(), the container policy needs all these and
         additionally needs erase() and insert(). The container policy will also need the
         element_type, parser_type and container_type typedefs.
         
@@ -156,7 +175,7 @@ namespace senf {
 
         size_type bytes(iterator i, state_type s) const; ///< Size of list in bytes
                                         /**< Return the complete size of the list in
-                                             bytes. Depending on the type of list, thie call may
+                                             bytes. Depending on the type of list, this call may
                                              need to completely traverse the list ... */
 
         size_type size(iterator i, state_type s) const; ///< Number of elements in list
@@ -173,13 +192,13 @@ namespace senf {
         void erase(iterator i, state_type s, iterator p) const; ///< Erase element from list
                                         /**< Delete the list element at p from the List (i,s). When
                                              this operation is called, the element is still part of
-                                             the list. This call must update the metadata as
+                                             the list. This call must update the meta-data as
                                              needed. The data will be removed after this call
                                              returns. */
 
         void insert(iterator i, state_type s, iterator p) const; ///< Insert element into list
                                         /**< This is called after an element has been inserted at p
-                                             into the List (i,s) to update the metadata. */
+                                             into the List (i,s) to update the meta-data. */
 
         /** \brief Example of a list iterator policy. ONLY FOR EXPOSITION.
 
@@ -234,6 +253,24 @@ namespace senf {
         };
     };
 
+    /** \brief Parse_List container wrapper
+
+        This is the container wrapper used for list parsers. The container wrapper will stay valid
+        after changing the collection. However the container still depends on the packet and will be
+        invalidated if the Packet is deallocated or if the packet size is changed from without the
+        container wrapper (more precisely, it is invalided if the insertion/deletion happens before
+        the vector in the packet data).
+
+        The vector container wrapper provides a complete STL random-access sequence interface.
+        
+        \code
+        SomePacket p (...);
+        SomePacket::aListCollection_t::container c (p->aListCollection());
+        c.insert(c.begin(), ... );
+        \endcode
+
+        \see Parse_List
+      */
     template <class ListPolicy>
     class Parse_List_Container
         : private ListPolicy

Packets/ParseList.ih

@@ -32,6 +32,10 @@
 namespace senf {
 namespace detail {
 
+    /** \brief Internal: Iterator used by Parse_List
+
+        \internal
+     */
     template <class ElementParser, class IteratorPolicy>
     class Parse_List_Iterator
         : public boost::iterator_facade< Parse_List_Iterator<ElementParser,IteratorPolicy>,

Packets/ParseListB.hh

@@ -38,10 +38,10 @@ namespace senf {
     /** \brief List parser with size-field in bytes
 
         This list parser will parse a list which size is given by a preceding field containing the
-        lenght of the list in bytes. This struct is just a template typedef:
+        length of the list in bytes. This struct is just a template typedef:
         \code
-          typedef senf::Parse_VectorN< Parser_UInt32, Parser_UInt16 >::parser Parse_MyVector;
-          typedef senf::Parse_ListB< Parse_MyVector, Parse_UInt16 >::parser Parse_MyList;
+        typedef senf::Parse_VectorN< Parser_UInt32, Parser_UInt16 >::parser Parse_MyVector;
+        typedef senf::Parse_ListB< Parse_MyVector, Parse_UInt16 >::parser Parse_MyList;
         \endcode
         This first defines a Vector of 32 bit unsigned integers with 16 bit length counter. Then it
         defines a list of such vectors with a 16 bit bytes field.
@@ -49,13 +49,16 @@ namespace senf {
         \warning There are some caveats when working with this kind of list
         \li You may <b>only change the size of a contained element from a container wrapper</b>.
         \li While you hold a container wrapper, <b>only access the packet through this wrapper</b>
-            or a nested wrepper either for reading or writing.
+            or a nested wrapper either for reading or writing.
 
         If lists are nested, you need to allocate a container wrapper for each level and may only
         access the packet through the lowest-level active container wrapper.
 
         \implementation These restrictions are necessary to ensure correct recalculation of the
             <tt>bytes</tt> field. For more info, see the comments in \ref ParseListB.ih
+
+        \see Parse_List
+        \ingroup parsecollection
      */
     template <class ElementParser, class BytesParser>
     struct Parse_ListB {

Packets/ParseListB.ih

@@ -31,7 +31,7 @@
 namespace senf {
 namespace detail {
 
-    /** \brief ListPolicy defing the Parse_ListB parser
+    /** \brief Internal: ListPolicy defing the Parse_ListB parser
         \internal
         \see \ref Parse_ListB
      */
@@ -76,7 +76,10 @@ namespace detail {
         size_type bytes  (iterator i, state_type s) const;
         size_type size   (iterator i, state_type s) const;
         void      init   (iterator i, state_type s) const;
-
+        
+        /** \brief Internal: Parse_ListB_Policy's iterator policy
+            \internal
+         */
         struct iterator_policy
         {
             iterator setBegin        (iterator i, state_type s);
@@ -86,6 +89,9 @@ namespace detail {
             iterator raw             (iterator i, state_type s) const;
         };
 
+        /** \brief Internal: Parse_ListB_Policy's container policy
+            \internal
+         */
         struct container_policy
         {
             typedef typename Parse_ListB_Policy<

Packets/ParseListN.hh

+
 // Copyright (C) 2007 
 // Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS)
 // Kompetenzzentrum fuer Satelitenkommunikation (SatCom)
@@ -35,6 +36,20 @@ namespace senf {
     namespace detail { template <class ElementParser, class SizeParser>
                        class Parse_ListN_Policy; }
 
+    /** \brief List parser with size-field giving number of list elements
+
+        This parser will parse a list which size is giving by a preceding field containing the
+        number of list elements. This struct is just a 'template typedef':
+        \code
+        senf::Parse_VectorN< Parser_UInt32, Parser_UInt16 >::parser Parse_MyVector;
+        senf::Parse_ListN< Parse_MyVector, Parse_UInt16 >::parser Parse_MyList;
+        \endcode
+        This first defines a Vector of 32 bit unsigned integers with 16 bit length counter. Then it
+        defines a list of such vectors with a 16 bit size field.
+
+        \see Parse_List
+        \ingroup parsecollection
+     */
     template <class ElementParser, class SizeParser>
     struct Parse_ListN {
         typedef Parse_List< detail::Parse_ListN_Policy<ElementParser,SizeParser> > parser;

Packets/ParseListN.ih

@@ -31,6 +31,10 @@
 namespace senf {
 namespace detail {
 
+    /** \brief Internal: ListPolicy defining the Parse_ListN parser
+        \internal
+        \see \ref Parse_ListN
+     */
     template <class ElementParser, class SizeParser>
     struct Parse_ListN_Policy
     {
@@ -50,6 +54,9 @@ namespace detail {
         void      insert (iterator i, state_type s, iterator p) const;
         void      update (iterator i, state_type s) const;
 
+        /** \brief Iternal: Parse_ListN_Policy's iterator policy
+            \internal
+         */
         struct iterator_policy
         {
             iterator setBegin        (iterator i, state_type s);

Packets/ParseVec.ct

@@ -20,7 +20,8 @@
 // Free Software Foundation, Inc.,
 // 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 
-// Definition of non-inline template funPacketRegistry.ons
+/** \file
+    \brief ParseVec non-inline template implementation */
 
 #include "ParseVec.ih"
 

Packets/ParseVec.cti

@@ -20,7 +20,8 @@
 // Free Software Foundation, Inc.,
 // 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 
-// Definition of inline template functions
+/** \file
+    \brief ParseVec inline template implementation */
 
 #include "ParseVec.ih"
 

Packets/ParseVec.hh

@@ -20,6 +20,9 @@
 // Free Software Foundation, Inc.,
 // 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 
+/** \file
+    \brief ParseVec public header */
+
 #ifndef HH_ParseVec_
 #define HH_ParseVec_ 1
 
@@ -47,7 +50,7 @@ namespace senf {
         A vector is a model of an STL random-access sequence. The parser only provides a reduced
         interface, the container wrapper however completes this interface.
 
-        Parse_Vector makes use of a policy template argument, \a Sizer to customize the way the
+        Parse_Vector makes use of a policy template argument, \a Sizer, to customize the way the
         containers size is obtained. You will normally not instantiate Parser_Vector directly, you
         will use one of the 'template typedefs' (which are templated structures since C++ does not
         provide real template typedefs) provided with the policy implementations.
@@ -203,6 +206,8 @@ namespace senf {
         SomePacket::aVectorCollection_t::container c (p->aVectorCollection());
         c.insert(c.begin(), ... );
         \endcode
+
+        \see Parse_Vector
       */
     template <class ElementParser, class Sizer>
     class Parse_Vector_Container

senf.dict

 accessor
 addtogroup
+aListCollection
 aVectorCollection
 BaseParser
 berlios
@@ -28,6 +29,7 @@ EthernetPacketType
 EthernetParser
 ethertype
 EthVLan
+ExampleListPolicy
 ExampleVectorPolicy
 ExtendedParser
 findNext
@@ -41,6 +43,7 @@ hideinitializer
 href
 html
 http
+ih
 impl
 INet
 ingroup
@@ -58,9 +61,13 @@ key
 Kommunikationssysteme
 Kompetenzzentrum
 li
+ListB
+ListN
+ListPolicy
 MACAddress
 mainpage
 mixin
+MyList
 MyVector
 namespace
 NextPacket
@@ -98,6 +105,9 @@ ParseArray
 parsecollection
 parseint
 ParseInt
+ParseList
+ParseListB
+ParseListN
 parseNextAs
 ParseVec
 png
@@ -114,6 +124,9 @@ SafePacketParser
 SatCom
 Satelitenkommunikation
 senf
+setBegin
+setEnd
+setFromPosition
 SimplePacketType
 SimpleVectorSizer
 SizeParser

senfscons/SENFSCons.py

@@ -408,7 +408,8 @@ def Doxygen(env, doxyfile = "Doxyfile", extra_sources = []):
                                     " --stringparam module $MODULE" +
                                     " --stringparam type $TYPE" +
                                     " ${SOURCES[1]} $SOURCE || touch $TARGET" ],
-                                  MODULE = xmlnode.dir.dir.dir.name,
+                                  MODULE = xmlnode.dir.dir.dir.abspath[
+                                               len(env.Dir('#').abspath)+1:],
                                   TYPE = type)
             env.SideEffect(xref, xmlnode)
             env.AddPreAction(docs, "rm -f %s" % (xref,))