osl: partial cleanup of socket_decl.hxx doxygen comments

Change-Id: Ie7de4fb82a6e5162bb1732baaa742f1943559ce6

1 files changed, 38 insertions, 19 deletions

diff --git a/include/osl/socket_decl.hxx b/include/osl/socket_decl.hxx
index 2c9020e3e93d..c470cd65f26f 100644
--- a/include/osl/socket_decl.hxx
+++ b/include/osl/socket_decl.hxx
@@ -32,7 +32,7 @@ namespace osl
 {
     enum __osl_socket_NoCopy { SAL_NO_COPY };
 
-    /** The class should be understood as a reference to a socket address handle ( struct sockaddr ).
+    /** The class should be understood as a reference to a socket address handle (struct sockaddr).
 
         The handle is mutable.
      */
@@ -54,66 +54,85 @@ namespace osl
         inline SocketAddr(SocketAddr && other);
 #endif
 
-        /** The SocketAddr takes over the responsibility of the handle ( which means,
+        /** The SocketAddr takes over the responsibility of the handle (which means
             that the handle gets destructed by the destructor of this reference)
-            @param Addr a handle
-            @param nocopy use SAL_NO_COPY
+
+            @param Addr     a handle
+            @param nocopy   use SAL_NO_COPY
          */
         inline SocketAddr(const oslSocketAddr Addr, __osl_socket_NoCopy nocopy );
 
         /** Copyconstructs the oslSocketAddr handle.
+
+            @param Addr     a handle
          */
         inline SocketAddr(oslSocketAddr Addr);
 
-        /** tcpip-specific constructor.
+        /** TCP/IP-specific constructor.
+
             @param strAddrOrHostName strAddrOrHostName hostname or dotted ip-number of the network
                                      interface, the socket shall be created on.
             @param nPort             tcp-ip port number
          */
-        inline SocketAddr( const ::rtl::OUString& strAddrOrHostName, sal_Int32 nPort );
+        inline SocketAddr(const ::rtl::OUString& strAddrOrHostName, sal_Int32 nPort);
 
         /** destroys underlying oslSocketAddress
          */
         inline ~SocketAddr();
 
-        /** checks, if the SocketAddr was created successful.
-            @return <code>true</code> if there is a valid underlying handle,
-                    otherwise false.
+        /** Checks if the SocketAddr was created successful.
+
+            @retval true    if there is a valid underlying handle
+            @retval false   no valid underlying handle
          */
         inline bool is() const;
 
         /** Converts the address to a (human readable) domain-name.
 
-            @param pResult 0, if you are not interested in errors,
+            @param pResult[out] value of 0 if you are not interested in errors,
                            otherwise *pResult contains an error code on failure
                            or osl_Socket_Ok on success
+
             @return the hostname of this SocketAddr or an empty string on failure.
-            @see osl_getHostnameOfSocketAddr()
+
+            @see osl_getHostnameOfSocketAddr
         */
-        inline ::rtl::OUString SAL_CALL getHostname( oslSocketResult *pResult = NULL ) const;
+        inline ::rtl::OUString SAL_CALL getHostname(oslSocketResult *pResult = NULL) const;
 
-        /** Sets the ipaddress or hostname of the SocketAddress
+        /** Sets the IP address or hostname of the SocketAddress
+
+           @param sDottedIpOrHostname[in]   IP address or hostname
+
+           @retval true     success
+           @retval false    failure
          */
-        inline bool SAL_CALL setHostname( const ::rtl::OUString &sDottedIpOrHostname );
+        inline bool SAL_CALL setHostname(const ::rtl::OUString &sDottedIpOrHostname);
 
         /** Returns the port number of the address.
+
             @return the port in host-byte order or OSL_INVALID_PORT on errors.
         */
         inline sal_Int32 SAL_CALL getPort() const;
 
         /** Sets the port number of the address.
-           @return true if successful.
+
+           @param nPort[in] port number
+
+           @retval true     success
+           @retval false    failure
          */
-        inline bool SAL_CALL setPort( sal_Int32 nPort );
+        inline bool SAL_CALL setPort(sal_Int32 nPort);
 
         /** Sets the address of the underlying socket address struct in network byte order.
-            @return true on success, false signals failure.
+
+           @retval true     success
+           @retval false    failure
          */
-        inline bool SAL_CALL setAddr( const ::rtl::ByteSequence & address );
+        inline bool SAL_CALL setAddr(const ::rtl::ByteSequence & address);
 
         /** Returns the address of the underlying socket in network byte order
           */
-        inline ::rtl::ByteSequence  SAL_CALL getAddr( oslSocketResult *pResult = NULL ) const;
+        inline ::rtl::ByteSequence SAL_CALL getAddr(oslSocketResult *pResult = NULL) const;
 
         /** assign the handle to this reference. The previous handle is released.
         */