cleanup doxygen warnings

Change-Id: I9181cad5bfa93f9e8b3d944b2b50a3ccc0b42595

19 files changed, 153 insertions, 101 deletions

diff --git a/sal/inc/osl/file.hxx b/sal/inc/osl/file.hxx
index e2e304f3e527..ee52cd570840 100644
--- a/sal/inc/osl/file.hxx
+++ b/sal/inc/osl/file.hxx
@@ -282,7 +282,6 @@ public:
         If pustrTempFileURL is not 0 the caller receives the name of the
         created file and is responsible for removing the file.
 
-        @descr
         Description of the different pHandle, ppustrTempFileURL parameter combinations.
         pHandle is 0 and pustrTempDirURL is 0 - this combination is invalid<br>
         pHandle is not 0 and pustrTempDirURL is 0 - a handle to the open file
@@ -1256,7 +1255,6 @@ public:
     <dd>On success</dd>
     <dt>E_INVAL</dt>
     <dd>The value of the input parameter is invalid</dd>
-    </dl>
     <br><p><strong>In addition to these error codes others may occur as well, for instance:</strong></p><br>
     <dt>E_BADF</dt>
     <dd>The file is not open for writing</dd>
diff --git a/sal/inc/osl/mutex.hxx b/sal/inc/osl/mutex.hxx
index 9ed68612dc38..18ff44444223 100644
--- a/sal/inc/osl/mutex.hxx
+++ b/sal/inc/osl/mutex.hxx
@@ -34,7 +34,7 @@ namespace osl
     public:
         /** Create a thread-local mutex.
             @return 0 if the mutex could not be created, otherwise a handle to the mutex.
-            @seealso ::osl_createMutex()
+            @see ::osl_createMutex()
         */
         Mutex()
         {
@@ -42,7 +42,7 @@ namespace osl
         }
 
         /** Release the OS-structures and free mutex data-structure.
-            @seealso ::osl_destroyMutex()
+            @see ::osl_destroyMutex()
         */
         ~Mutex()
         {
@@ -51,7 +51,7 @@ namespace osl
 
         /** Acquire the mutex, block if already acquired by another thread.
             @return sal_False if system-call fails.
-            @seealso ::osl_acquireMutex()
+            @see ::osl_acquireMutex()
         */
         sal_Bool acquire()
         {
@@ -60,7 +60,7 @@ namespace osl
 
         /** Try to acquire the mutex without blocking.
             @return sal_False if it could not be acquired.
-            @seealso ::osl_tryToAcquireMutex()
+            @see ::osl_tryToAcquireMutex()
         */
         sal_Bool tryToAcquire()
         {
@@ -69,7 +69,7 @@ namespace osl
 
         /** Release the mutex.
             @return sal_False if system-call fails.
-            @seealso ::osl_releaseMutex()
+            @see ::osl_releaseMutex()
         */
         sal_Bool release()
         {
@@ -80,7 +80,7 @@ namespace osl
             The global and static mutex object can be used to initialize other
             static objects in a thread safe manner.
             @return the global mutex object
-            @seealso ::osl_getGlobalMutex()
+            @see ::osl_getGlobalMutex()
         */
         static Mutex * getGlobalMutex()
         {
diff --git a/sal/inc/osl/security_decl.hxx b/sal/inc/osl/security_decl.hxx
index 0ac9276b9c0d..5b8b17066d91 100644
--- a/sal/inc/osl/security_decl.hxx
+++ b/sal/inc/osl/security_decl.hxx
@@ -51,12 +51,16 @@ public:
     inline sal_Bool SAL_CALL logonUser(const rtl::OUString& strName,
                                        const rtl::OUString& strPasswd);
     /** get the security information for one user.
+
+        @verbatim
         This method will try to login the user at the denoted file server.
         If a network resource named \\server\username exists and this resource
         could be connected by this user, the methos will return true and getHomeDir
         will return \\server\username.
+        @endverbatim
         @param[in] strName denotes the name of the user
         @param[in] strPasswd denotes the password of this user
+        @param[in] strFileServer denotes the file server to login to
         @return True, if the specified user is known by file server and the
         could be connected, otherwise False
     */
diff --git a/sal/inc/osl/socket.h b/sal/inc/osl/socket.h
index 385c4c3c9c09..ce47c8673beb 100644
--- a/sal/inc/osl/socket.h
+++ b/sal/inc/osl/socket.h
@@ -283,6 +283,7 @@ SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_getInetPortOfSocketAddr(
 
 
 /** Sets the Port of Addr.
+    @param[in] Addr the SocketAddr to perfom the operation on.
     @param[in] Port is expected in host byte-order.
     @return <code>sal_False</code> if Addr is not an inet-addr.
 */
@@ -291,7 +292,8 @@ SAL_DLLPUBLIC sal_Bool SAL_CALL osl_setInetPortOfSocketAddr(
 
 
 /** Returns the hostname represented by Addr.
-    @param strHostname out-parameter. The hostname represented by the address. If
+    @param[in] Addr The socket address from which to extract the hostname.
+    @param[out] strHostname The hostname represented by the address. If
     there is no hostname to be found, it returns 0.
 */
 SAL_DLLPUBLIC oslSocketResult SAL_CALL osl_getHostnameOfSocketAddr(
@@ -299,7 +301,8 @@ SAL_DLLPUBLIC oslSocketResult SAL_CALL osl_getHostnameOfSocketAddr(
 
 
 /** Gets the address in dotted decimal format.
-    @param strDottedInetAddr out-parameter. Contains the dotted decimal address
+    @param[in] Addr The socket address from which to extract the dotted decimal address.
+    @param[out] strDottedInetAddr 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.
@@ -314,7 +317,8 @@ SAL_DLLPUBLIC oslSocketResult SAL_CALL osl_setAddrOfSocketAddr(
         oslSocketAddr Addr, sal_Sequence *pByteSeq );
 
 /** Returns the addr field in the struct sockaddr.
-    @param ppByteSeq out parameter. After the call, *ppByteSeq contains the ipadrress
+    @param[in] Addr The socket address from which to extract the ipaddress.
+    @param[out] ppByteSeq After the call, *ppByteSeq contains the ipaddress
                      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>
  */
@@ -466,6 +470,7 @@ SAL_DLLPUBLIC oslSocketResult SAL_CALL osl_connectSocketTo(
 
 /** Prepares the socket to act as an acceptor of incoming connections.
     You should call "listen" before you use "accept".
+    @param[in] Socket The socket to listen on.
     @param[in] MaxPendingConnections 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).
@@ -478,6 +483,7 @@ SAL_DLLPUBLIC sal_Bool SAL_CALL osl_listenOnSocket(
 
 /** Waits for an ingoing connection on the socket.
     This call blocks if there is no incoming connection present.
+    @param[in] Socket The socket to accept the connection on.
     @param[in] pAddr if pAddr is != 0, the peers address is returned.
     @return 0 if the accept-call failed, otherwise you get a socket
     representing the new connection.
@@ -637,7 +643,8 @@ SAL_DLLPUBLIC sal_Bool SAL_CALL osl_isExceptionPending(
         oslSocket Socket, const TimeValue* pTimeout);
 
 /** Shuts down communication on a connected socket.
-    @param Direction denotes which end of the socket
+    @param[in] Socket the Socket to perfom the operation on.
+    @param[in] Direction denotes which end of the socket
     should be closed:
     <ul>
     <li> <code>osl_Socket_DirRead</code>    closes read operations.
@@ -784,6 +791,7 @@ SAL_DLLPUBLIC sal_Bool SAL_CALL osl_isNonBlockingMode(
 
 
 /** Queries the socket for its type.
+    @param[in] Socket The socket to query.
     @return one of:
     <ul>
     <li> osl_Socket_TypeStream
@@ -793,13 +801,13 @@ SAL_DLLPUBLIC sal_Bool SAL_CALL osl_isNonBlockingMode(
     <li> osl_Socket_TypeSeqPacket
     <li> osl_invalid_SocketType, if an error occurred
     </ul>
-
 */
 SAL_DLLPUBLIC oslSocketType SAL_CALL osl_getSocketType(
         oslSocket Socket);
 
 /** returns  a string which describes the last socket error.
-    @param strError out-parameter. The string that receives the error message.
+    @param[in] Socket The socket to query.
+    @param[out] strError The string that receives the error message.
 */
 SAL_DLLPUBLIC void SAL_CALL osl_getLastSocketErrorDescription(
         oslSocket Socket, rtl_uString **strError);
@@ -871,14 +879,16 @@ SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_demultiplexSocketEvents(oslSocketSet Incomi
                                     const TimeValue* pTimeout);
 
 /** Closes the socket terminating any ongoing dataflow.
+    @param[in] Socket The socket to close.
  */
 SAL_DLLPUBLIC void SAL_CALL osl_closeSocket(oslSocket Socket);
 
 
 /** Retrieves n bytes from the stream and copies them into pBuffer.
     The function avoids incomplete reads due to packet boundaries.
-    @param pBuffer receives the read data.
-    @param nSize the number of bytes to read. pBuffer must be large enough
+    @param[in] Socket The socket to read from.
+    @param[out] pBuffer receives the read data.
+    @param[out] nSize the number of bytes to read. pBuffer must be large enough
     to hold the n bytes!
     @return the number of read bytes. The number will only be smaller than
     n if an exceptional condition (e.g. connection closed) occurs.
@@ -888,8 +898,9 @@ SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_readSocket( oslSocket Socket, void *pBuffer
 
 /** Writes n bytes from pBuffer to the stream. The method avoids
     incomplete writes due to packet boundaries.
-    @param pBuffer contains the data to be written.
-    @param nSize the number of bytes to write.
+    @param[out] Socket The socket to write to.
+    @param[in] pBuffer contains the data to be written.
+    @param[in] nSize the number of bytes to write.
     @return the number of written bytes. The number will only be smaller than
     nSize if an exceptional condition (e.g. connection closed) occurs.
 */
diff --git a/sal/inc/osl/socket_decl.hxx b/sal/inc/osl/socket_decl.hxx
index 2b45b979cdaa..822450db8f1c 100644
--- a/sal/inc/osl/socket_decl.hxx
+++ b/sal/inc/osl/socket_decl.hxx
@@ -48,7 +48,6 @@ 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 );
@@ -116,6 +115,7 @@ namespace osl
         inline SocketAddr & SAL_CALL operator= (const SocketAddr& Addr);
 
         /** Assigns the socket addr without copyconstructing it.
+            @param Addr the socket address.
             @param nocopy use SAL_NO_COPY
           */
         inline SocketAddr & SAL_CALL assign( oslSocketAddr Addr, __osl_socket_NoCopy nocopy );
@@ -180,6 +180,7 @@ namespace osl
 
         /** The instance takes over the handle's ownership without acquiring the
             handle, but releases it within the dtor.
+            @param socketHandle the handle
             @param noacquire use SAL_NO_ACQUIRE
          */
         inline Socket( oslSocket socketHandle, __sal_NoAcquire noacquire );
@@ -498,6 +499,8 @@ namespace osl
     {
     public:
         /** Creates a socket.
+            @param Family the Family of the socket (Inet by default)
+            @param Protocol the Protocon of the socket (IP by default)
             @param Type For some protocols it might be desirable to
             use a different type than <code>osl_Socket_TypeStream</code>
             (like <code>osl_Socket_TypeSeqPacket</code>).
@@ -579,6 +582,8 @@ namespace osl
     {
     public:
         /** Creates a socket that can connect to a (remote) host.
+            @param Family the Family of the socket (Inet by default)
+            @param Protocol the Protocon of the socket (IP by default)
             @param Type For some protocols it might be desirable to
             use a different type than sock_stream <code>osl_Socket_TypeSeqPacket</code>
             (like <code>osl_Socket_TypeSeqPacket</code>).
@@ -649,6 +654,8 @@ namespace osl
     public:
 
         /** Creates a datagram socket.
+            @param Family the Family of the socket (Inet by default)
+            @param Protocol the Protocon of the socket (IP by default)
             @param Type is sock_dgram by default.
         */
         inline DatagramSocket(oslAddrFamily Family= osl_Socket_FamilyInet,
diff --git a/sal/inc/rtl/alloc.h b/sal/inc/rtl/alloc.h
index de708ea3cecb..ef48d01719ee 100644
--- a/sal/inc/rtl/alloc.h
+++ b/sal/inc/rtl/alloc.h
@@ -31,7 +31,8 @@ extern "C" {
 
 
 /** Allocate memory.
-    @descr A call to this function will return NULL upon the requested
+
+    A call to this function will return NULL upon the requested
     memory size being either zero or larger than currently allocatable.
 
     @param  Bytes [in] memory size.
@@ -43,9 +44,9 @@ SAL_DLLPUBLIC void * SAL_CALL rtl_allocateMemory (
 
 
 /** Reallocate memory.
-    @descr A call to this function with parameter 'Ptr' being NULL
-    is equivalent to a rtl_allocateMemory() call.
 
+    A call to this function with parameter 'Ptr' being NULL
+    is equivalent to a rtl_allocateMemory() call.
     A call to this function with parameter 'Bytes' being 0
     is equivalent to a rtl_freeMemory() call.
 
@@ -72,7 +73,8 @@ SAL_DLLPUBLIC void SAL_CALL rtl_freeMemory (
 
 
 /** Allocate and zero memory.
-    @descr A call to this function will return NULL upon the requested
+
+    A call to this function will return NULL upon the requested
     memory size being either zero or larger than currently allocatable.
 
     @param  Bytes [in] memory size.
@@ -187,6 +189,7 @@ typedef struct rtl_cache_st rtl_cache_type;
  *  @param  destructor  [in] object destructor callback function.
  *  @param  reclaim     [in] reclaim callback function.
  *  @param  pUserArg    [in] opaque argument passed to callback functions.
+ *  @param  pSource     [in] opaque argument passed to callback functions.
  *  @param  nFlags      [in] flags.
  *
  *  @return pointer to rtl_cache_type, or NULL upon failure.
diff --git a/sal/inc/rtl/bootstrap.h b/sal/inc/rtl/bootstrap.h
index 76795ba8e566..67fed2d92660 100644
--- a/sal/inc/rtl/bootstrap.h
+++ b/sal/inc/rtl/bootstrap.h
@@ -106,6 +106,7 @@ extern "C" {
      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>
+   </ul>
 */
 
 /** may be called by an application to set an ini-filename.
@@ -115,7 +116,7 @@ extern "C" {
     If it is never called, the filename is based on the name of the executable,
     with the suffix ".ini" on Windows or "rc" on Unix.
 
-    @param pNameUri URL of the inifile with path but WITHOUT suffix (.ini or rc)
+    @param pFileUri URL of the inifile with path but WITHOUT suffix (.ini or rc)
 */
 SAL_DLLPUBLIC void SAL_CALL rtl_bootstrap_setIniFileName( rtl_uString *pFileUri )
     SAL_THROW_EXTERN_C();
@@ -186,7 +187,8 @@ SAL_DLLPUBLIC sal_Bool SAL_CALL rtl_bootstrap_get_from_handle(
 
 /** Returns the name of the inifile associated with this handle.
 
-   @param ppIniName contains after the call the name of the ini-filename.
+   @param handle   [in]     The handle got by <code>rtl_bootstrap_args_open()</code>
+   @param ppIniName [out] contains after the call the name of the ini-filename.
 */
 SAL_DLLPUBLIC void SAL_CALL rtl_bootstrap_get_iniName_from_handle(
         rtlBootstrapHandle handle, rtl_uString ** ppIniName)
diff --git a/sal/inc/rtl/cipher.h b/sal/inc/rtl/cipher.h
index be90d12319f3..a116e57ba071 100644
--- a/sal/inc/rtl/cipher.h
+++ b/sal/inc/rtl/cipher.h
@@ -143,7 +143,7 @@ SAL_DLLPUBLIC rtlCipherError SAL_CALL rtl_cipher_init (
 
 
 /** Encode a buffer under a given cipher algorithm.
-    @precond Initialized for a compatible cipher direction.
+    @pre Initialized for a compatible cipher direction.
     @see     rtl_cipher_init()
 
     @param  Cipher  [in]  cipher handle.
@@ -161,7 +161,7 @@ SAL_DLLPUBLIC rtlCipherError SAL_CALL rtl_cipher_encode (
 
 
 /** Decode a buffer under a given cipher algorithm.
-    @precond Initialized for a compatible cipher direction.
+    @pre Initialized for a compatible cipher direction.
     @see     rtl_cipher_init()
 
     @param  Cipher  [in]  cipher handle.
@@ -193,7 +193,8 @@ SAL_DLLPUBLIC void SAL_CALL rtl_cipher_destroy (
  *
  *======================================================================*/
 /** Create a Blowfish cipher handle for the given mode.
-    @descr The Blowfish block cipher algorithm is specified in
+
+    The Blowfish block cipher algorithm is specified in
     Bruce Schneier: Applied Cryptography, 2nd edition, ch. 14.3
 
     @see rtl_cipher_create()
@@ -248,7 +249,8 @@ SAL_DLLPUBLIC void SAL_CALL rtl_cipher_destroyBF (
  *
  *======================================================================*/
 /** Create a RC4 cipher handle for the given mode.
-    @descr The RC4 symmetric stream cipher algorithm is specified in
+
+    The RC4 symmetric stream cipher algorithm is specified in
     Bruce Schneier: Applied Cryptography, 2nd edition, ch. 17.1
 
     @see rtl_cipher_create()
diff --git a/sal/inc/rtl/crc.h b/sal/inc/rtl/crc.h
index aafd9cbba096..7fad87ef4f37 100644
--- a/sal/inc/rtl/crc.h
+++ b/sal/inc/rtl/crc.h
@@ -35,7 +35,8 @@ extern "C" {
  *
  *======================================================================*/
 /** Evaluate CRC32 over given data.
-    @descr This function evaluates the CRC polynomial 0xEDB88320.
+
+    This function evaluates the CRC polynomial 0xEDB88320.
 
     @param  Crc    [in] CRC32 over previous data or zero.
     @param  Data   [in] data buffer.
diff --git a/sal/inc/rtl/digest.h b/sal/inc/rtl/digest.h
index 7c01335db306..cc49838821f7 100644
--- a/sal/inc/rtl/digest.h
+++ b/sal/inc/rtl/digest.h
@@ -91,7 +91,7 @@ SAL_DLLPUBLIC rtlDigest SAL_CALL rtl_digest_create  (
 
 
 /** Destroy a digest handle.
-    @postcond Digest handle destroyed and invalid.
+    @post Digest handle destroyed and invalid.
     @param    Digest [in] digest handle to be destroyed.
     @return   None.
  */
@@ -145,8 +145,8 @@ SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_update (
 
 
 /** Finalize a digest and retrieve the digest value.
-    @precond  Digest value length must not be less than digest length.
-    @postcond Digest initialized to accept another update sequence.
+    @pre  Digest value length must not be less than digest length.
+    @post Digest initialized to accept another update sequence.
     @see      rtl_digest_queryLength()
     @see      rtl_digest_update()
 
@@ -169,8 +169,8 @@ SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_get (
 #define RTL_DIGEST_LENGTH_MD2 16
 
 /** Create a MD2 digest handle.
-    @descr The MD2 digest algorithm is specified in
 
+    The MD2 digest algorithm is specified in
     RFC 1319 (Informational)
       The MD2 Message-Digest Algorithm
 
@@ -206,7 +206,8 @@ SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_getMD2 (
 
 
 /** Evaluate a MD2 digest value from given data.
-    @descr This function performs an optimized call sequence on a
+
+    This function performs an optimized call sequence on a
     single data buffer, avoiding digest creation and destruction.
 
     @see rtl_digest_updateMD2()
@@ -232,8 +233,8 @@ SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_MD2 (
 #define RTL_DIGEST_LENGTH_MD5 16
 
 /** Create a MD5 digest handle.
-    @descr The MD5 digest algorithm is specified in
 
+    The MD5 digest algorithm is specified in
     RFC 1321 (Informational)
       The MD5 Message-Digest Algorithm
 
@@ -269,10 +270,11 @@ SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_getMD5 (
 
 
 /** Retrieve the raw (not finalized) MD5 digest value.
-    @descr This function is a non-standard replacement for
+
+    This function is a non-standard replacement for
     rtl_digest_getMD5() and must be used with caution.
 
-    @postcond Digest initialized to accept another update sequence.
+    @post Digest initialized to accept another update sequence.
     @see      rtl_digest_get()
  */
 SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_rawMD5 (
@@ -282,7 +284,8 @@ SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_rawMD5 (
 
 
 /** Evaluate a MD5 digest value from given data.
-    @descr This function performs an optimized call sequence on a
+
+    This function performs an optimized call sequence on a
     single data buffer, avoiding digest creation and destruction.
 
     @see rtl_digest_updateMD5()
@@ -308,8 +311,8 @@ SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_MD5 (
 #define RTL_DIGEST_LENGTH_SHA 20
 
 /** Create a SHA digest handle.
-    @descr The SHA digest algorithm is specified in
 
+    The SHA digest algorithm is specified in
     FIPS PUB 180 (Superseded by FIPS PUB 180-1)
       Secure Hash Standard
 
@@ -345,7 +348,8 @@ SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_getSHA (
 
 
 /** Evaluate a SHA digest value from given data.
-    @descr This function performs an optimized call sequence on a
+
+    This function performs an optimized call sequence on a
     single data buffer, avoiding digest creation and destruction.
 
     @see rtl_digest_updateSHA()
@@ -371,8 +375,8 @@ SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_SHA (
 #define RTL_DIGEST_LENGTH_SHA1 20
 
 /** Create a SHA1 digest handle.
-    @descr The SHA1 digest algorithm is specified in
 
+    The SHA1 digest algorithm is specified in
     FIPS PUB 180-1 (Supersedes FIPS PUB 180)
       Secure Hash Standard
 
@@ -408,7 +412,8 @@ SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_getSHA1 (
 
 
 /** Evaluate a SHA1 digest value from given data.
-    @descr This function performs an optimized call sequence on a
+
+    This function performs an optimized call sequence on a
     single data buffer, avoiding digest creation and destruction.
 
     @see rtl_digest_updateSHA1()
@@ -434,7 +439,8 @@ SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_SHA1 (
 #define RTL_DIGEST_LENGTH_HMAC_MD5 RTL_DIGEST_LENGTH_MD5
 
 /** Create a HMAC_MD5 digest handle.
-    @descr The HMAC_MD5 digest algorithm is specified in
+
+    The HMAC_MD5 digest algorithm is specified in
 
     RFC 2104 (Informational)
       HMAC: Keyed-Hashing for Message Authentication
@@ -486,7 +492,8 @@ SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_getHMAC_MD5 (
 
 
 /** Evaluate a HMAC_MD5 digest value from given data.
-    @descr This function performs an optimized call sequence on a
+
+    This function performs an optimized call sequence on a
     single data buffer, avoiding digest creation and destruction.
 
     @see rtl_digest_initHMAC_MD5()
@@ -516,8 +523,8 @@ SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_HMAC_MD5 (
 #define RTL_DIGEST_LENGTH_HMAC_SHA1 RTL_DIGEST_LENGTH_SHA1
 
 /** Create a HMAC_SHA1 digest handle.
-    @descr The HMAC_SHA1 digest algorithm is specified in
 
+    The HMAC_SHA1 digest algorithm is specified in
     RFC 2104 (Informational)
       HMAC: Keyed-Hashing for Message Authentication
     RFC 2898 (Informational)
@@ -570,7 +577,8 @@ SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_getHMAC_SHA1 (
 
 
 /** Evaluate a HMAC_SHA1 digest value from given data.
-    @descr This function performs an optimized call sequence on a
+
+    This function performs an optimized call sequence on a
     single data buffer, avoiding digest creation and destruction.
 
     @see rtl_digest_initHMAC_SHA1()
@@ -598,8 +606,8 @@ SAL_DLLPUBLIC rtlDigestError SAL_CALL rtl_digest_HMAC_SHA1 (
  *
  *======================================================================*/
 /** Password-Based Key Derivation Function.
-    @descr The PBKDF2 key derivation function is specified in
 
+    The PBKDF2 key derivation function is specified in
     RFC 2898 (Informational)
       PKCS #5: Password-Based Cryptography Specification Version 2.0
 
diff --git a/sal/inc/rtl/logfile.hxx b/sal/inc/rtl/logfile.hxx
index 50083ca68626..5ee0739163e2 100644
--- a/sal/inc/rtl/logfile.hxx
+++ b/sal/inc/rtl/logfile.hxx
@@ -25,7 +25,7 @@
 namespace rtl
 {
 /**
-@descr  The intended use for class Logfile is to write time stamp information
+@brief  The intended use for class Logfile is to write time stamp information
         for profiling purposes.
 
         Profiling output should only be generated for a special product version of OpenOffice
@@ -93,7 +93,9 @@ namespace rtl
     {
     public:
         inline Logfile( const sal_Char *name );
-        /** @descr  Create a log file context where the message field consists of a project
+        /** Create a log file context
+
+                Create a log file context where the message field consists of a project
                 name, the author's shortcut, and the actual message.  These three strings
                 are written in a format that is understood by script that later parses the
                 log file and that so can extract the three strings.
diff --git a/sal/inc/rtl/strbuf.h b/sal/inc/rtl/strbuf.h
index f966548e494f..05dd2de8c61c 100644
--- a/sal/inc/rtl/strbuf.h
+++ b/sal/inc/rtl/strbuf.h
@@ -79,12 +79,13 @@ SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_stringbuffer_newFromStringBuffer(
     If the <code>minimumCapacity</code> argument is nonpositive, this
     method takes no action and simply returns.
 
-    @param   capacity         in: old capicity, out: new capacity.
-    @param   minimumCapacity   the minimum desired capacity.
+    @param[in,out]   This              the String to operate on.
+    @param[in,out]   capacity          in: old capacity, out: new capacity.
+    @param[in]       minimumCapacity   the minimum desired capacity.
  */
 SAL_DLLPUBLIC void SAL_CALL rtl_stringbuffer_ensureCapacity(
-                                                /*inout*/rtl_String ** This,
-                                                /*inout*/sal_Int32* capacity,
+                                                rtl_String ** This,
+                                                sal_Int32* capacity,
                                                 sal_Int32 minimumCapacity);
 
 
@@ -97,14 +98,15 @@ SAL_DLLPUBLIC void SAL_CALL rtl_stringbuffer_ensureCapacity(
     <code>offset</code>. The length of this string buffer increases by
     the length of the argument.
 
-    @param  capacity    the capacity of the string buffer
-    @param  offset      the offset.
-    @param  str         a character array.
-    @param  len         the number of characters to append.
+    @param[in,out]  This        the String to operate on.
+    @param[in,out]  capacity    the capacity of the string buffer
+    @param[in]      offset      the offset.
+    @param[in]      str         a character array.
+    @param[in]      len         the number of characters to append.
  */
 SAL_DLLPUBLIC void SAL_CALL rtl_stringbuffer_insert(
-                                       /*inout*/rtl_String ** This,
-                                       /*inout*/sal_Int32 * capacity,
+                                       rtl_String ** This,
+                                       sal_Int32 * capacity,
                                        sal_Int32 offset,
                                        const sal_Char * str,
                                        sal_Int32 len);
@@ -117,11 +119,12 @@ SAL_DLLPUBLIC void SAL_CALL rtl_stringbuffer_insert(
 
     start must be >= 0 && <= This->length
 
-    @param  start       The beginning index, inclusive
-    @param  len         The substring length
+    @param[in,out]  This        The String to operate on.
+    @param[in]      start       The beginning index, inclusive
+    @param[in]      len         The substring length
  */
 SAL_DLLPUBLIC void SAL_CALL rtl_stringbuffer_remove(
-                                       /*inout*/rtl_String ** This,
+                                       rtl_String ** This,
                                        sal_Int32 start,
                                        sal_Int32 len );
 
diff --git a/sal/inc/rtl/strbuf.hxx b/sal/inc/rtl/strbuf.hxx
index fe19227c41ba..b5d746eaa2d7 100644
--- a/sal/inc/rtl/strbuf.hxx
+++ b/sal/inc/rtl/strbuf.hxx
@@ -567,6 +567,7 @@ public:
         string are then appended to this string buffer.
 
         @param   i   an <code>sal_Int32</code>.
+        @param radix the radix
         @return  this string buffer.
      */
     OStringBuffer & append(sal_Int32 i, sal_Int16 radix = 10 )
@@ -584,6 +585,7 @@ public:
         string are then appended to this string buffer.
 
         @param   l   a <code>long</code>.
+        @param radix the radix
         @return  this string buffer.
      */
     OStringBuffer & append(sal_Int64 l, sal_Int16 radix = 10 )
@@ -780,6 +782,7 @@ public:
 
         @param      offset   the offset.
         @param      i        an <code>sal_Int32</code>.
+        @param      radix the radix
         @return     this string buffer.
      */
     OStringBuffer & insert(sal_Int32 offset, sal_Int32 i, sal_Int16 radix = 10 )
@@ -803,6 +806,7 @@ public:
 
         @param      offset   the offset.
         @param      l        a <code>long</code>.
+        @param      radix the radix
         @return     this string buffer.
      */
     OStringBuffer & insert(sal_Int32 offset, sal_Int64 l, sal_Int16 radix = 10 )
diff --git a/sal/inc/rtl/string.h b/sal/inc/rtl/string.h
index 6fc834918045..a16d61e0bb99 100644
--- a/sal/inc/rtl/string.h
+++ b/sal/inc/rtl/string.h
@@ -855,11 +855,8 @@ SAL_DLLPUBLIC void SAL_CALL rtl_string_new( rtl_String ** newStr ) SAL_THROW_EXT
     alternatively pass ownership to an OUString with
     rtl::OUString(newStr, SAL_NO_ACQUIRE);
 
-    @param newStr
-    pointer to the new string.
-
-    @param len
-    the number of characters.
+    @param[out] nLen the number of characters.
+    @return pointer to the new string.
 
     @since LibreOffice 4.1
  */
@@ -936,9 +933,10 @@ SAL_DLLPUBLIC void SAL_CALL rtl_string_newFromStr_WithLength( rtl_String ** newS
     or beginIndex + count greater than the length of the string have
     undefined behaviour.
 
-    @param     beginIndex   the beginning index, inclusive.
-    @param     count        the number of characters.
-    @return    the specified substring.
+    @param[out]    newStr       the specified substring.
+    @param[in]     from         the String to take the substring from.
+    @param[in]     beginIndex   the beginning index, inclusive.
+    @param[in]     count        the number of characters.
 
     @since LibreOffice 4.0
  */
diff --git a/sal/inc/rtl/uri.h b/sal/inc/rtl/uri.h
index 1e58e172d182..251af025ef82 100644
--- a/sal/inc/rtl/uri.h
+++ b/sal/inc/rtl/uri.h
@@ -33,13 +33,11 @@ extern "C" {
 
 /**  Various predefined URI 'char classes.'
 
-     @descr
      A 'char class' defines which (ASCII) characters can be written 'as they
      are' in a part of a Uri, and which characters have to be written using
      escape sequences ('%' followed by two hex digits).  Characters outside
      the ASCII range are always written using escape sequences.
 
-     @descr
      If there are other frequently used char classes, they can be added to
      this enumeration; the function rtl_getUriCharClass() has to be adapted
      then, too.
@@ -48,58 +46,64 @@ typedef enum
 {
     /** The empty char class.
 
-        @descr
         All characters are written using escape sequences.
      */
     rtl_UriCharClassNone,
 
     /** The RFC 2732 @<uric> char class.
 
-        @descr
+        @verbatim
         The 'valid' characters are !$&'()*+,-./:;=?@[]_~ plus digits and
         letters.
+        @endverbatim
      */
     rtl_UriCharClassUric,
 
     /** The RFC 2396 @<uric_no_slash> char class.
 
-        @descr
+        @verbatim
         The 'valid' characters are !$&'()*+,-.:;=?@_~ plus digits and letters.
+        @endverbatim
      */
     rtl_UriCharClassUricNoSlash,
 
     /** The RFC 2396 @<rel_segment> char class.
 
-        @descr
+        @verbatim
         The 'valid' characters are !$&'()*+,-.;=@_~ plus digits and letters.
+        @endverbatim
      */
     rtl_UriCharClassRelSegment,
 
     /** The RFC 2396 @<reg_name> char class.
 
-        @descr
+        @verbatim
         The 'valid' characters are !$&'()*+,-.:;=@_~ plus digits and letters.
+        @endverbatim
      */
     rtl_UriCharClassRegName,
 
     /** The RFC 2396 @<userinfo> char class.
 
-        @descr
+        @verbatim
         The 'valid' characters are !$&'()*+,-.:;=_~ plus digits and letters.
+        @endverbatim
      */
     rtl_UriCharClassUserinfo,
 
     /** The RFC 2396 @<pchar> char class.
 
-        @descr
+        @verbatim
         The 'valid' characters are !$&'()*+,-.:=@_~ plus digits and letters.
+        @endverbatim
      */
     rtl_UriCharClassPchar,
 
     /** The char class for the values of uno URL parameters.
 
-        @descr
+        @verbatim
         The 'valid' characters are !$&'()*+-./:?@_~ plus digits and letters.
+        @endverbatim
      */
     rtl_UriCharClassUnoParamValue,
 
@@ -115,7 +119,6 @@ typedef enum
     /** The special meaning of '%' is ignored (i.e., there are by definition
         no escape sequences in the input).
 
-        @descr
         This mechanism is useful to encode user input as part of a URI (e.g.,
         the user-supplied password in an ftp URL---'%20abcde' is a valid
         password, so do not assume that the '%20' is an escaped space).
@@ -126,7 +129,6 @@ typedef enum
         even if they represent characters that need not be escaped or if they
         do not even map to characters in the given charset.
 
-        @descr
         This mechanism is useful when passing on complete URIs more or less
         unmodified (e.g., within an HTTP proxy): missing escape sequences are
         added, but existing escape sequences are not touched (except that any
@@ -138,7 +140,6 @@ typedef enum
         a first step; only those that represent characters that need to be
         escaped are kept intact.
 
-        @descr
         This mechanism is useful to properly encode complete URIs entered by
         the user: the URI is brought into a 'canonic form,' but care is taken
         not to damage (valid) escape sequences the (careful) user already
@@ -176,7 +177,6 @@ typedef enum
     /** The text is returned in the form of an IURI (cf.
         draft-masinter-url-i18n-05.txt).
 
-        @descr
         All escape sequences representing ASCII characters (%00--%7F) are
         kept, all other escape sequences are interpreted as UTF-8 characters
         and translated to Unicode, if possible.
@@ -185,7 +185,6 @@ typedef enum
 
     /** The text is decoded.
 
-        @descr
         All escape sequences representing characters from the given charset
         are decoded and translated to Unicode, if possible.
      */
@@ -204,7 +203,6 @@ rtl_UriDecodeMechanism;
 
 /** Map a predefined rtl_UriCharClass to a form usable by rtl_uriEncode().
 
-    @descr
     The function rtl_uriEncode() expects an array of 128 booleans, and this
     function maps rtl_UriCharClass enumeration members to such arrays.
 
diff --git a/sal/inc/rtl/ustrbuf.h b/sal/inc/rtl/ustrbuf.h
index f52fac469f7d..7df10c18cc40 100644
--- a/sal/inc/rtl/ustrbuf.h
+++ b/sal/inc/rtl/ustrbuf.h
@@ -79,12 +79,13 @@ SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_uStringbuffer_newFromStringBuffer(
     If the <code>minimumCapacity</code> argument is nonpositive, this
     method takes no action and simply returns.
 
-    @param   capacity          in: old capicity, out: new capacity.
-    @param   minimumCapacity   the minimum desired capacity.
+    @param[in,out]   This              the String to operate on.
+    @param[in,out]   capacity          in: old capacity, out: new capacity.
+    @param[in]       minimumCapacity   the minimum desired capacity.
  */
 SAL_DLLPUBLIC void SAL_CALL rtl_uStringbuffer_ensureCapacity(
-                                                /*inout*/rtl_uString ** This,
-                                                /*inout*/sal_Int32* capacity,
+                                                rtl_uString ** This,
+                                                sal_Int32* capacity,
                                                 sal_Int32 minimumCapacity);
 
 /**
@@ -165,11 +166,12 @@ SAL_DLLPUBLIC void SAL_CALL rtl_uStringbuffer_insert_ascii(
 
     start must be >= 0 && <= This->length
 
-    @param  start       The beginning index, inclusive
-    @param  len         The substring length
+    @param[in,out]  This    The String to operate on.
+    @param[in]      start   The beginning index, inclusive
+    @param[in]      len     The substring length
  */
 SAL_DLLPUBLIC void SAL_CALL rtl_uStringbuffer_remove(
-                                       /*inout*/rtl_uString ** This,
+                                       rtl_uString ** This,
                                        sal_Int32 start,
                                        sal_Int32 len );
 
diff --git a/sal/inc/rtl/ustrbuf.hxx b/sal/inc/rtl/ustrbuf.hxx
index 8e4ca1d80ba4..5743800fc2ef 100644
--- a/sal/inc/rtl/ustrbuf.hxx
+++ b/sal/inc/rtl/ustrbuf.hxx
@@ -667,6 +667,7 @@ public:
         string are then appended to this string buffer.
 
         @param   i   an <code>sal_Int32</code>.
+        @param radix the radix
         @return  this string buffer.
      */
     OUStringBuffer & append(sal_Int32 i, sal_Int16 radix = 10 )
@@ -684,6 +685,7 @@ public:
         string are then appended to this string buffer.
 
         @param   l   a <code>long</code>.
+        @param radix the radix
         @return  this string buffer.
      */
     OUStringBuffer & append(sal_Int64 l, sal_Int16 radix = 10 )
diff --git a/sal/inc/rtl/ustring.h b/sal/inc/rtl/ustring.h
index ba19b83ee8cc..f6bf956c0c51 100644
--- a/sal/inc/rtl/ustring.h
+++ b/sal/inc/rtl/ustring.h
@@ -1207,11 +1207,8 @@ SAL_DLLPUBLIC void SAL_CALL rtl_uString_new(
     alternatively pass ownership to an OUString with
     rtl::OUString(newStr, SAL_NO_ACQUIRE);
 
-    @param newStr
-    pointer to the new string.
-
-    @param len
-    the number of characters.
+    @param[in] nLen the number of characters.
+    @return pointer to the new string.
 
     @since LibreOffice 4.1
  */
@@ -1292,8 +1289,10 @@ SAL_DLLPUBLIC void SAL_CALL rtl_uString_newFromStr_WithLength(
     or beginIndex + count greater than the length of the string have
     undefined behaviour.
 
-    @param     beginIndex   the beginning index, inclusive.
-    @param     count        the number of characters.
+    @param[out]    newStr       the specified substring.
+    @param[in]     from         the String to take the substring from.
+    @param[in]     beginIndex   the beginning index, inclusive.
+    @param[in]     count        the number of characters.
     @return    the specified substring.
 
     @since LibreOffice 4.0
diff --git a/sal/inc/sal/log.hxx b/sal/inc/sal/log.hxx
index 71e2d52ef7fe..340589e260e7 100644
--- a/sal/inc/sal/log.hxx
+++ b/sal/inc/sal/log.hxx
@@ -212,11 +212,15 @@ inline char const * unwrapStream(SAL_UNUSED_PARAMETER StreamIgnore const &) {
     For all the other macros, the given area argument must be non-null and must
     match the regular expression
 
+    @verbatim
       <area> ::= <segment>("."<segment>)*
+    @endverbatim
 
     with
 
+    @verbatim
       <segment> ::= [0-9a-z]+
+    @endverbatim
 
     For a list of areas used see @ref sal_log_areas "SAL debug areas". Whenever
     you use a new log area, add it to the file sal/inc/sal/log-areas.dox .
@@ -233,13 +237,17 @@ inline char const * unwrapStream(SAL_UNUSED_PARAMETER StreamIgnore const &) {
     macro calls actually generate log output.  The environment variable SAL_LOG
     must either be unset or must match the regular expression
 
+    @verbatim
       <env> ::= <switch>*
+    @endverbatim
 
     with
 
+    @verbatim
       <switch> ::= <sense><level>("."<area>)?
       <sense> ::= "+"|"-"
       <level> ::= "INFO"|"WARN"
+    @endverbatim
 
     If the environment variable is unset, "+WARN" is used instead (which results
     in all warnings being output but no infos).  If the given value does not