osl: variety of doxygen fixes

Change-Id: I48e4bcce447a1efdb37d6dca9e5808ec8d73492b

include/osl/conditn.hxx

@@ -104,6 +104,13 @@ namespace osl
 
         /** Blocks the calling thread until condition is set.
 
+            @param [in] pTimeout Timeout to wait before ending the condition.
+                Defaults to NULL
+
+            @retval result_ok       finished successfully
+            @retval result_error    error occurred
+            @retval result_timeout  timed out
+
             @deprecated use C++11's std::condition_variable instead
                 for a more robust and helpful condition.
         */
@@ -118,6 +125,9 @@ namespace osl
 
         /** Checks if the condition is set without blocking.
 
+            @retval true   condition is set
+            @retval false  condition is not set
+
             @deprecated use C++11's std::condition_variable instead
                 for a more robust and helpful condition.
         */
@@ -128,9 +138,11 @@ namespace osl
 
 
     private:
-        oslCondition condition;
+        oslCondition condition;     /*< condition variable */
+
+        /** Copy constructor
 
-        /** The underlying oslCondition has no reference count.
+            The underlying oslCondition has no reference count.
 
             Since the underlying oslCondition is not a reference counted
             object, copy constructed Condition may work on an already
@@ -139,7 +151,7 @@ namespace osl
             @deprecated use C++11's std::condition_variable instead
                 for a more robust and helpful condition.
         */
-        Condition(const Condition&) SAL_DELETED_FUNCTION;
+        Condition(const Condition& condition) SAL_DELETED_FUNCTION;
 
         /** This assignment operator is deleted for the same reason as
             the copy constructor.

include/osl/diagnose.h

@@ -27,8 +27,9 @@
 #include <sal/saldllapi.h>
 #include <sal/types.h>
 
-/** provides simple diagnostic support
+/** @file Provides simple diagnostic support.
 
+    @deprecated
     The facilities provided by this header are deprecated.  True assertions
     (that detect broken program logic) should use standard assert (which aborts
     if an assertion fails, and is controlled by the standard NDEBUG macro).
@@ -47,64 +48,73 @@
     of OSL_DEBUG_LEVEL macro: assertions are only active if OSL_DEBUG_LEVEL is 1
     or greater, traces if OSL_DEBUG_LEVEL is 2 or greater.
 
-    Assertions (cond is bool, msg is char*):
-    OSL_ASSERT(cond)
-        If cond is false, reports an error.
-
-    OSL_ENSURE(cond, msg)
-        If cond is false, reports an error with message msg.
-
-    OSL_FAIL(msg)
-        Reports an error with message msg unconditionally.
-
-    OSL_PRECOND(cond, msg)
-    OSL_POSTCOND(cond, msg)
-        These two are functionally equivalent to OSL_ENSURE(cond, msg). They are
-        intended to be used for checking pre- and postconditions of functions.
-
     Traces:
     OSL_TRACE(fmt, args...)
         Prints trace message. The arguments have the same meaning as the
         arguments of printf.
-
-    Other:
-    OSL_VERIFY(expr)
-        Evaluates the expression and if it is false, reports an error. The
-        expression is evaluated once without regard of the value of
-        OSL_DEBUG_LEVEL.
-
-        Example:
-
-        void extractBool(Any const& rAny, bool& rBool)
-        {
-            OSL_VERIFY(rAny >>= rBool);
-        }
-
-    OSL_DEBUG_ONLY(expr)
  */
 
 #if !defined OSL_DEBUG_LEVEL
 #define OSL_DEBUG_LEVEL 0
 #endif
 
-/* the macro OSL_LOG_PREFIX is intended to be an office internal macro for now
-
-   it is deprecated and superseded by (C++ only) SAL_WHERE
+/** @internal The macro OSL_LOG_PREFIX is intended to be an office internal macro for now
+    @deprecated superseded by (C++ only) SAL_WHERE
 */
 #define OSL_LOG_PREFIX SAL_DETAIL_WHERE
 
