Add tools usage text as doxygen for Tools UG #4602

byrnHDF · 2024-06-24T18:54:49Z

No description provided.

byrnHDF · 2024-06-24T20:14:53Z

bmribler

There are extra leading spaces in various paragraphs.
I'm aware that some of the text that I suggested to change were from the source code, but we can improve it here, and in the source code when we have the chance.

tools/src/misc/h5clear.h

hl/tools/h5watch/h5watch.h

tools/src/h5jam/h5jam.h

tools/src/h5import/h5import.h

byrnHDF · 2024-06-24T21:09:38Z

There are extra leading spaces in various paragraphs. I'm aware that some of the text that I suggested to change were from the source code, but we can improve it here, and in the source code when we have the chance.

Oh yes this is a work in progress - for sure. Just remember that the important text is what is in the doxygen generated files! And first off I just need to make sure that is correct then come back and cleanup the source. So just keep the comments coming in!

lrknox · 2024-06-26T19:17:26Z

hl/tools/h5watch/h5watch.h

+ *     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 separatorfor field names while "." is the separator


Suggested change

* compound data type. "," is the separatorfor field names while "." is the separator

* compound data type. "," is the separator for field names while "." is the separator

Add missing space after "separator"

lrknox · 2024-06-26T19:51:30Z

tools/src/h5copy/h5copy.h

+ *
+ * \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.


Code says enable-error-stack takes an optional_arg. Reading the help message I wasn't sure how the value 2 was to be specified. Would "Optional argument 2 be clearer?

lrknox · 2024-06-26T20:09:17Z

tools/src/h5diff/h5diff_main.h

+ * \section sec_cltools_h5diff h5diff
+ *
+ * \subsection subsec_cltools_h5diff_intro Introduction
+ * With h5diff, you can compare objects between a HDF5 file and another file.


"between an HDF5 file", or possibly "you can compare objects in two HDF5 files" might be better.

"Optional value 2" in line 32: see comment in h5copy.h.
Also "Error Report Option"?

lrknox · 2024-06-26T20:21:07Z

tools/src/h5diff/h5diff_main.h

+ * \li <strong>--vfd-info-2</strong> VFD-specific info to pass to the VFL driver used for
+ *                           opening the second HDF5 file specified
+ * \li <strong>--follow-symlinks</strong>
+ *         Follow symbolic links (soft links and external links and compare the)


should the ')' come after "external links" and before "and compare the"?

lrknox · 2024-06-26T20:29:37Z

tools/src/h5diff/h5diff_main.h

+ * \li <strong>--compare</strong> List objects that are not comparable
+ * \li <strong>--nan</strong> Avoid NaNs detection
+ * \li <strong>--count=C</strong> Print differences up to C. C must be a positive integer.
+ * \li <strong>--delta=D</strong>


In these three options, "Where a is ..." is a sentence fragment. "... positive number, where a is ..." would be grammatically correct.

lrknox · 2024-06-26T20:43:31Z

tools/src/h5diff/h5diff_main.h

+ * \li 4) <strong>Symbolic links</strong>
+ *      The paths to the target objects are compared.
+ *      (The option --follow-symlinks overrides the default behavior when
+ *       symbolic links are compared.).


Second '.' after ')' is unnecessary/incorrect.

lrknox · 2024-06-26T21:15:07Z

tools/src/h5dump/h5dump.h

+ *
+ * \subsection subsec_cltools_h5dump_options_file File Options
+ * \li <strong>--contents</strong>   Print a list of the file contents and exit
+ *                                   Optional value 1 also prints attributes.


just curious: does it print attribute names, values, or both?

lrknox · 2024-06-26T22:05:50Z

tools/src/h5dump/h5dump.h

+ * \li <strong>--stride=STRIDE</strong>  Hyperslab stride
+ * \li <strong>--count=COUNT</strong>    Number of blocks to include in selection
+ * \li <strong>--block=BLOCK</strong>    Size of block in hyperslab
+ *  \b START, \b COUNT, \b STRIDE, and \b BLOCK - is a list of integers the number of which are equal to the


I think (I could be wrong) that each of START, COUNT, STRIDE and BLOCK is a list of integers, and as written it could be interpreted that START, COUNT, STRIDE and BLOCK is a list.

lrknox · 2024-07-09T19:10:04Z

tools/src/h5format_convert/h5format_convert.h

+ *      - compact/contiguous dataset: downgrade the layout version to 3
+ *      - virtual dataset: no action
+ *
+ * \li 3) h5format_convert --noop -dname=/group/dataset file_name


