doc typos and minor mistakes in libhdf5 and libhdf4

[edhartnett]

Doxygen documentation fixes in libhdf4 and libhdf5

Summary

A review of the Doxygen documentation in the libhdf4 and libhdf5 directories found numerous typos, copy-paste errors, incorrect @param names, missing @param entries, duplicate @file blocks, and inconsistent formatting across 14 source files. All fixes are documentation/comment-only changes.

A separate potential bug was also identified (h5->cmode & NC_INDEF vs h5->flags & NC_INDEF in hdf5type.c:add_user_type) but is not included in this fix and should be addressed separately.

Issues Found and Fixed

1. Typo: "endniannessp" → "endiannessp" (libhdf4/hdf4file.c)

The @param name for the endianness output pointer in hdf4_type_info() was misspelled.

2. Misleading "HDF5 file info struct" in HDF4 code (libhdf4/hdf4file.c)

Four functions in the HDF4 layer documented the h5 parameter as "Pointer to HDF5 file info struct" even though these are HDF4 functions. Changed to "Pointer to file info struct" in:

• hdf4_type_info()
• hdf4_read_att()
• hdf4_read_dim()
• hdf4_read_var()

3. Typo: "insert int" → "insert into" (libhdf4/hdf4file.c)

In the nc4_var_list_add_full() doc: "Create a new variable and insert int relevant lists" → "insert into relevant lists."

4. Missing @param entries for nc4_var_list_add_full (libhdf4/hdf4file.c)

The function has 12 parameters but only 5 were documented. Added the 7 missing entries: xtype, endianness, type_size, type_name, fill_value, contiguous, chunksizes.

5. Typo: "Propate" → "Propagate" (libhdf4/hdf4file.c)

Code comment in nc4_var_list_add_full().

6. Wrong @param name: nc_file → ncid (libhdf4/hdf4file.c)

NC_HDF4_open() documented @param nc_file but the actual parameter is int ncid. Also added "Ignored by this function" note to the dispatch parameter.

7. Missing @internal tag (libhdf4/hdf4var.c)

NC_HDF4_get_vara() was the only function in libhdf4 missing the @internal tag.

8. Typo: "NC_BLOGAL" → "NC_GLOBAL" (libhdf5/hdf5attr.c)

In getattlist(): @param varid Variable ID | NC_BLOGAL → NC_GLOBAL.

9. Vague/joke description on NC4_HDF5_rename_att (libhdf5/hdf5attr.c)

The description read: "I think all atts should be named the exact same thing, to avoid confusion!" Replaced with: "Rename an attribute in a netCDF-4/HDF5 file."

10. Typo: "exetnal" → "external" (libhdf5/hdf5filter.c, libhdf5/hdf5internal.c)

Appeared in file-level @file doc blocks in both files (3 occurrences total).

11. Duplicate @file blocks (libhdf5/hdf5filter.c, libhdf5/hdf5plugins.c)

Both files had two @file Doxygen blocks. Doxygen uses only one and ignores the other. Removed the duplicate in each file, replacing with a plain comment.

12. Duplicate @author with spurious colon (libhdf5/hdf5plugins.c)

NC4_hdf5_plugin_path_get() had two @author tags, and the second one had a colon (@author: Dennis Heimbigner). Removed the duplicate.

13. "header file" → "file" (libhdf5/hdf5dispatch.c)

The file-level doc said "This header file contains prototypes and initialization" but hdf5dispatch.c is a .c source file, not a header.

14. Typo: "pronted" → "printed" (libhdf5/hdf5internal.c)

In the set_auto() doc block.

15. Typo: "H5eset_auto2" → "H5Eset_auto2" (libhdf5/hdf5internal.c)

Wrong capitalization of the HDF5 function name in the set_auto() doc block.

16. Duplicate @param h5 → @param var (libhdf5/hdf5internal.c)

In nc4_hdf5_find_grp_var_att(), the var parameter was documented as @param h5 (copy-paste from the previous parameter). Fixed to @param var.

17. Typo: "depend mode" → "define mode" (libhdf5/hdf5file.c)

