Merge pull request ESMCI#1447 from NCAR/ejh_try_3

documentation fix for --enable-developer-docs
rfiorella · May 24, 2019 · 167d331 · 167d331
2 parents abb1339 + 5188bc5
commit 167d331
Show file tree

Hide file tree

Showing 7 changed files with 67 additions and 52 deletions.
diff --git a/configure.ac b/configure.ac
@@ -132,13 +132,11 @@ if test "x$enable_docs" = xyes; then
    if test "x$enable_fortran" = xno; then
       AC_MSG_ERROR([--enable-fortran is required for documentation builds.])
    fi
+   AC_SUBST([FORTRAN_SRC_FILES], ["../src/flib/piodarray.f90  ../src/flib/pio.F90  ../src/flib/pio_kinds.F90  ../src/flib/piolib_mod.f90  ../src/flib/pionfatt_mod_2.f90  ../src/flib/pio_nf.F90  ../src/flib/pionfget_mod_2.f90  ../src/flib/pionfput_mod.f90  ../src/flib/pio_support.F90  ../src/flib/pio_types.F90"])
    if test "x$enable_developer_docs" = xyes; then
       AC_SUBST([C_SRC_FILES], ["../src/clib"])
-      AC_SUBST([FORTRAN_SRC_FILES], ["../src/flib"])
    else
       AC_SUBST([C_SRC_FILES], ["../src/clib/pio_nc.c ../src/clib/pio_nc4.c ../src/clib/pio_darray.c ../src/clib/pio_get_nc.c ../src/clib/pio_put_nc.c ../src/clib/pioc_support.c ../src/clib/pioc.c ../src/clib/pio_file.c ../src/clib/pio.h"])
-      AC_SUBST([FORTRAN_SRC_FILES], ["../src/flib/piodarray.f90  ../src/flib/pio.F90  ../src/flib/pio_kinds.F90  ../src/flib/piolib_mod.f90  ../src/flib/pionfatt_mod_2.f90  ../src/flib/pio_nf.F90  ../src/flib/pionfget_mod_2.f90  ../src/flib/pionfput_mod.f90  ../src/flib/pio_support.F90  ../src/flib/pio_types.F90"])
-#      AC_SUBST([FORTRAN_SRC_FILES], ["../src/flib/pio_types.F90 ../src/flib/piodarray.F90 ../src/flib/piolib_mod.F90 ../src/flib/pio_nf.F90"])
    fi
    AC_CONFIG_FILES([doc/Doxyfile])
 fi

diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in
@@ -817,6 +817,7 @@ RECURSIVE              = YES
 EXCLUDE                = gptl \
 		         @CMAKE_BINARY_DIR@/src/flib/*.dir \
 		         @CMAKE_BINARY_DIR@/src/flib/genf90 \
+       		         ../src/clib/uthash.h \
                          _UNUSED_
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or

diff --git a/doc/Makefile.am b/doc/Makefile.am
@@ -3,12 +3,13 @@
 # Ed Hartnett 4/1/19
 
 # Run doxygen, then confirm warning log file is empty.
-check: all
 all:
 	doxygen Doxyfile
 	cat doxywarn.log
 	[ ! -s doxywarn.log ]
 
+check: all
+
 SUBDIRS = source
 
 CLEANFILES = *.log

diff --git a/src/clib/pio_darray_int.c b/src/clib/pio_darray_int.c
@@ -1,4 +1,5 @@
-/** @file
+/**
+ * @file
  *
  * Private functions to help read and write distributed arrays in PIO.
  *
@@ -388,7 +389,8 @@ find_start_count(int ndims, int fndims, var_desc_t *vdesc,
  * that will be written to
  * @param nvars the number of variables to be written with this
  * decomposition.
- * @param vid: an array of the variable ids to be written.
+ * @param fndims number of dimensions of this var in the file.
+ * @param varids an array of the variable ids to be written.
  * @param iodesc pointer to the io_desc_t info.
  * @param fill Non-zero if this write is fill data.
  * @param frame the record dimension for each of the nvars variables
@@ -1047,6 +1049,7 @@ recv_and_write_data(file_desc_t *file, const int *varids, const int *frame,
  * that will be written to.
  * @param nvars the number of variables to be written with this
  * decomposition.
+ * @param fndims number of dims in the vars in the file.
  * @param varids an array of the variable ids to be written
  * @param iodesc pointer to the decomposition info.
  * @param fill Non-zero if this write is fill data.

diff --git a/src/clib/pio_internal.h b/src/clib/pio_internal.h
@@ -94,17 +94,17 @@ extern "C" {
     /** Used to sort map points in the subset rearranger. */
     typedef struct mapsort
     {
-        int rfrom;
-        PIO_Offset soffset;
-        PIO_Offset iomap;
+        int rfrom; /**< from */
+        PIO_Offset soffset; /**< ??? */
+        PIO_Offset iomap; /**< ??? */
     } mapsort;
 
     /** swapm defaults. */
     typedef struct pio_swapm_defaults
     {
-        int nreqs;
-        bool handshake;
-        bool isend;
+        int nreqs; /**< number of requests */
+        bool handshake; /**< handshake */
+        bool isend; /**< is end? */
     } pio_swapm_defaults;
 
     /* Handle an error in the PIO library. */
