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>

1 files changed, 218 insertions, 1 deletions

diff --git a/src/H5FDmulti.h b/src/H5FDmulti.h
index 9e04d8d..62cc9c8 100644
--- a/src/H5FDmulti.h
+++ b/src/H5FDmulti.h
@@ -25,11 +25,228 @@
 #ifdef __cplusplus
 extern "C" {
 #endif
-H5_DLL hid_t  H5FD_multi_init(void);
+H5_DLL hid_t H5FD_multi_init(void);
+
+/**
+ * \ingroup FAPL
+ *
+ * \brief Sets up use of the multi-file driver
+ *
+ * \fapl_id
+ * \param[in] memb_map Maps memory usage types to other memory usage types
+ * \param[in] memb_fapl Property list for each memory usage type
+ * \param[in] memb_name Name generator for names of member files
+ * \param[in] memb_addr The offsets within the virtual address space, from 0
+ *           (zero) to #HADDR_MAX, at which each type of data storage begins
+ * \param[in] relax Allows read-only access to incomplete file sets when \c TRUE
+ * \returns \herr_t
+ *
+ * \details H5Pset_fapl_multi() sets the file access property list \p fapl_id to
+ *          use the multi-file driver.
+ *
+ *          The multi-file driver enables different types of HDF5 data and
+ *          metadata to be written to separate files. These files are viewed by
+ *          the HDF5 library and the application as a single virtual HDF5 file
+ *          with a single HDF5 file address space. The types of data that can be
+ *          broken out into separate files include raw data, the superblock,
+ *          B-tree data, global heap data, local heap data, and object
+ *          headers. At the programmer's discretion, two or more types of data
+ *          can be written to the same file while other types of data are
+ *          written to separate files.
+ *
+ *          The array \p memb_map maps memory usage types to other memory usage
+ *          types and is the mechanism that allows the caller to specify how
+ *          many files are created. The array contains #H5FD_MEM_NTYPES entries,
+ *          which are either the value #H5FD_MEM_DEFAULT or a memory usage
+ *          type. The number of unique values determines the number of files
+ *          that are opened.
+ *
+ *          The array \p memb_fapl contains a property list for each memory
+ *          usage type that will be associated with a file.
+ *
+ *          The array \p memb_name should be a name generator (a
+ *          \Code{printf}-style format with a \Code{%s} which will be replaced
+ *          with the name passed to H5FDopen(), usually from H5Fcreate() or
+ *          H5Fopen()).
+ *
+ *          The array \p memb_addr specifies the offsets within the virtual
+ *          address space, from 0 (zero) to #HADDR_MAX, at which each type of
+ *          data storage begins.
+ *
+ *          If \p relax is set to 1 (TRUE), then opening an existing file for
+ *          read-only access will not fail if some file members are
+ *          missing. This allows a file to be accessed in a limited sense if
+ *          just the meta data is available.
+ *
+ *          Default values for each of the optional arguments are as follows:
+ *          <table>
+ *          <tr>
+ *          <td>\p memb_map</td>
+ *          <td>The default member map contains the value #H5FD_MEM_DEFAULT for each element.</td>
+ *          </tr>
+ *          <tr>
+ *          <td>
+ *          \p memb_fapl
+ *          </td>
+ *          <td>
+ *          The default value is #H5P_DEFAULT for each element.
+ *          </td>
+ *          </tr>
+ *          <tr>
+ *          <td>
+ *          \p memb_name
+ *          </td>
+ *          <td>
+ *          The default string is \Code{%s-X.h5} where \c X is one of the following letters:
+ *          - \c s for #H5FD_MEM_SUPER
+ *          - \c b for #H5FD_MEM_BTREE
+ *          - \c r for #H5FD_MEM_DRAW
+ *          - \c g for #H5FD_MEM_GHEAP
+ *          - \c l for #H5FD_MEM_LHEAP
+ *          - \c o for #H5FD_MEM_OHDR
+ *          </td>
+ *          </tr>
+ *          <tr>
+ *          <td>
+ *          \p memb_addr
+ *          </td>
+ *          <td>
+ *          The default setting is that the address space is equally divided
+ *          among all of the elements:
+ *          - #H5FD_MEM_SUPER \Code{-> 0 * (HADDR_MAX/6)}
+ *          - #H5FD_MEM_BTREE \Code{-> 1 * (HADDR_MAX/6)}
+ *          - #H5FD_MEM_DRAW \Code{-> 2 * (HADDR_MAX/6)}
+ *          - #H5FD_MEM_GHEAP \Code{-> 3 * (HADDR_MAX/6)}
+ *          - #H5FD_MEM_LHEAP \Code{-> 4 * (HADDR_MAX/6)}
+ *          - #H5FD_MEM_OHDR \Code{-> 5 * (HADDR_MAX/6)}
+ *          </td>
+ *          </tr>
+ *          </table>
+ *
+ * \par Example:
+ * The following code sample sets up a multi-file access property list that
+ * partitions data into meta and raw files, each being one-half of the address:\n
+ * \code
+ * H5FD_mem_t mt, memb_map[H5FD_MEM_NTYPES];
+ * hid_t memb_fapl[H5FD_MEM_NTYPES];
+ * const char *memb[H5FD_MEM_NTYPES];
+ * haddr_t memb_addr[H5FD_MEM_NTYPES];
+ *
+ * // The mapping...
+ * for (mt=0; mt<H5FD_MEM_NTYPES; mt++) {
+ *   memb_map[mt] = H5FD_MEM_SUPER;
+ * }
+ * memb_map[H5FD_MEM_DRAW] = H5FD_MEM_DRAW;
+ *
+ * // Member information
+ * memb_fapl[H5FD_MEM_SUPER] = H5P_DEFAULT;
+ * memb_name[H5FD_MEM_SUPER] = "%s.meta";
+ * memb_addr[H5FD_MEM_SUPER] = 0;
+ *
+ * memb_fapl[H5FD_MEM_DRAW] = H5P_DEFAULT;
+ * memb_name[H5FD_MEM_DRAW] = "%s.raw";
+ * memb_addr[H5FD_MEM_DRAW] = HADDR_MAX/2;
+ *
+ * hid_t fapl = H5Pcreate(H5P_FILE_ACCESS);
+ * H5Pset_fapl_multi(fapl, memb_map, memb_fapl,
+ *                   memb_name, memb_addr, TRUE);
+ * \endcode
+ *
+ * \version 1.6.3 \p memb_name parameter type changed to \Code{const char* const*}.
+ * \since 1.4.0
+ */
 H5_DLL herr_t H5Pset_fapl_multi(hid_t fapl_id, const H5FD_mem_t *memb_map, const hid_t *memb_fapl,
                                 const char *const *memb_name, const haddr_t *memb_addr, hbool_t relax);
+
+/**
+ * \ingroup FAPL
+ *
+ * \brief Returns information about the multi-file access property list
+ *
+ * \fapl_id
+ * \param[out] memb_map Maps memory usage types to other memory usage types
+ * \param[out] memb_fapl Property list for each memory usage type
+ * \param[out] memb_name Name generator for names of member files
+ * \param[out] memb_addr The offsets within the virtual address space, from 0
+ *           (zero) to #HADDR_MAX, at which each type of data storage begins
+ * \param[out] relax Allows read-only access to incomplete file sets when \c TRUE
+ * \returns \herr_t
+ *
+ * \details H5Pget_fapl_multi() returns information about the multi-file access
+ *          property list.
+ *
+ * \since 1.4.0
+ *
+ */
 H5_DLL herr_t H5Pget_fapl_multi(hid_t fapl_id, H5FD_mem_t *memb_map /*out*/, hid_t *memb_fapl /*out*/,
                                 char **memb_name /*out*/, haddr_t *memb_addr /*out*/, hbool_t *relax /*out*/);
+
+/**
+ * \ingroup FAPL
+ *
+ * \brief Emulates the old split file driver
+ *
+ * \fapl_id{fapl}
+ * \param[in] meta_ext Metadata filename extension
+ * \param[in] meta_plist_id File access property list identifier for the metadata file
+ * \param[in] raw_ext Raw data filename extension
+ * \param[in] raw_plist_id
+ * \returns \herr_t
+ *
+ * \details H5Pset_fapl_split() is a compatibility function that enables the
+ *          multi-file driver to emulate the split driver from HDF5 Releases 1.0
+ *          and 1.2. The split file driver stored metadata and raw data in
+ *          separate files but provided no mechanism for separating types of
+ *          metadata.
+ *
+ *          \p fapl is a file access property list identifier.
+ *
+ *          \p meta_ext is the filename extension for the metadata file. The
+ *          extension is appended to the name passed to H5FDopen(), usually from
+ *          H5Fcreate() or H5Fopen(), to form the name of the metadata file. If
+ *          the string \Code{%s} is used in the extension, it works like the
+ *          name generator as in H5Pset_fapl_multi().
+ *
+ *          \p meta_plist_id is the file access property list identifier for the
+ *          metadata file.
+ *
+ *          \p raw_ext is the filename extension for the raw data file. The
+ *          extension is appended to the name passed to H5FDopen(), usually from
+ *          H5Fcreate() or H5Fopen(), to form the name of the raw data file. If
+ *          the string \Code{%s} is used in the extension, it works like the
+ *          name generator as in H5Pset_fapl_multi().
+ *
+ *          \p raw_plist_id is the file access property list identifier for the
+ *          raw data file.
+ *
+ *          If a user wishes to check to see whether this driver is in use, the
+ *          user must call H5Pget_driver() and compare the returned value to the
+ *          string #H5FD_MULTI. A positive match will confirm that the multi
+ *          driver is in use; HDF5 provides no mechanism to determine whether it
+ *          was called as the special case invoked by H5Pset_fapl_split().
+ *
+ * \par Example:
+ * \code
+ * // Example 1: Both metadata and rawdata files are in the same
+ * //            directory. Use Station1-m.h5 and Station1-r.h5 as
+ * //            the metadata and rawdata files.
+ * hid_t fapl, fid;
+ * fapl = H5Pcreate(H5P_FILE_ACCESS);
+ * H5Pset_fapl_split(fapl, "-m.h5", H5P_DEFAULT, "-r.h5", H5P_DEFAULT);
+ * fid=H5Fcreate("Station1",H5F_ACC_TRUNC,H5P_DEFAULT,fapl);
+ *
+ * // Example 2: metadata and rawdata files are in different
+ * //            directories.  Use PointA-m.h5 and /pfs/PointA-r.h5 as
+ * //            the metadata and rawdata files.
+ * hid_t fapl, fid;
+ * fapl = H5Pcreate(H5P_FILE_ACCESS);
+ * H5Pset_fapl_split(fapl, "-m.h5", H5P_DEFAULT, "/pfs/%s-r.h5", H5P_DEFAULT);
+ * fid=H5Fcreate("PointA",H5F_ACC_TRUNC,H5P_DEFAULT,fapl);
+ * \endcode
+ *
+ * \since 1.4.0
+ *
+ */
 H5_DLL herr_t H5Pset_fapl_split(hid_t fapl, const char *meta_ext, hid_t meta_plist_id, const char *raw_ext,
                                 hid_t raw_plist_id);
 #ifdef __cplusplus