osl: use doxygen @retval and remove HTML markup

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

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);
 

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
 

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
 */

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
     */

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);
 

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);

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(

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)
         {

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;
 

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(