Mailing-List: contact commits-help@harmony.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@harmony.apache.org
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: svn commit: r521341 - in
 /harmony/enhanced/drlvm/trunk/vm/port/include:
 port_atomic.h port_disasm.h port_dso.h port_filepath.h port_sysinfo.h
 port_timer.h port_vmem.h
Date: Thu, 22 Mar 2007 16:54:17 -0000
To: commits@harmony.apache.org
From: nadinem@apache.org
Message-Id: <20070322165418.0FCF01A9838@eris.apache.org>

Author: nadinem
Date: Thu Mar 22 09:54:16 2007
New Revision: 521341

URL: http://svn.apache.org/viewvc?view=rev&rev=521341
Log:
HARMONY-3180: adding comments to port external files

Modified:
    harmony/enhanced/drlvm/trunk/vm/port/include/port_atomic.h
    harmony/enhanced/drlvm/trunk/vm/port/include/port_disasm.h
    harmony/enhanced/drlvm/trunk/vm/port/include/port_dso.h
    harmony/enhanced/drlvm/trunk/vm/port/include/port_filepath.h
    harmony/enhanced/drlvm/trunk/vm/port/include/port_sysinfo.h
    harmony/enhanced/drlvm/trunk/vm/port/include/port_timer.h
    harmony/enhanced/drlvm/trunk/vm/port/include/port_vmem.h

Modified: harmony/enhanced/drlvm/trunk/vm/port/include/port_atomic.h
URL: http://svn.apache.org/viewvc/harmony/enhanced/drlvm/trunk/vm/port/include/port_atomic.h?view=diff&rev=521341&r1=521340&r2=521341
==============================================================================
--- harmony/enhanced/drlvm/trunk/vm/port/include/port_atomic.h (original)
+++ harmony/enhanced/drlvm/trunk/vm/port/include/port_atomic.h Thu Mar 22 09:54:16 2007
@@ -22,9 +22,23 @@
 #ifndef _PORT_ATOMIC_H_
 #define _PORT_ATOMIC_H_
 
+/**
+* @file
+* Atomic operations
+*/
+
 #include "open/types.h"
 #include "port_general.h"
 
+/**
+ * @defgroup port_atomic Atomic operations
+ *
+ * All atomic operations are perfomance critical,
+ * thus they are defined as inlined for most platforms in this file.
+ * @ingroup port_apr
+ * @{
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -37,43 +51,50 @@
 #define INLINE static
 #endif
 #endif
-/**
- * All atomic operrations are perfomance critical, 
- * thus they are defined as inlined for most platforms in this file
- */
+
  
- #if defined(_IPF_)
+ #if defined(_IPF_) || defined(DOXYGEN)
 
-    
 /**
-* Atomic compare and exchange operation
-* @data[in, out]
-* @value[in] new value
-* @comp[in] value to compare with
-* return old value
+* The atomic compare and exchange operation on <code>uint8</code>.
+* The function compares the current value of the specified <i>data</i>
+* with the <i>comp</i> value and if they match, swaps the <i>data</i>
+* with the <i>value</i>.
+* @param[in, out] data  - the pointer to the value
+* @param[in] value      - the new value
+* @param[in] comp       - the value to compare with
+* @return The old value.
 */
 APR_DECLARE(uint8) port_atomic_cas8(volatile uint8 * data, 
                                                uint8 value, uint8 comp);
 
-/**
-* Atomic compare and exchange operation
-* @data[in, out]
-* @value[in] new value
-* @comp[in] value to compare with
-* return old value
+/**  
+* The atomic compare and exchange operation on uint16. 
+* The function compares the current value of the specified <i>data</i>
+* with the <i>comp</i> value and if they match, swaps the <i>data</i>
+* with the <i>value</i>.
+* @param[in, out] data - the pointer to the value
+* @param[in] value     - the new value
+* @param[in] comp      - the value to compare with
+* @return The old value.
 */
 APR_DECLARE(uint16) port_atomic_cas16(volatile uint16 * data, 
                                                  uint16 value, uint16 comp);
 
