Merge pull request #3268 from edhartnett/ejh_more_docs

fix docs in libhdf4, libhdf5, and libsrcp

Author: WardF

libdispatch/dvar.c

@@ -4,6 +4,8 @@
  * @file
  * Functions for defining and inquiring about variables. @note The
  * order of functions in this file affects the doxygen documentation.
+ *
+ * @author Dennis Heimbigner, Edward Hartnett
  */
 
 #include "config.h"
@@ -739,7 +741,7 @@ nc_def_var_chunking(int ncid, int varid, int storage, const size_t *chunksizesp)
 /**
    Define endianness of a variable.
 
-   With this function the endianness (i.e. order of bits in integers) can
+   With this function the endianness (i.e. order of bytes in integers) can
    be changed on a per-variable basis. By default, the endianness is the
    same as the default endianness of the platform. But with
    nc_def_var_endianness the endianness can be explicitly set for a

libhdf4/hdf4file.c

@@ -82,10 +82,10 @@ hdf4_rec_grp_del(NC_GRP_INFO_T *grp)
  * See http://www.hdfgroup.org/training/HDFtraining/UsersGuide/Fundmtls.fm3.html
  * for more information re: HDF4 types.
  *
- * @param h5 Pointer to HDF5 file info struct.
+ * @param h5 Pointer to file info struct.
  * @param hdf4_typeid Type ID for hdf4 datatype.
  * @param xtype Pointer that gets netcdf type. Ignored if NULL.
- * @param endniannessp Pointer that gets endianness. Ignored if NULL.
+ * @param endiannessp Pointer that gets endianness. Ignored if NULL.
  * @param type_sizep Pointer that gets type size. Ignored if NULL.
  * @param type_name Pointer that gets the type name. Ignored if NULL.
  *
@@ -251,9 +251,9 @@ nc4_set_var_type(nc_type xtype, int endianness, size_t type_size, char *type_nam
 }
 
 /**
- * @internal Read an attribute from a HDF4 file.
+ * @internal Read an attribute from an HDF4 file.
  *
- * @param h5 Pointer to the file metadata struct.
+ * @param h5 Pointer to the file info struct.
  * @param var Pointer to variable metadata struct or NULL for global
  * attributes.
  * @param a Index of attribute to read.
@@ -327,12 +327,11 @@ hdf4_read_att(NC_FILE_INFO_T *h5, NC_VAR_INFO_T *var, int a)
 }
 
 /**
- * @internal Read a HDF4 dimension. As new dimensions are found, add
+ * @internal Read an HDF4 dimension. As new dimensions are found, add
  * them to the metadata list of dimensions.
  *
- * @param h5 Pointer to the file metadata struct.
- * @param var Pointer to variable metadata struct or NULL for global
- * attributes.
+ * @param h5 Pointer to the file info struct.
+ * @param var Pointer to variable metadata struct.
  * @param rec_dim_len Actual length of first dim for this SD.
  * @param d Dimension index for this SD.
  *
@@ -391,11 +390,18 @@ hdf4_read_dim(NC_FILE_INFO_T *h5, NC_VAR_INFO_T *var, int rec_dim_len, int d)
 }
 
 /**
- * @internal Create a new variable and insert int relevant lists
+ * @internal Create a new variable and insert into relevant lists.
  *
- * @param grp the containing group
- * @param name the name for the new variable
- * @param ndims the rank of the new variable
+ * @param grp The containing group.
+ * @param name The name for the new variable.
+ * @param ndims The rank of the new variable.
+ * @param xtype The netCDF type of the variable.
+ * @param endianness The endianness of the data.
+ * @param type_size The size in bytes of one element of this type.
+ * @param type_name A name for the type.
+ * @param fill_value Pointer to fill value, or NULL.
+ * @param contiguous Non-zero for contiguous storage, zero for chunked.
+ * @param chunksizes Array of chunk sizes, or NULL.
  * @param format_var_info Pointer to format-specific var info struct.
  * @param var Pointer in which to return a pointer to the new var.
  *
@@ -424,7 +430,7 @@ nc4_var_list_add_full(NC_GRP_INFO_T* grp, const char* name, int ndims, nc_type x
     if ((retval = nc4_set_var_type(xtype, endianness, type_size, type_name,
                                    &(*var)->type_info)))
         return retval;
-    /* Propate the endianness to the variable */
+    /* Propagate the endianness to the variable */
     (*var)->endianness = (*var)->type_info->endianness;
 
     (*var)->type_info->rc++;