@@ -361,7 +361,7 @@ extern "C" {
     int pio_sorted_copy(const void *array, void *tmparray, io_desc_t *iodesc, int nvars, int direction);
 
     int PIOc_inq_att_eh(int ncid, int varid, const char *name, int eh,
-			nc_type *xtypep, PIO_Offset *lenp);
+                        nc_type *xtypep, PIO_Offset *lenp);
 #if defined(__cplusplus)
 }
 #endif

diff --git a/src/clib/pio_msg.c b/src/clib/pio_msg.c
@@ -425,7 +425,6 @@ int inq_dimid_handler(iosystem_desc_t *ios)
  * tasks.
  *
  * @param ios pointer to the iosystem_desc_t.
- * @param msg the message sent my the comp root task.
  * @returns 0 for success, PIO_EIO for MPI Bcast errors, or error code
  * from netCDF base function.
  * @internal
@@ -477,7 +476,6 @@ int inq_att_handler(iosystem_desc_t *ios)
  * tasks.
  *
  * @param ios pointer to the iosystem_desc_t.
- * @param msg the message sent my the comp root task.
  * @returns 0 for success, PIO_EIO for MPI Bcast errors, or error code
  * from netCDF base function.
  * @internal
@@ -522,7 +520,6 @@ int inq_attname_handler(iosystem_desc_t *ios)
  * tasks.
  *
  * @param ios pointer to the iosystem_desc_t.
- * @param msg the message sent my the comp root task.
  * @returns 0 for success, PIO_EIO for MPI Bcast errors, or error code
  * from netCDF base function.
  * @internal
