Merge pull request ESMCI#1438 from NCAR/ejh_docs_5

more documentation fixes
rfiorella · May 20, 2019 · 2c20802 · 2c20802
2 parents 298090c + d6acd33
commit 2c20802
Show file tree

Hide file tree

Showing 13 changed files with 252 additions and 197 deletions.
diff --git a/configure.ac b/configure.ac
@@ -128,12 +128,16 @@ fi
 if test "x$enable_docs" = xyes; then
    AC_SUBST([CMAKE_CURRENT_SOURCE_DIR], ["."])
    AC_SUBST([CMAKE_BINARY_DIR], [".."])
+   if test "x$enable_fortran" = xno; then
+      AC_MSG_ERROR([--enable-fortran is required for documentation builds.])
+   fi
    if test "x$enable_developer_docs" = xyes; then
-   AC_SUBST([C_SRC_FILES], ["../src/clib"])
-   AC_SUBST([FORTRAN_SRC_FILES], ["../src/flib"])
+      AC_SUBST([C_SRC_FILES], ["../src/clib"])
+      AC_SUBST([FORTRAN_SRC_FILES], ["../src/flib"])
    else
-   AC_SUBST([C_SRC_FILES], ["../src/clib/pio_nc4.c ../src/clib/pio_darray.c ../src/clib/pio_get_nc.c ../src/clib/pio_put_nc.c"])
-   AC_SUBST([FORTRAN_SRC_FILES], ["../src/flib/piodarray.F90 ../src/flib/piolib_mod.F90 ../src/flib/pio_nf.F90"])
+      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"])
+#      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/source/contributing_code.txt b/doc/source/contributing_code.txt
@@ -50,7 +50,7 @@ add to it, carefully.
 <li>Use spaces not tabs.
 <li>4 spaces is the unit of intendation.
 <li>Indentation as defined by the "linux" style in emacs (see below).
-<li>Use spaces around most operators (=+-*/) not pointer or prefix/postfile (*++--)
+<li>Use spaces around most operators (= + - * /) not pointer or prefix/postfile (* ++ --)
 <li>Spaces after most keywords (if, for, while, etc.)
 <li>No spaces after function name.
 </ul>
@@ -227,14 +227,14 @@ int PIOc_inq_attname(int ncid, int varid, int attnum, char *name)
     /* If this is an IO task, then call the netCDF function. */
     if (ios->ioproc)
     {
-#ifdef _PNETCDF
+\#ifdef _PNETCDF
         if (file->iotype == PIO_IOTYPE_PNETCDF)
             ierr = ncmpi_inq_attname(file->fh, varid, attnum, name);
-#endif /* _PNETCDF */
-#ifdef _NETCDF
+\#endif /* _PNETCDF */
+\#ifdef _NETCDF
         if (file->iotype != PIO_IOTYPE_PNETCDF && file->do_io)
             ierr = nc_inq_attname(file->fh, varid, attnum, name);
-#endif /* _NETCDF */
+\#endif /* _NETCDF */
         LOG((2, "PIOc_inq_attname netcdf call returned %d", ierr));
     }
 

diff --git a/doc/source/mach_walkthrough.txt b/doc/source/mach_walkthrough.txt
@@ -170,7 +170,7 @@ Download a copy of the PIO source into a sub-directory of your working directory
 
 It is not necessary to edit your .soft file on Mira inorder to build PIO. Execute the following commands to temporarily load packages into your softenv. These packages use the IBM/XL compiler.<br>
   %> soft add +mpiwrapper-xl (or switch from the default in your softenv)<br>
-  %> soft add @ibm-compilers-2015-02<br>
+  %> soft add \@ibm-compilers-2015-02<br>
   %> soft add +cmake<br>
   %> soft add +git<br>
 
@@ -374,7 +374,7 @@ found.
 <pre>cd hdf5-1.10.1
 CC=mpicc ./configure --with-zlib=/usr/local/zlib-1.2.11_mpich-3.2 --with-szlib=/usr/local/szip-2.1_mpich-3.2 --prefix=/usr/local/hdf5-1.10.1_mpich-3.2 --enable-parallel
 make all check
