added nc4cache.c to list of doxygen input files, fixed many doxygen warnings

docs/Doxyfile.in

@@ -789,6 +789,7 @@ INPUT = \
     @abs_top_srcdir@/libsrc4/ncfunc.c \
     @abs_top_srcdir@/libsrc4/nc4dim.c \
     @abs_top_srcdir@/libsrc4/nc4attr.c \
+    @abs_top_srcdir@/libsrc4/nc4cache.c \
     @abs_top_srcdir@/libhdf5/nc4info.c \
     @abs_top_srcdir@/libsrc4/nc4dispatch.c \
     @abs_top_srcdir@/libnczarr/zarr.c \

docs/notes.md

@@ -107,3 +107,44 @@ that is returned by nc_open() and nc_create().)
 For netCDF-4/HDF5 files, netCDF IDs can come not just from nc_open()
 and nc_create(), but also from nc_def_grp(), nc_inq_grps(),
 nc_inq_ncid(), nc_inq_grp_parent(), and nc_inq_grp_full_ncid().
+
+# NetCDF Names {#object_name}
+
+## Permitted Characters in NetCDF Names
+
+The names of dimensions, variables and attributes (and, in netCDF-4
+files, groups, user-defined types, compound member names, and
+enumeration symbols) consist of arbitrary sequences of alphanumeric
+characters, underscore '_', period '.', plus '+', hyphen '-', or at
+sign '@', but beginning with an alphanumeric character or
+underscore. However names commencing with underscore are reserved for
+system use.
+
+Beginning with versions 3.6.3 and 4.0, names may also include UTF-8
+encoded Unicode characters as well as other special characters, except
+for the character '/', which may not appear in a name.
+
+Names that have trailing space characters are also not permitted.
+
+Case is significant in netCDF names.
+
+## Name Length
+
+A zero-length name is not allowed.
+
+Names longer than ::NC_MAX_NAME will not be accepted any netCDF define
+function. An error of ::NC_EMAXNAME will be returned.
+
+All netCDF inquiry functions will return names of maximum size
+::NC_MAX_NAME for netCDF files. Since this does not include the
+terminating NULL, space should be reserved for ::NC_MAX_NAME + 1
+characters.
+
+## NetCDF Conventions
+
+Some widely used conventions restrict names to only alphanumeric
+characters or underscores.
+
+Note that, when using the DAP2 protocol to access netCDF data, there
+are reserved keywords, the use of which may result in undefined
+behavior. See DAP2 Reserved Keywords for more information.

include/netcdf.h

@@ -334,21 +334,27 @@ there. */
 #define NC_QUANTIZE_GRANULARBR 2 /**< Use Granular BitRound quantization. */
 #define NC_QUANTIZE_BITROUND 3 /**< Use BitRound quantization. */
 
+/**@{*/
 /** When quantization is used for a variable, an attribute of the
  * appropriate name is added. */
 #define NC_QUANTIZE_BITGROOM_ATT_NAME "_QuantizeBitGroomNumberOfSignificantDigits"
 #define NC_QUANTIZE_GRANULARBR_ATT_NAME "_QuantizeGranularBitRoundNumberOfSignificantDigits"
 #define NC_QUANTIZE_BITROUND_ATT_NAME "_QuantizeBitRoundNumberOfSignificantBits"
+/**@}*/
 
+/**@{*/
 /** For quantization, the allowed value of number of significant
  * decimal and binary digits, respectively, for float. */
 #define NC_QUANTIZE_MAX_FLOAT_NSD (7)
 #define NC_QUANTIZE_MAX_FLOAT_NSB (23)
+/**@}*/
 
+/**@{*/
 /** For quantization, the allowed value of number of significant
  * decimal and binary digits, respectively, for double. */
 #define NC_QUANTIZE_MAX_DOUBLE_NSD (15)
 #define NC_QUANTIZE_MAX_DOUBLE_NSB (52)
+/**@}*/
 
 /** The netcdf version 3 functions all return integer error status.
  * These are the possible values, in addition to certain values from

libdispatch/dvar.c

@@ -148,7 +148,9 @@
    nc_create(), nc_def_grp(), or associated inquiry functions such as
    nc_inq_ncid().
    @param name Variable @ref object_name.
-   @param xtype @ref data_type of the variable.
+   @param xtype (Data
+   type)[https://docs.unidata.ucar.edu/nug/current/md_types.html#data_type]
+   of the variable.
    @param ndims Number of dimensions for the variable. For example, 2
    specifies a matrix, 1 specifies a vector, and 0 means the variable is
    a scalar with no dimensions. Must not be negative or greater than the
@@ -488,7 +490,7 @@ nc_def_var_deflate(int ncid, int varid, int shuffle, int deflate, int deflate_le
    types return an error (NC_EINVAL). 
 
    Variables that use quantize will have added an attribute with name
-   ::NC_QUANTIZE_[ALGORITHM_NAME]_ATT_NAME, which will contain the 
+   NC_QUANTIZE_[ALGORITHM_NAME]_ATT_NAME, which will contain the 
    number of significant digits. Users should not delete or change this
    attribute. This is the only record that quantize has been applied
    to the data.
@@ -640,7 +642,7 @@ nc_def_var_fletcher32(int ncid, int varid, int fletcher32)
 
    @note Scalar variables may have a storage of NC_CONTIGUOUS or
    NC_COMPACT. Attempts to set chunking on a scalare variable will
-   cause ::NC_EINVEL to be returned. Only non-scalar variables can
+   cause ::NC_EINVAL to be returned. Only non-scalar variables can
    have chunking.
 
    @param ncid NetCDF ID, from a previous call to nc_open() or