should be --dname according to line 33.

lrknox · 2024-07-09T19:27:11Z

tools/src/h5import/h5import.h

+ * \subsection subsec_cltools_h5import_desc Description
+ *  The primary objective of the utility is to convert floating
+      point or integer data stored in \b ASCII text or binary form
+      into a data-set according to the type and storage properties


This file has 7 instances of data-set and ~20 of dataset. All other files in tools/src do not have data-set. Why in this file?

lrknox · 2024-07-09T19:31:31Z

tools/src/h5import/h5import.h

+      specified in this configuration file. A point to note is
+      that the floating point data in the \b ASCII text file may be
+      organized in the fixed floating form (for example 323.56)
+      or in a scientific notation (for example 3.23E+02). A


should be either "or in scientific notation" or else "or in a scientific notation form".

lrknox · 2024-07-09T19:34:35Z

tools/src/h5import/h5import.h

+      \li 5. <strong>Compressed </strong> (has to be chunked)
+      \li 6. <strong>Compressed & Extendible</strong> (has to be chunked)
+
+      If the user wants to store raw data in a non-HDF file then


lrknox · 2024-07-09T19:35:33Z

tools/src/h5import/h5import.h

+      unlimited, the extendible data set option can be chosen.
+
+      The user may also specify the type of compression and the
+      level to which the data set must be compresses by setting


"must be compressed"

lrknox · 2024-07-09T19:46:18Z

tools/src/h5import/h5import.h

+      <li>STR</li>
+      <li>TEXTUIN</li>
+      <li>UIN</li></ul>
+      \b INPUT-CLASS "TEXTIN" denotes an ASCII text  file with signed integer data in ASCII form,


extra space between text and file in line 183

lrknox · 2024-07-09T19:47:59Z

tools/src/h5import/h5import.h

+      "FP" denotes a floating point binary file,
+      "IN" denotes a signed integer binary file,
+      "UIN" denotes an unsigned integer binary file,
+       & "STR" denotes an ASCII text file the contents of which should be stored as an 1-D


stored as a 1-D

lrknox · 2024-07-09T19:49:42Z

tools/src/h5import/h5import.h

+      Integer denoting the number of dimensions.
+
+ * \li <strong>DIMENSION-SIZES</strong>
+      Integers separated by spaces to denote the dimension sizes for the no. of dimensions


why abbreviate "no." here?

lrknox · 2024-07-09T19:51:03Z

tools/src/h5import/h5import.h

+      determined by rank.
+
+ * \li <strong>OUTPUT-CLASS</strong>
+      String dentoting data type of the dataset to  be written ("IN","FP", "UIN")


denoting
extra space between "to" and "be"

lrknox · 2024-07-09T19:51:46Z

tools/src/h5import/h5import.h

+      String dentoting data type of the dataset to  be written ("IN","FP", "UIN")
+
+ * \li <strong>OUTPUT-SIZE</strong>
+      Integer denoting the size of the data in the  output dataset to be written.


extra space

lrknox · 2024-07-11T15:22:39Z

tools/src/h5repack/h5repack.h

+ * \li <strong>--indexed=L2</strong>    Minimum number of links in the indexed format
+ * \li <strong>--ssize=S[:F]</strong>   Shared object header message minimum size
+ * \li <strong>--minimum=M</strong>     Do not apply the filter to datasets smaller than M
+ * \li <strong>--file=E</strong>        Name of file E with the -f and -l options


If this doxygen section doesn't have entries for -f and -l, this line for --file should probably read "... with the --filter and --layout options"

lrknox · 2024-07-11T15:53:05Z

tools/src/h5repack/h5repack.h

+ *                 driver.
+ * \li The default strategy when not set is \b FSM_AGGR without persisting free-space.
+ *
+ * \li <strong>FS_PERSIST</strong> is 1 to persisting free-space or 0 to not persisting free-space.


could maybe be "1 for persisting" and "0 for not persisting"?

…evelop-tools-doxy