-sudo PATH=$PATH:/usr/local/bin make install
+sudo PATH=$PATH:/usr/local/bin make install</pre>
 
 <li>Installing NetCDF-4 C Library
 

diff --git a/src/clib/pio_nc.c b/src/clib/pio_nc.c
@@ -691,6 +691,7 @@ PIOc_inq_dimlen(int ncid, int dimid, PIO_Offset *lenp)
  *
  * @param ncid the ncid of the open file, obtained from
  * PIOc_openfile() or PIOc_createfile().
+ * @param name pointer taht gets the name of the dimension.
  * @param idp a pointer that will get the id of the variable or attribute.
  * @return PIO_NOERR for success, error code otherwise.  See PIOc_Set_File_Error_Handling
  * @author Jim Edwards, Ed Hartnett
@@ -1974,6 +1975,8 @@ PIOc_redef(int ncid)
  *
  * @param ncid the ncid of the open file, obtained from
  * PIOc_openfile() or PIOc_createfile().
+ * @param name name of the dimension.
+ * @param len length of the dimension.
  * @param idp a pointer that will get the id of the variable or attribute.
  * @return PIO_NOERR for success, error code otherwise.
  * @author Jim Edwards, Ed Hartnett
@@ -2064,8 +2067,11 @@ PIOc_def_dim(int ncid, const char *name, PIO_Offset len, int *idp)
  *
  * @param ncid the ncid of the open file, obtained from
  * PIOc_openfile() or PIOc_createfile().
- * @param varid the variable ID.
- * @param varidp a pointer that will get the variable id
+ * @param name the variable name.
+ * @param xtype the PIO_TYPE of the variable.
+ * @param ndims the number of dimensions.
+ * @param dimidsp pointer to array of dimension IDs.
+ * @param varidp a pointer that will get the variable ID.
  * @return PIO_NOERR for success, error code otherwise.
  * @ingroup PIO_def_var
  * @author Jim Edwards, Ed Hartnett
