More unit tests for nc4internal.c, also doxygen docs for nc4internal.h

RELEASE_NOTES.md

@@ -7,18 +7,24 @@ This file contains a high-level description of this package's evolution. Release
 
 ## 4.7.1 - TBD
 
+* [Enhancement] Added unit_test directory, which contains unit tests
+for the libdispatch and libsrc4 code (and any other directories that
+want to put unit tests there). Use --disable-unit-tests to run without
+unit tests (ex. for code coverage analysis).
+See [GitHub #1458](https://github.com/Unidata/netcdf-c/issues/1458)
+
 * [Bug Fix] Remove obsolete _CRAYMPP and LOCKNUMREC macros from
 code. Also brought documentation up to date in man page. These macros
 were used in ancient times, before modern parallel I/O systems were
 developed. Programmers interested in parallel I/O should see
 nc_open_par() and nc_create_par().
-See [GitHub #1436](https://github.com/Unidata/netcdf-c/issues/1459)
+See [GitHub #1459](https://github.com/Unidata/netcdf-c/issues/1459)
 
 * [Enhancement] Remove obsolete and deprecated functions
 nc_set_base_pe() and nc_inq_base_pe() from the dispatch table. (Both
 functions are still supported in the library, this is an internal
 change only.)
-See [GitHub #1436](https://github.com/Unidata/netcdf-c/issues/1468)
+See [GitHub #1468](https://github.com/Unidata/netcdf-c/issues/1468)
 
 * [Bug Fix] Reverted nccopy behavior so that if no -c parameters
 are given, then any default chunking is left to the netcdf-c library

libdispatch/nc.c

@@ -68,10 +68,11 @@ free_NC(NC *ncp)
 /**
  * Create and initialize a new NC struct. The ncid is assigned later.
  *
- * @param dispatcher
+ * @param dispatcher An pointer to the NC_Dispatch table that should
+ * be used by this NC.
  * @param path The name of the file.
  * @param mode The open or create mode.
- * @param model
+ * @param model An NCmodel instance, provided by NC_infermodel().
  * @param ncpp A pointer that gets a pointer to the newlly allocacted
  * and initialized NC struct.
  *

libsrc4/nc4internal.c

@@ -89,7 +89,7 @@ nc4_check_name(const char *name, char *norm_name)
  * nc4_nc4f_list_add(), except it takes an ncid instead of an NC *,
  * and also passes back the dispatchdata pointer.
  *
- * @param ncid The ncid of the file (aka ext_ncid).
+ * @param ncid The (already-assigned) ncid of the file (aka ext_ncid).
  * @param path The file name of the new file.
  * @param mode The mode flag.
  * @param dispatchdata Void * that gets pointer to dispatch data,
@@ -125,10 +125,35 @@ nc4_file_list_add(int ncid, const char *path, int mode, void **dispatchdata)
     return NC_NOERR;
 }
 
+/* /\** */
+/*  * @internal Change the ncid of an open file. This is needed for PIO */
+/*  * integration. */
+/*  * */
+/*  * @param ncid The ncid of the file (aka ext_ncid). */
+/*  * @param new_ncid The new ncid to use. */
+/*  * */
+/*  * @return ::NC_NOERR No error. */
+/*  * @return ::NC_EBADID No NC struct with this ext_ncid. */
+/*  * @return ::NC_ENOMEM Out of memory. */
+/*  * @author Ed Hartnett */
+/*  *\/ */
+/* int */
+/* nc4_file_change_ncid(int ncid, int new_ncid) */
+/* { */
+/*     NC *nc; */
+/*     int ret; */
+
+/*     /\* Find NC pointer for this file. *\/ */
+/*     if ((ret = NC_check_id(ncid, &nc))) */
+/*         return ret; */
+
+/*     return NC_NOERR; */
+/* } */
+
 /**
- * @internal Get info about a file on the list of libsrc4 open files. This is
- * used by dispatch layers that wish to use the libsrc4 metadata
- * model, but don't know about struct NC.
+ * @internal Get info about a file on the list of libsrc4 open
+ * files. This is used by dispatch layers that wish to use the libsrc4
+ * metadata model, but don't know about struct NC.
  *
  * @param ncid The ncid of the file (aka ext_ncid).
  * @param path A pointer that gets file name (< NC_MAX_NAME). Igored
@@ -212,7 +237,7 @@ nc4_nc4f_list_add(NC *nc, const char *path, int mode)
 
     /* There's always at least one open group - the root
      * group. Allocate space for one group's worth of information. Set
-     * its hdf id, name, and a pointer to it's file structure. */
+     * its grp id, name, and allocate associated empty lists. */
     if ((retval = nc4_grp_list_add(h5, NULL, NC_GROUP_NAME, &h5->root_grp)))
         return retval;
 

unit_test/Makefile.am

@@ -14,8 +14,12 @@ include $(top_srcdir)/lib_flags.am
 # Find and link to the netcdf-c library.
 LDADD = ${top_builddir}/liblib/libnetcdf.la
 
-check_PROGRAMS = tst_nclist
-TESTS = tst_nclist
+if USE_NETCDF4
+NC4_TESTS = tst_nc4internal
+endif # USE_NETCDF4
+
+check_PROGRAMS = tst_nclist $(NC4_TESTS)
+TESTS = tst_nclist $(NC4_TESTS)
 
 # If valgrind is present, add valgrind targets.
 @VALGRIND_CHECK_RULES@