@@ -456,10 +462,10 @@ nc4_var_list_add_full(NC_GRP_INFO_T* grp, const char* name, int ndims, nc_type x
 }
 
 /**
- * @internal Read a HDF4 variable, including its associated dimensions
+ * @internal Read an HDF4 variable, including its associated dimensions
  * and attributes.
  *
- * @param h5 Pointer to the file metadata struct.
+ * @param h5 Pointer to the file info struct.
  * @param v Index of variable to read.
  *
  * @return ::NC_NOERR No error.
@@ -594,8 +600,8 @@ hdf4_read_var(NC_FILE_INFO_T *h5, int v)
  * @param parameters pointer to struct holding extra data (e.g. for
  * parallel I/O) layer. Ignored if NULL. Ignored by this function.
  * @param dispatch Pointer to the dispatch table for this file.
- * @param nc_file Pointer to an instance of NC. The ncid has already
- * been assigned, and is in nc_file->ext_ncid.
+ * Ignored by this function.
+ * @param ncid The already-assigned ncid for this file.
  *
  * @return ::NC_NOERR No error.
  * @return ::NC_EINVAL Invalid input.

libhdf4/hdf4func.c

@@ -1,7 +1,8 @@
 /* Copyright 2018, UCAR/Unidata See netcdf/COPYRIGHT file for copying
  * and redistribution conditions.*/
 /**
- * @file @internal HDF4 functions.
+ * @file
+ * @internal HDF4 functions.
  *
  * @author Ed Hartnett
  */

libhdf4/hdf4var.c

@@ -1,7 +1,8 @@
 /* Copyright 2018, UCAR/Unidata See netcdf/COPYRIGHT file for copying
  * and redistribution conditions.*/
 /**
- * @file @internal This file handles the variable functions for the
+ * @file
+ * @internal This file handles the variable functions for the
  * HDF4 dispatch layer.
  *
  * @author Ed Hartnett
@@ -14,8 +15,8 @@
 #include <mfhdf.h>
 
 /**
- * Read an array of values. This is called by nc_get_vara() for
- * netCDF-4 files, as well as all the other nc_get_vara_*
+ * @internal Read an array of values. This is called by nc_get_vara()
+ * for netCDF-4 files, as well as all the other nc_get_vara_*
  * functions. HDF4 files are handled as a special case.
  *
  * @param ncid File ID.

libhdf5/hdf5attr.c

@@ -15,7 +15,7 @@
  * @internal Get the attribute list for either a varid or NC_GLOBAL
  *
  * @param grp Group
- * @param varid Variable ID | NC_BLOGAL
+ * @param varid Variable ID | NC_GLOBAL
  * @param varp Pointer that gets pointer to NC_VAR_INFO_T
  * instance. Ignored if NULL.
  * @param attlist Pointer that gets pointer to attribute list.
@@ -129,8 +129,7 @@ nc4_get_att_special(NC_FILE_INFO_T* h5, const char* name,
 }
 
 /**
- * @internal I think all atts should be named the exact same thing, to
- * avoid confusion!
+ * @internal Rename an attribute in a netCDF-4/HDF5 file.
  *
  * @param ncid File and group ID.
  * @param varid Variable ID.

libhdf5/hdf5dim.c

@@ -2,9 +2,10 @@
  * Research. See the COPYRIGHT file for copying and redistribution
  * conditions. */
 /**
- * @file @internal This file is part of netcdf-4, a netCDF-like
- * interface for HDF5, or a HDF5 backend for netCDF, depending on your
- * point of view.
+ * @file
+ * @internal This file is part of netcdf-4, a netCDF-like interface
+ * for HDF5, or a HDF5 backend for netCDF, depending on your point of
+ * view.
  *
  * This file includes the HDF5 code to deal with dimensions.
  *
@@ -71,7 +72,7 @@ HDF5_def_dim(int ncid, const char *name, size_t len, int *idp)
                     return NC_EUNLIMIT;
             }
         }
-        /* Must be in define mode for stict nc3. */
+        /* Must be in define mode for strict nc3. */
         if (!(h5->flags & NC_INDEF))
             return NC_ENOTINDEFINE;
     }