@@ -3123,7 +3129,6 @@ PIOc_put_att_ushort(int ncid, int varid, const char *name, nc_type xtype,
  * PIOc_openfile() or PIOc_createfile().
  * @param varid the variable ID.
  * @param name the name of the attribute.
- * @param xtype the nc_type of the attribute.
  * @param len the length of the attribute array.
  * @param op a pointer with the attribute data.
  * @return PIO_NOERR for success, error code otherwise.

diff --git a/src/clib/pio_nc4.c b/src/clib/pio_nc4.c
@@ -31,8 +31,9 @@
  * @ingroup PIO_def_var
  * @author Ed Hartnett
  */
-int PIOc_def_var_deflate(int ncid, int varid, int shuffle, int deflate,
-                         int deflate_level)
+int
+PIOc_def_var_deflate(int ncid, int varid, int shuffle, int deflate,
+                     int deflate_level)
 {
     iosystem_desc_t *ios;  /* Pointer to io system information. */
     file_desc_t *file;     /* Pointer to file information. */
@@ -121,8 +122,9 @@ int PIOc_def_var_deflate(int ncid, int varid, int shuffle, int deflate,
  * @ingroup PIO_inq_var
  * @author Ed Hartnett
  */
-int PIOc_inq_var_deflate(int ncid, int varid, int *shufflep, int *deflatep,
-                         int *deflate_levelp)
+int
+PIOc_inq_var_deflate(int ncid, int varid, int *shufflep, int *deflatep,
+                     int *deflate_levelp)
 {
     iosystem_desc_t *ios;  /* Pointer to io system information. */
     file_desc_t *file;     /* Pointer to file information. */
@@ -231,7 +233,8 @@ int PIOc_inq_var_deflate(int ncid, int varid, int *shufflep, int *deflatep,
  * @return PIO_NOERR for success, otherwise an error code.
  * @author Ed Hartnett
  */
-int PIOc_def_var_chunking(int ncid, int varid, int storage, const PIO_Offset *chunksizesp)
+int
+PIOc_def_var_chunking(int ncid, int varid, int storage, const PIO_Offset *chunksizesp)
 {
     iosystem_desc_t *ios;  /* Pointer to io system information. */
     file_desc_t *file;     /* Pointer to file information. */
@@ -353,7 +356,8 @@ int PIOc_def_var_chunking(int ncid, int varid, int storage, const PIO_Offset *ch
  * @ingroup PIO_inq_var
  * @author Ed Hartnett
  */
-int PIOc_inq_var_chunking(int ncid, int varid, int *storagep, PIO_Offset *chunksizesp)
+int
+PIOc_inq_var_chunking(int ncid, int varid, int *storagep, PIO_Offset *chunksizesp)
 {
     iosystem_desc_t *ios;  /* Pointer to io system information. */
     file_desc_t *file;     /* Pointer to file information. */
@@ -485,7 +489,8 @@ int PIOc_inq_var_chunking(int ncid, int varid, int *storagep, PIO_Offset *chunks
  * @ingroup PIO_def_var
  * @author Ed Hartnett
  */
-int PIOc_def_var_endian(int ncid, int varid, int endian)
+int
+PIOc_def_var_endian(int ncid, int varid, int endian)
 {
     iosystem_desc_t *ios;  /* Pointer to io system information. */
     file_desc_t *file;     /* Pointer to file information. */
@@ -561,7 +566,8 @@ int PIOc_def_var_endian(int ncid, int varid, int endian)
  * @ingroup PIO_inq_var
  * @author Ed Hartnett
  */
-int PIOc_inq_var_endian(int ncid, int varid, int *endianp)
+int
+PIOc_inq_var_endian(int ncid, int varid, int *endianp)
 {
     iosystem_desc_t *ios;  /* Pointer to io system information. */
     file_desc_t *file;     /* Pointer to file information. */
@@ -653,8 +659,9 @@ int PIOc_inq_var_endian(int ncid, int varid, int *endianp)
  * @ingroup PIO_def_var
  * @author Ed Hartnett
  */
-int PIOc_set_chunk_cache(int iosysid, int iotype, PIO_Offset size, PIO_Offset nelems,
-                         float preemption)
+int
+PIOc_set_chunk_cache(int iosysid, int iotype, PIO_Offset size, PIO_Offset nelems,
+                     float preemption)
 {
     iosystem_desc_t *ios;  /* Pointer to io system information. */
     int ierr;              /* Return code from function calls. */
@@ -753,8 +760,9 @@ int PIOc_set_chunk_cache(int iosysid, int iotype, PIO_Offset size, PIO_Offset ne
  * @ingroup PIO_def_var
  * @author Ed Hartnett
  */
-int PIOc_get_chunk_cache(int iosysid, int iotype, PIO_Offset *sizep, PIO_Offset *nelemsp,
-                         float *preemptionp)
+int
+PIOc_get_chunk_cache(int iosysid, int iotype, PIO_Offset *sizep, PIO_Offset *nelemsp,
+                     float *preemptionp)
 {
     iosystem_desc_t *ios;  /* Pointer to io system information. */
     int ierr;              /* Return code from function calls. */
@@ -872,8 +880,9 @@ int PIOc_get_chunk_cache(int iosysid, int iotype, PIO_Offset *sizep, PIO_Offset
  * @ingroup PIO_def_var
  * @author Ed Hartnett
  */
-int PIOc_set_var_chunk_cache(int ncid, int varid, PIO_Offset size, PIO_Offset nelems,
-                             float preemption)
+int
+PIOc_set_var_chunk_cache(int ncid, int varid, PIO_Offset size, PIO_Offset nelems,
+                         float preemption)
 {
     iosystem_desc_t *ios;  /* Pointer to io system information. */
     file_desc_t *file;     /* Pointer to file information. */
@@ -958,8 +967,9 @@ int PIOc_set_var_chunk_cache(int ncid, int varid, PIO_Offset size, PIO_Offset ne
  * @ingroup PIO_inq_var
  * @author Ed Hartnett
  */
-int PIOc_get_var_chunk_cache(int ncid, int varid, PIO_Offset *sizep, PIO_Offset *nelemsp,
-                             float *preemptionp)
+int
+PIOc_get_var_chunk_cache(int ncid, int varid, PIO_Offset *sizep, PIO_Offset *nelemsp,
+                         float *preemptionp)
 {
     iosystem_desc_t *ios;  /* Pointer to io system information. */
     file_desc_t *file;     /* Pointer to file information. */