X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=Packets%2FParseArray.hh;h=8dfca23640075a1c15df30ac68c18992c29e8e78;hb=81ffa1c459b96dd44472bcef37e1e373934ee138;hp=851486ac2e5686268251a6c597be98d0af099b28;hpb=47368f306a577d1e46df69a7f729bd3893cbe5e7;p=senf.git

diff --git a/Packets/ParseArray.hh b/Packets/ParseArray.hh
index 851486a..8dfca23 100644
--- a/Packets/ParseArray.hh
+++ b/Packets/ParseArray.hh
@@ -20,9 +20,36 @@
 // 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
 
+/** \defgroup parsecollection Collection parsers
+
+    Collection parsers are parsers which build collections from other parsers. Examples are a vector
+    of 16bit unsigned integers or a list of lists of 32bit numbers and so on.
+
+    Collection parsers provide a (reduced) STL sequence like interface. It depends on the type of
+    collection parser, what kind of sequence is modelled (e.g. random access sequence, forward
+    sequence etc). Most collections will also provide a kind of container wrapper to allow extensive
+    manipulations of the collection contents. A container wrapper is initialized with the collection
+    parser and then provides a more complete sequence interface. Additionally, the collection
+    wrapper has a longer lifetime than an ordinary parser: While a parser will be invalidated
+    whenever the collection is changed, the container wrapper will stay valid as long as the
+    collection is changed through the wrapper (directly or indirectly, where indirectly means that a
+    sub-field or sub-collection of the collection is changed). Some collections may provide even
+    more lifetime guarantees but this guarantee should be met by all collection wrappers.
+
+    \important Parser lifetime has to be tightly checked when working with collection parsers since
+    \e every change of the collections size will invalidate \e all parsers and iterators referencing
+    the \e complete packet chain. Collection wrappers do \e not invalidate if the change is \e after
+    the collection.
+
+    \ingroup packetparser
+*/
+
 // Custom includes
 #include "PacketParser.hh"
 
@@ -33,7 +60,16 @@ namespace senf {
 
     namespace detail { template <class> class Parse_Array_iterator; }
 
-    /* Parse_Array has the external interface of a container class
+    /** \brief Fixed size collection of fixed size elements
+
+        Parse_Array will parse a sequence of <em>fixed size</em> parsers. The number of array
+        elements is given by the \e elements template parameter and is fixed at compile time. 
+        
+        Each element will be parsed by \a ElementParser, which can be any <em>fixed size</em>
+        parser. The array models an STL random-access sequence with the restriction that elements
+        cannot be added or removed since the size is fixed.
+
+        \ingroup parsecollection
      */
     template <unsigned elements, class ElementParser>
     struct Parse_Array : public PacketParserBase
@@ -62,6 +98,9 @@ namespace senf {
 }
 
 ///////////////////////////////hh.e////////////////////////////////////////
+#endif
+#if !defined(SENF_PACKETS_DECL_ONLY) && !defined(HH_ParseArray_i_)
+#define HH_ParseArray_i_
 //#include "ParseArray.cci"
 //#include "ParseArray.ct"
 #include "ParseArray.cti"
@@ -75,4 +114,5 @@ namespace senf {
 // indent-tabs-mode: nil
 // ispell-local-dictionary: "american"
 // compile-command: "scons -u test"
+// comment-column: 40
 // End: