missing documentation in libdap2

[edhartnett]

Doxygen documentation missing or incorrect in libdap2

Summary

The libdap2 directory has almost no Doxygen documentation. Only one file
(dapcvt.c) had any Doxygen comments at all, and those contained several
factual errors and omissions. All other .c source files had zero Doxygen
markup on any function.

Incorrect documentation in dapcvt.c

1. cvtnumconst — @return is factually wrong

The @return tag says NC_NAT on failure, but the actual code returns
NC_INT on failure. NC_NAT is never returned by this function.

Additionally:

• There is no description text, only bare @param/@return tags.
• The input parameter s (the string to parse) has no @param entry.
• NC_INT || NC_DOUBLE || NC_NAT uses C operator syntax instead of prose.

2. cvtint2int — @param name is wrong

The @param says valp but the actual parameter is named val and has type
struct Value*, not a bare long long*.

3. cvtdbl2int — type description wrong, leading space on @param

• "to a long" is wrong — the function converts to long long.
• NC_MAX/MIN_INT is ambiguous; should be NC_MAX_INT/NC_MIN_INT.
• @param val has a leading space, inconsistent with the other blocks.

4. dapcvtattrval — missing @param att and @return tag

The att parameter is completely undocumented. There is also no @return tag;
the return value is described only in prose in the description block.

5. cvtint2dbl — missing @param val

The sole parameter val has no @param entry.

6. dapconvert — no documentation at all

The most important public function in the file has no Doxygen comment despite
being the primary entry point for type conversion.

Missing documentation — entire files

None of the following files had any Doxygen comments on any function:

ncdaperr.c

• ocerrtoncerr — converts OC error codes to NC error codes

dapattr.c

• dapmerge — merges DAS attributes into the DDS tree
• buildattribute — allocates and populates an NCattribute from a DAP attribute

dapodom.c

All seven public functions were undocumented:

• dapodom_fromsegment — build odometer from a DCE segment slice range
• dapodom_new — create odometer from explicit start/count/stride/size arrays
• dapodom_free — free an odometer
• dapodom_more — test whether iteration has more elements
• dapodom_count — convert current index to a flat linear offset
• dapodom_next — advance to the next position
• dapodom_varmcount — compute memory buffer offset using caller-supplied steps

daputil.c

All 35 public functions were undocumented, including:

• cdflegalname — convert DAP name to CDF-legal name
• nctypeconvert, octypetonc, nctypetodap, nctypesizeof, nctypetostring — type conversion utilities
• dapalignbuffer, dapdimproduct — buffer and dimension utilities
• dapparamvalue, dapparamcheck, dapparamparselist — URL parameter access
• nclistconcat, nclistminus, nclistdeleteall — list operations
• collectnodepath, collectocpath, makeocpathstring, makepathstring, makecdfpathstring, clonenodenamepath, simplepathstring — path building
• dapinsequence, dapinstructarray, dapgridmap, dapgridarray, dapgridelement, daptopgrid, daptopseq, daptoplevel — node location tests
• modeldecode, getlimitnumber, dapexpandescapes — miscellaneous utilities
• dap_fetch — server fetch wrapper with logging and HTTP error mapping
• dap_badname, dap_getselection — name and URL utilities

cache.c

All eight public functions were undocumented:

• iscached — test whether a variable can be served from cache
• prefetchdata — fetch and cache prefetchable variables
• buildcachenode — fetch from server and build a cache node
• createnccachenode, freenccachenode — cache node lifecycle
• createnccache, freenccache — cache lifecycle
• markprefetch — mark variables eligible for prefetching

cdf.c

All 17 public functions were undocumented, including:

• computecdfnodesets, computevarnodes — node set computation
• fixgrid, fixgrids — grid validation and repair
• computecdfvarnames — variable name assignment
• sequencecheck — sequence usability analysis
• restruct — re-grid constrained DDS trees to match pattern
• mapnodes, unmap — constrained/unconstrained tree mapping
• dimimprint — copy unconstrained dimension sizes to constrained nodes
• definedimsettrans, definedimsets — dimension set computation
• makecdfnode, buildcdftree, freecdfroot — CDFnode/CDFtree lifecycle
• nodematch, simplenodematch — node comparison

ncd2dispatch.c

The four public dispatch functions were undocumented:

• NCD2_initialize — initialize the DAP2 dispatch layer
• NCD2_finalize — finalize the DAP2 dispatch layer
• NCD2_open — open a remote DAP2 dataset (the main entry point, ~300 lines)
• NCD2_close — close a DAP2 dataset

Notes

• getvara.c, constraints.c, dceconstraints.c, and the parser files
  (dceparse.c, dcelex.c, dcetab.c) also have no Doxygen documentation
  but were not addressed here as they are largely generated or highly internal.
• The header files nccommon.h and ncd2dispatch.h also lack Doxygen
  markup on their struct definitions and function declarations.