Implemented global cross-reference generation

Updated documentation templates to include cross-reference
Fixed documentation build (especially regarding cleanup)
Cleaned up BUG, FIXME, TODO and IDEA items
More SocketLibrary documentation

Doxyfile

@@ -5,6 +5,7 @@ OUTPUT_DIRECTORY       = doc
 INPUT                  = .
 FILE_PATTERNS          = *.dox
 IMAGE_PATH             = .
+EXAMPLE_PATH           = Sniffer
 HTML_HEADER            = doclib/doxy-header-overview.html
 HTML_FOOTER            = doclib/doxy-footer.html
 GENERATE_LATEX         = NO

Mainpage.dox

@@ -30,6 +30,7 @@
 
     \see \ref usage\n
          \ref example\n
+         <a href="xref.html">Current status: Cross reference of action points</a>\n
          <a class="ext" href="http://developer.berlios.de/projects/senf">The BerliOS project page</a>\n
          <a class="ext" href="http://openfacts.berlios.de/index-en.phtml?title=SENF+Network+Framework">The SENF Wiki at BerliOS</a>
 */

Packets/EthernetPacket.cc

@@ -40,8 +40,8 @@ namespace {
 prefix_ void senf::EthernetPacket::v_nextInterpreter()
     const
 {
-    // TODO: Add LLC/SNAP support -> only use the registry
-    // for type() values >=1536, otherwise expect an LLC header
+    /** \todo Add LLC/SNAP support -> only use the registry
+	for type() values >=1536, otherwise expect an LLC header */
     registerInterpreter(type(),begin()+bytes(),end());
 }
 
@@ -85,8 +85,7 @@ prefix_ void senf::EthernetPacket::v_finalize()
 prefix_ void senf::EthVLanPacket::v_nextInterpreter()
     const
 {
-    // TODO: Add LLC/SNAP support -> only use the registry
-    // for type() values >=1536, otherwise expect an LLC header
+    /** \todo Add LLC/SNAP support (see above) */
     registerInterpreter(type(),begin()+bytes(),end());
 }
 

Packets/GenericPacket.ct

@@ -44,7 +44,7 @@ template <unsigned HEADER, unsigned TRAILER>
 prefix_ void senf::GenericPacket<HEADER,TRAILER>::v_dump(std::ostream & os)
     const
 {
-    // TODO: implement v_dump()
+    /// \todo implement v_dump()
 }
 
 ///////////////////////////////ct.e////////////////////////////////////////

Packets/Packet.cc

@@ -187,8 +187,8 @@ prefix_ senf::Packet::ptr senf::Packet::next()
     if (n == this->impl_->interpreters_.end()) {
         if (this->parsed_)
             return ptr(0);
-        // FIXME: v_nextInterpreter return bool? new Interpreter to be
-        // added ? hmm ... this however is quite suboptimal ...
+        /* \fixme v_nextInterpreter return bool? new Interpreter to be
+	   added ? hmm ... this however is quite suboptimal ... */
         this->v_nextInterpreter();
         this->parsed_ = true;
         n = boost::next(this->self_);
@@ -270,8 +270,8 @@ prefix_ void senf::Packet::erase(iterator first, iterator last)
     size_type index(first-impl_->data_.begin());
     size_type sz(last-first);
     BOOST_ASSERT( index >= begin_ && index < end_ && sz <= end_-index );
-    // FIXME: Here we should assert, that no bytes belonging to the
-    // next iterator are deleted ...
+    /** \fixme Here we should assert, that no bytes belonging to the
+	next iterator are deleted ... */
     impl_->data_.erase(first,last);
     impl_->updateIterators(index,-sz,self_,INSIDE);
 }

Packets/Packet.cci

@@ -154,10 +154,10 @@ prefix_ senf::Packet::ptr senf::Packet::head()
 
 prefix_  senf::Packet::~Packet()
 {
-    // FIXME: This is bad ... we cannot check this since this
-    // assertion fails at the moment if the Packet constructor throws
-    // ... hrmpf ... we really need to initialize refcount_ to 0 and
-    // remove the 'false' argument to the ptr constructor in ::create
+    /** \fixme This is bad ... we cannot check this since this
+	assertion fails at the moment if the Packet constructor throws
+	... hrmpf ... we really need to initialize refcount_ to 0 and
+	remove the 'false' argument to the ptr constructor in create */
     // BOOST_ASSERT( !this->refcount_  && !this->impl_ );
     SATCOM_PKF_REFC_MSG("] Packet::~Packet (" << this << ")\n");
 }

Packets/Packet.ct

@@ -56,8 +56,8 @@ template <class OuterPacket>
 prefix_ typename senf::Packet::ptr_t<OuterPacket>::ptr
 senf::Packet::create(Packet::ptr payload)
 {
-    // TODO: should I instead of using head() throw away all
-    // interpreters before payload? ... probably yes ...
+    /** \todo should I instead of using head() throw away all
+	interpreters before payload? ... probably yes ... */
     payload->insert(payload->head()->begin(),min_bytes<OuterPacket>(),0);
     typename ptr_t<OuterPacket>::ptr p (new OuterPacket(PacketOp_set(payload->impl_)));
     p->init();

Packets/Packet.cti

@@ -50,9 +50,9 @@ prefix_ senf::Packet::Packet(Operation const & arg)
       parsed_(false), refcount_(1)
 {
     SATCOM_PKF_REFC_MSG("] Packet::Packet (" << this << "): refcount_ = 1\n");
-    // FIXME: This is not exception safe, if an exception is thrown in
-    // the derived class constuctor, the effects of this call must be
-    // undone which is not possible in a simple way.
+    /** \fixme This is not exception safe, if an exception is thrown in
+	the derived class constuctor, the effects of this call must be
+	undone which is not possible in a simple way. */
     arg(this);
 }
 

Packets/Packet.hh

@@ -20,25 +20,25 @@
 // Free Software Foundation, Inc.,
 // 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 
-// TODO: Implement assign() method akin to reinterpret(). However,
-// instead of using the data already present, assign() will replace
-// the date of the current packet with the given Packet.
+/** \file
+    \brief Main packet interface
 
-// TODO: Implement wrapping-constructor. Somehow we want to have a
-// constructor, which allows creating a chain of packet interpreters
-// with as little overhead as possible.
+    \todo Implement assign() method akin to reinterpret(). However,
+    instead of using the data already present, assign() will replace
+    the date of the current packet with the given Packet.
 
-// TODO: Document the additional concrete Packet facade requirements
-// explicitly and not only within the Parser requirements (check(),
-// bytes() and min_bytes() members ...)
+    \todo Implement wrapping-constructor. Somehow we want to have a
+    constructor, which allows creating a chain of packet interpreters
+    with as little overhead as possible.
 
-// TODO: Implement special container replacing vector which manages
-// some headroom to allow efficient insertion of elements at the
-// beginning. This really is just another type of deque
-// implementation.
+    \todo Document the additional concrete Packet facade requirements
+    explicitly and not only within the Parser requirements (check(),
+    bytes() and min_bytes() members ...)
 
-/** \file
-    \brief Main packet interface
+    \todo Implement special container replacing vector which manages
+    some headroom to allow efficient insertion of elements at the
+    beginning. This really is just another type of deque
+    implementation.
  */
 
 #ifndef HH_Packet_
@@ -76,7 +76,7 @@ namespace senf {
         counted smart pointer, so resource management is quasi
         automatic.
 
-        \image html "../../structure.png" Overview
+        \image html structure.png Overview
         
         Internally, every Packet references a PacketImpl instance which
         manages the raw packet data and the interpreter list. This raw
@@ -260,6 +260,8 @@ namespace senf {
         intrusive_ptr is only the size of an ordinary pointer, a
         smart_ptr has the size of two pointers).
 
+        \fixme Make all data mutators protected
+
         \nosubgrouping
       */
     class Packet : boost::noncopyable
@@ -395,8 +397,8 @@ namespace senf {
             OtherPacket. 
 
             \attention This invalidates the packet instance \e
-            this</b>. You must ensure, not to use the Packet instance
-            any further after this call
+            this. You must ensure, not to use the Packet instance any
+            further after this call
 
             \return smart pointer to a \e new packet facade
             \throws TruncatedPacketException there is not enough data
@@ -439,8 +441,6 @@ namespace senf {
 
         // Modifying the raw packet data
 
-        // FIXME: Make all data mutators protected
-
         typedef enum { AUTO, BEFORE, INSIDE, OUTSIDE, AFTER } Whence;
 
         /** \brief insert single byte \a v before pos

Packets/PacketRegistry.hh

@@ -20,7 +20,6 @@
 // Free Software Foundation, Inc.,
 // 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 
-// TODO: Add parameterless create() method
 
 #ifndef HH_PacketRegistryImpl_
 #define HH_PacketRegistryImpl_ 1
@@ -79,17 +78,20 @@ namespace senf {
         constructor during global construction time.
 
         The PacketRegistry's purpose is mostly to assist in
-        implementing the \v v_nextInterpreter() member of packet
+        implementing the v_nextInterpreter() member of packet
         facades. This is further supported by the PacketRegistryMixin
         class.
+
+	\todo Add parameterless create() method
      */
     template <class Tag>
     class PacketRegistry
     {
     public:
-        // TODO: This fails to work within a library since the linker will
-        // remove all unused object files ...
         /** \brief Statically register a packet type in a PacketRegistry
+
+	    \fixme This fails to work within a library since the linker will
+	    remove all unused object files ...
          */
         template <class OtherPacket>
         struct RegistrationProxy

Packets/ParseListS.ct

@@ -82,7 +82,7 @@ prefix_ void
 senf::Parse_ListS_wrapper<Parser,Sentinel,Container>::insert(iterator pos,
                                                                     Value const & t)
 {
-    // FIXME: What, if pos == end() / default constructed iterator ?
+    /** \fixme What, if pos == end() / default constructed iterator ? */
     size_type ix (pos.raw()-container_.begin());
     container_.insert(pos.raw(),t.bytes(),0);
     Parser(container_.begin()+ix).value(t);

Packets/ParseVec.ct

@@ -61,8 +61,9 @@ senf::Parse_Vector_wrapper<Parser,SizeParser,Container>::insert(iterator pos,
                                                                        InputIterator f,
                                                                        InputIterator l)
 {
-    // FIXME: This is HORRIBLY inefficient ... we need to specialize 
-    // for random_aPacketRegistry.ess and forward iterators, where we can count the distance
+    /** \fixme This might be horribly inefficient ... we need to
+	specialize for random_access and forward iterators, where we
+	can count the distance */
 
     size_type ix(pos.raw()-container_.begin());
     for (;f!=l;++f) {

Packets/ParserBase.test.cc

@@ -40,7 +40,7 @@
 
 BOOST_AUTO_UNIT_TEST(parserBase_inherited)
 {
-    // TODO: Implement
+    /** \todo Implement */
 }
 
 namespace {

Packets/RTCPPacket.test.cc

@@ -69,7 +69,7 @@ BOOST_AUTO_UNIT_TEST(rtcpPacket_parser)
     BOOST_CHECK_EQUAL(p_1.rr().socount(),        0x0dc8u     );
 
 
-    // TODO RTCP RR
+    /// \todo RTCP RR
     unsigned char data_2[] = { 
                              0x82, 0xc8, 0x00, 0x06, 
                              0xe5, 0x70, 0xaa, 0x18, 
@@ -201,7 +201,7 @@ BOOST_AUTO_UNIT_TEST(rtcpPacket_parser)
     BOOST_CHECK_EQUAL( j->DLSR(),     0x20212223u  );
 #endif
 
-    // TODO RTCP SDES
+    /// \todo RTCP SDES
 
     unsigned char data_4[] = { 
                              0x81, 0xca, 0x00, 0x04, 
@@ -225,7 +225,7 @@ BOOST_AUTO_UNIT_TEST(rtcpPacket_parser)
 #if 0
     Parse_RTCP_SDES::Parse_itemList::iterator j_4 (p_4.sdes().chunkVec().begin());
 
-// TODO  -> ask Stefan
+/// \todo ask Stefan
 
  // BOOST_CHECK_EQUAL( p_4.sdes().chunkList()[0].ssrc(), 0xe570aa18u);
  // BOOST_CHECK_EQUAL( p_4.sdes().chunkList()[0].itemList().size(), 0x01u);

SConstruct

@@ -13,8 +13,6 @@ env = SENFSCons.MakeEnvironment()
 env.Append(
    CPPPATH = [ '#' ],
    LIBS = [ 'iberty' ],
-   DOXYFILES = [ '#/doclib/doxy-header.html', '#/doclib/doxy-footer.html',
-                 '#/doclib/Doxyfile.global' ]
 )
 
 Export('env')
@@ -24,5 +22,10 @@ SConscript(glob.glob("*/SConscript"))
 SENFSCons.StandardTargets(env)
 SENFSCons.GlobalTargets(env)
 SENFSCons.Doxygen(env)
+SENFSCons.DoxyXRef(env,
+                   TYPES = ('bug','fixme','todo','idea'),
+                   HTML_HEADER = '#/doclib/doxy-header-overview.html',
+                   HTML_FOOTER = '#/doclib/doxy-footer.html')
 
-if not os.path.exists("Doxyfile.local") : Execute(Touch("Doxyfile.local"))
+if not env.GetOption('clean') and not os.path.exists("Doxyfile.local"):
+    Execute(Touch("Doxyfile.local"))

Scheduler/ReadHelper.hh

@@ -2,7 +2,6 @@
 //
 // Copyright (C) 2006 
 
-// TODO: Move all not Handle dependent members to a ReadHandleBase class
 
 #ifndef HH_ReadHelper_
 #define HH_ReadHelper_ 1
@@ -22,6 +21,10 @@
 namespace senf {
 
 
+    /** \brief
+
+	\todo Move all not Handle dependent members to a ReadHandleBase class
+     */
     template <class Handle>
     class ReadHelper
 	: public senf::intrusive_refcount

Scheduler/Scheduler.cc

@@ -20,7 +20,19 @@
 // Free Software Foundation, Inc.,
 // 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 
-// TODO: Implement signal handling
+/** \file
+
+    \idea Implement signal handling (See source for more discussion
+    about this) 
+
+    \idea Multithreading support: To support multithreading, the
+    static member Scheduler::instance() must return a thread-local
+    value (that is Scheduler::instance() must allocate one Scheduler
+    instance per thread)
+
+    \fixme Test2
+ */
+
 // Here a basic concept of how to add signal support to the scheduler:
 //
 // Every signal to be reported by the scheduler will be asigned a
@@ -57,11 +69,6 @@
 // scheduler must be blocked as soon as it is registered with the
 // scheduler.
 
-// TODO: Multithreading support
-// To support multithreading, the static member Scheduler::instance()
-// must return a thread-local value (that is Scheduler::instance()
-// must allocate one Scheduler instance per thread)
-
 // Definition of non-inline non-template functions
 
 #include "Scheduler.hh"

Scheduler/Scheduler.hh

@@ -20,9 +20,6 @@
 // Free Software Foundation, Inc.,
 // 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 
-// TODO: Fix EventId parameter (probably to int) to allow |-ing without casting ...
-
-
 /** \mainpage The SENF Scheduler library
 
  */
@@ -52,6 +49,9 @@ namespace senf {
         descriptiors with this class and pass callback functions to be
         called on input, output or error. This functions are specified
         using boost::function objects
+
+	\todo Fix EventId parameter (probably to int) to allow |-ing
+	without casting ...
       */
     class Scheduler
         : boost::noncopyable

Socket/BSDSocketProtocol.cc

@@ -59,8 +59,8 @@ prefix_ void senf::BSDSocketProtocol::linger(bool enable, unsigned timeout)
 prefix_ struct timeval senf::BSDSocketProtocol::timestamp()
     const
 {
-    // BUG: Check, why this fails with ENOFILE (!!!!) at least when
-    // called from a tcp socket. Further investigation necessary ...
+    /** \bug Check, why this fails with ENOFILE (!!!!) at least when
+	called from a tcp socket. Further investigation necessary ... */
     struct timeval tv;
     if (::ioctl(body().fd(), SIOCGSTAMP, &tv) < 0)
         throw SystemException(errno);

Socket/BufferingPolicy.hh

@@ -33,7 +33,10 @@
 namespace senf {
 
 
-    // TODO: Should this be dependent on Read / WritePolicy ?
+    /** \brief
+
+	\todo Shouldn't this be dependent on Read / WritePolicy ?
+     */
     struct SocketBufferingPolicy : public BufferingPolicyBase
     {
         static unsigned rcvbuf(FileHandle handle);