diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in index ddc33798b..ffd5b9719 100644 --- a/docs/Doxyfile.in +++ b/docs/Doxyfile.in @@ -117,7 +117,7 @@ ABBREVIATE_BRIEF = # description. # The default value is: NO. -ALWAYS_DETAILED_SEC = NO +ALWAYS_DETAILED_SEC = YES # If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all # inherited members of a class in the documentation of that class as if those @@ -125,7 +125,7 @@ ALWAYS_DETAILED_SEC = NO # operators of the base classes will not be shown. # The default value is: NO. -INLINE_INHERITED_MEMB = NO +INLINE_INHERITED_MEMB = YES # If the FULL_PATH_NAMES tag is set to YES doxygen will prepend the full path # before files name in the file list and in the header files. If set to NO the @@ -189,7 +189,7 @@ QT_AUTOBRIEF = YES # not recognized any more. # The default value is: NO. -MULTILINE_CPP_IS_BRIEF = NO +MULTILINE_CPP_IS_BRIEF = YES # If the INHERIT_DOCS tag is set to YES then an undocumented member inherits the # documentation from any documented member that it re-implements. @@ -404,7 +404,7 @@ EXTRACT_ALL = NO # be included in the documentation. # The default value is: NO. -EXTRACT_PRIVATE = NO +EXTRACT_PRIVATE = YES # If the EXTRACT_PACKAGE tag is set to YES all members with package or internal # scope will be included in the documentation. @@ -441,7 +441,7 @@ EXTRACT_LOCAL_METHODS = NO # are hidden. # The default value is: NO. -EXTRACT_ANON_NSPACES = NO +EXTRACT_ANON_NSPACES = YES # If the HIDE_UNDOC_MEMBERS tag is set to YES, doxygen will hide all # undocumented members inside documented classes or files. If set to NO these @@ -487,7 +487,7 @@ INTERNAL_DOCS = @BUILD_INTERNAL_DOCS@ # and Mac users are advised to set this option to NO. # The default value is: system dependent. -CASE_SENSE_NAMES = YES +CASE_SENSE_NAMES = NO # If the HIDE_SCOPE_NAMES tag is set to NO then doxygen will show members with # their full class and namespace scopes in the documentation. If set to YES the @@ -513,7 +513,7 @@ SHOW_GROUPED_MEMB_INC = NO # files with double quotes in the documentation rather than with sharp brackets. # The default value is: NO. -FORCE_LOCAL_INCLUDES = NO +FORCE_LOCAL_INCLUDES = YES # If the INLINE_INFO tag is set to YES then a tag [inline] is inserted in the # documentation for inline members. @@ -2237,7 +2237,7 @@ INCLUDED_BY_GRAPH = YES # The default value is: NO. # This tag requires that the tag HAVE_DOT is set to YES. -CALL_GRAPH = YES +CALL_GRAPH = NO # If the CALLER_GRAPH tag is set to YES then doxygen will generate a caller # dependency graph for every global function or class method. diff --git a/libdispatch/dfile.c b/libdispatch/dfile.c index b4e28047d..2a6f69f73 100644 --- a/libdispatch/dfile.c +++ b/libdispatch/dfile.c @@ -1,4 +1,5 @@ -/** \file +/** \file dfile.c + File create and open functions These functions end up calling functions in one of the dispatch layers @@ -64,6 +65,20 @@ of the interfaces for these operations. */ /**@{*/ + +/*! + Interpret the magic number found in the header of a netCDF file. + + This function interprets the magic number/string contained in the header of a netCDF file and sets the appropriate NC_FORMATX flags. + + @param[in] magic Pointer to a character array with the magic number block. + @param[out] model Pointer to an integer to hold the corresponding netCDF type. + @param[out] version Pointer to an integer to hold the corresponding netCDF version. + @param[in] use_parallel 1 if using parallel, 0 if not. + @return Returns an error code or 0 on success. + + +*/ static int NC_interpret_magic_number(char* magic, int* model, int* version, int use_parallel) { @@ -100,7 +115,7 @@ done: return status; } -/** +/*! Given an existing file, figure out its format and return that format value (NC_FORMATX_XXX) in model arg. diff --git a/libdispatch/dparallel.c b/libdispatch/dparallel.c index d7105a5fc..5fbb24b34 100644 --- a/libdispatch/dparallel.c +++ b/libdispatch/dparallel.c @@ -1,5 +1,5 @@ /** \file dparallel.c -This file has the parallel I/O functions. +This file has the parallel I/O functions which correspond to the serial I/O functions. Copyright 2010 University Corporation for Atmospheric Research/Unidata. See COPYRIGHT file for more info. @@ -33,7 +33,11 @@ int nc_create_par(const char *path, int cmode, MPI_Comm comm, #endif /* USE_PARALLEL */ } -/* This function opens a file for parallel I/O. */ +/*! \ingroup datasets + + This function opens a file for parallel I/O. + +*/ int nc_open_par(const char *path, int mode, MPI_Comm comm, MPI_Info info, int *ncidp) diff --git a/libdispatch/dvarput.c b/libdispatch/dvarput.c index f8341acee..59e071bc7 100644 --- a/libdispatch/dvarput.c +++ b/libdispatch/dvarput.c @@ -1,4 +1,4 @@ -/*! +/*! \file dvarput.c Functions for writing data to variables. Copyright 2010 University Corporation for Atmospheric @@ -33,7 +33,7 @@ odom_init(struct PUTodometer* odom, odom->stride[i] = (stride != NULL ? stride[i] : 1); odom->stop[i] = odom->start[i] + (odom->edges[i]*(size_t)odom->stride[i]); odom->index[i] = odom->start[i]; - } + } } static int @@ -61,7 +61,7 @@ odom_next(struct PUTodometer* odom) \ingroup variables */ static int -NC_put_vara(int ncid, int varid, const size_t *start, +NC_put_vara(int ncid, int varid, const size_t *start, const size_t *edges, const void *value, nc_type memtype) { NC* ncp; @@ -70,7 +70,7 @@ NC_put_vara(int ncid, int varid, const size_t *start, if(edges == NULL) { size_t shape[NC_MAX_VAR_DIMS]; int ndims; - stat = nc_inq_varndims(ncid, varid, &ndims); + stat = nc_inq_varndims(ncid, varid, &ndims); if(stat != NC_NOERR) return stat; stat = NC_getshape(ncid, varid, ndims, shape); if(stat != NC_NOERR) return stat; @@ -98,7 +98,7 @@ NC_put_var(int ncid, int varid, const void *value, nc_type memtype) \ingroup variables */ static int -NC_put_var1(int ncid, int varid, const size_t *coord, const void* value, +NC_put_var1(int ncid, int varid, const size_t *coord, const void* value, nc_type memtype) { return NC_put_vara(ncid, varid, coord, NC_coord_one, value, memtype); @@ -120,7 +120,7 @@ NCDEFAULT_put_vars(int ncid, int varid, const size_t * start, return ncp->dispatch->put_varm(ncid,varid,start,edges,stride,NULL,value0,memtype); #else /* Rebuilt put_vars code to simplify and avoid use of put_varm */ - + int status = NC_NOERR; int i,isstride1,isrecvar; int rank; @@ -142,7 +142,7 @@ NCDEFAULT_put_vars(int ncid, int varid, const size_t * start, status = NC_check_id (ncid, &ncp); if(status != NC_NOERR) return status; - status = nc_inq_vartype(ncid, varid, &vartype); + status = nc_inq_vartype(ncid, varid, &vartype); if(status != NC_NOERR) return status; if(memtype == NC_NAT) memtype = vartype; @@ -168,7 +168,7 @@ NCDEFAULT_put_vars(int ncid, int varid, const size_t * start, } /* Get the variable rank */ - status = nc_inq_varndims(ncid, varid, &rank); + status = nc_inq_varndims(ncid, varid, &rank); if(status != NC_NOERR) return status; /* Get variable dimension sizes */ @@ -178,7 +178,7 @@ NCDEFAULT_put_vars(int ncid, int varid, const size_t * start, status = NC_inq_recvar(ncid,varid,&nrecdims,is_recdim); if(status != NC_NOERR) return status; isrecvar = (nrecdims > 0); - NC_getshape(ncid,varid,rank,varshape); + NC_getshape(ncid,varid,rank,varshape); /* Optimize out using various checks */ if (rank == 0) { @@ -215,7 +215,7 @@ NCDEFAULT_put_vars(int ncid, int varid, const size_t * start, /* cast needed for braindead systems with signed size_t */ || ((unsigned long) mystride[i] >= X_INT_MAX)) return NC_ESTRIDE; - if(mystride[i] != 1) isstride1 = 0; + if(mystride[i] != 1) isstride1 = 0; /* illegal value checks */ #if 0 dimlen = (i == 0 && isrecvar ? numrecs : varshape[i]); @@ -228,7 +228,7 @@ NCDEFAULT_put_vars(int ncid, int varid, const size_t * start, /* mystart is unsigned, will never be < 0 */ if(mystart[i] > dimlen) return NC_EINVALCOORDS; - /* myediges is unsigned, will never be < 0 */ + /* myediges is unsigned, will never be < 0 */ if(mystart[i] + myedges[i] > dimlen) return NC_EEDGE; } @@ -295,13 +295,13 @@ NCDEFAULT_put_varm( */ /* mid body */ - status = nc_inq_vartype(ncid, varid, &vartype); + status = nc_inq_vartype(ncid, varid, &vartype); if(status != NC_NOERR) return status; /* Check that this is an atomic type */ if(vartype > NC_MAX_ATOMIC_TYPE) return NC_EMAPTYPE; - status = nc_inq_varndims(ncid, varid, &varndims); + status = nc_inq_varndims(ncid, varid, &varndims); if(status != NC_NOERR) return status; if(memtype == NC_NAT) { @@ -310,7 +310,7 @@ NCDEFAULT_put_varm( if(memtype == NC_CHAR && vartype != NC_CHAR) return NC_ECHAR; - else if(memtype != NC_CHAR && vartype == NC_CHAR) + else if(memtype != NC_CHAR && vartype == NC_CHAR) return NC_ECHAR; memtypelen = nctypelen(memtype); @@ -371,7 +371,7 @@ NCDEFAULT_put_varm( /* Compute some dimension related values */ isrecvar = NC_is_recvar(ncid,varid,&numrecs); - NC_getshape(ncid,varid,varndims,varshape); + NC_getshape(ncid,varid,varndims,varshape); /* assert(sizeof(ptrdiff_t) >= sizeof(size_t)); */ mystart = (size_t *)calloc((size_t)(varndims * 7), sizeof(ptrdiff_t)); @@ -436,7 +436,7 @@ NCDEFAULT_put_varm( /* Lower body */ /* - * As an optimization, adjust I/O parameters when the fastest + * As an optimization, adjust I/O parameters when the fastest * dimension has unity stride both externally and internally. * In this case, the user could have called a simpler routine * (i.e. ncvar$1() @@ -460,7 +460,7 @@ NCDEFAULT_put_varm( if (lstatus != NC_NOERR) { if(status == NC_NOERR || lstatus != NC_ERANGE) status = lstatus; - } + } /* * The following code permutes through the variable s @@ -510,7 +510,7 @@ NC_put_vars(int ncid, int varid, const size_t *start, \ingroup variables */ static int -NC_put_varm(int ncid, int varid, const size_t *start, +NC_put_varm(int ncid, int varid, const size_t *start, const size_t *edges, const ptrdiff_t *stride, const ptrdiff_t* map, const void *value, nc_type memtype) { @@ -530,7 +530,7 @@ Functions to write data from variables. */ /*! \{ */ /* All these functions are part of this named group... */ /** \ingroup variables -Write an array of values to a variable. +Write an array of values to a variable. The values to be written are associated with the netCDF variable by assuming that the last dimension of the netCDF variable varies fastest @@ -546,7 +546,7 @@ user defined type. For this function, the type of the data in memory must match the type of the variable - no data conversion is done. \param ncid NetCDF or group ID, from a previous call to nc_open(), -nc_create(), nc_def_grp(), or associated inquiry functions such as +nc_create(), nc_def_grp(), or associated inquiry functions such as nc_inq_ncid(). \param varid Variable ID @@ -570,7 +570,7 @@ allocated by the user before this function is called. */ /**@{*/ int -nc_put_vara(int ncid, int varid, const size_t *startp, +nc_put_vara(int ncid, int varid, const size_t *startp, const size_t *countp, const void *op) { NC* ncp; @@ -583,59 +583,59 @@ nc_put_vara(int ncid, int varid, const size_t *startp, } int -nc_put_vara_text(int ncid, int varid, const size_t *startp, +nc_put_vara_text(int ncid, int varid, const size_t *startp, const size_t *countp, const char *op) { - return NC_put_vara(ncid, varid, startp, countp, + return NC_put_vara(ncid, varid, startp, countp, (void*)op, NC_CHAR); } int -nc_put_vara_schar(int ncid, int varid, const size_t *startp, +nc_put_vara_schar(int ncid, int varid, const size_t *startp, const size_t *countp, const signed char *op) { NC* ncp; int stat = NC_check_id(ncid, &ncp); if(stat != NC_NOERR) return stat; - return NC_put_vara(ncid, varid, startp, countp, (void *)op, + return NC_put_vara(ncid, varid, startp, countp, (void *)op, NC_BYTE); } int -nc_put_vara_uchar(int ncid, int varid, const size_t *startp, +nc_put_vara_uchar(int ncid, int varid, const size_t *startp, const size_t *countp, const unsigned char *op) { NC* ncp; int stat = NC_check_id(ncid, &ncp); if(stat != NC_NOERR) return stat; - return NC_put_vara(ncid, varid, startp, countp, (void *)op, + return NC_put_vara(ncid, varid, startp, countp, (void *)op, T_uchar); } int -nc_put_vara_short(int ncid, int varid, const size_t *startp, +nc_put_vara_short(int ncid, int varid, const size_t *startp, const size_t *countp, const short *op) { NC* ncp; int stat = NC_check_id(ncid, &ncp); if(stat != NC_NOERR) return stat; - return NC_put_vara(ncid, varid, startp, countp, (void *)op, + return NC_put_vara(ncid, varid, startp, countp, (void *)op, NC_SHORT); } int -nc_put_vara_int(int ncid, int varid, const size_t *startp, +nc_put_vara_int(int ncid, int varid, const size_t *startp, const size_t *countp, const int *op) { NC* ncp; int stat = NC_check_id(ncid, &ncp); if(stat != NC_NOERR) return stat; - return NC_put_vara(ncid, varid, startp, countp, (void *)op, + return NC_put_vara(ncid, varid, startp, countp, (void *)op, NC_INT); } int -nc_put_vara_long(int ncid, int varid, const size_t *startp, +nc_put_vara_long(int ncid, int varid, const size_t *startp, const size_t *countp, const long *op) { NC* ncp; @@ -646,7 +646,7 @@ nc_put_vara_long(int ncid, int varid, const size_t *startp, } int -nc_put_vara_float(int ncid, int varid, const size_t *startp, +nc_put_vara_float(int ncid, int varid, const size_t *startp, const size_t *countp, const float *op) { NC* ncp; @@ -657,7 +657,7 @@ nc_put_vara_float(int ncid, int varid, const size_t *startp, } int -nc_put_vara_double(int ncid, int varid, const size_t *startp, +nc_put_vara_double(int ncid, int varid, const size_t *startp, const size_t *countp, const double *op) { NC* ncp; @@ -668,7 +668,7 @@ nc_put_vara_double(int ncid, int varid, const size_t *startp, } int -nc_put_vara_ubyte(int ncid, int varid, const size_t *startp, +nc_put_vara_ubyte(int ncid, int varid, const size_t *startp, const size_t *countp, const unsigned char *op) { NC* ncp; @@ -679,7 +679,7 @@ nc_put_vara_ubyte(int ncid, int varid, const size_t *startp, } int -nc_put_vara_ushort(int ncid, int varid, const size_t *startp, +nc_put_vara_ushort(int ncid, int varid, const size_t *startp, const size_t *countp, const unsigned short *op) { NC* ncp; @@ -690,7 +690,7 @@ nc_put_vara_ushort(int ncid, int varid, const size_t *startp, } int -nc_put_vara_uint(int ncid, int varid, const size_t *startp, +nc_put_vara_uint(int ncid, int varid, const size_t *startp, const size_t *countp, const unsigned int *op) { NC* ncp; @@ -701,7 +701,7 @@ nc_put_vara_uint(int ncid, int varid, const size_t *startp, } int -nc_put_vara_longlong(int ncid, int varid, const size_t *startp, +nc_put_vara_longlong(int ncid, int varid, const size_t *startp, const size_t *countp, const long long *op) { NC* ncp; @@ -712,7 +712,7 @@ nc_put_vara_longlong(int ncid, int varid, const size_t *startp, } int -nc_put_vara_ulonglong(int ncid, int varid, const size_t *startp, +nc_put_vara_ulonglong(int ncid, int varid, const size_t *startp, const size_t *countp, const unsigned long long *op) { NC* ncp; @@ -724,7 +724,7 @@ nc_put_vara_ulonglong(int ncid, int varid, const size_t *startp, #ifdef USE_NETCDF4 int -nc_put_vara_string(int ncid, int varid, const size_t *startp, +nc_put_vara_string(int ncid, int varid, const size_t *startp, const size_t *countp, const char* *op) { NC* ncp; @@ -738,10 +738,10 @@ nc_put_vara_string(int ncid, int varid, const size_t *startp, /**@}*/ /** \ingroup variables -Write one datum. +Write one datum. \param ncid NetCDF or group ID, from a previous call to nc_open(), -nc_create(), nc_def_grp(), or associated inquiry functions such as +nc_create(), nc_def_grp(), or associated inquiry functions such as nc_inq_ncid(). \param varid Variable ID @@ -895,7 +895,7 @@ nc_put_var1_string(int ncid, int varid, const size_t *indexp, const char* *op) /**@}*/ /** \ingroup variables -Write an entire variable with one call. +Write an entire variable with one call. The nc_put_var_ type family of functions write all the values of a variable into a netCDF variable of an open netCDF dataset. This is the @@ -914,7 +914,7 @@ try to write all the values of a record variable but there are more records in the file than you assume, more in-memory data will be accessed than you supply, which may result in a segmentation violation. To avoid such problems, it is better to use the nc_put_vara -interfaces for variables that use the ::NC_UNLIMITED dimension. +interfaces for variables that use the ::NC_UNLIMITED dimension. The functions for types ubyte, ushort, uint, longlong, ulonglong, and string are only available for netCDF-4/HDF5 files. @@ -924,7 +924,7 @@ user defined type. For this function, the type of the data in memory must match the type of the variable - no data conversion is done. \param ncid NetCDF or group ID, from a previous call to nc_open(), -nc_create(), nc_def_grp(), or associated inquiry functions such as +nc_create(), nc_def_grp(), or associated inquiry functions such as nc_inq_ncid(). \param varid Variable ID @@ -1076,10 +1076,10 @@ nc_put_var_string(int ncid, int varid, const char* *op) /**\} */ /** \ingroup variables -Write a strided array of values to a variable. +Write a strided array of values to a variable. \param ncid NetCDF or group ID, from a previous call to nc_open(), -nc_create(), nc_def_grp(), or associated inquiry functions such as +nc_create(), nc_def_grp(), or associated inquiry functions such as nc_inq_ncid(). \param varid Variable ID @@ -1115,12 +1115,12 @@ nc_put_vars (int ncid, int varid, const size_t *startp, if ((stat = NC_check_id(ncid, &ncp))) return stat; - return ncp->dispatch->put_vars(ncid, varid, startp, countp, + return ncp->dispatch->put_vars(ncid, varid, startp, countp, stridep, op, NC_NAT); } int -nc_put_vars_text(int ncid, int varid, const size_t *startp, +nc_put_vars_text(int ncid, int varid, const size_t *startp, const size_t *countp, const ptrdiff_t *stridep, const char *op) { @@ -1132,14 +1132,14 @@ nc_put_vars_text(int ncid, int varid, const size_t *startp, } int -nc_put_vars_schar(int ncid, int varid, const size_t *startp, +nc_put_vars_schar(int ncid, int varid, const size_t *startp, const size_t *countp, const ptrdiff_t *stridep, const signed char *op) { NC *ncp; int stat = NC_check_id(ncid, &ncp); if(stat != NC_NOERR) return stat; - return NC_put_vars(ncid, varid, startp, countp, + return NC_put_vars(ncid, varid, startp, countp, stridep,(void*)op,NC_BYTE); } @@ -1303,7 +1303,7 @@ nc_put_vars_string(int ncid, int varid, /**\} */ /** \ingroup variables -Write a mapped array of values to a variable. +Write a mapped array of values to a variable. The nc_put_varm() function will only write a variable of an atomic type; it will not write user defined types. For this @@ -1316,7 +1316,7 @@ The reason is the complexity of the algorithm makes its use difficult for users to properly use. \param ncid NetCDF or group ID, from a previous call to nc_open(), -nc_create(), nc_def_grp(), or associated inquiry functions such as +nc_create(), nc_def_grp(), or associated inquiry functions such as nc_inq_ncid(). \param varid Variable ID @@ -1355,13 +1355,13 @@ nc_put_varm (int ncid, int varid, const size_t *startp, if ((stat = NC_check_id(ncid, &ncp))) return stat; - return ncp->dispatch->put_varm(ncid, varid, startp, countp, + return ncp->dispatch->put_varm(ncid, varid, startp, countp, stridep, imapp, op, NC_NAT); } int -nc_put_varm_text(int ncid, int varid, const size_t *startp, - const size_t *countp, const ptrdiff_t *stridep, +nc_put_varm_text(int ncid, int varid, const size_t *startp, + const size_t *countp, const ptrdiff_t *stridep, const ptrdiff_t *imapp, const char *op) { NC *ncp; @@ -1545,4 +1545,3 @@ nc_put_varm_string(int ncid, int varid, /*! \} */ /*End of named group... */ -