+/** Prints trace message.
+
+    The arguments have the same meaning as the arguments of printf.
+*/
 #define OSL_TRACE(...) \
     SAL_DETAIL_INFO_IF_FORMAT(OSL_DEBUG_LEVEL > 0, "legacy.osl", __VA_ARGS__)
 
+/** @defgroup assert Assertions
+
+    Assertions (cond is bool, msg is char*).
+
+    @{
+ */
+
+/** If cond is false, reports an error. */
 #define OSL_ASSERT(c) \
     SAL_DETAIL_WARN_IF_FORMAT(!(c), "legacy.osl", "OSL_ASSERT: %s", #c)
+/** If cond is false, reports an error with message msg. */
 #define OSL_ENSURE(c, m) SAL_DETAIL_WARN_IF_FORMAT(!(c), "legacy.osl", "%s", m)
+/** Reports an error with message msg unconditionally. */
 #define OSL_FAIL(m) SAL_DETAIL_WARN_IF_FORMAT(sal_True, "legacy.osl", "%s", m)
 
+/** Evaluates the expression and if it is false, reports an error. The
+    expression is evaluated once without regard of the value of
+    OSL_DEBUG_LEVEL.
+
+    Example:
+
+    @code{.c}
+
+    void extractBool(Any const& rAny, bool& rBool)
+    {
+        OSL_VERIFY(rAny >>= rBool);
+    }
+
+    @endcode
+*/
 #define OSL_VERIFY(c) do { if (!(c)) OSL_ASSERT(0); } while (0)
+
+/** Check the precondition of functions.
+
+    Functionally equivalent to OSL_ENSURE(cond, msg).
+*/
 #define OSL_PRECOND(c, m)   OSL_ENSURE(c, m)
+
+/** Check the postcondition of functions.
+
+    Functionally equivalent to OSL_ENSURE(cond, msg).
+*/
 #define OSL_POSTCOND(c, m)  OSL_ENSURE(c, m)
 
+/** @} */
 
 /* the macro OSL_THIS_FUNC is intended to be an office internal macro for now */
 /* copied from boost/current_function.hpp to make it usable from C

include/osl/file.h

@@ -315,7 +315,9 @@ SAL_DLLPUBLIC sal_Bool SAL_CALL osl_identicalDirectoryItem(
                                         oslDirectoryItem pItemB );
 
 /**
-   @defgroup File types
+   @defgroup filetype File types
+
+   @{
  */
 typedef enum {
     osl_File_Type_Directory,        /*< directory               */
@@ -330,7 +332,7 @@ typedef enum {
 /** @} */
 
 /**
-   @defgroup File attributes
+   @defgroup fileattrs File attributes
 
    @{
  */
@@ -349,7 +351,7 @@ typedef enum {
 /** @} */
 
 /**
-   @defgroup Flags specifying which fields to retrieve by osl_getFileStatus
+   @defgroup filestatus Flags specifying which fields to retrieve by osl_getFileStatus
 
    @{
  */
@@ -512,8 +514,11 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_acquireVolumeDeviceHandle(
 SAL_DLLPUBLIC oslFileError SAL_CALL osl_getVolumeDeviceMountPath(
         oslVolumeDeviceHandle Handle, rtl_uString **ppustrDirectoryURL);
 
-/* Volume attributes */
+/**
+   @defgroup volattrs Volume attributes
 
+   @{
+ */
 #define osl_Volume_Attribute_Removeable            0x00000001L
 #define osl_Volume_Attribute_Remote                0x00000002L
 #define osl_Volume_Attribute_CompactDisc           0x00000004L
@@ -524,7 +529,13 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_getVolumeDeviceMountPath(
 #define osl_Volume_Attribute_Case_Is_Preserved     0x00000040L
 #define osl_Volume_Attribute_Case_Sensitive        0x00000080L
 
-/* Flags specifying which fields to retrieve by osl_getVolumeInfo */
+/** @} */
+
+/**
+    @defgroup volinfoflags Flags specifying which fields to retrieve by osl_getVolumeInfo
+
+    @{
+ */
 
 #define osl_VolumeInfo_Mask_Attributes             0x00000001L
 #define osl_VolumeInfo_Mask_TotalSpace             0x00000002L

include/osl/file.hxx

@@ -424,7 +424,6 @@ public:
         @param nMask
         Set of flags describing the demanded information.
     */
-
     VolumeInfo( sal_uInt32 nMask )
         : _nMask( nMask )
     {
@@ -433,9 +432,6 @@ public:
         _aInfo.pDeviceHandle = &_aDevice._aHandle;
     }
 
-    /** Destructor.
-    */
-
     ~VolumeInfo()
     {
         if( _aInfo.ustrFileSystemName )
@@ -449,7 +445,6 @@ public:
 
         @return true if all fields are valid else false.
     */
-
     bool isValid( sal_uInt32 nMask ) const
     {
         return ( nMask & _aInfo.uValidFields ) == nMask;
@@ -460,7 +455,6 @@ public:
         @return
         true if Attributes are valid and the volume is remote else false.
     */
-
     bool getRemoteFlag() const
     {
         return (_aInfo.uAttributes & osl_Volume_Attribute_Remote) != 0;
@@ -471,7 +465,6 @@ public:
         @return
         true if attributes are valid and the volume is removable else false.
     */
-
     bool getRemoveableFlag() const
     {
         return (_aInfo.uAttributes & osl_Volume_Attribute_Removeable) != 0;

include/osl/module.h

@@ -56,6 +56,7 @@ extern "C" {
 typedef void* oslModule;
 
 /** Generic Function pointer type that will be used as symbol address.
+
     @see osl_getFunctionSymbol.
     @see osl_getModuleURLFromFunctionAddress.
 */
@@ -64,34 +65,33 @@ typedef void ( SAL_CALL *oslGenericFunction )( void );
 #ifndef DISABLE_DYNLOADING
 
 /** Load a shared library or module.
-    @param strModuleName denotes the name of the module to be loaded.
-    @param nRtldMode denotes the mode.
-    @return NULL if the module could not be loaded, otherwise a handle to the module.
+
+    @param[in] strModuleName denotes the name of the module to be loaded.
+    @param[in] nRtldMode denotes the mode.
+
+    @returns NULL if the module could not be loaded, otherwise a handle to the module.
 */
 SAL_DLLPUBLIC oslModule SAL_CALL osl_loadModule(rtl_uString *strModuleName, sal_Int32 nRtldMode);
 
 /** Load a shared library or module.
-    @param pModuleName denotes the name of the module to be loaded.
-    @param nRtldMode denotes the mode.
+
+    @param[in] pModuleName denotes the name of the module to be loaded.
+    @paramiin] nRtldMode denotes the mode.
+
     @return NULL if the module could not be loaded, otherwise a handle to the module.
+
     @since UDK 3.6
 */
 SAL_DLLPUBLIC oslModule SAL_CALL osl_loadModuleAscii(const sal_Char *pModuleName, sal_Int32 nRtldMode);
 
 /** Load a module located relative to some other module.
 
-    @param baseModule
-    must point to a function that is part of the code of some loaded module;
-    must not be NULL.
-
-    @param relativePath
-    a relative URL; must not be NULL.
-
-    @param mode
-    the SAL_LOADMODULE_xxx flags.
+    @param[in] baseModule must point to a function that is part of the code of some loaded module;
+                        must not be NULL.
+    @param[in] relativePath a relative URL; must not be NULL.
+    @param[in] mode the SAL_LOADMODULE_xxx flags.
 
-    @return
-    a non-NULL handle to the loaded module, or NULL if an error occurred.
+    @return a non-NULL handle to the loaded module, or NULL if an error occurred.
 
     @since UDK 3.2.8
 */
@@ -100,19 +100,13 @@ SAL_DLLPUBLIC oslModule SAL_CALL osl_loadModuleRelative(
 
 /** Load a module located relative to some other module.
 
-    @param baseModule
-    must point to a function that is part of the code of some loaded module;
-    must not be NULL.
-
-    @param relativePath
-    a relative URL containing only ASCII (0x01--7F) characters; must not be
-    NULL.
-
-    @param mode
-    the SAL_LOADMODULE_xxx flags.
+    @param[in] baseModule must point to a function that is part of the code of some loaded module;
+                        must not be NULL.
+    @param[in] relativePath a relative URL containing only ASCII (0x01--7F) characters;
+                        must not be NULL.
+    @param[in] mode     the SAL_LOADMODULE_xxx flags.
 
-    @return
-    a non-NULL handle to the loaded module, or NULL if an error occurred.
+    @return a non-NULL handle to the loaded module, or NULL if an error occurred.
 
     @since LibreOffice 3.5
 */
@@ -130,12 +124,10 @@ SAL_DLLPUBLIC oslModule SAL_CALL osl_loadModuleRelativeAscii(
     Do not use the returned handle as an argument to osl_unloadModule. On Unix platforms,
     pModuleName gets ignored and the special handle RTLD_DEFAULT is returned.
 
-    @param pModuleName
-    [in] denotes the name of the module to search for. Ignored on Unix
-
-    @param pResult
-    [out] a pointer to a oslModule that is updated with the requested module handle
-    on success.
+    @param[in] pModuleName  denotes the name of the module to search for.
+                            @attention Ignored on Unix.
+    @param[out] pResult     a pointer to a oslModule that is updated with the
+                            requested module handle on success.
 
     @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.
@@ -154,7 +146,13 @@ SAL_DLLPUBLIC void SAL_CALL osl_unloadModule(oslModule Module);
 #endif
 
 /** lookup the specified symbol name.
+
+    @param[in] Module the handle of the Module.
+    @param[in] strSymbolName Name of the function that will be looked up.
+
     @return address of the symbol or NULL if lookup failed.
+
+    @see osl_getFunctionSymbol
 */
 SAL_DLLPUBLIC void* SAL_CALL osl_getSymbol( oslModule Module, rtl_uString *strSymbolName);
 
@@ -163,11 +161,8 @@ SAL_DLLPUBLIC void* SAL_CALL osl_getSymbol( oslModule Module, rtl_uString *strSy
     osl_getFunctionSymbol is an alternative function for osl_getSymbol.
     Use Function pointer as symbol address to conceal type conversion.
 
-    @param Module
-    [in] the handle of the Module.
-
-    @param ustrFunctionSymbolName
-    [in] Name of the function that will be looked up.
+    @param[in] Module the handle of the Module.
+    @param[in] ustrFunctionSymbolName Unicode name of the function that will be looked up.
 
     @retval function-address on success
     @retval NULL lookup failed or the parameter are invalid
@@ -198,10 +193,10 @@ SAL_DLLPUBLIC oslGenericFunction SAL_CALL osl_getFunctionSymbol(
 SAL_DLLPUBLIC oslGenericFunction SAL_CALL osl_getAsciiFunctionSymbol(
         oslModule Module, const sal_Char *pSymbol );
 
-
 /** Lookup URL of module which is mapped at the specified address.
-    @param pv specifies an address in the process memory space.
-    @param pustrURL receives the URL of the module that is mapped at pv.
+
+    @param[in] pv       specifies an address in the process memory space.
+    @paramout] pustrURL receives the URL of the module that is mapped at pv.
     @return sal_True on success, sal_False if no module can be found at the specified address.
 */
 SAL_DLLPUBLIC sal_Bool SAL_CALL osl_getModuleURLFromAddress(
@@ -212,11 +207,8 @@ SAL_DLLPUBLIC sal_Bool SAL_CALL osl_getModuleURLFromAddress(
     osl_getModuleURLFromFunctionAddress is an alternative function for osl_getModuleURLFromAddress.
     Use Function pointer as symbol address to conceal type conversion.
 
-    @param pf
-    [in] function address in oslGenericFunction format.
-
-    @param pustrFunctionURL
-    [out] receives the URL of the module that is mapped at pf.
+    @param[in] pf       function address in oslGenericFunction format.
+    @param[out] pustrFunctionURL receives the URL of the module that is mapped at pf.
 
     @retval sal_True on success
     @retval sal_False no module can be found at the specified function address or parameter is somewhat invalid