Port VOL User Guide to doxygen (#2165)

* Port VOL User Guide to doxygen

* Fix spelling

* Committing clang-format changes

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

2 files changed, 674 insertions, 1 deletions

diff --git a/doxygen/dox/UsersGuide.dox b/doxygen/dox/UsersGuide.dox
index dbb6053..10b4ba1 100644
--- a/doxygen/dox/UsersGuide.dox
+++ b/doxygen/dox/UsersGuide.dox
@@ -270,8 +270,44 @@ HDF5 Release 1.14
 \ref sec_vol
 \li \ref subsec_vol_intro
 \li \ref subsec_vol_abstract_layer
+\li \ref subsec_vol_quickstart
+    <ul>
+        <li> \ref subsubsec_vol_quick_read
+        <li> \ref subsubsec_vol_quick_use
+        <li> \ref subsubsec_vol_quick_set
+        <li> \ref subsubsec_vol_quick_update
+        <li> \ref subsubsec_vol_quick_plugin
+        <li> \ref subsubsec_vol_quick_opt
+    </ul>
 \li \ref subsec_vol_connect
-\li \ref subsec_vol_use
+    <ul>
+        <li> \ref subsubsec_vol_connect_register
+        <li> \ref subsubsec_vol_connect_version
+        <li> \ref subsubsec_vol_connect_reg_calls
+        <li> \ref subsubsec_vol_connect_set_vol
+        <li> \ref subsubsec_vol_connect_search
+        <li> \ref subsubsec_vol_connect_param
+        <li> \ref subsubsec_vol_connect_env
+    </ul>
+\li \ref subsec_vol_adapt
+    <ul>
+        <li> \ref subsubsec_vol_adapt_token
+        <li> \ref subsubsec_vol_adapt_api
+        <li> \ref subsubsec_vol_adapt_native
+    </ul>
+\li \ref subsec_vol_lang
+    <ul>
+        <li> \ref subsubsec_vol_lang_c
+        <li> \ref subsubsec_vol_lang_fort
+        <li> \ref subsubsec_vol_lang_java
+    </ul>
+\li \ref subsec_vol_cl
+\li \ref subsec_vol_compat
+    <ul>
+        <li> \ref subsubsec_vol_compat_native
+        <li> \ref subsubsec_vol_compat_indep
+        <li> \ref subsubsec_vol_compat_opt
+    </ul>
 
 \ref sec_async
 \li \ref subsec_async_intro
diff --git a/doxygen/examples/tables/volAPIs.dox b/doxygen/examples/tables/volAPIs.dox
new file mode 100644
index 0000000..6b9df9b
--- /dev/null
+++ b/doxygen/examples/tables/volAPIs.dox
@@ -0,0 +1,637 @@
+/** VOL API List
+ *
+//! [vol_native_table]
+<table>
+<caption>Alphabetical list of HDF5 API calls specific to the native VOL connector</caption>
+<tr>
+<th>API</th>
+<th>Description</th>
+</tr>
+<tr>
+<td>#H5Aget_num_attrs</td>
+<td>deprecated</td>
+</tr>
+<tr>
+<td>#H5Aiterate1</td>
+<td>deprecated</td>
+</tr>
+<tr>
+<td>#H5Dchunk_iter</td>
+<td></td>
+</tr>
+<tr>
+<td>H5Ddebug</td>
+<td>Internal API routines</td>
+</tr>
+<tr>
+<td>H5Dformat_convert</td>
+<td>Internal API routines</td>
+</tr>
+<tr>
+<td>H5Dget_chunk_index_type</td>
+<td>Internal API routines</td>
+</tr>
+<tr>
+<td>#H5Dget_chunk_info</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Dget_chunk_info_by_coord</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Dget_chunk_storage_size</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Dget_num_chunks</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Dget_offset</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Dread_chunk</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Dwrite_chunk</td>
+<td></td>
+</tr>
+<tr>
+<td>H5FD*</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Fclear_elink_file_cache</td>
+<td></td>
+</tr>
+<tr>
+<td>H5Fformat_convert</td>
+<td>Internal API routines</td>
+</tr>
+<tr>
+<td>#H5Fget_dset_no_attrs_hint</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Fget_eoa</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Fget_file_image</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Fget_filesize</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Fget_free_sections</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Fget_freespace</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Fget_info1</td>
+<td>deprecated</td>
+</tr>
+<tr>
+<td>#H5Fget_info2</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Fget_mdc_config</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Fget_mdc_hit_rate</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Fget_mdc_image_info</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Fget_mdc_logging_status</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Fget_mdc_size</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Fget_metadata_read_retry_info</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Fget_mpi_atomicity</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Fget_page_buffering_stats</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Fget_vfd_handle</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Fincrement_filesize</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Fis_hdf5</td>
+<td>deprecated</td>
+</tr>
+<tr>
+<td>#H5Freset_mdc_hit_rate_stats</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Freset_page_buffering_stats</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Fset_dset_no_attrs_hint</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Fset_latest_format</td>
+<td>deprecated</td>
+</tr>
+<tr>
+<td>#H5Fset_libver_bounds</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Fset_mdc_config</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Fset_mpi_atomicity</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Fstart_mdc_logging</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Fstart_swmr_write</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Fstop_mdc_logging</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Gget_comment</td>
+<td>deprecated</td>
+</tr>
+<tr>
+<td>#H5Giterate</td>
+<td>deprecated</td>
+</tr>
+<tr>
+<td>#H5Gget_info</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Gget_info_by_name</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Gget_info_by_idx</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Gget_objinfo</td>
+<td>deprecated</td>
+</tr>
+<tr>
+<td>#H5Gget_objname_by_idx</td>
+<td>deprecated</td>
+</tr>
+<tr>
+<td>#H5Gget_objtype_by_idx</td>
+<td>deprecated</td>
+</tr>
+<tr>
+<td>#H5Gset_comment</td>
+<td>deprecated</td>
+</tr>
+<tr>
+<td>#H5Lget_info1</td>
+<td>deprecated</td>
+</tr>
+<tr>
+<td>#H5Lget_info_by_idx1</td>
+<td>deprecated</td>
+</tr>
+<tr>
+<td>#H5Literate1</td>
+<td>deprecated</td>
+</tr>
+<tr>
+<td>#H5Literate_by_name1</td>
+<td>deprecated</td>
+</tr>
+<tr>
+<td>#H5Lvisit1</td>
+<td>deprecated</td>
+</tr>
+<tr>
+<td>#H5Lvisit_by_name1</td>
+<td>deprecated</td>
+</tr>
+<tr>
+<td>#H5Oare_mdc_flushes_disabled</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Odisable_mdc_flushes</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Oenable_mdc_flushes</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Oget_comment</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Oget_comment_by_name</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Oget_info_by_idx1</td>
+<td>deprecated</td>
+</tr>
+<tr>
+<td>#H5Oget_info_by_idx2</td>
+<td>deprecated</td>
+</tr>
+<tr>
+<td>#H5Oget_info_by_name1</td>
+<td>deprecated</td>
+</tr>
+<tr>
+<td>#H5Oget_info_by_name2</td>
+<td>deprecated</td>
+</tr>
+<tr>
+<td>#H5Oget_info1</td>
+<td>deprecated</td>
+</tr>
+<tr>
+<td>#H5Oget_info2</td>
+<td>deprecated</td>
+</tr>
+<tr>
+<td>#H5Oget_native_info</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Oget_native_info_by_idx</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Oget_native_info_by_name</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Oopen_by_addr</td>
+<td>deprecated</td>
+</tr>
+<tr>
+<td>#H5Oset_comment</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Oset_comment_by_name</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Ovisit1</td>
+<td>deprecated</td>
+</tr>
+<tr>
+<td>#H5Ovisit by name1</td>
+<td>deprecated</td>
+</tr>
+<tr>
+<td>#H5Ovisit2</td>
+<td>deprecated</td>
+</tr>
+<tr>
+<td>#H5Ovisit by name2</td>
+<td>deprecated</td>
+</tr>
+</table>
+//! [vol_native_table]
+ *
+ *
+//! [vol_independent_table]
+<table>
+<caption>Alphabetical list of VOL-independent HDF5 API calls</caption>
+<tr>
+<th>API</th>
+<th>Description</th>
+</tr>
+<tr>
+<td>H5*</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Dfill</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Dgather</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Diterate</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Dscatter</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Dvlen_reclaim</td>
+<td>deprecated</td>
+</tr>
+<tr>
+<td>#H5Dvlen_get_buf_size</td>
+<td></td>
+</tr>
+<tr>
+<td>H5E*</td>
+<td></td>
+</tr>
+<tr>
+<td>H5I*</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Lis_registered</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Lregister</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Lunpack_elink_val</td>
+<td></td>
+</tr>
+<tr>
+<td>#H5Lunregister</td>
+<td></td>
+</tr>
+<tr>
+<td>H5PL*</td>
+<td></td>
+</tr>
+<tr>
+<td>H5P*</td>
+<td></td>
+</tr>
+<tr>
+<td>H5S*</td>
+<td></td>
+</tr>
+<tr>
+<td>H5T*</td>
+<td>non-committed</td>
+</tr>
+<tr>
+<td>H5VL*</td>
+<td></td>
+</tr>
+<tr>
+<td>H5Z*</td>
+<td></td>
+</tr>
+</table>
+//! [vol_independent_table]
+ *
+ *
+//! [vol_optional_table]
+<table>
+<caption>List of Native VOL Optional Operation Values By Subclass</caption>
+<tr>
+<th>Subclass</th>
+<th>API Reference</th>
+<th>Definition</th>
+</tr>
+<tr>
+<th>H5VL_SUBCLS_ATTR</th>
+<td>#H5Aiterate (deprecated routine)</td>
+<td>#H5VL_NATIVE_ATTR_ITERATE_OLD</td>
+</tr>
+<tr>
+<th rowspan="11">H5VL_SUBCLS_DATASET</th>
+<td>H5Dformat_convert (internal)</td>
+<td>#H5VL_NATIVE_DATASET_FORMAT_CONVERT</td>
+</tr>
+<tr>
+<td>H5Dget_chunk_index_type (internal)</td>
+<td>#H5VL_NATIVE_DATASET_GET_CHUNK_INDEX_TYPE</td>
+</tr>
+<tr>
+<td>#H5Dget_chunk_storage_size</td>
+<td>#H5VL_NATIVE_DATASET_GET_CHUNK_STORAGE_SIZE</td>
+</tr>
+<tr>
+<td>#H5Dget_num_chunks</td>
+<td>#H5VL_NATIVE_DATASET_GET_NUM_CHUNKS</td>
+</tr>
+<tr>
+<td>#H5Dget_chunk_info</td>
+<td>#H5VL_NATIVE_DATASET_GET_CHUNK_INFO_BY_IDX</td>
+</tr>
+<tr>
+<td>#H5Dget_chunk_info_by_coord</td>
+<td>#H5VL_NATIVE_DATASET_GET_CHUNK_INFO_BY_COORD</td>
+</tr>
+<tr>
+<td>#H5Dread_chunk</td>
+<td>#H5VL_NATIVE_DATASET_CHUNK_READ</td>
+</tr>
+<tr>
+<td>#H5Dwrite_chunk</td>
+<td>#H5VL_NATIVE_DATASET_CHUNK_WRITE</td>
+</tr>
+<tr>
+<td>#H5Dvlen_get_buf_size</td>
+<td>#H5VL_NATIVE_DATASET_GET_VLEN_BUF_SIZE</td>
+</tr>
+<tr>
+<td>#H5Dget_offset</td>
+<td>#H5VL_NATIVE_DATASET_GET_OFFSET</td>
+</tr>
+<tr>
+<td>#H5Dget_offset</td>
+<td>#H5VL_NATIVE_DATASET_CHUNK_ITER</td>
+</tr>
+<tr>
+<th rowspan="29">H5VL_SUBCLS_FILE</th>
+<td>#H5Fclear_elink_file_cache</td>
+<td>#H5VL_NATIVE_FILE_CLEAR_ELINK_CACHE</td>
+</tr>
+<tr>
+<td>#H5Fget_file_image</td>
+<td>#H5VL_NATIVE_FILE_GET_FILE_IMAGE</td>
+</tr>
+<tr>
+<td>#H5Fget_free_sections</td>
+<td>#H5VL_NATIVE_FILE_GET_FREE_SECTIONS</td>
+</tr>
+<tr>
+<td>#H5Fget_freespace</td>
+<td>#H5VL_NATIVE_FILE_GET_FREE_SPACE</td>
+</tr>
+<tr>
+<td>#H5Fget_info1 / #H5Fget_info2</td>
+<td>#H5VL_NATIVE_FILE_GET_INFO</td>
+</tr>
+<tr>
+<td>#H5Fget_mdc_config</td>
+<td>#H5VL_NATIVE_FILE_GET_MDC_CONF</td>
+</tr>
+<tr>
+<td>#H5Fget_mdc_hit_rate</td>
+<td>#H5VL_NATIVE_FILE_GET_MDC_HR</td>
+</tr>
+<tr>
+<td>#H5Fget_mdc_size</td>
+<td>#H5VL_NATIVE_FILE_GET_MDC_SIZE</td>
+</tr>
+<tr>
+<td>#H5Fget_filesize</td>
+<td>#H5VL_NATIVE_FILE_GET_SIZE</td>
+</tr>
+<tr>
+<td>#H5Fget_vfd_handle</td>
+<td>#H5VL_NATIVE_FILE_GET_VFD_HANDLE</td>
+</tr>
+<tr>
+<td>#H5Freset_mdc_hit_rate_stats</td>
+<td>#H5VL_NATIVE_FILE_RESET_MDC_HIT_RATE</td>
+</tr>
+<tr>
+<td>#H5Fset_mdc_config</td>
+<td>#H5VL_NATIVE_FILE_SET_MDC_CONFIG</td>
+</tr>
+<tr>
+<td>#H5Fget_metadata_read_retry_info</td>
+<td>#H5VL_NATIVE_FILE_GET_METADATA_READ_RETRY_INFO</td>
+</tr>
+<tr>
+<td>#H5Fstart_swmr_write</td>
+<td>#H5VL_NATIVE_FILE_START_SWMR_WRITE</td>
+</tr>
+<tr>
+<td>#H5Fstart_mdc_logging</td>
+<td>#H5VL_NATIVE_FILE_START_MDC_LOGGING</td>
+</tr>
+<tr>
+<td>#H5Fstop_mdc_logging</td>
+<td>#H5VL_NATIVE_FILE_STOP_MDC_LOGGING</td>
+</tr>
+<tr>
+<td>#H5Fget_mdc_logging_status</td>
+<td>#H5VL_NATIVE_FILE_GET_MDC_LOGGING_STATUS</td>
+</tr>
+<tr>
+<td>H5Fformat_convert (internal)</td>
+<td>#H5VL_NATIVE_FILE_FORMAT_CONVERT</td>
+</tr>
+<tr>
+<td>#H5Freset_page_buffering_stats</td>
+<td>#H5VL_NATIVE_FILE_RESET_PAGE_BUFFERING_STATS</td>
+</tr>
+<tr>
+<td>#H5Fget_page_buffering_stats</td>
+<td>#H5VL_NATIVE_FILE_GET_PAGE_BUFFERING_STATS</td>
+</tr>
+<tr>
+<td>#H5Fget_mdc_image_info</td>
+<td>#H5VL_NATIVE_FILE_GET_MDC_IMAGE_INFO</td>
+</tr>
+<tr>
+<td>#H5Fget_eoa</td>
+<td>#H5VL_NATIVE_FILE_GET_EOA</td>
+</tr>
+<tr>
+<td>#H5Fincrement_filesize</td>
+<td>#H5VL_NATIVE_FILE_INCR_FILESIZE</td>
+</tr>
+<tr>
+<td>#H5Fset_latest_format/#H5Fset_libver_bounds</td>
+<td>#H5VL_NATIVE_FILE_SET_LIBVER_BOUNDS</td>
+</tr>
+<tr>
+<td>#H5Fget_dset_no_attrs_hint</td>
+<td>#H5VL_NATIVE_FILE_GET_MIN_DSET_OHDR_FLAG</td>
+</tr>
+<tr>
+<td>#H5Fset_dset_no_attrs_hint</td>
+<td>#H5VL_NATIVE_FILE_SET_MIN_DSET_OHDR_FLAG</td>
+</tr>
+<tr>
+<td>#H5Fget_mpi_atomicity</td>
+<td>#H5VL_NATIVE_FILE_GET_MPI_ATOMICITY</td>
+</tr>
+<tr>
+<td>#H5Fset_mpi_atomicity</td>
+<td>#H5VL_NATIVE_FILE_SET_MPI_ATOMICITY</td>
+</tr>
+<tr>
+<td>Adjust file after open, with wrapping context</td>
+<td>#H5VL_NATIVE_FILE_POST_OPEN</td>
+</tr>
+<tr>
+<th rowspan="2">H5VL_SUBCLS_GROUP</th>
+<td>#H5Giterate (deprecated routine)</td>
+<td>#H5VL_NATIVE_GROUP_ITERATE_OLD</td>
+</tr>
+<tr>
+<td>#H5Gget_objinfo (deprecated routine)</td>
+<td>#H5VL_NATIVE_GROUP_GET_OBJINFO</td>
+</tr>
+<tr>
+<th rowspan="6">H5VL_SUBCLS_OBJECT</th>
+<td>#H5Gget_comment, #H5Oget_comment, #H5Oget_comment_by_name</td>
+<td>#H5VL_NATIVE_OBJECT_GET_COMMENT</td>
+</tr>
+<tr>
+<td>#H5Gset_comment, #H5Oset_comment, #H5Oset_comment_by_name</td>
+<td>#H5VL_NATIVE_OBJECT_SET_COMMENT</td>
+</tr>
+<tr>
+<td>#H5Odisable_mdc_flushes</td>
+<td>#H5VL_NATIVE_OBJECT_DISABLE_MDC_FLUSHES</td>
+</tr>
+<tr>
+<td>#H5Oenable_mdc_flushes</td>
+<td>#H5VL_NATIVE_OBJECT_ENABLE_MDC_FLUSHES</td>
+</tr>
+<tr>
+<td>#H5Oare_mdc_flushes_disabled</td>
+<td>#H5VL_NATIVE_OBJECT_ARE_MDC_FLUSHES_DISABLED</td>
+</tr>
+<tr>
+<td>#H5Oget_native_info, #H5Oget_native_info_by_idx, #H5Oget_native_info_by_name</td>
+<td>#H5VL_NATIVE_OBJECT_GET_NATIVE_INFO/td>
+</tr>
+</table>
+//! [vol_optional_table]
+ *
+ */