From 596ee10d50369b920f971217e3f0d9754aa29e07 Mon Sep 17 00:00:00 2001 From: Ed Hartnett Date: Mon, 20 May 2019 12:15:41 -0600 Subject: [PATCH] more documentation fixes --- src/clib/pio.h | 21 ++++++++++++-------- src/clib/pio_nc.c | 5 +++-- src/clib/pio_nc4.c | 14 ++++++------- src/clib/pioc.c | 2 +- src/flib/pio_nf.F90 | 6 ++++-- src/flib/pio_types.F90 | 38 ++++++++++++++++++------------------ src/flib/piolib_mod.F90 | 5 ++++- src/flib/pionfatt_mod.F90.in | 10 +++++----- src/flib/pionfput_mod.F90.in | 5 ++--- 9 files changed, 58 insertions(+), 48 deletions(-) diff --git a/src/clib/pio.h b/src/clib/pio.h index 63d1d505b32..8bc5f38542c 100644 --- a/src/clib/pio.h +++ b/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 diff --git a/src/clib/pio_nc.c b/src/clib/pio_nc.c index 71371d24a94..e93394fb541 100644 --- a/src/clib/pio_nc.c +++ b/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 diff --git a/src/clib/pio_nc4.c b/src/clib/pio_nc4.c index b2b4e6e1996..5f7e571e2a7 100644 --- a/src/clib/pio_nc4.c +++ b/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 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 diff --git a/src/clib/pioc.c b/src/clib/pioc.c index 267d6fa46b9..98705b6f033 100644 --- a/src/clib/pioc.c +++ b/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 diff --git a/src/flib/pio_nf.F90 b/src/flib/pio_nf.F90 index e7f19acb00d..064741d6993 100644 --- a/src/flib/pio_nf.F90 +++ b/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, & diff --git a/src/flib/pio_types.F90 b/src/flib/pio_types.F90 index 27d0f1bb1ca..0d85b4748e3 100644 --- a/src/flib/pio_types.F90 +++ b/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,& diff --git a/src/flib/piolib_mod.F90 b/src/flib/piolib_mod.F90 index 248d54ff763..3ca529439ef 100644 --- a/src/flib/piolib_mod.F90 +++ b/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 diff --git a/src/flib/pionfatt_mod.F90.in b/src/flib/pionfatt_mod.F90.in index daaca6dca81..82709f59188 100644 --- a/src/flib/pionfatt_mod.F90.in +++ b/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 diff --git a/src/flib/pionfput_mod.F90.in b/src/flib/pionfput_mod.F90.in index d4b54220a94..81e6661be0f 100644 --- a/src/flib/pionfput_mod.F90.in +++ b/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