mirror/netcdf-c
2
0
Fork 0
mirror of https://github.com/Unidata/netcdf-c.git synced 2024-11-21 03:13:42 +08:00
Code Issues Packages Projects Releases Wiki Activity

Tightening the Doxygen documentation.

Browse Source
This commit is contained in:
Ward Fisher 2016-01-14 15:33:50 -07:00
parent 04db4cd4a7
commit 3f27ec6db4
4 changed files with 87 additions and 69 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
docs/Doxyfile.in
View File

@ -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.

19
libdispatch/dfile.c
View File

@ -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.

8
libdispatch/dparallel.c
View File

@ -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)

113
libdispatch/dvarput.c
View File

@ -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... */