Merge pull request ESMCI#1611 from NCAR/ejh_dos

fixed some documentation warnings
jedwards4b · Nov 12, 2019 · 8c3ab43 · 8c3ab43
2 parents 824f576 + 1376df1
commit 8c3ab43
Showing 1 changed file with 118 additions and 122 deletions.
diff --git a/src/clib/pio.h b/src/clib/pio.h
@@ -632,141 +632,137 @@ enum PIO_ERROR_HANDLERS
     PIO_RETURN_ERROR = (-53)
 };
 
+/** Attribute id to put/get a global attribute. */
 #define PIO_GLOBAL NC_GLOBAL
+
+/** Size argument to nc_def_dim() for an unlimited dimension. */
 #define PIO_UNLIMITED NC_UNLIMITED
 
 /* NetCDF types. */
-#define PIO_BYTE   NC_BYTE
-#define PIO_CHAR   NC_CHAR
-#define PIO_SHORT  NC_SHORT
-#define PIO_INT    NC_INT
-#define PIO_FLOAT  NC_FLOAT
-#define PIO_REAL   NC_FLOAT
-#define PIO_DOUBLE NC_DOUBLE
-#define PIO_UBYTE  NC_UBYTE
-#define PIO_USHORT NC_USHORT
-#define PIO_UINT   NC_UINT
-#define PIO_INT64  NC_INT64
-#define PIO_UINT64 NC_UINT64
-#define PIO_STRING NC_STRING
+#define PIO_BYTE   NC_BYTE       /**< signed 1 byte integer */
+#define PIO_CHAR   NC_CHAR       /**< ISO/ASCII character */
+#define PIO_SHORT  NC_SHORT      /**< signed 2 byte integer */
+#define PIO_INT    NC_INT        /**< signed 4 byte integer */
+#define PIO_FLOAT  NC_FLOAT      /**< single precision floating point number */
+#define PIO_REAL   NC_FLOAT      /**< single precision floating point number */
+#define PIO_DOUBLE NC_DOUBLE     /**< double precision floating point number */
+#define PIO_UBYTE  NC_UBYTE      /**< unsigned 1 byte int */
+#define PIO_USHORT NC_USHORT     /**< unsigned 2-byte int */
+#define PIO_UINT   NC_UINT       /**< unsigned 4-byte int */
+#define PIO_INT64  NC_INT64      /**< signed 8-byte int */
+#define PIO_UINT64 NC_UINT64     /**< unsigned 8-byte int */
+#define PIO_STRING NC_STRING     /**< string */
 
 /* NetCDF flags. */
-#define PIO_WRITE  NC_WRITE
-#define PIO_NOWRITE  NC_NOWRITE
-#define PIO_CLOBBER NC_CLOBBER
-#define PIO_NOCLOBBER NC_NOCLOBBER
-#define PIO_FILL NC_FILL
-#define PIO_NOFILL NC_NOFILL
-#define PIO_MAX_NAME NC_MAX_NAME
-#define PIO_MAX_VAR_DIMS NC_MAX_VAR_DIMS
-#define PIO_64BIT_OFFSET NC_64BIT_OFFSET
+#define PIO_WRITE  NC_WRITE      /**< Set read-write access for nc_open(). */
+#define PIO_NOWRITE  NC_NOWRITE  /**< Set read-only access for nc_open(). */
+#define PIO_CLOBBER NC_CLOBBER   /**< Destroy existing file. Mode flag for nc_create(). */
+#define PIO_NOCLOBBER NC_NOCLOBBER  /**< Don't destroy existing file. Mode flag for nc_create(). */
+#define PIO_FILL NC_FILL         /**< Argument to nc_set_fill() to clear NC_NOFILL */
+#define PIO_NOFILL NC_NOFILL     /**< Argument to nc_set_fill() to turn off filling of data. */
+#define PIO_MAX_NAME NC_MAX_NAME /**< Max name length. */
+#define PIO_MAX_VAR_DIMS NC_MAX_VAR_DIMS /**< max per variable dimensions */
+#define PIO_64BIT_OFFSET NC_64BIT_OFFSET /**< Use large (64-bit) file offsets. Mode flag for nc_create(). */
 
 /** NC_64BIT_DATA This is a problem - need to define directly instead
  * of using include file. */
