some documentation updates

[senf.git] / Socket / Protocols / INet / INet4Address.hh

diff --git a/Socket/Protocols/INet/INet4Address.hh b/Socket/Protocols/INet/INet4Address.hh
index f075555..f40b6dc 100644 (file)
--- a/Socket/Protocols/INet/INet4Address.hh
+++ b/Socket/Protocols/INet/INet4Address.hh
@@ -1,3 +1,5 @@
+// $Id$
+//
 // Copyright (C) 2007 
 // Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS)
 // Kompetenzzentrum fuer Satelitenkommunikation (SatCom)
@@ -42,7 +44,14 @@ namespace senf {
         INet4Address represents a simple IP address. It is modelled as a fixed-size
         container/sequence of 4 bytes.
 
+        \implementation We awkwardly need to use static named constructors (<tt>from_</tt> members)
+            instead of ordinarily overloaded constructors for one simple reason: <tt>char *</tt>
+            doubles as string literal and as arbitrary data iterator. The iterator constructor can
+            therefore not be distinguished from initialization with a string literal. Therefore we
+            need to disambiguate using the named constructors.
+
         \todo Add additional classes for CIDR addresses and networks and network math.
+        \ingroup addr_group
       */
     class INet4Address
         : public boost::array<boost::uint8_t,4>, 
@@ -50,6 +59,9 @@ namespace senf {
 
     {
     public:
+        ///////////////////////////////////////////////////////////////////////////
+        // Types
+        
         typedef uint32_t address_type;  ///< Address representation as number in host byte order
         typedef uint32_t inaddr_type;   ///< Legacy address representation in network byte order
         typedef boost::function<void (INet4Address const &)> Callback;
@@ -61,8 +73,12 @@ namespace senf {
 
         enum NoInit_t { noinit };
 
+        ///////////////////////////////////////////////////////////////////////////
+        ///\name Structors and default members
+        ///@{
+
         INet4Address();                 ///< Construct an empty address
-        INet4Address(NoInit_t);         ///< Construct uninitialized (!) address
+        explicit INet4Address(NoInit_t); ///< Construct uninitialized (!) address
         explicit INet4Address(address_type value);
                                         ///< Construct an address constant
 
@@ -104,6 +120,11 @@ namespace senf {
                                              code to convert a network byte order address in an
                                              integer number into an INet4Address. */
 
+        ///@}
+        ///////////////////////////////////////////////////////////////////////////
+        ///\name Accessors
+        ///@{
+
         bool local() const;             ///< \c true, if address is locally administered
                                         /**< This call checks, if the address is within one of the
                                              IANA private ranges. */
@@ -125,6 +146,8 @@ namespace senf {
                                              host byte order. This representation allows simple
                                              network math operations. */
 
+        ////@}
+
         struct SyntaxException : public std::exception
         { virtual char const * what() const throw() { return "invalid INet4 address syntax"; } };