#88337# Docu reviewed

5 files changed, 495 insertions, 383 deletions

diff --git a/sal/inc/osl/socket.h b/sal/inc/osl/socket.h
index a639a3794..58fc82863 100644
--- a/sal/inc/osl/socket.h
+++ b/sal/inc/osl/socket.h
@@ -2,9 +2,9 @@
  *
  *  $RCSfile: socket.h,v $
  *
- *  $Revision: 1.5 $
+ *  $Revision: 1.6 $
  *
- *  last change: $Author: jbu $ $Date: 2001-04-27 11:00:43 $
+ *  last change: $Author: jbu $ $Date: 2001-10-24 10:49:53 $
  *
  *  The Contents of this file are made available subject to the terms of
  *  either of the following licenses
@@ -87,16 +87,17 @@ extern "C" {
 #define OSL_INVALID_PORT			0xffffffff
 #define OSL_INVALID_IPX_SOCKET_NO	0xffffffff
 
-/**@{ begin section types
+/**@HTML
+   
 */
 
-/*
+/**
     Opaque datatype SocketAddr.
 */
 typedef struct oslSocketAddrImpl * oslSocketAddr;
 
 
-/*
+/**
     Represents the address-family of a socket
 */
 typedef enum {	
@@ -106,7 +107,7 @@ typedef enum {
     osl_Socket_Family_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
 } oslAddrFamily;
 
-/*
+/**
     represent a specific protocol within a address-family
 */
 typedef enum {
@@ -119,7 +120,7 @@ typedef enum {
 } oslProtocol;
 
 
-/*
+/**
     Represents the type of a socket
 */
 typedef enum {
@@ -133,7 +134,7 @@ typedef enum {
 } oslSocketType;
 
 
-/*
+/**
     Represents socket-options
 */
 typedef enum {
@@ -159,7 +160,7 @@ typedef enum {
     osl_Socket_Option_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
 } oslSocketOption;	
 
-/*
+/**
     Represents the different socket-option levels
 */
 typedef enum  {
@@ -170,7 +171,7 @@ typedef enum  {
 } oslSocketOptionLevel;
 
 
-/*
+/**
     Represents flags to be used with send/recv-calls.
 */
 typedef enum {
@@ -183,7 +184,7 @@ typedef enum {
     osl_Socket_Msg_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
 } oslSocketMsgFlag;
 
-/*
+/**
     Used by shutdown to denote which end of the socket to "close".
 */
 typedef enum {
@@ -194,7 +195,8 @@ typedef enum {
     osl_Socket_Dir_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
 } oslSocketDirection;
 
-
+/** Describes the various error socket error conditions, which may
+    occur */
 typedef enum {
     osl_Socket_E_None,				/* no error */
     osl_Socket_E_NotSocket,			/* Socket operation on non-socket */
@@ -232,7 +234,8 @@ typedef enum {
     osl_Socket_E_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
 } oslSocketError;
 
-
+/** Common return codes of socket related functions.
+ */
 typedef enum {
     osl_Socket_Ok,          /* successful completion */
     osl_Socket_Error,       /* error occured, check osl_getLastSocketError() for details */
@@ -252,18 +255,20 @@ typedef sal_uInt8 oslSocketIpxNodeNumber[6];
 */
 
 /**	Creates a socket-address for the given family.
-    If family == osl_af_inet the address is set to INADDR_ANY
-    port 0.
+    @param family If family == osl_Socket_FamilyInet the address is
+                  set to INADDR_ANY	port 0.
     @return 0 if address could not be created.
 */
 oslSocketAddr SAL_CALL osl_createEmptySocketAddr(oslAddrFamily Family);
 
 
-/**	Create a new SocketAddress and fill it from Addr.
+/**	Creates a new SocketAddress and fills it from Addr.
 */
 oslSocketAddr SAL_CALL osl_copySocketAddr(oslSocketAddr Addr);
 
-/**	Compare to SocketAddress.
+/**	Compares the values of two SocketAddresses.
+    @return <code>sal_True</code> if both addresses denote the same socket address,
+            <code>sal_False</code> otherwise.
 */
 sal_Bool SAL_CALL osl_isEqualSocketAddr(
     oslSocketAddr Addr1, oslSocketAddr Addr2);
@@ -278,7 +283,8 @@ oslSocketAddr SAL_CALL osl_resolveHostname(rtl_uString *strHostname);
 /** Create an internet address usable for sending broadcast datagrams.
     To limit the broadcast to your subnet, pass your hosts IP address
     in dotted decimal notation as first argument.
-    @see    osl_sendToSocket(..., oslSocketAddr ReceiverAddr, ...).
+    @see    osl_sendToSocket()
+    @see    oslSocketAddr
     @param  strDottedAddr [in] dotted decimal internet address, may be 0.
     @param  Port          [in] port number in host byte order.
     @return 0 if address could not be created.
@@ -298,18 +304,11 @@ oslSocketAddr SAL_CALL osl_createInetSocketAddr (
     rtl_uString *strDottedAddr, sal_Int32 Port);
 
 
-/** Create an IPX address.
-*/
-oslSocketAddr SAL_CALL osl_createIpxSocketAddr(rtl_uString * strNetNumber,
-                                                 rtl_uString * strNodeNumber,
-                                               sal_uInt32 SocketNumber);
-
-/**	Free all memory allocated by pAddress.
+/** Frees all resources allocated by Addr. The handle Addr must not
+    be used after the call anymore.
 */
 void SAL_CALL osl_destroySocketAddr(oslSocketAddr Addr);
 
-
-
 /**	Looks up the port-number designated to the specified service/protocol-pair.
     (e.g. "ftp" "tcp").
     @return OSL_INVALID_PORT if no appropriate entry was found, otherwise the port-number.
@@ -320,36 +319,38 @@ sal_Int32 SAL_CALL osl_getServicePort(rtl_uString *strServicename, rtl_uString *
 
 /** Retrieves the address-family from the Addr.
     @return the family of the socket-address.
-    In case of an unknown family you get osl_invalid_AddrFamily.
+    In case of an unknown family you get <code>osl_Socket_FamilyInvalid</code>.
 */
 oslAddrFamily SAL_CALL osl_getFamilyOfSocketAddr(oslSocketAddr Addr);
 
 
 /** Retrieves the internet port-number of Addr.
     @return the port-number of the address in host-byte order. If Addr
-    is not an address of type osl_af_inet, it returns OSL_INVALID_PORT
+    is not an address of type <code>osl_Socket_FamilyInet</code>, it returns <code>OSL_INVALID_PORT</code>
 */
 sal_Int32 SAL_CALL osl_getInetPortOfSocketAddr(oslSocketAddr Addr);
 
 
 /** Sets the Port of Addr.
     @param Port [in] is expected in host byte-order.
-    @return False if Addr is not an inet-addr.
+    @return <code>sal_False</code> if Addr is not an inet-addr.
 */
 sal_Bool SAL_CALL osl_setInetPortOfSocketAddr(oslSocketAddr Addr, sal_Int32 Port);
 
 
-/** Gets the hostname represented by Addr.
-    @return the hostname represented by the address. If
+/** Returns the hostname represented by Addr.
+    @param strHostname out-parameter. The hostname represented by the address. If
     there is no hostname to be found, it returns 0.
 */
 oslSocketResult	SAL_CALL osl_getHostnameOfSocketAddr(oslSocketAddr Addr, rtl_uString **strHostname);
 
 
 /** Gets the address in dotted decimal format.
-    @return the dotted decimal address (e.g. 141.99.20.34) represented
-    by the address. If the address is invalid or not of type osl_af_inet,
+    @param strDottedInetAddr out-parameter. Contains the dotted decimal address
+    (e.g. 141.99.20.34) represented	by the address.
+    If the address is invalid or not of type <code>osl_Socket_FamilyInet</code>,
     it returns 0.
+    @return <code>osl_Socket_Ok</code> or <code>osl_Socket_Error</code>
 */
 oslSocketResult	SAL_CALL osl_getDottedInetAddrOfSocketAddr(oslSocketAddr Addr, rtl_uString **strDottedInetAddr);
 
@@ -357,33 +358,13 @@ oslSocketResult	SAL_CALL osl_getDottedInetAddrOfSocketAddr(oslSocketAddr Addr, r
  */
 oslSocketResult SAL_CALL osl_setAddrOfSocketAddr( oslSocketAddr Addr, sal_Sequence *pByteSeq );
 
-/** Returns the addr field in the struct sockaddr. ppByteSeq is in network byteorder. *ppByteSeq may
-    either be 0 or contain a constructed sal_Sequence.
+/** Returns the addr field in the struct sockaddr.
+    @param ppByteSeq out parameter. After the call, *ppByteSeq contains the ipadrress
+                     in network byteorder. *ppByteSeq may be 0 in case of an invalid socket handle.
+    @return <code>osl_Socket_Ok</code> or <code>osl_Socket_Error</code>
  */
 oslSocketResult SAL_CALL osl_getAddrOfSocketAddr( oslSocketAddr Addr, sal_Sequence **ppByteSeq );
     
-/** Gets the IPX Net-Number of the address.
-    @return the (4 bytes long) net-number or 0 if not an IPX address.
-*/
-oslSocketResult SAL_CALL osl_getIpxNetNumber(oslSocketAddr Addr, oslSocketIpxNetNumber NetNumber);
-
-
-/** Gets the IPX Node-Number of the address.
-    @return the (6 bytes long) net-number or 0 if not an IPX address.
-*/
-oslSocketResult SAL_CALL osl_getIpxNodeNumber(oslSocketAddr Addr, oslSocketIpxNodeNumber NodeNumber);
-
-/** Gets the IPX Socket-Number of the address.
-    @return the IPX socket number or OSL_INVALID_IPX_SOCKET_NO if not an IPX address.
-*/
-sal_Int32 SAL_CALL osl_getIpxSocketNumber(oslSocketAddr Addr);
-
-/**@} end section oslSocketAddr
-*/
-
-/**@{ begin section oslHostAddr
-*/
-
 /*
     Opaque datatype HostAddr.
 */
@@ -424,7 +405,8 @@ oslHostAddr SAL_CALL osl_createHostAddrByAddr(const oslSocketAddr Addr);
 oslHostAddr SAL_CALL osl_copyHostAddr(const oslHostAddr Addr);
 
 
-/** Free all memory allocated by Addr.
+/** Frees all resources allocated by Addr. The handle Addr must not
+    be used after the call anymore.
 */
 void SAL_CALL osl_destroyHostAddr(oslHostAddr Addr);
 
@@ -442,8 +424,8 @@ oslSocketAddr SAL_CALL osl_getSocketAddrOfHostAddr(const oslHostAddr Addr);
 
 /** Retrieve this machines hostname.
     May not always be a fully qualified domain name (FQDN).
-    @param  strLocalHostname [out] The string that receives the local host name.
-    @return True upon success, False otherwise.
+    @param  strLocalHostname out-parameter. The string that receives the local host name.
+    @return <code>sal_True</code> upon success, <code>sal_False</code> otherwise.
 */
 oslSocketResult SAL_CALL osl_getLocalHostname(rtl_uString **strLocalHostname);
 
@@ -500,7 +482,8 @@ oslSocketAddr SAL_CALL osl_getPeerAddrOfSocket(oslSocket Socket);
 /** Binds the given address to the socket.
     @param Socket [in]
     @param Address [in]
-    @return False if the bind failed.
+    @return <code>sal_False</code> if the bind failed, <code> sal_True</code> if successful.
+    @see osl_getLastSocketError()
 */
 sal_Bool SAL_CALL osl_bindAddrToSocket(oslSocket Socket,
                                        oslSocketAddr Addr);
@@ -510,11 +493,11 @@ sal_Bool SAL_CALL osl_bindAddrToSocket(oslSocket Socket,
     @param Socket [in] a bound socket.
     @param Addr [in] the peer address.
     @param pTimeout Timeout value or NULL for blocking.
-
-    @return osl_sock_result_ok on successful connection,
-            osl_sock_result_timeout if operation timed out,
-            osl_sock_result_interrupted if operation was interrupted
-            osl_sock_result_error if the connection failed.
+    
+    @return <code>osl_Socket_Ok</code> on successful connection,
+            <code>osl_Socket_TimedOut</code> if operation timed out,
+            <code>osl_Socket_Interrupted</code> if operation was interrupted
+            <code>osl_Socket_Error</code> if the connection failed.
 */
 oslSocketResult SAL_CALL osl_connectSocketTo(oslSocket Socket,
                                              oslSocketAddr Addr,
@@ -526,7 +509,7 @@ oslSocketResult SAL_CALL osl_connectSocketTo(oslSocket Socket,
     @param MaxPendingConnections [in] denotes the length of the queue of
     pending connections for this socket. If MaxPendingConnections is
     -1, the systems default value will be used (Usually 5).
-    @return False if the listen failed.
+    @return <code>sal_False</code> if the listen failed.
 */
 sal_Bool SAL_CALL osl_listenOnSocket(oslSocket Socket,
                            sal_Int32 MaxPendingConnections);
@@ -552,11 +535,11 @@ oslSocket SAL_CALL osl_acceptConnectionOnSocket(oslSocket Socket,
     this size.
     @param Flag [in] Modifier for the call. Valid values are:
     <ul>
-    <li> osl_msg_normal,
-    <li> osl_msg_oob,
-    <li> osl_msg_peek,
-    <li> osl_msg_dontroute,
-    <li> osl_msg_maxiovlen,
+    <li><code>osl_Socket_MsgNormal</code>
+    <li><code>osl_Socket_MsgOOB</code>
+    <li><code>osl_Socket_MsgPeek</code>
+    <li><code>osl_Socket_MsgDontRoute</code>
+    <li><code>osl_Socket_MsgMaxIOVLen</code>
     </ul>
 
     @return the number of received bytes.
@@ -579,11 +562,11 @@ sal_Int32 SAL_CALL osl_receiveSocket(oslSocket Socket,
     @param BufferSize [in] The size of pBuffer.
     @param Flag [in] Modifier for the call. Valid values are:
     <ul>
-    <li> osl_msg_normal,
-    <li> osl_msg_oob,
-    <li> osl_msg_peek,
-    <li> osl_msg_dontroute,
-    <li> osl_msg_maxiovlen,
+    <li><code>osl_Socket_MsgNormal</code>
+    <li><code>osl_Socket_MsgOOB</code>
+    <li><code>osl_Socket_MsgPeek</code>
+    <li><code>osl_Socket_MsgDontRoute</code>
+    <li><code>osl_Socket_MsgMaxIOVLen</code>
     </ul>
     
     @return the number of received bytes.
@@ -603,11 +586,11 @@ sal_Int32 SAL_CALL osl_receiveFromSocket(oslSocket Socket,
     this size.
     @param Flag [in] Modifier for the call. Valid values are:
     <ul>
-    <li> osl_msg_normal,
-    <li> osl_msg_oob,
-    <li> osl_msg_peek,
-    <li> osl_msg_dontroute,
-    <li> osl_msg_maxiovlen,
+    <li><code>osl_Socket_MsgNormal</code>
+    <li><code>osl_Socket_MsgOOB</code>
+    <li><code>osl_Socket_MsgPeek</code>
+    <li><code>osl_Socket_MsgDontRoute</code>
+    <li><code>osl_Socket_MsgMaxIOVLen</code>
     </ul>
 
     @return the number of transfered bytes.
@@ -619,8 +602,8 @@ sal_Int32 SAL_CALL osl_sendSocket(oslSocket Socket,
 
 /** Tries to send one datagram with BytesToSend data to the given ReceiverAddr
     via the (implicitly unconnected) datagram-socket.
-    Since we only send one packet, we don't need to concern ourselfes here with
-    incomplete sends due to packet boundaries.
+    Since there is only sent one packet, the function sends the data always complete
+    even with incomplete packet boundaries.
 
     @param Socket [in] A bound or unbound socket. Socket will be bound
     after a successful call.
@@ -633,11 +616,11 @@ sal_Int32 SAL_CALL osl_sendSocket(oslSocket Socket,
     this size.
     @param Flag [in] Modifier for the call. Valid values are:
     <ul>
-    <li> osl_msg_normal,
-    <li> osl_msg_oob,
-    <li> osl_msg_peek,
-    <li> osl_msg_dontroute,
-    <li> osl_msg_maxiovlen,
+    <li><code>osl_Socket_MsgNormal</code>
+    <li><code>osl_Socket_MsgOOB</code>
+    <li><code>osl_Socket_MsgPeek</code>
+    <li><code>osl_Socket_MsgDontRoute</code>
+    <li><code>osl_Socket_MsgMaxIOVLen</code>
     </ul>
 
     @return the number of transfered bytes.
@@ -649,22 +632,23 @@ sal_Int32 SAL_CALL osl_sendToSocket(oslSocket Socket,
                          oslSocketMsgFlag Flag);
 
 /** Checks if read operations will block.
+    
     You can specify a timeout-value in seconds/microseconds that denotes
     how long the operation will block if the Socket is not ready.
-    @return True if read operations (recv, recvFrom, accept) on the Socket
-    will NOT block; False if it would block or if an error occured.
+
+    @return <code>sal_True</code> if read operations (recv, recvFrom, accept) on the Socket
+    will NOT block; <code>sal_False</code> if it would block or if an error occured.
     
     @param Socket the Socket to perfom the operation on.
-    @param pTimeout if NULL, the operation will block without a timeout. Otherwise
-    the time define by timeout value.
+    @param pTimeout if NULL, the operation will block without a timeout. 
 */
 sal_Bool SAL_CALL osl_isReceiveReady(oslSocket Socket, const TimeValue* pTimeout);
 
 /** Checks if send operations will block.
     You can specify a timeout-value in seconds/microseconds that denotes
     how long the operation will block if the Socket is not ready.
-    @return True if send operations (send, sendTo) on the Socket
-    will NOT block; False if it would block or if an error occured.
+    @return <code>sal_True</code> if send operations (send, sendTo) on the Socket
+    will NOT block; <code>sal_False</code> if it would block or if an error occured.
     
     @param Socket the Socket to perfom the operation on.
     @param pTimeout if NULL, the operation will block without a timeout. Otherwise
@@ -675,12 +659,11 @@ sal_Bool SAL_CALL osl_isSendReady(oslSocket Socket, const TimeValue* pTimeout);
 /** Checks if a request for out-of-band data will block.
     You can specify a timeout-value in seconds/microseconds that denotes
     how long the operation will block if the Socket has no pending OOB data.
-    @return True if OOB-request operations (recv with appropriate flags)
-    on the Socket will NOT block; False if it would block or if an error occured.
+    @return <code>sal_True</code> if OOB-request operations (recv with appropriate flags)
+    on the Socket will NOT block; <code>sal_False</code> if it would block or if an error occured.
     
     @param Socket the Socket to perfom the operation on.
-    @param pTimeout if NULL, the operation will block without a timeout. Otherwise
-    the time define by timeout value.
+    @param pTimeout if NULL, the operation will block without a timeout. 
 */
 sal_Bool SAL_CALL osl_isExceptionPending(oslSocket Socket, const TimeValue* pTimeout);
 
@@ -688,11 +671,11 @@ sal_Bool SAL_CALL osl_isExceptionPending(oslSocket Socket, const TimeValue* pTim
     @param Direction denotes which end of the socket
     should be closed:
     <ul>
-    <li> osl_shut_read	closes read operations.
-    <li> osl_shut_write closes write operations.
-    <li> osl_shut_readwrite closes read and write operations.
+    <li> <code>osl_Socket_DirRead</code>	closes read operations.
+    <li> <code>osl_Socket_DirReadWrite</code> closes write operations.
+    <li> <code>osl_Socket_DirWrite</code> closes read and write operations.
     </ul>
-    @return True if the socket could be closed down.
+    @return <code>sal_True</code> if the socket could be closed down.
 */
 sal_Bool SAL_CALL osl_shutdownSocket(oslSocket Socket,
                            oslSocketDirection Direction);
@@ -710,35 +693,76 @@ sal_Bool SAL_CALL osl_shutdownSocket(oslSocket Socket,
     @param Option denotes the option to query.
     Valid values (depending on the Level) are:
     <ul>
-    <li> osl_so_debug,
-    <li> osl_so_acceptconn,
-    <li> osl_so_reuseaddr,
-    <li> osl_so_keepalive,
-    <li> osl_so_dontroute,
-    <li> osl_so_broadcast,
-    <li> osl_so_useloopback,
-    <li> osl_so_linger,
-    <li> osl_so_oobinline,
-    <li> osl_so_sndbuf,
-    <li> osl_so_rcvbuf,
-    <li> osl_so_sndlowat,
-    <li> osl_so_rcvlowat,
-    <li> osl_so_sndtimeo,
-    <li> osl_so_rcvtimeo,
-    <li> osl_so_error,
-    <li> osl_so_type,
-    <li> osl_so_tcp_nodelay,	(sol_tcp)
+    <li> <code>osl_Socket_Option_Debug</code><br>
+    (sal_Bool) Socket debug flag 1 = enabled, 0 = disabled.
+            
+    <li> <code>osl_Socket_OptionAcceptConn</code><br>
+    <li> <code>osl_Socket_OptionReuseAddr</code><br>
+    (sal_Bool) Allows the socket to be bound to an address that is
+    already in use.
+    1 = multiple bound allowed, 0 = no multiple bounds allowed
+              
+    <li><code>osl_Socket_OptionKeepAlive</code><br>
+    (sal_Bool) Keepalive packets are sent by the underlying socket.
+    1 = enabled, 0 = disabled
+              
+    <li><code>osl_Socket_OptionDontRoute</code><br>
+    (sal_Bool) Do not route: send directly to interface.
+    1 = do not route , 0 = routing possible
+               
+    <li><code>osl_Socket_OptionBroadcast</code><br>
+    (sal_Bool) Transmission of broadcast messages are allowed on the socket. 
+    1 = transmission allowed, 0 = transmission disallowed
+               
+    <li><code>osl_Socket_OptionUseLoopback</code><br>
+
+    <li><code>osl_Socket_OptionLinger</code><br>
+    (sal_Int32) Linger on close if unsent data is present.
+    0 = linger is off, > 0  = timeout in seconds.
+              
+    <li><code>osl_Socket_OptionOOBinLine</code><br>
+              
+
+    <li><code>osl_Socket_OptionSndBuf</code><br>
+    (sal_Int32) Size of the send buffer in bytes. Data is sent after
+    SndTimeo or when the buffer is full. This allows faster writing
+    to the socket.
+            
+    <li><code>osl_Socket_OptionRcvBuf</code><br>
+    (sal_Int32) Size of the receive buffer in bytes. Data is sent after
+    SndTimeo or when the buffer is full. This allows faster writing
+    to the socket and larger packet sizes.
+            
+    <li><code>osl_Socket_OptionSndLowat</code><br>
+            
+    <li><code>osl_Socket_OptionRcvLowat</code><br>
+            
+    <li><code>osl_Socket_OptionSndTimeo</code><br>
+    (sal_Int32) Data is sent after this timeout. This allows gathering
+    of data to send larger packages but increases latency times.
+            
+    <li><code>osl_Socket_OptionRcvTimeo</code><br>
+            
+    <li><code>osl_Socket_OptionError</code><br>
+    <li><code>osl_Socket_OptionType</code><br>
+
+    <li><code>osl_Socket_OptionTcpNoDelay</code><br>
+    Disables the Nagle algorithm for send coalescing. (Do not
+    collect data until a packet is full, instead send immediatly.
+    This increases network traffic but might improve latency-times.)
+    1 = disables the algorithm, 0 = keeps it enabled. 
     </ul>
     If not above mentioned otherwise, the options are only valid for
-    level sol_socket.
-    
-    @param pBuffer Pointer to a Buffer with enough room to take the desired
+    level <code>osl_Socket_LevelSocket</code>.
+
+    @param pBuffer Pointer to a buffer large enough to take the desired
     attribute-value.
 
     @param BufferSize contains the length of the Buffer.
 
     @return -1 if an error occured or else the size of the data copied into
     pBuffer.
+    @see osl_setSocketOption()
 */
 sal_Int32 SAL_CALL osl_getSocketOption(oslSocket            Socket,
                                oslSocketOptionLevel Level,
@@ -757,30 +781,8 @@ sal_Int32 SAL_CALL osl_getSocketOption(oslSocket            Socket,
     <li> osl_sol_tcp:		Level of Transmission Control Protocol
     </ul>
     
-    @param Option denotes the option to modify.
-    Valid values (depending on the Level) are:
-    <ul>
-    <li> osl_so_debug,
-    <li> osl_so_acceptconn,
-    <li> osl_so_reuseaddr,
-    <li> osl_so_keepalive,
-    <li> osl_so_dontroute,
-    <li> osl_so_broadcast,
-    <li> osl_so_useloopback,
-    <li> osl_so_linger,
-    <li> osl_so_oobinline,
-    <li> osl_so_sndbuf,
-    <li> osl_so_rcvbuf,
-    <li> osl_so_sndlowat,
-    <li> osl_so_rcvlowat,
-    <li> osl_so_sndtimeo,
-    <li> osl_so_rcvtimeo,
-    <li> osl_so_error,
-    <li> osl_so_type,
-    <li> osl_so_tcp_nodelay,	(sol_tcp)
-    </ul>
-    If not above mentioned otherwise, the options are only valid for
-    level sol_socket.
+    @param Option denotes the option to modify. See osl_setSocketOption() for more
+    details.
     
     @param pBuffer Pointer to a Buffer which contains the attribute-value.
 
@@ -796,8 +798,9 @@ sal_Bool SAL_CALL osl_setSocketOption(oslSocket Socket,
 
 /** Enables/disables non-blocking-mode of the socket.
     @param Socket Change mode for this socket.
-    @param On True: enable non-blocking mode, False: disable non-blocking mode.
-    @return True if mode could be changed.
+    @param On <code>sal_True</code> enables non-blocking mode,
+              <code>sal_False</code> disables non-blocking mode.
+    @return <code>sal_True</code> if mode could be changed.
 */
 sal_Bool SAL_CALL osl_enableNonBlockingMode(oslSocket Socket,
                                   sal_Bool On);
@@ -813,28 +816,26 @@ sal_Bool SAL_CALL osl_isNonBlockingMode(oslSocket Socket);
 /** Queries the socket for its type.
     @return one of:
     <ul>
-    <li> osl_sock_stream,
-    <li> osl_sock_dgram,
-    <li> osl_sock_raw,
-    <li> osl_sock_rdm,
-    <li> osl_sock_seqpacket,
+    <li> osl_Socket_TypeStream
+    <li> osl_Socket_TypeDgram
+    <li> osl_Socket_TypeRaw
+    <li> osl_Socket_TypeRdm
+    <li> osl_Socket_TypeSeqPacket
     <li> osl_invalid_SocketType, if an error occured
     </ul>
     
 */
 oslSocketType SAL_CALL osl_getSocketType(oslSocket Socket);
 
-/** Delivers a string which describes the last socket error.
-    @param strError The string that receives the error message.
-    than the provided buffer, it will be cut short. Buffer sizes about 128 chars
-    should be large enough.
+/** returns  a string which describes the last socket error.
+    @param strError out-parameter. The string that receives the error message.
 */
 void SAL_CALL osl_getLastSocketErrorDescription(oslSocket Socket, rtl_uString **strError);
 
-/** Delivers a constant decribing the last error for the socket system.
-    @return osl_Socket_E_NONE if no error occured, osl_invalid_SocketError if
-    an unknown (unmapped) error occured, otherwise an enum describing the
-    error.
+/** returns a constant decribing the last error for the socket system.
+    @return <code>osl_Socket_E_NONE</code> if no error occured,
+            <code>osl_invalid_SocketError</code> if	an unknown (unmapped)
+            error occured, otherwise an enum describing the	error.
 */
 oslSocketError SAL_CALL osl_getLastSocketError(oslSocket Socket);
 
@@ -872,7 +873,7 @@ void SAL_CALL osl_removeFromSocketSet(oslSocketSet Set, oslSocket Socket);
 /** Checks if socket is in the set.
     @param Set the set to be checked.
     @param Socket check if this socket is in the set.
-    @return True if socket is in the set.
+    @return <code>sal_True</code> if socket is in the set.
 */
 sal_Bool SAL_CALL osl_isInSocketSet(oslSocketSet Set, oslSocket Socket);
 
@@ -896,6 +897,8 @@ sal_Int32 SAL_CALL osl_demultiplexSocketEvents(oslSocketSet IncomingSet,
                                     oslSocketSet OutOfBandSet,
                                     const TimeValue* pTimeout);
 
+/** Closes the socket terminating any ongoing dataflow.
+ */
 void SAL_CALL osl_closeSocket(oslSocket Socket);
 
     
diff --git a/sal/inc/osl/socket_decl.hxx b/sal/inc/osl/socket_decl.hxx
index 077ad9fed..3f7ddd95e 100644
--- a/sal/inc/osl/socket_decl.hxx
+++ b/sal/inc/osl/socket_decl.hxx
@@ -2,9 +2,9 @@
  *
  *  $RCSfile: socket_decl.hxx,v $
  *
- *  $Revision: 1.2 $
+ *  $Revision: 1.3 $
  *
- *  last change: $Author: jbu $ $Date: 2001-03-15 11:07:36 $
+ *  last change: $Author: jbu $ $Date: 2001-10-24 10:49:53 $
  *
  *  The Contents of this file are made available subject to the terms of
  *  either of the following licenses
@@ -74,14 +74,16 @@
 #include <rtl/byteseq.hxx>
 #endif
 
+/** @HTML
+ */
 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 handle is mutable. 
      */
-    enum __osl_socket_NoCopy { SAL_NO_COPY };
-    
     class SocketAddr
     {
     protected:
@@ -98,10 +100,12 @@ namespace osl
 
         /** The SocketAddr takes over the responsibility of the handle ( which means,
             that the handle gets destructed by the destructor of this reference)
+
+            @param nocopy use SAL_NO_COPY
          */
         inline SocketAddr(const oslSocketAddr , __osl_socket_NoCopy nocopy );
 
-        /**
+        /** Copyconstructs the oslSocketAddr handle.
          */
         inline SocketAddr(oslSocketAddr Addr);
 
@@ -117,17 +121,23 @@ namespace osl
         inline ~SocketAddr();
 
         /** checks, if the SocketAddr was created successful.
+            @return <code>sal_True</code> if there is a valid underlying handle,
+                    otherwise sal_False.
          */
         inline sal_Bool is() const;
 
         /** Converts the address to a (human readable) domain-name.
+
             @param pResult 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()
         */
         inline ::rtl::OUString SAL_CALL getHostname( oslSocketResult *pResult = 0 ) const;
 
+        /** Sets the ipaddress or hostname of the SocketAddress
+         */
         inline sal_Bool SAL_CALL setHostname( const ::rtl::OUString &sDottedIpOrHostname );
 
         /** Returns the port number of the address.
@@ -149,7 +159,7 @@ namespace osl
           */
         inline ::rtl::ByteSequence  SAL_CALL getAddr( oslSocketResult *pResult = 0 ) const;
 
-        /** assign the handle to this reference. The previous handle is release.
+        /** assign the handle to this reference. The previous handle is released.
         */
         inline SocketAddr & SAL_CALL operator= (oslSocketAddr Addr);
 
@@ -157,7 +167,8 @@ namespace osl
          */
         inline SocketAddr & SAL_CALL operator= (const SocketAddr& Addr);
 
-        /** Assigns the socket addr without copyconstructing it.
+        /** Assigns the socket addr without copyconstructing it. 
+            @param nocopy use SAL_NO_COPY
           */
         inline SocketAddr & SAL_CALL assign( oslSocketAddr Addr, __osl_socket_NoCopy nocopy );
         
@@ -181,6 +192,7 @@ namespace osl
         static inline ::rtl::OUString SAL_CALL getLocalHostname( oslSocketResult *pResult = 0);
         
         /** Tries to find an address for a host.
+            @see osl_resolveHostname()
             @return A new created socket-address or 0 if the name could not be found.
         */
         static inline void SAL_CALL resolveHostname(
@@ -189,7 +201,7 @@ namespace osl
         /**
            Tries to find the port associated with the given service/protocol-
            pair (e.g. "ftp"/"tcp").
-           @return the port number in host-byte order or CVOS_PORT_NONE
+           @return the port number in host-byte order or <code>OSL_INVALID_PORT</code>
            if no service/protocol pair could be found.
         */
         static inline sal_Int32 SAL_CALL getServicePort(
@@ -218,6 +230,10 @@ namespace osl
 
         inline Socket( oslSocket socketHandle );
 
+        /** The instance takes over the handle's ownership without acquiring the
+            handle, but releases it within the dtor.
+            @param noacquire use SAL_NO_ACQUIRE
+         */
         inline Socket( oslSocket socketHandle, __sal_NoAcquire noacquire );
         
         /** Destructor. Releases the underlying handle
@@ -235,33 +251,34 @@ namespace osl
         inline Socket& SAL_CALL operator= (const Socket& sock);
 
         /** 
-           @return true, when the underlying handle of both
-                         Socket references are identical.
-                   false otherwise
+           @return <code>sal_True</code>, when the underlying handle of both
+                         Socket instances are identical, <code>sal_False</code> otherwise.
          */
         inline sal_Bool SAL_CALL operator==( const Socket& rSocket ) const ;
 
         /** 
-           @return true, when the underlying handle of this socket reference
-                         and the parameter is identical.
-                   false otherwise
+           @return <code>sal_True</code>, when the underlying handle of both
+                         Socket instances are identical, <code>sal_False</code> otherwise.
          */
         inline sal_Bool SAL_CALL operator==( const oslSocket socketHandle ) const;
 
-        /** Closes a definite direction of the bidirectional stream
+        /** Closes a definite or both directions of the bidirectional stream.
             
-           @param Direction 
+           @param Direction
+           @see osl_shutdownSocket()
          */
         inline void SAL_CALL shutdown( oslSocketDirection Direction = osl_Socket_DirReadWrite );
 
         /** Closes a socket.
             Note that closing a socket is identical to shutdown( osl_Socket_DirReadWrite ),
             as the operating system distinguish both cases, both functions or offered in this API.
+            @see osl_closeSocket()
          */
         inline void SAL_CALL close();
 
         /** Retrieves the address of the local interface of this socket.
             @return Addr [out] receives the address.
+            @see osl_getLocalAddrOfSocket()
         */
         inline void SAL_CALL getLocalAddr( SocketAddr &Addr ) const;
 
@@ -296,12 +313,12 @@ namespace osl
         */
         inline sal_Bool SAL_CALL bind(const SocketAddr& LocalInterface);
         
-
         /** Checks if read operations will block.
+            
             You can specify a timeout-value in seconds/nanoseconds that denotes
-            how sal_Int32 the operation will block if the Socket is not ready.
-            @return True if read operations (recv, recvFrom, accept) on the Socket
-            will NOT block; False if it would block or if an error occured.
+            how the operation will block if the Socket is not ready.
+            @return <code>sal_True</code> if read operations (recv, recvFrom, accept) on the Socket
+            will NOT block; <code>sal_False</code> if it would block or if an error occured.
             
             @param pTimeout if 0, the operation will block without a timeout. Otherwise
             the specified amout of time.
@@ -309,10 +326,11 @@ namespace osl
         inline sal_Bool	SAL_CALL isRecvReady(const TimeValue *pTimeout = 0) const;
 
         /** Checks if send operations will block.
+            
             You can specify a timeout-value in seconds/nanoseconds that denotes
-            how sal_Int32 the operation will block if the Socket is not ready.
-            @return True if send operations (send, sendTo) on the Socket
-            will NOT block; False if it would block or if an error occured.
+            how the operation will block if the Socket is not ready.
+            @return <code>sal_True</code> if send operations (send, sendTo) on the Socket
+            will NOT block; <code>sal_False</code> if it would block or if an error occured.
             
             @param pTimeout if 0, the operation will block without a timeout. Otherwise
             the specified amout of time.
@@ -321,11 +339,13 @@ namespace osl
 
         
         /** Checks if a request for out-of-band data will block.
+            
             You can specify a timeout-value in seconds/nanoseconds that denotes
-            how sal_Int32 the operation will block if the Socket has no pending OOB data.
+            how the operation will block if the Socket has no pending OOB data.
             
-            @return True if OOB-request operations (recv with appropriate flags) 
-            on the Socket will NOT block; False if it would block or if an error occured.
+            @return <code>sal_True</code> if OOB-request operations (recv with appropriate flags) 
+            on the Socket will NOT block; <code>sal_True</code>if it would block or if
+            an error occured.
             
             @param pTimeout if 0, the operation will block without a timeout. Otherwise
             the specified amout of time.
@@ -335,84 +355,95 @@ namespace osl
         
         /** Queries the socket for its type.
             @return one of:
+            <ul>
+            <li> <code>osl_Socket_TypeStream</code>
+            <li> <code>osl_Socket_TypeDgram</code>
+            <li> <code>osl_Socket_TypeRaw</code>
+            <li> <code>osl_Socket_TypeRdm</code>
+            <li> <code>osl_Socket_TypeSeqPacket</code>
+            <li> <code>osl_invalid_SocketType</code>, if an error occured
+            </ul>
         */
         inline oslSocketType	SAL_CALL getType() const;
         
         /** Retrieves option-attributes associated with the socket.
             @param Option The attribute to query.
             Valid values (depending on the Level) are:
-        
-            - osl_Socket_Option_Debug
-              (sal_Bool) Socket debug flag 1 = enabled, 0 = disabled.
+            <ul>
+            <li> <code>osl_Socket_Option_Debug</code><br>
+                 (sal_Bool) Socket debug flag 1 = enabled, 0 = disabled.
             
-            - osl_Socket_OptionAcceptConn
-            - osl_Socket_OptionReuseAddr
+            <li> <code>osl_Socket_OptionAcceptConn</code><br>
+            <li> <code>osl_Socket_OptionReuseAddr</code><br>
               (sal_Bool) Allows the socket to be bound to an address that is
               already in use.
               1 = multiple bound allowed, 0 = no multiple bounds allowed
               
-            - osl_Socket_OptionKeepAlive
+            <li><code>osl_Socket_OptionKeepAlive</code><br>
                (sal_Bool) Keepalive packets are sent by the underlying socket.
                1 = enabled, 0 = disabled
               
-            - osl_Socket_OptionDontRoute
+            <li><code>osl_Socket_OptionDontRoute</code><br>
                (sal_Bool) Do not route: send directly to interface.
                   1 = do not route , 0 = routing possible
                
-            - osl_Socket_OptionBroadcast
+            <li><code>osl_Socket_OptionBroadcast</code><br>
                (sal_Bool) Transmission of broadcast messages are allowed on the socket. 
                1 = transmission allowed, 0 = transmission disallowed
                
-            - osl_Socket_OptionUseLoopback
+            <li><code>osl_Socket_OptionUseLoopback</code><br>
 
-            - osl_Socket_OptionLinger
+            <li><code>osl_Socket_OptionLinger</code><br>
                (sal_Int32) Linger on close if unsent data is present.
                0 = linger is off, > 0  = timeout in seconds.
               
-            - osl_Socket_OptionOOBinLine
+            <li><code>osl_Socket_OptionOOBinLine</code><br>
               
 
-            - osl_Socket_OptionSndBuf
+            <li><code>osl_Socket_OptionSndBuf</code><br>
               (sal_Int32) Size of the send buffer in bytes. Data is sent after
               SndTimeo or when the buffer is full. This allows faster writing
               to the socket.
             
-            - osl_Socket_OptionRcvBuf
+            <li><code>osl_Socket_OptionRcvBuf</code><br>
               (sal_Int32) Size of the receive buffer in bytes. Data is sent after
               SndTimeo or when the buffer is full. This allows faster writing
               to the socket and larger packet sizes.
             
-            - osl_Socket_OptionSndLowat
+            <li><code>osl_Socket_OptionSndLowat</code><br>
             
-            - osl_Socket_OptionRcvLowat
+            <li><code>osl_Socket_OptionRcvLowat</code><br>
             
-            - osl_Socket_OptionSndTimeo
+            <li><code>osl_Socket_OptionSndTimeo</code><br>
               (sal_Int32) Data is sent after this timeout. This allows gathering
               of data to send larger packages but increases latency times.
             
-            - osl_Socket_OptionRcvTimeo
+            <li><code>osl_Socket_OptionRcvTimeo</code><br>
             
-            - osl_Socket_OptionError      
-            - osl_Socket_OptionType       
+            <li><code>osl_Socket_OptionError</code><br>
+            <li><code>osl_Socket_OptionType</code><br>
 
-            - osl_Socket_OptionTcpNoDelay
+            <li><code>osl_Socket_OptionTcpNoDelay</code><br>
               Disables the Nagle algorithm for send coalescing. (Do not
               collect data until a packet is full, instead send immediatly.
               This increases network traffic but might improve latency-times.)
               1 = disables the algorithm, 0 = keeps it enabled. 
+            </ul>
             
-            If not above mentioned otherwise, the options are only valid for
-            level TLevel_Socket.
-            
+              If not above mentioned otherwise, the options are only valid for
+              level <code>osl_Socket_LevelSocket</code>.
             @param pBuffer The Buffer will be filled with the attribute.
             
             @param BufferSize The size of pBuffer.
             
-            @param Level The option level. Valid values are:
-            - osl_Socket_LevelSocket : Socket Level
-            - osl_Socket_LevelTcp    : Level of Transmission Control Protocol
-            
-            @return The size of the attribute copied into pBuffer ot -1 if an error
+            @param Level The option level.
+
+            Valid values are:
+            <ul>
+            <li><code>osl_Socket_LevelSocket</code> : Socket Level
+            <li><code>osl_Socket_LevelTcp</code>    : Level of Transmission Control Protocol
+            </ul>
+            @return The size of the attribute copied into pBuffer or -1 if an error
             occured.
         */
         inline sal_Int32 SAL_CALL getOption(
@@ -420,29 +451,31 @@ namespace osl
             void* pBuffer,
             sal_uInt32 BufferLen,
             oslSocketOptionLevel Level= osl_Socket_LevelSocket) const;
-        
+
         /** Sets the sockets attributes.
             
             @param Option denotes the option to modify.
             Valid values (depending on the Level) are:
-            - osl_Socket_Option_Debug      
-            - osl_Socket_OptionAcceptConn 
-            - osl_Socket_OptionReuseAddr  
-            - osl_Socket_OptionKeepAlive  
-            - osl_Socket_OptionDontRoute  
-            - osl_Socket_OptionBroadcast  
-            - osl_Socket_OptionUseLoopback
-            - osl_Socket_OptionLinger     
-            - osl_Socket_OptionOOBinLine  
-            - osl_Socket_OptionSndBuf    
-            - osl_Socket_OptionRcvBuf     
-            - osl_Socket_OptionSndLowat   
-            - osl_Socket_OptionRcvLowat   
-            - osl_Socket_OptionSndTimeo   
-            - osl_Socket_OptionRcvTimeo   
-            - osl_Socket_OptionError      
-            - osl_Socket_OptionType       
-            - osl_Socket_OptionTcpNoDelay 
+            <ul>
+            <li> osl_Socket_Option_Debug      
+            <li> osl_Socket_OptionAcceptConn 
+            <li> osl_Socket_OptionReuseAddr  
+            <li> osl_Socket_OptionKeepAlive  
+            <li> osl_Socket_OptionDontRoute  
+            <li> osl_Socket_OptionBroadcast  
+            <li> osl_Socket_OptionUseLoopback
+            <li> osl_Socket_OptionLinger     
+            <li> osl_Socket_OptionOOBinLine  
+            <li> osl_Socket_OptionSndBuf    
+            <li> osl_Socket_OptionRcvBuf     
+            <li> osl_Socket_OptionSndLowat   
+            <li> osl_Socket_OptionRcvLowat   
+            <li> osl_Socket_OptionSndTimeo   
+            <li> osl_Socket_OptionRcvTimeo   
+            <li> osl_Socket_OptionError      
+            <li> osl_Socket_OptionType       
+            <li> osl_Socket_OptionTcpNoDelay
+            </ul>
             
             If not above mentioned otherwise, the options are only valid for
             level osl_Socket_LevelSocket.
@@ -453,8 +486,10 @@ namespace osl
             
             @param Level selects the level for which an option should be changed.
             Valid values are:
-            - osl_Socket_evel_Socket : Socket Level
-            - osl_Socket_Level_Tcp   : Level of Transmission Control Protocol
+            <ul>
+            <li> osl_Socket_evel_Socket : Socket Level
+            <li> osl_Socket_Level_Tcp   : Level of Transmission Control Protocol
+            </ul>
 
             @return True if the option could be changed.
         */
@@ -464,38 +499,39 @@ namespace osl
                                             oslSocketOptionLevel Level= osl_Socket_LevelSocket ) const;
 
         /** Convenience function for setting sal_Bool and sal_Int32 option values.
-            @see setOption for a complete description of possible options.
+            @see setOption() 
          */
         inline sal_Bool setOption( oslSocketOption option, sal_Int32 nValue  );
 
         /** Convenience function for retrieving sal_Bool and sal_Int32 option values.
-            @see setOption for a complete description of possible options.
+            @see setOption() 
          */
         inline sal_Int32 getOption( oslSocketOption option ) const;
 
         /** Enables/disables non-blocking mode of the socket.
-            @param bNonBlockingMode If True, blocking mode will be switched off
-                   If false, the socket will become a blocking
+            @param bNonBlockingMode If <code>sal_True</code>, blocking mode will be switched off
+                   If <code>sal_False</code>, the socket will become a blocking
                    socket (which is the default behaviour of a socket).
-            @return True if mode could be set.
+            @return <code>sal_True</code> if mode could be set.
         */
         inline sal_Bool SAL_CALL enableNonBlockingMode( sal_Bool bNonBlockingMode);
         
         /** Query blocking mode of the socket.
-            @return True if non-blocking mode is set.
+            @return <code>sal_True</code> if non-blocking mode is set.
         */
         inline sal_Bool SAL_CALL isNonBlockingMode() const;
 
 
-        /** Gets clears the error status
-            @returns the current error state.
+        /** clears the error status
         */
         inline void	SAL_CALL clearError() const;
 
-        /** Delivers a constant decribing the last error for the socket system.
-            @return ENONE if no error occured, invalid_SocketError if
+        /** returns a constant decribing the last error for the socket system.
+            
+            @return osl_Socket_E_NONE if no error occured, invalid_SocketError if
             an unknown (unmapped) error occured, otherwise an enum describing the
             error.
+            @see osl_getLastSocketError()
         */
         inline oslSocketError getError() const;
 
@@ -503,7 +539,7 @@ namespace osl
          */
         inline ::rtl::OUString getErrorAsString( ) const;
 
-        /** Returns the underlying handle unacquired  (The caller must acquire it to keep it)
+        /** Returns the underlying handle unacquired  (The caller must acquire it to keep it).
          */
         inline oslSocket getHandle() const;
     };
@@ -512,10 +548,11 @@ namespace osl
     class StreamSocket : public Socket 
     {
     public:
-        /** Creates a socket that can accept connections. 
+        /** Creates a socket. 
             @param Type For some protocols it might be desirable to
-            use a different type than sock_stream (like sock_seqpacket).
-            Therefore we do not hide this parameter here.
+            use a different type than <code>osl_Socket_TypeStream</code>
+            (like <code>osl_Socket_TypeSeqPacket</code>).
+            Therefore this parameter is not hidden.
         */
           inline StreamSocket(oslAddrFamily Family = osl_Socket_FamilyInet, 
                             oslProtocol	Protocol = osl_Socket_ProtocolIp,
@@ -528,17 +565,18 @@ namespace osl
         inline StreamSocket( oslSocket Socket );
 
         /** Retrieves n bytes from the stream and copies them into pBuffer.
-            The method avoids incomplete reads due to packet boundaries.		
-            @param pBuffer receives the read data.
-            @param n the number of bytes to read. pBuffer must be large enough
-            to hold the n bytes!
+            The method avoids incomplete reads due to packet boundaries and is thus
+            blocking.
+            @param pBuffer receives the read data. pBuffer must be large enough
+            to hold n bytes.
+            @param n the number of bytes to read. 
             @return	the number of read bytes. The number will only be smaller than
-            n if an exceptional condition (e.g. connection closed) occurs.				 
+            n if an exceptional condition (e.g. connection closed) occurs.
         */
         inline sal_Int32 SAL_CALL read(void* pBuffer, sal_uInt32 n);
 
         /** Writes n bytes from pBuffer to the stream. The method avoids 
-            incomplete writes due to packet boundaries.
+            incomplete writes due to packet boundaries and is thus blocking.
             @param pBuffer contains the data to be written.
             @param n the number of bytes to write.
             @return the number of written bytes. The number will only be smaller than
@@ -547,38 +585,41 @@ namespace osl
         inline sal_Int32 SAL_CALL write(const void* pBuffer, sal_uInt32 n);
 
 
-        /** Tries to receives BytesToRead data from the connected socket,
+        /** Tries to receive BytesToRead data from the connected socket,
             
             @param pBuffer [out] Points to a buffer that will be filled with the received 
-            data.
-            @param BytesToRead [in] The number of bytes to read. pBuffer must have at least
-            this size.
+            data. pBuffer must have at least have a size of BytesToRead.
+            @param BytesToRead [in] The number of bytes to read. 
             @param Flag [in] Modifier for the call. Valid values are:
 
-            - TMsg_Normal   
-            - TMsg_OOB      
-            - TMsg_Peek     
-            - TMsg_DontRoute
-            - TMsg_MaxIOVLen
-            @return the number of received bytes.
+            <ul>
+            <li><code>osl_Socket_MsgNormal</code>
+            <li><code>osl_Socket_MsgOOB</code>
+            <li><code>osl_Socket_MsgPeek</code>
+            <li><code>osl_Socket_MsgDontRoute</code>
+            <li><code>osl_Socket_MsgMaxIOVLen</code>
+            </ul>
+            @return the number of received bytes, which may be less than BytesToRead.
         */
         inline sal_Int32 SAL_CALL recv(void* pBuffer, 
                                        sal_uInt32 BytesToRead, 
                                        oslSocketMsgFlag flags= osl_Socket_MsgNormal);
 
-        /** Tries to sends BytesToSend data from the connected socket.
+        /** Tries to send BytesToSend data to the connected socket.
             
             @param pBuffer [in] Points to a buffer that contains the send-data.
             @param BytesToSend [in] The number of bytes to send. pBuffer must have at least
             this size.
             @param Flag [in] Modifier for the call. Valid values are:
-            - TMsg_Normal   
-            - TMsg_OOB      
-            - TMsg_Peek     
-            - TMsg_DontRoute
-            - TMsg_MaxIOVLen
+            <ul>
+            <li><code>osl_Socket_MsgNormal</code>
+            <li><code>osl_Socket_MsgOOB</code>
+            <li><code>osl_Socket_MsgPeek</code>
+            <li><code>osl_Socket_MsgDontRoute</code>
+            <li><code>osl_Socket_MsgMaxIOVLen</code>
+            </ul>
 
-            @return the number of transfered bytes.
+            @return the number of transfered bytes. It may be less than BytesToSend.
         */
         sal_Int32 SAL_CALL send(const void* pBuffer, 
                                 sal_uInt32 BytesToSend, 
@@ -590,7 +631,8 @@ namespace osl
     public:
         /** Creates a socket that can connect to a (remote) host.
             @param Type For some protocols it might be desirable to
-            use a different type than sock_stream (like sock_seqpacket).
+            use a different type than sock_stream <code>osl_Socket_TypeSeqPacket</code>
+            (like <code>osl_Socket_TypeSeqPacket</code>).
             Therefore we do not hide this parameter here.
         */
           ConnectorSocket(oslAddrFamily Family = osl_Socket_FamilyInet, 
@@ -600,15 +642,18 @@ namespace osl
         
         /** Connects the socket to a (remote) host.
             @param TargetHost The address of the target.
-            @param pTimeOut The timeout for blocking. 
-            @return result_ok if connected successfully,
-            result_timeout on timeout,
-            result_interrupted if unblocked forcefully (by close()),
-            result_error if connect failed.
+            @param pTimeOut The timeout for blocking. If 0, a default system dependent timeout
+                            us used.
+            @return <code> osl_Socket_Ok</code> if connected successfully,
+            <code>osl_Socket_TimedOut</code> on timeout,
+            <code>osl_Socket_Interrupted</code> if unblocked forcefully (by osl::Socket::close()),
+            <code>osl_Socket_Error</code> if connect failed.
         */
         oslSocketResult SAL_CALL connect(const SocketAddr& TargetHost, const TimeValue* pTimeout = 0);
     };
 
+    /** Allows to accept socket connections.
+     */
     class AcceptorSocket : public Socket
     {
     public:
@@ -621,28 +666,27 @@ namespace osl
             @param MaxPendingConnections The maximum number of pending
             connections (waiting to be accepted) on this socket. If you use
             -1, a system default value is used.
-            @return True if call was successful.
+            @return <code>sal_True</code> if call was successful.
         */
         inline sal_Bool SAL_CALL listen(sal_Int32 MaxPendingConnections= -1);
 
         /** Accepts incoming connections on the socket. You must
-            precede this call with bind() and listen().
+            precede this call with osl::Socket::bind() and listen().
             @param Connection receives the incoming connection.
-            @return result_ok: if a connection has been accepted,
-            result_timeout: if m_RecvTimeout milliseconds passed without connect,
-            result_error: on errors.
+            @return <code>osl_Socket_Ok</code>, if a connection has been accepted,
+            <code>osl_Socket_TimedOut</code>, if m_RecvTimeout milliseconds passed without connect,
+            <code>osl_Socket_Error</code> on errors.
         */
         inline oslSocketResult SAL_CALL acceptConnection( StreamSocket& Connection);
 
         /** Accepts incoming connections on the socket. You must
-            precede this call with bind() and listen().
+            precede this call with osl::Socket::bind() and listen().
             @param PeerAddr receives the address of the connecting entity 
             (your communication	partner).
             @param Connection receives the incoming connection.
-            @return True if a connection has been accepted, False on errors.
-            @return result_ok: if a connection has been accepted,
-            result_timeout: if m_RecvTimeout milliseconds passed without connect,
-            result_error: on errors.
+            @return <code>osl_Socket_Ok</code>, if a connection has been accepted,
+            <code>osl_Socket_TimedOut</code>, if m_RecvTimeout milliseconds passed without connect,
+            <code>osl_Socket_Error</code> on errors.
         */
         inline oslSocketResult SAL_CALL acceptConnection( StreamSocket&	Connection, SocketAddr & PeerAddr);
     };
@@ -672,11 +716,11 @@ namespace osl
             @param BufferSize [in] The size of pBuffer.
             @param Flag [in] Modifier for the call. Valid values are:
             <ul>
-            <li> TMsg_Normal   
-            <li> TMsg_OOB      
-            <li> TMsg_Peek     
-            <li> TMsg_DontRoute
-            <li> TMsg_MaxIOVLen
+            <li><code>osl_Socket_MsgNormal</code>
+            <li><code>osl_Socket_MsgOOB</code>
+            <li><code>osl_Socket_MsgPeek</code>
+            <li><code>osl_Socket_MsgDontRoute</code>
+            <li><code>osl_Socket_MsgMaxIOVLen</code>
             </ul>
             
             @return the number of received bytes.
@@ -686,9 +730,9 @@ namespace osl
                                            SocketAddr* pSenderAddr= 0, 
                                            oslSocketMsgFlag Flag= osl_Socket_MsgNormal);
         
-        /** Tries to send one datagram with BytesToSend data to the given ReceiverAddr.
-            Since we only send one packet, we don't need to concern ourselfes here with
-            incomplete sends due to packet boundaries.
+        /** Tries to send one datagram with BytesToSend size to the given ReceiverAddr.
+            Since there is only send one packet, the function doesn't care about
+            packet boundaries.
             
             @param ReceiverAddr [in] A SocketAddr that contains
             the destination address for this send. 
@@ -698,11 +742,12 @@ namespace osl
             this size.
             @param Flag [in] Modifier for the call. Valid values are:
 
-            - osl_Socket_MsgNormal
-            - osl_Socket_MsgOOB
-            - osl_Socket_MsgPeek     
-            - osl_Socket_MsgDontRoute
-            - osl_Socket_MsgMaxIOVLen
+            <ul>
+            <li><code>osl_Socket_MsgNormal</code>
+            <li><code>osl_Socket_MsgOOB</code>
+            <li><code>osl_Socket_MsgPeek</code>
+            <li><code>osl_Socket_MsgDontRoute</code>
+            <li><code>osl_Socket_MsgMaxIOVLen</code>
             </ul>
             
             @return the number of transfered bytes.
diff --git a/sal/inc/rtl/bootstrap.h b/sal/inc/rtl/bootstrap.h
index 318889c07..3593c1c48 100644
--- a/sal/inc/rtl/bootstrap.h
+++ b/sal/inc/rtl/bootstrap.h
@@ -2,9 +2,9 @@
  *
  *  $RCSfile: bootstrap.h,v $
  *
- *  $Revision: 1.2 $
+ *  $Revision: 1.3 $
  *
- *  last change: $Author: kr $ $Date: 2001-08-30 11:51:36 $
+ *  last change: $Author: jbu $ $Date: 2001-10-24 10:51:08 $
  *
  *  The Contents of this file are made available subject to the terms of
  *  either of the following licenses
@@ -68,80 +68,90 @@ extern "C" {
 #endif
 
 /**
+   @HTML
+   @file
+   
    The described concept provides a platform independent way to access 
    minimum bootstrap settings for every application by excplitly or 
-   implicitly passing the values to the application.
+   implicitly passing the values to the application.<p>
 
-   4-LEVEL STRATEGY FOR RETRIEVAL OF BOOTSTRAP VALUES :
+   4-LEVEL STRATEGY FOR RETRIEVAL OF BOOTSTRAP VALUES :<p>
 
    The 1st level is tried first. On failure, 
    the next level is tried. Every query starts at the first level again, so 
-   that one setting may be taken from the 3rd and one from the 1st level.
+   that one setting may be taken from the 3rd and one from the 1st level.<p>
 
    1st level: command line arguments. A "-env:SETTINGNAME=value" is given on 
    command line. This allows to give an application a certain setting, even 
    if an ini-file exists (espicially useful for e.g. daemons that want to 
-   start an executable with dynamical changing settings).
+   start an executable with dynamical changing settings).<p>
 
    2nd level: ini-files. Every application looks for an ini-file.  
    The filename defaults to /absoulte/path/to/executable[rc|.ini]
    (without .bin or .exe suffix). The ini-filename can be
    set by the special command line parameter
    '-env:INIFILENAME=/absolute/path/to/inifile' at runtime or it may
-   be set at compiletime by an API-call.
+   be set at compiletime by an API-call.<p>
 
    3rd level: environment variables. The application tries to get the 
-   setting from the environment.
+   setting from the environment.<p>
 
    4th level: default. An application can have some default settings decided 
    at compile time, which allow the application to run even with no 
-   deployment settings. 
+   deployment settings. <p>
 
    If neither of the 4 levels leads to an successful retrieval of the value 
-   (no default possible), the application may  fail to start.
+   (no default possible), the application may  fail to start.<p>
 
-   NAMING CONVENTIONS 
+   NAMING CONVENTIONS <p>
 
    Naming conventions for names of bootstrap values :
    Names may only include characters, that are allowed charcters for 
    environment variables. This excludes '.', ' ', ';', ':' and any non-ascii 
-   character. Names are case insensitive.
+   character. Names are case insensitive.<p>
    
    The ini-file is only allowed to have one section, which must be named '[Bootstrap]'.
    The section may be omitted.
    The section name does not appear in the name of the corresponding
    environment variable or commandline arg.
-   Values maybe arbitrary unicode strings, they must be encoded in UTF8.
+   Values maybe arbitrary unicode strings, they must be encoded in UTF8.<p>
 
-   Example:
+   Example:<p>
    
    in an ini-file:
+   <code>
    [Sectionname]
    Name=value
+   </code><p>
 
    as commandline arg:
-   -env:Name=value
+   <code>-env:Name=value</code><p>
 
    as environment
+   <code>
    setenv Name value
    set Name=value
-
+   </code><p>
+   
    SPECIAL VARIABLES:
 
-   - INIFILENAME
+   <ul>
+   <li> INIFILENAME<br>
      This variable allows to set the inifilename. This makes only sense, if the filename
      is different than the executable file name. It must be given on command line. If it is
      given the executable ini-file is ignored.
+   </li>
 */
     
 /** may be called by an application to set an ini-filename.
-    
+
+    <p>
     Must be called before rtl_bootstrap_get(). May not be called twice.
     If it is never called, a the filename executable.ini (win)
     or execuablerc (unx) is assumed.
 
-    @pName Name of the inifile with path but WITHOUT 
-           suffix (.ini or rc) 
+    @param pName Name of the inifile with path but WITHOUT 
+    suffix (.ini or rc) 
 */
 void SAL_CALL rtl_bootstrap_setIniFileName( rtl_uString *pName );
 
@@ -149,19 +159,18 @@ void SAL_CALL rtl_bootstrap_setIniFileName( rtl_uString *pName );
    @param ppValue
         out parameter. Contains always a valid rtl_uString pointer.
    @param pName 
-            The name of the bootstrap setting to be
-        retrieved.
+            The name of the bootstrap setting to be 	retrieved.
    @param pDefault  
         maybe NULL. If once the default is 
            returned, successive calls always return this
            default value, even when called with different
            defaults.
 
-   @return sal_True, when a value could be retrieved successfully
-           sal_False, when none of the 4 methods gave a value. ppValue
+   @return <code>sal_True</code>, when a value could be retrieved successfully,
+           <code>sal_False</code>, when none of the 4 methods gave a value. ppValue
            then contains ane empty string.
            When a pDefault value is given, the function returns always
-           sal_True.
+           <code>sal_True</code>.
 */
 sal_Bool SAL_CALL rtl_bootstrap_get( rtl_uString *pName, rtl_uString **ppValue, rtl_uString *pDefault );
 
@@ -178,14 +187,14 @@ rtlBootstrapHandle SAL_CALL rtl_bootstrap_args_open(rtl_uString * pIniName);
 
 /** 
    Closes a boostrap agument container.
-   @ param handle [in]     The handle got by <code>rtl_bootstrap_args_open</code>
+   @param handle [in]     The handle got by <code>rtl_bootstrap_args_open()</code>
 */
 void SAL_CALL rtl_bootstrap_args_close(rtlBootstrapHandle handle);
 
 /**
-   @param handle   [in]     The handle got by <code>rtl_bootstrap_args_open</code>
+   @param handle   [in]     The handle got by <code>rtl_bootstrap_args_open()</code>
    @param pName    [in]     The name of the variable to be retrieved
-   @param ppValue  [out]    The result of the retrieval
+   @param ppValue  [out]    The result of the retrieval. *ppValue may be null in case of failure.
    @param pDefault [in]     The default value for the retrieval, may be <code>NULL</code>
 
    @return                  The status of the retrieval, <code>sal_True</code> on success.
@@ -193,6 +202,10 @@ void SAL_CALL rtl_bootstrap_args_close(rtlBootstrapHandle handle);
 sal_Bool SAL_CALL rtl_bootstrap_get_from_handle(rtlBootstrapHandle handle, rtl_uString *pName, rtl_uString **ppValue, rtl_uString *pDefault);
 
 
+/** Returns the name of the inifile associated with this handle.
+   
+   @param ppIniName contains after the call the name of the ini-filename.
+*/
 void SAL_CALL rtl_bootstrap_get_iniName_from_handle(rtlBootstrapHandle handle, rtl_uString ** ppIniName);
 
 
diff --git a/sal/inc/rtl/bootstrap.hxx b/sal/inc/rtl/bootstrap.hxx
index 90fbe2064..2e6af7c8d 100644
--- a/sal/inc/rtl/bootstrap.hxx
+++ b/sal/inc/rtl/bootstrap.hxx
@@ -2,9 +2,9 @@
  *
  *  $RCSfile: bootstrap.hxx,v $
  *
- *  $Revision: 1.2 $
+ *  $Revision: 1.3 $
  *
- *  last change: $Author: kr $ $Date: 2001-08-30 11:51:36 $
+ *  last change: $Author: jbu $ $Date: 2001-10-24 10:51:08 $
  *
  *  The Contents of this file are made available subject to the terms of
  *  either of the following licenses
@@ -70,28 +70,29 @@ namespace rtl
         void * _handle;
     public:
         /**
-           @see rtl_bootstrap_setIniFileName
+           @see rtl_bootstrap_setIniFileName()
          */
         static inline void SAL_CALL setIniFilename( const ::rtl::OUString &sFile );
 
-        /**
+        /** Retrieves a bootstrap parameter
            @param sName name of the bootstrap value. case insensitive.
            @param outValue (out parameter). On success contains the value, otherwise
                   an empty string.
            @return sal_False, if no value could be retrieved, otherwise sal_True
-           @see rtl_bootstrap_get
+           @see rtl_bootstrap_get()
          */
         static inline sal_Bool get(
             const ::rtl::OUString &sName,
             ::rtl::OUString &outValue );
 
-        /**
+        /** Retrieves a bootstrap parameter
+           
            @param sName name of the bootstrap value. case insensitive.
            @param outValue (out parameter). Contains the value associated with sName.
            @param aDefault if none of the other methods retrieved a value, outValue
                            is assigned to a Default.
                   
-           @see rtl_bootstrap_get
+           @see rtl_bootstrap_get()
          */
         static inline void get(
             const ::rtl::OUString &sName,
@@ -100,17 +101,40 @@ namespace rtl
 
 
         inline Bootstrap();
+
+        /** Opens a bootstrap argment container
+            @see rtl_bootstrap_args_open()
+         */
         inline Bootstrap(const OUString & iniName);
+
+        /** Closes a bootstrap argument container
+            @see rtl_bootstrap_args_close()
+        */
         inline ~Bootstrap();
 
+        /** Retrieves a bootstrap argument.
+
+            It is first tried to retrieve the value via the global function
+            and second via the special bootstrap container.
+            @see rtl_bootstrap_get_from_handle()
+        */
+        
         inline sal_Bool getFrom(const ::rtl::OUString &sName,
                                 ::rtl::OUString &outValue) const;
 
+        /** Retrieves a bootstrap argument.
 
+            It is first tried to retrieve the value via the global function
+            and second via the special bootstrap container.
+            @see rtl_bootstrap_get_from_handle()
+        */
         inline void getFrom(const ::rtl::OUString &sName,
                             ::rtl::OUString &outValue,
                             const ::rtl::OUString &aDefault) const;
 
+        /** Retrieves the name of the underlying ini-file.
+            @see rtl_bootstrap_get_iniName_from_handle()
+         */
         inline void getIniName(::rtl::OUString & iniName) const;
 
     };
diff --git a/sal/inc/rtl/uuid.h b/sal/inc/rtl/uuid.h
index 70ae5b805..8910177ce 100644
--- a/sal/inc/rtl/uuid.h
+++ b/sal/inc/rtl/uuid.h
@@ -2,9 +2,9 @@
  *
  *  $RCSfile: uuid.h,v $
  *
- *  $Revision: 1.5 $
+ *  $Revision: 1.6 $
  *
- *  last change: $Author: jsc $ $Date: 2001-04-26 13:34:01 $
+ *  last change: $Author: jbu $ $Date: 2001-10-24 10:51:08 $
  *
  *  The Contents of this file are made available subject to the terms of
  *  either of the following licenses
@@ -66,18 +66,21 @@
 #include <rtl/string.h>
 
 /**
-    (from <draft-leach-uuids-guids-01.txt> )
-    Specification
-
-    A UUID is an identifier that is unique across both space and time,
-    with respect to the space of all UUIDs. To be precise, the UUID
-    consists of a finite bit space. Thus the time value used for
-    constructing a UUID is limited and will roll over in the future
-    (approximately at A.D. 3400, based on the specified algorithm). A
-    UUID can be used for multiple purposes, from tagging objects with an
-    extremely short lifetime, to reliably identifying very persistent
-    objects across a network.
+   @HTML
+   @file
+   Specification (from draft-leach-uuids-guids-01.txt )
 
+   <p>
+   A UUID is an identifier that is unique across both space and time,
+   with respect to the space of all UUIDs. To be precise, the UUID
+   consists of a finite bit space. Thus the time value used for
+   constructing a UUID is limited and will roll over in the future
+   (approximately at A.D. 3400, based on the specified algorithm). A
+   UUID can be used for multiple purposes, from tagging objects with an
+   extremely short lifetime, to reliably identifying very persistent
+   objects across a network.
+
+   <p>
     The generation of UUIDs does not require that a registration
     authority be contacted for each identifier. Instead, it requires a
     unique value over space for each UUID generator. This spatially
@@ -91,12 +94,10 @@
 extern "C" {
 #endif	
 
-/**
-    Generates a new UUID (Universally Unique IDentifier).
+/** Generates a new UUID (Universally Unique IDentifier).
     If available, the ethernetaddress of a networkcard is used, otherwise
     a 6 Byte random number is generated( for which rtlRandomPool is used ).
 
-
     @param pTargetUUID          pointer to at least 16 bytes of memory. After the call it contains
                                 the newly generated uuid in network byte order.
     @param pPredecessorUUID     pointer to the previously generated uuid in network byte
@@ -106,48 +107,60 @@ extern "C" {
                                 Set pPredecessorUUID to 0 if no predecessor is available.
                                 The caller is responsible for making the value persistent
                                 (if desired).
-    @param bUseEthernetAddress  if sal_True, the generator uses the ethernet address of a
-                                network card (if available). <br>
-                                if sal_False, the generator generates a new 6-Byte random
+    @param bUseEthernetAddress  if <code>sal_True</code>, the generator uses the ethernet
+                                address of a network card (if available). 
+                                if <code>sal_False</code>, the generator generates a new
+                                6-Byte random
                                 value each time it is called with pPredecessorUUID = 0.
  */
 void SAL_CALL rtl_createUuid( sal_uInt8 *pTargetUUID ,
                               const sal_uInt8 *pPredecessorUUID,
                               sal_Bool bUseEthernetAddress );
 
-/**
-    uid_compare --  Compare two UUID's "lexically" and return
-          -1   u1 is lexically before u2
-           0   u1 is equal to u2
-           1   u1 is lexically after u2
+/** Compare two UUID's lexically
 
+    <p>
     Note:   lexical ordering is not temporal ordering!
+    <p>
     Note:   For equalnesschecking, a memcmp(pUUID1,pUUID2,16) is more efficient
+
+    @return
+    <ul>
+    <li>-1   u1 is lexically before u2
+    <li>0   u1 is equal to u2
+    <li>1   u1 is lexically after u2
+    </ul>
+
  */
 sal_Int32 SAL_CALL rtl_compareUuid( const sal_uInt8 *pUUID1 , const sal_uInt8 *pUUID2 );
 
-/**
-    The version 3 UUID is meant for generating UUIDs from "names" that
-    are drawn from, and unique within, some "name space". Some examples
+/** Creates named UUIDs.
+
+    <p>
+    The version 3 UUID is meant for generating UUIDs from <em>names</em> that
+    are drawn from, and unique within, some <em>name space</em>. Some examples
     of names (and, implicitly, name spaces) might be DNS names, URLs, ISO
     Object IDs (OIDs), reserved words in a programming language, or X.500
     Distinguished Names (DNs); thus, the concept of name and name space
     should be broadly construed, and not limited to textual names. 
 
+    <p>
     The requirements for such UUIDs are as follows:
 
-    - The UUIDs generated at different times from the same name in the
-      same namespace MUST be equal
+    <ul>
+    <li> The UUIDs generated at different times from the same name in the
+         same namespace MUST be equal
 
-    - The UUIDs generated from two different names in the same namespace
-      should be different (with very high probability)
+    <li> The UUIDs generated from two different names in the same namespace
+         should be different (with very high probability)
 
-    - The UUIDs generated from the same name in two different namespaces
-      should be different with (very high probability)
+    <li> The UUIDs generated from the same name in two different namespaces
+         should be different with (very high probability)
 
-    - If two UUIDs that were generated from names are equal, then they
-      were generated from the same name in the same namespace (with very
-      high probability).
+    <li> If two UUIDs that were generated from names are equal, then they
+         were generated from the same name in the same namespace (with very
+         high probability).
+    </ul>
 
     @param pTargetUUID pointer to at least 16 bytes of memory. After the call
                        it contains the newly generated uuid in network byte order.
@@ -164,11 +177,16 @@ void SAL_CALL rtl_createNamedUuid(
 
 
 
-/**
+/*
     Predefined Namespaces
     (Use them the following way : sal_uInt8 aNsDNS[16])  = RTL_UUID_NAMESPACE_DNS;
  */
-/* 6ba7b810-9dad-11d1-80b4-00c04fd430c8 */
+/** namesapce DNS
+
+    <p>
+    (Use them the following way : sal_uInt8 aNsDNS[16])  = RTL_UUID_NAMESPACE_DNS;
+    <p>
+   6ba7b810-9dad-11d1-80b4-00c04fd430c8 */
 #define RTL_UUID_NAMESPACE_DNS {\
       0x6b,0xa7,0xb8,0x10,\
       0x9d,0xad,\
@@ -176,7 +194,10 @@ void SAL_CALL rtl_createNamedUuid(
       0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8\
     }
 
-/* 6ba7b811-9dad-11d1-80b4-00c04fd430c8 */
+/** namespace URL
+
+   <p>
+   6ba7b811-9dad-11d1-80b4-00c04fd430c8 */
 #define RTL_UUID_NAMESPACE_URL { \
       0x6b, 0xa7, 0xb8, 0x11,\
       0x9d, 0xad,\
@@ -184,7 +205,10 @@ void SAL_CALL rtl_createNamedUuid(
       0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8\
     }
 
-/* 6ba7b812-9dad-11d1-80b4-00c04fd430c8 */
+/** namespace oid
+
+    <p>
+    6ba7b812-9dad-11d1-80b4-00c04fd430c8 */
 #define RTL_UUID_NAMESPACE_OID {\
       0x6b, 0xa7, 0xb8, 0x12,\
       0x9d, 0xad,\
@@ -192,7 +216,10 @@ void SAL_CALL rtl_createNamedUuid(
       0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8\
     }
 
-/* 6ba7b814-9dad-11d1-80b4-00c04fd430c8 */
+/** namespace X500
+
+    <p>
+    6ba7b814-9dad-11d1-80b4-00c04fd430c8 */
 #define RTL_UUID_NAMESPACE_X500 {\
       0x6b, 0xa7, 0xb8, 0x14,\
       0x9d, 0xad,\
@@ -201,7 +228,7 @@ void SAL_CALL rtl_createNamedUuid(
     }
     
 
-/**
+/*
     This macro must have a value below the system time resolution of the
     system. The uuid routines use this value  as an upper limit for adding ticks to the
     the predecessor time value if system times are equal.