@@ -569,7 +566,6 @@ int inq_attid_handler(iosystem_desc_t *ios)
 /** Handle attribute operations. This code only runs on IO tasks.
  *
  * @param ios pointer to the iosystem_desc_t.
- * @param msg the message sent my the comp root task.
  * @returns 0 for success, PIO_EIO for MPI Bcast errors, or error code
  * from netCDF base function.
  * @internal
@@ -638,7 +634,6 @@ int att_put_handler(iosystem_desc_t *ios)
 /** Handle attribute operations. This code only runs on IO tasks.
  *
  * @param ios pointer to the iosystem_desc_t.
- * @param msg the message sent my the comp root task.
  * @returns 0 for success, PIO_EIO for MPI Bcast errors, or error code
  * from netCDF base function.
  * @internal
@@ -1413,6 +1408,7 @@ int advanceframe_handler(iosystem_desc_t *ios)
  * This function is run on the IO tasks to enddef a netCDF file.
  *
  * @param ios pointer to the iosystem_desc_t.
+ * @param msg the message sent my the comp root task.
  * @returns 0 for success, PIO_EIO for MPI Bcast errors, or error code
  * from netCDF base function.
  * @internal

diff --git a/src/clib/pio_rearrange.c b/src/clib/pio_rearrange.c
@@ -1,4 +1,5 @@
-/** @file
+/**
+ * @file
  * Code to map IO to model decomposition.
  *
  * @author Jim Edwards
@@ -30,7 +31,7 @@
  * @author Jim Edwards
  */
 inline void idx_to_dim_list(int ndims, const int *gdimlen, PIO_Offset idx,
-                     PIO_Offset *dim_list)
+                            PIO_Offset *dim_list)
 {
     /* Check inputs. */
     pioassert(ndims >= 0 && gdimlen && idx >= -1 && dim_list, "invalid input",
@@ -549,7 +550,7 @@ int compute_counts(iosystem_desc_t *ios, io_desc_t *iodesc,
 
     /* Check inputs. */
     pioassert(ios && iodesc && (iodesc->ndof == 0 ||
-	     (iodesc->ndof > 0 && dest_ioproc && dest_ioindex)) &&
+                                (iodesc->ndof > 0 && dest_ioproc && dest_ioindex)) &&
               iodesc->rearranger == PIO_REARR_BOX && ios->num_uniontasks > 0,
               "invalid input", __FILE__, __LINE__);
     LOG((1, "compute_counts ios->num_uniontasks = %d ios->compproc %d ios->ioproc %d",
@@ -566,8 +567,8 @@ int compute_counts(iosystem_desc_t *ios, io_desc_t *iodesc,
     PIO_Offset *s2rindex = NULL;
     if (iodesc->ndof > 0)
     {
-	if (!(s2rindex = malloc(sizeof(PIO_Offset) * iodesc->ndof)))
-	    return pio_err(ios, NULL, PIO_ENOMEM, __FILE__, __LINE__);
+        if (!(s2rindex = malloc(sizeof(PIO_Offset) * iodesc->ndof)))
+            return pio_err(ios, NULL, PIO_ENOMEM, __FILE__, __LINE__);
     }
     /* Allocate memory for the array of counts and init to zero. */
     if (!(iodesc->scount = calloc(ios->num_iotasks, sizeof(int))))
@@ -920,30 +921,30 @@ int rearrange_comp2io(iosystem_desc_t *ios, io_desc_t *iodesc, void *sbuf,
      * each exchange.  */
     if(!ios->async || ios->compproc)
     {
-	for (int i = 0; i < niotasks; i++)
+        for (int i = 0; i < niotasks; i++)
         {
             int io_comprank = ios->ioranks[i];
             LOG((3, "ios->ioranks[%d] = %d", i, ios->ioranks[i]));
             if (iodesc->rearranger == PIO_REARR_SUBSET)
                 io_comprank = 0;
 
-	    LOG((3, "i = %d iodesc->scount[i] = %d", i, iodesc->scount[i]));
-	    if (iodesc->scount[i] > 0 && sbuf)
-	    {
-		LOG((3, "io task %d creating sendtypes[%d]", i, io_comprank));
-		sendcounts[io_comprank] = 1;
-		if ((mpierr = MPI_Type_create_hvector(nvars, 1, (MPI_Aint)iodesc->ndof * iodesc->mpitype_size,
-						      iodesc->stype[i], &sendtypes[io_comprank])))
-		    return check_mpi(NULL, NULL, mpierr, __FILE__, __LINE__);
-		pioassert(sendtypes[io_comprank] != PIO_DATATYPE_NULL,  "bad mpi type", __FILE__, __LINE__);
-
-		if ((mpierr = MPI_Type_commit(&sendtypes[io_comprank])))
-		    return check_mpi(NULL, NULL, mpierr, __FILE__, __LINE__);
-	    }
-	    else
-	    {
-		sendcounts[io_comprank] = 0;
-	    }
+            LOG((3, "i = %d iodesc->scount[i] = %d", i, iodesc->scount[i]));
+            if (iodesc->scount[i] > 0 && sbuf)
+            {
+                LOG((3, "io task %d creating sendtypes[%d]", i, io_comprank));
+                sendcounts[io_comprank] = 1;
+                if ((mpierr = MPI_Type_create_hvector(nvars, 1, (MPI_Aint)iodesc->ndof * iodesc->mpitype_size,
+                                                      iodesc->stype[i], &sendtypes[io_comprank])))
+                    return check_mpi(NULL, NULL, mpierr, __FILE__, __LINE__);
+                pioassert(sendtypes[io_comprank] != PIO_DATATYPE_NULL,  "bad mpi type", __FILE__, __LINE__);
+
+                if ((mpierr = MPI_Type_commit(&sendtypes[io_comprank])))
+                    return check_mpi(NULL, NULL, mpierr, __FILE__, __LINE__);
+            }
+            else
+            {
+                sendcounts[io_comprank] = 0;
+            }
         }
     }
 
@@ -1339,8 +1340,8 @@ int box_rearrange_create(iosystem_desc_t *ios, int maplen, const PIO_Offset *com
      * I/O task
      */
     for(int i=0; i<ios->num_uniontasks; i++){
-      sendcounts[i] = 0;
-      sdispls[i] = 0;
+        sendcounts[i] = 0;
+        sdispls[i] = 0;
     }
     if(ios->ioproc){
         /* Only I/O procs send sc_info messages */
@@ -1394,10 +1395,10 @@ int box_rearrange_create(iosystem_desc_t *ios, int maplen, const PIO_Offset *com
             PIO_Offset *start = &(sc_info_msg_recv[i * sc_info_msg_sz + 1]);
             PIO_Offset *count = &(sc_info_msg_recv[i * sc_info_msg_sz + 1 + ndims]);
 
-  #if PIO_ENABLE_LOGGING
+#if PIO_ENABLE_LOGGING
             for (int d = 0; d < ndims; d++)
                 LOG((3, "start[%d] = %lld count[%d] = %lld", d, start[d], d, count[d]));
-  #endif /* PIO_ENABLE_LOGGING */
+#endif /* PIO_ENABLE_LOGGING */
 
             /* For each element of the data array on the compute task,
              * find the IO task to send the data element to, and its
@@ -1484,11 +1485,26 @@ int box_rearrange_create(iosystem_desc_t *ios, int maplen, const PIO_Offset *com
 }
 
 
-/* The box_rearrange_create algorithm optimized for the case where many
+/**
+ * The box_rearrange_create algorithm optimized for the case where many
  * iotasks have iomaplen == 0 (holes)
+ *
+ * @param ios pointer to the iosystem_desc_t struct.
+ * @param maplen the length of the map.
+ * @param compmap a 1 based array of offsets into the global space. A
+ * 0 in this array indicates a value which should not be transfered.
+ * @param gdimlen an array length ndims with the sizes of the global
+ * dimensions.
+ * @param ndims the number of dimensions.
+ * @param iodesc a pointer to the io_desc_t struct, which must be
+ * allocated before this function is called.
+ * @returns 0 on success, error code otherwise.
+ * @author Jim Edwards
  */
-int box_rearrange_create_with_holes(iosystem_desc_t *ios, int maplen, const PIO_Offset *compmap,
-                         const int *gdimlen, int ndims, io_desc_t *iodesc)
+int box_rearrange_create_with_holes(iosystem_desc_t *ios, int maplen,
+                                    const PIO_Offset *compmap,
+                                    const int *gdimlen, int ndims,
+                                    io_desc_t *iodesc)
 {
     int ret;
 
@@ -2318,7 +2334,7 @@ int subset_rearrange_create(iosystem_desc_t *ios, int maplen, PIO_Offset *compma
 
         /* Get the max maxholegridsize, and distribute it to all tasks
          * in the IO communicator. */
-	iodesc->maxholegridsize = iodesc->holegridsize;
+        iodesc->maxholegridsize = iodesc->holegridsize;
         if ((mpierr = MPI_Allreduce(MPI_IN_PLACE, &(iodesc->maxholegridsize), 1, MPI_INT,
                                     MPI_MAX, ios->io_comm)))
             return check_mpi(NULL, NULL, mpierr, __FILE__, __LINE__);
@@ -2384,10 +2400,10 @@ void performance_tune_rearranger(iosystem_desc_t *ios, io_desc_t *iodesc)
 
     assert(iodesc);
     if(iodesc->mpitype == MPI_DATATYPE_NULL)
-	tsize = 0;
+        tsize = 0;
     else
-	if ((mpierr = MPI_Type_size(iodesc->mpitype, &tsize)))
-	    return check_mpi(NULL, NULL, mpierr, __FILE__, __LINE__);
+        if ((mpierr = MPI_Type_size(iodesc->mpitype, &tsize)))
+            return check_mpi(NULL, NULL, mpierr, __FILE__, __LINE__);
     cbuf = NULL;
     ibuf = NULL;
     if (iodesc->ndof > 0)