Packets/DefaultBundle: Fix packet parser documentation using #ifndef DOXYGEN guards

[senf.git] / Packets / DefaultBundle / EthernetPacket.hh

diff --git a/Packets/DefaultBundle/EthernetPacket.hh b/Packets/DefaultBundle/EthernetPacket.hh
index ffa1f4b..ebb07ae 100644 (file)
--- a/Packets/DefaultBundle/EthernetPacket.hh
+++ b/Packets/DefaultBundle/EthernetPacket.hh
@@ -33,9 +33,12 @@
 
 namespace senf {
 
-    ///\addtogroup protocolbundle_default
-    ///@{
+    /** \brief Ethernet MAC address
+        
+        The Ethernet MAC is modelled as a fixed-size container/sequence of 6 bytes.
 
+        \todo Move to someplace else when implementing the addressing classes
+     */
     struct MACAddress
         : boost::array<PacketParserBase::byte,6>
     {
@@ -47,6 +50,13 @@ namespace senf {
         { virtual char const * what() const throw() { return "invalid mac address syntax"; } };
     };
 
+    /** \brief Parse an Ethernet MAC address 
+
+        The ethernet MAC is returned by value as a 6-byte sequence
+
+        \see MACAddress \n
+            EthernetPacket
+     */
     struct Parse_MAC : public PacketParserBase
     {
         Parse_MAC(data_iterator i, state_type s) : PacketParserBase(i,s,fixed_bytes) {}
@@ -63,26 +73,60 @@ namespace senf {
 
         Parse_MAC const & operator= (value_type const & other) { value(other); return *this; }
     };
+    
+    /** \brief Parse an Ethernet packet
 
+        Parser implementing an ethernet header.
+
+        \see EthernetPacketType
+     */
     struct Parse_Ethernet : public PacketParserBase
     {
-        SENF_PACKET_PARSER_INIT(Parse_Ethernet);
+        typedef Parse_UInt16                      Parse_Type;
 
-        ///////////////////////////////////////////////////////////////////////////
+#       ifndef DOXYGEN
 
-        typedef Parse_UInt16                      Parse_Type;
+        SENF_PACKET_PARSER_INIT(Parse_Ethernet);
 
         SENF_PACKET_PARSER_DEFINE_FIXED_FIELDS(
             ((Field)( destination, Parse_MAC  ))
             ((Field)( source,      Parse_MAC  ))
             ((Field)( type,        Parse_Type )) );
+
+#       else
+
+        Parse_MAC destination();
+        Parse_MAC source();
+        Parse_Type type();
+
+#       endif
     };
 
+    /** \brief EtherType registry
+
+        This registry registers packet types with their EtherType number.
+        
+        \see <a href="http://www.iana.org/assignments/ethernet-numbers">Ethernet numbers</a>
+         \ref PacketRegistry
+     */
     struct EtherTypes {
-        // See http://www.iana.org/assignments/ethernet-numbers
+        // See 
         typedef boost::uint16_t key_t;
     };
 
+    /** \brief Ethernet packet
+
+        \par Packet type (typedef):
+            \ref EthernetPacket
+
+        \par Fields:
+            \ref Parse_Ethernet
+
+        \par Associated registries:
+            \ref EtherTypes
+
+        \ingroup protocolbundle_default
+     */
     struct EthernetPacketType
         : public PacketTypeBase,
           public PacketTypeMixin<EthernetPacketType, EtherTypes>
@@ -104,26 +148,55 @@ namespace senf {
         static void dump(packet p, std::ostream & os);
     };
 
+    /** \brief Ethernet packet typedef */
     typedef EthernetPacketType::packet EthernetPacket;
 
+    /** \brief Parse an ethernet VLAN tag
+        
+        Parser interpreting the ethernet VLAN tag. Fields are
+
+        \see EthVLanPacketType
+     */
     struct Parse_EthVLan : public PacketParserBase
     {
-        SENF_PACKET_PARSER_INIT(Parse_EthVLan);
-
-        ///////////////////////////////////////////////////////////////////////////
-
         typedef Parse_UIntField < 0,  3 > Parse_Priority;
         typedef Parse_Flag          < 3 > Parse_CFI;
         typedef Parse_UIntField < 4, 16 > Parse_VLanId;
         typedef Parse_UInt16              Parse_Type;
 
+#       ifndef DOXYGEN
+
+        SENF_PACKET_PARSER_INIT(Parse_EthVLan);
+
         SENF_PACKET_PARSER_DEFINE_FIXED_FIELDS(
             ((OverlayField)( priority, Parse_Priority ))
             ((OverlayField)( cfi,      Parse_CFI      ))
             ((Field       )( vlanId,   Parse_VLanId   ))
             ((Field       )( type,     Parse_Type     )) );
+
+#       else
+
+        Parse_Priority priority();
+        Parse_CFI cfi();
+        Parse_VLanId vlanId();
+        Parse_Type type();
+
+#       endif
     };
 
+    /** \brief Ethernet VLAN tag
+
+        \par Packet type (typedef):
+            \ref EthVLanPacket
+
+        \par Fields:
+            \ref Parse_EthVLan
+
+        \par Associated registries:
+            \ref EtherTypes
+
+        \ingroup protocolbundle_default
+     */
     struct EthVLanPacketType
         : public PacketTypeBase, 
           public PacketTypeMixin<EthVLanPacketType, EtherTypes>
@@ -145,9 +218,8 @@ namespace senf {
         static void dump(packet p, std::ostream & os);
     };
 
+    /** \brief Ethernet VLAN tag typedef */
     typedef EthVLanPacketType::packet EthVLanPacket;
-
-    ///@}
 }