-/**
-* Atomic compare and exchange operation
-* @data[in, out]
-* @value[in] new value
-* @comp[in] value to compare with
-* return old value
+/**  
+* The atomic compare and exchange operation on uint64. 
+* The function compares the current value of the specified <i>data</i>
+* with the <i>comp</i> value and if they match, swaps the <i>data</i>
+* with the <i>value</i>.
+* @param[in, out] data - the pointer to the value
+* @param[in] value     - the new value
+* @param[in] comp      - the value to compare with
+* @return The old value.
 */
 APR_DECLARE(uint64) port_atomic_cas64(volatile uint64 * data, 
                                                  uint64 value, uint64 comp);
+
+/** @} */
 
 #elif defined(WIN32) && !defined(_WIN64)
 

Modified: harmony/enhanced/drlvm/trunk/vm/port/include/port_disasm.h
URL: http://svn.apache.org/viewvc/harmony/enhanced/drlvm/trunk/vm/port/include/port_disasm.h?view=diff&rev=521341&r1=521340&r2=521341
==============================================================================
--- harmony/enhanced/drlvm/trunk/vm/port/include/port_disasm.h (original)
+++ harmony/enhanced/drlvm/trunk/vm/port/include/port_disasm.h Thu Mar 22 09:54:16 2007
@@ -30,6 +30,18 @@
 extern "C" {
 #endif
 
+/**
+* @file
+* Provides information on dynamically-generated code
+*/
+
+/**
+ * @defgroup port_disasm Disassembler of machine codes
+ * @ingroup port_apr
+ * @{
+ */
+
+
 typedef struct port_disassembler_t port_disassembler_t;
 
 typedef struct port_disasm_info_t {
@@ -40,27 +52,27 @@
 
 
 /**
- * Initializes disasm module
+ * Initializes the <code>disasm</code> module.
  *
- * @remark It's safe to call it several times.
+ * @remark It's safe to call the function several times.
  */
 APR_DECLARE(apr_status_t) port_disasm_initialize();
 
 /**
- * Creates disassembler
+ * Creates the disassembler.
  *
- * @param disassembler The created disassembler
- * @param pool The pool to use
- * @remark It's safe to call this function by multiple threads with different pools
+ * @param disassembler - the created disassembler
+ * @param pool         - the pool to use
+ * @remark It's safe to call this function by multiple threads with different pools.
  */
 APR_DECLARE(apr_status_t) port_disassembler_create(port_disassembler_t ** disassembler,
                                                    apr_pool_t * pool);
 /**
- * @param new_info The info to set up
- * @param old_info Should point to the memory to store old info in.
- *                 NULL value should be specified if no interest for the old info.
- * @remark Not thread safe. Only one thread may change the info for the specified
-           disassembler
+ * @param new_info - the info to set up
+ * @param old_info - the pointer to the memory to store old info in; <code>NULL</code> 
+ *                   should be specified if no interest for the old info
+ * @warning Not thread safe. Only one thread can change the info for the specified
+           disassembler.
  */
 APR_DECLARE(apr_status_t) port_disasm_set_info(port_disassembler_t * disassembler,
                                                const port_disasm_info_t new_info,
@@ -70,12 +82,12 @@
 /**
  * Translates from machine native to human readable code.
  *
- * @param disassembler The disassembler
- * @param code Assembler code to translate
- * @param len Number of bytes to be translated
- * @param disasm_code Points to pointer to the disassembled code at exit.
- *                    The pointer is valid until the disassembler is valid.
- * @warning Not thread safe. Only one thread can use the specified disassembler
+ * @param disassembler   - the disassembler
+ * @param code           - the assembler code to translate
+ * @param len            - the number of bytes to be translated
+ * @param disasm_code    - the pointer to the pointer to the disassembled code on exit;
+ *                         is valid when the disassembler is valid
+ * @warning Not thread safe. Only one thread can use the specified disassembler.
  */
 APR_DECLARE(apr_status_t) port_disasm(port_disassembler_t * disassembler,
                                       const char * code, 
@@ -85,9 +97,9 @@
 /**
  * Translates from machine native to human readable code.
  *
- * @param code Assembler code to translate
- * @param len Number of bytes to be translated
- * @param thefile Destination file
+ * @param code    - the assembler code to translate
+ * @param len     - the number of bytes to be translated
+ * @param thefile - the destination file
  * @warning Not thread safe. Only one thread can use the specified disassembler
  */
 APR_DECLARE(apr_status_t) port_disasm_to_file(port_disassembler_t * disassembler,
@@ -95,11 +107,15 @@
                                               unsigned int len,
                                               apr_file_t * thefile);
 
+/** @} */
+
+
 #ifdef __cplusplus
 }
 #endif
 
 #endif // _DISASM_H_
+
 
 
 

Modified: harmony/enhanced/drlvm/trunk/vm/port/include/port_dso.h
URL: http://svn.apache.org/viewvc/harmony/enhanced/drlvm/trunk/vm/port/include/port_dso.h?view=diff&rev=521341&r1=521340&r2=521341
==============================================================================
--- harmony/enhanced/drlvm/trunk/vm/port/include/port_dso.h (original)
+++ harmony/enhanced/drlvm/trunk/vm/port/include/port_dso.h Thu Mar 22 09:54:16 2007
@@ -22,32 +22,66 @@
 #ifndef _PORT_DSO_H_
 #define _PORT_DSO_H_
 
+/**
+* @file
+* Dynamic binaries handling
+*/
+
 #include "open/types.h"
 #include "port_general.h"
 #include <apr_pools.h>
 #include <apr_dso.h>
 
+/**
+ * @defgroup port_dso Dynamic binaries handling
+ * @ingroup port_apr
+ * @{
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 /**
- * Decorate shared library name (.dll <-> lib*.so).
- * The "name" parameter should be double-quoted string.
- * @non_apr
+ * Decorates the shared library name (.dll <-> lib*.so).
+ * The <i>name</i> parameter should be double-quoted string.
  */
+#ifdef DOXYGEN
+#define PORT_DSO_NAME(name)
+#endif
+
 #ifdef PLATFORM_POSIX
 #   define PORT_DSO_NAME(name) "lib" name ".so"
 #elif PLATFORM_NT
 #   define PORT_DSO_NAME(name) name ".dll"
 #endif
 
+/**
+ * @defgroup dso_modes Shared library binding modes
+ * @{
+ */
+/** The APR-default binding mode flag (?) */
 #define PORT_DSO_DEFAULT 0
+/** 
+* Eager mode flag: the resolution/relocation of dynamic symbols should 
+* be performed at library loading.
+*/
 #define PORT_DSO_BIND_NOW 0x1
+/** 
+* Lazy mode flag: the resolution/relocation of dynamic symbols should 
+* be deferred until reference to the symbol encountered.
+*/
 #define PORT_DSO_BIND_DEFER 0x2
+/** @} */
 
 /**
-* Loads shared binary (executable or library).
+* Loads the shared binary file, an executable or a library.
+* @param[out] handle - a handle to the loaded object
+* @param path        - the path to the binary
+* @param mode        - the flag to control resolution/relocation of dynamic symbols in
+                       the loaded object, see <code>PORT_DSO_BIND_*</code> defines.
+* @param pool        - storage to allocate the returned handle
+* @return <code>APR_SUCCESS</code> if OK; otherwise, an error code.
 */
 APR_DECLARE(apr_status_t) port_dso_load_ex(apr_dso_handle_t** handle,
                                       const char* path,
@@ -56,17 +90,24 @@
 
 
 /**
-* Returns list of directories in which OS searches for libraries.
+* Returns the list of directories wher the OS searches for libraries.
+* @param[out] path - the pointer to the path list
+* @param pool      - the storage to allocate the returned buffer
+* @return <code>APR_SUCCESS</code> if OK; otherwise, an error code.
 */
 APR_DECLARE(apr_status_t) port_dso_search_path(char** path,
                                         apr_pool_t* pool);
 
 /**
- * Decorate shared library name (.dll <-> lib*.so).
- * @non_apr
+ * Decorates shared library name (.dll <-> lib*.so).
+ * @param dl_name - the name of the shared library
+ * @param pool    - storage to allocate the returned handle
+ * @return The platform-specific filename for the library.
  */
 APR_DECLARE(char *) port_dso_name_decorate(const char* dl_name,
                             apr_pool_t* pool);
+
+/** @} */
 
 #ifdef __cplusplus
 }

Modified: harmony/enhanced/drlvm/trunk/vm/port/include/port_filepath.h
URL: http://svn.apache.org/viewvc/harmony/enhanced/drlvm/trunk/vm/port/include/port_filepath.h?view=diff&rev=521341&r1=521340&r2=521341
==============================================================================
--- harmony/enhanced/drlvm/trunk/vm/port/include/port_filepath.h (original)
+++ harmony/enhanced/drlvm/trunk/vm/port/include/port_filepath.h Thu Mar 22 09:54:16 2007
@@ -22,17 +22,40 @@
 #ifndef _PORT_FILEPATH_H_
 #define _PORT_FILEPATH_H_
 
+/**
+* @file
+* Filepath manipulation routines
+*
+*/
+
 #include "port_general.h"
 #include <apr_pools.h>
 
 #ifdef __cplusplus
 extern "C" {
 #endif
+/**
+ * @defgroup port_filepath Filepath manipulation routines
+ * @ingroup port_apr
+ * @{
+ */
 
 /**
- * File system separators definitions.
- * @non_apr
+ * @defgroup file_sep File system separators definitions.
+ * @{
  */
+#ifdef DOXYGEN
+/** The platform-specific file name separator char delimiting entities in a filepath. */
+#define PORT_FILE_SEPARATOR
+/** The platform-specific file path separator char delimiting filepaths in a path list. */
+#define PORT_PATH_SEPARATOR
+/** The platform-specific file name separator as a string. */
+#define PORT_FILE_SEPARATOR_STR
+/** The platform-specific file name separator as a string. */
+#define PORT_PATH_SEPARATOR_STR
+#endif
+/** @} */
+
 #ifdef PLATFORM_POSIX
 #   define PORT_FILE_SEPARATOR '/'
 #   define PORT_PATH_SEPARATOR ':'
@@ -44,9 +67,13 @@
 #   define PORT_FILE_SEPARATOR_STR "\\"
 #   define PORT_PATH_SEPARATOR_STR ";"
 #endif
+
 /**
-* Sticks together filepath parts.
-* @non_apr
+* Sticks together filepath parts delimiting them by a platform-specific file separator.
+* A typical example is obtaining a path to file by the directory path and the file name.
+* @param root  - the beginning of the file path
+* @param trail - the ending of the file path
+* @return The resulting filepath.
 */
 APR_DECLARE(char *) port_filepath_merge(const char* root,
                           const char* trail,
@@ -54,11 +81,21 @@
 
 
 /**
-* Returns canonical form of the specified path.
-* @non_apr
+* Provides the <i>canonical form</i> of the specified path.
+* This means that the function returns the standardized absolute path to a resource
+* that can be addressed via different file paths.
+* The canonical form is reasonable to use as a resource identifier. 
+* @note The canonical form cannot be guaranteed to be the only unique name
+* due to various file systems specifics.
+* @param original - the path to be canonicalized
+* @param pool     - the pool to allocate return buffer
+* @return The canonical name of the specified path.
 */
 APR_DECLARE(char*) port_filepath_canonical(const char* original,
                                       apr_pool_t* pool);
+
+/** @} */
+
 
 #ifdef __cplusplus
 }

Modified: harmony/enhanced/drlvm/trunk/vm/port/include/port_sysinfo.h
URL: http://svn.apache.org/viewvc/harmony/enhanced/drlvm/trunk/vm/port/include/port_sysinfo.h?view=diff&rev=521341&r1=521340&r2=521341
==============================================================================
--- harmony/enhanced/drlvm/trunk/vm/port/include/port_sysinfo.h (original)
+++ harmony/enhanced/drlvm/trunk/vm/port/include/port_sysinfo.h Thu Mar 22 09:54:16 2007
@@ -22,6 +22,12 @@
 #ifndef _PORT_SYSINFO_H_
 #define _PORT_SYSINFO_H_
 
+/**
+* @file
+* System information routines
+*
+*/
+
 #include "open/types.h"
 #include "port_general.h"
 #include <apr_pools.h>
@@ -29,46 +35,71 @@
 #ifdef __cplusplus
 extern "C" {
 #endif
+/**
+ * @defgroup port_sysinfo System information routines
+ * @ingroup port_apr
+ * @{
+ */
 
 /**
- * Determines absolute path of the executing process.
+ * Determines the absolute path of the executing process.
+ * @param[out] self_name - the pointer to the requested path string
+ * @param pool           - a pool to allocate return buffer
+ * @return <code>APR_SUCCESS</code> if OK; otherwise, an error code.
  */
 APR_DECLARE(apr_status_t) port_executable_name(char** self_name,
                                    apr_pool_t* pool);
 
 /**
-* Returns number of processors in the system.
+* Returns the number of processors in the system.
 */
 APR_DECLARE(int) port_CPUs_number(void);
 
 /**
-* Returns name of CPU architecture.
+* Returns the name of CPU architecture.
 */
 APR_DECLARE(const char *) port_CPU_architecture(void);
 
 /**
-* Returns OS name and version.
+* Provides the name and version of the host operating system.
+* @param[out] os_name - the pointer to the OS name string
+* @param[out] os_ver  - the pointer to the OS version string
+* @param pool         - a pool to allocate return buffers
+* @return <code>APR_SUCCESS</code> if OK; otherwise, an error code.
 */
 APR_DECLARE(apr_status_t) port_OS_name_version(char** os_name, char** os_ver, 
                                    apr_pool_t* pool);
 
 /**
-* Returns name of active account.
+* Returns the name of the account under which the current process is executed.
+* @param[out] account - the pointer to the requested name string
+* @param pool         - a pool to allocate the return buffer
+* @return <code>APR_SUCCESS</code> if OK; otherwise, an error code.
 */
 APR_DECLARE(apr_status_t) port_user_name(char** account,
                              apr_pool_t* pool);
 
 /**
-* Returns home path of active account.
+* Returns the home path of the account under which the process is executed.
+* @param[out] path - the pointer to the requested path string
+* @param pool      - a pool to allocate return buffer
+* @return <code>APR_SUCCESS</code> if OK; otherwise, an error code.
 */
 APR_DECLARE(apr_status_t) port_user_home(char** path,
                              apr_pool_t* pool);
 
 /**
- * Returns name of current system time zone.
+ * Returns the name of current system time zone. Time zone names are defined 
+ * in the <i>tz</i> database, see ftp://elsie.nci.nih.gov/pub/.
+ * @param[out] tzname - the pointer to the name string
+ * @param pool        - a pool to allocate return buffer
+ * @return <code>APR_SUCCESS</code> if OK; otherwise, an error code.
  */
 APR_DECLARE(apr_status_t) port_user_timezone(char** tzname,
                                              apr_pool_t* pool);
+
+/** @} */
+
 
 #ifdef __cplusplus
 }

Modified: harmony/enhanced/drlvm/trunk/vm/port/include/port_timer.h
URL: http://svn.apache.org/viewvc/harmony/enhanced/drlvm/trunk/vm/port/include/port_timer.h?view=diff&rev=521341&r1=521340&r2=521341
==============================================================================
--- harmony/enhanced/drlvm/trunk/vm/port/include/port_timer.h (original)
+++ harmony/enhanced/drlvm/trunk/vm/port/include/port_timer.h Thu Mar 22 09:54:16 2007
@@ -27,17 +27,33 @@
 extern "C" {
 #endif
 
+/**
+* @file
+* High resolution timer
+*/
+
+/**
+ * @defgroup port_timer High resolution timer
+ * @ingroup port_apr
+ * @{
+ */
+
     /**
-     * High resolution timer, in nanoseconds.
+     * High resolution timer, in nanoseconds. 
+     * The timer is not tied to system clocks, rather intended for precise 
+     * measuring of elapsed time intervals.
      */
     typedef apr_int64_t apr_nanotimer_t;
 
     /**
     * Returns the value of the system timer with the best possible accuracy.
-    * This value is not tied to the absolute time, but intended for precise 
-    * measuring of elapsed time intervals.
+    * The difference between two subsequent invocations returns the number of
+    * passed nanoseconds.
     */
     APR_DECLARE(apr_nanotimer_t) port_nanotimer();
+
+/** @} */
+
 
 #ifdef __cplusplus
 }

Modified: harmony/enhanced/drlvm/trunk/vm/port/include/port_vmem.h
URL: http://svn.apache.org/viewvc/harmony/enhanced/drlvm/trunk/vm/port/include/port_vmem.h?view=diff&rev=521341&r1=521340&r2=521341
==============================================================================
--- harmony/enhanced/drlvm/trunk/vm/port/include/port_vmem.h (original)
+++ harmony/enhanced/drlvm/trunk/vm/port/include/port_vmem.h Thu Mar 22 09:54:16 2007
@@ -21,6 +21,13 @@
 
 #ifndef _PORT_VMEM_H_
 #define _PORT_VMEM_H_
+/**
+ * @file
+ * Virtual memory support
+ *
+ * Functions to manipulate memory pages in virtual address space: 
+ * reserve, de/commit, free, control size and access protection of pages.
+ */
 
 #include "port_general.h"
 #include <apr_pools.h>
@@ -28,34 +35,61 @@
 #ifdef __cplusplus
 extern "C" {
 #endif
+/** @defgroup port_apr Portability layer */
+
+/**
+ * @defgroup port_vmem Virtual memory support
+ * @ingroup port_apr
+ * @{
+ */
 
+/**
+ * @defgroup vmem_protection Memory protection flags
+ * @{
+ */
+/** Enabling read access to the committed memory region */
 #define PORT_VMEM_MODE_READ 0x1
+/** Enabling write access to the committed memory region */
 #define PORT_VMEM_MODE_WRITE 0x2
+/** Enabling read access to the committed memory region */
 #define PORT_VMEM_MODE_EXECUTE 0x4
+/** @} */
 
+/**
+ * @defgroup vmem_size Memory page size directives
+ * These defines can be used instead of explicit calls to <code>port_vmem_page_sizes()</code>.
+ * @{
+ */
+/** System default page size*/
 #define PORT_VMEM_PAGESIZE_DEFAULT 0
+/** Large page (if supported by system) */
 #define PORT_VMEM_PAGESIZE_LARGE 1
+/** @} */
 
 /**
- * Virtual memory block descriptor. Incomplete type, 
- * runtime instance should be obtained via port_vmem_reserve() call
+ * Virtual memory block descriptor. This is an <i>incomplete type</i>, 
+ * the run-time instance should be obtained via port_vmem_reserve() call
  */
 typedef struct port_vmem_t port_vmem_t;
 
 /**
  * Reserves a continuous memory region in the virtual address space 
- * of the calling process.
- * @param[in,out] block descriptor for the reserved memory, required for 
- * further operations with the memory
- * @param[in,out] address starting address of the region to allocate. If null,
- * system will determine appropriate location. Actual allocated address is 
- * returned on success
- * @param amount size of the region in bytes. For large pages, size must be 
- * multiply of page size. See port_vmem_page_sizes()
- * @param protectionMode bit mask of PORT_VMEM_MODE_* values
- * @param pageSize desired size of memory page. Value should be either
- * any of PORT_VMEM_PAGESIZE_* flags or actual size in bytes.
- * @param pool auxiliary pool
+ * of the calling process. 
+ * @param[out] block      - descriptor for the reserved memory, required for 
+ *                          further operations with the memory
+ * @param[in,out] address - desired starting address of the region to allocate. If
+ *                          <code>NULL</code>, the system determines the
+ *                          appropriate location.On success, the actual
+ *                          allocated address is returned
+ * @param amount          - the size of the region in bytes. For large pages,
+                            the size must be multiply of page size
+ * @param protectionMode  - the bit mask of <code>PORT_VMEM_MODE_*</code> flags
+ * @param pageSize        - the desired size of the memory page; should contain 
+ *                          <code>PORT_VMEM_PAGESIZE_DEFAULT</code>,
+ *                          <code>PORT_VMEM_PAGESIZE_LARGE</code> or the actual size in bytes
+ * @param pool            - the auxiliary pool to allocate the descriptor data, etc
+ * @return <code>APR_SUCCESS</code> if OK; otherwise, an error code.
+ * @see port_vmem_page_sizes()
  */
 APR_DECLARE(apr_status_t) port_vmem_reserve(port_vmem_t **block, void **address, 
                                            size_t amount, 
@@ -63,37 +97,45 @@
                                            size_t pageSize, apr_pool_t *pool);
 
 /**
-* Commits (part of) previously reserved memory region.
-* @param[in,out] address starting address of the region to commit. Returned value 
-* may differ due to page-alignment.
-* @param amount size of the region in bytes
-* @param block descriptor to the reserved virtual memory
+* Commits (a part of) the previously reserved memory region. The allocated memory 
+* is initialized to zero.
+* @param[in,out] address - the starting address of the region to commit; the returned value 
+*                          may differ due to page alignment
+* @param amount          - the size of the region in bytes
+* @param block           - the descriptor to the reserved virtual memory
+* @return <code>APR_SUCCESS</code> if OK; otherwise, an error code.
 */
 APR_DECLARE(apr_status_t) port_vmem_commit(void **address, size_t amount, 
                                           port_vmem_t *block);
 
 /**
 * Decommits the specified region of committed memory. It is safe to 
-* decommit reserved (but not committed) region.
+* decommit a reserved (but not committed) region.
+* @param address - the starting address of the region to decommit
+* @param amount  - the size of the region in bytes
+* @param block   - the memory region descriptor
+* @return <code>APR_SUCCESS</code> if OK; otherwise, an error code.
 */
 APR_DECLARE(apr_status_t) port_vmem_decommit(void *address, size_t amount, 
                                             port_vmem_t *block);
 
 /**
 * Releases previously reserved virtual memory region as a whole.
-* If the region was committed, function first decommits it.
+* If the region was committed, the function first decommits it.
+* @param block - the memory region descriptor
+* @return <code>APR_SUCCESS</code> if OK; otherwise, an error code.
 */
-APR_DECLARE(apr_status_t) port_vmem_release(/*void *address, size_t amount,*/
-                                           port_vmem_t *block);
+APR_DECLARE(apr_status_t) port_vmem_release(port_vmem_t *block);
 
 /**
-* Returns zero-terminated array of supported memory page sizes.
-* The first element refers to system default size and is guaranteed
+* Returns a zero-terminated array of supported memory page sizes.
+* The first element refers to the system default size and is guaranteed
 * to be non-zero. Subsequent elements (if any) provide large page
 * sizes.
 */
 APR_DECLARE(size_t *) port_vmem_page_sizes();
 
+/** @} */
 
 #ifdef __cplusplus
 }