-#define PIO_64BIT_DATA 0x0010
+#define PIO_64BIT_DATA 0x0010 /**< CDF5 foemat. */
 
 /** Define the netCDF-based error codes. */
-#define PIO_NOERR  NC_NOERR
-#define PIO_EBADID NC_EBADID
-#define PIO_ENFILE NC_ENFILE
-#define PIO_EEXIST NC_EEXIST
-#define PIO_EINVAL NC_EINVAL
-#define PIO_EPERM NC_EPERM
-#define PIO_ENOTINDEFINE NC_ENOTINDEFINE
-#define PIO_EINDEFINE NC_EINDEFINE
-#define PIO_EINVALCOORDS NC_EINVALCOORDS
-#define PIO_EMAXDIMS NC_EMAXDIMS
-#define PIO_ENAMEINUSE NC_ENAMEINUSE
-#define PIO_ENOTATT NC_ENOTATT
-#define PIO_EMAXATTS NC_EMAXATTS
-#define PIO_EBADTYPE NC_EBADTYPE
-#define PIO_EBADDIM NC_EBADDIM
-#define PIO_EUNLIMPOS NC_EUNLIMPOS
-#define PIO_EMAXVARS NC_EMAXVARS
-#define PIO_ENOTVAR NC_ENOTVAR
-#define PIO_EGLOBAL NC_EGLOBAL
-#define PIO_ENOTNC NC_ENOTNC
-#define PIO_ESTS NC_ESTS
-#define PIO_EMAXNAME NC_EMAXNAME
-#define PIO_EUNLIMIT NC_EUNLIMIT
-#define PIO_ENORECVARS NC_ENORECVARS
-#define PIO_ECHAR NC_ECHAR
-#define PIO_EEDGE NC_EEDGE
-#define PIO_ESTRIDE NC_ESTRIDE
-#define PIO_EBADNAME NC_EBADNAME
-#define PIO_ERANGE NC_ERANGE
-#define PIO_ENOMEM NC_ENOMEM
-#define PIO_EVARSIZE NC_EVARSIZE
-#define PIO_EDIMSIZE NC_EDIMSIZE
-#define PIO_ETRUNC NC_ETRUNC
-#define PIO_EAXISTYPE NC_EAXISTYPE
-#define PIO_EDAP NC_EDAP
-#define PIO_ECURL NC_ECURL
-#define PIO_EIO NC_EIO
-#define PIO_ENODATA NC_ENODATA
-#define PIO_EDAPSVC NC_EDAPSVC
-#define PIO_EDAS NC_EDAS
-#define PIO_EDDS NC_EDDS
-#define PIO_EDATADDS NC_EDATADDS
-#define PIO_EDAPURL NC_EDAPURL
-#define PIO_EDAPCONSTRAINT NC_EDAPCONSTRAINT
-#define PIO_ETRANSLATION NC_ETRANSLATION
-#define PIO_EHDFERR NC_EHDFERR
-#define PIO_ECANTREAD NC_ECANTREAD
-#define PIO_ECANTWRITE NC_ECANTWRITE
-#define PIO_ECANTCREATE NC_ECANTCREATE
-#define PIO_EFILEMETA NC_EFILEMETA
-#define PIO_EDIMMETA NC_EDIMMETA
-#define PIO_EATTMETA NC_EATTMETA
-#define PIO_EVARMETA NC_EVARMETA
-#define PIO_ENOCOMPOUND NC_ENOCOMPOUND
-#define PIO_EATTEXISTS NC_EATTEXISTS
-#define PIO_ENOTNC4 NC_ENOTNC4
-#define PIO_ESTRICTNC3 NC_ESTRICTNC3
-#define PIO_ENOTNC3 NC_ENOTNC3
-#define PIO_ENOPAR NC_ENOPAR
-#define PIO_EPARINIT NC_EPARINIT
-#define PIO_EBADGRPID NC_EBADGRPID
-#define PIO_EBADTYPID NC_EBADTYPID
-#define PIO_ETYPDEFINED NC_ETYPDEFINED
-#define PIO_EBADFIELD NC_EBADFIELD
-#define PIO_EBADCLASS NC_EBADCLASS
-#define PIO_EMAPTYPE NC_EMAPTYPE
-#define PIO_ELATEFILL NC_ELATEFILL
-#define PIO_ELATEDEF NC_ELATEDEF
-#define PIO_EDIMSCALE NC_EDIMSCALE
-#define PIO_ENOGRP NC_ENOGRP
-#define PIO_ESTORAGE NC_ESTORAGE
-#define PIO_EBADCHUNK NC_EBADCHUNK
-#define PIO_ENOTBUILT NC_ENOTBUILT
-#define PIO_EDISKLESS NC_EDISKLESS
+#define PIO_NOERR  NC_NOERR           /**< No Error */
+#define PIO_EBADID NC_EBADID          /**< Bad ncid */
+#define PIO_ENFILE NC_ENFILE          /**< Too many netcdfs open */
+#define PIO_EEXIST NC_EEXIST          /**< netcdf file exists && NC_NOCLOBBER */
+#define PIO_EINVAL NC_EINVAL          /**< Invalid Argument */
+#define PIO_EPERM NC_EPERM            /**< Write to read only */
+#define PIO_ENOTINDEFINE NC_ENOTINDEFINE /**< Not in define mode */
+#define PIO_EINDEFINE NC_EINDEFINE    /**< Not allowed in define mode */
+#define PIO_EINVALCOORDS NC_EINVALCOORDS /**< Invalid coordinates */
+#define PIO_EMAXDIMS NC_EMAXDIMS      /**< not enforced after netcdf-c 4.5.0 */
+#define PIO_ENAMEINUSE NC_ENAMEINUSE  /**< String match to name in use */
+#define PIO_ENOTATT NC_ENOTATT        /**< Attribute not found */
+#define PIO_EMAXATTS NC_EMAXATTS      /**< NC_MAX_ATTRS exceeded - not enforced after 4.5.0 */
+#define PIO_EBADTYPE NC_EBADTYPE      /**< Not a netcdf data type */
+#define PIO_EBADDIM NC_EBADDIM        /**< Invalid dimension id or name */
+#define PIO_EUNLIMPOS NC_EUNLIMPOS    /**< NC_UNLIMITED in the wrong index */
+#define PIO_EMAXVARS NC_EMAXVARS      /**< not enforced after 4.5.0 */
+#define PIO_ENOTVAR NC_ENOTVAR        /**< variable not found */
+#define PIO_EGLOBAL NC_EGLOBAL        /**< Action prohibited on NC_GLOBAL varid */
+#define PIO_ENOTNC NC_ENOTNC          /**< Not a netcdf file */
+#define PIO_ESTS NC_ESTS              /**< In Fortran, string too short */
+#define PIO_EMAXNAME NC_EMAXNAME      /**< NC_MAX_NAME exceeded */
+#define PIO_EUNLIMIT NC_EUNLIMIT      /**< NC_UNLIMITED size already in use */
+#define PIO_ENORECVARS NC_ENORECVARS  /**< nc_rec op when there are no record vars */
+#define PIO_ECHAR NC_ECHAR            /**< Attempt to convert between text & numbers */
+#define PIO_EEDGE NC_EEDGE            /**< Start+count exceeds dimension bound. */
+#define PIO_ESTRIDE NC_ESTRIDE        /**< Illegal stride */
+#define PIO_EBADNAME NC_EBADNAME      /**< Attribute or variable name contains illegal characters */
+#define PIO_ERANGE NC_ERANGE          /**< Range error */
+#define PIO_ENOMEM NC_ENOMEM          /**< Memory allocation (malloc) failure */
+#define PIO_EVARSIZE NC_EVARSIZE      /**< One or more variable sizes violate format constraints */
+#define PIO_EDIMSIZE NC_EDIMSIZE      /**< Invalid dimension size */
+#define PIO_ETRUNC NC_ETRUNC          /**< File likely truncated or possibly corrupted */
+#define PIO_EAXISTYPE NC_EAXISTYPE    /**< Unknown axis type. */
+#define PIO_EDAP NC_EDAP              /**< Generic DAP error */
+#define PIO_ECURL NC_ECURL            /**< Generic libcurl error */
+#define PIO_EIO NC_EIO                /**< Generic IO error */
+#define PIO_ENODATA NC_ENODATA        /**< Attempt to access variable with no data */
+#define PIO_EDAPSVC NC_EDAPSVC        /**< DAP server error */
+#define PIO_EDAS NC_EDAS              /**< Malformed or inaccessible DAS */
+#define PIO_EDDS NC_EDDS              /**< Malformed or inaccessible DDS */
+#define PIO_EDATADDS NC_EDATADDSDS    /**< Dap4 alias */
+#define PIO_EDAPURL NC_EDAPURL        /**< Malformed DAP URL */
+#define PIO_EDAPCONSTRAINT NC_EDAPCONSTRAINT /**< Malformed DAP Constraint*/
+#define PIO_ETRANSLATION NC_ETRANSLATION     /**< Untranslatable construct */
+#define PIO_EHDFERR NC_EHDFERR        /**< Error at HDF5 layer. */
+#define PIO_ECANTREAD NC_ECANTREAD    /**< Can't read. */
+#define PIO_ECANTWRITE NC_ECANTWRITE  /**< Can't write. */
+#define PIO_ECANTCREATE NC_ECANTCREATE /**< Can't create. */
+#define PIO_EFILEMETA NC_EFILEMETA    /**< Problem with file metadata. */
+#define PIO_EDIMMETA NC_EDIMMETA      /**< Problem with dimension metadata. */
+#define PIO_EATTMETA NC_EATTMETA      /**< Problem with attribute metadata. */
+#define PIO_EVARMETA NC_EVARMETA      /**< Problem with variable metadata. */
+#define PIO_ENOCOMPOUND NC_ENOCOMPOUND  /**< Not a compound type. */
+#define PIO_EATTEXISTS NC_EATTEXISTS  /**< Attribute already exists. */
+#define PIO_ENOTNC4 NC_ENOTNC4        /**< Attempting netcdf-4 operation on netcdf-3 file. */
+#define PIO_ESTRICTNC3 NC_ESTRICTNC3  /**< Attempting netcdf-4 operation on strict nc3 netcdf-4 file. */
+#define PIO_ENOTNC3 NC_ENOTNC3        /**< Attempting netcdf-3 operation on netcdf-4 file. */
+#define PIO_ENOPAR NC_ENOPAR          /**< Parallel operation on file opened for non-parallel access. */
+#define PIO_EPARINIT NC_EPARINIT      /**< Error initializing for parallel access. */
+#define PIO_EBADGRPID NC_EBADGRPID    /**< Bad group ID. */
+#define PIO_EBADTYPID NC_EBADTYPID    /**< Bad type ID. */
+#define PIO_ETYPDEFINED NC_ETYPDEFINED    /**< Type has already been defined and may not be edited. */
+#define PIO_EBADFIELD NC_EBADFIELD    /**< Bad field ID. */
+#define PIO_EBADCLASS NC_EBADCLASS    /**< Bad class. */
+#define PIO_EMAPTYPE NC_EMAPTYPE      /**< Mapped access for atomic types only. */
+#define PIO_ELATEFILL NC_ELATEFILL    /**< Attempt to define fill value when data already exists. */
+#define PIO_ELATEDEF NC_ELATEDEF      /**< Attempt to define var properties, like deflate, after enddef. */
+#define PIO_EDIMSCALE NC_EDIMSCALE    /**< Problem with HDF5 dimscales. */
+#define PIO_ENOGRP NC_ENOGRP          /**< No group found. */
+#define PIO_ESTORAGE NC_ESTORAGE      /**< Can't specify both contiguous and chunking. */
+#define PIO_EBADCHUNK NC_EBADCHUNK    /**< Bad chunksize. */
+#define PIO_ENOTBUILT NC_ENOTBUILT    /**< Attempt to use feature that was not turned on when netCDF was built. */
+#define PIO_EDISKLESS NC_EDISKLESS    /**< Error in using diskless  access. */
 
 /* These are the netCDF default fill values. */
