more documentation fixes

src/clib/pio.h

@@ -114,10 +114,10 @@
  */
 typedef struct var_desc_t
 {
-    /* Variable ID. */
+    /** Variable ID. */
     int varid;
 
-    /* Non-zero if this is a record var (i.e. uses unlimited
+    /** Non-zero if this is a record var (i.e. uses unlimited
      * dimension). */
     int rec_var;
 
@@ -131,7 +131,7 @@ typedef struct var_desc_t
     /** Number of requests pending with pnetcdf. */
     int nreqs;
 
-    /* Holds the fill value of this var. */
+    /** Holds the fill value of this var. */
     void *fillvalue;
 
     /** Non-zero if fill mode is turned on for this var. */
@@ -153,6 +153,7 @@ typedef struct var_desc_t
     /** The size in bytes of a datum of MPI type mpitype. */
     int mpi_type_size;
 
+    /** Hash table entry. */
     UT_hash_handle hh;
 
 } var_desc_t;
@@ -277,9 +278,10 @@ typedef struct io_desc_t
     PIO_Offset *map;
 
     /** If the map passed in is not monotonically increasing
-     *	then map is sorted and remap is an array of original
+     *  then map is sorted and remap is an array of original
      * indices of map. */
 
+    /** Remap. */
     int *remap;
 
     /** Number of tasks involved in the communication between comp and
@@ -389,6 +391,7 @@ typedef struct io_desc_t
      * group. */
     MPI_Comm subset_comm;
 
+    /** Hash table entry. */
     UT_hash_handle hh;
 
 } io_desc_t;
@@ -537,9 +540,11 @@ typedef struct wmulti_buffer
     /** Pointer to the data. */
     void *data;
 
-  /** uthash handle for hash of buffers **/
-  int htid;
-  UT_hash_handle hh;
+    /** uthash handle for hash of buffers */
+    int htid;
+
+    /** Hash table entry. */
+    UT_hash_handle hh;
 } wmulti_buffer;
 
 /**
@@ -581,7 +586,7 @@ typedef struct file_desc_t
     /** PIO data type. */
     int pio_type;
 
-    /* hash table entry */
+    /** Hash table entry. */
     UT_hash_handle hh;
 
     /** True if this task should participate in IO (only true for one

src/clib/pio_nc.c

@@ -1040,7 +1040,7 @@ PIOc_inq_varnatts(int ncid, int varid, int *nattsp)
  *
  * @param ncid the ncid of the open file, obtained from
  * PIOc_openfile() or PIOc_createfile().
- * @param varid the variable ID.
+ * @param name the variable name.
  * @param varidp a pointer that will get the variable id
  * @return PIO_NOERR for success, error code otherwise.  See PIOc_Set_File_Error_Handling
  * @author Jim Edwards, Ed Hartnett
@@ -1298,6 +1298,7 @@ PIOc_inq_atttype(int ncid, int varid, const char *name, nc_type *xtypep)
  * PIOc_openfile() or PIOc_createfile().
  * @param varid the variable ID.
  * @param attnum the attribute ID.
+ * @param name the name of the attribute.
  * @return PIO_NOERR for success, error code otherwise.  See PIOc_Set_File_Error_Handling
  * @author Jim Edwards, Ed Hartnett
  */
