diff options
author | Allen Byrne <50328838+byrnHDF@users.noreply.github.com> | 2022-03-31 13:23:35 (GMT) |
---|---|---|
committer | GitHub <noreply@github.com> | 2022-03-31 13:23:35 (GMT) |
commit | 9fdf9546541866f989b4f46aad6f6ac975563777 (patch) | |
tree | e56a66816abf1a6c16c9db2874d25b1c0dbeb3e8 /src/H5public.h | |
parent | dcdbeb7124c28f87d96bb9900f3d92e2a07bcd6b (diff) | |
download | hdf5-9fdf9546541866f989b4f46aad6f6ac975563777.zip hdf5-9fdf9546541866f989b4f46aad6f6ac975563777.tar.gz hdf5-9fdf9546541866f989b4f46aad6f6ac975563777.tar.bz2 |
1.8 Merge doxygen changes from develop (#1545)
* Merge doxygen changes from develop
* revert macro code change
* Format correction
Diffstat (limited to 'src/H5public.h')
-rw-r--r-- | src/H5public.h | 74 |
1 files changed, 55 insertions, 19 deletions
diff --git a/src/H5public.h b/src/H5public.h index 3c90c2a..aeb8664 100644 --- a/src/H5public.h +++ b/src/H5public.h @@ -11,19 +11,40 @@ * help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +/* + * This file contains public declarations for the HDF5 module. + */ +#ifndef H5public_H +#define H5public_H + /**\defgroup H5 H5 * * Use the functions in this module to manage the life cycle of HDF5 library * instances. * + * <table> + * <tr><th>Create</th><th>Read</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5_examples.c create + * </td> + * <td> + * \snippet{lineno} H5_examples.c read + * </td> + * <tr><th>Update</th><th>Delete</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5_examples.c update + * </td> + * <td> + * \snippet{lineno} H5_examples.c closing_shop + * \snippet{lineno} H5_examples.c delete + * </td> + * </tr> + * </table> + * */ -/* - * This file contains public declarations for the HDF5 module. - */ -#ifndef H5public_H -#define H5public_H - /* Include files for public use... */ /* * Since H5pubconf.h is a generated header file, it is messy to try @@ -63,6 +84,7 @@ #ifdef H5_HAVE_STDDEF_H #include <stddef.h> #endif + #ifdef H5_HAVE_PARALLEL /* Don't link against MPI C++ bindings */ #define MPICH_SKIP_MPICXX 1 @@ -199,8 +221,9 @@ extern "C" { * Status return values. Failed integer functions in HDF5 result almost * always in a negative value (unsigned failing functions sometimes return * zero for failure) while successful return is non-negative (often zero). - * The negative failure value is most commonly -1, but don't bet on it. The - * proper way to detect failure is something like: + * The negative failure value is most commonly -1, but don't bet on it. + * + * The proper way to detect failure is something like: * \code * if((dset = H5Dopen2(file, name)) < 0) * fprintf(stderr, "unable to open the requested dataset\n"); @@ -227,7 +250,14 @@ typedef int herr_t; typedef unsigned int hbool_t; typedef int htri_t; -/* Define the ssize_t type if it not is defined */ +/* The signed version of size_t + * + * ssize_t is POSIX and not defined in any C standard. It's used in some + * public HDF5 API calls so this work-around will define it if it's not + * present. + * + * Use of ssize_t should be discouraged in new code. + */ #if H5_SIZEOF_SSIZE_T == 0 /* Undefine this size, we will re-define it in one of the sections below */ #undef H5_SIZEOF_SSIZE_T @@ -245,8 +275,10 @@ typedef long long ssize_t; #endif #endif -/* int64_t type is used for creation order field for links. It may be - * defined in Posix.1g, otherwise it is defined here. +/** + * The size of file objects. + * + * \internal Defined as a (minimum) 64-bit integer type. */ #if H5_SIZEOF_INT64_T >= 8 #elif H5_SIZEOF_INT >= 8 @@ -291,9 +323,11 @@ typedef unsigned long long uint64_t; #error "nothing appropriate for uint64_t" #endif -/* - * The sizes of file objects have their own types defined here, use a minimum - * 64-bit type. +/** + * The size of file objects. Used when negative values are needed to indicate errors. + * + * \internal Defined as a (minimum) 64-bit integer type. Use of hssize_t + * should be discouraged in new code. */ #if H5_SIZEOF_LONG_LONG >= 8 H5_GCC_DIAG_OFF("long-long") @@ -313,8 +347,10 @@ H5_GCC_DIAG_ON("long-long") #error "nothing appropriate for hsize_t" #endif -/* - * File addresses have their own types. +/** + * The address of an object in the file. + * + * \internal Defined as a (minimum) 64-bit unsigned integer type. */ #if H5_SIZEOF_INT >= 8 typedef unsigned haddr_t; @@ -395,9 +431,9 @@ typedef enum { /* (Actually, any positive value will cause the iterator to stop and pass back * that positive value to the function that called the iterator) */ -#define H5_ITER_ERROR (-1) -#define H5_ITER_CONT (0) -#define H5_ITER_STOP (1) +#define H5_ITER_ERROR (-1) /**< Error, stop iteration */ +#define H5_ITER_CONT (0) /**< Continue iteration */ +#define H5_ITER_STOP (1) /**< Stop iteration, short-circuit success */ //! <!-- [H5_index_t_snip] --> /** |