Add tools usage text as doxygen for Tools UG (HDFGroup#4602)

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/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

@@ -309,6 +309,8 @@
 
 \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     *
+ * [email protected].                                                        *
+ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
+#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

@@ -777,6 +777,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     *
+ * [email protected].                                                        *
+ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
+
+#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 */