Add tools usage text as doxygen for Tools UG

doxygen/Doxyfile.in

@@ -689,6 +689,8 @@ FILE_PATTERNS  = H5*public.h H5*module.h H5*develop.h H5FD*.h \
                  *.F90 \
                  *.dox \
                  *.md \
+                 h5copy.h h5diff_main.h h5dump.h h5format_convert.h h5import.h h5jam.h h5ls.h h5repack.h h5stat.h \
+                 h5watch.h h5clear.h h5debug.h h5delete.h h5mkgrp.h h5repart.h \
                  H5Cpp.h H5AbstractDs.h H5AtomType.h H5Attribute.h H5CommonFG.h H5CompType.h \
                  H5DataSet.h H5DataSpace.h H5DataType.h H5OcreatProp.h H5DaccProp.h H5DcreatProp.h \
                  H5DxferProp.h H5EnumType.h H5Exception.h H5FaccProp.h H5FcreatProp.h H5File.h \

doxygen/aliases

@@ -387,8 +387,8 @@ ALIASES += str_pad_type="<table><tr><td>#H5T_STR_NULLTERM</td><td>0</td><td>Null
 ALIASES += see_virtual=" \see Supporting Functions: H5Pget_layout(), H5Pset_layout(), H5Sget_regular_hyperslab(), H5Sis_regular_hyperslab(), H5Sselect_hyperslab() \see VDS Functions: H5Pget_virtual_count(), H5Pget_virtual_dsetname(), H5Pget_virtual_filename(), H5Pget_virtual_prefix(), H5Pget_virtual_printf_gap(), H5Pget_virtual_srcspace(), H5Pget_virtual_view(), H5Pget_virtual_vspace(), H5Pset_virtual(), H5Pset_virtual_prefix(), H5Pset_virtual_printf_gap(), H5Pset_virtual_view()"
 ALIASES += obj_info_fields="<table><tr><th>Flag</th><th>Purpose</th></tr><tr><td>#H5O_INFO_BASIC</td><td>Fill in the fileno, addr, type, and rc fields</td></tr><tr> <td>#H5O_INFO_TIME</td><td>Fill in the atime, mtime, ctime, and btime fields</td></tr><tr> <td>#H5O_INFO_NUM_ATTRS</td> <td>Fill in the num_attrs field</td></tr><tr><td>#H5O_INFO_HDR</td><td>Fill in the num_attrs field</td></tr><tr><td>#H5O_INFO_META_SIZE</td><td>Fill in the meta_size field</td></tr><tr><td>#H5O_INFO_ALL</td><td>#H5O_INFO_BASIC | #H5O_INFO_TIME | #H5O_INFO_NUM_ATTRS | #H5O_INFO_HDR | #H5O_INFO_META_SIZE</td></tr></table>"
 
-ALIASES += details_namelen{2}="Up to \p size characters of the \1 name are returned in \p name; additional characters, if any, are not returned to the user application.\n\n If the length of the \1 name, which determines the required value of \p size, is unknown, a preliminary call to \2() with the last two parameters set to NULL and zero respectively can be made. The return value of this call will be the size in bytes of the \1 name. That value, plus 1 for a NULL terminator, must then be assigned to \p size for a second \2() call, which will retrieve the actual \1 name.
-ALIASES += details_namelen_plusone{2}="Up to \p size characters of the \1 name are returned in \p name; additional characters, if any, are not returned to the user application.\n\n If the length of the \1 name, which determines the required value of \p size, is unknown, a preliminary call to \2() with the last two parameters set to NULL and zero respectively can be made. The return value of this call will be the size in bytes of the \1 name plus 1 for a NULL terminator. That value must then be assigned to \p size for a second \2() call, which will retrieve the actual \1 name.
+ALIASES += details_namelen{2}="Up to \p size characters of the \1 name are returned in \p name; additional characters, if any, are not returned to the user application.\n\n If the length of the \1 name, which determines the required value of \p size, is unknown, a preliminary call to \2() with the last two parameters set to NULL and zero respectively can be made. The return value of this call will be the size in bytes of the \1 name. That value, plus 1 for a NULL terminator, must then be assigned to \p size for a second \2() call, which will retrieve the actual \1 name."
+ALIASES += details_namelen_plusone{2}="Up to \p size characters of the \1 name are returned in \p name; additional characters, if any, are not returned to the user application.\n\n If the length of the \1 name, which determines the required value of \p size, is unknown, a preliminary call to \2() with the last two parameters set to NULL and zero respectively can be made. The return value of this call will be the size in bytes of the \1 name plus 1 for a NULL terminator. That value must then be assigned to \p size for a second \2() call, which will retrieve the actual \1 name."
 
 
 ################################################################################

