diff options
author | Gerd Heber <gheber@hdfgroup.org> | 2021-04-26 19:07:29 (GMT) |
---|---|---|
committer | GitHub <noreply@github.com> | 2021-04-26 19:07:29 (GMT) |
commit | 1d680fe04c545d601678d876ad22dea7bfc31edd (patch) | |
tree | f84a97c149df9ccf4409c5bfea04a7316c019e8a /src/H5Tpublic.h | |
parent | 12082e728de7481144db7ea3cca6f38acf0a7cac (diff) | |
download | hdf5-1d680fe04c545d601678d876ad22dea7bfc31edd.zip hdf5-1d680fe04c545d601678d876ad22dea7bfc31edd.tar.gz hdf5-1d680fe04c545d601678d876ad22dea7bfc31edd.tar.bz2 |
Merge doxygen2 into develop (#553)
* Fixed warnings and started H5Epublic.h.
* Include H5FD* headers to correctly resolve references.
* Doxygen2 (#330)
* H5Eauto_is_v2.
* Added a few more calls.
* Added a few more H5E calls.
* First cut of H5E v2.
* Added the deprecated v1 calls.
* Updated spacing.
* Once more.
* Taking some inspiration from Eigen3.
* Add doxygen for the assigned functions: H5Pregister1,H5Pinsert1,H5Pen… (#352)
* Add doxygen for the assigned functions: H5Pregister1,H5Pinsert1,H5Pencode1, H5Pget_filter_by_id1,H5Pget_version, H5Pset_file_space,H5Pget_file_space. Someone already adds H5Pget_filter1. Also fixs an extra parameter 'close' call back function for HPregister2.
* doxygen work. fixs format by using clang-format.
* doxgen work for H5Pregister1 etc. Addressed Barbara and Gerd's comments.
For Quincey's comments, since we are not supposed to change the source code.
I leave this to future improvements.
* added documentation for H5P APIs (#350)
* add documenation for H5Pget_buffer,H5Pget_data_transform,H5Pget_edc_check,H5Pget_hyper_vector_size,H5Pget_preserve,H5Pget_type_conv_cb,H5Pget_vlen_mem_manager,H5Pset_btree_ratios
* format corrections
* fixed grammer
* fixed herr_t
* Better name.
* A fresh look.
* add doxygen to H5Ppublic.h
* use attention instead of warning
* Add doxygen comments in H5Ppublic.h (#375)
* Add doxygen comments in H5Ppublic.h
* H5Pset_meta_block_size
* H5Pset_metadata_read_attempts
* H5Pset_multi_type
* H5Pset_object_flush_cb
* H5Pset_sieve_buf_size
* H5Pset_small_data_block_size
* H5Pset_all_coll_metadata_ops
* H5Pget_all_coll_metadata_ops
* Add DOXYGEN_EXAMPLES_DIR to src/CMakeLists.txt
* Fix clang-format errors
* Fix filenames in doxygen/examples
* add doxygen to H5Ppublic.h (#378)
* add doxygen to H5Ppublic.h
* use attention instead of warning
Co-authored-by: Kimmy Mu <kmu@hdfgroup.org>
* Revert "add doxygen to H5Ppublic.h (#378)"
This reverts commit 2ee1821b138a5c00b15ea57ce9e950367480f5f2.
* Updated Doxygen variables.
* I forgot to copy two images.
* Enable desktop search by default.
* Add my assigned Doxygen documentation.
* Remove whitespace at EOL. Appease clang-format.
* Addressed Chris' comments.
* Added an alias for asynchronous functions.
* One space is enough for all of us.
* Slightly restructured RM page.
* address some issues
* reformatting
* Style external links.
* reformatting
* reformatting
* Added "Metadata Caching in HDF5" as a technical note example.
* Revise this soon!
* Added specification examples.
* Fixed references.
* Added H5AC cache image stuff and file format study.
* Added older FMT versions. Where did 1.0 go?
* Updated C/C++ note and replaced ambiguous labels.
* Reformat source with clang v10.0.1.
* Added the VFL technical note.
* Added what I believe might be called version 1.0 of the format.
* Added the remaining specs.
* Added H5Z callback documentation and fixed a few mistakes.
* Added dox for deprecated H5G calls and fixed a few snippet blockIDs.
* clang-format happy?
* Ok?
* Bonus track: Deprecated H5D functions.
* Carry over the more detailed group description.
* Added documentation for the missing and deprecated H5R calls.
* Life is easier and less repetitive w/ snippets. Use them!
* Eliminate the snippet block ID artifacts in the HTML rendering.
* Fixed snippet HTML artifacts and added a few missing calls.
* Under 20 H5Ps to go!
* Almost complete!
* "This is a form of pedantry up with which I will not put." (Churchill)
* Let's not waste as much space on bulleted lists!
* First complete (?) draft of the Doxygen-based RM.
* Completeness check and minor fixes along the way.
* Pedantry.
* Adding missing H5FD calls checkpoint.
* Pedantry.
* More pedantry.
* Added H5Pset_fapl_log.
* First draft of H5ES.
* Fixed warnings.
* Prep. for map module.
* First cut of the map module.
* Pedantry.
* Possible H5F introduction.
* Fix the indentation.
* Pedantry.
* Ditto.
* Thanks to the reviewers for their comments.
* Added missing images.
* Line numbers are a distraction here.
* More examples, references, and clean-up. Don't repeat yourself!
* Clang pedantry.
* Ditto.
* More reviewer comments...
* Templatized references and cleaned up \todos.
* Committing clang-format changes
* Fixed MANIFEST.
* Addressed Quincey's comments. (OCPLs)
* Fixed a few more \todo items.
* Fixed more \todo items.
* Added attribute life cycle.
* Forgot the examples file.
* Committing clang-format changes
* Pedantry.
* Live and learn!
* Added a sample H5D life cycle.
* Committing clang-format changes
* Pedantry.
Co-authored-by: kyang2014 <kyang2014@users.noreply.github.com>
Co-authored-by: Scot Breitenfeld <brtnfld@hdfgroup.org>
Co-authored-by: Kimmy Mu <kmu@hdfgroup.org>
Co-authored-by: Christopher Hogan <ChristopherHogan@users.noreply.github.com>
Co-authored-by: jya-kmu <53388330+jya-kmu@users.noreply.github.com>
Co-authored-by: David Young <dyoung@hdfgroup.org>
Co-authored-by: Larry Knox <lrknox@hdfgroup.org>
Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>
Diffstat (limited to 'src/H5Tpublic.h')
-rw-r--r-- | src/H5Tpublic.h | 114 |
1 files changed, 56 insertions, 58 deletions
diff --git a/src/H5Tpublic.h b/src/H5Tpublic.h index 1457053..5301ea2 100644 --- a/src/H5Tpublic.h +++ b/src/H5Tpublic.h @@ -28,7 +28,7 @@ * internal If this goes over 16 types (0-15), the file format will need to * change. */ -//! [H5T_class_t_snip] +//! <!-- [H5T_class_t_snip] --> typedef enum H5T_class_t { H5T_NO_CLASS = -1, /**< error */ H5T_INTEGER = 0, /**< integer types */ @@ -45,12 +45,12 @@ typedef enum H5T_class_t { H5T_NCLASSES /**< sentinel: this must be last */ } H5T_class_t; -//! [H5T_class_t_snip] +//! <!-- [H5T_class_t_snip] --> /** * Byte orders */ -//! [H5T_order_t_snip] +//! <!-- [H5T_order_t_snip] --> typedef enum H5T_order_t { H5T_ORDER_ERROR = -1, /**< error */ H5T_ORDER_LE = 0, /**< little endian */ @@ -60,12 +60,12 @@ typedef enum H5T_order_t { H5T_ORDER_NONE = 4 /**< no particular order (strings, bits,..) */ /*H5T_ORDER_NONE must be last */ } H5T_order_t; -//! [H5T_order_t_snip] +//! <!-- [H5T_order_t_snip] --> /** * Types of integer sign schemes */ -//! [H5T_sign_t_snip] +//! <!-- [H5T_sign_t_snip] --> typedef enum H5T_sign_t { H5T_SGN_ERROR = -1, /**< error */ H5T_SGN_NONE = 0, /**< this is an unsigned type */ @@ -73,12 +73,12 @@ typedef enum H5T_sign_t { H5T_NSGN = 2 /** sentinel: this must be last! */ } H5T_sign_t; -//! [H5T_sign_t_snip] +//! <!-- [H5T_sign_t_snip] --> /** * Floating-point normalization schemes */ -//! [H5T_norm_t_snip] +//! <!-- [H5T_norm_t_snip] --> typedef enum H5T_norm_t { H5T_NORM_ERROR = -1, /**< error */ H5T_NORM_IMPLIED = 0, /**< msb of mantissa isn't stored, always 1 */ @@ -86,7 +86,7 @@ typedef enum H5T_norm_t { H5T_NORM_NONE = 2 /**< not normalized */ /*H5T_NORM_NONE must be last */ } H5T_norm_t; -//! [H5T_norm_t_snip] +//! <!-- [H5T_norm_t_snip] --> /** * Character set to use for text strings. @@ -141,7 +141,7 @@ typedef enum H5T_str_t { /** * Type of padding to use in other atomic types */ -//! [H5T_pad_t_snip] +//! <!-- [H5T_pad_t_snip] --> typedef enum H5T_pad_t { H5T_PAD_ERROR = -1, /**< error */ H5T_PAD_ZERO = 0, /**< always set to zero */ @@ -150,7 +150,7 @@ typedef enum H5T_pad_t { H5T_NPAD = 3 /**< sentinal: THIS MUST BE LAST */ } H5T_pad_t; -//! [H5T_pad_t_snip] +//! <!-- [H5T_pad_t_snip] --> /** * Commands sent to conversion functions @@ -173,14 +173,14 @@ typedef enum H5T_bkg_t { /** * Type conversion client data */ -//! [H5T_cdata_t_snip] +//! <!-- [H5T_cdata_t_snip] --> typedef struct H5T_cdata_t { H5T_cmd_t command; /**< what should the conversion function do? */ H5T_bkg_t need_bkg; /**< is the background buffer needed? */ hbool_t recalc; /**< recalculate private data */ void * priv; /**< private data */ } H5T_cdata_t; -//! [H5T_cdata_t_snip] +//! <!-- [H5T_cdata_t_snip] --> /** * Conversion function persistence @@ -194,25 +194,32 @@ typedef enum H5T_pers_t { /** * The order to retrieve atomic native datatype */ -//! [H5T_direction_t_snip] +//! <!-- [H5T_direction_t_snip] --> typedef enum H5T_direction_t { H5T_DIR_DEFAULT = 0, /**< default direction is inscendent */ H5T_DIR_ASCEND = 1, /**< in inscendent order */ H5T_DIR_DESCEND = 2 /**< in descendent order */ } H5T_direction_t; -//! [H5T_direction_t_snip] +//! <!-- [H5T_direction_t_snip] --> /** * The exception type passed into the conversion callback function */ typedef enum H5T_conv_except_t { - H5T_CONV_EXCEPT_RANGE_HI = 0, /**< source value is greater than destination's range */ - H5T_CONV_EXCEPT_RANGE_LOW = 1, /**< source value is less than destination's range */ - H5T_CONV_EXCEPT_PRECISION = 2, /**< source value loses precision in destination */ - H5T_CONV_EXCEPT_TRUNCATE = 3, /**< source value is truncated in destination */ - H5T_CONV_EXCEPT_PINF = 4, /**< source value is positive infinity(floating number) */ - H5T_CONV_EXCEPT_NINF = 5, /**< source value is negative infinity(floating number) */ - H5T_CONV_EXCEPT_NAN = 6 /**< source value is NaN(floating number) */ + H5T_CONV_EXCEPT_RANGE_HI = 0, + /**< Source value is greater than destination's range */ + H5T_CONV_EXCEPT_RANGE_LOW = 1, + /**< Source value is less than destination's range */ + H5T_CONV_EXCEPT_PRECISION = 2, + /**< Source value loses precision in destination */ + H5T_CONV_EXCEPT_TRUNCATE = 3, + /**< Source value is truncated in destination */ + H5T_CONV_EXCEPT_PINF = 4, + /**< Source value is positive infinity */ + H5T_CONV_EXCEPT_NINF = 5, + /**< Source value is negative infinity */ + H5T_CONV_EXCEPT_NAN = 6 + /**< Source value is \c NaN (not a number, including \c QNaN and \c SNaN) */ } H5T_conv_except_t; /** @@ -254,17 +261,31 @@ extern "C" { /** * All datatype conversion functions are... */ -//! [H5T_conv_t_snip] +//! <!-- [H5T_conv_t_snip] --> typedef herr_t (*H5T_conv_t)(hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, size_t nelmts, size_t buf_stride, size_t bkg_stride, void *buf, void *bkg, hid_t dset_xfer_plist); -//! [H5T_conv_t_snip] +//! <!-- [H5T_conv_t_snip] --> +//! <!-- [H5T_conv_except_func_t_snip] --> /** - * Exception handler. If an exception like overflow happenes during conversion, - * this function is called if it's registered through H5Pset_type_conv_cb(). + * \brief Exception handler. + * + * \param[in] except_type The kind of exception that occurred + * \param[in] src_id Source datatype identifier + * \param[in] dst_id Destination datatype identifier + * \param[in] src_buf Source data buffer + * \param[in,out] dst_buf Destination data buffer + * \param[in,out] user_data Callback context + * \returns Valid callback function return values are #H5T_CONV_ABORT, + * #H5T_CONV_UNHANDLED and #H5T_CONV_HANDLED. + * + * \details If an exception like overflow happenes during conversion, this + * function is called if it's registered through H5Pset_type_conv_cb(). + * */ typedef H5T_conv_ret_t (*H5T_conv_except_func_t)(H5T_conv_except_t except_type, hid_t src_id, hid_t dst_id, void *src_buf, void *dst_buf, void *user_data); +//! <!-- [H5T_conv_except_func_t_snip] --> /* When this header is included from a private header, don't make calls to H5open() */ #undef H5OPEN @@ -1061,7 +1082,7 @@ H5_DLLVAR hid_t H5T_NATIVE_UINT_FAST64_g; * predefined datatype. * * When creating a variable-length string datatype, \p size must - * be #H5T_VARIABLE. + * be #H5T_VARIABLE; see \ref_vlen_strings. * * When creating a fixed-length string datatype, \p size will * be the length of the string in bytes. The length of the @@ -1075,13 +1096,9 @@ H5_DLLVAR hid_t H5T_NATIVE_UINT_FAST64_g; * The datatype identifier returned from this function should be * released with H5Tclose or resource leaks will result. * - * \since 1.2.0 - * * \see H5Tclose() * - * \todo Original has a reference to “Creating variable-length string - * datatypes”. - * \todo Create an example for H5Tcreate. + * \since 1.2.0 * */ H5_DLL hid_t H5Tcreate(H5T_class_t type, size_t size); @@ -1106,8 +1123,6 @@ H5_DLL hid_t H5Tcreate(H5T_class_t type, size_t size); * The returned datatype identifier should be released with H5Tclose() * to prevent resource leak. * - * \todo Create an example for H5Tcopy(). - * */ H5_DLL hid_t H5Tcopy(hid_t type_id); /** @@ -1130,8 +1145,6 @@ H5_DLL herr_t H5Tclose(hid_t type_id); * * \brief Asynchronous version of H5Tclose(). * - * \todo Create an example for H5Tclose_async(). - * */ H5_DLL herr_t H5Tclose_async(const char *app_file, const char *app_func, unsigned app_line, hid_t type_id, hid_t es_id); @@ -1222,8 +1235,6 @@ H5_DLL herr_t H5Tcommit2(hid_t loc_id, const char *name, hid_t type_id, hid_t lc * * \brief Asynchronous version of H5Tcommit2(). * - * \todo Create an example for H5Tcommit_async(). - * */ H5_DLL herr_t H5Tcommit_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id, const char *name, hid_t type_id, hid_t lcpl_id, hid_t tcpl_id, hid_t tapl_id, @@ -1257,8 +1268,6 @@ H5_DLL hid_t H5Topen2(hid_t loc_id, const char *name, hid_t tapl_id); * * \brief Asynchronous version of H5Topen2(). * - * \todo Create an example for H5Topen_async(). - * */ H5_DLL hid_t H5Topen_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id, const char *name, hid_t tapl_id, hid_t es_id); @@ -1503,8 +1512,6 @@ H5_DLL herr_t H5Trefresh(hid_t type_id); * * \since 1.2.0 * - * \todo Create example for H5Tinsert - * */ H5_DLL herr_t H5Tinsert(hid_t parent_id, const char *name, size_t offset, hid_t member_id); /** @@ -1663,10 +1670,7 @@ H5_DLL herr_t H5Tenum_valueof(hid_t type, const char *name, void *value /*out*/) * character base type creates a variable-length sequence of strings * (a variable-length, 1-dimensional array), with each element of * the array being of the string or character base type.\n - * To create a variable-length string datatype, see "Creating - * variable-length string datatypes." - * - * \todo Fix the reference. + * To create a variable-length string datatype, see \ref_vlen_strings. * */ H5_DLL hid_t H5Tvlen_create(hid_t base_id); @@ -1870,13 +1874,9 @@ H5_DLL htri_t H5Tdetect_class(hid_t type_id, H5T_class_t cls); * actual data and a size value. This function does not return the * size of actual variable-length sequence data. * - * \since 1.2.0 - * * \see H5Tset_size() * - * \todo Original has a reference to “Creating variable-length string datatypes”. - * \todo Create an example for H5Tget_size(). - * + * \since 1.2.0 */ H5_DLL size_t H5Tget_size(hid_t type_id); /** @@ -2090,7 +2090,7 @@ H5_DLL H5T_pad_t H5Tget_inpad(hid_t type_id); */ H5_DLL H5T_str_t H5Tget_strpad(hid_t type_id); /** - * \ingroup COMPOUND + * \ingroup COMPOUND ENUM * * \brief Retrieves the number of elements in a compound or enumeration datatype * @@ -2107,7 +2107,7 @@ H5_DLL H5T_str_t H5Tget_strpad(hid_t type_id); */ H5_DLL int H5Tget_nmembers(hid_t type_id); /** - * \ingroup COMPOUND + * \ingroup COMPOUND ENUM * * \brief Retrieves the name of a compound or enumeration datatype member * @@ -2134,7 +2134,7 @@ H5_DLL int H5Tget_nmembers(hid_t type_id); */ H5_DLL char *H5Tget_member_name(hid_t type_id, unsigned membno); /** - * \ingroup COMPOUND + * \ingroup COMPOUND ENUM * * \brief Retrieves the index of a compound or enumeration datatype member * @@ -2406,6 +2406,7 @@ H5_DLL hid_t H5Tget_native_type(hid_t type_id, H5T_direction_t direction); * * \li Variable-length string datatypes: If \p dtype_id is a * variable-length string, size must normally be set to #H5T_VARIABLE. + * See \ref_vlen_strings. * * \li Compound datatypes: This function may be used to increase or * decrease the size of a compound datatype, but the function will @@ -2416,12 +2417,9 @@ H5_DLL hid_t H5Tget_native_type(hid_t type_id, H5T_direction_t direction); * variable-length array datatypes (#H5T_VLEN), or reference datatypes * (#H5T_REFERENCE). * - * \since 1.2.0 - * * \see H5Tget_size() * - *\todo Create an example for H5Tset_size(). - *\todo Original has a reference to “Creating variable-length string datatypes”. + * \since 1.2.0 * */ H5_DLL herr_t H5Tset_size(hid_t type_id, size_t size); @@ -2873,7 +2871,7 @@ H5_DLL htri_t H5Tcompiler_conv(hid_t src_id, hid_t dst_id); * enough to hold the larger of the input and output data. * * \version 1.6.3 \p nelmts parameter type changed to size_t. - * \version 1.4.0 \p nelmts parameter type changed to \ref hsize_t. + * \version 1.4.0 \p nelmts parameter type changed to hsize_t. * */ H5_DLL herr_t H5Tconvert(hid_t src_id, hid_t dst_id, size_t nelmts, void *buf, void *background, |