@@ -117,7 +118,7 @@ HDF5_def_dim(int ncid, const char *name, size_t len, int *idp)
 /**
  * @internal Find out name and len of a dim. For an unlimited
  * dimension, the length is the largest length so far written. If the
- * name of lenp pointers are NULL, they will be ignored.
+ * name or lenp pointers are NULL, they will be ignored.
  *
  * @param ncid File and group ID.
  * @param dimid Dimension ID.

libhdf5/hdf5dispatch.c

@@ -2,8 +2,8 @@
    Research/Unidata. */
 /**
  * @file
- * @internal This header file contains prototypes and initialization
- * for the HDF5 dispatch layer.
+ * @internal This file contains the initialization for the HDF5
+ * dispatch layer.
  *
  * @author Ed Hartnett, Dennis Heimbigner
  */

libhdf5/hdf5file.c

@@ -128,7 +128,7 @@ sync_netcdf4_file(NC_FILE_INFO_T *h5)
     assert(h5 && h5->format_file_info);
     LOG((3, "%s", __func__));
 
-    /* End depend mode if needed. (Error checking for classic mode has
+    /* End define mode if needed. (Error checking for classic mode has
      * already happened). */
     if (h5->flags & NC_INDEF)
     {
@@ -644,7 +644,7 @@ NC4_close(int ncid, void* params)
  * @param nvarsp Pointer that gets number of variables.
  * @param nattsp Pointer that gets number of global attributes.
  * @param unlimdimidp Pointer that gets first unlimited dimension ID,
- * or -1 if there are no unlimied dimensions.
+ * or -1 if there are no unlimited dimensions.
  *
  * @return ::NC_NOERR No error.
  * @author Ed Hartnett

libhdf5/hdf5filter.c

@@ -3,10 +3,11 @@
  * conditions.
  */
 /**
- * @file @internal Internal netcdf-4 functions for filters
+ * @file
+ * @internal Internal netcdf-4 functions for filters.
  *
  * This file contains functions internal to the netcdf4 library. None of
- * the functions in this file are exposed in the exetnal API. These
+ * the functions in this file are exposed in the external API. These
  * functions all relate to the manipulation of netcdf-4 filters
  *
  * @author Dennis Heimbigner
@@ -30,17 +31,7 @@
 static int NC4_hdf5_filter_free(struct NC_HDF5_Filter* spec);
 
 /**************************************************/
-/**
- * @file
- * @internal
- * Internal netcdf hdf5 filter functions.
- *
- * This file contains functions internal to the libhdf5 library.
- * None of the functions in this file are exposed in the exetnal API. These
- * functions all relate to the manipulation of netcdf-4's var->filters list.
- *
- * @author Dennis Heimbigner
- */
+/* Internal netcdf hdf5 filter functions for the var->filters list. */
 #ifdef TFILTERS
 static void
 printfilter1(struct NC_HDF5_Filter* nfs)
@@ -402,7 +393,7 @@ NC4_hdf5_def_var_filter(int ncid, int varid, unsigned int id, size_t nparams,
                 goto done;
 #ifdef USE_PARALLEL
 #ifdef HDF5_SUPPORTS_PAR_FILTERS
-        /* Switch to collective access. HDF5 requires collevtive access
+        /* Switch to collective access. HDF5 requires collective access
          * for filter use with parallel I/O. */
         if (h5->parallel)
             var->parallel_access = NC_COLLECTIVE;

libhdf5/hdf5grp.c

@@ -2,9 +2,10 @@
  * Research. See COPYRIGHT file for copying and redistribution
  * conditions. */
 /**
- * @file @internal This file is part of netcdf-4, a netCDF-like
- * interface for HDF5, or a HDF5 backend for netCDF, depending on your
- * point of view.
+ * @file
+ * @internal This file is part of netcdf-4, a netCDF-like interface
+ * for HDF5, or a HDF5 backend for netCDF, depending on your point of
+ * view.
  *
  * This file handles HDF5 groups.
  *