-#define PIO_FILL_BYTE NC_FILL_BYTE
-#define PIO_FILL_CHAR NC_FILL_CHAR
-#define PIO_FILL_SHORT NC_FILL_SHORT
-#define PIO_FILL_INT NC_FILL_INT
-#define PIO_FILL_FLOAT NC_FILL_FLOAT
-#define PIO_FILL_DOUBLE NC_FILL_DOUBLE
-#define PIO_FILL_UBYTE NC_FILL_UBYTE
-#define PIO_FILL_USHORT NC_FILL_USHORT
-#define PIO_FILL_UINT NC_FILL_UINT
-#define PIO_FILL_INT64 NC_FILL_INT64
-#define PIO_FILL_UINT64 NC_FILL_UINT64
-
-#define PIO_EINDEP  NC_EINDEP
-
-/** The first error code for PIO. */
-#define PIO_FIRST_ERROR_CODE (-500)
-
-/** Bad IOTYPE error. */
-#define PIO_EBADIOTYPE  (-500)
-
-/** Variable dimensions do not match in a multivar call. */
-#define PIO_EVARDIMMISMATCH (-501)
-
-/** Request null. */
-#define PIO_REQ_NULL (NC_REQ_NULL-1)
+#define PIO_FILL_BYTE NC_FILL_BYTE     /**< Default fill value for this type. */
+#define PIO_FILL_CHAR NC_FILL_CHAR     /**< Default fill value for this type. */
+#define PIO_FILL_SHORT NC_FILL_SHORT   /**< Default fill value for this type. */
+#define PIO_FILL_INT NC_FILL_INT       /**< Default fill value for this type. */
+#define PIO_FILL_FLOAT NC_FILL_FLOAT   /**< Default fill value for this type. */
+#define PIO_FILL_DOUBLE NC_FILL_DOUBLE /**< Default fill value for this type. */
+#define PIO_FILL_UBYTE NC_FILL_UBYTE   /**< Default fill value for this type. */
+#define PIO_FILL_USHORT NC_FILL_USHORT /**< Default fill value for this type. */
+#define PIO_FILL_UINT NC_FILL_UINT     /**< Default fill value for this type. */
+#define PIO_FILL_INT64 NC_FILL_INT64   /**< Default fill value for this type. */
+#define PIO_FILL_UINT64 NC_FILL_UINT64 /**< Default fill value for this type. */
+
+#define PIO_EINDEP  (-203)  /**< independent access error. */
+
+#define PIO_FIRST_ERROR_CODE (-500)  /**< The first error code for PIO. */
+#define PIO_EBADIOTYPE  (-500)       /**< Bad IOTYPE error. */
+#define PIO_EVARDIMMISMATCH (-501)   /**< Variable dimensions do not match in a multivar call. */
+#define PIO_REQ_NULL (NC_REQ_NULL-1) /**< Request null. */
 
 #if defined(__cplusplus)
 extern "C" {