Documentation issue: API reference does not cover all public NetCDF functions

[ckhroulev]

Please consider adding doxygen comment stubs to all functions in NetCDF's public API. This will greatly help with API discoverability even if a function's documentation is empty or just contains a "FIX ME" note.

For example: it took me a while to convince myself that NetCDF does expose HDF5's chunking settings: nc_def_var_chunking is not mentioned in NetCDF API reference.

As a suggestion: setting

WARN_IF_UNDOCUMENTED   = YES

in docs/Doxyfile.in would produce warnings for all undocumented functions (both public and internal). Comparing these to contents of netcdf.h would give a list of undocumented public functions.

Let me know if I should do this and submit a pull request. (I should have some time over the weekend and I think I can automate this.)

[WardF]

Hi! Sorry for the delayed response, I've been out of the office. A pull request would be great, thank you very much! If this is no longer on your radar due to the delay, I understand, let me know and I'll look into it myself.

[edhartnett]

This is really the same as issue: Some netcdf functions are not in the doxygen documentation on-line. #277

I agree with Constantine Khroulev that all public netCDF functions should be fully documented.

I will go further and say that all private, internal functions should be fully documented. (Doxygen has the ability to build them for developers but not for users.)

I suggest that you adopt this as a general principal and start checking for it in all changed code. I'm sure users would be willing to document functions in code where they are making significant changes. I know I would be happy to do so.

I have not taken a good look recently at the state of documentation in netCDF internal code. Perhaps you already maintain this standard. What I am really suggesting is that you turn on doxygen warnings, get the warning count down to 0, and they have Doxygen warnings treated as errors by your automated testing.

[edhartnett]

Running doxygen with the warning enabled turns up some surprising undocumented functions. Here the relevant warnings for public functions:

