correct wrong doxygen syntax; also comments clean-up

Change-Id: I6074241dfcdcd4ca8a365ab6e03f01028d2c1a7b
Reviewed-on: https://gerrit.libreoffice.org/43344
Reviewed-by: Michael Stahl <mstahl@redhat.com>
Tested-by: Michael Stahl <mstahl@redhat.com>

2 files changed, 106 insertions, 121 deletions

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