* Test fixes for log-based vol (#4618) * fixes to address failures in the log-based VOL * moved file cleanup to tests proper * skipped index API test if not supported * Add 'try' parameter to H5Z_find, and remove calls to H5E_clear_stack() (#4609) * Bump the github-actions group with 4 updates (#4620) Bumps the github-actions group with 4 updates: [actions/checkout](https://github.com/actions/checkout), [aws-actions/configure-aws-credentials](https://github.com/aws-actions/configure-aws-credentials), [softprops/action-gh-release](https://github.com/softprops/action-gh-release) and [github/codeql-action](https://github.com/github/codeql-action). Updates `actions/checkout` from 4.1.1 to 4.1.7 - [Release notes](https://github.com/actions/checkout/releases) - [Commits](actions/checkout@v4.1.1...v4.1.7) Updates `aws-actions/configure-aws-credentials` from 1 to 4 - [Release notes](https://github.com/aws-actions/configure-aws-credentials/releases) - [Changelog](https://github.com/aws-actions/configure-aws-credentials/blob/main/CHANGELOG.md) - [Commits](aws-actions/configure-aws-credentials@v1...v4) Updates `softprops/action-gh-release` from 2.0.5 to 2.0.6 - [Release notes](https://github.com/softprops/action-gh-release/releases) - [Changelog](https://github.com/softprops/action-gh-release/blob/master/CHANGELOG.md) - [Commits](softprops/action-gh-release@69320db...a74c6b7) Updates `github/codeql-action` from 3.25.7 to 3.25.11 - [Release notes](https://github.com/github/codeql-action/releases) - [Changelog](https://github.com/github/codeql-action/blob/main/CHANGELOG.md) - [Commits](github/codeql-action@f079b84...b611370) --- updated-dependencies: - dependency-name: actions/checkout dependency-type: direct:production update-type: version-update:semver-patch dependency-group: github-actions - dependency-name: aws-actions/configure-aws-credentials dependency-type: direct:production update-type: version-update:semver-major dependency-group: github-actions - dependency-name: softprops/action-gh-release dependency-type: direct:production update-type: version-update:semver-patch dependency-group: github-actions - dependency-name: github/codeql-action dependency-type: direct:production update-type: version-update:semver-patch dependency-group: github-actions ... Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * Fix a stack size warning in ros3 VFD code (#4625) Just makes a stack array dynamic. Valgrind shows no memory leaks. * Reworked cleaning up API test files (#4626) * Reworked cleaning up test files, only removing test files if present to account for skipped tests * changed to using H5Fis_accessible * update to full use of remove_test_file * corrected offset type in C wrapper (#4622) * Remove some internal use of API calls and H5E_BEGIN_TRY/H5E_END_TRY (#4624) * Remove auto NSIS check because of issues with CI (#4646) * Add python testing for examples (#4628) * Clean up Fortran __float128 configure-time checks (#4649) * Always use DECIMAL_DIG instead of LDBL_DIG. This was controlled by an ifdef that is always true in C99 or greater It's confusing to use float.h C constants as variable names in configure.ac and the PAC_FC_LDBL_DIG macro. * Directly compare MY_FLT128_DIG and MY_LDBL_DIG * Make uniform across CMake and Autotools * Don't export quadmath.h variables to H5pubconf.h * Feature/awesome (#4604) * Added Doxygen Awesome and fixed a few quirks. * Fixed unterminated strings. * Added Doxygen Awesome by copy. * Add tools usage text as doxygen for Tools UG (#4602) * Add h5* compiler wrapper testing for CMake #4605 (#4613) * Add show option * remove non-static libs and correct names of static libs * Fixup the pkg-config libs and comp builds * Fix commands and add fortran pkg-config test scripts * Add help usage option * Add temporary fix for ARM64 Mac _Float16 build failure (#4639) * Correct H5VL_t ref count on H5O_refresh_metadata failure (#4636) * Fix bad H5VL_t rc on H5O_refresh_metadata fail * Decrement nrefs before raising error * Update doxygen Learn Basics / example refs. Add Reference sections (#4640) * Fixed messed up table captions. (#4653) * Fixed messed up table captions. Browsers don't seem to respect relative values for width. Hardcoding 800px for now. * Fixed FetchContent usage for new CMake reqs. (#4650) CMake version 3.30 changed the behavior of the FetchContent module to deprecate the use of FetchContent_Populate() in favor of FetchContent_MakeAvailable(). Therefore, the copying of HDF specialized CMakeLists.txt files to the dependent project's source was implemented in the FetchContent_Declare() call. * Fixed usage issue with FindZLIB.cmake module (#4655) * Add a comment on the FindZLIB.cmake module usage * Allow choice of static/shared compression libs for Find Module * Added new option to INSTALL_CMake file and changed option text * Eliminate more H5E_BEGIN/END_TRY macros and H5E_clear_stack() calls (#4648) * Correct name of zlib_ng option (#4658) * Fix the examples for testing java with binaries (#4660) * Update filename in RELEASE_PROCESS.md to current name INSTALL_autotools.txt. * Remove reference to V116 in tools/src/h5repack/h5repack.h.

byrnHDF and others added 7 commits June 21, 2024 13:08

Add doxygen version of tools usage

1df2bb1

Committing clang-format changes

14b78db

Add additional tools doxygen

109ae8c

Committing clang-format changes

882e84f

Add more tools doxygen files

8a76c1d

Committing clang-format changes

0cd0f09

Correct unterminated alias lines

479c749

byrnHDF self-assigned this Jun 24, 2024

byrnHDF requested review from lrknox, derobins, fortnern, jhendersonHDF, qkoziol, vchoi-hdfgroup, bmribler, glennsong09, mattjala and brtnfld as code owners June 24, 2024 18:54

byrnHDF mentioned this pull request Jun 24, 2024

Add tools to doxygen #2875

Open

bmribler requested changes Jun 24, 2024

View reviewed changes

byrnHDF and others added 2 commits June 24, 2024 17:39

Correct formatting add h5dump

e5253a5

Committing clang-format changes

373d932

byrnHDF mentioned this pull request Jun 25, 2024

H5TOOLS_BUFSIZE documentation error #1761

Closed

byrnHDF and others added 8 commits June 25, 2024 10:50

Cleanup text

5c09f39

Fix typo

1c2e5d4

Cleanup text in the tools doxygen code. Add release note.

7aa818e

Committing clang-format changes

c0a73d3

Fix some doxygen display issues

655d269

Committing clang-format changes

a68e83f

Fix formatting

2654e65

Use long form options in examples

cbbb59b

lrknox reviewed Jun 26, 2024

View reviewed changes

byrnHDF and others added 4 commits June 27, 2024 07:47

Fix sentence typo and sentences

c57d0c3

Add enhanced text explanation

76cf281

Update some explanations for better grammer.

7768d81

Committing clang-format changes

0a6a802

bmribler approved these changes Jul 2, 2024

View reviewed changes

lrknox reviewed Jul 9, 2024

View reviewed changes

byrnHDF and others added 2 commits July 9, 2024 16:44

Fix typos

7402112

Committing clang-format changes

6d21699

lrknox approved these changes Jul 11, 2024

View reviewed changes

byrnHDF added 2 commits July 11, 2024 15:37

Fix option references

01c8644

Merge branch 'develop' of https://github.com/HDFGroup/hdf5.git into d…

d93eac2

…evelop-tools-doxy

lrknox merged commit f8069fa into HDFGroup:develop Jul 15, 2024
59 checks passed

qkoziol pushed a commit to qkoziol/hdf5 that referenced this pull request Jul 15, 2024

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

19eb43d

qkoziol pushed a commit to qkoziol/hdf5 that referenced this pull request Jul 16, 2024

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

d28ba95

byrnHDF deleted the develop-tools-doxy branch July 19, 2024 15:21

lrknox pushed a commit to lrknox/hdf5 that referenced this pull request Jul 19, 2024

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

21ffd80

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add tools usage text as doxygen for Tools UG #4602

Add tools usage text as doxygen for Tools UG #4602

byrnHDF commented Jun 24, 2024

byrnHDF commented Jun 24, 2024

bmribler left a comment

byrnHDF commented Jun 24, 2024

lrknox Jun 26, 2024

lrknox Jun 26, 2024

lrknox Jun 26, 2024

lrknox Jun 26, 2024

lrknox Jun 26, 2024

lrknox Jun 26, 2024

lrknox Jun 26, 2024

lrknox Jun 26, 2024

lrknox Jul 9, 2024

lrknox Jul 9, 2024

lrknox Jul 9, 2024

lrknox Jul 9, 2024

lrknox Jul 9, 2024

lrknox Jul 9, 2024

lrknox Jul 9, 2024

lrknox Jul 9, 2024

lrknox Jul 9, 2024

lrknox Jul 9, 2024

lrknox Jul 11, 2024

byrnHDF Jul 11, 2024

lrknox Jul 11, 2024

byrnHDF Jul 11, 2024

	* compound data type. "," is the separatorfor field names while "." is the separator
	* compound data type. "," is the separator for field names while "." is the separator

Add tools usage text as doxygen for Tools UG #4602

Add tools usage text as doxygen for Tools UG #4602

Conversation

byrnHDF commented Jun 24, 2024

byrnHDF commented Jun 24, 2024

bmribler left a comment

Choose a reason for hiding this comment

byrnHDF commented Jun 24, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment