[Libreoffice-commits] core.git: include/comphelper include/rtl
Korrawit Pruegsanusak
detective.conan.1412 at gmail.com
Tue Oct 17 11:26:35 UTC 2017
include/comphelper/extract.hxx | 17 +++--
include/rtl/alloc.h | 118 +++++++++++++++++++----------------------
include/rtl/bootstrap.h | 109 +++++++++++++++++--------------------
3 files changed, 115 insertions(+), 129 deletions(-)
New commits:
commit 167afaf1111af5dab7645ef6efd12528eaa0389d
Author: Korrawit Pruegsanusak <detective.conan.1412 at gmail.com>
Date: Thu Oct 12 22:40:51 2017 +0700
correct wrong doxygen syntax; also comments clean-up
Change-Id: I6074241dfcdcd4ca8a365ab6e03f01028d2c1a7b
Reviewed-on: https://gerrit.libreoffice.org/43344
Reviewed-by: Michael Stahl <mstahl at redhat.com>
Tested-by: Michael Stahl <mstahl at redhat.com>
diff --git a/include/comphelper/extract.hxx b/include/comphelper/extract.hxx
index 4f4072145e71..4330faa1a625 100644
--- a/include/comphelper/extract.hxx
+++ b/include/comphelper/extract.hxx
@@ -34,7 +34,7 @@ namespace cppu
/**
* Sets enum from int32 value. This function does NOT check for valid enum values!
- *<BR>
+ *
* @param nEnum int32 enum value
* @param rType enum type
* @return enum or empty any.
@@ -48,10 +48,11 @@ inline css::uno::Any SAL_CALL int2enum(
/**
* Sets int32 from enum or int in any.
- *<BR>
- * @param rnEnum [out] int32 enum value
+ *
+ * @param[out] rnEnum int32 enum value
* @param rAny enum or int
- * @param sal_True if enum or int value was set else sal_False.
+ * @retval true if enum or int value was set
+ * @retval false otherwise
*/
inline bool enum2int( sal_Int32 & rnEnum, const css::uno::Any & rAny )
{
@@ -66,10 +67,10 @@ inline bool enum2int( sal_Int32 & rnEnum, const css::uno::Any & rAny )
/**
* Sets int32 from enum or int in any with additional typecheck
- * <BR>
- * @param rAny enum or int
- * @param eRet the enum value as int. If there is not enum of the given type or
+ *
+ * @param[out] eRet the enum value as int. If there is no enum of the given type
* a css::lang::IllegalArgumentException is thrown
+ * @param rAny enum or int
* @throws css::lang::IllegalArgumentException
*/
template< typename E >
@@ -88,7 +89,7 @@ inline void any2enum( E & eRet, const css::uno::Any & rAny )
}
/**
- * extracts a boolean either as a bool or an integer from
+ * Extracts a boolean either as a bool or an integer from
* an any. If there is no bool or integer inside the any
* a css::lang::IllegalArgumentException is thrown
*
diff --git a/include/rtl/alloc.h b/include/rtl/alloc.h
index ccb8d4183b20..8e59f4b8712d 100644
--- a/include/rtl/alloc.h
+++ b/include/rtl/alloc.h
@@ -35,8 +35,8 @@ extern "C" {
A call to this function will return NULL upon the requested
memory size being either zero or larger than currently allocatable.
- @param Bytes [in] memory size.
- @return pointer to allocated memory.
+ @param[in] Bytes memory size.
+ @return pointer to the allocated memory.
*/
SAL_DLLPUBLIC void * SAL_CALL rtl_allocateMemory (
sal_Size Bytes
@@ -53,9 +53,9 @@ SAL_DLLPUBLIC void * SAL_CALL rtl_allocateMemory (
@see rtl_allocateMemory()
@see rtl_freeMemory()
- @param Ptr [in] pointer to previously allocated memory.
- @param Bytes [in] new memory size.
- @return pointer to reallocated memory. May differ from Ptr.
+ @param[in] Ptr pointer to the previously allocated memory.
+ @param[in] Bytes new memory size.
+ @return pointer to the reallocated memory. May differ from Ptr.
*/
SAL_DLLPUBLIC void * SAL_CALL rtl_reallocateMemory (
void * Ptr,
@@ -64,7 +64,7 @@ SAL_DLLPUBLIC void * SAL_CALL rtl_reallocateMemory (
/** Free memory.
- @param Ptr [in] pointer to previously allocated memory.
+ @param[in] Ptr pointer to the previously allocated memory.
@return none. Memory is released. Ptr is invalid.
*/
SAL_DLLPUBLIC void SAL_CALL rtl_freeMemory (
@@ -76,8 +76,8 @@ SAL_DLLPUBLIC void SAL_CALL rtl_freeMemory (
A call to this function will return NULL upon the requested
memory size being either zero or larger than currently allocatable.
- @param Bytes [in] memory size.
- @return pointer to allocated and zero'ed memory.
+ @param[in] Bytes memory size.
+ @return pointer to the allocated and zero'ed memory.
*/
SAL_DLLPUBLIC void * SAL_CALL rtl_allocateZeroMemory (
sal_Size Bytes
@@ -87,8 +87,8 @@ SAL_DLLPUBLIC void * SAL_CALL rtl_allocateZeroMemory (
Fills a block of memory with zeros in a way that is guaranteed to be secure
- @param Ptr [in] pointer to previously allocated memory.
- @param Bytes [in] memory size.
+ @param[in] Ptr pointer to the previously allocated memory.
+ @param[in] Bytes memory size.
@since LibreOffice 5.0
*/
@@ -99,10 +99,10 @@ SAL_DLLPUBLIC void SAL_CALL rtl_secureZeroMemory (
/** Zero and free memory.
- @param Ptr [in] pointer to previously allocated memory.
- @param Bytes [in] memory size.
- @return none. Memory is zero'ed with rtl_secureZeroMemory and released. Ptr
- is invalid.
+ @param[in] Ptr pointer to the previously allocated memory.
+ @param[in] Bytes memory size.
+ @return none. Memory is zero'ed with rtl_secureZeroMemory() and released.
+ Ptr is invalid.
*/
SAL_DLLPUBLIC void SAL_CALL rtl_freeZeroMemory (
void * Ptr,
@@ -115,12 +115,12 @@ SAL_DLLPUBLIC void SAL_CALL rtl_freeZeroMemory (
memory size being either zero or larger than currently allocatable.
Memory obtained through this function must be freed with
- rtl_freeAlignedMemory.
+ rtl_freeAlignedMemory().
- @param Alignment [in] alignment in bytes, must be a power of two multiple of
+ @param[in] Alignment alignment in bytes, must be a power of two multiple of
sizeof(void*).
- @param Bytes [in] memory size.
- @return pointer to allocated memory.
+ @param[in] Bytes memory size.
+ @return pointer to the allocated memory.
@since LibreOffice 4.3
*/
@@ -130,9 +130,9 @@ SAL_DLLPUBLIC void* SAL_CALL rtl_allocateAlignedMemory (
) SAL_THROW_EXTERN_C();
-/** Free memory allocated with rtl_allocateAlignedMemory.
+/** Free memory allocated with rtl_allocateAlignedMemory().
- @param Ptr [in] pointer to previously allocated memory.
+ @param[in] Ptr pointer to the previously allocated memory.
@return none. Memory is released. Ptr is invalid.
@since LibreOffice 4.3
@@ -149,15 +149,14 @@ typedef struct SAL_DLLPUBLIC_RTTI rtl_arena_st rtl_arena_type;
#define RTL_ARENA_NAME_LENGTH 31
-/** rtl_arena_create()
- *
- * @param pName [in] descriptive name; for debugging purposes.
- * @param quantum [in] resource allocation unit / granularity; rounded up to next power of 2.
- * @param quantum_cache_max [in] max resources to cache; rounded up to next multiple of quantum; usually 0.
- * @param source_arena [in] passed as argument to source_alloc, source_free; usually NULL.
- * @param source_alloc [in] function to allocate resources; usually rtl_arena_alloc.
- * @param source_free [in] function to free resources; usually rtl_arena_free.
- * @param nFlags [in] flags; usually 0.
+/**
+ * @param[in] pName descriptive name; for debugging purposes.
+ * @param[in] quantum resource allocation unit / granularity; rounded up to next power of 2.
+ * @param[in] quantum_cache_max max resources to cache; rounded up to next multiple of quantum; usually 0.
+ * @param[in] source_arena passed as argument to source_alloc, source_free; usually NULL.
+ * @param[in] source_alloc function to allocate resources; usually rtl_arena_alloc.
+ * @param[in] source_free function to free resources; usually rtl_arena_free.
+ * @param[in] nFlags flags; usually 0.
*
* @return pointer to rtl_arena_type, or NULL upon failure.
*
@@ -174,9 +173,8 @@ SAL_DLLPUBLIC rtl_arena_type * SAL_CALL rtl_arena_create (
) SAL_THROW_EXTERN_C();
-/** rtl_arena_destroy()
- *
- * @param pArena [in] the arena to destroy.
+/**
+ * @param[in] pArena the arena to destroy.
* @return None
*
* @see rtl_arena_create()
@@ -186,10 +184,9 @@ SAL_DLLPUBLIC void SAL_CALL rtl_arena_destroy (
) SAL_THROW_EXTERN_C();
-/** rtl_arena_alloc()
- *
- * @param pArena [in] arena from which resource is allocated.
- * @param pBytes [inout] size of resource to allocate.
+/**
+ * @param[in] pArena arena from which resource is allocated.
+ * @param[in,out] pBytes size of resource to allocate.
*
* @return allocated resource, or NULL upon failure.
*
@@ -201,11 +198,10 @@ SAL_DLLPUBLIC void * SAL_CALL rtl_arena_alloc (
) SAL_THROW_EXTERN_C();
-/** rtl_arena_free()
- *
- * @param pArena [in] arena from which resource was allocated.
- * @param pAddr [in] resource to free.
- * @param nBytes [in] size of resource.
+/**
+ * @param[in] pArena arena from which resource was allocated.
+ * @param[in] pAddr resource to free.
+ * @param[in] nBytes size of resource.
*
* @return None.
*
@@ -226,17 +222,16 @@ typedef struct rtl_cache_st rtl_cache_type;
#define RTL_CACHE_FLAG_BULKDESTROY 1
-/** rtl_cache_create()
- *
- * @param pName [in] descriptive name; for debugging purposes.
- * @param nObjSize [in] object size.
- * @param nObjAlign [in] object alignment; usually 0 for suitable default.
- * @param constructor [in] object constructor callback function; returning 1 for success or 0 for failure.
- * @param destructor [in] object destructor callback function.
- * @param reclaim [in] reclaim callback function.
- * @param pUserArg [in] opaque argument passed to callback functions.
- * @param pSource [in] opaque argument passed to callback functions.
- * @param nFlags [in] flags.
+/**
+ * @param[in] pName descriptive name; for debugging purposes.
+ * @param[in] nObjSize object size.
+ * @param[in] nObjAlign object alignment; usually 0 for suitable default.
+ * @param[in] constructor object constructor callback function; returning 1 for success or 0 for failure.
+ * @param[in] destructor object destructor callback function.
+ * @param[in] reclaim reclaim callback function.
+ * @param[in] pUserArg opaque argument passed to callback functions.
+ * @param[in] pSource opaque argument passed to callback functions.
+ * @param[in] nFlags flags.
*
* @return pointer to rtl_cache_type, or NULL upon failure.
*
@@ -255,9 +250,8 @@ SAL_DLLPUBLIC rtl_cache_type * SAL_CALL rtl_cache_create (
) SAL_THROW_EXTERN_C();
-/** rtl_cache_destroy()
- *
- * @param pCache [in] the cache to destroy.
+/**
+ * @param[in] pCache the cache to destroy.
*
* @return None.
*
@@ -268,21 +262,19 @@ SAL_DLLPUBLIC void SAL_CALL rtl_cache_destroy (
) SAL_THROW_EXTERN_C();
-/** rtl_cache_alloc()
+/**
+ * @param[in] pCache cache from which object is allocated.
*
- * @param pCache [in] cache from which object is allocated.
- *
- * @return pointer to allocated object, or NULL upon failure.
+ * @return pointer to the allocated object, or NULL upon failure.
*/
SAL_DLLPUBLIC void * SAL_CALL rtl_cache_alloc (
rtl_cache_type * pCache
) SAL_THROW_EXTERN_C();
-/** rtl_cache_free()
- *
- * @param pCache [in] cache from which object was allocated.
- * @param pObj [in] object to free.
+/**
+ * @param[in] pCache cache from which object was allocated.
+ * @param[in] pObj object to free.
*
* @return None.
*
diff --git a/include/rtl/bootstrap.h b/include/rtl/bootstrap.h
index 76dfb1f5edc3..5aa636356d2d 100644
--- a/include/rtl/bootstrap.h
+++ b/include/rtl/bootstrap.h
@@ -33,85 +33,80 @@ extern "C" {
The described concept provides a platform independent way to access
minimum bootstrap settings for every application by explicitly or
- implicitly passing the values to the application.<p>
+ implicitly passing the values to the application.
- MULTI-LEVEL STRATEGY FOR RETRIEVAL OF BOOTSTRAP VALUES :<p>
+ <strong>MULTI-LEVEL STRATEGY FOR RETRIEVAL OF BOOTSTRAP VALUES:</strong>
The 1st level is tried first. On failure,
the next level is tried. Every query starts at the first level again, so
- that one setting may be taken from the 3rd and one from the 1st level.<p>
+ that one setting may be taken from the 3rd and one from the 1st level.
1st level: explicitly set variables via rtl_bootstrap_set()
- 2nd level: command line arguments. A "-env:SETTINGNAME=value" is given on
- command line. This allows to give an application a certain setting, even
+ 2nd level: command line arguments. A `-env:SETTINGNAME=value` is given on
+ command line. This allows giving an application a certain setting, even
if an ini-file exists (especially useful for e.g. daemons that want to
- start an executable with dynamical changing settings).<p>
+ start an executable with dynamical changing settings).
3rd level: environment variables. The application tries to get the
- setting from the environment.<p>
+ setting from the environment.
4th level: executable ini-file. Every application looks for an ini-file.
- The filename defaults to /absolute/path/to/executable[rc|.ini]
+ The filename defaults to `/absolute/path/to/executable[rc|.ini]`
without .bin or .exe suffix. The ini-filename can be
set by the special command line parameter
- '-env:INIFILENAME=/absolute/path/to/inifile' at runtime or it may
- be set at compile time by an API-call.<p>
+ `-env:INIFILENAME=/absolute/path/to/inifile` at runtime or it may
+ be set at compile time by an API-call.
5th level: URE_BOOTSTRAP ini-file. If the bootstrap variable URE_BOOTSTRAP
- expands to the URL of an ini-file, that ini-file is searched.<p>
+ expands to the URL of an ini-file, that ini-file is searched.
6th level: default. An application can have some default settings decided
at compile time, which allow the application to run even with no
- deployment settings. <p>
+ deployment settings.
- If neither of the above levels leads to an successful retrieval of the value
- (no default possible), the application may fail to start.<p>
+ If neither of the above levels leads to a successful retrieval of the value
+ (no default possible), the application may fail to start.
- NAMING CONVENTIONS <p>
+ <strong>NAMING CONVENTIONS</strong>
- Naming conventions for names of bootstrap values :
+ Naming conventions for names of bootstrap values:
Names may only include characters, that are allowed characters for
environment variables. This excludes '.', ' ', ';', ':' and any non-ascii
- character. Names are case insensitive.<p>
+ character. Names are case insensitive.
- An ini-file is only allowed to have one section, which must be named '[Bootstrap]'.
+ An ini-file is only allowed to have one section, which must be named
+ `[Bootstrap]` with the square brackets.
The section may be omitted.
The section name does not appear in the name of the corresponding
environment variable or commandline arg.
- Values maybe arbitrary unicode strings, they must be encoded in UTF8.<p>
+ Values may be arbitrary unicode strings, they must be encoded in UTF8.
- Example:<p>
+ <em>Example:</em>
in an ini-file:
<code>
[Sectionname]
Name=value
- </code><p>
+ </code>
as commandline arg:
- <code>-env:Name=value</code><p>
+ <code>-env:Name=value</code>
- as environment
- <code>
- setenv Name value
- set Name=value
- </code><p>
+ as environment:
+ - <code>setenv Name value</code>
+ - <code>set Name=value</code>
- SPECIAL VARIABLES:
+ <strong>SPECIAL VARIABLES:</strong>
- <ul>
- <li> INIFILENAME<br>
+ - INIFILENAME<br>
This variable allows to set the inifilename. This makes only sense, if the filename
is different than the executable file name. It must be given on command line. If it is
given the executable ini-file is ignored.
- </li>
- </ul>
*/
/** may be called by an application to set an ini-filename.
- <p>
Must be called before rtl_bootstrap_get(). May not be called twice.
If it is never called, the filename is based on the name of the executable,
with the suffix ".ini" on Windows or "rc" on Unix.
@@ -121,21 +116,21 @@ extern "C" {
SAL_DLLPUBLIC void SAL_CALL rtl_bootstrap_setIniFileName( rtl_uString *pFileUri );
/**
- @param ppValue
- out parameter. Contains always a valid rtl_uString pointer.
@param pName
- The name of the bootstrap setting to be retrieved.
+ The name of the bootstrap setting to be retrieved.
+ @param[out] ppValue
+ Contains always a valid rtl_uString pointer.
@param pDefault
- maybe NULL. If once the default is
+ maybe <code>NULL</code>. If once the default is
returned, successive calls always return this
default value, even when called with different
defaults.
- @return <code>sal_True</code>, when a value could be retrieved successfully,
- <code>sal_False</code>, when none of the 4 methods gave a value. ppValue
- then contains ane empty string.
- When a pDefault value is given, the function returns always
- <code>sal_True</code>.
+ @retval sal_True when a value could be retrieved successfully.
+ When a <code>pDefault</code> value is given,
+ the function always returns <code>sal_True</code>.
+ @retval sal_False when none of the 4 methods gave a value.
+ <code>ppValue</code> then contains an empty string.
*/
SAL_DLLPUBLIC sal_Bool SAL_CALL rtl_bootstrap_get(
rtl_uString *pName, rtl_uString **ppValue, rtl_uString *pDefault );
@@ -155,25 +150,24 @@ typedef void * rtlBootstrapHandle;
/**
Opens a bootstrap argument container.
- @param pIniName [in] The name of the ini-file to use, if <code>NULL</code> defaults
+ @param[in] pIniName The name of the ini-file to use, if <code>NULL</code> defaults
to the executables name
- @return Handle for a bootstrap argument
- container
+ @return Handle for a bootstrap argument container
*/
SAL_DLLPUBLIC rtlBootstrapHandle SAL_CALL rtl_bootstrap_args_open(rtl_uString * pIniName);
/**
Closes a bootstrap argument container.
- @param handle [in] The handle got by <code>rtl_bootstrap_args_open()</code>
+ @param[in] handle The handle got by rtl_bootstrap_args_open()
*/
SAL_DLLPUBLIC void SAL_CALL rtl_bootstrap_args_close(rtlBootstrapHandle handle)
SAL_THROW_EXTERN_C();
/**
- @param handle [in] The handle got by <code>rtl_bootstrap_args_open()</code>
- @param pName [in] The name of the variable to be retrieved
- @param ppValue [out] The result of the retrieval. *ppValue may be null in case of failure.
- @param pDefault [in] The default value for the retrieval, may be <code>NULL</code>
+ @param[in] handle The handle got by rtl_bootstrap_args_open()
+ @param[in] pName The name of the variable to be retrieved
+ @param[out] ppValue The result of the retrieval. *ppValue may be null in case of failure.
+ @param[in] pDefault The default value for the retrieval, may be <code>NULL</code>
@return The status of the retrieval, <code>sal_True</code> on success.
*/
@@ -183,23 +177,23 @@ SAL_DLLPUBLIC sal_Bool SAL_CALL rtl_bootstrap_get_from_handle(
/** Returns the name of the inifile associated with this handle.
- @param handle [in] The handle got by <code>rtl_bootstrap_args_open()</code>
- @param ppIniName [out] contains after the call the name of the ini-filename.
+ @param[in] handle The handle got by rtl_bootstrap_args_open()
+ @param[out] ppIniName contains after the call the name of the ini-filename.
*/
SAL_DLLPUBLIC void SAL_CALL rtl_bootstrap_get_iniName_from_handle(
rtlBootstrapHandle handle, rtl_uString ** ppIniName);
/** Expands a macro using bootstrap variables.
- @param handle [in] The handle got by <code>rtl_bootstrap_args_open()</code>
- @param macro [inout] The macro to be expanded
+ @param[in] handle The handle got by rtl_bootstrap_args_open()
+ @param[in,out] macro The macro to be expanded
*/
SAL_DLLPUBLIC void SAL_CALL rtl_bootstrap_expandMacros_from_handle(
rtlBootstrapHandle handle, rtl_uString ** macro );
/** Expands a macro using default bootstrap variables.
- @param macro [inout] The macro to be expanded
+ @param[in,out] macro The macro to be expanded
*/
SAL_DLLPUBLIC void SAL_CALL rtl_bootstrap_expandMacros(
rtl_uString ** macro);
@@ -209,9 +203,8 @@ SAL_DLLPUBLIC void SAL_CALL rtl_bootstrap_expandMacros(
@param value
an arbitrary, non-NULL value
- @param encoded
- non-NULL out parameter, receiving the given value with all occurrences of
- special characters ("$" and "\") escaped
+ @param[out] encoded
+ the given value with all occurrences of special characters ("$" and "\") escaped
@since UDK 3.2.9
*/
More information about the Libreoffice-commits
mailing list