[Libreoffice-commits] core.git: 2 commits - include/osl
Chris Sherlock
chris.sherlock79 at gmail.com
Sun Jun 25 05:56:40 UTC 2017
include/osl/conditn.hxx | 18 ++++++++--
include/osl/diagnose.h | 78 ++++++++++++++++++++++++-------------------
include/osl/file.h | 49 ++++++++++++++++++++-------
include/osl/file.hxx | 7 ---
include/osl/module.h | 86 +++++++++++++++++++++---------------------------
5 files changed, 134 insertions(+), 104 deletions(-)
New commits:
commit 3fe969eba649fe390008044fe23a8a9bc9276a14
Author: Chris Sherlock <chris.sherlock79 at gmail.com>
Date: Sun Jun 25 15:50:53 2017 +1000
osl: variety of doxygen fixes
Change-Id: I48e4bcce447a1efdb37d6dca9e5808ec8d73492b
diff --git a/include/osl/conditn.hxx b/include/osl/conditn.hxx
index 5852f376b98b..d7bd1d9a7c13 100644
--- a/include/osl/conditn.hxx
+++ b/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.
diff --git a/include/osl/diagnose.h b/include/osl/diagnose.h
index 564ebc0e9b76..8461daf76ed2 100644
--- a/include/osl/diagnose.h
+++ b/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
diff --git a/include/osl/file.h b/include/osl/file.h
index af15d64d9b8d..2e9dfe7ca91e 100644
--- a/include/osl/file.h
+++ b/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
diff --git a/include/osl/file.hxx b/include/osl/file.hxx
index f34633cb7222..a3edbc1fe81e 100644
--- a/include/osl/file.hxx
+++ b/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;
diff --git a/include/osl/module.h b/include/osl/module.h
index fadd573dc0cd..9d1bbefa328a 100644
--- a/include/osl/module.h
+++ b/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
commit b2f63a266396a38c7d88c397d26db1c08e5f7ef5
Author: Chris Sherlock <chris.sherlock79 at gmail.com>
Date: Sun Jun 25 14:57:52 2017 +1000
osl: document and group code via doxygen
Change-Id: I9945df95e14fbca47f7cea80b1d4097d00a3eb54
diff --git a/include/osl/file.h b/include/osl/file.h
index 5708bc4cfc7d..af15d64d9b8d 100644
--- a/include/osl/file.h
+++ b/include/osl/file.h
@@ -314,19 +314,26 @@ SAL_DLLPUBLIC sal_Bool SAL_CALL osl_identicalDirectoryItem(
oslDirectoryItem pItemA,
oslDirectoryItem pItemB );
-/* File types */
+/**
+ @defgroup File types
+ */
typedef enum {
- osl_File_Type_Directory,
- osl_File_Type_Volume,
- osl_File_Type_Regular,
- osl_File_Type_Fifo,
- osl_File_Type_Socket,
- osl_File_Type_Link,
- osl_File_Type_Special,
- osl_File_Type_Unknown
+ osl_File_Type_Directory, /*< directory */
+ osl_File_Type_Volume, /*< volume (e.g. C:, A:) */
+ osl_File_Type_Regular, /*< regular file */
+ osl_File_Type_Fifo, /*< named pipe */
+ osl_File_Type_Socket, /*< socket */
+ osl_File_Type_Link, /*< file link */
+ osl_File_Type_Special, /*< special device file */
+ osl_File_Type_Unknown /*< unknown file type */
} oslFileType;
+/** @} */
+
+/**
+ @defgroup File attributes
-/* File attributes */
+ @{
+ */
#define osl_File_Attribute_ReadOnly 0x00000001
#define osl_File_Attribute_Hidden 0x00000002
#define osl_File_Attribute_Executable 0x00000010
@@ -339,9 +346,13 @@ typedef enum {
#define osl_File_Attribute_OthWrite 0x00000800
#define osl_File_Attribute_OthRead 0x00001000
#define osl_File_Attribute_OthExe 0x00002000
+/** @} */
-/* Flags specifying which fields to retrieve by osl_getFileStatus */
+/**
+ @defgroup Flags specifying which fields to retrieve by osl_getFileStatus
+ @{
+ */
#define osl_FileStatus_Mask_Type 0x00000001
#define osl_FileStatus_Mask_Attributes 0x00000002
#define osl_FileStatus_Mask_CreationTime 0x00000010
@@ -353,6 +364,7 @@ typedef enum {
#define osl_FileStatus_Mask_LinkTargetURL 0x00000400
#define osl_FileStatus_Mask_All 0x7FFFFFFF
#define osl_FileStatus_Mask_Validate 0x80000000
+/** @} */
/** Structure containing information about files and directories
More information about the Libreoffice-commits
mailing list