Packets: senf::Parse_Variant documentation

[senf.git] / Packets / ParseVariant.dox

diff --git a/Packets/ParseVariant.dox b/Packets/ParseVariant.dox
index d9153e5..3747a03 100644 (file)
--- a/Packets/ParseVariant.dox
+++ b/Packets/ParseVariant.dox
@@ -22,19 +22,71 @@
 
 namespace senf {
 
+    /** \brief Example of a variant policy. ONLY FOR EXPOSITION
+
+        This class shows the interace which must be impemented by a variant policy. It is \e not a
+        variant policy, it is only a declaration of the interface:
+        \code
+        struct ExampleVariantPolicy
+        {
+            // optional typedefs used tosimplify all other declarations
+            typedef PacketParserBase::data_iterator data_iterator;
+            typedef PacketParserBase::state_type state_type;
+            typedef PacketParserBase::size_type size_type;
+
+            // mandatory members
+            static size_type const init_bytes = 0;
+            size_type bytes  (data_iterator i, state_type s) const;
+
+            data_iterator begin(data_iterator i, state_type s) const;
+
+            unsigned variant (data_iterator i, state_type s) const;
+            void variant     (unsigned v, data_iterator i, state_type s);
+        };
+        \endcode
+
+        The \a VariantPolicy may define additional data members if needed. It must be either default
+        constructible or copy constructible. If a \a VariantPolicy is not default constructible, an
+        additional \a VariantPolicy argument needs to be passed to the senf::Parse_Variant
+        constructor which is used to copy-initialize the embeded policy.
+
+        \see senf::Parse_Variant
+     */
     struct ExampleVariantPolicy
     {
-        // optional typedefs used to simplify all other declarations
         typedef PacketParserBase::data_iterator data_iterator;
         typedef PacketParserBase::state_type state_type;
         typedef PacketParserBase::size_type size_type;
 
-        static size_type const init_bytes = 0;
+        static size_type const init_bytes = 0; ///< Additional initial size
+                                        /**< This value is added to the size of the first variant
+                                             sub-parser to calculate the \c init_bytes value. */
+
         size_type bytes  (data_iterator i, state_type s) const;
+                                        ///< Additional parser size
+                                        /**< The return value is added to the size of the current
+                                             variant. */
+
         data_iterator begin(data_iterator i, state_type s) const;
+                                        ///< Advance \a i to beginning of variant data
+                                        /**< This member must return the beginning of the variant's
+                                             data (the place, where the sub-parsers reside in the
+                                             packet). */
 
         unsigned variant (data_iterator i, state_type s) const;
+                                        ///< Get current variant index
+                                        /**< \returns current variant sub-parser, interpreted as
+                                             index into the 0-indexed list of sub-parsers. */
+
         void variant     (unsigned v, data_iterator i, state_type s);
+                                        ///< Set current variant index
+                                        /**< Must set the current variant to \a v which is the index
+                                             into the 0-index list of sub-parsers of the currently
+                                             active variant sub-parser.
+
+                                             This member must not process the sub-parser data (like
+                                             initializing the sub-parser or changing the data
+                                             container size). */
     };
 
 }