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, 173 insertions, 0 deletions

diff --git a/doxygen/examples/H5D_examples.c b/doxygen/examples/H5D_examples.c
new file mode 100644
index 0000000..aad057d
--- /dev/null
+++ b/doxygen/examples/H5D_examples.c
@@ -0,0 +1,173 @@
+/* -*- c-file-style: "stroustrup" -*- */
+
+#include "hdf5.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+
+int
+main(void)
+{
+    int ret_val = EXIT_SUCCESS;
+
+    //! <!-- [create] -->
+    {
+        __label__ fail_lcpl, fail_dset, fail_file;
+        hid_t file, lcpl, fspace, dset;
+
+        unsigned mode        = H5F_ACC_TRUNC;
+        char     file_name[] = "d1.h5";
+        // link names can be arbitrary Unicode strings
+        char dset_name[] = "σύνολο/δεδομένων";
+
+        if ((file = H5Fcreate(file_name, mode, H5P_DEFAULT, H5P_DEFAULT)) == H5I_INVALID_HID) {
+            ret_val = EXIT_FAILURE;
+            goto fail_file;
+        }
+        if ((lcpl = H5Pcreate(H5P_LINK_CREATE)) == H5I_INVALID_HID) {
+            ret_val = EXIT_FAILURE;
+            goto fail_lcpl;
+        }
+        // use UTF-8 encoding for link names
+        if (H5Pset_char_encoding(lcpl, H5T_CSET_UTF8) < 0) {
+            ret_val = EXIT_FAILURE;
+            goto fail_fspace;
+        }
+        // create intermediate groups as needed
+        if (H5Pset_create_intermediate_group(lcpl, 1) < 0) {
+            ret_val = EXIT_FAILURE;
+            goto fail_fspace;
+        }
+        // create a 1D dataspace
+        if ((fspace = H5Screate_simple(1, (hsize_t[]){10}, NULL)) == H5I_INVALID_HID) {
+            ret_val = EXIT_FAILURE;
+            goto fail_fspace;
+        }
+        // create a 32-bit integer dataset
+        if ((dset = H5Dcreate2(file, dset_name, H5T_STD_I32LE, fspace, lcpl, H5P_DEFAULT, H5P_DEFAULT)) ==
+            H5I_INVALID_HID) {
+            ret_val = EXIT_FAILURE;
+            goto fail_dset;
+        }
+
+        H5Dclose(dset);
+fail_dset:
+        H5Sclose(fspace);
+fail_fspace:
+        H5Pclose(lcpl);
+fail_lcpl:
+        H5Fclose(file);
+fail_file:;
+    }
+    //! <!-- [create] -->
+
+    //! <!-- [read] -->
+    {
+        __label__ fail_dset, fail_file;
+        hid_t file, dset;
+
+        unsigned mode        = H5F_ACC_RDONLY;
+        char     file_name[] = "d1.h5";
+        // assume a priori knowledge of dataset name and size
+        char dset_name[] = "σύνολο/δεδομένων";
+        int  elts[10];
+
+        if ((file = H5Fopen(file_name, mode, H5P_DEFAULT)) == H5I_INVALID_HID) {
+            ret_val = EXIT_FAILURE;
+            goto fail_file;
+        }
+        if ((dset = H5Dopen2(file, dset_name, H5P_DEFAULT)) == H5I_INVALID_HID) {
+            ret_val = EXIT_FAILURE;
+            goto fail_dset;
+        }
+        // read all dataset elements
+        if (H5Dread(dset, H5T_NATIVE_INT, H5S_ALL, H5S_ALL, H5P_DEFAULT, elts) < 0)
+            ret_val = EXIT_FAILURE;
+
+        // do something w/ the dataset elements
+
+        H5Dclose(dset);
+fail_dset:
+        H5Fclose(file);
+fail_file:;
+    }
+    //! <!-- [read] -->
+
+    //! <!-- [update] -->
+    {
+        __label__ fail_update, fail_fspace, fail_dset, fail_file;
+        hid_t file, dset, fspace;
+
+        unsigned mode           = H5F_ACC_RDWR;
+        char     file_name[]    = "d1.h5";
+        char     dset_name[]    = "σύνολο/δεδομένων";
+        int      new_elts[6][2] = {{-1, 1}, {-2, 2}, {-3, 3}, {-4, 4}, {-5, 5}, {-6, 6}};
+
+        if ((file = H5Fopen(file_name, mode, H5P_DEFAULT)) == H5I_INVALID_HID) {
+            ret_val = EXIT_FAILURE;
+            goto fail_file;
+        }
+        if ((dset = H5Dopen2(file, dset_name, H5P_DEFAULT)) == H5I_INVALID_HID) {
+            ret_val = EXIT_FAILURE;
+            goto fail_dset;
+        }
+        // get the dataset's dataspace
+        if ((fspace = H5Dget_space(dset)) == H5I_INVALID_HID) {
+            ret_val = EXIT_FAILURE;
+            goto fail_fspace;
+        }
+        // select the first 5 elements in odd positions
+        if (H5Sselect_hyperslab(fspace, H5S_SELECT_SET, (hsize_t[]){1}, (hsize_t[]){2}, (hsize_t[]){5},
+                                NULL) < 0) {
+            ret_val = EXIT_FAILURE;
+            goto fail_update;
+        }
+
+        // (implicitly) select and write the first 5 elements of the second column of NEW_ELTS
+        if (H5Dwrite(dset, H5T_NATIVE_INT, H5S_ALL, fspace, H5P_DEFAULT, new_elts) < 0)
+            ret_val = EXIT_FAILURE;
+
+fail_update:
+        H5Sclose(fspace);
+fail_fspace:
+        H5Dclose(dset);
+fail_dset:
+        H5Fclose(file);
+fail_file:;
+    }
+    //! <!-- [update] -->
+
+    //! <!-- [delete] -->
+    {
+        __label__ fail_delete, fail_file;
+        hid_t file;
+
+        unsigned mode         = H5F_ACC_RDWR;
+        char     file_name[]  = "d1.h5";
+        char     group_name[] = "σύνολο";
+        char     dset_name[]  = "σύνολο/δεδομένων";
+
+        if ((file = H5Fopen(file_name, mode, H5P_DEFAULT)) == H5I_INVALID_HID) {
+            ret_val = EXIT_FAILURE;
+            goto fail_file;
+        }
+        // delete (unlink) the dataset
+        if (H5Ldelete(file, dset_name, H5P_DEFAULT) < 0) {
+            ret_val = EXIT_FAILURE;
+            goto fail_delete;
+        }
+        // the previous call deletes (unlinks) only the dataset
+        if (H5Ldelete(file, group_name, H5P_DEFAULT) < 0) {
+            ret_val = EXIT_FAILURE;
+            goto fail_delete;
+        }
+
+fail_delete:
+        H5Fclose(file);
+fail_file:;
+    }
+
+    //! <!-- [delete] -->
+
+    return ret_val;
+}