added doxygen for libdap4

libdap4/d4bytes.c

@@ -1,5 +1,15 @@
 /* Copyright 2018, UCAR/Unidata and OPeNDAP, Inc.
-   See the COPYRIGHT file for more information. */
+   See the COPYRIGHT file for more information. * 
+ */
+
+/** @file d4bytes.c
+ * @brief Byte-buffer utilities for the DAP4 client.
+ *
+ * Provides low-level byte-array allocation and manipulation helpers
+ * used by the DAP4 serialization and dechunking code.
+ *
+ * @author Dennis Heimbigner
+ */
 
 #include <stdlib.h>
 #include <stdio.h>

libdap4/d4bytes.h

@@ -1,27 +1,49 @@
 /* Copyright 2018, UCAR/Unidata and OPeNDAP, Inc.
    See the COPYRIGHT file for more information. */
 
+/** @file d4bytes.h
+ * @brief Growable byte-buffer type for the DAP4 client.
+ *
+ * Declares D4bytes, a simple heap-allocated buffer that grows on demand,
+ * and the functions and macros for allocating, writing, and resetting it.
+ * @author Dennis Heimbigner
+ */
+
 #ifndef D4BYTES_H
 #define D4BYTES_H 1
 
+/** Growable heap buffer used for assembling DAP4 byte streams. */
 typedef struct D4bytes {
-  size_t alloc;
-  size_t used;
-  void* memory;
+  size_t alloc;  /**< Total allocated capacity in bytes. */
+  size_t used;   /**< Number of bytes currently written. */
+  void* memory;  /**< Pointer to the allocated buffer. */
 } D4bytes;
 
 #if defined(_CPLUSPLUS_) || defined(__CPLUSPLUS__) || defined(__CPLUSPLUS)
 extern "C" {
 #endif
 
+/** Allocate and initialise a new empty D4bytes buffer. */
 extern D4bytes* d4bytesnew(void);
-extern void d4bytesfree(D4bytes*);
-extern void* d4bytesalloc(D4bytes*,size_t);
-extern void* d4byteszero(D4bytes*,size_t);
-extern D4bytes* d4bytesconcat(D4bytes*,D4bytes*);
+/** Free a D4bytes buffer and its contents. */
+extern void d4bytesfree(D4bytes* b);
+/**
+ * Ensure at least @p n bytes are available and return a pointer to the
+ * next write position; advances the used count by @p n.
+ */
+extern void* d4bytesalloc(D4bytes* b, size_t n);
+/**
+ * Like d4bytesalloc() but zero-fills the allocated region.
+ */
+extern void* d4byteszero(D4bytes* b, size_t n);
+/** Append the contents of @p src onto @p dst and return @p dst. */
+extern D4bytes* d4bytesconcat(D4bytes* dst, D4bytes* src);
 
+/** Return the number of bytes written into @p d4. */
 #define d4byteslength(d4) ((d4)->used)
+/** Return a pointer to the start of the buffer in @p d4. */
 #define d4bytesmemory(d4) ((d4)->memory)
+/** Reset the used count of @p d4 to zero without freeing memory. */
 #define d4bytesreset(d4) {(d4)->used = 0;}
 
 #if defined(_CPLUSPLUS_) || defined(__CPLUSPLUS__) || defined(__CPLUSPLUS)

libdap4/d4chunk.c

@@ -3,6 +3,16 @@
  *   See netcdf/COPYRIGHT file for copying and redistribution conditions.
  *********************************************************************/
 
+/** @file d4chunk.c
+ * @brief DAP4 chunk-protocol decoder.
+ *
+ * Implements NCD4_dechunk(), which converts a chunked DAP4 wire
+ * response into a contiguous buffer, and NCD4_infermode(), which
+ * determines whether a raw response is DMR-only or a full DAP
+ * (DMR + data) response.
+ * @author Dennis Heimbigner
+ */
+
 #include "d4includes.h"
 #include "d4chunk.h"
 
@@ -25,6 +35,18 @@ and whether it has checksums.
 static int processerrchunk(NCD4response*, void* errchunk, unsigned int count);
 
 /**************************************************/
+/**
+ * Convert a chunked DAP4 wire response into a contiguous buffer in place.
+ *
+ * Walks the chunk headers in @p resp->raw, concatenates the payloads,
+ * and sets @p resp->serial.dmr and (for DAP mode) @p resp->serial.dap
+ * and @p resp->serial.dapsize.  Sets @p resp->remotelittleendian from
+ * the NCD4_LITTLE_ENDIAN_CHUNK flag of the first data chunk.
+ *
+ * @param resp Response object whose @c raw field contains the raw wire bytes.
+ * @return NC_NOERR on success, NC_EDMR if only a DMR was received,
+ *         or another netCDF error code on failure.
+ */
 int
 NCD4_dechunk(NCD4response* resp)
 {

libdap4/d4chunk.h

@@ -3,9 +3,15 @@
  *   See netcdf/COPYRIGHT file for copying and redistribution conditions.
  *********************************************************************/
 
+/** @file d4chunk.h
+ * @brief Public header for the DAP4 chunk-protocol decoder.
+ *
+ * The actual declarations are in ncd4.h (NCD4_dechunk, NCD4_infermode, etc.).
+ * This header is a placeholder included by d4includes.h.
+ * @author Dennis Heimbigner
+ */
+
 #ifndef D4CHUNK_H
 #define D4CHUNK_H 1
-/**************************************************/
-
 
 #endif /*D4CHUNK_H*/

libdap4/d4curlflags.c

@@ -3,6 +3,14 @@
  *   See netcdf/COPYRIGHT file for copying and redistribution conditions.
  *********************************************************************/
 
+/** @file d4curlflags.c
+ * @brief Sets libcurl option flags for DAP4 HTTP connections.
+ *
+ * Applies authentication, proxy, SSL, and other CURLOPT settings
+ * to a CURL easy handle based on the NCD4INFO controls and RC file.
+ * @author Dennis Heimbigner
+ */
+
 #include "d4includes.h"
 #include "d4curlfunctions.h"
 

libdap4/d4curlfunctions.c

@@ -3,6 +3,15 @@
  *   See netcdf/COPYRIGHT file for copying and redistribution conditions.
  *********************************************************************/
 
+/** @file d4curlfunctions.c
+ * @brief libcurl session management for the DAP4 client.
+ *
+ * Implements NCD4_curlopen(), NCD4_curlclose(), and the helpers that
+ * configure authentication, proxy, SSL, and keepalive options on a
+ * CURL easy handle.  Parallel to oc2/occurlfunctions.c.
+ * @author Dennis Heimbigner
+ */
+
 /* WARNING: oc2/occurlfunctions.c and libdap4/d4curlfunctions.c
 should be merged since they are essentially the same file.
 In the meantime, changes to one should be propagated to the other.

libdap4/d4curlfunctions.h

@@ -3,36 +3,55 @@
   *   See netcdf/COPYRIGHT file for copying and redistribution conditions.
   *********************************************************************/
 
+/** @file d4curlfunctions.h
+ * @brief libcurl option management for the DAP4 client.
+ *
+ * Declares the CURLFLAG table type and the functions that apply
+ * per-fetch and per-link CURLOPT settings to a DAP4 connection.
+ * @author Dennis Heimbigner
+ */
+
 #ifndef D4CURLFUNCTIONS_H
 #define D4CURLFUNCTIONS_H
 
-/* Aliases to older names */
+/* Aliases to older libcurl option names */
 #ifndef HAVE_CURLOPT_KEYPASSWD
-#define CURLOPT_KEYPASSWD CURLOPT_SSLKEYPASSWD
+#define CURLOPT_KEYPASSWD CURLOPT_SSLKEYPASSWD /**< Compatibility alias for older libcurl. */
 #endif
 #ifndef HAVE_CURLINFO_RESPONSE_CODE
-#define CURLINFO_RESPONSE_CODE CURLINFO_HTTP_CODE
+#define CURLINFO_RESPONSE_CODE CURLINFO_HTTP_CODE /**< Compatibility alias for older libcurl. */
 #endif
 
-enum CURLFLAGTYPE {CF_UNKNOWN=0,CF_OTHER=1,CF_STRING=2,CF_LONG=3};
+/** Classification of a CURLFLAG value type. */
+enum CURLFLAGTYPE {CF_UNKNOWN=0, CF_OTHER=1, CF_STRING=2, CF_LONG=3};
+
+/** Descriptor for one named libcurl option flag. */
 struct CURLFLAG {
-    const char* name;
-    int flag;
-    int value;
-    enum CURLFLAGTYPE type;
+    const char* name;       /**< Human-readable option name string. */
+    int flag;               /**< CURLOPT_* constant value. */
+    int value;              /**< Default numeric value (for CF_LONG flags). */
+    enum CURLFLAGTYPE type; /**< Value type of this option. */
 };
 
+/** Set a single CURLOPT on @p state->curl->curl. */
 extern ncerror NCD4_set_curlopt(NCD4INFO* state, int flag, void* value);
 
-extern ncerror NCD4_set_flags_perfetch(NCD4INFO*);
-extern ncerror NCD4_set_flags_perlink(NCD4INFO*);
+/** Apply all per-fetch CURLOPT settings (called before each HTTP request). */
+extern ncerror NCD4_set_flags_perfetch(NCD4INFO* state);
+/** Apply all per-link CURLOPT settings (called once when the handle is opened). */
+extern ncerror NCD4_set_flags_perlink(NCD4INFO* state);
 
-extern ncerror NCD4_set_curlflag(NCD4INFO*,int);
+/** Apply one named curl flag from the CURLFLAG table to @p state. */
+extern ncerror NCD4_set_curlflag(NCD4INFO* state, int flag);
 
+/** Enable verbose libcurl debug output for @p state. */
 extern void NCD4_curl_debug(NCD4INFO* state);
 
+/** Look up a CURLFLAG descriptor by option name string. */
 extern struct CURLFLAG* NCD4_curlflagbyname(const char* name);
-extern void NCD4_curl_protocols(NCD4INFO*);
+/** Configure the allowed protocols on @p state's curl handle. */
+extern void NCD4_curl_protocols(NCD4INFO* state);
+/** Read RC-file properties and apply them to @p state. */
 extern ncerror NCD4_get_rcproperties(NCD4INFO* state);
 
 #endif /*D4CURLFUNCTIONS_H*/

libdap4/d4cvt.c

@@ -2,6 +2,16 @@
  *   Copyright 2018, UCAR/Unidata
  *   See netcdf/COPYRIGHT file for copying and redistribution conditions.
  *********************************************************************/
+
+/** @file d4cvt.c
+ * @brief DAP4 type-conversion utility.
+ *
+ * Implements NCD4_convert(), which converts an array of values from
+ * one nc_type to another.  Used when the server returns data in a
+ * wider type than the variable's declared type.
+ * @author Dennis Heimbigner
+ */
+
 #include "config.h"
 #include <assert.h>
 #include "netcdf.h"
@@ -17,7 +27,21 @@ Code taken directly from libdap4/dapcvt.c
 /* Forward */
 static size_t nctypesizeof(nc_type nctype);
 
-
+/**
+ * Convert @p count values from @p srctype to @p dsttype in place.
+ *
+ * Reads each value from @p value0, converts it to @p dsttype while
+ * preserving the bit pattern where possible, and writes the result
+ * to @p memory0.  Used to handle DAP4 type-upgrade situations where
+ * the server sends a wider type than the variable's declared type.
+ *
+ * @param srctype  Source nc_type.
+ * @param dsttype  Destination nc_type.
+ * @param memory0  Destination buffer (receives converted values).
+ * @param value0   Source buffer.
+ * @param count    Number of values to convert.
+ * @return NC_NOERR on success, or a netCDF error code.
+ */
 int
 NCD4_convert(nc_type srctype, nc_type dsttype, char* memory0, char* value0, size_t count)
 {

libdap4/d4data.c

@@ -3,6 +3,16 @@
  *   See netcdf/COPYRIGHT file for copying and redistribution conditions.
  *********************************************************************/
 
+/** @file d4data.c
+ * @brief DAP4 data pre-processing and conversion to NetCDF-4 memory layout.
+ *
+ * Implements NCD4_processdata() (endian swap + checksum verification),
+ * NCD4_parcelvars() (assigns each variable's slice in the dechunked
+ * buffer), NCD4_movetoinstance() (copies one type instance into
+ * NetCDF-4 memory), and NCD4_getToplevelVars().
+ * @author Dennis Heimbigner
+ */
+
 #include "d4includes.h"
 #include <stdarg.h>
 #include <assert.h>
@@ -84,7 +94,18 @@ NCD4_parcelvars(NCD4meta* meta, NCD4response* resp)
     return THROW(ret);
 }
 
-/* Process top level vars wrt checksums and swapping */
+/**
+ * Pre-process the dechunked DAP data (endian swap + checksum verification).
+ *
+ * For each top-level variable: byte-swaps multi-byte scalars if the
+ * server's endianness differs from the host's, then verifies the
+ * embedded CRC32 checksum against a locally computed value when
+ * checksumming is enabled.
+ *
+ * @param meta Metadata object with the parsed DMR tree.
+ * @param resp Response object with dechunked DAP data.
+ * @return NC_NOERR on success, or a netCDF error code.
+ */
 int
 NCD4_processdata(NCD4meta* meta, NCD4response* resp)
 {

libdap4/d4debug.c

@@ -2,6 +2,16 @@
  *   Copyright 2018, UCAR/Unidata
  *   See netcdf/COPYRIGHT file for copying and redistribution conditions.
  *********************************************************************/
+
+/** @file d4debug.c
+ * @brief Debug and panic utilities for the DAP4 client.
+ *
+ * Implements d4panic(), NCD4_sortname(), NCD4_subsortname(),
+ * NCD4_debugcopy(), and (when D4CATCH is defined) d4breakpoint()
+ * and d4throw().
+ * @author Dennis Heimbigner
+ */
+
 #include "config.h"
 #include <stdarg.h>
 #include <stddef.h>