Fix documentation typos

[senf.git] / Socket / INetAddressing.hh

diff --git a/Socket/INetAddressing.hh b/Socket/INetAddressing.hh
index 28a8a59..d87f71f 100644 (file)
--- a/Socket/INetAddressing.hh
+++ b/Socket/INetAddressing.hh
@@ -20,6 +20,10 @@
 // Free Software Foundation, Inc.,
 // 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 
+/** \file
+    \brief INet[46]Address and INet[46]AddressingPolicy public header
+ */
+
 #ifndef HH_INetAddressing_
 #define HH_INetAddressing_ 1
 
@@ -35,47 +39,105 @@
 //#include "INetAddressing.mpp"
 ///////////////////////////////hh.p////////////////////////////////////////
 
-namespace satcom {
-namespace lib {
+namespace senf {
+
+    /// \addtogroup addr_group
+    /// @{
+
+    /** \brief IPv4 socket address
 
-    // TODO: Implement real INet4Address datatype and 
-    // rename this one to INet4SockAddress ...
+       INet4Address wrapps the standard sockaddr_in datatype. It provides simple accessor methods
+       to accss the host and port. It does \e not integrate \c gethostbyname or DNS lookup.
 
+       \todo Implement real INet4Address datatype and rename this one to INet4SockAddress ...
+       \todo Implement more complete interface
+       \todo  gethostbyname support ?
+     */
     class INet4Address
     {
     public:
         INet4Address();
-        INet4Address(char const * address);
-        INet4Address(std::string address);
-        INet4Address(std::string host, unsigned port);
-
-        bool operator==(INet4Address const & other) const;
-
-        std::string str() const;
-        std::string host() const;
-        unsigned port() const;
-
-        // TODO: Interface
-
-        void clear();
+        INet4Address(char const * address); ///< Set address and port
+                                        /**< See INet4Address(std::string)
+                                            \throws InvalidINetAddressException
+                                            \fixme Why do I need this version? Shouldn't the
+                                            std::string version be enough ? */
+        INet4Address(std::string address); ///< Set address and port
+                                        /**< This constructor expects a string of the form
+                                            'xxx.xxx.xxx.xxx:pppp'. The constructor will use this
+                                            value to initialize the host and port members. This
+                                            constructor does \e only support numeric ip addresses
+                                            not hostnames 
+                                            \param[in] address Address and port 
+                                            \throws InvalidINetAddressException */
+        INet4Address(std::string host, unsigned port); ///< Set address and port explicitly
+                                        /**< \param[in] host ip address in dotted-quad notation
+                                            \param[in] port port number 
+                                            \throws InvalidINetAddressException */
+       
+
+        bool operator==(INet4Address const & other) const; ///< Check INet4Address for equality
+
+        std::string str() const;        ///< Return "address:port" string
+        std::string host() const;       ///< Return address in doted quad notation
+        unsigned port() const;          ///< Return portnumber
+
+        void clear();                   ///< Clear address/port to 0.0.0.0:0
+
+       /// \name Generic Address Interface
+       /// @{
 
         struct sockaddr * sockaddr_p();
         struct sockaddr const * sockaddr_p() const;
         unsigned sockaddr_len() const;
 
+       /// @}
+
     private:
         void assignString(std::string addr);
         
         struct ::sockaddr_in addr_;
     };
 
+    /** \brief Write address and port to os
+
+       \related INet4Address 
+     */
     std::ostream & operator<<(std::ostream & os, INet4Address const & addr);
 
+    /** \brief IPv6 socket address
+
+       \todo Implement
+     */
     class INet6Address
     {
-        // TODO: Implement
     };
-    
+
+    /** \brief Signal invalid INet address syntax
+
+       \related INet4Address
+       \relatesalso INet6Address
+     */
+    struct InvalidINetAddressException : public std::exception
+    { char const * what() const throw() { return "invalid inet address"; } };
+
+    /// @}
+
+    /// \addtogroup policy_impl_group
+    /// @{
+
+    /** \brief Addressing policy supporting IPv4 addressing
+       
+       \par Address Type:
+           INet4Address
+       
+       This addressing policy implements addressing using Internet V4
+       addresses.
+
+       The various members are directly importet from
+       GenericAddressingPolicy which see for a detailed
+       documentation.
+     */
     struct INet4AddressingPolicy 
         : public AddressingPolicyBase,
           private GenericAddressingPolicy<INet4Address>
@@ -88,17 +150,28 @@ namespace lib {
         using GenericAddressingPolicy<INet4Address>::bind;
     };
 
+    /** \brief Addressing policy supporting IPv6 addressing
+       
+       \par Address Type:
+           INet6Address
+       
+       This addressing policy implements addressing using Internet V6
+       addresses.
+
+       The various members are directly importet from
+       GenericAddressingPolicy which see for a detailed
+       documentation.
+
+       \todo implement
+     */
     struct INet6AddressingPolicy : public AddressingPolicyBase
     {
         typedef INet6Address Address;
-
-        // TODO: Implement
     };
 
-    struct InvalidINetAddressException : public std::exception
-    { char const * what() const throw() { return "invalid inet address"; } };
+    /// @}
 
-}}
+}
 
 ///////////////////////////////hh.e////////////////////////////////////////
 #include "INetAddressing.cci"
@@ -110,5 +183,6 @@ namespace lib {
 \f
 // Local Variables:
 // mode: c++
-// c-file-style: "satcom"
+// c-file-style: "senf"
+// fill-column: 100
 // End: