From bc125f81c50167284200e6252a9dbf4dea07ed13 Mon Sep 17 00:00:00 2001
From: Ed Hartnett <edwardjameshartnett@gmail.com>
Date: Wed, 17 Jul 2019 10:55:23 -0600
Subject: [PATCH] more docs

---
 src/ncint/ncintdispatch.c | 59 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)

diff --git a/src/ncint/ncintdispatch.c b/src/ncint/ncintdispatch.c
index b1a041f1bae..e552be311a5 100644
--- a/src/ncint/ncintdispatch.c
+++ b/src/ncint/ncintdispatch.c
@@ -111,6 +111,10 @@ NC_Dispatch NCINT_dispatcher = {
     NC_NOTNC4_get_var_chunk_cache
 };
 
+/**
+ * Pointer to the dispatch table used for netCDF/PIO
+ * integration. Files opened or created with mode flag NC_UDF0 will be
+ * opened using the functions in this dispatch table. */
 const NC_Dispatch* NCINT_dispatch_table = NULL;
 
 /**
@@ -151,6 +155,17 @@ PIO_NCINT_finalize(void)
 /**
  * Create a file using PIO via netCDF's nc_create().
  *
+ * @param path The file name of the new file.
+ * @param cmode The creation mode flag.
+ * @param initialsz Ignored by this function.
+ * @param basepe Ignored by this function.
+ * @param chunksizehintp Ignored by this function.
+ * @param parameters pointer to struct holding extra data (e.g. for
+ * parallel I/O) layer. Ignored if NULL.
+ * @param dispatch Pointer to the dispatch table for this file.
+ * @param nc_file Pointer to an already-existing instance of NC.
+ *
+ * @return ::NC_NOERR No error, or error code.
  * @author Ed Hartnett
  */
 int
@@ -188,6 +203,25 @@ PIO_NCINT_create(const char *path, int cmode, size_t initialsz, int basepe,
     return PIO_NOERR;
 }
 
+/**
+ * @internal Open a netCDF file with PIO.
+ *
+ * @param path The file name of the file.
+ * @param mode The open mode flag.
+ * @param basepe Ignored by this function.
+ * @param chunksizehintp Ignored by this function.
+ * @param parameters pointer to struct holding extra data (e.g. for
+ * parallel I/O) layer. Ignored if NULL. Ignored by this function.
+ * @param dispatch Pointer to the dispatch table for this file.
+ * @param nc_file Pointer to an instance of NC. The ncid has already
+ * been assigned, and is in nc_file->ext_ncid.
+ *
+ * @return ::NC_NOERR No error.
+ * @return ::NC_EINVAL Invalid input.
+ * @return ::NC_EHDFERR Error from HDF4 layer.
+ * @return ::NC_ENOMEM Out of memory.
+ * @author Ed Hartnett
+ */
 int
 PIO_NCINT_open(const char *path, int mode, int basepe, size_t *chunksizehintp,
                void *parameters, const NC_Dispatch *dispatch, NC *nc_file)
@@ -326,6 +360,17 @@ PIO_NCINT_set_fill(int ncid, int fillmode, int *old_modep)
     return PIOc_set_fill(ncid, fillmode, old_modep);
 }
 
+/**
+ * @internal Get the format (i.e. NC_FORMAT_UDF0) of a file opened
+ * with PIO.
+ *
+ * @param ncid File ID (ignored).
+ * @param formatp Pointer that gets the constant indicating format.
+
+ * @return ::NC_NOERR No error.
+ * @return ::NC_EBADID Bad ncid.
+ * @author Ed Hartnett
+ */
 int
 PIO_NCINT_inq_format(int ncid, int *formatp)
 {
@@ -336,6 +381,20 @@ PIO_NCINT_inq_format(int ncid, int *formatp)
     return NC_NOERR;
 }
 
+/**
+ * @internal Return the extended format (i.e. the dispatch model),
+ * plus the mode associated with an open file.
+ *
+ * @param ncid File ID.
+ * @param formatp a pointer that gets the extended format. PIO files
+ * will always get NC_FORMATX_UDF0.
+ * @param modep a pointer that gets the open/create mode associated with
+ * this file. Ignored if NULL.
+
+ * @return ::NC_NOERR No error.
+ * @return ::NC_EBADID Bad ncid.
+ * @author Ed Hartnett
+ */
 int
 PIO_NCINT_inq_format_extended(int ncid, int *formatp, int *modep)
 {