From: g0dil <g0dil@270642c3-0616-0410-b53a-bc976706d245>
Date: Fri, 2 Nov 2007 15:15:06 +0000 (+0000)
Subject: Utils: Revamp documentation overview and add some missing docs
X-Git-Url: http://g0dil.de/git?a=commitdiff_plain;h=f00a102138bcbabdaab1caab1db6a8876463dedc;p=senf.git

Utils: Revamp documentation overview and add some missing docs
Utils: Rename SafeBool to safe_bool (hmm ...)

git-svn-id: https://svn.berlios.de/svnroot/repos/senf/trunk@493 270642c3-0616-0410-b53a-bc976706d245
---

diff --git a/PPI/Connectors.hh b/PPI/Connectors.hh
index 4779c30..0f54dc6 100644
--- a/PPI/Connectors.hh
+++ b/PPI/Connectors.hh
@@ -28,7 +28,7 @@
 #include <deque>
 #include <boost/utility.hpp>
 #include <boost/scoped_ptr.hpp>
-#include "../Utils/SafeBool.hh"
+#include "../Utils/safe_bool.hh"
 #include "../Packets/Packets.hh"
 #include "predecl.hh"
 #include "detail/Callback.hh"
@@ -334,7 +334,7 @@ namespace connector {
      */
     class PassiveInput 
         : public PassiveConnector, public InputConnector,
-          public SafeBool<PassiveInput>
+          public safe_bool<PassiveInput>
     {
     public:
         PassiveInput();
@@ -362,7 +362,7 @@ namespace connector {
      */
     class PassiveOutput
         : public PassiveConnector, public OutputConnector,
-          public SafeBool<PassiveOutput>
+          public safe_bool<PassiveOutput>
     {
     public:
         ActiveInput & peer() const;
@@ -378,7 +378,7 @@ namespace connector {
      */
     class ActiveInput
         : public ActiveConnector, public InputConnector,
-          public SafeBool<ActiveInput>
+          public safe_bool<ActiveInput>
     {
     public:
         PassiveOutput & peer() const;
@@ -395,7 +395,7 @@ namespace connector {
      */
     class ActiveOutput
         : public ActiveConnector, public OutputConnector,
-          public SafeBool<ActiveOutput>
+          public safe_bool<ActiveOutput>
     {
     public:
         PassiveInput & peer() const;
diff --git a/PPI/DebugModules.hh b/PPI/DebugModules.hh
index 67068d1..b52b871 100644
--- a/PPI/DebugModules.hh
+++ b/PPI/DebugModules.hh
@@ -28,7 +28,7 @@
 
 // Custom includes
 #include <deque>
-#include "../Utils/SafeBool.hh"
+#include "../Utils/safe_bool.hh"
 #include "../Packets/Packets.hh"
 #include "Module.hh"
 #include "ActiveFeeder.hh"
@@ -75,7 +75,7 @@ namespace debug {
      */
     class ActiveSource
         : public Module, 
-          public SafeBool<ActiveSource>
+          public safe_bool<ActiveSource>
     {
         SENF_PPI_MODULE(ActiveSource);
 
@@ -136,7 +136,7 @@ namespace debug {
      */
     class ActiveSink
         : public Module,
-          public SafeBool<ActiveSink>
+          public safe_bool<ActiveSink>
     {
         SENF_PPI_MODULE(ActiveSink);
 
diff --git a/Packets/Packet.hh b/Packets/Packet.hh
index 7fa54fa..44dcf2f 100644
--- a/Packets/Packet.hh
+++ b/Packets/Packet.hh
@@ -28,7 +28,7 @@
 #include <boost/operators.hpp>
 
 #include "../Utils/Exception.hh"
-#include "../Utils/SafeBool.hh"
+#include "../Utils/safe_bool.hh"
 #include "PacketInterpreter.hh"
 
 //#include "Packet.mpp"
@@ -135,7 +135,7 @@ namespace senf {
             \ref packetparser for a specification of the parser interface
       */
     class Packet
-        : public SafeBool<Packet>,
+        : public safe_bool<Packet>,
           public boost::equality_comparable<Packet>
     {
     public:
diff --git a/Packets/PacketData.hh b/Packets/PacketData.hh
index c316778..3bcb522 100644
--- a/Packets/PacketData.hh
+++ b/Packets/PacketData.hh
@@ -28,7 +28,7 @@
 #include <boost/utility.hpp>
 #include <boost/type_traits.hpp>
 #include <boost/iterator/iterator_facade.hpp>
-#include "../Utils/SafeBool.hh"
+#include "../Utils/safe_bool.hh"
 #include "PacketTypes.hh"
 
 //#include "PacketData.mpp"
@@ -175,7 +175,7 @@ namespace senf {
         : public boost::iterator_facade< safe_data_iterator,
                                          PacketData::value_type,
                                          boost::random_access_traversal_tag >,
-          public ComparableSafeBool<safe_data_iterator>
+          public comparable_safe_bool<safe_data_iterator>
     {
     public:
         typedef PacketData::size_type size_type;
diff --git a/Packets/PacketParser.hh b/Packets/PacketParser.hh
index 543ba9c..010780e 100644
--- a/Packets/PacketParser.hh
+++ b/Packets/PacketParser.hh
@@ -155,7 +155,7 @@
 #include <boost/utility/enable_if.hpp>
 #include <boost/type_traits.hpp>
 #include <boost/optional.hpp>
-#include "../Utils/SafeBool.hh"
+#include "../Utils/safe_bool.hh"
 #include "PacketTypes.hh"
 #include "PacketData.hh"
 #include "ParseHelpers.hh"
@@ -468,7 +468,7 @@ namespace senf {
       */
     template <class Parser>
     class SafePacketParser
-        : public SafeBool< SafePacketParser<Parser> >
+        : public safe_bool< SafePacketParser<Parser> >
     {
     public:
         ///////////////////////////////////////////////////////////////////////////
diff --git a/Socket/FileHandle.hh b/Socket/FileHandle.hh
index 584ba59..ea9dc53 100644
--- a/Socket/FileHandle.hh
+++ b/Socket/FileHandle.hh
@@ -59,7 +59,7 @@
 
 // Custom includes
 #include <memory> // std::auto_ptr
-#include "../Utils/SafeBool.hh"
+#include "../Utils/safe_bool.hh"
 
 //#include "FileHandle.mpp"
 ///////////////////////////////hh.p////////////////////////////////////////
@@ -100,7 +100,7 @@ namespace senf {
         senf::FileBody.
      */
     class FileHandle
-        : public SafeBool<FileHandle>
+        : public safe_bool<FileHandle>
     {
     public:
         ///////////////////////////////////////////////////////////////////////////
diff --git a/Socket/Protocols/INet/INet4Address.hh b/Socket/Protocols/INet/INet4Address.hh
index ffe2289..b163aaa 100644
--- a/Socket/Protocols/INet/INet4Address.hh
+++ b/Socket/Protocols/INet/INet4Address.hh
@@ -32,7 +32,7 @@
 #include <boost/cstdint.hpp>
 #include <boost/array.hpp>
 #include <boost/operators.hpp>
-#include "../../../Utils/SafeBool.hh"
+#include "../../../Utils/safe_bool.hh"
 
 //#include "INet4Address.mpp"
 ///////////////////////////////hh.p////////////////////////////////////////
@@ -56,7 +56,7 @@ namespace senf {
       */
     class INet4Address
         : public boost::array<boost::uint8_t,4>, 
-          public ComparableSafeBool<INet4Address>
+          public comparable_safe_bool<INet4Address>
     {
     public:
         ///////////////////////////////////////////////////////////////////////////
@@ -193,7 +193,7 @@ namespace senf {
       */
     class INet4Network
         : public boost::equality_comparable<INet4Network>, 
-          public ComparableSafeBool<INet4Network>
+          public comparable_safe_bool<INet4Network>
     {
     public:
         ///////////////////////////////////////////////////////////////////////////
diff --git a/Socket/Protocols/INet/INet6Address.hh b/Socket/Protocols/INet/INet6Address.hh
index 1639ba3..877752b 100644
--- a/Socket/Protocols/INet/INet6Address.hh
+++ b/Socket/Protocols/INet/INet6Address.hh
@@ -32,7 +32,7 @@
 #include <boost/cstdint.hpp>
 #include <boost/array.hpp>
 #include <boost/operators.hpp>
-#include "../../../Utils/SafeBool.hh"
+#include "../../../Utils/safe_bool.hh"
 #include "INet4Address.hh"
 
 //#include "INet6Address.mpp"
@@ -97,7 +97,7 @@ namespace senf {
      */
     class INet6Address
         : public boost::array<boost::uint8_t,16>,
-          public ComparableSafeBool<INet6Address>
+          public comparable_safe_bool<INet6Address>
     {
     public:
         ///////////////////////////////////////////////////////////////////////////
@@ -294,7 +294,7 @@ namespace senf {
       */
     class INet6Network
         : public boost::equality_comparable<INet6Network>, 
-          public ComparableSafeBool<INet6Network>
+          public comparable_safe_bool<INet6Network>
     {
     public:
         ///////////////////////////////////////////////////////////////////////////
diff --git a/Socket/Protocols/INet/INetAddressing.hh b/Socket/Protocols/INet/INetAddressing.hh
index 43a13cf..f2972e0 100644
--- a/Socket/Protocols/INet/INetAddressing.hh
+++ b/Socket/Protocols/INet/INetAddressing.hh
@@ -36,6 +36,7 @@
 #include "../../../Socket/ClientSocketHandle.hh"
 #include "../../../Socket/CommunicationPolicy.hh"
 #include "../../../Socket/Protocols/GenericAddressingPolicy.hh"
+#include "../../../Utils/safe_bool.hh"
 #include "INet4Address.hh"
 #include "INet6Address.hh"
 
@@ -56,7 +57,7 @@ namespace senf {
      */
     class INet4SocketAddress
         : public boost::equality_comparable<INet4SocketAddress>, 
-          public senf::ComparableSafeBool<INet4SocketAddress>
+          public senf::comparable_safe_bool<INet4SocketAddress>
     {
     public:
         INet4SocketAddress();
diff --git a/Socket/Protocols/Raw/MACAddress.hh b/Socket/Protocols/Raw/MACAddress.hh
index 33eb687..9f413a7 100644
--- a/Socket/Protocols/Raw/MACAddress.hh
+++ b/Socket/Protocols/Raw/MACAddress.hh
@@ -30,7 +30,7 @@
 #include <boost/array.hpp>
 #include <boost/utility.hpp>
 #include <boost/type_traits.hpp>
-#include "../../../Utils/SafeBool.hh"
+#include "../../../Utils/safe_bool.hh"
 
 //#include "MACAddress.mpp"
 ///////////////////////////////hh.p////////////////////////////////////////
@@ -51,7 +51,7 @@ namespace senf {
      */
     struct MACAddress
         : public boost::array<boost::uint8_t,6>, 
-          public ComparableSafeBool<MACAddress>
+          public comparable_safe_bool<MACAddress>
     {
         static MACAddress const Broadcast; ///< The broadcast address
         static MACAddress const None;   ///< The empty (0) address
diff --git a/Socket/Protocols/UN/UNAddress.hh b/Socket/Protocols/UN/UNAddress.hh
index b5be60d..1b6ed5f 100644
--- a/Socket/Protocols/UN/UNAddress.hh
+++ b/Socket/Protocols/UN/UNAddress.hh
@@ -28,7 +28,7 @@
 #include <string>
 #include <boost/operators.hpp>
 #include <boost/filesystem/path.hpp>
-#include "../../../Utils/SafeBool.hh"
+#include "../../../Utils/safe_bool.hh"
 
 //#include "UNAddress.mpp"
 ///////////////////////////////hh.p////////////////////////////////////////
@@ -42,7 +42,7 @@ namespace senf {
       */
     class UNAddress 
         : public boost::filesystem::path,
-          public ComparableSafeBool<UNAddress>
+          public comparable_safe_bool<UNAddress>
     {   
     public: 
         UNAddress(); ///< Construct an empty address
diff --git a/Socket/Protocols/UN/UNAddressing.cc b/Socket/Protocols/UN/UNAddressing.cc
index 3916d06..763d667 100644
--- a/Socket/Protocols/UN/UNAddressing.cc
+++ b/Socket/Protocols/UN/UNAddressing.cc
@@ -28,8 +28,7 @@
 #include <stdio.h>
 #include <boost/operators.hpp>
 #include <boost/filesystem/path.hpp>
-#include "../../../Utils/SafeBool.hh"
-//#include "UNAddressing.mpp"
+
 #define prefix_
 ///////////////////////////////cc.p////////////////////////////////////////
 prefix_ senf::UNSocketAddress::UNSocketAddress(boost::filesystem::path p)
diff --git a/Socket/Protocols/UN/UNAddressing.hh b/Socket/Protocols/UN/UNAddressing.hh
index 79d6f18..af121f0 100644
--- a/Socket/Protocols/UN/UNAddressing.hh
+++ b/Socket/Protocols/UN/UNAddressing.hh
@@ -36,6 +36,7 @@
 #include "../../../Socket/ClientSocketHandle.hh"
 #include "../../../Socket/CommunicationPolicy.hh"
 #include "../../../Socket/Protocols/GenericAddressingPolicy.hh"
+#include "../../../Utils/safe_bool.hh"
 #include "UNAddress.hh"
 
 //#include "UNAddressing.mpp"
@@ -51,7 +52,7 @@ namespace senf {
         \ingroup addr_group
      */
     class UNSocketAddress
-        : public ComparableSafeBool<UNSocketAddress>
+        : public comparable_safe_bool<UNSocketAddress>
     {
     public:
 
diff --git a/Utils/Exception.hh b/Utils/Exception.hh
index c6e9ba3..a991710 100644
--- a/Utils/Exception.hh
+++ b/Utils/Exception.hh
@@ -39,45 +39,43 @@ namespace senf {
 
     /** \brief Exception handling standard UNIX errors (errno)
 
-        This exception is thrown to signal generic errno failures.
+        This exception is thrown to signal generic \c errno failures. In addition to the \c errno
+        number (the code()), this class manages optional origin information. This parameter should
+        be provided to further describe, in what context the exception was created.
 
-        \todo make where and err accessors and make the member variables private
+        This exception should not be used directly. Instead the derived class ErrnoException should
+        be thrown via one of the senf::throwErrno() helpers.
 
-        \idea Add a template class derived from SystemException which takes the error number as a
-        numeric argument. This allows catching specific errno conditions: ErrnoException<EPIPE> etc.
-
-        \idea Add a generic error thrower which takes the origin string and errno value as an
-        argument and will throw a corresponding template class instance. This would just be a big
-        switch statement containing all possible errno values, probably created using some macro
-        meta-programming.
+        \see ErrnoException
      */
     class SystemException : public std::exception
     {
     public:
         SystemException();              ///< SystemException without error location infor
                                         /**< The error code is taken from the current value of the
-                                             global 'errno' variable  */
+                                             global \c errno variable  */
 
         explicit SystemException(int code); ///< SystemException without error location info
-                                        /**< \param[in] code error number (the errno value) */
+                                        /**< \param[in] code error number (the \c errno value) */
 
         explicit SystemException(char const * where); ///< SystemException with error location info
                                         /**< The error code is taken from the current value of the
-                                             global 'errno' variable 
+                                             global \c errno variable 
                                              \param[in] where description of error origin */
 
         SystemException(char const * where, int code); ///< SystemException with error location info 
                                         /**< \param[in] where description of error origin
-                                             \param[in] code error number (the errno value) */
+                                             \param[in] code error number (the \c errno value) */
 
         virtual char const * what() const throw(); ///< Return verbose error description
 
         char const * where() const;     ///< Error origin
-        int code() const;               ///< Error code (errno number)
+        int code() const;               ///< Error code (\c errno number)
         char const * description() const; ///< Error description (strerror() value)
 
         bool anyOf(int c0, int c1=0, int c2=0, int c3=0, int c4=0, int c5=0, 
                    int c6=0, int c7=0, int c8=0, int c9=0);
+                                        ///< \c true, if code() is one of \a c0 ... \a c9
 
         virtual ~SystemException() throw();
 
@@ -85,23 +83,54 @@ namespace senf {
         void init();
 
         char const * const where_;
-        int const code_;
+        int const code_;                // This must be const to make the derived ErrnoException
+                                        // class a valid derived class.
         std::string buffer_;
     };
 
+    /** \brief Error specific system exception
+
+        This template restricts the generic SystemException to a specific, compile-time constant
+        error number \p Code. This allows a specific \c errno number to be cached explicitly.
+
+        This exception is normally thrown via one of the senf::throwErrno() helpers. These helpers
+        take the numeric \c errno value (either from the \c errno variable or from their
+        argument) and will throw the corresponding ErrnoException:
+        \code
+        if ((fd = ::open(filename, O_RDWR)) < 0)
+             senf::throwErrno("open()");
+        \endcode
+     */
     template <int Code>
     class ErrnoException : public SystemException
     {
     public:
         static int const fixed_code = Code;
 
-        ErrnoException();
+        ErrnoException();               ///< ErrnoException without error location information
         explicit ErrnoException(char const * where);
+                                        ///< ErrnoException with error location information
     };
 
+    
+    /** \brief Throw ErrnoException based on current \c errno value
+        \related ErrnoException
+     */
     void throwErrno();
+
+    /** \brief Throw ErrnoException based on current \c errno value (with location info)
+        \related ErrnoException
+     */
     void throwErrno(char const * where);
+
+    /** \brief Throw ErrnoException based on given \c errno value
+        \related ErrnoException
+     */
     void throwErrno(int code);
+
+    /** \brief Throw ErrnoException based on given \c errno value (with location info)
+        \related ErrnoException
+     */
     void throwErrno(char const * where, int code);
 
     enum NoThrow_t { nothrow };
diff --git a/Utils/IpChecksum.hh b/Utils/IpChecksum.hh
index 7efb55d..89b3f4f 100644
--- a/Utils/IpChecksum.hh
+++ b/Utils/IpChecksum.hh
@@ -34,7 +34,17 @@
 
 namespace senf {
     
-    /** \brief
+    /** \brief Calculate TCP/IP 16bit checksum value
+
+        This class allows calculation of the 16bit checksum value as defined in the TCP/IP v4
+        RFC's. This checksum is \e not a CRC.
+
+        To calculate the checksum, you create an instance of IpChecksum. You then repeatedly call
+        the feed() members to pass data in. After all data has been processed, the sum() member will
+        return the calculated checksum.
+
+        The mathematical properties of the checksum allow to skip any \e even number of zero bytes
+        without changing the checksum value.
       */
     class IpChecksum
     {
@@ -51,12 +61,13 @@ namespace senf {
         ///@}
         ///////////////////////////////////////////////////////////////////////////
 
-        void feed(boost::uint8_t byte);
+        void feed(boost::uint8_t byte); ///< Feed single byte
 
         template <class InputIterator>
         void feed(InputIterator b, InputIterator e);
+                                        ///< Feed range of bytes
 
-        boost::uint16_t sum() const;
+        boost::uint16_t sum() const;    ///< Calculate checksum
     
     protected:
 
diff --git a/Utils/Mainpage.dox b/Utils/Mainpage.dox
index 7472bda..bb6435e 100644
--- a/Utils/Mainpage.dox
+++ b/Utils/Mainpage.dox
@@ -2,46 +2,79 @@ namespace senf {
 
 /** \mainpage The SENF Utilities Library
 
-    The Utilities Library is a collection of independent utilities. We have 
+    The Utilities Library is a collection of independent utilities.
 
-    <dl>
 
-    <dt>SystemException</dt><dd>standard exception for system errors (errno)</dd>
+    \section basic_helpers C++ Language helpers and simple library extensions
 
-    <dt>\ref process</dt><dd>Some simple process management and daemon helpers<?dd>
+    <table class="listing">
+    <tr><td>\ref membind</td><td>a simple <a
+    href="http://www.boost.org/libs/bind/bind.html">Boost.Bind</a> extension</td></tr>
 
-    <dt>\ref membind</dt><dd>a simple <a
-    href="http://www.boost.org/libs/bind/bind.html">Boost.Bind</a> extension</dd>
+    <tr><td>\ref senfmpl</td><td>Some simple tools which help to solve common meta-programming
+    tasks</td></tr>
 
-    <dt>intrusive_refcount</dt><dd>mixin to simplify writing classes for use with <a
-    href="http://www.boost.org/libs/smart_ptr/intrusive_ptr.html">boost::intrusive_ptr</a></dd>
+    <tr><td>\ref senfpp</td><td>Extensions to the Boost.Preprocessor library</td></tr>
+    </table>
 
-    <dt>SafeBool</dt><dd>a mixin class to provide a really safe replacement for <tt>operator
-    bool</tt></dd>
+
+    \section basic_mixins Basic mixin classes
+    
+    <table class="listing">
+    <tr><td>\ref intrusive_refcount</td><td>mixin to simplify writing classes for use with <a
+    href="http://www.boost.org/libs/smart_ptr/intrusive_ptr.html">boost::intrusive_ptr</a></td></tr>
+
+    <tr><td>\ref safe_bool</td><td>a mixin class to provide a really safe replacement for
+    <tt>operator bool</tt>
     
-    <dt>pool_alloc_mixin</dt><dd>mixin to provide pool allocation to a class</dd>
+    <tr><td>\ref singleton</td><td>mixin to make a class a singleton</td></tr>
+    </table>
+    
+
+    \section memory_management Memory Management
+
+    <table class="listing">
+    <tr><td>\ref SENF_SCOPED_BUFFER</td><td>a portable way to efficiently allocate temporary
+    buffers</td></tr>
+
+    <tr><td>\ref pool_alloc_mixin</td><td>mixin to provide pool allocation to a class</td></tr>
     
-    <dt>\ref singleton</dt><dd>mixin to make a class a singleton</dd>
+    <tr><td>\ref contiguous_storage_iterator</td><td>traits class to check iterator type for raw
+    pointer accessibility</td></tr>
+    </table>
 
-    <dt>prettyName()</dt><dd>an interface to the C++ demangler of g++ to get formated type names
-    from typeinfo objects</dd>
 
-    <dt>\ref SENF_SCOPED_BUFFER</dt><dd>a portable way to efficiently allocate temporary
-    buffers</dd>
+    \section typeinfo C++ Type interface
 
-    <dt>\ref contiguous_storage_iterator</dt><dd>traits class to check iterator type for raw pointer
-    accessibility</dd>
+    <table class="listing">
+    <tr><td>\ref prettyName()</td><td>an interface to the C++ demangler of g++ to get formated type
+    names from typeinfo objects</td></tr>
 
-    <dt>\ref TypeIdValue</dt><dd>class wrapping a typeid in a way that it can be used like any other
-    value type, e.g. as the key in a map.</dd>
+    <tr><td>\ref TypeIdValue</td><td>class wrapping a typeid in a way that it can be used like any
+    other value type, e.g. as the key in a map.</td></tr>
+    </table>
     
-    <dt>\ref hexdump<dt><dd>a simple but usefull function to write binary data in in hexadecimal
-    format.</dd>
 
-    <dt>\ref senfmpl</dt><dd>Some simple tools which help to solve common meta-programming
-    tasks</dd>
+    \section miscstuff Miscellaneous
+
+    <table class="listing">
+    <tr><td>\ref SystemException</td><td>standard exception for system errors (errno)</td></tr>
+
+    <tr><td>\ref process</td><td>Some simple process management and daemon helpers</td></tr>
+
+    <tr><td>\ref hexdump</td><td>a simple but usefull function to write binary data in in
+    hexadecimal format.</td></tr>
+
+    <tr><td>\ref IpChecksum</td><td>calculating the 16 bit checksum used in the IP
+    specification</td></tr>
+    </table>
+
+    \section compatibility Compatibility
 
-    </dl>
+    <table class="listing">
+    <tr><td>\ref auto_unit_test.hh</td><td>Boost auto unit test compatibility across Boost versions
+    1.33 and 1.34</td></tr>
+    </table>
  */
 
 }
@@ -53,6 +86,5 @@ namespace senf {
 // c-file-style: "senf"
 // indent-tabs-mode: nil
 // ispell-local-dictionary: "american"
-// mode: flyspell
 // mode: auto-fill
 // End:
diff --git a/Utils/auto_unit_test.hh b/Utils/auto_unit_test.hh
index beb770f..f93ae3c 100644
--- a/Utils/auto_unit_test.hh
+++ b/Utils/auto_unit_test.hh
@@ -21,7 +21,15 @@
 // 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 
 /** \file
-    \brief auto_unit_test public header */
+    \brief Boost.Test auto unit test compatibility across Boost V 1.33 and 1.34
+
+    This header file will allows to consistently use the Boost Version 1.33 syntax for defining auto
+    unit tests. If the available Boost version is 1.34, this file will automatically take care of
+    any necessary workarounds.
+
+    So, instead of <tt>#include <boost/test/auto_unit_test.hpp></tt>, you should always write
+    <tt>#include "../Utils/auto_unit_test.hh"<tt> (with possibliy adjusted path).
+ */
 
 #ifndef HH_auto_unit_test_
 #define HH_auto_unit_test_ 1
diff --git a/Utils/mpl.hh b/Utils/mpl.hh
index 761ebf4..e1b6e80 100644
--- a/Utils/mpl.hh
+++ b/Utils/mpl.hh
@@ -36,7 +36,7 @@
 namespace senf {
 namespace mpl {
 
-    /** \defgroup senfmpl Low-level template meta programming helpers
+    /** \defgroup senfmpl Template meta programming helpers
      */
 
     /** \brief Marker class for empty default values etc.
diff --git a/Utils/preprocessor.hh b/Utils/preprocessor.hh
index c51605a..4b66c7c 100644
--- a/Utils/preprocessor.hh
+++ b/Utils/preprocessor.hh
@@ -34,8 +34,21 @@
 //#include "preprocessor.mpp"
 ///////////////////////////////hh.p////////////////////////////////////////
 
+/** \defgroup senfpp Preprocessor meta programming macros
+
+    preprocessor.hh provides some additional helper macros based on the Boost.Preprocessor library.
+ */
+
+///\{
+///\ingroup senfpp
+
+/** \brief Return last element of a sequence 
+    \hideinitializer 
+ */
 #define SENF_PP_SEQ_BACK(seq) BOOST_PP_SEQ_ELEM(BOOST_PP_DEC(BOOST_PP_SEQ_SIZE(seq)),seq)
 
+///\}
+
 ///////////////////////////////hh.e////////////////////////////////////////
 //#include "preprocessor.cci"
 //#include "preprocessor.ct"
diff --git a/Utils/SafeBool.cci b/Utils/safe_bool.cci
similarity index 78%
rename from Utils/SafeBool.cci
rename to Utils/safe_bool.cci
index cbcafa7..d5afd44 100644
--- a/Utils/SafeBool.cci
+++ b/Utils/safe_bool.cci
@@ -1,3 +1,4 @@
+
 // $Id$
 //
 // Copyright (C) 2007 
@@ -21,29 +22,29 @@
 // 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 
 /** \file
-    \brief SafeBool inline non-template implementation */
+    \brief safe_bool inline non-template implementation */
 
 // Custom includes
 
 #define prefix_ inline
 ///////////////////////////////cci.p///////////////////////////////////////
 
-prefix_ void senf::SafeBoolBase::this_type_does_not_support_comparisons()
+prefix_ void senf::safe_bool_base::this_type_does_not_support_comparisons()
     const
 {}
 
-prefix_ senf::SafeBoolBase::SafeBoolBase()
+prefix_ senf::safe_bool_base::safe_bool_base()
 {}
 
-prefix_ senf::SafeBoolBase::SafeBoolBase(const SafeBoolBase&)
+prefix_ senf::safe_bool_base::safe_bool_base(const safe_bool_base&)
 {}
 
-prefix_ senf::SafeBoolBase& senf::SafeBoolBase::operator=(const SafeBoolBase&)
+prefix_ senf::safe_bool_base& senf::safe_bool_base::operator=(const safe_bool_base&)
 {
     return *this;
 }
 
-prefix_ senf::SafeBoolBase::~SafeBoolBase()
+prefix_ senf::safe_bool_base::~safe_bool_base()
 {}
 
 ///////////////////////////////cci.e///////////////////////////////////////
diff --git a/Utils/SafeBool.cti b/Utils/safe_bool.cti
similarity index 78%
rename from Utils/SafeBool.cti
rename to Utils/safe_bool.cti
index f2618e6..d552792 100644
--- a/Utils/SafeBool.cti
+++ b/Utils/safe_bool.cti
@@ -21,9 +21,9 @@
 // 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 
 /** \file
-    \brief SafeBool inline template implementation */
+    \brief safe_bool inline template implementation */
 
-//#include "SafeBool.ih"
+//#include "safe_bool.ih"
 
 // Custom includes
 
@@ -31,32 +31,32 @@
 ///////////////////////////////cti.p///////////////////////////////////////
 
 template <typename T>
-prefix_ senf::ComparableSafeBool<T>::operator bool_type()
+prefix_ senf::comparable_safe_bool<T>::operator bool_type()
     const
 {
     return (static_cast<const T*>(this))->boolean_test()
-        ? &SafeBoolBase::this_type_does_not_support_comparisons : 0;
+        ? &safe_bool_base::this_type_does_not_support_comparisons : 0;
 }
 
 template <typename T>
-prefix_ bool senf::ComparableSafeBool<T>::operator!()
+prefix_ bool senf::comparable_safe_bool<T>::operator!()
     const
 {
     return ! (static_cast<const T*>(this))->boolean_test();
 }
 
 template <typename T>
-prefix_ senf::ComparableSafeBool<T>::~ComparableSafeBool()
+prefix_ senf::comparable_safe_bool<T>::~comparable_safe_bool()
 {}
 
 template <typename T, typename U>
-prefix_ void senf::operator==(const SafeBool<T>& lhs, const SafeBool<U>& rhs)
+prefix_ void senf::operator==(const safe_bool<T>& lhs, const safe_bool<U>& rhs)
 {
     lhs.this_type_does_not_support_comparisons();
 }
 
 template <typename T, typename U>
-prefix_ void senf::operator!=(const SafeBool<T>& lhs, const SafeBool<U>& rhs)
+prefix_ void senf::operator!=(const safe_bool<T>& lhs, const safe_bool<U>& rhs)
 {
     lhs.this_type_does_not_support_comparisons();
 }
diff --git a/Utils/SafeBool.hh b/Utils/safe_bool.hh
similarity index 50%
rename from Utils/SafeBool.hh
rename to Utils/safe_bool.hh
index eb116da..50a113a 100644
--- a/Utils/SafeBool.hh
+++ b/Utils/safe_bool.hh
@@ -21,66 +21,76 @@
 // 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 
 /** \file
-    \brief SafeBool public header */
+    \brief safe_bool public header */
 
-#ifndef HH_SafeBool_
-#define HH_SafeBool_ 1
+#ifndef HH_safe_bool_
+#define HH_safe_bool_ 1
 
 // Custom includes
 
-//#include "SafeBool.mpp"
+//#include "safe_bool.mpp"
 ///////////////////////////////hh.p////////////////////////////////////////
 
 namespace senf {
 
-    /** \brief internal SafeBool base class
+    /** \brief internal safe_bool base class
         \internal
+
+        \see safe_bool
      */
-    class SafeBoolBase
+    class safe_bool_base
     {
     protected:
-        typedef void (SafeBoolBase::*bool_type)() const;
+        typedef void (safe_bool_base::*bool_type)() const;
         void this_type_does_not_support_comparisons() const;
 
         // Just here to make them protected ...
 
-        SafeBoolBase();
-        SafeBoolBase(const SafeBoolBase&);
-        SafeBoolBase& operator=(const SafeBoolBase&);
-        ~SafeBoolBase();
+        safe_bool_base();
+        safe_bool_base(const safe_bool_base&);
+        safe_bool_base& operator=(const safe_bool_base&);
+        ~safe_bool_base();
+    };
+
+    /** \brief Mixin class for safe bool conversion support (comparable classes)
+
+        \see safe_bool
+     */
+    template <typename T>
+    class comparable_safe_bool
+        : public safe_bool_base
+    {
+    public:
+        operator bool_type() const;
+        bool operator !() const;
+
+    protected:
+        ~comparable_safe_bool();
     };
 
     /** \brief Mixin class for safe boolean conversion support
 
-        This is a direct yet simplified copy of a safe bool solution
-        by Bjorn Karlsson from
+        This is a direct yet simplified copy of a safe bool solution by Bjorn Karlsson from
         http://www.artima.com/cppsource/safebool.html
 
-        This mixin provides the client class with safe boolean
-        testing. It is a safe replacement for <tt>operator
-        bool</tt>. <tt>operator bool</tt> is problematic since \c bool
-        is an integer type. This conversion operator makes the class
-        usable in any numeric context, which can be quite
-        dangerous. The <tt>operator void *</tt> solution is much
-        better in this respect but still allows two instances of any
-        class having such a <tt>void *</tt> conversion to be compared
-        for equality. This again will produce absolutely unexpected
-        results since it will not check whether the objects are
-        identical, it will only check, that both return the same
+        This mixin provides the client class with safe boolean testing. It is a safe replacement for
+        <tt>operator bool</tt>. <tt>operator bool</tt> is problematic since \c bool is an integer
+        type. This conversion operator makes the class usable in any numeric context, which can be
+        quite dangerous. The <tt>operator void *</tt> solution is much better in this respect but
+        still allows two instances of any class having such a <tt>void *</tt> conversion to be
+        compared for equality. This again will produce absolutely unexpected results since it will
+        not check whether the objects are identical, it will only check, that both return the same
         boolean state.
 
-        This solutions solves all these problems by returning a
-        pointer-to-member which cannot be converted to any other
-        type. By providing explicit implementations of \c operator==
-        and \c operator!= which fail in an obvious way at compile
-        time, this hazard is removed.
+        This solutions solves all these problems by returning a pointer-to-member which cannot be
+        converted to any other type. By providing explicit implementations of \c operator== and \c
+        operator!= which fail in an obvious way at compile time, this hazard is removed.
 
-        To make a class boolean testable, just inherit from the mixin
-        and implement \c boolean_test:
+        To make a class boolean testable, just inherit from the mixin and implement \c boolean_test:
 
         \code
         class Testable
-            : public SafeBool<Testable>
+            : public safe_bool<Testable>
         {
         public:
             bool boolean_test() const
@@ -95,38 +105,29 @@ namespace senf {
            ...
         }
         \endcode
+        
+        If the class to be made using senf::safe_bool is itself comparable via it's own \c
+        operator==, you must use comparable_safe_bool instead of safe_bool to not loose this
+        capability.
 
-        \todo Either rename intrusive_refcount to IntrusiveRefcount or
-        SafeBool to safe_bool (I tend to the latter ...)
+        \see comparable_safe_bool
      */
     template <typename T>
-    class ComparableSafeBool
-        : public SafeBoolBase
-    {
-    public:
-        operator bool_type() const;
-        bool operator !() const;
-
-    protected:
-        ~ComparableSafeBool();
-    };
-
-    template <typename T>
-    class SafeBool : public ComparableSafeBool<T> {};
+    class safe_bool : public comparable_safe_bool<T> {};
 
     template <typename T, typename U>
-    void operator==(const SafeBool<T>& lhs,const SafeBool<U>& rhs);
+    void operator==(const safe_bool<T>& lhs,const safe_bool<U>& rhs);
 
     template <typename T,typename U>
-    void operator!=(const SafeBool<T>& lhs,const SafeBool<U>& rhs);
+    void operator!=(const safe_bool<T>& lhs,const safe_bool<U>& rhs);
 
 }
 
 ///////////////////////////////hh.e////////////////////////////////////////
-#include "SafeBool.cci"
-//#include "SafeBool.ct"
-#include "SafeBool.cti"
-//#include "SafeBool.mpp"
+#include "safe_bool.cci"
+//#include "safe_bool.ct"
+#include "safe_bool.cti"
+//#include "safe_bool.mpp"
 #endif
 
 
diff --git a/Utils/SafeBool.test.cc b/Utils/safe_bool.test.cc
similarity index 87%
rename from Utils/SafeBool.test.cc
rename to Utils/safe_bool.test.cc
index 88dd748..a4e0681 100644
--- a/Utils/SafeBool.test.cc
+++ b/Utils/safe_bool.test.cc
@@ -21,13 +21,13 @@
 // 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 
 /** \file
-    \brief SafeBool.test unit tests */
+    \brief safe_bool.test unit tests */
 
-//#include "SafeBool.test.hh"
-//#include "SafeBool.test.ih"
+//#include "safe_bool.test.hh"
+//#include "safe_bool.test.ih"
 
 // Custom includes
-#include "SafeBool.hh"
+#include "safe_bool.hh"
 
 #include "../Utils/auto_unit_test.hh"
 #include <boost/test/test_tools.hpp>
@@ -37,7 +37,7 @@
 
 namespace {
 
-    class TestTrue : public senf::SafeBool<TestTrue>
+    class TestTrue : public senf::safe_bool<TestTrue>
     {
     public:
         bool boolean_test() const {
@@ -45,7 +45,7 @@ namespace {
         }
     };
 
-    class TestFalse : public senf::SafeBool<TestFalse>
+    class TestFalse : public senf::safe_bool<TestFalse>
     {
     public:
         bool boolean_test() const {
diff --git a/doclib/senf.css b/doclib/senf.css
index b1a8ab1..ea77f17 100644
--- a/doclib/senf.css
+++ b/doclib/senf.css
@@ -277,6 +277,25 @@ table.ebnf td:first-child {
         font-style: italic;
 }
 
+table.listing {
+        margin: 0;
+        padding: 0;
+        border-spacing: 0;
+        border: none;
+        font-size: 120%; /* ????????  Why is THIS needed ?? */
+}
+
+table.listing td {
+        text-align: left;
+        vertical-align: top;
+        border: none;
+        padding: 0 0 3pt 0;
+}
+
+table.listing td:first-child {
+        width: 35%;
+}
+
 dl.xref-bug, dl.xref-fix, dl.xref-todo, dl.xref-idea {
         border: 1px solid #CC8888;
         padding: 2px 3px;