Comment in sync_netcdf4_file(): "End depend mode if needed" → "End define mode if needed."

18. Typo: "unlimied" → "unlimited" (libhdf5/hdf5file.c)

In NC4_inq() doc: "no unlimied dimensions" → "no unlimited dimensions."

19. Typo: "name of lenp" → "name or lenp" (libhdf5/hdf5dim.c)

In HDF5_inq_dim() doc: "the name of lenp pointers are NULL" → "the name or lenp pointers are NULL."

20. Typo: "stict" → "strict" (libhdf5/hdf5dim.c)

Code comment: "Must be in define mode for stict nc3" → "strict nc3."

21. Copy-paste errors: "vlen type" in opaque/enum docs (libhdf5/hdf5type.c)

• NC4_def_opaque(): @param name Name of new vlen type → "Name of new opaque type."
• NC4_def_enum(): @param base_typeid Base type of vlen → "Base type of enum." and @param name Name of new vlen type → "Name of new enum type."

22. Copy-pasted doc on NC4_get_vlen_element (libhdf5/hdf5type.c)

The doc block was identical to NC4_put_vlen_element() ("Insert one element into..."). Changed to "Read one element from..." and fixed @param descriptions to reflect output semantics (len is a pointer that gets the length, data is a pointer that gets the data).

23. Typo: "Nemonic" → "Mnemonic" (libhdf5/hdf5open.c)

Comment above #define FILTERACTIVE.

24. Typo: "sepecific" → "specific" (libhdf5/hdf5open.c)

Appeared in two places: read_coord_dimids() and get_filter_info().

25. Typo: "mac len" → "max len" (libhdf5/hdf5open.c)

Comment in create_phony_dims(): "Get ndims, also len and mac len of all dims" → "max len."

26. Misleading log message (libhdf5/nc4info.c)

In NC4_read_provenance(), the error log said "Could not create _NCProperties attribute" but this is a read function. Changed to "Could not read _NCProperties attribute."

27. Inconsistent @file @internal formatting (multiple files)

Seven files had @file @internal on a single line. Split to separate lines for consistency with the rest of the codebase:

• libhdf4/hdf4func.c
• libhdf4/hdf4var.c
• libhdf5/hdf5dim.c
• libhdf5/hdf5grp.c
• libhdf5/hdf5internal.c
• libhdf5/hdf5plugins.c
• libhdf5/hdf5type.c

Potential Bug (Not Fixed Here)

In libhdf5/hdf5type.c, add_user_type() checks h5->cmode & NC_INDEF to determine if the file is in define mode. Other functions throughout the codebase use h5->flags & NC_INDEF for this purpose. The cmode field stores the creation mode, while flags tracks the current state. This should be investigated and fixed separately.

Files Modified

File	Changes
libhdf4/hdf4file.c	Typos (3), misleading param docs (4 functions), missing params (7), wrong param name (1)
libhdf4/hdf4func.c	@file @internal formatting
libhdf4/hdf4var.c	@file @internal formatting, missing @internal tag
libhdf5/hdf5attr.c	"NC_BLOGAL" typo, vague function description
libhdf5/hdf5dim.c	@file @internal formatting, typos (2)
libhdf5/hdf5dispatch.c	"header file" → "file"
libhdf5/hdf5file.c	Typos (2)
libhdf5/hdf5filter.c	"exetnal" typo, duplicate @file block, "collevtive" typo
libhdf5/hdf5grp.c	@file @internal formatting
libhdf5/hdf5internal.c	"exetnal" typo, "pronted" typo, "H5eset_auto2" typo, duplicate @param h5, @file @internal formatting
libhdf5/hdf5open.c	"Nemonic" typo, "sepecific" typo (2), "mac len" typo
libhdf5/hdf5plugins.c	@file @internal formatting, duplicate @file block, duplicate @author
libhdf5/hdf5type.c	@file @internal formatting, copy-paste "vlen" errors (3), copy-pasted get/put doc
libhdf5/nc4info.c	Misleading "create" → "read" log message