Packets: Add short documentation for most internal classes

Packets: Document DataPacket, safe_data_iterator and exceptions
Packets: Move bundle documentation out of the Packets documentation
Scheduler: Make test more robust (add sleep ...)
Move all local dictionary words into senf.dict

PPI/Mainpage.dox

@@ -401,4 +401,3 @@
 // mode: auto-fill
 // End:
 
-//  LocalWords:  callbacks

Packets/DataPacket.hh

@@ -32,10 +32,23 @@
 ///////////////////////////////hh.p////////////////////////////////////////
 
 namespace senf {
-    
+
+    /** \brief Internal: Packet type of DataPacket
+
+        \internal
+     */
     struct DataPacketType : public PacketTypeBase
     {};
 
+
+    /** \brief Generic payload-only packet
+        
+        DataPacket is a simple generic packet with just a payload of uninterpreted data. This is the
+        packet used whenever no more specific packet type can be found for a sub-packet (e.g. as the
+        payload data of a UDP packet)
+
+        \ingroup packet_module
+     */
     typedef ConcretePacket<DataPacketType> DataPacket;
 }
 
@@ -58,3 +71,4 @@ namespace senf {
 // ispell-local-dictionary: "american"
 // compile-command: "scons -u test"
 // End:
+

Packets/DefaultBundle/DefaultBundle.dox

@@ -18,18 +18,19 @@
 // Free Software Foundation, Inc.,
 // 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 
-/** \defgroup protocolbundles Protocol Bundles
+/** \mainpage The Default Bundle
 
-    Each protocol bundle provides a collection of related concrete packet classes for a group of
-    related protocols.    
+    The default bundle combines a set of basic low level protocols like Ethernet or IP. You can find
+    the list of implemented protocols at \ref protocolbundle_default (see the list of typedefs)
  */
 
-/** \defgroup protocolbundle_default The Default Bundle
+/** \defgroup protocolbundle_default Protocols of the default bundle
 
-    The default bundle combines a set of basic low level protocols like Ethernet or IP. Find the
-    list of packet types implemented below under 'Typedefs'.
+    Each protocol consists of several objects
 
-    \ingroup protocolbundles
+    \li The packet \c typedef symbol. This is the only object explicitly accessed from the outside
+    \li The associated parser object. This is, where the field names are documented
+    \li The internal packet type object
  */
 
 
@@ -44,6 +45,3 @@
 // mode: auto-fill
 // End:
 
-//  LocalWords:  Fraunhofer Institut fuer offene Kommunikationssysteme FOKUS de
-//  LocalWords:  Kompetenzzentrum Satelitenkommunikation SatCom Bund berlios IP
-//  LocalWords:  defgroup protocolbundles protocolbundle ingroup dil

Packets/DefaultBundle/Doxyfile

+@INCLUDE         = "$(TOPDIR)/doclib/Doxyfile.global"
+
+PROJECT_NAME     = libPackets/DefaultBundle
+TAGFILES         = "$(TOPDIR)/Utils/doc/Utils.tag" "$(TOPDIR)/Packets/doc/Packets.tag"
+GENERATE_TAGFILE = doc/DefaultBundle.tag
+INPUT            = .

Packets/DefaultBundle/SConscript

@@ -11,4 +11,7 @@ SENFSCons.StandardTargets(env)
 
 SENFSCons.Object(env, target = 'DefaultBundle', sources=sources,
                  LIBS = ['Packets', 'Socket', 'Utils'])
+SENFSCons.Lib(env, library = 'Packets_DefaultBundle', sources = sources[0],
+              LIBS = ['Packets', 'Socket', 'Utils'])
                  
+SENFSCons.Doxygen(env)

Packets/Doxyfile

@@ -3,6 +3,7 @@
 PROJECT_NAME     = libPackets
 TAGFILES         = "$(TOPDIR)/Utils/doc/Utils.tag"
 GENERATE_TAGFILE = doc/Packets.tag
-INPUT            = . DefaultBundle MPEG_DVBBundle
+#INPUT            = . DefaultBundle MPEG_DVBBundle
+INPUT            = .
 
-EXAMPLE_PATH     = . DefaultBundle
+#EXAMPLE_PATH     = . DefaultBundle

Packets/MPEG_DVBBundle/Doxyfile

+@INCLUDE         = "$(TOPDIR)/doclib/Doxyfile.global"
+
+PROJECT_NAME     = libPackets/MPEG_DVBBundle
+TAGFILES         = "$(TOPDIR)/Utils/doc/Utils.tag" "$(TOPDIR)/Packets/doc/Packets.tag"
+GENERATE_TAGFILE = doc/MPEG_DVBBundle.tag
+INPUT            = .

Packets/MPEG_DVBBundle/SConscript

@@ -11,4 +11,7 @@ SENFSCons.StandardTargets(env)
 
 SENFSCons.Object(env, target = 'MPEG_DVBBundle', sources=sources,
                  LIBS = ['Packets', 'Socket', 'Utils'])
+SENFSCons.Lib(env, library = 'Packets_MPEG_DVBBundle', sources = sources[0],
+              LIBS = ['Packets', 'Socket', 'Utils'])
                  
+SENFSCons.Doxygen(env)

Packets/Mainpage.dox

@@ -128,6 +128,17 @@
     a detailed discussion see the respective reference documentation.
  */
 
+/** \defgroup protocolbundles Protocol Bundles
+
+    Each protocol bundle provides a collection of related concrete packet classes for a group of
+    related protocols:
+
+    \li <a href="../../DefaultBundle/doc/html/index.html">DefaultBundle</a>: Some basic
+        default protocols: Ethernet, Ip, TCP, UDP
+    \li <a href="../../MPEG_DVBBundle/doc/html/index.html">MPEG_DVBBundle</a>: MPEG and DVB
+        protocols
+ */
+
 
 // Local Variables:
 // mode: c++
@@ -139,8 +150,3 @@
 // compile-command: "scons -u doc"
 // End:
 
-//  LocalWords:  mainpage SENF packetparser protocolbundles protocolbundle IPv4
-//  LocalWords:  udp endcode li senf EthernetPacket eth IpV createAfter ip std
-//  LocalWords:  ethernet UDPPacket DataPacket ttl INet MACAddress nothrow prev
-//  LocalWords:  PacketSocketHandle InvalidPacketChainException findNext noinit
-//  LocalWords:  tt TruncatedPacketException const cerr Ooops hh

Packets/Packet.hh

@@ -599,12 +599,3 @@ namespace senf {
 // comment-column: 40
 // End:
 
-//  LocalWords:  defgroup li html png STL ConcretePacket PacketInterpreterBase
-//  LocalWords:  PacketInterpreter PacketImpl OtherPacket EthernetPacket param
-//  LocalWords:  EthernetPacketType PacketData packetparser nothrow senf prev
-//  LocalWords:  InvalidPacketChainException findNext findPrev parseNextAs tt
-//  LocalWords:  PacketType SomePacketType createAfter createBefore noinit href
-//  LocalWords:  PacketTypeBase TruncatedPacketException http www org Institut
-//  LocalWords:  Fraunhofer fuer offene Kommunikationssysteme FOKUS SatCom Bund
-//  LocalWords:  Kompetenzzentrum Satelitenkommunikation berlios de hh
-//  LocalWords:  addtogroup Structors PacketType dil PacketType's

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;
@@ -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

Packets/PacketImpl.hh

@@ -36,6 +36,15 @@
 namespace senf {
 namespace detail {
     
+    /** \brief Internal: Packet data storage
+        
+        \internal
+
+        This is the class holding the packet data and the interpreter chain. All manipulations of
+        the packet data are performed via the interface exported here. This is very important, since
+        PacketImpl will update the interpreters (that is the vector indices stored therein) whenever
+        the data is changed.
+     */
     class PacketImpl 
         : boost::noncopyable,
           public pool_alloc_mixin<PacketImpl>
@@ -92,9 +101,14 @@ namespace detail {
         void erase(PacketData * self, iterator first, iterator last);
         void clear(PacketData * self);
 
-        // The Guard will keep the PacketImpl instance alive during a members execution time
-        // It the refcount should drop to 0, PacketImpl will be deleted after the member
-        // has completed executing.
+        /** \brief Internal: Keep PacketImpl instance alive
+
+            \internal
+
+            The Guard will keep the PacketImpl instance alive during a members execution time
+            It the refcount should drop to 0, PacketImpl will be deleted after the member
+            has completed executing.
+         */
         struct Guard {
             Guard(PacketImpl * impl);
             ~Guard();
@@ -108,7 +122,6 @@ namespace detail {
 
         void eraseInterpreters(interpreter_list::iterator b, interpreter_list::iterator e);
         void updateIterators(PacketData * self, iterator pos, difference_type n);
-
     };
 
 }}
@@ -132,3 +145,4 @@ namespace detail {
 // compile-command: "scons -u test"
 // comment-column: 40
 // End:
+

Packets/PacketInterpreter.hh

@@ -42,7 +42,12 @@ namespace senf {
 
     template <class PacketType> class PacketInterpreter;
 
-    /** \brief
+    /** \brief Internal: Base packet interpreter class
+        
+        \internal
+
+        This is the base class for the persistent interpreter. This class encapsulates all the
+        functionality accessible via the packet handle, most handle operations are just forwarded.
       */
     class PacketInterpreterBase
         : protected PacketData, 
@@ -70,6 +75,14 @@ namespace senf {
         enum Prepend_t { Prepend };
         enum NoInit_t { noinit };
 
+        /** \brief Internal: Abstract packet factory
+
+            \internal
+
+            This abstract class provides an abstract packet factory interface. It allows to call
+            almost any one of the create / createAfter / createBefore static PacketInterpreter
+            without static information on the type of packet to create.
+         */
         struct Factory { 
             virtual ~Factory();
 
@@ -169,7 +182,7 @@ namespace senf {
         ptr appendClone(detail::PacketImpl * impl, range r);
 
     public:
-        // Need this for g++ < 4.0. Since PacketInterpreter is not publically visible, it should not
+        // Need this for g++ < 4.0. Since PacketInterpreter is not publicly visible, it should not
         // be a real problem to make impl() public here
         using PacketData::impl;
 
@@ -201,7 +214,13 @@ namespace senf {
         friend class detail::packet::test::TestDriver;
     };
 
-    /** \brief Concrete packet interpreter
+    /** \brief Internal: Concrete packet interpreter
+
+        \internal
+
+        Instantiations of this class build the interpreter chain. This class is accessed by the
+        packet handles. It provides the packet-type specific functionality in addition to the
+        interface defined in the PacketInterpreterBase class.
 
         \see PacketTypeBase for the \a PacketType interface
       */
@@ -301,6 +320,12 @@ namespace senf {
 
         // factory
 
+        /** \brief Internal: Implementation of abstract factory interface
+            
+            \internal
+
+            Implements the abstract factory interface for \a PacketType
+         */
         struct FactoryImpl : public Factory {
             // Create completely new packet
 
@@ -346,6 +371,11 @@ namespace senf {
         friend class FactoryImpl;
     };
 
+    /** \brief Invalid packet chain operation
+
+        This exception signals an invalid operation on the chain like trying to find a non-existent
+        chain member and other similar error conditions. 
+     */
     struct InvalidPacketChainException : public std::exception
     { virtual char const * what() const throw() { return "invalid packet chain"; } };
     

Packets/PacketParser.hh

@@ -516,6 +516,8 @@ namespace senf {
 #   define SENF_PACKET_PARSER_DEFINE_FIXED_FIELDS_OFFSET(offset,fields)                           \
     SENF_PACKET_PARSER_I_DEFINE_FIXED_FIELDS(offset,fields)
 
+    /** \brief Default parser parsing nothing
+     */
     struct VoidPacketParser 
         : public PacketParserBase
     {
@@ -599,13 +601,3 @@ namespace senf {
 // comment-column: 40
 // End:
 
-//  LocalWords:  templated PacketParser defgroup packetparser PacketParsers li
-//  LocalWords:  EthernetParser ethertype UInt senf PacketParserBase tt
-//  LocalWords:  struct FooParser const init endcode ingroup param SomeParser
-//  LocalWords:  ethernet DefaultBundle EthernetPacket hh EthVLan UIntField CFI
-//  LocalWords:  VLanId OverlayField cfi vlanId accessor defaultInit bitfield
-//  LocalWords:  SomePacket SimpleVectorSizer packetparsermacros Fraunhofer std
-//  LocalWords:  hideinitializer Institut fuer offene Kommunikationssysteme STL
-//  LocalWords:  FOKUS Kompetenzzentrum Satelitenkommunikation SatCom Bund cerr
-//  LocalWords:  berlios dil Structors someField someVector someOtherField
-//  LocalWords:  TruncatedPacketException

Packets/PacketRegistry.hh

@@ -193,6 +193,10 @@ packet of which the key is requested
         static Registry & registry();
     };
 
+    /** \brief Entry not found in registry
+
+        This exception is signaled whenever a throwing lookup operation fails.
+     */
     struct PacketTypeNotRegisteredException : public std::exception
     { virtual char const * what() const throw() { return "packet type not registered"; } };
 
@@ -218,10 +222,3 @@ packet of which the key is requested
 // comment-column: 40
 // End:
 
-//  LocalWords:  PacketRegistry hh dil Fraunhofer Institut fuer offene FOKUS de
-//  LocalWords:  Kommunikationssysteme Kompetenzzentrum Satelitenkommunikation
-//  LocalWords:  SatCom Bund stefan bund fokus fraunhofer Ethertype IP struct
-//  LocalWords:  SomeTag endcode senf SomePacket registerPacket ingroup param
-//  LocalWords:  registerSomePacket RegistrationProxy namespace PacketType key
-//  LocalWords:  registerPacketType ConcretePacket PacketTypeNotRegistered href
-//  LocalWords:  http www org html

Packets/PacketRegistry.ih

@@ -35,7 +35,9 @@
 namespace senf {
 namespace detail {
     
-    ///\internal
+    /** \brief Internal
+        \internal
+     */
     template <class PacketType>
     struct PkReg_EntryImpl
         : public PkReg_Entry
@@ -43,7 +45,9 @@ namespace detail {
         virtual Packet::factory_t factory() const;
     };
 
-    ///\internal
+    /** \brief Internal
+        \internal
+     */
     template <class KeyType>
     class PacketRegistryImpl 
         : private boost::noncopyable

Packets/PacketType.hh

@@ -321,6 +321,8 @@ namespace senf {
         static void                                  init            (Packet p);
     };
 
+#   ifndef DOXYGEN
+
     template <class Self>
     class PacketTypeMixin<Self,void>
     {
@@ -330,6 +332,8 @@ namespace senf {
         static void                                  init            (Packet p);
     };
 
+#   endif
+
 }
 
 ///////////////////////////////hh.e////////////////////////////////////////
@@ -352,11 +356,3 @@ namespace senf {
 // comment-column: 40
 // End:
 
-//  LocalWords:  Fraunhofer Institut fuer offene Kommunikationssysteme FOKUS de
-//  LocalWords:  Kompetenzzentrum Satelitenkommunikation SatCom Bund berlios dil
-//  LocalWords:  PacketType struct SomePacketType senf PacketTypeBase initSize
-//  LocalWords:  ConcretePacket init initHeadSize nextPacketRange NextPacket os
-//  LocalWords:  nextPacketType std ostream endcode ingroup VoidPacketParser Ok
-//  LocalWords:  tt li OtherPacketType Mixin mixin SimplePacketType typeField
-//  LocalWords:  PacketTypeMixin SomeRegistryTag SomePacketParser nextPacketKey
-//  LocalWords:  hh

Packets/PacketTypes.hh

@@ -45,6 +45,10 @@ namespace detail {
 
 namespace packet {
 
+    /** \brief Internal: Tempalte typedef for used smart pointer
+
+        \internal
+     */
     template <class T>
     struct smart_pointer {
         typedef boost::intrusive_ptr<T> ptr_t;

Scheduler/Scheduler.test.cc

+
 // $Id$
 //
 // Copyright (C) 2006
@@ -240,6 +241,7 @@ BOOST_AUTO_UNIT_TEST(scheduler)
 
     BOOST_CHECK_NO_THROW( Scheduler::instance().remove(handle,Scheduler::EV_WRITE) );
     event = Scheduler::EV_NONE;
+    sleep(1);
     BOOST_CHECK_NO_THROW( Scheduler::instance().process() );
     BOOST_CHECK_EQUAL( event, Scheduler::EventId(Scheduler::EV_READ|Scheduler::EV_HUP) );
     BOOST_REQUIRE_EQUAL( size, 2 );

project.el

@@ -77,4 +77,6 @@ is ignored (Those are the file local variables and local words)."
 
 ;; Better set this here than in the file variables since the setting
 ;; is only valid if project.el is loaded ...
+(set (make-local-variable 'ispell-personal-dictionary)
+     (expand-file-name "senf.dict" ccide-project-root))
 (flyspell-cc-mode)