osl: use doxygen @retval and remove HTML markup

Change-Id: Ia0d0d6b0805612a26fcb3e1cf2f7d2555f7f98f1
Reviewed-on: https://gerrit.libreoffice.org/35331
Tested-by: Jenkins <ci@libreoffice.org>
Reviewed-by: Chris Sherlock <chris.sherlock79@gmail.com>

12 files changed, 706 insertions, 859 deletions

diff --git a/include/osl/conditn.h b/include/osl/conditn.h
index d0c56a33e643..6c7c166ea87d 100644
--- a/include/osl/conditn.h
+++ b/include/osl/conditn.h
@@ -32,9 +32,9 @@ extern "C" {
 typedef void* oslCondition;
 
 typedef enum {
-    osl_cond_result_ok,     /* successful completion */
-    osl_cond_result_error,  /* error occurred, check osl_getLastSocketError() for details */
-    osl_cond_result_timeout, /* blocking operation timed out */
+    osl_cond_result_ok,         /* successful completion */
+    osl_cond_result_error,      /* error occurred, check osl_getLastSocketError() for details */
+    osl_cond_result_timeout,    /* blocking operation timed out */
     osl_cond_result_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
 } oslConditionResult;
 
@@ -44,7 +44,7 @@ typedef enum {
                 for a more robust and helpful condition.
 
     The condition is in the reset-state.
-    @returns 0 if condition could not be created.
+    @retval 0 if condition could not be created.
 */
 SAL_DLLPUBLIC oslCondition SAL_CALL osl_createCondition(void);
 
@@ -56,13 +56,13 @@ SAL_DLLPUBLIC void SAL_CALL osl_destroyCondition(oslCondition Condition);
 /** Sets condition to True => wait() will not block, check() returns True.
     NOTE: ALL threads waiting on this condition are unblocked!
     @param Condition handle to a created condition.
-    @return False if system-call failed.
+    @retval False if system-call failed.
 */
 SAL_DLLPUBLIC sal_Bool SAL_CALL osl_setCondition(oslCondition Condition);
 
 /** Sets condition to False => wait() will block, check() returns False
     @param Condition handle to a created condition.
-    @return False if system-call failed.
+    @retval False if system-call failed.
 */
 SAL_DLLPUBLIC sal_Bool SAL_CALL osl_resetCondition(oslCondition Condition);
 
@@ -77,8 +77,8 @@ SAL_DLLPUBLIC oslConditionResult SAL_CALL osl_waitCondition(oslCondition Conditi
 
 /** Queries the state of the condition without blocking.
     @param Condition handle to a created condition.
-    @return True: condition is set. <BR>
-    False: condition is not set. <BR>
+    @retval True condition is set
+    @retval False condition is not set
 */
 SAL_DLLPUBLIC sal_Bool SAL_CALL osl_checkCondition(oslCondition Condition);
 
diff --git a/include/osl/diagnose.hxx b/include/osl/diagnose.hxx
index facccf929950..7108a046a98a 100644
--- a/include/osl/diagnose.hxx
+++ b/include/osl/diagnose.hxx
@@ -98,7 +98,7 @@ typedef ::std::unordered_set<void const*, VoidPtrHash > VoidPointerSet;
 struct ObjectRegistryData {
     ObjectRegistryData( ::std::type_info const& rTypeInfo )
         : m_pName(rTypeInfo.name()), m_nCount(0), m_addresses(),
-          m_bStoreAddresses(osl_detail_ObjectRegistry_storeAddresses(m_pName)){}
+          m_bStoreAddresses(osl_detail_ObjectRegistry_storeAddresses(m_pName)) {}
 
     char const* const m_pName;
     oslInterlockedCount m_nCount;
@@ -148,9 +148,7 @@ private:
 /** Helper class which indicates leaking object(s) of a particular class in
     non-pro builds; use e.g.
 
-    <pre>
     class MyClass : private osl::DebugBase<MyClass> {...};
-    </pre>
 
     Using the environment variable
 
diff --git a/include/osl/file.h b/include/osl/file.h
index 12a0de8c9074..e99ff3bc7d19 100644
--- a/include/osl/file.h
+++ b/include/osl/file.h
@@ -35,26 +35,26 @@ extern "C" {
 Main goals and usage hints
 
 The main intentention of this interface is to provide an universal portable and
-high performance access to file system issues on any operating system.<p>
+high performance access to file system issues on any operating system.
 
-There are a few main goals:<p>
+There are a few main goals:
 
 1.The path specifications always has to be absolute. Any usage of relative path
-specifications is forbidden. Exceptions are <code>osl_getSystemPathFromFileURL</code>,
-<code>osl_getFileURLFromSystemPath</code> and <code>osl_getAbsoluteFileURL</code>. Most operating systems
+specifications is forbidden. Exceptions are osl_getSystemPathFromFileURL,
+osl_getFileURLFromSystemPath and osl_getAbsoluteFileURL. Most operating systems
 provide a "Current Directory" per process. This is the reason why relative path
-specifications can cause problems in multithreading environments.<p>
+specifications can cause problems in multithreading environments.
 
 2.Proprietary notations of file paths are not supported. Every path notation
 must the file URL specification. File URLs must be encoded in UTF8 and
 after that escaped. Although the URL parameter is a unicode string, the must
-contain only ASCII characters<p>
+contain only ASCII characters
 
 3.The caller cannot get any information whether a file system is case sensitive,
 case preserving or not. The operating system implementation itself should
 determine if it can map case-insensitive paths. The case correct notation of
 a filename or file path is part of the "File Info". This case correct name
-can be used as a unique key if necessary.<p>
+can be used as a unique key if necessary.
 
 4. Obtaining information about files or volumes is controlled by a
 bitmask which specifies which fields are of interest. Due to performance
@@ -63,18 +63,18 @@ But if the operating system provides more information anyway the
 implementation can set more fields on output as were requested. It is in the
 responsibility of the caller to decide if he uses this additional information
 or not. But he should do so to prevent further unnecessary calls if the information
-is already there.<br>
+is already there.
 
-The input bitmask supports a flag <code>osl_FileStatus_Mask_Validate</code> which
+The input bitmask supports a flag osl_FileStatus_Mask_Validate which
 can be used to force retrieving uncached validated information. Setting this flag
-when calling <code>osl_getFileStatus</code> in combination with no other flag is
+when calling osl_getFileStatus in combination with no other flag is
 a synonym for a "FileExists". This should only be done when processing a single file
 (f.e. before opening) and NEVER during enumeration of directory contents on any step
 of information processing. This would change the runtime behaviour from O(n) to
-O(n*n/2) on nearly every file system.<br>
+O(n*n/2) on nearly every file system.
 On Windows NT reading the contents of an directory with 7000 entries and
 getting full information about every file only takes 0.6 seconds. Specifying the
-flag <code>osl_FileStatus_Mask_Validate</code> for each entry will increase the
+flag osl_FileStatus_Mask_Validate for each entry will increase the
 time to 180 seconds (!!!).
 
 */
@@ -148,17 +148,16 @@ typedef void *oslDirectoryItem;
     On success it receives a handle used for subsequent calls by osl_getNextDirectoryItem().
     The handle has to be released by a call to osl_closeDirectory().
 
-    @return
-    osl_File_E_None on success<br>
-    osl_File_E_INVAL the format of the parameters was not valid<br>
-    osl_File_E_NOENT the specified path doesn't exist<br>
-    osl_File_E_NOTDIR the specified path is not an directory <br>
-    osl_File_E_NOMEM not enough memory for allocating structures <br>
-    osl_File_E_ACCES permission denied<br>
-    osl_File_E_MFILE too many open files used by the process<br>
-    osl_File_E_NFILE too many open files in the system<br>
-    osl_File_E_NAMETOOLONG File name too long<br>
-    osl_File_E_LOOP Too many symbolic links encountered<p>
+    @retval osl_File_E_None on success
+    @retval osl_File_E_INVAL the format of the parameters was not valid
+    @retval osl_File_E_NOENT the specified path doesn't exist
+    @retval osl_File_E_NOTDIR the specified path is not an directory
+    @retval osl_File_E_NOMEM not enough memory for allocating structures
+    @retval osl_File_E_ACCES permission denied
+    @retval osl_File_E_MFILE too many open files used by the process
+    @retval osl_File_E_NFILE too many open files in the system
+    @retval osl_File_E_NAMETOOLONG File name too long
+    @retval osl_File_E_LOOP Too many symbolic links encountered
 
     @see osl_getNextDirectoryItem()
     @see osl_closeDirectory()
@@ -185,13 +184,12 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_openDirectory(
     is going to call this function uHint times afterwards. This enables the implementation to
     get the information for more than one file and cache it until the next calls.
 
-    @return
-    osl_File_E_None on success<br>
-    osl_File_E_INVAL the format of the parameters was not valid<br>
-    osl_File_E_NOMEM not enough memory for allocating structures <br>
-    osl_File_E_NOENT no more entries in this directory<br>
-    osl_File_E_BADF invalid oslDirectory parameter<br>
-    osl_File_E_OVERFLOW the value too large for defined data type
+    @retval osl_File_E_None on success
+    @retval osl_File_E_INVAL the format of the parameters was not valid
+    @retval osl_File_E_NOMEM not enough memory for allocating structures
+    @retval osl_File_E_NOENT no more entries in this directory
+    @retval osl_File_E_BADF invalid oslDirectory parameter
+    @retval osl_File_E_OVERFLOW the value too large for defined data type
 
     @see osl_releaseDirectoryItem()
     @see osl_acquireDirectoryItem()
@@ -211,12 +209,11 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_getNextDirectoryItem(
     @param Directory [in]
     A handle received by a call to osl_openDirectory().
 
-    @return
-    osl_File_E_None on success<br>
-    osl_File_E_INVAL the format of the parameters was not valid<br>
-    osl_File_E_NOMEM not enough memory for allocating structures<br>
-    osl_File_E_BADF invalid oslDirectory parameter<br>
-    osl_File_E_INTR the function call was interrupted<p>
+    @retval osl_File_E_None on success
+    @retval osl_File_E_INVAL the format of the parameters was not valid
+    @retval osl_File_E_NOMEM not enough memory for allocating structures
+    @retval osl_File_E_BADF invalid oslDirectory parameter
+    @retval osl_File_E_INTR the function call was interrupted
 
     @see osl_openDirectory()
 */
@@ -238,22 +235,21 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_closeDirectory(
     On success it receives a handle which can be used for subsequent calls to osl_getFileStatus().
     The handle has to be released by a call to osl_releaseDirectoryItem().
 
-    @return
-    osl_File_E_None on success<br>
-    osl_File_E_INVAL the format of the parameters was not valid<br>
-    osl_File_E_NOMEM not enough memory for allocating structures <br>
-    osl_File_E_ACCES permission denied<br>
-    osl_File_E_MFILE too many open files used by the process<br>
-    osl_File_E_NFILE too many open files in the system<br>
-    osl_File_E_NOENT no such file or directory<br>
-    osl_File_E_LOOP too many symbolic links encountered<br>
-    osl_File_E_NAMETOOLONG the file name is too long<br>
-    osl_File_E_NOTDIR a component of the path prefix of path is not a directory<br>
-    osl_File_E_IO on I/O errors<br>
-    osl_File_E_MULTIHOP multihop attempted<br>
-    osl_File_E_NOLINK link has been severed<br>
-    osl_File_E_FAULT bad address<br>
-    osl_File_E_INTR the function call was interrupted<p>
+    @retval osl_File_E_None on success
+    @retval osl_File_E_INVAL the format of the parameters was not valid
+    @retval osl_File_E_NOMEM not enough memory for allocating structures
+    @retval osl_File_E_ACCES permission denied
+    @retval osl_File_E_MFILE too many open files used by the process
+    @retval osl_File_E_NFILE too many open files in the system
+    @retval osl_File_E_NOENT no such file or directory
+    @retval osl_File_E_LOOP too many symbolic links encountered
+    @retval osl_File_E_NAMETOOLONG the file name is too long
+    @retval osl_File_E_NOTDIR a component of the path prefix of path is not a directory
+    @retval osl_File_E_IO on I/O errors
+    @retval osl_File_E_MULTIHOP multihop attempted
+    @retval osl_File_E_NOLINK link has been severed
+    @retval osl_File_E_FAULT bad address
+    @retval osl_File_E_INTR the function call was interrupted
 
     @see osl_releaseDirectoryItem()
     @see osl_acquireDirectoryItem()
@@ -274,10 +270,9 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_getDirectoryItem(
     @param  Item [in]
     A handle received by a call to osl_getDirectoryItem() or osl_getNextDirectoryItem().
 
-    @return
-    osl_File_E_None on success<br>
-    osl_File_E_NOMEM not enough memory for allocating structures<br>
-    osl_File_E_INVAL the format of the parameters was not valid<br>
+    @retval osl_File_E_None on success
+    @retval osl_File_E_NOMEM not enough memory for allocating structures
+    @retval osl_File_E_INVAL the format of the parameters was not valid
 
     @see osl_getDirectoryItem()
     @see osl_getNextDirectoryItem()
@@ -297,10 +292,9 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_acquireDirectoryItem(
     @param  Item [in]
     A handle received by a call to osl_getDirectoryItem() or osl_getNextDirectoryItem().
 
-    @return
-    osl_File_E_None on success<br>
-    osl_File_E_NOMEM not enough memory for allocating structures<br>
-    osl_File_E_INVAL the format of the parameters was not valid<br>
+    @retval osl_File_E_None on success
+    @retval osl_File_E_NOMEM not enough memory for allocating structures
+    @retval osl_File_E_INVAL the format of the parameters was not valid
 
     @see osl_getDirectoryItem()
     @see osl_getNextDirectoryItem()
@@ -321,9 +315,8 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_releaseDirectoryItem(
     @param  pItemB [in]
     A directory handle to compare with pItemA
 
-    @return
-    sal_True: if the items point to an identical resource<br>
-    sal_False: if the items point to a different resource, or a fatal error occurred<br>
+    @retval sal_True if the items point to an identical resource
+    @retval sal_False if the items point to a different resource, or a fatal error occurred
 
     @see osl_getDirectoryItem()
 
@@ -403,14 +396,14 @@ struct _oslFileStatus {
     TimeValue   aModifyTime;
 /** Size in bytes of the file. Zero for directories and volumes. */
     sal_uInt64  uFileSize;
-/** Case correct name of the file. Should be set to zero before calling <code>osl_getFileStatus</code>
+/** Case correct name of the file. Should be set to zero before calling osl_getFileStatus
     and released after usage. */
     rtl_uString *ustrFileName;
-/** Full URL of the file. Should be set to zero before calling <code>osl_getFileStatus</code>
+/** Full URL of the file. Should be set to zero before calling osl_getFileStatus
     and released after usage. */
     rtl_uString *ustrFileURL;
 /** Full URL of the target file if the file itself is a link.
-    Should be set to zero before calling <code>osl_getFileStatus</code>
+    Should be set to zero before calling osl_getFileStatus
     and released after usage. */
     rtl_uString *ustrLinkTargetURL;
 } oslFileStatus;
@@ -429,26 +422,25 @@ struct _oslFileStatus {
     @param  uFieldMask [in]
     Specifies which fields of the structure pointed to by pStatus are of interest to the caller.
 
-    @return
-    osl_File_E_None on success<br>
-    osl_File_E_NOMEM not enough memory for allocating structures <br>
-    osl_File_E_INVAL the format of the parameters was not valid<br>
-    osl_File_E_LOOP too many symbolic links encountered<br>
-    osl_File_E_ACCES permission denied<br>
-    osl_File_E_NOENT no such file or directory<br>
-    osl_File_E_NAMETOOLONG file name too long<br>
-    osl_File_E_BADF invalid oslDirectoryItem parameter<br>
-    osl_File_E_FAULT bad address<br>
-    osl_File_E_OVERFLOW value too large for defined data type<br>
-    osl_File_E_INTR function call was interrupted<br>
-    osl_File_E_NOLINK link has been severed<br>
-    osl_File_E_MULTIHOP components of path require hopping to multiple remote machines and the file system does not allow it<br>
-    osl_File_E_MFILE too many open files used by the process<br>
-    osl_File_E_NFILE too many open files in the system<br>
-    osl_File_E_NOSPC no space left on device<br>
-    osl_File_E_NXIO no such device or address<br>
-    osl_File_E_IO on I/O errors<br>
-    osl_File_E_NOSYS function not implemented<p>
+    @retval osl_File_E_None on success
+    @retval osl_File_E_NOMEM not enough memory for allocating structures
+    @retval osl_File_E_INVAL the format of the parameters was not valid
+    @retval osl_File_E_LOOP too many symbolic links encountered
+    @retval osl_File_E_ACCES permission denied
+    @retval osl_File_E_NOENT no such file or directory
+    @retval osl_File_E_NAMETOOLONG file name too long
+    @retval osl_File_E_BADF invalid oslDirectoryItem parameter
+    @retval osl_File_E_FAULT bad address
+    @retval osl_File_E_OVERFLOW value too large for defined data type
+    @retval osl_File_E_INTR function call was interrupted
+    @retval osl_File_E_NOLINK link has been severed
+    @retval osl_File_E_MULTIHOP components of path require hopping to multiple remote machines and the file system does not allow it
+    @retval osl_File_E_MFILE too many open files used by the process
+    @retval osl_File_E_NFILE too many open files in the system
+    @retval osl_File_E_NOSPC no space left on device
+    @retval osl_File_E_NXIO no such device or address
+    @retval osl_File_E_IO on I/O errors
+    @retval osl_File_E_NOSYS function not implemented
 
     @see osl_getDirectoryItem()
     @see osl_getNextDirectoryItem()
@@ -469,8 +461,8 @@ typedef void *oslVolumeDeviceHandle;
     @param Handle [in]
     An oslVolumeDeviceHandle received by a call to osl_getVolumeInformation().
 
-    @return
-    osl_File_E_None on success<br>
+    @retval
+    osl_File_E_None on success
 
     @todo
     specify all error codes that may be returned
@@ -491,8 +483,8 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_releaseVolumeDeviceHandle(
     @param Handle [in]
     An oslVolumeDeviceHandle received by a call to osl_getVolumeInformation().
 
-    @return
-    osl_File_E_None on success<br>
+    @retval
+    osl_File_E_None on success
 
     @todo
     specify all error codes that may be returned
@@ -512,20 +504,19 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_acquireVolumeDeviceHandle(
     @param ppustrDirectoryURL [out]
     Receives the full qualified URL where the device is mounted to.
 
-    @return
-    osl_File_E_None on success<br>
-    osl_File_E_NOMEM not enough memory for allocating structures <br>
-    osl_File_E_INVAL the format of the parameters was not valid<br>
-    osl_File_E_ACCES permission denied<br>
-    osl_File_E_NXIO  no such device or address<br>
-    osl_File_E_NODEV no such device<br>
-    osl_File_E_NOENT no such file or directory<br>
-    osl_File_E_FAULT bad address<br>
-    osl_FilE_E_INTR function call was interrupted<br>
-    osl_File_E_IO on I/O errors<br>
-    osl_File_E_MULTIHOP multihop attempted<br>
-    osl_File_E_NOLINK link has been severed<br>
-    osl_File_E_EOVERFLOW value too large for defined data type<br>
+    @retval osl_File_E_None on success
+    @retval osl_File_E_NOMEM not enough memory for allocating structures
+    @retval osl_File_E_INVAL the format of the parameters was not valid
+    @retval osl_File_E_ACCES permission denied
+    @retval osl_File_E_NXIO  no such device or address
+    @retval osl_File_E_NODEV no such device
+    @retval osl_File_E_NOENT no such file or directory
+    @retval osl_File_E_FAULT bad address
+    @retval osl_FilE_E_INTR function call was interrupted
+    @retval osl_File_E_IO on I/O errors
+    @retval osl_File_E_MULTIHOP multihop attempted
+    @retval osl_File_E_NOLINK link has been severed
+    @retval osl_File_E_EOVERFLOW value too large for defined data type
 
     @see    osl_getVolumeInformation()
 */
@@ -582,10 +573,10 @@ struct _oslVolumeInfo {
     sal_uInt32      uMaxNameLength;
 /** Maximum length of a full quallified path in system notation */
     sal_uInt32      uMaxPathLength;
-/** Points to a string that receives the name of the file system type. String should be set to zero before calling <code>osl_getVolumeInformation</code>
+/** Points to a string that receives the name of the file system type. String should be set to zero before calling osl_getVolumeInformation
     and released after usage. */
     rtl_uString     *ustrFileSystemName;
-/** Pointer to handle the receives underlying device. Handle should be set to zero before calling <code>osl_getVolumeInformation</code>*/
+/** Pointer to handle the receives underlying device. Handle should be set to zero before calling osl_getVolumeInformation*/
     oslVolumeDeviceHandle   *pDeviceHandle;
 } oslVolumeInfo;
 
@@ -606,21 +597,20 @@ struct _oslVolumeInfo {
     @param uFieldMask [in]
     Specifies which members of the structure should be filled
 
-    @return
-    osl_File_E_None on success<br>
-    osl_File_E_NOMEM not enough memory for allocating structures <br>
-    osl_File_E_INVAL the format of the parameters was not valid<br>
-    osl_File_E_NOTDIR not a directory<br>
-    osl_File_E_NAMETOOLONG file name too long<br>
-    osl_File_E_NOENT no such file or directory<br>
-    osl_File_E_ACCES permission denied<br>
-    osl_File_E_LOOP too many symbolic links encountered<br>
-    ols_File_E_FAULT Bad address<br>
-    osl_File_E_IO on I/O errors<br>
-    osl_File_E_NOSYS function not implemented<br>
-    osl_File_E_MULTIHOP multihop attempted<br>
-    osl_File_E_NOLINK link has been severed<br>
-    osl_File_E_INTR function call was interrupted<br>
+    @retval osl_File_E_None on success
+    @retval osl_File_E_NOMEM not enough memory for allocating structures
+    @retval osl_File_E_INVAL the format of the parameters was not valid
+    @retval osl_File_E_NOTDIR not a directory
+    @retval osl_File_E_NAMETOOLONG file name too long
+    @retval osl_File_E_NOENT no such file or directory
+    @retval osl_File_E_ACCES permission denied
+    @retval osl_File_E_LOOP too many symbolic links encountered
+    @retval ols_File_E_FAULT Bad address
+    @retval osl_File_E_IO on I/O errors
+    @retval osl_File_E_NOSYS function not implemented
+    @retval osl_File_E_MULTIHOP multihop attempted
+    @retval osl_File_E_NOLINK link has been severed
+    @retval osl_File_E_INTR function call was interrupted
 
     @see    osl_getFileStatus()
     @see    oslVolumeInfo
@@ -660,32 +650,31 @@ typedef void *oslFileHandle;
     the LibreOffice Android bootstrapping code. So files "opened" from
     there aren't actually files in the OS sense.
 
-    @return
-    osl_File_E_None on success<br>
-    osl_File_E_NOMEM not enough memory for allocating structures <br>
-    osl_File_E_INVAL the format of the parameters was not valid<br>
-    osl_File_E_NAMETOOLONG pathname was too long<br>
-    osl_File_E_NOENT no such file or directory<br>
-    osl_File_E_ACCES permission denied<br>
-    osl_File_E_AGAIN a write lock could not be established<br>
-    osl_File_E_NOTDIR not a directory<br>
-    osl_File_E_NXIO no such device or address<br>
-    osl_File_E_NODEV no such device<br>
-    osl_File_E_ROFS read-only file system<br>
-    osl_File_E_TXTBSY text file busy<br>
-    osl_File_E_FAULT bad address<br>
-    osl_File_E_LOOP too many symbolic links encountered<br>
-    osl_File_E_NOSPC no space left on device<br>
-    osl_File_E_ISDIR is a directory<br>
-    osl_File_E_MFILE too many open files used by the process<br>
-    osl_File_E_NFILE too many open files in the system<br>
-    osl_File_E_DQUOT quota exceeded<br>
-    osl_File_E_EXIST file exists<br>
-    osl_FilE_E_INTR function call was interrupted<br>
-    osl_File_E_IO on I/O errors<br>
-    osl_File_E_MULTIHOP multihop attempted<br>
-    osl_File_E_NOLINK link has been severed<br>
-    osl_File_E_EOVERFLOW value too large for defined data type<br>
+    @retval osl_File_E_None on success
+    @retval osl_File_E_NOMEM not enough memory for allocating structures
+    @retval osl_File_E_INVAL the format of the parameters was not valid
+    @retval osl_File_E_NAMETOOLONG pathname was too long
+    @retval osl_File_E_NOENT no such file or directory
+    @retval osl_File_E_ACCES permission denied
+    @retval osl_File_E_AGAIN a write lock could not be established
+    @retval osl_File_E_NOTDIR not a directory
+    @retval osl_File_E_NXIO no such device or address
+    @retval osl_File_E_NODEV no such device
+    @retval osl_File_E_ROFS read-only file system
+    @retval osl_File_E_TXTBSY text file busy
+    @retval osl_File_E_FAULT bad address
+    @retval osl_File_E_LOOP too many symbolic links encountered
+    @retval osl_File_E_NOSPC no space left on device
+    @retval osl_File_E_ISDIR is a directory
+    @retval osl_File_E_MFILE too many open files used by the process
+    @retval osl_File_E_NFILE too many open files in the system
+    @retval osl_File_E_DQUOT quota exceeded
+    @retval osl_File_E_EXIST file exists
+    @retval osl_FilE_E_INTR function call was interrupted
+    @retval osl_File_E_IO on I/O errors
+    @retval osl_File_E_MULTIHOP multihop attempted
+    @retval osl_File_E_NOLINK link has been severed
+    @retval osl_File_E_EOVERFLOW value too large for defined data type
 
     @see osl_closeFile()
     @see osl_setFilePos()
@@ -714,10 +703,9 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_openFile(
     @param uPos [in]
     Absolute position from the beginning of the file.
 
-    @return
-    osl_File_E_None on success<br>
-    osl_File_E_INVAL the format of the parameters was not valid<br>
-    osl_File_E_OVERFLOW the resulting file offset would be a value which cannot be represented correctly for regular files<br>
+    @retval osl_File_E_None on success
+    @retval osl_File_E_INVAL the format of the parameters was not valid
+    @retval osl_File_E_OVERFLOW the resulting file offset would be a value which cannot be represented correctly for regular files
 
     @see    osl_openFile()
     @see    osl_getFilePos()
@@ -735,10 +723,9 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_setFilePos(
     @param pPos [out]
     On success receives the current position of the file pointer.
 
-    @return
-    osl_File_E_None on success<br>
-    osl_File_E_INVAL the format of the parameters was not valid<br>
-    osl_File_E_OVERFLOW the resulting file offset would be a value which cannot be represented correctly for regular files<br>
+    @retval osl_File_E_None on success
+    @retval osl_File_E_INVAL the format of the parameters was not valid
+    @retval osl_File_E_OVERFLOW the resulting file offset would be a value which cannot be represented correctly for regular files
 
     @see osl_openFile()
     @see osl_setFilePos()
@@ -761,10 +748,9 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_getFilePos(
     @param uSize [in]
     New size in bytes.
 
-    @return
-    osl_File_E_None on success<br>
-    osl_File_E_INVAL the format of the parameters was not valid<br>
-    osl_File_E_OVERFLOW the resulting file offset would be a value which cannot be represented correctly for regular files<br>
+    @retval osl_File_E_None on success
+    @retval osl_File_E_INVAL the format of the parameters was not valid
+    @retval osl_File_E_OVERFLOW the resulting file offset would be a value which cannot be represented correctly for regular files
 
     @see osl_openFile()
     @see osl_setFilePos()
@@ -787,10 +773,9 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_setFileSize(
     @param pSize [out]
     Current size in bytes.
 
-    @return
-    osl_File_E_None on success<br>
-    osl_File_E_INVAL the format of the parameters was not valid<br>
-    osl_File_E_OVERFLOW the resulting file offset would be a value which cannot be represented correctly for regular files<br>
+    @retval osl_File_E_None on success
+    @retval osl_File_E_INVAL the format of the parameters was not valid
+    @retval osl_File_E_OVERFLOW the resulting file offset would be a value which cannot be represented correctly for regular files
 
     @see osl_openFile()
     @see osl_setFilePos()
@@ -895,16 +880,15 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_unmapMappedFile (
     @param pBytesRead [out]
     On success the number of bytes which have actually been retrieved.
 
-    @return
-    osl_File_E_None on success<br>
-    osl_File_E_INVAL the format of the parameters was not valid<br>
-    osl_File_E_INTR function call was interrupted<br>
-    osl_File_E_IO on I/O errors<br>
-    osl_File_E_ISDIR is a directory<br>
-    osl_File_E_BADF bad file<br>
-    osl_File_E_FAULT bad address<br>
-    osl_File_E_AGAIN operation would block<br>
-    osl_File_E_NOLINK link has been severed<br>
+    @retval osl_File_E_None on success
+    @retval osl_File_E_INVAL the format of the parameters was not valid
+    @retval osl_File_E_INTR function call was interrupted
+    @retval osl_File_E_IO on I/O errors
+    @retval osl_File_E_ISDIR is a directory
+    @retval osl_File_E_BADF bad file
+    @retval osl_File_E_FAULT bad address
+    @retval osl_File_E_AGAIN operation would block
+    @retval osl_File_E_NOLINK link has been severed
 
     @see osl_openFile()
     @see osl_writeFile()
@@ -924,16 +908,15 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_readFile(
     @param pIsEOF [out]
     Points to a variable that receives the end-of-file status.
 
-    @return
-    osl_File_E_None on success <br>
-    osl_File_E_INVAL the format of the parameters was not valid<br>
-    osl_File_E_INTR function call was interrupted<br>
-    osl_File_E_IO on I/O errors<br>
-    osl_File_E_ISDIR is a directory<br>
-    osl_File_E_BADF bad file<br>
-    osl_File_E_FAULT bad address<br>
-    osl_File_E_AGAIN operation would block<br>
-    osl_File_E_NOLINK link has been severed<p>
+    @retval osl_File_E_None on success
+    @retval osl_File_E_INVAL the format of the parameters was not valid
+    @retval osl_File_E_INTR function call was interrupted
+    @retval osl_File_E_IO on I/O errors
+    @retval osl_File_E_ISDIR is a directory
+    @retval osl_File_E_BADF bad file
+    @retval osl_File_E_FAULT bad address
+    @retval osl_File_E_AGAIN operation would block
+    @retval osl_File_E_NOLINK link has been severed
 
     @see osl_openFile()
     @see osl_readFile()
@@ -962,20 +945,19 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_isEndOfFile(
     @param pBytesWritten [out]
     On success the number of bytes which have actually been written.
 
-    @return
-    osl_File_E_None on success<br>
-    osl_File_E_INVAL the format of the parameters was not valid<br>
-    osl_File_E_FBIG file too large<br>
-    osl_File_E_DQUOT quota exceeded<p>
-    osl_File_E_AGAIN operation would block<br>
-    osl_File_E_BADF bad file<br>
-    osl_File_E_FAULT bad address<br>
-    osl_File_E_INTR function call was interrupted<br>
-    osl_File_E_IO on I/O errosr<br>
-    osl_File_E_NOLCK no record locks available<br>
-    osl_File_E_NOLINK link has been severed<br>
-    osl_File_E_NOSPC no space left on device<br>
-    osl_File_E_NXIO no such device or address<br>
+    @retval osl_File_E_None on success
+    @retval osl_File_E_INVAL the format of the parameters was not valid
+    @retval osl_File_E_FBIG file too large
+    @retval osl_File_E_DQUOT quota exceeded
+    @retval osl_File_E_AGAIN operation would block
+    @retval osl_File_E_BADF bad file
+    @retval osl_File_E_FAULT bad address
+    @retval osl_File_E_INTR function call was interrupted
+    @retval osl_File_E_IO on I/O errosr
+    @retval osl_File_E_NOLCK no record locks available
+    @retval osl_File_E_NOLINK link has been severed
+    @retval osl_File_E_NOSPC no space left on device
+    @retval osl_File_E_NXIO no such device or address
 
     @see osl_openFile()
     @see osl_readFile()
@@ -1025,16 +1007,15 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_writeFileAt(
     @param  ppSequence [in/out]
     A pointer pointer to a sal_Sequence that will hold the line read on success.
 
-    @return
-    osl_File_E_None on success<br>
-    osl_File_E_INVAL the format of the parameters was not valid<br>
-    osl_File_E_INTR function call was interrupted<br>
-    osl_File_E_IO on I/O errors<br>
-    osl_File_E_ISDIR is a directory<br>
-    osl_File_E_BADF bad file<br>
-    osl_File_E_FAULT bad address<br>
-    osl_File_E_AGAIN operation would block<br>
-    osl_File_E_NOLINK link has been severed<p>
+    @retval osl_File_E_None on success
+    @retval osl_File_E_INVAL the format of the parameters was not valid
+    @retval osl_File_E_INTR function call was interrupted
+    @retval osl_File_E_IO on I/O errors
+    @retval osl_File_E_ISDIR is a directory
+    @retval osl_File_E_BADF bad file
+    @retval osl_File_E_FAULT bad address
+    @retval osl_File_E_AGAIN operation would block
+    @retval osl_File_E_NOLINK link has been severed
 
     @see osl_openFile()
     @see osl_readFile()
@@ -1055,26 +1036,13 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_readLine(
       @param Handle
       [in] Handle to a file received by a previous call to osl_openFile().
 
-      @return
-      <dl>
-      <dt>osl_File_E_None</dt>
-      <dd>On success</dd>
-      <dt>osl_File_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>
-      <dl>
-      <dt>osl_File_E_BADF</dt>
-      <dd>The file associated with the given file handle is not open for writing</dd>
-      <dt>osl_File_E_IO</dt>
-      <dd>An I/O error occurred</dd>
-      <dt>osl_File_E_NOSPC</dt>
-      <dd>There is no enough space on the target device</dd>
-      <dt>osl_File_E_ROFS</dt>
-      <dd>The file associated with the given file handle is located on a read only file system</dd>
-      <dt>osl_File_E_TIMEDOUT</dt>
-      <dd>A remote connection timed out. This may happen when a file is on a remote location</dd>
-      </dl>
+      @retval osl_File_E_None On success
+      @retval osl_File_E_INVAL The value of the input parameter is invalid
+      @retval osl_File_E_BADF The file associated with the given file handle is not open for writing
+      @retval osl_File_E_IO An I/O error occurred
+      @retval osl_File_E_NOSPC There is no enough space on the target device
+      @retval osl_File_E_ROFS The file associated with the given file handle is located on a read only file system
+      @retval osl_File_E_TIMEDOUT A remote connection timed out. This may happen when a file is on a remote location
 
       @see osl_openFile()
       @see osl_writeFile()
@@ -1087,13 +1055,13 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_syncFile( oslFileHandle Handle );
     Handle to a file received by a previous call to osl_openFile().
 
     @return
-    osl_File_E_None on success<br>
-    osl_File_E_INVAL the format of the parameters was not valid<br>
-    osl_File_E_BADF Bad file<br>
-    osl_File_E_INTR function call was interrupted<br>
-    osl_File_E_NOLINK link has been severed<br>
-    osl_File_E_NOSPC no space left on device<br>
-    osl_File_E_IO on I/O errors<br>
+    @retval osl_File_E_None on success
+    @retval osl_File_E_INVAL the format of the parameters was not valid
+    @retval osl_File_E_BADF Bad file
+    @retval osl_File_E_INTR function call was interrupted
+    @retval osl_File_E_NOLINK link has been severed
+    @retval osl_File_E_NOSPC no space left on device
+    @retval osl_File_E_IO on I/O errors
 
     @see osl_openFile()
 */
@@ -1107,23 +1075,23 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_closeFile( oslFileHandle Handle );
     Full qualified URL of the directory to create.
 
     @return
-    osl_File_E_None on success<br>
-    osl_File_E_INVAL the format of the parameters was not valid<br>
-    osl_File_E_NOMEM not enough memory for allocating structures <br>
-    osl_File_E_EXIST file exists<br>
-    osl_File_E_ACCES permission denied<br>
-    osl_File_E_NAMETOOLONG file name too long<br>
-    osl_File_E_NOENT no such file or directory<br>
-    osl_File_E_NOTDIR not a directory<br>
-    osl_File_E_ROFS read-only file system<br>
-    osl_File_E_NOSPC no space left on device<br>
-    osl_File_E_DQUOT quota exceeded<br>
-    osl_File_E_LOOP too many symbolic links encountered<br>
-    osl_File_E_FAULT bad address<br>
-    osl_FileE_IO on I/O errors<br>
-    osl_File_E_MLINK too many links<br>
-    osl_File_E_MULTIHOP multihop attempted<br>
-    osl_File_E_NOLINK link has been severed<br>
+    @retval osl_File_E_None on success
+    @retval osl_File_E_INVAL the format of the parameters was not valid
+    @retval osl_File_E_NOMEM not enough memory for allocating structures
+    @retval osl_File_E_EXIST file exists
+    @retval osl_File_E_ACCES permission denied
+    @retval osl_File_E_NAMETOOLONG file name too long
+    @retval osl_File_E_NOENT no such file or directory
+    @retval osl_File_E_NOTDIR not a directory
+    @retval osl_File_E_ROFS read-only file system
+    @retval osl_File_E_NOSPC no space left on device
+    @retval osl_File_E_DQUOT quota exceeded
+    @retval osl_File_E_LOOP too many symbolic links encountered
+    @retval osl_File_E_FAULT bad address
+    @retval osl_FileE_IO on I/O errors
+    @retval osl_File_E_MLINK too many links
+    @retval osl_File_E_MULTIHOP multihop attempted
+    @retval osl_File_E_NOLINK link has been severed
 
     @see osl_removeDirectory()
 */
@@ -1153,23 +1121,23 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_createDirectoryWithFlags(
     Full qualified URL of the directory.
 
     @return
-    osl_File_E_None on success<br>
-    osl_File_E_INVAL the format of the parameters was not valid<br>
-    osl_File_E_NOMEM not enough memory for allocating structures <br>
-    osl_File_E_PERM operation not permitted<br>
-    osl_File_E_ACCES permission denied<br>
-    osl_File_E_NOENT no such file or directory<br>
-    osl_File_E_NOTDIR not a directory<br>
-    osl_File_E_NOTEMPTY directory not empty<br>
-    osl_File_E_FAULT bad address<br>
-    osl_File_E_NAMETOOLONG file name too long<br>
-    osl_File_E_BUSY device or resource busy<br>
-    osl_File_E_ROFS read-only file system<br>
-    osl_File_E_LOOP too many symbolic links encountered<br>
-    osl_File_E_EXIST file exists<br>
-    osl_File_E_IO on I/O errors<br>
-    osl_File_E_MULTIHOP multihop attempted<br>
-    osl_File_E_NOLINK link has been severed<br>
+    @retval osl_File_E_None on success
+    @retval osl_File_E_INVAL the format of the parameters was not valid
+    @retval osl_File_E_NOMEM not enough memory for allocating structures
+    @retval osl_File_E_PERM operation not permitted
+    @retval osl_File_E_ACCES permission denied
+    @retval osl_File_E_NOENT no such file or directory
+    @retval osl_File_E_NOTDIR not a directory
+    @retval osl_File_E_NOTEMPTY directory not empty
+    @retval osl_File_E_FAULT bad address
+    @retval osl_File_E_NAMETOOLONG file name too long
+    @retval osl_File_E_BUSY device or resource busy
+    @retval osl_File_E_ROFS read-only file system
+    @retval osl_File_E_LOOP too many symbolic links encountered
+    @retval osl_File_E_EXIST file exists
+    @retval osl_File_E_IO on I/O errors
+    @retval osl_File_E_MULTIHOP multihop attempted
+    @retval osl_File_E_NOLINK link has been severed
 
     @see osl_createDirectory()
 */
@@ -1197,9 +1165,9 @@ typedef void (SAL_CALL *oslDirectoryCreationCallbackFunc)(void* pData, rtl_uStri
 
     The osl_createDirectoryPath function creates a specified directory path.
     All nonexisting sub directories will be created.
-    <p><strong>PLEASE NOTE:</strong> You cannot rely on getting the error code
+    <strong>PLEASE NOTE:</strong> You cannot rely on getting the error code
     osl_File_E_EXIST for existing directories. Programming against this error
-    code is in general a strong indication of a wrong usage of osl_createDirectoryPath.</p>
+    code is in general a strong indication of a wrong usage of osl_createDirectoryPath.
 
     @param aDirectoryUrl
     [in] The absolute file URL of the directory path to create.
@@ -1216,37 +1184,20 @@ typedef void (SAL_CALL *oslDirectoryCreationCallbackFunc)(void* pData, rtl_uStri
     callback function. The value of this parameter may be arbitrary
     and will not be interpreted by osl_createDirectoryPath.
 
-    @return
-    <dl>
-    <dt>osl_File_E_None</dt>
-    <dd>On success</dd>
-    <dt>osl_File_E_INVAL</dt>
-    <dd>The format of the parameters was not valid</dd>
-    <dt>osl_File_E_ACCES</dt>
-    <dd>Permission denied</dd>
-    <dt>osl_File_E_EXIST</dt>
-    <dd>The final node of the specified directory path already exist</dd>
-    <dt>osl_File_E_NAMETOOLONG</dt>
-    <dd>The name of the specified directory path exceeds the maximum allowed length</dd>
-    <dt>osl_File_E_NOTDIR</dt>
-    <dd>A component of the specified directory path already exist as file in any part of the directory path</dd>
-    <dt>osl_File_E_ROFS</dt>
-    <dd>Read-only file system</dd>
-    <dt>osl_File_E_NOSPC</dt>
-    <dd>No space left on device</dd>
-    <dt>osl_File_E_DQUOT</dt>
-    <dd>Quota exceeded</dd>
-    <dt>osl_File_E_FAULT</dt>
-    <dd>Bad address</dd>
-    <dt>osl_File_E_IO</dt>
-    <dd>I/O error</dd>
-    <dt>osl_File_E_LOOP</dt>
-    <dd>Too many symbolic links encountered</dd>
-    <dt>osl_File_E_NOLINK</dt>
-    <dd>Link has been severed</dd>
-    <dt>osl_File_E_invalidError</dt>
-    <dd>An unknown error occurred</dd>
-    </dl>
+    @retval osl_File_E_None On success
+    @retval osl_File_E_INVAL The format of the parameters was not valid
+    @retval osl_File_E_ACCES Permission denied
+    @retval osl_File_E_EXIST The final node of the specified directory path already exist
+    @retval osl_File_E_NAMETOOLONG The name of the specified directory path exceeds the maximum allowed length
+    @retval osl_File_E_NOTDIR A component of the specified directory path already exist as file in any part of the directory path
+    @retval osl_File_E_ROFS Read-only file system
+    @retval osl_File_E_NOSPC No space left on device
+    @retval osl_File_E_DQUOT Quota exceeded
+    @retval osl_File_E_FAULT Bad address
+    @retval osl_File_E_IO I/O error
+    @retval osl_File_E_LOOP Too many symbolic links encountered
+    @retval osl_File_E_NOLINK Link has been severed
+    @retval osl_File_E_invalidError An unknown error occurred
 
     @see oslDirectoryCreationFunc
     @see oslFileError
@@ -1262,25 +1213,24 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_createDirectoryPath(
     @param pustrFileURL [in]
     Full qualified URL of the file to remove.
 
-    @return
-    osl_File_E_None on success<br>
-    osl_File_E_INVAL the format of the parameters was not valid<br>
-    osl_File_E_NOMEM not enough memory for allocating structures <br>
-    osl_File_E_ACCES permission denied<br>
-    osl_File_E_PERM operation not permitted<br>
-    osl_File_E_NAMETOOLONG file name too long<br>
-    osl_File_E_NOENT no such file or directory<br>
-    osl_File_E_ISDIR is a directory<br>
-    osl_File_E_ROFS read-only file system<br>
-    osl_File_E_FAULT bad address<br>
-    osl_File_E_LOOP too many symbolic links encountered<br>
-    osl_File_E_IO on I/O errors<br>
-    osl_File_E_BUSY device or resource busy<br>
-    osl_File_E_INTR function call was interrupted<br>
-    osl_File_E_LOOP too many symbolic links encountered<br>
-    osl_File_E_MULTIHOP multihop attempted<br>
-    osl_File_E_NOLINK link has been severed<br>
-    osl_File_E_TXTBSY text file busy<br>
+    @retval osl_File_E_None on success
+    @retval osl_File_E_INVAL the format of the parameters was not valid
+    @retval osl_File_E_NOMEM not enough memory for allocating structures
+    @retval osl_File_E_ACCES permission denied
+    @retval osl_File_E_PERM operation not permitted
+    @retval osl_File_E_NAMETOOLONG file name too long
+    @retval osl_File_E_NOENT no such file or directory
+    @retval osl_File_E_ISDIR is a directory
+    @retval osl_File_E_ROFS read-only file system
+    @retval osl_File_E_FAULT bad address
+    @retval osl_File_E_LOOP too many symbolic links encountered
+    @retval osl_File_E_IO on I/O errors
+    @retval osl_File_E_BUSY device or resource busy
+    @retval osl_File_E_INTR function call was interrupted
+    @retval osl_File_E_LOOP too many symbolic links encountered
+    @retval osl_File_E_MULTIHOP multihop attempted
+    @retval osl_File_E_NOLINK link has been severed
+    @retval osl_File_E_TXTBSY text file busy
 
     @see osl_openFile()
 */
@@ -1300,17 +1250,16 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_removeFile(
     @param pustrDestFileURL [in]
     Full qualified URL of the destination file. A directory is NOT a valid destination file!
 
-    @return
-    osl_File_E_None on success<br>
-    osl_File_E_INVAL the format of the parameters was not valid<br>
-    osl_File_E_NOMEM not enough memory for allocating structures <br>
-    osl_File_E_ACCES permission denied<br>
-    osl_File_E_PERM operation not permitted<br>
-    osl_File_E_NAMETOOLONG file name too long<br>
-    osl_File_E_NOENT no such file or directory<br>
-    osl_File_E_ISDIR is a directory<br>
-    osl_File_E_ROFS read-only file system<br>
-    osl_File_E_BUSY if the implementation internally requires resources that are
+    @retval osl_File_E_None on success
+    @retval osl_File_E_INVAL the format of the parameters was not valid
+    @retval osl_File_E_NOMEM not enough memory for allocating structures
+    @retval osl_File_E_ACCES permission denied
+    @retval osl_File_E_PERM operation not permitted
+    @retval osl_File_E_NAMETOOLONG file name too long
+    @retval osl_File_E_NOENT no such file or directory
+    @retval osl_File_E_ISDIR is a directory
+    @retval osl_File_E_ROFS read-only file system
+    @retval osl_File_E_BUSY if the implementation internally requires resources that are
         (temporarily) unavailable (added with LibreOffice 4.4)
 
     @see    osl_moveFile()
@@ -1332,16 +1281,15 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_copyFile(
     @param pustrDestFileURL [in]
     Full qualified URL of the destination file. An existing directory is NOT a valid destination !
 
-    @return
-    osl_File_E_None on success<br>
-    osl_File_E_INVAL the format of the parameters was not valid<br>
-    osl_File_E_NOMEM not enough memory for allocating structures <br>
-    osl_File_E_ACCES permission denied<br>
-    osl_File_E_PERM operation not permitted<br>
-    osl_File_E_NAMETOOLONG file name too long<br>
-    osl_File_E_NOENT no such file or directory<br>
-    osl_File_E_ROFS read-only file system<br>
-    osl_File_E_BUSY if the implementation internally requires resources that are
+    @retval osl_File_E_None on success
+    @retval osl_File_E_INVAL the format of the parameters was not valid
+    @retval osl_File_E_NOMEM not enough memory for allocating structures
+    @retval osl_File_E_ACCES permission denied
+    @retval osl_File_E_PERM operation not permitted
+    @retval osl_File_E_NAMETOOLONG file name too long
+    @retval osl_File_E_NOENT no such file or directory
+    @retval osl_File_E_ROFS read-only file system
+    @retval osl_File_E_BUSY if the implementation internally requires resources that are
         (temporarily) unavailable (added with LibreOffice 4.4)
 
     @see osl_copyFile()
@@ -1365,9 +1313,8 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_moveFile(
     On success receives a name which is unused and valid on the actual Operating System and
     File System.
 
-    @return
-    osl_File_E_None on success<br>
-    osl_File_E_INVAL the format of the parameters was not valid<br>
+    @retval osl_File_E_None on success
+    @retval osl_File_E_INVAL the format of the parameters was not valid
 
     @see osl_getFileStatus()
 */
@@ -1393,20 +1340,19 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_getCanonicalName(
     @param ppustrAbsoluteFileURL [out]
     On success it receives the full qualified absolute file URL.
 
-    @return
-    osl_File_E_None on success<br>
-    osl_File_E_INVAL the format of the parameters was not valid<br>
-    osl_File_E_NOMEM not enough memory for allocating structures <br>
-    osl_File_E_NOTDIR not a directory<br>
-    osl_File_E_ACCES permission denied<br>
-    osl_File_E_NOENT no such file or directory<br>
-    osl_File_E_NAMETOOLONG file name too long<br>
-    osl_File_E_OVERFLOW value too large for defined data type<br>
-    osl_File_E_FAULT bad address<br>
-    osl_File_E_INTR function call was interrupted<br>
-    osl_File_E_LOOP too many symbolic links encountered<br>
-    osl_File_E_MULTIHOP multihop attempted<br>
-    osl_File_E_NOLINK link has been severed<br>
+    @retval osl_File_E_None on success
+    @retval osl_File_E_INVAL the format of the parameters was not valid
+    @retval osl_File_E_NOMEM not enough memory for allocating structures
+    @retval osl_File_E_NOTDIR not a directory
+    @retval osl_File_E_ACCES permission denied
+    @retval osl_File_E_NOENT no such file or directory
+    @retval osl_File_E_NAMETOOLONG file name too long
+    @retval osl_File_E_OVERFLOW value too large for defined data type
+    @retval osl_File_E_FAULT bad address
+    @retval osl_File_E_INTR function call was interrupted
+    @retval osl_File_E_LOOP too many symbolic links encountered
+    @retval osl_File_E_MULTIHOP multihop attempted
+    @retval osl_File_E_NOLINK link has been severed
 
     @see    osl_getFileStatus()
 */
@@ -1425,9 +1371,8 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_getAbsoluteFileURL(
     @param ppustrFileURL [out]
     On success it receives the file URL.
 
-    @return
-    osl_File_E_None on success<br>
-    osl_File_E_INVAL the format of the parameters was not valid<br>
+    @retval osl_File_E_None on success
+    @retval osl_File_E_INVAL the format of the parameters was not valid
 
     @see osl_getSystemPathFromFileURL()
 */
@@ -1454,11 +1399,10 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_getFileURLFromSystemPath(
     @param ppustrFileURL [out]
     On success it receives the full qualified file URL.
 
-    @return
-    osl_File_E_None on success<br>
-    osl_File_E_INVAL the format of the parameters was not valid<br>
-    osl_File_E_NOTDIR not a directory<br>
-    osl_File_E_NOENT no such file or directory not found<br>
+    @retval osl_File_E_None on success
+    @retval osl_File_E_INVAL the format of the parameters was not valid
+    @retval osl_File_E_NOTDIR not a directory
+    @retval osl_File_E_NOENT no such file or directory not found
 
     @see osl_getFileURLFromSystemPath()
     @see osl_getSystemPathFromFileURL()
@@ -1476,9 +1420,8 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_searchFileURL(
     @param ppustrSystemPath [out]
     On success it receives the system path.
 
-    @return
-    osl_File_E_None on success
-    osl_File_E_INVAL the format of the parameters was not valid
+    @retval osl_File_E_None on success
+    @retval osl_File_E_INVAL the format of the parameters was not valid
 
     @see osl_getFileURLFromSystemPath()
 */
@@ -1517,8 +1460,7 @@ typedef sal_uInt32 (SAL_CALL *oslCalcTextWidthFunc)( rtl_uString *ustrText );
     Maximum width allowed that is retunrned from pCalcWidth.
     If pCalcWidth is zero the character count is assumed as width.
 
-    @return
-    osl_File_E_None on success<br>
+    @retval osl_File_E_None on success
 
     @see    oslCalcTextWidthFunc
 */
@@ -1538,9 +1480,8 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_abbreviateSystemPath(
     @param uAttributes [in]
     Attributes of the file to be set.
 
-    @return
-    osl_File_E_None on success<br>
-    osl_File_E_INVAL the format of the parameters was not valid<br>
+    @retval osl_File_E_None on success
+    @retval osl_File_E_INVAL the format of the parameters was not valid
 
     @see osl_getFileStatus()
 */
@@ -1563,10 +1504,9 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_setFileAttributes(
     @param aLastWriteTime [in]
     Time of the last modifying of the given file.
 
-    @return
-    osl_File_E_None on success<br>
-    osl_File_E_INVAL the format of the parameters was not valid<br>
-    osl_File_E_NOENT no such file or directory not found<br>
+    @retval osl_File_E_None on success
+    @retval osl_File_E_INVAL the format of the parameters was not valid
+    @retval osl_File_E_NOENT no such file or directory not found
 
     @see osl_getFileStatus()
 */
@@ -1583,9 +1523,8 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_setFileTime(
     @param[out] pustrTempDirURL
     On success receives the URL of system's temporary directory path.
 
-    @return
-    osl_File_E_None on success
-    osl_File_E_NOENT no such file or directory not found
+    @retval osl_File_E_None on success
+    @retval osl_File_E_NOENT no such file or directory not found
 */
 
 SAL_DLLPUBLIC oslFileError SAL_CALL osl_getTempDirURL(
@@ -1629,16 +1568,15 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_getTempDirURL(
     file and is responsible for removing the file, in this case
     *ppustrTempFileURL must be 0 or must point to a valid rtl_uString.
 
-    @return
-    osl_File_E_None   on success
-    osl_File_E_INVAL  the format of the parameter is invalid
-    osl_File_E_NOMEM  not enough memory for allocating structures
-    osl_File_E_ACCES  Permission denied
-    osl_File_E_NOENT  No such file or directory
-    osl_File_E_NOTDIR Not a directory
-    osl_File_E_ROFS   Read-only file system
-    osl_File_E_NOSPC  No space left on device
-    osl_File_E_DQUOT  Quota exceeded
+    @retval osl_File_E_None   on success
+    @retval osl_File_E_INVAL  the format of the parameter is invalid
+    @retval osl_File_E_NOMEM  not enough memory for allocating structures
+    @retval osl_File_E_ACCES  Permission denied
+    @retval osl_File_E_NOENT  No such file or directory
+    @retval osl_File_E_NOTDIR Not a directory
+    @retval osl_File_E_ROFS   Read-only file system
+    @retval osl_File_E_NOSPC  No space left on device
+    @retval osl_File_E_DQUOT  Quota exceeded
 
     @see    osl_getTempDirURL()
 */
diff --git a/include/osl/file.hxx b/include/osl/file.hxx
index 042a1dfc9d49..3db335c2029b 100644
--- a/include/osl/file.hxx
+++ b/include/osl/file.hxx
@@ -120,9 +120,8 @@ public:
         On success receives a name which is unused and valid on the actual Operating System and
         File System.
 
-        @return
-        E_None on success
-        E_INVAL the format of the parameters was not valid
+        @retval E_None on success
+        @retval E_INVAL the format of the parameters was not valid
 
         @see DirectoryItem::getFileStatus()
     */
@@ -149,20 +148,19 @@ public:
         @param ustrAbsoluteFileURL [out]
         On success it receives the full qualified absolute file URL.
 
-        @return
-        E_None on success
-        E_INVAL the format of the parameters was not valid
-        E_NOMEM not enough memory for allocating structures
-        E_NOTDIR not a directory
-        E_ACCES permission denied
-        E_NOENT no such file or directory
-        E_NAMETOOLONG file name too long
-        E_OVERFLOW value too large for defined data type
-        E_FAULT bad address
-        E_INTR function call was interrupted
-        E_LOOP too many symbolic links encountered
-        E_MULTIHOP multihop attempted
-        E_NOLINK link has been severed
+        @retval E_None on success
+        @retval E_INVAL the format of the parameters was not valid
+        @retval E_NOMEM not enough memory for allocating structures
+        @retval E_NOTDIR not a directory
+        @retval E_ACCES permission denied
+        @retval E_NOENT no such file or directory
+        @retval E_NAMETOOLONG file name too long
+        @retval E_OVERFLOW value too large for defined data type
+        @retval E_FAULT bad address
+        @retval E_INTR function call was interrupted
+        @retval E_LOOP too many symbolic links encountered
+        @retval E_MULTIHOP multihop attempted
+        @retval E_NOLINK link has been severed
 
         @see DirectoryItem::getFileStatus()
     */
@@ -180,9 +178,8 @@ public:
         @param ustrSystemPath [out]
         On success it receives the system path.
 
-        @return
-        E_None on success
-        E_INVAL the format of the parameters was not valid
+        @retval E_None on success
+        @retval E_INVAL the format of the parameters was not valid
 
         @see getFileURLFromSystemPath()
     */
@@ -200,9 +197,8 @@ public:
         @param ustrFileURL [out]
         On success it receives the file URL.
 
-        @return
-        E_None on success
-        E_INVAL the format of the parameters was not valid
+        @retval E_None on success
+        @retval E_INVAL the format of the parameters was not valid
 
         @see getSystemPathFromFileURL()
     */
@@ -230,11 +226,10 @@ public:
         @param ustrFileURL [out]
         On success it receives the full qualified file URL.
 
-        @return
-        E_None on success
-        E_INVAL the format of the parameters was not valid
-        E_NOTDIR not a directory
-        E_NOENT no such file or directory not found
+        @retval E_None on success
+        @retval E_INVAL the format of the parameters was not valid
+        @retval E_NOTDIR not a directory
+        @retval E_NOENT no such file or directory not found
 
         @see getFileURLFromSystemPath()
         @see getSystemPathFromFileURL()
@@ -250,9 +245,8 @@ public:
         @param[out] ustrTempDirURL
         On success receives the URL of system's temporary directory path.
 
-        @return
-        E_None on success
-        E_NOENT no such file or directory not found
+        @retval E_None on success
+        @retval E_NOENT no such file or directory not found
     */
 
     static RC getTempDirURL( ::rtl::OUString& ustrTempDirURL )
@@ -294,16 +288,15 @@ public:
         the file name will be returned, the caller is responsible for closing and removing
         the file.<br>
 
-        @return
-        E_None   on success
-        E_INVAL  the format of the parameter is invalid
-        E_NOMEM  not enough memory for allocating structures
-        E_ACCES  Permission denied
-        E_NOENT  No such file or directory
-        E_NOTDIR Not a directory
-        E_ROFS   Read-only file system
-        E_NOSPC  No space left on device
-        E_DQUOT  Quota exceeded
+        @retval E_None   on success
+        @retval E_INVAL  the format of the parameter is invalid
+        @retval E_NOMEM  not enough memory for allocating structures
+        @retval E_ACCES  Permission denied
+        @retval E_NOENT  No such file or directory
+        @retval E_NOTDIR Not a directory
+        @retval E_ROFS   Read-only file system
+        @retval E_NOSPC  No space left on device
+        @retval E_DQUOT  Quota exceeded
 
         @see getTempDirURL()
     */
@@ -384,7 +377,7 @@ public:
 
     /** Get the full qualified URL where a device is mounted to.
 
-           @return
+        @return
         The full qualified URL where the device is mounted to.
     */
     rtl::OUString getMountPath()
@@ -949,32 +942,31 @@ public:
         @param uFlags [in]
         Specifies the open mode.
 
-        @return
-        E_None on success
-        E_NOMEM not enough memory for allocating structures
-        E_INVAL the format of the parameters was not valid
-        E_NAMETOOLONG pathname was too long
-        E_NOENT no such file or directory
-        E_ACCES permission denied
-        E_AGAIN a write lock could not be established
-        E_NOTDIR not a directory
-        E_NXIO no such device or address
-        E_NODEV no such device
-        E_ROFS read-only file system
-        E_TXTBSY text file busy
-        E_FAULT bad address
-        E_LOOP too many symbolic links encountered
-        E_NOSPC no space left on device
-        E_ISDIR is a directory
-        E_MFILE too many open files used by the process
-        E_NFILE too many open files in the system
-        E_DQUOT quota exceeded
-        E_EXIST file exists
-        E_INTR function call was interrupted
-        E_IO on I/O errors
-        E_MULTIHOP multihop attempted
-        E_NOLINK link has been severed
-        E_EOVERFLOW value too large for defined data type
+        @retval E_None on success
+        @retval E_NOMEM not enough memory for allocating structures
+        @retval E_INVAL the format of the parameters was not valid
+        @retval E_NAMETOOLONG pathname was too long
+        @retval E_NOENT no such file or directory
+        @retval E_ACCES permission denied
+        @retval E_AGAIN a write lock could not be established
+        @retval E_NOTDIR not a directory
+        @retval E_NXIO no such device or address
+        @retval E_NODEV no such device
+        @retval E_ROFS read-only file system
+        @retval E_TXTBSY text file busy
+        @retval E_FAULT bad address
+        @retval E_LOOP too many symbolic links encountered
+        @retval E_NOSPC no space left on device
+        @retval E_ISDIR is a directory
+        @retval E_MFILE too many open files used by the process
+        @retval E_NFILE too many open files in the system
+        @retval E_DQUOT quota exceeded
+        @retval E_EXIST file exists
+        @retval E_INTR function call was interrupted
+        @retval E_IO on I/O errors
+        @retval E_MULTIHOP multihop attempted
+        @retval E_NOLINK link has been severed
+        @retval E_EOVERFLOW value too large for defined data type
 
         @see close()
         @see setPos()
@@ -992,14 +984,13 @@ public:
 
     /** Close an open file.
 
-        @return
-        E_None on success
-        E_INVAL the format of the parameters was not valid
-        E_BADF Bad file
-        E_INTR function call was interrupted
-        E_NOLINK link has been severed
-        E_NOSPC no space left on device
-        E_IO on I/O errors
+        @retval E_None on success
+        @retval E_INVAL the format of the parameters was not valid
+        @retval E_BADF Bad file
+        @retval E_INTR function call was interrupted
+        @retval E_NOLINK link has been severed
+        @retval E_NOSPC no space left on device
+        @retval E_IO on I/O errors
 
         @see open()
     */
@@ -1025,10 +1016,9 @@ public:
         @param uPos [in]
         Absolute position from the beginning of the file.
 
-        @return
-        E_None on success
-        E_INVAL the format of the parameters was not valid
-        E_OVERFLOW the resulting file offset would be a value which cannot be represented correctly for regular files
+        @retval E_None on success
+        @retval E_INVAL the format of the parameters was not valid
+        @retval E_OVERFLOW the resulting file offset would be a value which cannot be represented correctly for regular files
 
         @see open()
         @see getPos()
@@ -1044,10 +1034,9 @@ public:
         @param uPos [out]
         On success receives the current position of the file pointer.
 
-        @return
-        E_None on success
-        E_INVAL the format of the parameters was not valid
-        E_OVERFLOW the resulting file offset would be a value which cannot be represented correctly for regular files
+        @retval E_None on success
+        @retval E_INVAL the format of the parameters was not valid
+        @retval E_OVERFLOW the resulting file offset would be a value which cannot be represented correctly for regular files
 
         @see open()
         @see setPos()
@@ -1065,16 +1054,15 @@ public:
         @param pIsEOF [out]
         Points to a variable that receives the end-of-file status.
 
-        @return
-        E_None on success
-        E_INVAL the format of the parameters was not valid
-        E_INTR function call was interrupted
-        E_IO on I/O errors
-        E_ISDIR is a directory
-        E_BADF bad file
-        E_FAULT bad address
-        E_AGAIN operation would block
-        E_NOLINK link has been severed
+        @retval E_None on success
+        @retval E_INVAL the format of the parameters was not valid
+        @retval E_INTR function call was interrupted
+        @retval E_IO on I/O errors
+        @retval E_ISDIR is a directory
+        @retval E_BADF bad file
+        @retval E_FAULT bad address
+        @retval E_AGAIN operation would block
+        @retval E_NOLINK link has been severed
 
         @see open()
         @see read()
@@ -1095,10 +1083,9 @@ public:
         @param uSize [in]
         New size in bytes.
 
-        @return
-        E_None on success
-        E_INVAL the format of the parameters was not valid
-        E_OVERFLOW the resulting file offset would be a value which cannot  be represented correctly for regular files
+        @retval E_None on success
+        @retval E_INVAL the format of the parameters was not valid
+        @retval E_OVERFLOW the resulting file offset would be a value which cannot  be represented correctly for regular files
 
         @see open()
         @see setPos()
@@ -1118,10 +1105,9 @@ public:
         @param rSize [out]
         Current size in bytes.
 
-        @return
-        E_None on success
-        E_INVAL the format of the parameters was not valid
-        E_OVERFLOW the resulting file offset would be a value which cannot  be represented correctly for regular files
+        @retval E_None on success
+        @retval E_INVAL the format of the parameters was not valid
+        @retval E_OVERFLOW the resulting file offset would be a value which cannot  be represented correctly for regular files
 
         @see open()
         @see setPos()
@@ -1150,16 +1136,15 @@ public:
         @param rBytesRead [out]
         On success the number of bytes which have actually been retrieved.
 
-        @return
-        E_None on success
-        E_INVAL the format of the parameters was not valid
-        E_INTR function call was interrupted
-        E_IO on I/O errors
-        E_ISDIR is a directory
-        E_BADF bad file
-        E_FAULT bad address
-        E_AGAIN operation would block
-        E_NOLINK link has been severed
+        @retval E_None on success
+        @retval E_INVAL the format of the parameters was not valid
+        @retval E_INTR function call was interrupted
+        @retval E_IO on I/O errors
+        @retval E_ISDIR is a directory
+        @retval E_BADF bad file
+        @retval E_FAULT bad address
+        @retval E_AGAIN operation would block
+        @retval E_NOLINK link has been severed
 
         @see open()
         @see write()
@@ -1186,20 +1171,19 @@ public:
         @param rBytesWritten [out]
         On success the number of bytes which have actually been written.
 
-        @return
-        E_None on success
-        E_INVAL the format of the parameters was not valid
-        E_FBIG file too large
-        E_DQUOT quota exceeded
-        E_AGAIN operation would block
-        E_BADF bad file
-        E_FAULT bad address
-        E_INTR function call was interrupted
-        E_IO on I/O errosr
-        E_NOLCK no record locks available
-        E_NOLINK link has been severed
-        E_NOSPC no space left on device
-        E_NXIO no such device or address
+        @retval E_None on success
+        @retval E_INVAL the format of the parameters was not valid
+        @retval E_FBIG file too large
+        @retval E_DQUOT quota exceeded
+        @retval E_AGAIN operation would block
+        @retval E_BADF bad file
+        @retval E_FAULT bad address
+        @retval E_INTR function call was interrupted
+        @retval E_IO on I/O errosr
+        @retval E_NOLCK no record locks available
+        @retval E_NOLINK link has been severed
+        @retval E_NOSPC no space left on device
+        @retval E_NXIO no such device or address
 
         @see open()
         @see read()
@@ -1219,16 +1203,15 @@ public:
         @param  aSeq [in/out]
         A reference to a ::rtl::ByteSequence that will hold the line read on success.
 
-        @return
-        E_None on success
-        E_INVAL the format of the parameters was not valid
-        E_INTR function call was interrupted
-        E_IO on I/O errors
-        E_ISDIR is a directory
-        E_BADF bad file
-        E_FAULT bad address
-        E_AGAIN operation would block
-        E_NOLINK link has been severed
+        @retval E_None on success
+        @retval E_INVAL the format of the parameters was not valid
+        @retval E_INTR function call was interrupted
+        @retval E_IO on I/O errors
+        @retval E_ISDIR is a directory
+        @retval E_BADF bad file
+        @retval E_FAULT bad address
+        @retval E_AGAIN operation would block
+        @retval E_NOLINK link has been severed
 
         @see open()
         @see read()
@@ -1243,33 +1226,22 @@ public:
 
     /** Synchronize the memory representation of a file with that on the physical medium.
 
-    The function ensures that all modified data and attributes of the file associated with
-    the given file handle have been written to the physical medium.
-    In case the hard disk has a write cache enabled, the data may not really be on
-    permanent storage when osl_syncFile returns.
-
-    @return
-    <dl>
-    <dt>E_None</dt>
-    <dd>On success</dd>
-    <dt>E_INVAL</dt>
-    <dd>The value of the input parameter is invalid</dd>
-    <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>
-    <dt>E_IO</dt>
-    <dd>An I/O error occurred</dd>
-    <dt>E_NOSPC</dt>
-    <dd>There is no enough space on the target device</dd>
-    <dt>E_ROFS</dt>
-    <dd>The file is located on a read only file system</dd>
-    <dt>E_TIMEDOUT</dt>
-    <dd>A remote connection timed out. This may happen when a file is on a remote location</dd>
-    </dl>
-
-    @see osl_syncFile()
-    @see open()
-    @see write()
+        The function ensures that all modified data and attributes of the file associated with
+        the given file handle have been written to the physical medium.
+        In case the hard disk has a write cache enabled, the data may not really be on
+        permanent storage when osl_syncFile returns.
+
+        @retval E_None On success
+        @retval E_INVAL The value of the input parameter is invalid
+        @retval E_BADF The file is not open for writing
+        @retval E_IO An I/O error occurred
+        @retval E_NOSPC There is no enough space on the target device
+        @retval E_ROFS The file is located on a read only file system
+        @retval E_TIMEDOUT A remote connection timed out. This may happen when a file is on a remote location
+
+        @see osl_syncFile()
+        @see open()
+        @see write()
     */
     RC sync() const
     {
@@ -1288,16 +1260,15 @@ public:
         @param ustrDestFileURL [in]
         Full qualified URL of the destination file. A directory is NOT a valid destination file!
 
-        @return
-        E_None on success
-        E_INVAL the format of the parameters was not valid
-        E_NOMEM not enough memory for allocating structures
-        E_ACCES permission denied
-        E_PERM operation not permitted
-        E_NAMETOOLONG file name too long
-        E_NOENT no such file or directory
-        E_ISDIR is a directory
-        E_ROFS read-only file system
+        @retval E_None on success
+        @retval E_INVAL the format of the parameters was not valid
+        @retval E_NOMEM not enough memory for allocating structures
+        @retval E_ACCES permission denied
+        @retval E_PERM operation not permitted
+        @retval E_NAMETOOLONG file name too long
+        @retval E_NOENT no such file or directory
+        @retval E_ISDIR is a directory
+        @retval E_ROFS read-only file system
 
         @see move()
         @see remove()
@@ -1319,15 +1290,14 @@ public:
         @param ustrDestFileURL [in]
         Full qualified URL of the destination file. An existing directory is NOT a valid destination !
 
-        @return
-        E_None on success
-        E_INVAL the format of the parameters was not valid
-        E_NOMEM not enough memory for allocating structures
-        E_ACCES permission denied
-        E_PERM operation not permitted
-        E_NAMETOOLONG file name too long
-        E_NOENT no such file or directory
-        E_ROFS read-only file system
+        @retval E_None on success
+        @retval E_INVAL the format of the parameters was not valid
+        @retval E_NOMEM not enough memory for allocating structures
+        @retval E_ACCES permission denied
+        @retval E_PERM operation not permitted
+        @retval E_NAMETOOLONG file name too long
+        @retval E_NOENT no such file or directory
+        @retval E_ROFS read-only file system
 
         @see copy()
     */
@@ -1342,25 +1312,24 @@ public:
         @param ustrFileURL [in]
         Full qualified URL of the file to remove.
 
-        @return
-        E_None on success
-        E_INVAL the format of the parameters was not valid
-        E_NOMEM not enough memory for allocating structures
-        E_ACCES permission denied
-        E_PERM operation not permitted
-        E_NAMETOOLONG file name too long
-        E_NOENT no such file or directory
-        E_ISDIR is a directory
-        E_ROFS read-only file system
-        E_FAULT bad address
-        E_LOOP too many symbolic links encountered
-        E_IO on I/O errors
-        E_BUSY device or resource busy
-        E_INTR function call was interrupted
-        E_LOOP too many symbolic links encountered
-        E_MULTIHOP multihop attempted
-        E_NOLINK link has been severed
-        E_TXTBSY text file busy
+        @retval E_None on success
+        @retval E_INVAL the format of the parameters was not valid
+        @retval E_NOMEM not enough memory for allocating structures
+        @retval E_ACCES permission denied
+        @retval E_PERM operation not permitted
+        @retval E_NAMETOOLONG file name too long
+        @retval E_NOENT no such file or directory
+        @retval E_ISDIR is a directory
+        @retval E_ROFS read-only file system
+        @retval E_FAULT bad address
+        @retval E_LOOP too many symbolic links encountered
+        @retval E_IO on I/O errors
+        @retval E_BUSY device or resource busy
+        @retval E_INTR function call was interrupted
+        @retval E_LOOP too many symbolic links encountered
+        @retval E_MULTIHOP multihop attempted
+        @retval E_NOLINK link has been severed
+        @retval E_TXTBSY text file busy
 
         @see open()
     */
@@ -1379,8 +1348,8 @@ public:
         Attributes of the file to be set.
 
         @return
-        E_None on success
-        E_INVAL the format of the parameters was not valid
+        @retval E_None on success
+        @retval E_INVAL the format of the parameters was not valid
 
         @see FileStatus
     */
@@ -1404,10 +1373,9 @@ public:
         @param rLastWriteTime [in]
         Time of the last modifying of the given file.
 
-        @return
-        E_None on success
-        E_INVAL the format of the parameters was not valid
-        E_NOENT no such file or directory not found
+        @retval E_None on success
+        @retval E_INVAL the format of the parameters was not valid
+        @retval E_NOENT no such file or directory not found
 
         @see FileStatus
     */
@@ -1507,22 +1475,21 @@ public:
         On success it receives a handle which can be used for subsequent calls to osl_getFileStatus().
         The handle has to be released by a call to osl_releaseDirectoryItem().
 
-        @return
-        E_None on success
-        E_INVAL the format of the parameters was not valid
-        E_NOMEM not enough memory for allocating structures
-        E_ACCES permission denied
-        E_MFILE too many open files used by the process
-        E_NFILE too many open files in the system
-        E_NOENT no such file or directory
-        E_LOOP  too many symbolic links encountered
-        E_NAMETOOLONG the file name is too long
-        E_NOTDIR a component of the path prefix of path is not a directory
-        E_IO on I/O errors
-        E_MULTIHOP multihop attempted
-        E_NOLINK link has been severed
-        E_FAULT bad address
-        E_INTR the function call was interrupted
+        @retval E_None on success
+        @retval E_INVAL the format of the parameters was not valid
+        @retval E_NOMEM not enough memory for allocating structures
+        @retval E_ACCES permission denied
+        @retval E_MFILE too many open files used by the process
+        @retval E_NFILE too many open files in the system
+        @retval E_NOENT no such file or directory
+        @retval E_LOOP  too many symbolic links encountered
+        @retval E_NAMETOOLONG the file name is too long
+        @retval E_NOTDIR a component of the path prefix of path is not a directory
+        @retval E_IO on I/O errors
+        @retval E_MULTIHOP multihop attempted
+        @retval E_NOLINK link has been severed
+        @retval E_FAULT bad address
+        @retval E_INTR the function call was interrupted
 
         @see FileStatus
         @see Directory::getNextItem()
@@ -1545,26 +1512,25 @@ public:
         Reference to a class which receives the information of the file or directory
         represented by this directory item.
 
-        @return
-        E_None on success
-        E_NOMEM not enough memory for allocating structures
-        E_INVAL the format of the parameters was not valid
-        E_LOOP too many symbolic links encountered
-        E_ACCES permission denied
-        E_NOENT no such file or directory
-        E_NAMETOOLONG file name too long
-        E_BADF invalid oslDirectoryItem parameter
-        E_FAULT bad address
-        E_OVERFLOW value too large for defined data type
-        E_INTR function call was interrupted
-        E_NOLINK link has been severed
-        E_MULTIHOP components of path require hopping to multiple remote machines and the file system does not allow it
-        E_MFILE too many open files used by the process
-        E_NFILE too many open files in the system
-        E_NOSPC no space left on device
-        E_NXIO no such device or address
-        E_IO on I/O errors
-        E_NOSYS function not implemented
+        @retval E_None on success
+        @retval E_NOMEM not enough memory for allocating structures
+        @retval E_INVAL the format of the parameters was not valid
+        @retval E_LOOP too many symbolic links encountered
+        @retval E_ACCES permission denied
+        @retval E_NOENT no such file or directory
+        @retval E_NAMETOOLONG file name too long
+        @retval E_BADF invalid oslDirectoryItem parameter
+        @retval E_FAULT bad address
+        @retval E_OVERFLOW value too large for defined data type
+        @retval E_INTR function call was interrupted
+        @retval E_NOLINK link has been severed
+        @retval E_MULTIHOP components of path require hopping to multiple remote machines and the file system does not allow it
+        @retval E_MFILE too many open files used by the process
+        @retval E_NFILE too many open files in the system
+        @retval E_NOSPC no space left on device
+        @retval E_NXIO no such device or address
+        @retval E_IO on I/O errors
+        @retval E_NOSYS function not implemented
 
         @see get()
         @see Directory::getNextItem()
@@ -1584,9 +1550,8 @@ public:
     @param[in]  pOther
     A directory handle to compare with the underlying object's item
 
-    @return
-    true: if the items point to an identical resource<br>
-    false: if the items point to a different resource, or a fatal error occurred<br>
+    @retval true if the items point to an identical resource<br>
+    @retval false if the items point to a different resource, or a fatal error occurred<br>
 
     @see osl_getDirectoryItem()
 
@@ -1689,17 +1654,16 @@ public:
 
     /** Open a directory for enumerating its contents.
 
-        @return
-        E_None on success
-        E_INVAL the format of the parameters was not valid
-        E_NOENT the specified path doesn't exist
-        E_NOTDIR the specified path is not an directory
-        E_NOMEM not enough memory for allocating structures
-        E_ACCES permission denied
-        E_MFILE too many open files used by the process
-        E_NFILE too many open files in the system
-        E_NAMETOOLONG File name too long
-        E_LOOP Too many symbolic links encountered
+        @retval E_None on success
+        @retval E_INVAL the format of the parameters was not valid
+        @retval E_NOENT the specified path doesn't exist
+        @retval E_NOTDIR the specified path is not an directory
+        @retval E_NOMEM not enough memory for allocating structures
+        @retval E_ACCES permission denied
+        @retval E_MFILE too many open files used by the process
+        @retval E_NFILE too many open files in the system
+        @retval E_NAMETOOLONG File name too long
+        @retval E_LOOP Too many symbolic links encountered
 
         @see getNextItem()
         @see close()
@@ -1714,8 +1678,7 @@ public:
 
         Query if directory is open and so item enumeration is valid.
 
-        @return
-        true if the directory is open else false.
+        @retval true if the directory is open else false.
 
         @see open()
         @see close()
@@ -1725,12 +1688,11 @@ public:
 
     /** Close a directory.
 
-         @return
-        E_None on success
-        E_INVAL the format of the parameters was not valid
-        E_NOMEM not enough memory for allocating structures
-        E_BADF invalid oslDirectory parameter
-        E_INTR the function call was interrupted
+        @retval E_None on success
+        @retval E_INVAL the format of the parameters was not valid
+        @retval E_NOMEM not enough memory for allocating structures
+        @retval E_BADF invalid oslDirectory parameter
+        @retval E_INTR the function call was interrupted
 
         @see open()
     */
@@ -1751,17 +1713,16 @@ public:
 
     /** Resets the directory item enumeration to the beginning.
 
-        @return
-        E_None on success
-        E_INVAL the format of the parameters was not valid
-        E_NOENT the specified path doesn't exist
-        E_NOTDIR the specified path is not an directory
-        E_NOMEM not enough memory for allocating structures
-        E_ACCES permission denied
-        E_MFILE too many open files used by the process
-        E_NFILE too many open files in the system
-        E_NAMETOOLONG File name too long
-        E_LOOP Too many symbolic links encountered
+        @retval E_None on success
+        @retval E_INVAL the format of the parameters was not valid
+        @retval E_NOENT the specified path doesn't exist
+        @retval E_NOTDIR the specified path is not an directory
+        @retval E_NOMEM not enough memory for allocating structures
+        @retval E_ACCES permission denied
+        @retval E_MFILE too many open files used by the process
+        @retval E_NFILE too many open files in the system
+        @retval E_NAMETOOLONG File name too long
+        @retval E_LOOP Too many symbolic links encountered
 
         @see open()
     */
@@ -1784,13 +1745,12 @@ public:
         is going to call this function uHint times afterwards. This enables the implementation to
         get the information for more than one file and cache it until the next calls.
 
-        @return
-        E_None on success
-        E_INVAL the format of the parameters was not valid
-        E_NOMEM not enough memory for allocating structures
-        E_NOENT no more entries in this directory
-        E_BADF invalid oslDirectory parameter
-        E_OVERFLOW the value too large for defined data type
+        @retval E_None on success
+        @retval E_INVAL the format of the parameters was not valid
+        @retval E_NOMEM not enough memory for allocating structures
+        @retval E_NOENT no more entries in this directory
+        @retval E_BADF invalid oslDirectory parameter
+        @retval E_OVERFLOW the value too large for defined data type
 
         @see DirectoryItem
     */
@@ -1817,21 +1777,20 @@ public:
         @param rInfo [out]
         On success it receives information about the volume.
 
-        @return
-        E_None on success
-        E_NOMEM not enough memory for allocating structures
-        E_INVAL the format of the parameters was not valid
-        E_NOTDIR not a directory
-        E_NAMETOOLONG file name too long
-        E_NOENT no such file or directory
-        E_ACCES permission denied
-        E_LOOP too many symbolic links encountered
-        E_FAULT Bad address
-        E_IO on I/O errors
-        E_NOSYS function not implemented
-        E_MULTIHOP multihop attempted
-        E_NOLINK link has been severed
-        E_INTR function call was interrupted
+        @retval E_None on success
+        @retval E_NOMEM not enough memory for allocating structures
+        @retval E_INVAL the format of the parameters was not valid
+        @retval E_NOTDIR not a directory
+        @retval E_NAMETOOLONG file name too long
+        @retval E_NOENT no such file or directory
+        @retval E_ACCES permission denied
+        @retval E_LOOP too many symbolic links encountered
+        @retval E_FAULT Bad address
+        @retval E_IO on I/O errors
+        @retval E_NOSYS function not implemented
+        @retval E_MULTIHOP multihop attempted
+        @retval E_NOLINK link has been severed
+        @retval E_INTR function call was interrupted
 
         @see FileStatus
         @see VolumeInfo
@@ -1851,24 +1810,23 @@ public:
         Optional flags, see osl_createDirectoryWithFlags for details.  This
         defaulted parameter is new since LibreOffice 4.3.
 
-        @return
-        E_None on success
-        E_INVAL the format of the parameters was not valid
-        E_NOMEM not enough memory for allocating structures
-        E_EXIST file exists
-        E_ACCES permission denied
-        E_NAMETOOLONG file name too long
-        E_NOENT no such file or directory
-        E_NOTDIR not a directory
-        E_ROFS read-only file system
-        E_NOSPC no space left on device
-        E_DQUOT quota exceeded
-        E_LOOP too many symbolic links encountered
-        E_FAULT bad address
-        E_IO on I/O errors
-        E_MLINK too many links
-        E_MULTIHOP multihop attempted
-        E_NOLINK link has been severed
+        @retval E_None on success
+        @retval E_INVAL the format of the parameters was not valid
+        @retval E_NOMEM not enough memory for allocating structures
+        @retval E_EXIST file exists
+        @retval E_ACCES permission denied
+        @retval E_NAMETOOLONG file name too long
+        @retval E_NOENT no such file or directory
+        @retval E_NOTDIR not a directory
+        @retval E_ROFS read-only file system
+        @retval E_NOSPC no space left on device
+        @retval E_DQUOT quota exceeded
+        @retval E_LOOP too many symbolic links encountered
+        @retval E_FAULT bad address
+        @retval E_IO on I/O errors
+        @retval E_MLINK too many links
+        @retval E_MULTIHOP multihop attempted
+        @retval E_NOLINK link has been severed
 
         @see remove()
     */
@@ -1886,25 +1844,24 @@ public:
         @param ustrDirectoryURL [in]
         Full qualified URL of the directory.
 
-        @return
-        E_None on success
-        E_INVAL the format of the parameters was not valid
-        E_NOMEM not enough memory for allocating structures
-        E_PERM operation not permitted
-        E_ACCES permission denied
-        E_NOENT no such file or directory
-        E_NOTDIR not a directory
-        E_NOTEMPTY directory not empty
-        E_FAULT bad address
-        E_NAMETOOLONG file name too long
-        E_BUSY device or resource busy
-        E_ROFS read-only file system
-        E_LOOP too many symbolic links encountered
-        E_BUSY device or resource busy
-        E_EXIST file exists
-        E_IO on I/O errors
-        E_MULTIHOP multihop attempted
-        E_NOLINK link has been severed
+        @retval E_None on success
+        @retval E_INVAL the format of the parameters was not valid
+        @retval E_NOMEM not enough memory for allocating structures
+        @retval E_PERM operation not permitted
+        @retval E_ACCES permission denied
+        @retval E_NOENT no such file or directory
+        @retval E_NOTDIR not a directory
+        @retval E_NOTEMPTY directory not empty
+        @retval E_FAULT bad address
+        @retval E_NAMETOOLONG file name too long
+        @retval E_BUSY device or resource busy
+        @retval E_ROFS read-only file system
+        @retval E_LOOP too many symbolic links encountered
+        @retval E_BUSY device or resource busy
+        @retval E_EXIST file exists
+        @retval E_IO on I/O errors
+        @retval E_MULTIHOP multihop attempted
+        @retval E_NOLINK link has been severed
 
         @see create()
     */
@@ -1918,9 +1875,10 @@ public:
 
         The osl_createDirectoryPath function creates a specified directory path.
         All nonexisting sub directories will be created.
-        <p><strong>PLEASE NOTE:</strong> You cannot rely on getting the error code
-        E_EXIST for existing directories. Programming against this error code is
-        in general a strong indication of a wrong usage of osl_createDirectoryPath.</p>
+
+        @attention You cannot rely on getting the error code E_EXIST for existing
+        directories. Programming against this error code is in general a strong
+        indication of a wrong usage of osl_createDirectoryPath.
 
         @param aDirectoryUrl
         [in] The absolute file URL of the directory path to create.
@@ -1931,37 +1889,20 @@ public:
         be informed about the creation of a directory. The value of this
         parameter may be NULL, in this case notifications will not be sent.
 
-        @return
-        <dl>
-        <dt>E_None</dt>
-        <dd>On success</dd>
-        <dt>E_INVAL</dt>
-        <dd>The format of the parameters was not valid</dd>
-        <dt>E_ACCES</dt>
-        <dd>Permission denied</dd>
-        <dt>E_EXIST</dt>
-        <dd>The final node of the specified directory path already exist</dd>
-        <dt>E_NAMETOOLONG</dt>
-        <dd>The name of the specified directory path exceeds the maximum allowed length</dd>
-        <dt>E_NOTDIR</dt>
-        <dd>A component of the specified directory path already exist as file in any part of the directory path</dd>
-        <dt>E_ROFS</dt>
-        <dd>Read-only file system</dd>
-        <dt>E_NOSPC</dt>
-        <dd>No space left on device</dd>
-        <dt>E_DQUOT</dt>
-        <dd>Quota exceeded</dd>
-        <dt>E_FAULT</dt>
-        <dd>Bad address</dd>
-        <dt>E_IO</dt>
-        <dd>I/O error</dd>
-        <dt>E_LOOP</dt>
-        <dd>Too many symbolic links encountered</dd>
-        <dt>E_NOLINK</dt>
-        <dd>Link has been severed</dd>
-        <dt>E_invalidError</dt>
-        <dd>An unknown error occurred</dd>
-        </dl>
+        @retval E_None On success
+        @retval E_INVAL The format of the parameters was not valid
+        @retval E_ACCES Permission denied
+        @retval E_EXIST The final node of the specified directory path already exist
+        @retval E_NAMETOOLONG The name of the specified directory path exceeds the maximum allowed length
+        @retval E_NOTDIR A component of the specified directory path already exist as file in any part of the directory path
+        @retval E_ROFS Read-only file system
+        @retval E_NOSPC No space left on device
+        @retval E_DQUOT Quota exceeded
+        @retval E_FAULT Bad address
+        @retval E_IO I/O error
+        @retval E_LOOP Too many symbolic links encountered
+        @retval E_NOLINK Link has been severed
+        @retval E_invalidError An unknown error occurred
 
         @see DirectoryCreationObserver
         @see create
diff --git a/include/osl/module.h b/include/osl/module.h
index b89c57115e02..fadd573dc0cd 100644
--- a/include/osl/module.h
+++ b/include/osl/module.h
@@ -137,9 +137,8 @@ SAL_DLLPUBLIC oslModule SAL_CALL osl_loadModuleRelativeAscii(
     [out] a pointer to a oslModule that is updated with the requested module handle
     on success.
 
-    @return
-    sal_True if the module handle could be retrieved and has been copied to *pResult.
-    sal_False if the module has not been loaded yet.
+    @retval sal_True if the module handle could be retrieved and has been copied to *pResult.
+    @retval sal_False if the module has not been loaded yet.
 
     @see osl_getFunctionSymbol
     @see osl_getAsciiFunctionSymbol
@@ -170,13 +169,8 @@ SAL_DLLPUBLIC void* SAL_CALL osl_getSymbol( oslModule Module, rtl_uString *strSy
     @param ustrFunctionSymbolName
     [in] Name of the function that will be looked up.
 
-    @return
-    <dl>
-    <dt>Function address.</dt>
-    <dd>on success</dd>
-    <dt>NULL</dt>
-    <dd>lookup failed or the parameter are invalid.</dd>
-    </dl>
+    @retval function-address on success
+    @retval NULL lookup failed or the parameter are invalid
 
     @see osl_getSymbol
     @see osl_getAsciiFunctionSymbol
@@ -195,13 +189,8 @@ SAL_DLLPUBLIC oslGenericFunction SAL_CALL osl_getFunctionSymbol(
     @param pSymbol
     [in] Name of the function that will be looked up.
 
-    @return
-    <dl>
-    <dt>Function address.</dt>
-    <dd>on success</dd>
-    <dt>NULL</dt>
-    <dd>lookup failed or the parameter are invalid.</dd>
-    </dl>
+    @retval function-address on success
+    @retval NULL lookup failed or the parameter are invalid
 
     @see osl_getModuleHandle
     @see osl_getFunctionSymbol
@@ -229,13 +218,8 @@ SAL_DLLPUBLIC sal_Bool SAL_CALL osl_getModuleURLFromAddress(
     @param pustrFunctionURL
     [out] receives the URL of the module that is mapped at pf.
 
-    @return
-    <dl>
-    <dt>sal_True</dt>
-    <dd>on success</dd>
-    <dt>sal_False</dt>
-    <dd>no module can be found at the specified function address or parameter is somewhat invalid.</dd>
-    </dl>
+    @retval sal_True on success
+    @retval sal_False no module can be found at the specified function address or parameter is somewhat invalid
 
     @see osl_getModuleURLFromAddress
 */
diff --git a/include/osl/module.hxx b/include/osl/module.hxx
index 0cf9e64b3c09..cad8b587fd8f 100644
--- a/include/osl/module.hxx
+++ b/include/osl/module.hxx
@@ -51,13 +51,8 @@ public:
         @param libraryUrl
         [in|out] receives the URL of the module.
 
-        @return
-        <dl>
-        <dt>true</dt>
-        <dd>on success</dd>
-        <dt>false</dt>
-        <dd>can not get the URL from the specified function address or the parameter is invalid.</dd>
-        </dl>
+        @retval true on success
+        @retval false can not get the URL from the specified function address or the parameter is invalid.
 
         @see getUrlFromAddress
     */
@@ -142,13 +137,8 @@ public:
         @param ustrFunctionSymbolName
         [in] Function name to be looked up.
 
-        @return
-        <dl>
-        <dt>oslGenericFunction format function address</dt>
-        <dd>on success</dd>
-        <dt>NULL</dt>
-        <dd>lookup failed or parameter is somewhat invalid</dd>
-        </dl>
+        @retval oslGenericFunction format function address on success
+        @retval NULL lookup failed or parameter is somewhat invalid
 
         @see getSymbol
     */
diff --git a/include/osl/mutex.h b/include/osl/mutex.h
index 03c78b117f53..6cbfba15f026 100644
--- a/include/osl/mutex.h
+++ b/include/osl/mutex.h
@@ -44,19 +44,19 @@ SAL_DLLPUBLIC void SAL_CALL osl_destroyMutex(oslMutex Mutex);
 
 /** Acquire the mutex, block if already acquired by another thread.
     @param Mutex handle to a created mutex.
-    @return False if system-call fails.
+    @retval False if system-call fails.
 */
 SAL_DLLPUBLIC sal_Bool SAL_CALL osl_acquireMutex(oslMutex Mutex);
 
 /** Try to acquire the mutex without blocking.
     @param Mutex handle to a created mutex.
-    @return False if it could not be acquired.
+    @retval False if it could not be acquired.
 */
 SAL_DLLPUBLIC sal_Bool SAL_CALL osl_tryToAcquireMutex(oslMutex Mutex);
 
 /** Release the mutex.
     @param Mutex handle to a created mutex.
-    @return False if system-call fails.
+    @retval False if system-call fails.
 */
 SAL_DLLPUBLIC sal_Bool SAL_CALL osl_releaseMutex(oslMutex Mutex);
 
diff --git a/include/osl/process.h b/include/osl/process.h
index 517e2eb79ef2..ee7b401703fa 100644
--- a/include/osl/process.h
+++ b/include/osl/process.h
@@ -140,17 +140,10 @@ typedef void* oslProcess;
     [out] Pointer to a oslProcess variable, which receives the handle of the newly created process.
     This parameter must not be NULL.
 
-    @return
-    <dl>
-    <dt>osl_Process_E_None</dt>
-    <dd>on success</dd>
-    <dt>osl_Process_E_NotFound</dt>
-    <dd>if the specified executable could not be found</dd>
-    <dt>osl_Process_E_InvalidError</dt>
-    <dd>if invalid parameters will be detected</dd>
-    <dt>osl_Process_E_Unknown</dt>
-    <dd>if arbitrary other errors occur</dd>
-    </dl>
+    @retval osl_Process_E_None on success
+    @retval osl_Process_E_NotFound if the specified executable could not be found</dd>
+    @retval osl_Process_E_InvalidError if invalid parameters will be detected</dd>
+    @retval osl_Process_E_Unknown if arbitrary other errors occur</dd>
 
     @see oslProcessOption
     @see osl_executeProcess_WithRedirectedIO
@@ -225,17 +218,10 @@ SAL_DLLPUBLIC oslProcessError SAL_CALL osl_executeProcess(
     the child process standard error device. The returned handle is not random accessible.
     The Handle has to be closed with osl_closeFile if no longer used. This parameter can be NULL.
 
-    @return
-    <dl>
-    <dt>osl_Process_E_None</dt>
-    <dd>on success</dd>
-    <dt>osl_Process_E_NotFound</dt>
-    <dd>if the specified executable could not be found</dd>
-    <dt>osl_Process_E_InvalidError</dt>
-    <dd>if invalid parameters will be detected</dd>
-    <dt>osl_Process_E_Unknown</dt>
-    <dd>if arbitrary other errors occur</dd>
-    </dl>
+    @retval osl_Process_E_None on success
+    @retval osl_Process_E_NotFound if the specified executable could not be found
+    @retval osl_Process_E_InvalidError if invalid parameters will be detected
+    @retval osl_Process_E_Unknown if arbitrary other errors occur
 
     @see oslProcessOption
     @see osl_executeProcess
@@ -287,7 +273,7 @@ SAL_DLLPUBLIC void SAL_CALL osl_freeProcessHandle(
 
 /** Wait for completion of the specified childprocess.
     @param Process [in]
-    @return ols_Process_E_None
+    @retval ols_Process_E_None
     @see osl_executeProcess
 */
 SAL_DLLPUBLIC oslProcessError SAL_CALL osl_joinProcess(
@@ -303,10 +289,9 @@ SAL_DLLPUBLIC oslProcessError SAL_CALL osl_joinProcess(
     A timeout value or NULL for infinite waiting.
     The unit of resolution is second.
 
-    @return
-    osl_Process_E_None on success
-    osl_Process_E_TimedOut waiting for the child process timed out
-    osl_Process_E_Unknown an error occurred or the parameter are invalid
+    @retval osl_Process_E_None on success
+    @retval osl_Process_E_TimedOut waiting for the child process timed out
+    @retval osl_Process_E_Unknown an error occurred or the parameter are invalid
 
     @see osl_executeProcess
 */
@@ -326,7 +311,8 @@ SAL_DLLPUBLIC oslProcessError SAL_CALL osl_joinProcessWithTimeout(
                         of the oslProcessInfo structure.
                         on success the Field member holds the (or'ed)
                         retrieved valid information fields.
-    @return osl_Process_E_None on success, osl_Process_E_Unknown on failure.
+    @retval osl_Process_E_None on success
+    @retval osl_Process_E_Unknown on failure
  */
 SAL_DLLPUBLIC oslProcessError SAL_CALL osl_getProcessInfo(
         oslProcess Process, oslProcessData Fields, oslProcessInfo* pInfo);
diff --git a/include/osl/profile.h b/include/osl/profile.h
index fe0358260c9d..e8584ec85b85 100644
--- a/include/osl/profile.h
+++ b/include/osl/profile.h
@@ -43,7 +43,7 @@ typedef void* oslProfile;
 
 /** Deprecated API.
     Open or create a configuration profile.
-    @return 0 if the profile could not be created, otherwise a handle to the profile.
+    @retval 0 if the profile could not be created, otherwise a handle to the profile.
     @deprecated
 */
 SAL_DLLPUBLIC oslProfile SAL_CALL osl_openProfile(
@@ -112,7 +112,7 @@ SAL_DLLPUBLIC sal_Bool SAL_CALL osl_writeProfileIdent(
 
 /** Deprecated API.
     Acquire the mutex, block if already acquired by another thread.
-    @return False if section or entry could not be found.
+    @retval False if section or entry could not be found.
     @deprecated
 */
 SAL_DLLPUBLIC sal_Bool SAL_CALL osl_removeProfileEntry(
@@ -121,7 +121,7 @@ SAL_DLLPUBLIC sal_Bool SAL_CALL osl_removeProfileEntry(
 
 /** Deprecated API.
     Get all entries belonging to the specified section.
-    @return Pointer to a array of pointers.
+    @returns Pointer to a array of pointers.
     @deprecated
 */
 SAL_DLLPUBLIC sal_uInt32 SAL_CALL osl_getProfileSectionEntries(
@@ -130,7 +130,7 @@ SAL_DLLPUBLIC sal_uInt32 SAL_CALL osl_getProfileSectionEntries(
 
 /** Deprecated API.
     Get all section entries
-    @return Pointer to a array of pointers.
+    @retval Pointer to a array of pointers.
     @deprecated
 */
 SAL_DLLPUBLIC sal_uInt32 SAL_CALL osl_getProfileSections(
diff --git a/include/osl/profile.hxx b/include/osl/profile.hxx
index 661efe2b38c0..a95967d4abdf 100644
--- a/include/osl/profile.hxx
+++ b/include/osl/profile.hxx
@@ -44,7 +44,7 @@ namespace osl {
 
     public:
         /** Open or create a configuration profile.
-            @return 0 if the profile could not be created, otherwise a handle to the profile.
+            @retval 0 if the profile could not be created, otherwise a handle to the profile.
         */
         Profile(const rtl::OUString & strProfileName, oslProfileOption Options = Profile_DEFAULT )
         {
@@ -138,7 +138,7 @@ namespace osl {
         /** Remove an entry from a section.
             @param rSection Name of the section.
             @param rEntry Name of the entry to remove.
-            @return False if section or entry could not be found.
+            @retval False if section or entry could not be found.
         */
         bool removeEntry(const rtl::OString& rSection, const rtl::OString& rEntry)
         {
diff --git a/include/osl/security_decl.hxx b/include/osl/security_decl.hxx
index a809f06698bd..e03474e5a8a2 100644
--- a/include/osl/security_decl.hxx
+++ b/include/osl/security_decl.hxx
@@ -26,7 +26,7 @@
 namespace osl
 {
 
-/** capsulate security information for one user.
+/** Encapsulate security information for one user.
     A object of this class is used to execute a process with the rights an
     security options of a scecified user.
     @see Process::executeProcess
@@ -45,8 +45,8 @@ public:
         The underlying operating system is asked for this information.
         @param[in] strName denotes the name of the user
         @param[in] strPasswd denotes the password of this user
-        @return True, if the specified user is known by the underlying operating system,
-        otherwise False
+        @retval True, if the specified user is known by the underlying operating system
+        @retval False unknown user
     */
     inline bool SAL_CALL logonUser(const rtl::OUString& strName,
                                        const rtl::OUString& strPasswd);
@@ -61,8 +61,10 @@ public:
         @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
+
+        @retval True if the specified user is known by the file server and they
+        could be connected
+        @retval False if the user is not known by the file server
     */
     inline bool SAL_CALL logonUser(const rtl::OUString & strName,
                                        const rtl::OUString & strPasswd,
@@ -70,7 +72,9 @@ public:
 
     /** get the ident of the logged in user.
         @param[out] strIdent is the OUString which returns the name
-        @return True, if any user is successfully logged in, otherwise False
+
+        @retval True if any user is successfully logged in
+        @retval False no user logged in
     */
     inline bool  SAL_CALL getUserIdent( rtl::OUString& strIdent) const;
 
@@ -78,24 +82,31 @@ public:
         @param[out] strName is the OUString which returns the name
         @param[in] bIncludeDomain Include the Domain name (like "ORG\username"). Affects Windows only.
                                   This parameter is available since LibreOffice 5.2.
-        @return True, if any user is successfully logged in, otherwise False
+
+        @retval True if any user is successfully logged in
+        @retval False if no user is logged in
     */
     inline bool SAL_CALL getUserName( rtl::OUString& strName, bool bIncludeDomain=true ) const;
 
     /** get the home directory of the logged in user.
         @param[out] strDirectory is the OUString which returns the directory name
-         @return True, if any user is successfully logged in, otherwise False
+
+        @retval True if any user is successfully logged in
+        @retval False if user is not logged in
     */
     inline bool SAL_CALL getHomeDir( rtl::OUString& strDirectory) const;
 
     /** get the directory for configuration data of the logged in user.
         @param[out] strDirectory is the OUString which returns the directory name
-        @return True, if any user is successfully logged in, otherwise False
+
+        @retval True if any user is successfully logged in
+        @retval False if user is not logged in
     */
     inline bool SAL_CALL getConfigDir( rtl::OUString & strDirectory) const;
 
     /** Query if the user who is logged in has administrator rights.
-        @return True, if the user has administrator rights, otherwise false.
+        @retval True if the user has administrator rights
+        @retval False if the user does not have admin rights
     */
     inline bool SAL_CALL isAdministrator() const;
 
diff --git a/include/osl/signal.h b/include/osl/signal.h
index 96425342773b..a2efece30d05 100644
--- a/include/osl/signal.h
+++ b/include/osl/signal.h
@@ -93,9 +93,8 @@ SAL_DLLPUBLIC oslSignalAction SAL_CALL osl_raiseSignal(
     @param  bEnable [in]
     Enables or disables error reporting.
 
-    @return
-    sal_True if previous state of error reporting was enabled<br>
-    sal_False if previous state of error reporting was disabled<br>
+    @retval sal_True if previous state of error reporting was enabled
+    @retval sal_False if previous state of error reporting was disabled
 */
 
 SAL_DLLPUBLIC sal_Bool SAL_CALL osl_setErrorReporting(