/home/ed/tmp/netcdf-c/libdispatch/derror.c:28: warning: Member nc_inq_libvers(void) (function) of file derror.c is not documented.
/home/ed/tmp/netcdf-c/libdispatch/dfile.c:1508: warning: Member nc_inq_nvars(int ncid, int *nvarsp) (function) of file dfile.c is not documented.
/home/ed/tmp/netcdf-c/libdispatch/dparallel.c:98: warning: Member nc_var_par_access(int ncid, int varid, int par_access) (function) of file dparallel.c is not documented.
/home/ed/tmp/netcdf-c/libdispatch/dparallel.c:16: warning: parameters of member nc_create_par are not (all) documented
/home/ed/tmp/netcdf-c/libdispatch/dparallel.c:16: warning: return type of member nc_create_par is not documented
/home/ed/tmp/netcdf-c/libdispatch/dv2i.c:370: warning: Member nc_advise(const char *routine_name, int err, const char *fmt,...) (function) of file dv2i.c is not documented.
/home/ed/tmp/netcdf-c/libdispatch/dv2i.c:330: warning: Member nc_get_rec(int ncid, size_t recnum, void **datap) (function) of file dv2i.c is not documented.
/home/ed/tmp/netcdf-c/libdispatch/dv2i.c:230: warning: Member nc_inq_rec(int ncid, size_t *nrecvarsp, int *recvarids, size_t *recsizes) (function) of file dv2i.c is not documented.
/home/ed/tmp/netcdf-c/libdispatch/dv2i.c:284: warning: Member nc_put_rec(int ncid, size_t recnum, void *const *datap) (function) of file dv2i.c is not documented.
/home/ed/tmp/netcdf-c/libdispatch/dv2i.c:517: warning: Member ncabort(int ncid) (function) of file dv2i.c is not documented.
/home/ed/tmp/netcdf-c/libdispatch/dv2i.c:1054: warning: Member ncattcopy(int ncid_in, int varid_in, const char *name, int ncid_out, int varid_out) (function) of file dv2i.c is not documented.
/home/ed/tmp/netcdf-c/libdispatch/dv2i.c:1109: warning: Member ncattdel(int ncid, int varid, const char *name) (function) of file dv2i.c is not documented.
/home/ed/tmp/netcdf-c/libdispatch/dv2i.c:1036: warning: Member ncattget(int ncid, int varid, const char *name, void *value) (function) of file dv2i.c is not documented.
/home/ed/tmp/netcdf-c/libdispatch/dv2i.c:1009: warning: Member ncattinq(int ncid, int varid, const char *name, nc_type *datatype, int *len) (function) of file dv2i.c is not documented.
/home/ed/tmp/netcdf-c/libdispatch/dv2i.c:1073: warning: Member ncattname(int ncid, int varid, int attnum, char *name) (function) of file dv2i.c is not documented.
/home/ed/tmp/netcdf-c/libdispatch/dv2i.c:989: warning: Member ncattput(int ncid, int varid, const char *name, nc_type datatype, int len, const void *value) (function) of file dv2i.c is not documented.
/home/ed/tmp/netcdf-c/libdispatch/dv2i.c:1091: warning: Member ncattrename(int ncid, int varid, const char *name, const char *newname) (function) of file dv2i.c is not documented.
/home/ed/tmp/netcdf-c/libdispatch/dv2i.c:457: warning: Member ncclose(int ncid) (function) of file dv2i.c is not documented.
/home/ed/tmp/netcdf-c/libdispatch/dv2i.c:403: warning: Member nccreate(const char *path, int cmode) (function) of file dv2i.c is not documented.
/home/ed/tmp/netcdf-c/libdispatch/dv2i.c:530: warning: Member ncdimdef(int ncid, const char *name, long length) (function) of file dv2i.c is not documented.
/home/ed/tmp/netcdf-c/libdispatch/dv2i.c:554: warning: Member ncdimid(int ncid, const char *name) (function) of file dv2i.c is not documented.
/home/ed/tmp/netcdf-c/libdispatch/dv2i.c:568: warning: Member ncdiminq(int ncid, int dimid, char *name, long *length) (function) of file dv2i.c is not documented.
/home/ed/tmp/netcdf-c/libdispatch/dv2i.c:593: warning: Member ncdimrename(int ncid, int dimid, const char *name) (function) of file dv2i.c is not documented.
/home/ed/tmp/netcdf-c/libdispatch/dv2i.c:444: warning: Member ncendef(int ncid) (function) of file dv2i.c is not documented.
/home/ed/tmp/netcdf-c/libdispatch/dv2i.c:471: warning: Member ncinquire(int ncid, int *ndims, int *nvars, int *natts, int *recdim) (function) of file dv2i.c is not documented.
/home/ed/tmp/netcdf-c/libdispatch/dv2i.c:417: warning: Member ncopen(const char *path, int mode) (function) of file dv2i.c is not documented.
/home/ed/tmp/netcdf-c/libdispatch/dv2i.c:1188: warning: Member ncrecget(int ncid, long recnum, void **datap) (function) of file dv2i.c is not documented.
/home/ed/tmp/netcdf-c/libdispatch/dv2i.c:1146: warning: Member ncrecinq(int ncid, int *nrecvars, int *recvarids, long *recsizes) (function) of file dv2i.c is not documented.
/home/ed/tmp/netcdf-c/libdispatch/dv2i.c:1205: warning: Member ncrecput(int ncid, long recnum, void *const *datap) (function) of file dv2i.c is not documented.
/home/ed/tmp/netcdf-c/libdispatch/dv2i.c:154: warning: Member ncrecsize(int ncid, int varid, size_t *recsizep) (function) of file dv2i.c is not documented.
/home/ed/tmp/netcdf-c/libdispatch/dv2i.c:431: warning: Member ncredef(int ncid) (function) of file dv2i.c is not documented.
/home/ed/tmp/netcdf-c/libdispatch/dv2i.c:1129: warning: Member ncsetfill(int ncid, int fillmode) (function) of file dv2i.c is not documented.
/home/ed/tmp/netcdf-c/libdispatch/dv2i.c:503: warning: Member ncsync(int ncid) (function) of file dv2i.c is not documented.
/home/ed/tmp/netcdf-c/libdispatch/dv2i.c:610: warning: Member ncvardef(int ncid, const char *name, nc_type datatype, int ndims, const int *dim) (function) of file dv2i.c is not documented.
/home/ed/tmp/netcdf-c/libdispatch/dv2i.c:755: warning: Member ncvarget(int ncid, int varid, const long *start, const long *count, void *value) (function) of file dv2i.c is not documented.
/home/ed/tmp/netcdf-c/libdispatch/dv2i.c:703: warning: Member ncvarget1(int ncid, int varid, const long *index, void *value) (function) of file dv2i.c is not documented.
/home/ed/tmp/netcdf-c/libdispatch/dv2i.c:915: warning: Member ncvargetg(int ncid, int varid, const long *start, const long *count, const long *stride, const long *map, void *value) (function) of file dv2i.c is not documented.
/home/ed/tmp/netcdf-c/libdispatch/dv2i.c:821: warning: Member ncvargets(int ncid, int varid, const long *start, const long *count, const long *stride, void *value) (function) of file dv2i.c is not documented.
/home/ed/tmp/netcdf-c/libdispatch/dv2i.c:630: warning: Member ncvarid(int ncid, const char *name) (function) of file dv2i.c is not documented.
/home/ed/tmp/netcdf-c/libdispatch/dv2i.c:647: warning: Member ncvarinq(int ncid, int varid, char *name, nc_type *datatype, int *ndims, int *dim, int *natts) (function) of file dv2i.c is not documented.
/home/ed/tmp/netcdf-c/libdispatch/dv2i.c:727: warning: Member ncvarput(int ncid, int varid, const long *start, const long *count, const void *value) (function) of file dv2i.c is not documented.
/home/ed/tmp/netcdf-c/libdispatch/dv2i.c:679: warning: Member ncvarput1(int ncid, int varid, const long *index, const void *value) (function) of file dv2i.c is not documented.
/home/ed/tmp/netcdf-c/libdispatch/dv2i.c:858: warning: Member ncvarputg(int ncid, int varid, const long *start, const long *count, const long *stride, const long *map, const void *value) (function) of file dv2i.c is not documented.
/home/ed/tmp/netcdf-c/libdispatch/dv2i.c:783: warning: Member ncvarputs(int ncid, int varid, const long *start, const long *count, const long *stride, const void *value) (function) of file dv2i.c is not documented.
/home/ed/tmp/netcdf-c/libdispatch/dv2i.c:972: warning: Member ncvarrename(int ncid, int varid, const char *name) (function) of file dv2i.c is not documented.
/home/ed/tmp/netcdf-c/libdispatch/dv2i.c:108: warning: Member numrecvars(int ncid, int *nrecvarsp, int *recvarids) (function) of file dv2i.c is not documented.
/home/ed/tmp/netcdf-c/libdispatch/dv2i.c:19: warning: Member ncerr (variable) of file dv2i.c is not documented.
/home/ed/tmp/netcdf-c/libdispatch/dv2i.c:18: warning: Member ncopts (variable) of file dv2i.c is not documented.
/home/ed/tmp/netcdf-c/libdispatch/dvar.c:722: warning: Member nc_def_var_endian(int ncid, int varid, int endian) (function) of file dvar.c is not documented.
/home/ed/tmp/netcdf-c/libdispatch/dvar.c:713: warning: Member nc_def_var_fill(int ncid, int varid, int no_fill, const void *fill_value) (function) of file dvar.c is not documented.
/home/ed/tmp/netcdf-c/libdispatch/dvar.c:627: warning: Member nc_def_var_fletcher32(int ncid, int varid, int fletcher32) (function) of file dvar.c is not documented.
/home/ed/tmp/netcdf-c/libdispatch/dvlen.c:176: warning: Member nc_get_vlen_element(int ncid, int typeid1, const void *vlen_element, size_t *len, void *data) (function) of file dvlen.c is not documented.
/home/ed/tmp/netcdf-c/libdispatch/dvlen.c:148: warning: Member nc_put_vlen_element(int ncid, int typeid1, void *vlen_element, size_t len, const void *data) (function) of file dvlen.c is not documented.
/home/ed/tmp/netcdf-c/libsrc4/nc4file.c:227: warning: Member nc_get_chunk_cache(size_t *sizep, size_t *nelemsp, float *preemptionp) (function) of file nc4file.c is not documented.
/home/ed/tmp/netcdf-c/libsrc4/nc4file.c:214: warning: Member nc_set_chunk_cache(size_t size, size_t nelems, float preemption) (function) of file nc4file.c is not documented.
/home/ed/tmp/netcdf-c/include/netcdf.h:1727: warning: Member nc_set_log_level(e) (macro definition) of file netcdf.h is not documented.

There are also hundreds of warnings for internal functions. I will see if I can knock some off documentation for some of the public functions over the next few weeks as I work on the code.

[edhartnett]

I believe that when all current PRs are merged, this ticket can be re-evaluated to see what public functions are still undocumented.

[edhartnett]

@WardF this issue can be closed. All public functions have documentation now.