Hdf5 1 12 doxygen merge (#615)

* OESS-98 fix tools test for plugins

* sync fork

* Merge of changes from dev

* Move problem option to bottom of the list until fixed

* HDFFV-11106 - fix parsing optional args

* HDFFV-11106 add note

* grammer fix

* Whitespace after clang formatting

* Undo format version 11 changes

* Update check to working version

* Merge workflow and minor changes from develop

* Update supported platforms

* PR#3 merge from develop

* Merge gcc 10 diagnostics option from develop

* Merge #318 OSX changes from develop

* Merge serval small changes from dev

* fix typo

* Minor non-space formatting changes

* GH #386 copyright corrections for java folder

* revert because logic requires false return

* Merges from develop

#358 patches from vtk
#361 fix header guard spelling

* Remove case statement for H5I_EVENTSET

* Correct call with versioning

* Remove tabs

* Double underscore change

* Merges from develop

#340 clang -Wformat-security warnings
#360 Fixed uninitialized warnings
Remove more underscores from header guards

* Merge #380 from develop

* Correct date entry

* Split format source and commit changes on repo push

* remove pre-split setting

* Change windows TS to use older VS.

* HDFFV-11212 JNI export util and Javadoc

* Suggested review changes

* Another change found

* Committing clang-format changes

* Some Javadoc warning fixes

* Committing clang-format changes

* Updated javadoc fixes

* HDFFV-11228/9 merges from develop

* remove obsolete debug comment

* Fix conflict

* HDFFV-11229 merge changes from develop

* HDFFV-11229 merge second compare from develop

* HDFFV-11229 fix reference file

* HDFFV-11229 update autotools test script for two ref files

* HDFFV-11229 merge dev changes for long double display in tools

* Committing clang-format changes

* Update with changes from develop

* Add "option" command for clang options

* Rework CMake add_custom to use the BYPRODUCTS argument

Update pkgconfig scripts for parallel builds.
Fix install COPYING file reference.
Remove unused round defines.
Change CMake default setting of BUILD_CPP to off.

* Whitespace changes

* Rework CMake add_custom to use the BYPRODUCTS argument

* Revert CMake configure checks for round defines

* With VS 2015 minimum strdup is supported

* Doxygen comments merged from develop

* doxygen build updates

* Correct version string for map functions

Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>

1 files changed, 187 insertions, 0 deletions

diff --git a/doxygen/examples/H5F_examples.c b/doxygen/examples/H5F_examples.c
new file mode 100644
index 0000000..a7ce6fb
--- /dev/null
+++ b/doxygen/examples/H5F_examples.c
@@ -0,0 +1,187 @@
+/* -*- c-file-style: "stroustrup" -*- */
+
+#include "hdf5.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+
+int
+main(void)
+{
+    int ret_val = EXIT_SUCCESS;
+
+    //! <!-- [life_cycle] -->
+    {
+        __label__ fail_fapl, fail_fcpl, fail_file;
+        hid_t fcpl, fapl, file;
+
+        if ((fcpl = H5Pcreate(H5P_FILE_CREATE)) == H5I_INVALID_HID) {
+            ret_val = EXIT_FAILURE;
+            goto fail_fcpl;
+        }
+        else {
+            // adjust the file creation properties
+        }
+
+        if ((fapl = H5Pcreate(H5P_FILE_ACCESS)) == H5I_INVALID_HID) {
+            ret_val = EXIT_FAILURE;
+            goto fail_fapl;
+        }
+        else {
+            // adjust the file access properties
+        }
+
+        unsigned mode   = H5F_ACC_EXCL;
+        char     name[] = "f1.h5";
+
+        if ((file = H5Fcreate(name, mode, fcpl, fapl)) == H5I_INVALID_HID) {
+            ret_val = EXIT_FAILURE;
+            goto fail_file;
+        }
+
+        // do something useful with FILE
+
+        H5Fclose(file);
+fail_file:
+        H5Pclose(fapl);
+fail_fapl:
+        H5Pclose(fcpl);
+fail_fcpl:;
+    }
+    //! <!-- [life_cycle] -->
+
+    //! <!-- [life_cycle_w_open] -->
+    {
+        __label__ fail_fapl, fail_file;
+        hid_t fapl, file;
+
+        if ((fapl = H5Pcreate(H5P_FILE_ACCESS)) == H5I_INVALID_HID) {
+            ret_val = EXIT_FAILURE;
+            goto fail_fapl;
+        }
+        else {
+            // adjust the file access properties
+        }
+
+        unsigned mode   = H5F_ACC_RDWR;
+        char     name[] = "f1.h5";
+
+        if ((file = H5Fopen(name, mode, fapl)) == H5I_INVALID_HID) {
+            ret_val = EXIT_FAILURE;
+            goto fail_file;
+        }
+
+        // do something useful with FILE
+
+        H5Fclose(file);
+fail_file:
+        H5Pclose(fapl);
+fail_fapl:;
+    }
+    //! <!-- [life_cycle_w_open] -->
+
+    //! <!-- [minimal] -->
+    {
+        unsigned mode   = H5F_ACC_TRUNC;
+        char     name[] = "f11.h5";
+
+        hid_t file = H5Fcreate(name, mode, H5P_DEFAULT, H5P_DEFAULT);
+        if (file != H5I_INVALID_HID)
+            H5Fclose(file);
+        else
+            ret_val = EXIT_FAILURE;
+    }
+    //! <!-- [minimal] -->
+
+    //! <!-- [open] -->
+    {
+        unsigned mode   = H5F_ACC_RDONLY;
+        char     name[] = "f11.h5";
+
+        hid_t file = H5Fopen(name, mode, H5P_DEFAULT);
+        if (file != H5I_INVALID_HID)
+            H5Fclose(file);
+        else
+            ret_val = EXIT_FAILURE;
+    }
+    //! <!-- [open] -->
+
+    //! <!-- [flush] -->
+    {
+        unsigned mode   = H5F_ACC_RDWR;
+        char     name[] = "f11.h5";
+
+        hid_t file = H5Fopen(name, mode, H5P_DEFAULT);
+        if (file != H5I_INVALID_HID) {
+            int step;
+            for (step = 0; step < 1000; ++step) {
+
+                // do important work & flush every 20 steps
+
+                if (step % 20 == 0) {
+                    if (H5Fflush(file, H5F_SCOPE_LOCAL) < 0) {
+                        perror("H5Fflush failed.");
+                        ret_val = EXIT_FAILURE;
+                        break;
+                    }
+                }
+            }
+
+            if (H5Fclose(file) < 0)
+                perror("H5Fclose failed.");
+        }
+        else
+            ret_val = EXIT_FAILURE;
+    }
+    //! <!-- [flush] -->
+
+    //! <!-- [libver_bounds] -->
+    {
+        unsigned mode   = H5F_ACC_RDWR;
+        char     name[] = "f11.h5";
+
+        hid_t file = H5Fopen(name, mode, H5P_DEFAULT);
+        if (file != H5I_INVALID_HID) {
+            if (H5Fset_libver_bounds(file, H5F_LIBVER_EARLIEST, H5F_LIBVER_V18) >= 0) {
+
+                // object creation will not exceed HDF5 version 1.8.x
+            }
+            else
+                perror("H5Fset_libver_bounds failed.");
+
+            if (H5Fclose(file) < 0)
+                perror("H5Fclose failed.");
+        }
+        else
+            ret_val = EXIT_FAILURE;
+    }
+    //! <!-- [libver_bounds] -->
+
+    //! <!-- [mount] -->
+    {
+        hid_t file = H5Fopen("f11.h5", H5F_ACC_RDWR, H5P_DEFAULT);
+        if (file != H5I_INVALID_HID) {
+            hid_t group, child;
+            if ((group = H5Gcreate1(file, "mount_point", H5P_DEFAULT)) != H5I_INVALID_HID) {
+                if ((child = H5Fopen("f1.h5", H5F_ACC_RDONLY, H5P_DEFAULT)) != H5I_INVALID_HID) {
+                    if (H5Fmount(group, ".", child, H5P_DEFAULT) >= 0) {
+
+                        // do something useful w/ the mounted file
+                    }
+                    else {
+                        ret_val = EXIT_FAILURE;
+                        perror("H5Fmount failed.");
+                    }
+                    H5Fclose(child);
+                }
+                H5Gclose(group);
+            }
+            H5Fclose(file);
+        }
+        else
+            ret_val = EXIT_FAILURE;
+    }
+    //! <!-- [mount] -->
+
+    return ret_val;
+}