From 436d6910ec95e4f0191387931b1ca01ff29aff85 Mon Sep 17 00:00:00 2001
From: Allen Byrne <50328838+byrnHDF@users.noreply.github.com>
Date: Fri, 13 May 2022 18:01:39 -0500
Subject: INITIAL attempt at User Guide in doxygen (#1678)
* HDFFV-10865 - merge from dev, HDFArray perf fix.
* Remove duplicate setting
* Whitespace changes after clang format
* Undo version 11 clang format changes
* Merge CMake changes from develop
* test testing script merge from develop
* Update supported platforms
* PR#3 merge from develop
* Merge gcc 10 diagnostics option from develop
* Merge #318 OSX changes from develop
* Merge small changes from develop
* Minor non-space formatting changes
* #386 copyright corrections for java folder
* Merges from develop
#358 patches from vtk
#361 fix header guard spelling
* Merge updates
#358 patches from vtk
#361 fix header guard spelling
* format fix
* Fix missing underscore and make H5public.h closer to dev
* Merges from develop
#340 clang -Wformat-security warnings
#360 Fixed uninitialized warnings
header guard underscore cleanup
JNI cleanup
* format alignment
* Add missing test ref file
* Merge #380 from develop
* Finish java merges from develop
* Fix java issues with tests and javadoc
* Correct use of attribute access plist
* Remove debug code
* Remove unused variable
* Change file access to read only for java tests
* Split clang format operations.
* More javadoc comments
* Remove pre-split setting
* format source
* Change windows TS to use older VS.
* Mostly all javadoc fixes, one argument rename.
* synch file
* Merge of long double fix and compiler flags
* HDFFV-11229 merge changes from develop
* HDFFV-11229 correct test script
* 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
* minor whitespace
* remove unneeded macro
* Committing clang-format changes
* 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.
* Fortran target depends
* Remove incorrect source attribute
* Revert define removal
* printf specifiers and VS2015 min changes
* Committing clang-format changes
* Add time struct
* TRILAB-227 and tools debug merges from develop
* Merge various changes from dev
* Issue #669 remove version from pkgcfg filename
* remove version from h5cc script
* doxygen changes merged from develop
* Committing clang-format changes
* Merge CMake fortran ninja changes from dev
* Enable fortran to gcc yaml
* Refactor Fortran CMake config tests and CMake test args
* Merge warnings files fixes from develop
* Fix cmake configure path
* Update missing release note info.
* Update code owners
* Add known problem
* Use only core library for testing dynamic plugins.
CMake uses H5_HAVE_DIRECT instead of DIRECT_VFD
* INITIAL attempt at User Guide in doxygen
* Add quick H5E to show actual UG header sections
* Add Error Handling chapter
* Cleanup format changes
* Committing clang-format changes
Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>
---
doxygen/CMakeLists.txt | 2 +-
doxygen/Doxyfile.in | 2 +-
doxygen/dox/Overview.dox | 6 +-
doxygen/dox/UsersGuide.dox | 145 ++++++++++
doxygen/hdf5doxy_layout.xml | 1 +
doxygen/img/Shared_Attribute.jpg | Bin 0 -> 37209 bytes
doxygen/img/UML_Attribute.jpg | Bin 0 -> 36134 bytes
src/H5Amodule.h | 332 +++++++++++++++++++++-
src/H5Emodule.h | 576 +++++++++++++++++++++++++++++++++++++--
9 files changed, 1021 insertions(+), 43 deletions(-)
create mode 100644 doxygen/dox/UsersGuide.dox
create mode 100644 doxygen/img/Shared_Attribute.jpg
create mode 100644 doxygen/img/UML_Attribute.jpg
diff --git a/doxygen/CMakeLists.txt b/doxygen/CMakeLists.txt
index 920fafa..38c2fad 100644
--- a/doxygen/CMakeLists.txt
+++ b/doxygen/CMakeLists.txt
@@ -21,7 +21,7 @@ if (DOXYGEN_FOUND)
set (DOXYGEN_HTML_HEADER ${HDF5_DOXYGEN_DIR}/hdf5_header.html)
set (DOXYGEN_HTML_FOOTER ${HDF5_DOXYGEN_DIR}/hdf5_footer.html)
set (DOXYGEN_HTML_EXTRA_STYLESHEET ${HDF5_DOXYGEN_DIR}/hdf5doxy.css)
- set (DOXYGEN_HTML_EXTRA_FILES "${HDF5_DOXYGEN_DIR}/hdf5_navtree_hacks.js ${HDF5_DOXYGEN_DIR}/img/FF-IH_FileGroup.gif ${HDF5_DOXYGEN_DIR}/img/FF-IH_FileObject.gif ${HDF5_DOXYGEN_DIR}/img/FileFormatSpecChunkDiagram.jpg ${HDF5_DOXYGEN_DIR}/img/ftv2node.png ${HDF5_DOXYGEN_DIR}/img/ftv2pnode.png ${HDF5_DOXYGEN_DIR}/img/HDFG-logo.png ${HDF5_DOXYGEN_DIR}/img/IOFlow2.gif ${HDF5_DOXYGEN_DIR}/img/IOFlow3.gif ${HDF5_DOXYGEN_DIR}/img/IOFlow.gif ${HDF5_DOXYGEN_DIR}/img/PaletteExample1.gif ${HDF5_DOXYGEN_DIR}/img/Palettes.fm.anc.gif")
+ set (DOXYGEN_HTML_EXTRA_FILES "${HDF5_DOXYGEN_DIR}/hdf5_navtree_hacks.js ${HDF5_DOXYGEN_DIR}/img/FF-IH_FileGroup.gif ${HDF5_DOXYGEN_DIR}/img/FF-IH_FileObject.gif ${HDF5_DOXYGEN_DIR}/img/FileFormatSpecChunkDiagram.jpg ${HDF5_DOXYGEN_DIR}/img/ftv2node.png ${HDF5_DOXYGEN_DIR}/img/ftv2pnode.png ${HDF5_DOXYGEN_DIR}/img/HDFG-logo.png ${HDF5_DOXYGEN_DIR}/img/IOFlow2.gif ${HDF5_DOXYGEN_DIR}/img/IOFlow3.gif ${HDF5_DOXYGEN_DIR}/img/IOFlow.gif ${HDF5_DOXYGEN_DIR}/img/PaletteExample1.gif ${HDF5_DOXYGEN_DIR}/img/Palettes.fm.anc.gif ${HDF5_DOXYGEN_DIR}/img/UML_Attribute.jpg ${HDF5_DOXYGEN_DIR}/img/Shared_Attribute.jpg")
set (DOXYGEN_TAG_FILE ${HDF5_BINARY_DIR}/hdf5.tag)
set (DOXYGEN_SERVER_BASED_SEARCH NO)
set (DOXYGEN_EXTERNAL_SEARCH NO)
diff --git a/doxygen/Doxyfile.in b/doxygen/Doxyfile.in
index 7958767..e391422 100644
--- a/doxygen/Doxyfile.in
+++ b/doxygen/Doxyfile.in
@@ -938,7 +938,7 @@ EXAMPLE_RECURSIVE = NO
# that contain images that are to be included in the documentation (see the
# \image command).
-IMAGE_PATH =
+IMAGE_PATH = @HDF5_DOXYGEN_DIR@/img
# The INPUT_FILTER tag can be used to specify a program that doxygen should
# invoke to filter for each input file. Doxygen will invoke the filter program
diff --git a/doxygen/dox/Overview.dox b/doxygen/dox/Overview.dox
index 040769c..8f428b5 100644
--- a/doxygen/dox/Overview.dox
+++ b/doxygen/dox/Overview.dox
@@ -23,7 +23,7 @@ documents cover a mix of tasks, concepts, and reference, to help a specific
\par Versions
Version-specific documentation (see the version in the title area) can be found
here:
- - HDF5 develop
branch (this site)
+ - HDF5 1.10
branch (this site)
- HDF5 1.12.x
- HDF5 1.10.x
- HDF5 1.8.x
@@ -36,10 +36,6 @@ documents cover a mix of tasks, concepts, and reference, to help a specific
\par Offline reading
You can download it as a tgz archive for offline reading.
-\par History
- A snapshot (~April 2017) of the pre-Doxygen HDF5 documentation can be found
- here.
-
\par ToDo List
There is plenty of unfinished business.
diff --git a/doxygen/dox/UsersGuide.dox b/doxygen/dox/UsersGuide.dox
new file mode 100644
index 0000000..22fe5c6
--- /dev/null
+++ b/doxygen/dox/UsersGuide.dox
@@ -0,0 +1,145 @@
+/** \page UG HDF5 User’s Guide
+
+
Create | Read |
---|---|
Create | Update |
* \snippet{lineno} H5A_examples.c create * | *- * \snippet{lineno} H5A_examples.c read + * \snippet{lineno} H5A_examples.c update * | - *
Update | Delete |
Read | Delete |
- * \snippet{lineno} H5A_examples.c update + * \snippet{lineno} H5A_examples.c read * | ** \snippet{lineno} H5A_examples.c delete @@ -60,6 +116,258 @@ * |
Create |
---|
+ * \snippet{lineno} H5A_examples.c create + * | + *
Create | Read |
---|---|
- * \snippet{lineno} H5E_examples.c create - * | - *- * \snippet{lineno} H5E_examples.c read - * | - *
Update | Delete |
- * \snippet{lineno} H5E_examples.c update - * | - *- * \snippet{lineno} H5E_examples.c delete - * | - *
+ * If an application calls \ref H5Tclose on a + * predefined datatype then the following message is + * printed on the standard error stream. This is a + * simple error that has only one component, the API + * function; other errors may have many components. + *
|
+ *
+ * An application can temporarily turn off error messages while “probing” a function. See the + * example below. + *
|
+ *
+ * Or automatic printing can be disabled altogether and error messages can be explicitly printed. + *
|
+ *
+ *
|
+ *
+ *
|
+ *
+ * The following example shows a user‐defined callback function. + *
|
+ *
+ * An error report shows both the library’s error record and the application’s error records. + * See the example below. + *
|
+ *
+ *
|
+ *
+ * The example below shows how an application creates an error class and error messages. + *
|
+ *
+ * The example below shows how an application closes error messages and unregisters the error + * class. + *
|
+ *
+ * The example below shows how an application pushes an error record onto the default error stack. + *
|
+ *
+ * The example below shows how an application registers the current error stack and + * creates an object handle to avoid another HDF5 function from clearing the error stack. + *
|
+ *