doxygen/dox/Tools.dox

@@ -0,0 +1,29 @@
+/** @page CommandTools Command Line Tools for HDF5 Files
+
+Navigate back: \ref index "Main"
+<hr>
+
+
+\section sec_cltools Command Line Tools for HDF5 Files
+There are several command line tools provided with HDF5.
+\li \ref sec_cltools_h5copy
+\li \ref sec_cltools_h5diff
+\li \ref sec_cltools_h5dump
+\li \ref sec_cltools_h5format_convert
+\li \ref sec_cltools_h5import
+\li \ref sec_cltools_h5jam
+\li \ref sec_cltools_h5ls
+\li \ref sec_cltools_h5repack
+\li \ref sec_cltools_h5stat
+\li \ref sec_cltools_h5clear
+\li \ref sec_cltools_h5debug
+\li \ref sec_cltools_h5delete
+\li \ref sec_cltools_h5mkgrp
+\li \ref sec_cltools_h5repart
+\li \ref sec_cltools_h5watch
+
+
+<hr>
+Navigate back: \ref index "Main"
+
+*/

doxygen/dox/UsersGuide.dox

@@ -316,6 +316,8 @@ HDF5 Release 1.14
 
 \ref sec_map
 
+\ref sec_cltools
+
 \ref sec_addition
 
 \page AR_UG Additional Resources

hl/tools/h5watch/h5watch.h

@@ -0,0 +1,62 @@
+/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+ * Copyright by The HDF Group.                                               *
+ * All rights reserved.                                                      *
+ *                                                                           *
+ * This file is part of HDF5.  The full HDF5 copyright notice, including     *
+ * terms governing use, modification, and redistribution, is contained in    *
+ * the COPYING file, which can be found at the root of the source code       *
+ * distribution tree, or in https://www.hdfgroup.org/licenses.               *
+ * If you do not have access to either file, you may request a copy from     *
+ * help@hdfgroup.org.                                                        *
+ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
+#ifndef H5WATCH_H
+#define H5WATCH_H
+
+/** \page H5TOOL_WH_UG The HDF5 h5watch Tool
+ *
+ * \section sec_cltools_h5watch h5watch
+ *
+ * \subsection subsec_cltools_h5watch_intro Introduction
+ *  With h5watch, you can dump stats from an HDF5 file.
+ *
+ * \subsection subsec_cltools_h5watch_usage Usage
+ *  <h4>h5watch [OPTIONS] [OBJECT]</h4>
+ *
+ * \subsection subsec_cltools_h5watch_error Error Report Option
+ * \li <strong>--enable-error-stack</strong> Prints messages from the HDF5 error stack as they occur.
+ *             Optional value 2 also prints file open errors, --enable-error-stack=2.
+ *
+ * \subsection subsec_cltools_h5watch_options Options
+ * \li <strong>--help</strong>    Print a usage message and exit
+ * \li <strong>--version</strong> Print the library version number and exit
+ * \li <strong>--label</strong>   Label members of compound typed dataset.
+ * \li <strong>--simple</strong>  Use a machine-readable output format.
+ * \li <strong>--dim</strong>     Monitor changes in size of dataset dimensions only.
+ * \li <strong>--width=N</strong> Set the number of columns to N for output.<br />
+ *                                A value of 0 sets the number of columns to the
+ *                                maximum (65535). The default width is 80 columns.
+ * \li <strong>--polling=N</strong> Set the polling interval to N (in seconds) when the
+ *                                dataset will be checked for appended data.
+ *                                The default polling interval is 1.
+ * \li <strong>--fields=\<list_of_fields\></strong>
+ *     Display data for the fields specified in \<list_of_fields\>
+ *     for a compound data type.
+ *     \<list_of_fields\> can be specified as follows:
+ *     <ul><li>1) A comma-separated list of field names in a
+ *     compound data type. "," is the separator for field names while "." is the separator
+ *     for a nested field.</li>
+ *     <li>2) A single field name in a compound data type.
+ *     This option can be used multiple times.</li></ul>
+ *     Note that backslash is the escape character to avoid
+ *     characters in field names that conflict with the tool's separators.
+ *
+ * \subsection subsec_cltools_h5watch_objs Object
+ *  <strong>OBJECT</strong> is specified as [\<filename\>/\<path_to_dataset\>/\<dsetname\>]
+ * \li <strong>\<filename\></strong>  Name of the HDF5 file. It may be preceded by path
+ *                                    separated by slashes to the specified HDF5 file.
+ * \li <strong>\<path_to_dataset\></strong> Path separated by slashes to the specified dataset
+ * \li <strong>\<dsetname\></strong>  Name of the dataset
+ *
+ */
+
+#endif /* H5WATCH_H */

