Skip to content

Commit d28ba95

Browse files
byrnHDFqkoziol
byrnHDF
authored and
qkoziol
committed
Add tools usage text as doxygen for Tools UG (HDFGroup#4602)
1 parent 675d2e6 commit d28ba95

File tree

20 files changed

+1604
-1
lines changed

20 files changed

+1604
-1
lines changed

‎doxygen/Doxyfile.in

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -689,6 +689,8 @@ FILE_PATTERNS = H5*public.h H5*module.h H5*develop.h H5FD*.h \
689689
*.F90 \
690690
*.dox \
691691
*.md \
692+
h5copy.h h5diff_main.h h5dump.h h5format_convert.h h5import.h h5jam.h h5ls.h h5repack.h h5stat.h \
693+
h5watch.h h5clear.h h5debug.h h5delete.h h5mkgrp.h h5repart.h \
692694
H5Cpp.h H5AbstractDs.h H5AtomType.h H5Attribute.h H5CommonFG.h H5CompType.h \
693695
H5DataSet.h H5DataSpace.h H5DataType.h H5OcreatProp.h H5DaccProp.h H5DcreatProp.h \
694696
H5DxferProp.h H5EnumType.h H5Exception.h H5FaccProp.h H5FcreatProp.h H5File.h \

‎doxygen/dox/Tools.dox

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
/** @page CommandTools Command Line Tools for HDF5 Files
2+
3+
Navigate back: \ref index "Main"
4+
<hr>
5+
6+
7+
\section sec_cltools Command Line Tools for HDF5 Files
8+
There are several command line tools provided with HDF5.
9+
\li \ref sec_cltools_h5copy
10+
\li \ref sec_cltools_h5diff
11+
\li \ref sec_cltools_h5dump
12+
\li \ref sec_cltools_h5format_convert
13+
\li \ref sec_cltools_h5import
14+
\li \ref sec_cltools_h5jam
15+
\li \ref sec_cltools_h5ls
16+
\li \ref sec_cltools_h5repack
17+
\li \ref sec_cltools_h5stat
18+
\li \ref sec_cltools_h5clear
19+
\li \ref sec_cltools_h5debug
20+
\li \ref sec_cltools_h5delete
21+
\li \ref sec_cltools_h5mkgrp
22+
\li \ref sec_cltools_h5repart
23+
\li \ref sec_cltools_h5watch
24+
25+
26+
<hr>
27+
Navigate back: \ref index "Main"
28+
29+
*/

‎doxygen/dox/UsersGuide.dox

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -309,6 +309,8 @@
309309

310310
\ref sec_map
311311

312+
\ref sec_cltools
313+
312314
\ref sec_addition
313315

314316
\page AR_UG Additional Resources

‎hl/tools/h5watch/h5watch.h

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
2+
* Copyright by The HDF Group. *
3+
* All rights reserved. *
4+
* *
5+
* This file is part of HDF5. The full HDF5 copyright notice, including *
6+
* terms governing use, modification, and redistribution, is contained in *
7+
* the COPYING file, which can be found at the root of the source code *
8+
* distribution tree, or in https://www.hdfgroup.org/licenses. *
9+
* If you do not have access to either file, you may request a copy from *
10+
* help@hdfgroup.org. *
11+
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
12+
#ifndef H5WATCH_H
13+
#define H5WATCH_H
14+
15+
/** \page H5TOOL_WH_UG The HDF5 h5watch Tool
16+
*
17+
* \section sec_cltools_h5watch h5watch
18+
*
19+
* \subsection subsec_cltools_h5watch_intro Introduction
20+
* With h5watch, you can dump stats from an HDF5 file.
21+
*
22+
* \subsection subsec_cltools_h5watch_usage Usage
23+
* <h4>h5watch [OPTIONS] [OBJECT]</h4>
24+
*
25+
* \subsection subsec_cltools_h5watch_error Error Report Option
26+
* \li <strong>--enable-error-stack</strong> Prints messages from the HDF5 error stack as they occur.
27+
* Optional value 2 also prints file open errors, --enable-error-stack=2.
28+
*
29+
* \subsection subsec_cltools_h5watch_options Options
30+
* \li <strong>--help</strong> Print a usage message and exit
31+
* \li <strong>--version</strong> Print the library version number and exit
32+
* \li <strong>--label</strong> Label members of compound typed dataset.
33+
* \li <strong>--simple</strong> Use a machine-readable output format.
34+
* \li <strong>--dim</strong> Monitor changes in size of dataset dimensions only.
35+
* \li <strong>--width=N</strong> Set the number of columns to N for output.<br />
36+
* A value of 0 sets the number of columns to the
37+
* maximum (65535). The default width is 80 columns.
38+
* \li <strong>--polling=N</strong> Set the polling interval to N (in seconds) when the
39+
* dataset will be checked for appended data.
40+
* The default polling interval is 1.
41+
* \li <strong>--fields=\<list_of_fields\></strong>
42+
* Display data for the fields specified in \<list_of_fields\>
43+
* for a compound data type.
44+
* \<list_of_fields\> can be specified as follows:
45+
* <ul><li>1) A comma-separated list of field names in a
46+
* compound data type. "," is the separator for field names while "." is the separator
47+
* for a nested field.</li>
48+
* <li>2) A single field name in a compound data type.
49+
* This option can be used multiple times.</li></ul>
50+
* Note that backslash is the escape character to avoid
51+
* characters in field names that conflict with the tool's separators.
52+
*
53+
* \subsection subsec_cltools_h5watch_objs Object
54+
* <strong>OBJECT</strong> is specified as [\<filename\>/\<path_to_dataset\>/\<dsetname\>]
55+
* \li <strong>\<filename\></strong> Name of the HDF5 file. It may be preceded by path
56+
* separated by slashes to the specified HDF5 file.
57+
* \li <strong>\<path_to_dataset\></strong> Path separated by slashes to the specified dataset
58+
* \li <strong>\<dsetname\></strong> Name of the dataset
59+
*
60+
*/
61+
62+
#endif /* H5WATCH_H */

‎release_docs/RELEASE.txt

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -777,6 +777,10 @@ New Features
777777

778778
Tools:
779779
------
780+
- Add doxygen files for the tools
781+
782+
Implement the tools usage text as pages in doxygen.
783+
780784
- Add option to adjust the page buffer size in tools
781785

782786
The page buffer cache size for a file can now be adjusted using the

‎tools/src/h5copy/h5copy.h

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
2+
* Copyright by The HDF Group. *
3+
* All rights reserved. *
4+
* *
5+
* This file is part of HDF5. The full HDF5 copyright notice, including *
6+
* terms governing use, modification, and redistribution, is contained in *
7+
* the COPYING file, which can be found at the root of the source code *
8+
* distribution tree, or in https://www.hdfgroup.org/licenses. *
9+
* If you do not have access to either file, you may request a copy from *
10+
* help@hdfgroup.org. *
11+
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
12+
13+
#ifndef H5COPY_H
14+
#define H5COPY_H
15+
16+
/** \page H5TOOL_CP_UG The HDF5 h5copy Tool
17+
*
18+
* \section sec_cltools_h5copy h5copy
19+
*
20+
* \subsection subsec_cltools_h5copy_intro Introduction
21+
* With h5copy, you can copy objects from an HDF5 file to another file.
22+
*
23+
* \subsection subsec_cltools_h5copy_usage Usage
24+
* <h4>h5copy [OPTIONS] [OBJECTS...]</h4>
25+
*
26+
* \subsection subsec_cltools_h5copy_objs Objects
27+
* \li <strong>--input</strong> input file name
28+
* \li <strong>--output</strong> output file name
29+
* \li <strong>--source</strong> source object name
30+
* \li <strong>--destination</strong> destination object name
31+
*
32+
* \subsection subsec_cltools_h5copy_error Error Report Option
33+
* \li <strong>--enable-error-stack</strong> Prints messages from the HDF5 error stack as they occur.
34+
Optional value 2 also prints file open errors, --enable-error-stack=2.
35+
*
36+
* \subsection subsec_cltools_h5copy_options Options
37+
* \li <strong>--help</strong> Print a usage message and exit
38+
* \li <strong>--parents</strong> No error if existing, make parent groups as needed
39+
* \li <strong>--verbose</strong> Print information about OBJECTS and OPTIONS
40+
* \li <strong>--version</strong> Print the library version number and exit
41+
* \li <strong>--flag</strong> Flag type
42+
*
43+
* \subsubsection subsubsec_cltools_h5copy_options_args Flag Type Options
44+
* Flag type is one of the following strings:
45+
* \li <strong>shallow</strong> Copy only immediate members for groups
46+
* \li <strong>soft</strong> Expand soft links into new objects
47+
* \li <strong>ext</strong> Expand external links into new objects
48+
* \li <strong>ref</strong> Copy references and any referenced objects, i.e., objects
49+
* that the references point to.<br />
50+
* Referenced objects are copied in addition to the objects
51+
* specified on the command line and reference datasets are
52+
* populated with correct reference values. Copies of referenced
53+
* datasets outside the copy range specified on the command line
54+
* will normally have a different name from the original.<br />
55+
* (Default: Without this option, reference value(s) in any
56+
* reference datasets are set to NULL and referenced objects are
57+
* not copied unless they are otherwise within the copy range
58+
* specified on the command line.)
59+
* \li <strong>noattr</strong> Copy object without copying attributes
60+
* \li <strong>allflags</strong> Switches all flags from the default to the non-default setting
61+
*
62+
* These flag types correspond to the following API symbols
63+
* \li <strong>#H5O_COPY_SHALLOW_HIERARCHY_FLAG</strong>
64+
* \li <strong>#H5O_COPY_EXPAND_SOFT_LINK_FLAG</strong>
65+
* \li <strong>#H5O_COPY_EXPAND_EXT_LINK_FLAG</strong>
66+
* \li <strong>#H5O_COPY_EXPAND_REFERENCE_FLAG</strong>
67+
* \li <strong>#H5O_COPY_WITHOUT_ATTR_FLAG</strong>
68+
* \li <strong>#H5O_COPY_ALL</strong>
69+
*
70+
*/
71+
72+
#endif /* H5COPY_H */

0 commit comments

Comments
 (0)