@@ -2278,7 +2279,7 @@ PIOc_def_var(int ncid, const char *name, nc_type xtype, int ndims,
  * @param ncid the ncid of the open file.
  * @param varid the ID of the variable to set chunksizes for.
  * @param fill_mode fill mode for this variable (NC_FILL or NC_NOFILL)
- * @param fill_value pointer to the fill value to be used if fill_mode is set to NC_FILL.
+ * @param fill_valuep pointer to the fill value to be used if fill_mode is set to NC_FILL.
  * @return PIO_NOERR for success, otherwise an error code.
  * @ingroup PIO_def_var
  * @author Jim Edwards, Ed Hartnett

src/clib/pio_nc4.c

@@ -228,7 +228,7 @@ PIOc_inq_var_deflate(int ncid, int varid, int *shufflep, int *deflatep,
  * @param ncid the ncid of the open file.
  * @param varid the ID of the variable to set chunksizes for.
  * @param storage NC_CONTIGUOUS or NC_CHUNKED.
- * @param chunksizep an array of chunksizes. Must have a chunksize for
+ * @param chunksizesp an array of chunksizes. Must have a chunksize for
  * every variable dimension.
  * @return PIO_NOERR for success, otherwise an error code.
  * @author Ed Hartnett
@@ -482,9 +482,7 @@ PIOc_inq_var_chunking(int ncid, int varid, int *storagep, PIO_Offset *chunksizes
  *
  * @param ncid the ncid of the open file.
  * @param varid the ID of the variable to set chunksizes for.
- * @param storage NC_CONTIGUOUS or NC_CHUNKED.
- * @param chunksizep an array of chunksizes. Must have a chunksize for
- * every variable dimension.
+ * @param endian NC_ENDIAN_NATIVE, NC_ENDIAN_LITTLE, or NC_ENDIAN_BIG.
  * @return PIO_NOERR for success, otherwise an error code.
  * @ingroup PIO_def_var
  * @author Ed Hartnett
@@ -651,6 +649,7 @@ PIOc_inq_var_endian(int ncid, int varid, int *endianp)
  * variable documentation</a> for details about the operation of this
  * function.
  *
+ * @param iosysid the IO system ID.
  * @param iotype the iotype of files to be created or opened.
  * @param size size of file cache.
  * @param nelems number of elements in file cache.
@@ -752,6 +751,7 @@ PIOc_set_chunk_cache(int iosysid, int iotype, PIO_Offset size, PIO_Offset nelems
  * attempts to choose sensible chunk sizes by default, but for best
  * performance check chunking against access patterns.
  *
+ * @param iosysid the IO system ID.
  * @param iotype the iotype of files to be created or opened.
  * @param sizep gets the size of file cache.
  * @param nelemsp gets the number of elements in file cache.
@@ -873,9 +873,9 @@ PIOc_get_chunk_cache(int iosysid, int iotype, PIO_Offset *sizep, PIO_Offset *nel
  *
  * @param ncid the ncid of the open file.
  * @param varid the ID of the variable to set chunksizes for.
- * @param storage NC_CONTIGUOUS or NC_CHUNKED.
- * @param chunksizep an array of chunksizes. Must have a chunksize for
- * every variable dimension.
+ * @param size the size in bytes for the cache.
+ * @param nelems the number of elements in the cache.
+ * @param preemption the cache preemption value.
  * @return PIO_NOERR for success, otherwise an error code.
  * @ingroup PIO_def_var
  * @author Ed Hartnett

src/clib/pioc.c

@@ -755,7 +755,7 @@ PIOc_init_decomp(int iosysid, int pio_type, int ndims, const int *gdimlen, int m
  * dimensions.
  * @param start start array
  * @param count count array
- * @param pointer that gets the IO ID.
+ * @param ioidp pointer that gets the IO ID.
  * @returns 0 for success, error code otherwise
  * @ingroup PIO_initdecomp
  * @author Jim Edwards

src/flib/pio_nf.F90

@@ -1057,7 +1057,7 @@ end function inq_vartype_id
 !! @details
 !! @param File @copydoc file_desc_t
 !! @param vardesc @copydoc var_desc_t
-!! @param type : The type of variable
+!! @param natts : The number of atts
 !! @retval ierr @copydoc error_return
 !<
   integer function inq_varnatts_desc(File                   ,vardesc,natts) result(ierr)
@@ -1114,7 +1114,9 @@ end function inq_varnatts_id
 !! @details
 !! @param File @copydoc file_desc_t
 !! @param vardesc @copydoc var_desc_t
-!! @param type : The type of variable
+!! @param shuffle : Value of shuffle
+!! @param deflate : Status of deflate
+!! @param deflate_level : Level of deflate
 !! @retval ierr @copydoc error_return
 !<
   integer function inq_var_deflate_desc(File, vardesc, shuffle, deflate, &

src/flib/pio_types.F90

@@ -15,8 +15,8 @@ module pio_types
 #ifdef SEQUENCE
         sequence
 #endif
-        integer(i4) :: start
-        integer(i4) :: length
+        integer(i4) :: start  !< start
+        integer(i4) :: length !< length
     end type
 
     !------------------------------------
@@ -28,7 +28,7 @@ module pio_types
 !! @brief A defined PIO system descriptor created by @ref PIO_init (see pio_types)
 !<
     type, public :: IOSystem_desc_t
-        integer(kind=c_int) :: iosysid = -1
+        integer(kind=c_int) :: iosysid = -1 !< iosysid
      end type IOSystem_desc_t
 
 !>
@@ -52,8 +52,8 @@ module pio_types
 !!
 !>
     type, public :: File_desc_t
-       integer(kind=c_int) :: fh
-       type(iosystem_desc_t), pointer :: iosystem => null()
+       integer(kind=c_int) :: fh !< file handle
+       type(iosystem_desc_t), pointer :: iosystem => null() !< iosystem
     end type File_desc_t
 
 
@@ -75,7 +75,7 @@ module pio_types
 #ifdef SEQUENCE
         sequence
 #endif
-        integer(i4)         :: ioid
+        integer(i4)         :: ioid !< decomposition id
     end type
 
 !>
@@ -87,8 +87,8 @@ module pio_types
 #ifdef SEQUENCE
        sequence
 #endif
-       integer(i4) :: varID
-       integer(i4) :: ncid
+       integer(i4) :: varID !< variable id
+       integer(i4) :: ncid  !< file id
     end type Var_desc_t
 
 !>
@@ -121,9 +121,8 @@ module pio_types
 !! @details
 !!  - PIO_rearr_none : Do not use any form of rearrangement
 !!  - PIO_rearr_box : Use a PIO internal box rearrangement
-!! -  PIO_rearr_subset : Use a PIO internal subsetting rearrangement
-!>
-
+!!  - PIO_rearr_subset : Use a PIO internal subsetting rearrangement
+!<
     integer(i4), public, parameter :: PIO_rearr_box =  1    !< box rearranger
     integer(i4), public, parameter :: PIO_rearr_subset =  2 !< subset rearranger
 
@@ -277,9 +276,9 @@ module pio_types
 !!                    number of requests use PIO_REARR_COMM_UNLIMITED_PEND_REQ)
 !>
    type, bind(c), public :: PIO_rearr_comm_fc_opt_t
-      logical(c_bool) :: enable_hs            ! Enable handshake?
-      logical(c_bool) :: enable_isend         ! Enable isends?
-      integer(c_int) :: max_pend_req         ! Maximum pending requests
+      logical(c_bool) :: enable_hs            !< Enable handshake?
+      logical(c_bool) :: enable_isend         !< Enable isends?
+      integer(c_int) :: max_pend_req          !< Maximum pending requests
     end type PIO_rearr_comm_fc_opt_t
 
     integer, public, parameter :: PIO_REARR_COMM_UNLIMITED_PEND_REQ = -1 !< unlimited requests
@@ -289,13 +288,14 @@ module pio_types
 !! @details
 !!  - comm_type : @copydoc PIO_rearr_comm_t
 !!  - fcd : @copydoc PIO_rearr_comm_dir
-!!  - comm_fc_opts : @copydoc PIO_rearr_comm_fc_options
+!!  - comm_fc_opts_comp2io : @copydoc PIO_rearr_comm_fc_options
+!!  - comm_fc_opts_io2comp : @copydoc PIO_rearr_comm_fc_options
 !>
     type, bind(c), public :: PIO_rearr_opt_t
-      integer(c_int)                         :: comm_type
-      integer(c_int)                         :: fcd       ! Flow control direction
-      type(PIO_rearr_comm_fc_opt_t)   :: comm_fc_opts_comp2io
-      type(PIO_rearr_comm_fc_opt_t)   :: comm_fc_opts_io2comp
+      integer(c_int)                         :: comm_type !< comm type
+      integer(c_int)                         :: fcd       !< Flow control direction
+      type(PIO_rearr_comm_fc_opt_t)   :: comm_fc_opts_comp2io !< comp2io
+      type(PIO_rearr_comm_fc_opt_t)   :: comm_fc_opts_io2comp !< io2comp
     end type PIO_rearr_opt_t
 
     public :: PIO_rearr_comm_p2p, PIO_rearr_comm_coll,&

src/flib/piolib_mod.F90

@@ -377,7 +377,8 @@ end subroutine setdebuglevel
 !! @brief set the pio error handling method for a file
 !!
 !! @param file @copydoc file_desc_t
-!! @param method :
+!! @param method : error handling method
+!! @param oldmethod : old error handling method
 !! @copydoc PIO_error_method
 !<
   subroutine seterrorhandlingfile(file, method, oldmethod)
@@ -394,6 +395,7 @@ end subroutine seterrorhandlingfile
 !! @param iosystem : a defined pio system descriptor, see PIO_types
 !! @param method :
 !! @copydoc PIO_error_method
+!! @param oldmethod : old error handling method
 !<
   subroutine seterrorhandlingiosystem(iosystem, method, oldmethod)
     type(iosystem_desc_t), intent(inout) :: iosystem
@@ -409,6 +411,7 @@ end subroutine seterrorhandlingiosystem
 !! @param iosysid : a pio system ID (pass PIO_DEFAULT to change the global default error handling)
 !! @param method :
 !! @copydoc PIO_error_method
+!! @param oldmethod : old error handling method
 !<
   subroutine seterrorhandlingiosysid(iosysid, method, oldmethod)
     integer, intent(in) :: iosysid

src/flib/pionfatt_mod.F90.in

@@ -153,9 +153,9 @@ contains
   !! @brief Writes an netcdf attribute to a file
   !! @details
   !! @param File @copydoc file_desc_t
-  !! @param varid : The netcdf variable identifier
+  !! @param vdesc : The netcdf variable descriptor
   !! @param name : name of the attribute to add
-  !! @param var : The value for the netcdf attribute
+  !! @param values : The value for the netcdf attribute
   !! @retval ierr @copydoc error_return
   !<
   integer function put_att_desc_{TYPE} (File, vdesc, name, values) result(ierr)
@@ -271,7 +271,7 @@ contains
   !! @ingroup PIO_put_att
   !! @brief Writes an netcdf attribute to a file
   !! @details
-  !! @param File @copydoc file_desc_t
+  !! @param ncid @copydoc file_desc_t
   !! @param varid : The netcdf variable identifier
   !! @param name : name of the attribute to add
   !! @param values : The value for the netcdf attribute
@@ -312,7 +312,7 @@ contains
   !! @param File @copydoc file_desc_t
   !! @param varDesc @copydoc var_desc_t
   !! @param name : name of the attribute to add
-  !! @param var : The value for the netcdf attribute
+  !! @param values : The value for the netcdf attribute
   !! @retval ierr @copydoc error_return
   !<
   integer function put_att_1d_desc_{TYPE} (File,varDesc,name,values) result(ierr)
@@ -390,7 +390,7 @@ contains
   !! @ingroup PIO_get_att
   !! @brief Reads an netcdf attribute from a  file
   !! @details
-  !! @param File @copydoc file_desc_t
+  !! @param ncid : The netcdf file ID
   !! @param varid : The netcdf variable identifier
   !! @param name : name of the attribute to get
   !! @param values : The value for the netcdf attribute

src/flib/pionfput_mod.F90.in

@@ -178,7 +178,7 @@ contains
 !! @details
 !! @param File @copydoc file_desc_t
 !! @param vardesc @copydoc var_desc_t
-!! @param start :
+!! @param index :
 !! @param ival : The value for the netcdf metadata
 !! @retval ierr @copydoc error_return
 !<
@@ -266,8 +266,7 @@ contains
 !! @ingroup PIO_put_var
 !! @brief Writes {TYPE} data to a netCDF variable.
 !! @details
-!! @param File @copydoc file_desc_t
-!! @param File : A file handle returne from \ref PIO_openfile or \ref PIO_createfile.
+!! @param ncid : The netcdf file id.
 !! @param varid : The netcdf variable identifier
 !! @param ival : The data to write.
 !! @retval ierr @copydoc error_return