release_docs/RELEASE.txt

@@ -765,6 +765,10 @@ New Features
 
     Tools:
     ------
+    - Add doxygen files for the tools
+
+      Implement the tools usage text as pages in doxygen.
+
     - Add option to adjust the page buffer size in tools
 
       The page buffer cache size for a file can now be adjusted using the

tools/src/h5copy/h5copy.h

@@ -0,0 +1,72 @@
+/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+ * Copyright by The HDF Group.                                               *
+ * All rights reserved.                                                      *
+ *                                                                           *
+ * This file is part of HDF5.  The full HDF5 copyright notice, including     *
+ * terms governing use, modification, and redistribution, is contained in    *
+ * the COPYING file, which can be found at the root of the source code       *
+ * distribution tree, or in https://www.hdfgroup.org/licenses.               *
+ * If you do not have access to either file, you may request a copy from     *
+ * help@hdfgroup.org.                                                        *
+ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
+
+#ifndef H5COPY_H
+#define H5COPY_H
+
+/** \page H5TOOL_CP_UG The HDF5 h5copy Tool
+ *
+ * \section sec_cltools_h5copy h5copy
+ *
+ * \subsection subsec_cltools_h5copy_intro Introduction
+ *  With h5copy, you can copy objects from an HDF5 file to another file.
+ *
+ * \subsection subsec_cltools_h5copy_usage Usage
+ *  <h4>h5copy [OPTIONS] [OBJECTS...]</h4>
+ *
+ * \subsection subsec_cltools_h5copy_objs Objects
+ * \li <strong>--input</strong>        input file name
+ * \li <strong>--output</strong>       output file name
+ * \li <strong>--source</strong>       source object name
+ * \li <strong>--destination</strong>  destination object name
+ *
+ * \subsection subsec_cltools_h5copy_error Error Report Option
+ * \li <strong>--enable-error-stack</strong> Prints messages from the HDF5 error stack as they occur.
+                          Optional value 2 also prints file open errors, --enable-error-stack=2.
+ *
+ * \subsection subsec_cltools_h5copy_options Options
+ * \li <strong>--help</strong>    Print a usage message and exit
+ * \li <strong>--parents</strong> No error if existing, make parent groups as needed
+ * \li <strong>--verbose</strong> Print information about OBJECTS and OPTIONS
+ * \li <strong>--version</strong> Print the library version number and exit
+ * \li <strong>--flag</strong>    Flag type
+ *
+ * \subsubsection subsubsec_cltools_h5copy_options_args Flag Type Options
+ *  Flag type is one of the following strings:
+ * \li <strong>shallow</strong> Copy only immediate members for groups
+ * \li <strong>soft</strong>    Expand soft links into new objects
+ * \li <strong>ext</strong>     Expand external links into new objects
+ * \li <strong>ref</strong>     Copy references and any referenced objects, i.e., objects
+ *                  that the references point to.<br />
+ *                  Referenced objects are copied in addition to the objects
+ *                  specified on the command line and reference datasets are
+ *                  populated with correct reference values. Copies of referenced
+ *                  datasets outside the copy range specified on the command line
+ *                  will normally have a different name from the original.<br />
+ *                  (Default: Without this option, reference value(s) in any
+ *                  reference datasets are set to NULL and referenced objects are
+ *                  not copied unless they are otherwise within the copy range
+ *                  specified on the command line.)
+ * \li <strong>noattr</strong>   Copy object without copying attributes
+ * \li <strong>allflags</strong> Switches all flags from the default to the non-default setting
+ *
+ * These flag types correspond to the following API symbols
+ * \li <strong>#H5O_COPY_SHALLOW_HIERARCHY_FLAG</strong>
+ * \li <strong>#H5O_COPY_EXPAND_SOFT_LINK_FLAG</strong>
+ * \li <strong>#H5O_COPY_EXPAND_EXT_LINK_FLAG</strong>
+ * \li <strong>#H5O_COPY_EXPAND_REFERENCE_FLAG</strong>
+ * \li <strong>#H5O_COPY_WITHOUT_ATTR_FLAG</strong>
+ * \li <strong>#H5O_COPY_ALL</strong>
+ *
+ */
+
+#endif /* H5COPY_H */