From 91316f314deaecf2d69ee70090d9a1474ade7923 Mon Sep 17 00:00:00 2001 From: Achim Gsell Date: Thu, 17 Mar 2016 17:50:42 +0100 Subject: [PATCH] src/include/*: - update/review documentation - re-introduce old API functions --- doc/Doxyfile | 7 +- doc/H5.dox | 10 +- src/include/H5.h | 190 ++++++++++++++++++++++++++-------- src/include/H5Block_attribs.h | 75 ++------------ src/include/H5Block_io.h | 56 ++-------- src/include/H5Block_model.h | 61 +++-------- src/include/H5Part_io.h | 24 ++--- src/include/H5Part_model.h | 44 ++------ src/include/H5_attribs.h | 66 +++--------- src/include/H5_model.h | 42 ++------ src/include/H5hut.h | 4 + 11 files changed, 233 insertions(+), 346 deletions(-) diff --git a/doc/Doxyfile b/doc/Doxyfile index 8636d8a..3e1bf0f 100644 --- a/doc/Doxyfile +++ b/doc/Doxyfile @@ -1958,7 +1958,7 @@ PERLMOD_MAKEVAR_PREFIX = # C-preprocessor directives found in the sources and include files. # The default value is: YES. -ENABLE_PREPROCESSING = NO +ENABLE_PREPROCESSING = YES # If the MACRO_EXPANSION tag is set to YES, doxygen will expand all macro names # in the source code. If set to NO, only conditional compilation will be @@ -1967,7 +1967,7 @@ ENABLE_PREPROCESSING = NO # The default value is: NO. # This tag requires that the tag ENABLE_PREPROCESSING is set to YES. -MACRO_EXPANSION = NO +MACRO_EXPANSION = YES # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES then # the macro expansion is limited to the macros specified with the PREDEFINED and @@ -2007,7 +2007,8 @@ INCLUDE_FILE_PATTERNS = # recursively expanded use the := operator instead of the = operator. # This tag requires that the tag ENABLE_PREPROCESSING is set to YES. -PREDEFINED = PARALLEL_IO +PREDEFINED = PARALLEL_IO \ + H5HUT_API_VERSION=2 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this # tag can be used to specify a list of macro names that should be expanded. The diff --git a/doc/H5.dox b/doc/H5.dox index 7749867..904f3aa 100644 --- a/doc/H5.dox +++ b/doc/H5.dox @@ -45,12 +45,12 @@ For more information, please contact the \defgroup h5hut_error error handling @} - \defgroup h5hut_c_api H5 + \defgroup h5_c_api H5 @{ - \defgroup h5hut_file file handling - \defgroup h5hut_model setting up the data model - \defgroup h5hut_file_attribs reading and writing file attributes - \defgroup h5hut_step_attribs reading and writing step attributes + \defgroup h5_file file handling + \defgroup h5_model setting up the data model + \defgroup h5_file_attribs reading and writing file attributes + \defgroup h5_step_attribs reading and writing step attributes @} \defgroup h5part_c_api H5Part @{ diff --git a/src/include/H5.h b/src/include/H5.h index ebeae2e..4d7411a 100644 --- a/src/include/H5.h +++ b/src/include/H5.h @@ -15,15 +15,23 @@ #include "H5_model.h" #include "H5_attribs.h" +/** + \ingroup h5_c_api + \addtogroup h5_file + @{ +*/ + #ifdef __cplusplus extern "C" { #endif -/** - \ingroup h5hut_c_api - \addtogroup h5hut_file - @{ -*/ +#if H5HUT_API_VERSION == 2 +#define H5OpenFile2 H5OpenFile +#define H5SetVerbosityLevel2 H5SetVerbosityLevel +#elif H5HUT_API_VERSION == 1 +#define H5OpenFile1 H5OpenFile +#define H5SetVerbosityLevel1 H5SetVerbosityLevel +#endif /** Create a new, empty file property list. @@ -43,6 +51,11 @@ extern "C" { \see H5SetPropFileCoreVFD() \see H5SetPropFileAlign() \see H5SetPropFileThrottle() + + \note + | Release | Change | + | :------ | :----- | + | \c 1.99.15 | Function introduced in this release. | */ static inline h5_prop_t H5CreateFileProp ( @@ -56,36 +69,17 @@ H5CreateFileProp ( Stores MPI IO communicator information to given file property list. If used in \ref H5OpenFile(), MPI collective IO will be used. - \note H5SetPropFileMPIO() is deprecated. Use H5SetPropFileMPIOCollective() instead. - \return \c H5_SUCCESS on success \return \c H5_FAILURE on error \see H5SetPropFileMPIOIndependent() \see H5SetPropFileMPIOPosix() (HDF5 <= 1.8.12 only) \see H5SetPropFileCoreVFD() -*/ -static inline h5_err_t -H5SetPropFileMPIO ( - h5_prop_t prop, ///< [in,out] identifier for file property list - MPI_Comm* comm ///< [in] MPI communicator - ) { - H5_API_ENTER (h5_err_t, "prop=%p, comm=%p", (void*)prop, comm); - H5_API_RETURN (h5_set_prop_file_mpio_collective (prop, comm)); -} -/** - Stores MPI IO communicator information to given file property list. If used in - \ref H5OpenFile(), MPI collective IO will be used. - - \return \c H5_SUCCESS on success - \return \c H5_FAILURE on error - - \note This function deprecates H5SetPropFileMPIO(). - - \see H5SetPropFileMPIOIndependent() - \see H5SetPropFileMPIOPosix() (HDF5 <= 1.8.12 only) - \see H5SetPropFileCoreVFD() + \note + | Release | Change | + | :------ | :----- | + | \c 1.99.15 | Function introduced in this release. | */ static inline h5_err_t H5SetPropFileMPIOCollective ( @@ -106,6 +100,11 @@ H5SetPropFileMPIOCollective ( \see H5SetPropFileMPIOCollective() \see H5SetPropFileMPIOPosix() (HDF5 <= 1.8.12 only) \see H5SetPropFileCoreVFD() + + \note + | Release | Change | + | :------ | :----- | + | \c 1.99.15 | Function introduced in this release. | */ static inline h5_err_t H5SetPropFileMPIOIndependent ( @@ -125,12 +124,17 @@ H5SetPropFileMPIOIndependent ( \return \c H5_SUCCESS on success \return \c H5_FAILURE on error - \note This function is available only, if H5hut has been compiled with - HDF5 1.8.12 or older. - \see H5SetPropFileMPIOCollective() \see H5SetPropFileMPIOIndependent() \see H5SetPropFileCoreVFD() + + \note This function is available only, if H5hut has been compiled with + HDF5 1.8.12 or older. + + \note + | Release | Change | + | :------ | :----- | + | \c 1.99.15 | Function introduced in this release. | */ static inline h5_err_t H5SetPropFileMPIOPosix ( @@ -152,6 +156,11 @@ H5SetPropFileMPIOPosix ( \return \c H5_SUCCESS on success \return \c H5_FAILURE on error + + \note + | Release | Change | + | :------ | :----- | + | \c 1.99.15 | Function introduced in this release. | */ static inline h5_err_t H5SetPropFileCoreVFD ( @@ -181,13 +190,19 @@ H5SetPropFileCoreVFD ( \return \c H5_FAILURE on error \see H5SetPropFileCoreVFD() + + \note + | Release | Change | + | :------ | :----- | + | \c 1.99.15 | Function introduced in this release. | */ static inline h5_err_t H5SetPropFileAlign ( h5_prop_t prop, ///< [in,out] identifier for file property list h5_int64_t align ///< [in] alignment ) { - H5_API_ENTER (h5_err_t, "prop=%p, align=%lld", (void*)prop, (long long int)align); + H5_API_ENTER (h5_err_t, "prop=%p, align=%lld", + (void*)prop, (long long int)align); H5_API_RETURN (h5_set_prop_file_align (prop, align)); } @@ -205,18 +220,29 @@ H5SetPropFileAlign ( \return \c H5_SUCCESS on success \return \c H5_FAILURE on error + + \note + | Release | Change | + | :------ | :----- | + | \c 1.99.15 | Function introduced in this release. | */ static inline h5_err_t H5SetPropFileThrottle ( h5_prop_t prop, ///< [in,out] identifier for file property list h5_int64_t throttle ///< [in] throttle factor ) { - H5_API_ENTER (h5_err_t, "prop=%p, throttle=%lld", (void*)prop, (long long int)throttle); + H5_API_ENTER (h5_err_t, "prop=%p, throttle=%lld", + (void*)prop, (long long int)throttle); H5_API_RETURN (h5_set_prop_file_throttle (prop, throttle)); } /** Close file property list. + + \note + | Release | Change | + | :------ | :----- | + | \c 1.99.15 | Function introduced in this release. | */ static inline h5_err_t H5CloseProp ( @@ -234,9 +260,9 @@ H5CloseProp ( - \c H5_O_WRONLY: create new file, dataset must not exist - \c H5_O_APPENDONLY: allows to append new data to an existing file - \c H5_O_RDWR: dataset may exist - - \c H5_FS_LUSTRE - enable optimizations for the Lustre file system - - \c H5_VFD_MPIO_POSIX - use the HDF5 MPI-POSIX virtual file driver - - \c H5_VFD_MPIO_INDEPENDENT - use MPI-IO in indepedent mode + - \c H5_FS_LUSTRE: enable optimizations for the Lustre file system + - \c H5_VFD_MPIO_POSIX: use the HDF5 MPI-POSIX virtual file driver + - \c H5_VFD_MPIO_INDEPENDENT: use MPI-IO in indepedent mode The file is opened with the properties set in the file property list \c prop. This argument can also be set to \c H5_PROP_DEFAULT to use @@ -249,9 +275,13 @@ H5CloseProp ( \return \c H5_FAILURE on error \see H5CreateFileProp() + + | Release | Change | + | :------ | :----- | + | \c 1.99.15 | API changed, old implementation is available as \c H5OpenFile1() | */ static inline h5_file_t -H5OpenFile ( +H5OpenFile2 ( const char* filename, ///< [in] name of file h5_int64_t mode, ///< [in] file mode h5_prop_t props ///< [in] identifier for file property list @@ -262,6 +292,41 @@ H5OpenFile ( H5_API_RETURN (h5_open_file2 (filename, mode, props)); } +/** + Open file with name \c filename. + + File mode flags are: + - \c H5_O_RDONLY: Only reading allowed + - \c H5_O_WRONLY: create new file, dataset must not exist + - \c H5_O_APPENDONLY: allows to append new data to an existing file + - \c H5_O_RDWR: dataset may exist + - \c H5_FS_LUSTRE - enable optimizations for the Lustre file system + - \c H5_VFD_MPIO_POSIX - use the HDF5 MPI-POSIX virtual file driver + (hdf5 <= 1.8.12 only) + - \c H5_VFD_MPIO_INDEPENDENT - use MPI-IO in indepedent mode + + In the serial version of H5hut, \c comm can be set to any value. + + \return File handle. + \return (h5_file_p*)H5_FAILURE + + \note This function is deprecated! + + \note + | Release | Change | + | :------ | :----- | + | \c 1.99.15 | Old implementation of \c H5OpenFile() | +*/ +static inline h5_file_p +H5OpenFile1 ( + const char* filename, ///< [in] file name + h5_int32_t flags, ///< [in] file open flags + MPI_Comm comm ///< [in] MPI communicator + ) { + H5_API_ENTER (h5_file_p, "filename='%s', flags=%d, ...",filename,flags); + H5_API_RETURN (h5_open_file (filename, flags, comm, 0)); +} + /** Close file and free all memory associated with the file handle. @@ -348,7 +413,7 @@ H5Finalize ( \addtogroup h5hut_verbosity @{ */ - + /** Set verbosity level to \c level. @@ -358,17 +423,44 @@ H5Finalize ( - \c H5_VERBOSE_WARN: output error messages and warning - \c H5_VERBOSE_INFO: output error messages, warnings and informational messages - The default verbosity level ist \c H5_VERBOSE_ERROR. + The default verbosity level is \c H5_VERBOSE_ERROR. + + \return \c H5_SUCCESS + + \see H5GetVerbosityLevel() + + \note + | Release | Change | + | :------ | :----- | + | \c 1.99.15 | Function cannot be used to set the debug level. | +*/ +static inline h5_err_t +H5SetVerbosityLevel2 ( + const h5_id_t level ///< [in] verbosity level. + ) { + return h5_set_debuglevel (level & 0x03); +} + +/** + Set verbosity and debug level to \p level. + + Verbosity levels are: + - \c H5_VERBOSE_NONE: be quiet + - \c H5_VERBOSE_ERROR: output error messages + - \c H5_VERBOSE_WARN: output error messages and warning + - \c H5_VERBOSE_INFO: output error messages, warnings and informational messages + + The default verbosity level is \c H5_VERBOSE_ERROR. \return \c H5_SUCCESS \see H5GetVerbosityLevel() */ static inline h5_err_t -H5SetVerbosityLevel ( +H5SetVerbosityLevel1 ( const h5_id_t level ///< [in] verbosity level. ) { - return h5_set_debuglevel (level & 0x03); + return h5_set_debuglevel (level); } /** @@ -396,7 +488,7 @@ H5GetVerbosityLevel ( Set debug mask. The debug mask is an or'ed value of - \c H5_DEBUG_API: C-API calls - - \c H5_DEBUG_CORE_API: core API calls. The core API is used by the C- and Fortran API. + - \c H5_DEBUG_CORE_API: core API calls. - \c H5_DEBUG_PRIV_API: private API calls - \c H5_DEBUG_PRIV_FUNC: static functions - \c H5_DEBUG_HDF5: HDF5 wrapper calls @@ -407,6 +499,11 @@ H5GetVerbosityLevel ( \return \c H5_SUCCESS \see H5GetDebugMask() + + \note + | Release | Change | + | :------ | :----- | + | \c 1.99.15 | Function introduced in this release. | */ static inline h5_err_t H5SetDebugMask ( @@ -421,6 +518,11 @@ H5SetDebugMask ( \return debug mask \see H5SetDebugMask() + + \note + | Release | Change | + | :------ | :----- | + | \c 1.99.15 | Function introduced in this release. | */ static inline h5_id_t H5GetDebugMask ( @@ -560,10 +662,10 @@ H5GetErrno ( return h5_get_errno (); } -///< @} - #ifdef __cplusplus } #endif +///< @} + #endif diff --git a/src/include/H5Block_attribs.h b/src/include/H5Block_attribs.h index e884038..2f584e0 100644 --- a/src/include/H5Block_attribs.h +++ b/src/include/H5Block_attribs.h @@ -16,14 +16,18 @@ #include "h5core/h5.h" #include "h5core/h5_debug.h" #include "h5core/h5b_attribs.h" + +/** + \ingroup h5block_c_api + \addtogroup h5block_attrib + @{ +*/ + #ifdef __cplusplus extern "C" { #endif /** - \ingroup h5block_attrib - \anchor H5BlockGetNumFieldAttribs - Query the number of attributes of field \c field_name. \return number of attributes @@ -41,9 +45,6 @@ H5BlockGetNumFieldAttribs ( } /** - \ingroup h5block_attrib - \anchor H5BlockGetFieldAttribInfo - Gets the name, type and number of elements of the field attribute specified by its index. @@ -91,9 +92,6 @@ H5BlockGetFieldAttribInfo ( /********************** reading and writing attribute ************************/ /** - \ingroup h5block_attrib - \anchor H5BlockWriteFieldAttribString - Write the string in \c buffer as attribute \c attrib_name of field \c field_name. @@ -127,9 +125,6 @@ H5BlockWriteFieldAttribString ( } /** - \ingroup h5block_attrib - \anchor H5BlockReadFieldAttribString ( - Read the string value from attribute \c attrib_name of field \c field_name into \c buffer. @@ -163,9 +158,6 @@ H5BlockReadFieldAttribString ( /** - \ingroup h5block_attrib - \anchor H5BlockWriteFieldAttribFloat64 - Write float64 \c values as attribute \c attrib_name of field \c field_name. @@ -195,9 +187,6 @@ H5BlockWriteFieldAttribFloat64 ( } /** - \ingroup h5block_attrib - \anchor H5BlockReadFieldAttribFloat64 - Read float64 values from attribute \c attrib_name of field \c field_name into a \c buffer. @@ -225,9 +214,6 @@ H5BlockReadFieldAttribFloat64 ( /** - \ingroup h5block_attrib - \anchor H5BlockWriteFieldAttribFloat32 - Write float32 \c values as attribute \c attrib_name of field \c field_name. @@ -257,9 +243,6 @@ H5BlockWriteFieldAttribFloat32 ( } /** - \ingroup h5block_attrib - \anchor H5BlockReadFieldAttribFloat32 - Read float32 values from attribute \c attrib_name of field \c field_name into a \c buffer. @@ -286,9 +269,6 @@ H5BlockReadFieldAttribFloat32 ( } /** - \ingroup h5block_attrib - \anchor H5BlockWriteFieldAttribInt64 - Write int64 \c values as attribute \c attrib_name of field \c field_name. @@ -317,9 +297,6 @@ H5BlockWriteFieldAttribInt64 ( } /** - \ingroup h5block_attrib - \anchor H5BlockReadFieldAttribInt64 - Read int64 values from attribute \c attrib_name of field \c field_name into a \c buffer. @@ -347,9 +324,6 @@ H5BlockReadFieldAttribInt64 ( /** - \ingroup h5block_attrib - \anchor H5BlockWriteFieldAttribInt32 - Write int32 \c values as attribute \c attrib_name of field \c field_name. @@ -379,9 +353,6 @@ H5BlockWriteFieldAttribInt32 ( } /** - \ingroup h5block_attrib - \anchor H5BlockReadFieldAttribInt32 - Read int32 values from attribute \c attrib_name of field \c field_name into a \c buffer. @@ -407,9 +378,6 @@ H5BlockReadFieldAttribInt32 ( } /** - \ingroup h5block_attrib - \anchor H5Block3dGetFieldOrigin - Get field origin. \return \c H5_SUCCESS on success @@ -443,9 +411,6 @@ H5Block3dGetFieldOrigin ( } /** - \ingroup h5block_attrib - \anchor H5Block3dSetFieldOrigin - Set field origin. \return \c H5_SUCCESS on success @@ -473,9 +438,6 @@ H5Block3dSetFieldOrigin ( } /** - \ingroup h5block_attrib - \anchor H5Block3dGetFieldSpacing - Get field spacing for field \c field_name in the current time step. \return \c H5_SUCCESS on success @@ -507,9 +469,6 @@ H5Block3dGetFieldSpacing ( } /** - \ingroup h5block_attrib - \anchor H5Block3dSetFieldSpacing - Set field spacing for field \c field_name in the current time step. \return \c H5_SUCCESS on success @@ -537,9 +496,6 @@ H5Block3dSetFieldSpacing ( } /** - \ingroup h5block_attrib - \anchor H5Block3dSetFieldXCoords - Set an explicit list of X coordinates for field \c field_name in the current time step. The coordinates are a 1D array of floating point values with dimension \c n_coords. @@ -571,9 +527,6 @@ H5Block3dSetFieldXCoords ( /** - \ingroup h5block_attrib - \anchor H5Block3dGetFieldXCoords - Get the explicit list of X coordinates for field \c field_name in the current time step. The coordinates are read into the 1D array \c coords which has length \c n_coords. @@ -604,9 +557,6 @@ H5Block3dGetFieldXCoords ( } /** - \ingroup h5block_attrib - \anchor H5Block3dSetFieldYCoords - Set an explicit list of Y coordinates for field \c field_name in the current time step. The coordinates are a 1D array of floating point values with dimension \c n_coords. @@ -638,9 +588,6 @@ H5Block3dSetFieldYCoords ( /** - \ingroup h5block_attrib - \anchor H5Block3dGetFieldYCoords - Get the explicit list of Y coordinates for field \c field_name in the current time step. The coordinates are read into the 1D array \c coords which has length \c n_coords. @@ -671,9 +618,6 @@ H5Block3dGetFieldYCoords ( } /** - \ingroup h5block_attrib - \anchor H5Block3dSetFieldZCoords - Set an explicit list of Z coordinates for field \c field_name in the current time step. The coordinates are a 1D array of floating point values with dimension \c n_coords. @@ -705,9 +649,6 @@ H5Block3dSetFieldZCoords ( /** - \ingroup h5block_attrib - \anchor H5Block3dGetFieldZCoords - Get the explicit list of Z coordinates for field \c field_name in the current time step. The coordinates are read into the 1D array \c coords which has length \c n_coords. @@ -741,4 +682,6 @@ H5Block3dGetFieldZCoords ( } #endif +///< @} + #endif diff --git a/src/include/H5Block_io.h b/src/include/H5Block_io.h index e8cf402..d070b38 100644 --- a/src/include/H5Block_io.h +++ b/src/include/H5Block_io.h @@ -15,13 +15,17 @@ #include "h5core/h5_debug.h" #include "h5core/h5b_io.h" +/** + \ingroup h5block_c_api + \addtogroup h5block_io + @{ +*/ + #ifdef __cplusplus extern "C" { #endif /** - \ingroup h5block_io - Attempts to write the 3-dimensional field \p name from the buffer pointed to by \p buffer to the current step using the previously defined field view. @@ -48,9 +52,6 @@ H5Block3dWriteScalarFieldFloat64 ( } /** - \ingroup h5block_io - \anchor H5Block3dReadScalarFieldFloat64 - Read a 3-dimensional field \c name into the buffer starting at \c data from the current time-step using the defined field layout. Values are floating points (64-bit). @@ -74,9 +75,6 @@ H5Block3dReadScalarFieldFloat64 ( } /** - \ingroup h5block_io - \anchor H5Block3dWriteVector3dFieldFloat64 - Write a 3-dimensional field \c name with 3-dimensional vectors as values from the buffers starting at \c x_buf, \c y_buf and \c z_buf to the current time-step using the defined field layout. Values are 3-dimensional @@ -104,9 +102,6 @@ H5Block3dWriteVector3dFieldFloat64 ( } /** - \ingroup h5block_io - \anchor H5Block3dReadVector3dFieldFloat64 - Read a 3-dimensional field \c name with 3-dimensional vectors as values from the buffers starting at \c x_buf, \c y_buf and \c z_buf to the current time-step using the defined field layout. Values are 3-dimensional @@ -135,9 +130,6 @@ H5Block3dReadVector3dFieldFloat64 ( /** - \ingroup h5block_io - \anchor H5Block3dWriteScalarFieldFloat32 - Write a 3-dimensional field \c name from the buffer starting at \c data to the current time-step using the defined field layout. Values are floating points (32-bit). @@ -161,9 +153,6 @@ H5Block3dWriteScalarFieldFloat32 ( } /** - \ingroup h5block_io - \anchor H5Block3dReadScalarFieldFloat32 - Read a 3-dimensional field \c name into the buffer starting at \c data from the current time-step using the defined field layout. Values are floating points (32-bit). @@ -187,9 +176,6 @@ H5Block3dReadScalarFieldFloat32 ( } /** - \ingroup h5block_io - \anchor H5Block3dWriteVector3dFieldFloat32 - Write a 3-dimensional field \c name with 3-dimensional vectors as values from the buffers starting at \c x_buf, \c y_buf and \c z_buf to the current time-step using the defined field layout. Values are 3-dimensional @@ -217,9 +203,6 @@ H5Block3dWriteVector3dFieldFloat32 ( } /** - \ingroup h5block_io - \anchor H5Block3dReadVector3dFieldFloat32 - Read a 3-dimensional field \c name with 3-dimensional vectors as values from the buffers starting at \c x_buf, \c y_buf and \c z_buf to the current time-step using the defined field layout. Values are 3-dimensional @@ -248,9 +231,6 @@ H5Block3dReadVector3dFieldFloat32 ( /** - \ingroup h5block_io - \anchor H5Block3dWriteScalarFieldInt64 - Write a 3-dimensional field \c name from the buffer starting at \c data to the current time-step using the defined field layout. Values are integers (64-bit). @@ -274,9 +254,6 @@ H5Block3dWriteScalarFieldInt64 ( } /** - \ingroup h5block_io - \anchor H5Block3dReadScalarFieldInt64 - Read a 3-dimensional field \c name into the buffer starting at \c data from the current time-step using the defined field layout. Values are integers (64-bit). @@ -301,9 +278,6 @@ H5Block3dReadScalarFieldInt64 ( /** - \ingroup h5block_io - \anchor H5Block3dWriteVector3dFieldInt64 - Write a 3-dimensional field \c name with 3-dimensional vectors as values from the buffers starting at \c x_buf, \c y_buf and \c z_buf to the current time-step using the defined field layout. Values are 3-dimensional @@ -331,9 +305,6 @@ H5Block3dWriteVector3dFieldInt64 ( } /** - \ingroup h5block_io - \anchor H5Block3dReadVector3dFieldInt64 - Read a 3-dimensional field \c name with 3-dimensional vectors as values from the buffers starting at \c x_buf, \c y_buf and \c z_buf to the current time-step using the defined field layout. Values are 3-dimensional @@ -362,9 +333,6 @@ H5Block3dReadVector3dFieldInt64 ( /** - \ingroup h5block_io - \anchor H5Block3dWriteScalarFieldInt32 - Write a 3-dimensional field \c name from the buffer starting at \c data to the current time-step using the defined field layout. Values are integers (32-bit). @@ -388,9 +356,6 @@ H5Block3dWriteScalarFieldInt32 ( } /** - \ingroup h5block_io - \anchor H5Block3dReadScalarFieldInt32 - Read a 3-dimensional field \c name into the buffer starting at \c data from the current time-step using the defined field layout. Values are integers (32-bit). @@ -415,9 +380,6 @@ H5Block3dReadScalarFieldInt32 ( /** - \ingroup h5block_io - \anchor H5Block3dWriteVector3dFieldInt32 - Write a 3-dimensional field \c name with 3-dimensional vectors as values from the buffers starting at \c x_buf, \c y_buf and \c z_buf to the current time-step using the defined field layout. Values are 3-dimensional @@ -445,9 +407,6 @@ H5Block3dWriteVector3dFieldInt32 ( } /** - \ingroup h5block_io - \anchor H5Block3dReadVector3dFieldInt32 - Read a 3-dimensional field \c name with 3-dimensional vectors as values from the buffers starting at \c x_buf, \c y_buf and \c z_buf to the current time-step using the defined field layout. Values are 3-dimensional @@ -474,9 +433,10 @@ H5Block3dReadVector3dFieldInt32 ( x_buf, y_buf, z_buf, H5T_NATIVE_INT32)); } - #ifdef __cplusplus } #endif +///< @} + #endif diff --git a/src/include/H5Block_model.h b/src/include/H5Block_model.h index 552cc7a..7b31dc3 100644 --- a/src/include/H5Block_model.h +++ b/src/include/H5Block_model.h @@ -15,6 +15,12 @@ #include "h5core/h5_debug.h" #include "h5core/h5b_model.h" +/** + \ingroup h5block_c_api + \addtogroup h5block_model + @{ +*/ + #ifdef __cplusplus extern "C" { #endif @@ -22,14 +28,11 @@ extern "C" { /********************** defining the layout **********************************/ /** - \ingroup h5block_model - \anchor H5BlockHasFieldData - Checks whether the current time-step has field data or not. - \return \c H5_OK if field data is available - \return \c H5_NOK if no field data is available - \return \c H5_FAILURE on error + \return true (value \c >0) if step exists + \return false (\c 0) if step does not exist + \return \c H5_FAILURE on error */ static inline h5_err_t H5BlockHasFieldData ( @@ -42,15 +45,12 @@ H5BlockHasFieldData ( } /** - \ingroup h5block_model - \anchor H5Block3dHasView - Tests whether a view has been set, either directly with \ref H5Block3dSetView or indirectly with \ref H5Block3dSetGrid. - \return \c H5_OK if field data is available - \return \c H5_NOK if no field data is available - \return \c H5_FAILURE on error + \return true (value \c >0) if step exists + \return false (\c 0) if step does not exist + \return \c H5_FAILURE on error */ static inline h5_int64_t H5Block3dHasView ( @@ -63,9 +63,6 @@ H5Block3dHasView ( } /** - \ingroup h5block_model - \anchor H5Block3dSetView - Defines the partition of the field that this processor owns, using Fortran ordering: the fastest moving index is \c i. @@ -103,8 +100,6 @@ H5Block3dSetView ( } /** - \ingroup h5block_model - \anchor H5Block3dGetView Return the view of this processor. \return \c H5_SUCCESS on success @@ -133,9 +128,6 @@ H5Block3dGetView ( } /** - \ingroup h5block_model - \anchor H5Block3dGetReducedView - Return the reduced (ghost-zone free) view of this processor. \return \c H5_SUCCESS on success @@ -164,9 +156,6 @@ H5Block3dGetReducedView ( } /** - \ingroup h5block_model - \anchor H5Block3dSetChunkSize - Define the chunk dimensions and enable chunking in the underlying HDF5 dataset. @@ -190,9 +179,6 @@ H5Block3dSetChunkSize ( } /** - \ingroup h5block_model - \anchor H5Block3dGetChunkSize - Lookup the chunk dimensions of the underlying HDF5 dataset. \return \c H5_SUCCESS on success @@ -214,9 +200,6 @@ H5Block3dGetChunkSize ( #ifdef PARALLEL_IO /** - \ingroup h5block_model - \anchor H5Block3dSetGrid - Define an underlying 3D Cartesian grid on the processors with dimensions (\c i,\c j,\c k). You can look up a processor's index into the grid using \ref H5Block3dGetGridCoords. @@ -246,9 +229,6 @@ H5Block3dSetGrid ( } /** - \ingroup h5block_model - \anchor H5Block3dGetGridCoords - Look up the index (\c i, \c j, \c k) in the grid belonging to MPI processor \c proc. @@ -270,9 +250,6 @@ H5Block3dGetGridCoords ( } /** - \ingroup h5block_model - \anchor H5Block3dSetDims - Set the dimensions of each processor's block when the field is a regular grid. @@ -300,9 +277,6 @@ H5Block3dSetDims ( #endif /** - \ingroup h5block_model - \anchor H5Block3dSetHalo - Sets the additional cells (\c i, \c j, \c k) in each direction to use as the `halo` region (or `ghost zone`) that overlaps between neighboring processors on the grid. @@ -330,9 +304,6 @@ H5Block3dSetHalo ( } /** - \ingroup h5block_model - \anchor H5BlockGetNumFields - Query number of fields in current time step. \return \c number of fields @@ -350,9 +321,6 @@ H5BlockGetNumFields ( /** - \ingroup h5block_model - \anchor H5BlockGetFieldInfo - Get the name, rank and dimensions of the field specified by the index \c idx. @@ -399,9 +367,6 @@ H5BlockGetFieldInfo ( } /** - \ingroup h5block_model - \anchor H5BlockGetFieldInfoByName - Get the rank and dimensions of the field specified by its name. \return \c H5_SUCCESS on success @@ -432,6 +397,8 @@ H5BlockGetFieldInfoByName ( type)); } +///< @} + #ifdef __cplusplus } #endif diff --git a/src/include/H5Part_io.h b/src/include/H5Part_io.h index 332416c..c443565 100644 --- a/src/include/H5Part_io.h +++ b/src/include/H5Part_io.h @@ -15,13 +15,17 @@ #include "h5core/h5_debug.h" #include "h5core/h5u_io.h" +/** + \ingroup h5part_c_api + \addtogroup h5part_io + @{ +*/ + #ifdef __cplusplus extern "C" { #endif /** - \ingroup h5part_io - Write array of 64 bit floating point data to file. After setting the number of elements with \c H5PartSetNumParticles() and @@ -59,8 +63,6 @@ H5PartWriteDataFloat64 ( } /** - \ingroup h5part_io - Write array of 32 bit floating point data to file. See \ref H5PartWriteDataFloat64() for more details. @@ -81,8 +83,6 @@ H5PartWriteDataFloat32 ( } /** - \ingroup h5part_io - Write array of 64 bit integer data to file. See \ref H5PartWriteDataFloat64() for more details. @@ -103,8 +103,6 @@ H5PartWriteDataInt64 ( } /** - \ingroup h5part_io - Write array of 32 bit integer data to file. See \ref H5PartWriteDataFloat64() for more details. @@ -125,8 +123,6 @@ H5PartWriteDataInt32 ( } /** - \ingroup h5part_io - Read array of 64 bit floating point data from file. See \ref H5PartWriteDataFloat64() for more details. @@ -147,8 +143,6 @@ H5PartReadDataFloat64 ( } /** - \ingroup h5part_io - Read array of 32 bit floating point data from file. See \ref H5PartWriteDataFloat64() for more details. @@ -169,8 +163,6 @@ H5PartReadDataFloat32 ( } /** - \ingroup h5part_io - Read array of 64 bit integer data from file. See \ref H5PartWriteDataFloat64() for more details. @@ -191,8 +183,6 @@ H5PartReadDataInt64 ( } /** - \ingroup h5part_io - Read array of 32 bit integer data from file. See \ref H5PartWriteDataFloat64() for more details. @@ -216,4 +206,6 @@ H5PartReadDataInt32 ( } #endif +///< @} + #endif diff --git a/src/include/H5Part_model.h b/src/include/H5Part_model.h index 57ddc11..45d1165 100644 --- a/src/include/H5Part_model.h +++ b/src/include/H5Part_model.h @@ -15,13 +15,17 @@ #include "h5core/h5_debug.h" #include "h5core/h5u_model.h" +/** + \ingroup h5part_c_api + \addtogroup h5part_model + @{ +*/ + #ifdef __cplusplus extern "C" { #endif /** - \ingroup h5part_model - Set the number of points/particles for the current time-step. After you call this subroutine, all subsequent operations will assume this number of particles will be written. @@ -60,8 +64,6 @@ H5PartSetNumPoints ( } /** - \ingroup h5part_model - \see H5PartSetNumPoints() */ static inline h5_err_t @@ -77,8 +79,6 @@ H5PartSetNumParticles ( } /** - \ingroup h5part_model - Set the number of particles for the current time-step. After you call this subroutine, all subsequent operations will assume this number of particles will be written. @@ -119,8 +119,6 @@ H5PartSetNumParticlesStrided ( } /** - \ingroup h5part_model - Define the chunk \c size and enables chunking in the underlying HDF5 layer. @@ -148,8 +146,6 @@ H5PartSetChunkSize ( } /** - \ingroup h5part_model - Get the number of datasets that are stored at the current time-step. \return number of datasets in current timestep @@ -166,8 +162,6 @@ H5PartGetNumDatasets ( } /** - \ingroup h5part_model - This reads the name of a dataset specified by it's index in the current time-step. @@ -194,8 +188,6 @@ H5PartGetDatasetName ( } /** - \ingroup h5part_model - Gets the name, type and number of elements of a dataset based on its index in the current timestep. @@ -232,8 +224,6 @@ H5PartGetDatasetInfo ( } /** - \ingroup h5part_model - This function returns the number of particles in this processor's view, if a view has been set. @@ -263,8 +253,6 @@ H5PartGetNumPoints ( } /** - \ingroup h5part_model - \see H5PartGetNumPoints() */ static inline h5_ssize_t @@ -278,8 +266,6 @@ H5PartGetNumParticles ( } /** - \ingroup h5part_model - Reset the view. \return \c H5_SUCCESS on success @@ -296,15 +282,13 @@ H5PartResetView ( } /** - \ingroup h5part_model - Check whether a view has been set, either automatically with \ref H5PartSetNumParticles() or manually with \ref H5PartSetView or \ref H5PartSetViewIndices. - \return \c H5_OK if view has been set. - \return \c H5_NOK if no view has been set. - \return \c H5_FAILURE on error. + \return true (value \c >0) if step exists + \return false (\c 0) if step does not exist + \return \c H5_FAILURE on error */ static inline h5_err_t H5PartHasView ( @@ -317,8 +301,6 @@ H5PartHasView ( } /** - \ingroup h5part_model - For parallel I/O or for subsetting operations on the datafile, this function allows you to define a subset of the total particle dataset to operate on. @@ -351,8 +333,6 @@ H5PartSetView ( } /** - \ingroup h5part_model - For parallel I/O or for subsetting operations on the datafile, this function allows you to define a subset of the total dataset to operate on by specifying a list of indices. @@ -387,8 +367,6 @@ H5PartSetViewIndices ( } /** - \ingroup h5part_model - Allows you to query the current view. Start and End will be \c -1 if there is no current view established. Use \c H5PartHasView() to see if the view is smaller than the @@ -410,8 +388,6 @@ H5PartGetView ( } /** - \ingroup h5part_model - If it is too tedious to manually set the start and end coordinates for a view, \c H5SetCanonicalView() will automatically select an appropriate domain decomposition of the data arrays for the degree @@ -434,4 +410,6 @@ H5PartSetCanonicalView ( } #endif +///< @} + #endif diff --git a/src/include/H5_attribs.h b/src/include/H5_attribs.h index 6d6f27e..897f395 100644 --- a/src/include/H5_attribs.h +++ b/src/include/H5_attribs.h @@ -17,6 +17,12 @@ #include "h5core/h5_debug.h" #include "h5core/h5_attribs.h" +/** + \ingroup h5_c_api + \addtogroup h5_file_attribs + @{ +*/ + #ifdef __cplusplus extern "C" { #endif @@ -36,8 +42,6 @@ extern "C" { */ /** - \ingroup h5hut_file_attribs - Gets the number of attributes in the file's root ("/"). \return Number of attributes @@ -54,8 +58,6 @@ H5GetNumFileAttribs ( } /** - \ingroup h5hut_file_attribs - Gets the name, type and number of elements of the file attribute specified by its index. @@ -95,8 +97,6 @@ H5GetFileAttribInfo ( } /** - \ingroup h5hut_file_attribs - Get the type and number of elements of the file attribute specified by its name. @@ -138,8 +138,6 @@ H5GetFileAttribInfoByName ( */ /** - \ingroup h5hut_file_attribs - Write an attribute \c name with the string \c value to the file root ("/"). @@ -164,8 +162,6 @@ H5WriteFileAttribString ( } /** - \ingroup h5hut_file_attribs - Read a string into a \c buffer from an attribute \c name in the file root ("/"). @@ -189,8 +185,6 @@ H5ReadFileAttribString ( } /** - \ingroup h5hut_file_attribs - Write an attribute \c name with float64 \c values to the file root ("/"). @@ -216,8 +210,6 @@ H5WriteFileAttribFloat64 ( } /** - \ingroup h5hut_file_attribs - Read float64 values into a \c buffer from an attribute \c name in the file root ("/"). @@ -242,8 +234,6 @@ H5ReadFileAttribFloat64 ( /** - \ingroup h5hut_file_attribs - Write an attribute \c name with float32 \c values to the file root ("/"). @@ -269,8 +259,6 @@ H5WriteFileAttribFloat32 ( } /** - \ingroup h5hut_file_attribs - Read float32 values into a \c buffer from an attribute \c name in the file root ("/"). @@ -294,8 +282,6 @@ H5ReadFileAttribFloat32 ( } /** - \ingroup h5hut_file_attribs - Write an attribute \c name with int64 \c values to the file root ("/"). @@ -321,8 +307,6 @@ H5WriteFileAttribInt64 ( } /** - \ingroup h5hut_file_attribs - Read int64 values into a \c buffer from an attribute \c name in the file root ("/"). @@ -346,8 +330,6 @@ H5ReadFileAttribInt64 ( } /** - \ingroup h5hut_file_attribs - Write an attribute \c name with int32 \c values to the file root ("/"). @@ -373,8 +355,6 @@ H5WriteFileAttribInt32 ( } /** - \ingroup h5hut_file_attribs - Read int32 values into a \c buffer from an attribute \c name in the file root ("/"). @@ -396,6 +376,13 @@ H5ReadFileAttribInt32 ( H5_INT32_T, (void*)buffer)); } +///< @} + +/** + \ingroup h5_c_api + \addtogroup h5_step_attribs + @{ +*/ /* _ _ _ _ _ _ @@ -413,8 +400,6 @@ H5ReadFileAttribInt32 ( */ /** - \ingroup h5hut_step_attribs - Gets the number of attributes bound to the current step. \return Number of attributes @@ -431,8 +416,6 @@ H5GetNumStepAttribs ( } /** - \ingroup h5hut_step_attribs - Gets the name, type and number of elements of the step attribute specified by its index. @@ -473,8 +456,6 @@ H5GetStepAttribInfo ( } /** - \ingroup h5hut_step_attribs - Gets the type and number of elements of the step attribute specified by its name. @@ -517,8 +498,6 @@ H5GetStepAttribInfoByName ( */ /** - \ingroup h5hut_step_attribs - Write an attribute \c name with the string \c value to the current timestep. @@ -543,8 +522,6 @@ H5WriteStepAttribString ( } /** - \ingroup h5hut_step_attribs - Read a string into a \c buffer from an attribute \c name in the current timestep. @@ -568,8 +545,6 @@ H5ReadStepAttribString ( } /** - \ingroup h5hut_step_attribs - Write an attribute \c name with float64 \c values to the current time step. @@ -595,8 +570,6 @@ H5WriteStepAttribFloat64 ( } /** - \ingroup h5hut_step_attribs - Read float64 values into a \c buffer from an attribute \c name in the current time step. @@ -620,8 +593,6 @@ H5ReadStepAttribFloat64 ( } /** - \ingroup h5hut_step_attribs - Write an attribute \c name with float32 \c values to the current time step. @@ -647,8 +618,6 @@ H5WriteStepAttribFloat32 ( } /** - \ingroup h5hut_step_attribs - Read float32 values into a \c buffer from an attribute \c name in the current time step. @@ -672,8 +641,6 @@ H5ReadStepAttribFloat32 ( } /** - \ingroup h5hut_step_attribs - Write an attribute \c name with int64 \c values to the current time step. @@ -699,8 +666,6 @@ H5WriteStepAttribInt64 ( } /** - \ingroup h5hut_step_attribs - Read int64 values into a \c buffer from an attribute \c name in the current time step. @@ -725,8 +690,6 @@ H5ReadStepAttribInt64 ( } /** - \ingroup h5hut_step_attribs - Write an attribute \c name with int32 \c values to the current time step. @@ -752,8 +715,6 @@ H5WriteStepAttribInt32 ( } /** - \ingroup h5hut_step_attribs - Read int32 values into a \c buffer from an attribute \c name in the current time step. @@ -776,6 +737,7 @@ H5ReadStepAttribInt32 ( (void*)buffer)); } +///< @} #ifdef __cplusplus } diff --git a/src/include/H5_model.h b/src/include/H5_model.h index 5f29e07..d8e6f53 100644 --- a/src/include/H5_model.h +++ b/src/include/H5_model.h @@ -15,13 +15,17 @@ #include "h5core/h5_debug.h" #include "h5core/h5_model.h" +/** + \ingroup h5_c_api + \addtogroup h5_model + @{ +*/ + #ifdef __cplusplus extern "C" { #endif /** - \ingroup h5hut_model - Define format of the step names. Example: ==H5SetStepNameFormat( f, "Step", 6 )== defines step names @@ -43,8 +47,6 @@ H5SetStepNameFormat ( } /** - \ingroup h5hut_model - Get format of the step names. \return \c H5_SUCCESS on success @@ -64,8 +66,6 @@ H5GetStepNameFormat ( } /** - \ingroup h5hut_model - Set the current step. \return \c H5_SUCCESS on success @@ -83,8 +83,6 @@ H5SetStep ( } /** - \ingroup h5hut_model - Get current step. \return Step number @@ -101,8 +99,6 @@ H5GetStep ( } /** - \ingroup h5hut_model - Get the number of processors. \return Number of processors. @@ -119,8 +115,6 @@ H5GetNumProcs ( } /** - \ingroup h5hut_model - Get the number of time-steps that are currently stored in the file \c f. @@ -141,12 +135,10 @@ H5GetNumSteps ( } /** - \ingroup h5hut_model - Query whether a particular step already exists in the file. - \return \c H5_OK if step exists - \return \c H5NOK if step does not exist + \return true (value \c >0) if step exists + \return false (\c 0) if step does not exist \return \c H5_FAILURE on error */ static inline h5_err_t @@ -161,8 +153,6 @@ H5HasStep ( } /** - \ingroup h5hut_model - Start traversing steps. \note This function is not yet implemented! @@ -181,8 +171,6 @@ H5StartTraverseSteps ( } /** - \ingroup h5hut_model - Go to next step. \note This function is not yet implemented! @@ -201,8 +189,6 @@ H5TraverseSteps ( } /** - \ingroup h5hut_model - Return number of attached files. \return number of attachments. @@ -219,8 +205,6 @@ H5GetNumAttachments ( } /** - \ingroup h5hut_model - Get name and size of attachment given by index \c idx. Return the file name in \c fname and the original size in \c fsize. @@ -245,8 +229,6 @@ H5GetAttachmentInfoByIdx ( } /** - \ingroup h5hut_model - Get size of attached file with name \c fname. \return \c H5_SUCCESS on success @@ -264,8 +246,6 @@ H5GetAttachmentInfoByName ( } /** - \ingroup h5hut_model - Attach file \c fname. \return \c H5_SUCCESS on success @@ -281,8 +261,6 @@ H5AddAttachment ( } /** - \ingroup h5hut_model - Get attachment \c fname from H5hut file and write it to disk in the current working directory. @@ -299,8 +277,6 @@ H5GetAttachment ( } /** - \ingroup h5hut_model - Delete attachment \c fname. \return \c H5_SUCCESS on success @@ -319,6 +295,8 @@ H5DeleteAttachment ( } #endif +///< @} + #endif diff --git a/src/include/H5hut.h b/src/include/H5hut.h index fd17fad..ed67968 100644 --- a/src/include/H5hut.h +++ b/src/include/H5hut.h @@ -10,6 +10,10 @@ #ifndef __H5HUT_H #define __H5HUT_H +#if !defined(H5HUT_API_VERSION) +#define H5HUT_API_VERSION 2 +#endif + #include "H5.h" #include "H5Part.h" #include "H5Block.h"