diff --git a/src/clib/pio_darray.c b/src/clib/pio_darray.c index 8fa52ebc89c..c04e4de93bf 100644 --- a/src/clib/pio_darray.c +++ b/src/clib/pio_darray.c @@ -14,8 +14,10 @@ #include /** - * @defgroup PIO_read_darray_c Reading a Variable into Distributes Arrays - * @defgroup PIO_write_darray_c Writing Distributes Arrays into a Variable + * @defgroup PIO_read_darray_c Reading Distributes Arrays + * Read data from a netCDF file to a distributed array with the C API. + * @defgroup PIO_write_darray_c Writing Distributes Arrays + * Write data from a distributed array to a netCDF file with the C API. */ /** 10MB default limit. */ diff --git a/src/clib/pio_file.c b/src/clib/pio_file.c index 3ef347e1589..6bf3cf0ba4d 100644 --- a/src/clib/pio_file.c +++ b/src/clib/pio_file.c @@ -9,9 +9,13 @@ /** * @defgroup PIO_open_file_c Open a File + * Open an existing netCDF file with PIO with the C API. * @defgroup PIO_create_file_c Create a File + * Create a new netCDF file with PIO with the C API. * @defgroup PIO_sync_file_c Sync a File + * Flush buffers and sync data to disk with the C API. * @defgroup PIO_close_file_c Close a File + * Close a file with the C API. */ /* This is the next ncid that will be used when a file is opened or diff --git a/src/clib/pio_nc.c b/src/clib/pio_nc.c index 72cf28a0e2a..37a20bd0150 100644 --- a/src/clib/pio_nc.c +++ b/src/clib/pio_nc.c @@ -19,21 +19,37 @@ #include /** - * @defgroup PIO_inq_c Learn About File Contents - * @defgroup PIO_typelen_c Learn Length of a Data Type - * @defgroup PIO_inq_format_c Learn About File Binary Format - * @defgroup PIO_inq_dim_c Learn About Dimensions + * @defgroup PIO_inq_c Learn About File + * Learn the number of variables, dimensions, and global atts, and the + * unlimited dimension. + * @defgroup PIO_typelen_c Learn Aboue a Data Type + * Learn the length of a data type. + * @defgroup PIO_inq_format_c Learn About Binary Format + * Learn about the binary format. + * @defgroup PIO_inq_dim_c Learn About a Dimension + * Learn dimension name and length. * @defgroup PIO_inq_var_c Learn About a Variable + * Learn variable name, dimensions, and type. * @defgroup PIO_inq_att_c Learn About an Attribute + * Learn length, type, and name of an attribute. * @defgroup PIO_rename_dim_c Rename a Dimension + * Rename a dimension. * @defgroup PIO_rename_var_c Rename a Variable + * Rename a variable. * @defgroup PIO_rename_att_c Rename an Attribute + * Rename an attribute. * @defgroup PIO_del_att_c Delete an Attribute + * Delete an attribute. * @defgroup PIO_set_fill_c Set Fill Value + * Set the fill value for a variable. * @defgroup PIO_enddef_c End Define Mode + * End define mode. * @defgroup PIO_redef_c Re-enter Define Mode + * Re-enter Define Mode. * @defgroup PIO_def_dim_c Define a Dimension + * Define a new dimension in the file. * @defgroup PIO_def_var_c Define a Variable + * Define a new variable in the file. */ /** diff --git a/src/clib/pioc.c b/src/clib/pioc.c index dc2d39569f7..39488ca77fe 100644 --- a/src/clib/pioc.c +++ b/src/clib/pioc.c @@ -12,16 +12,28 @@ /** * @defgroup PIO_init_c Initialize the IO System + * Initialize the IOSystem, including specifying number of IO and computation tasks. * @defgroup PIO_finalize_c Shut Down the IO System + * Shut down an IOSystem, freeing all associated resources. * @defgroup PIO_initdecomp_c Initialize a Decomposition + * Intiailize a decomposition of data into distributed arrays. * @defgroup PIO_freedecomp_c Free a Decomposition + * Free a decomposition, and associated resources. * @defgroup PIO_setframe_c Set the Record Number - * @defgroup PIO_set_hint_c Set an MPI Hint - * @defgroup PIO_error_method_c Set the Error Handling - * @defgroup PIO_get_local_array_size_c Get the Local Array Size - * @defgroup PIO_iosystem_is_active_c Is this IO System Active? - * @defgroup PIO_getnumiotasks_c Get the Number of IO Tasks - * @defgroup PIO_set_blocksize_c Set the Blocksize + * Set the record number for a future call to PIOc_write_darray() or + * PIOc_read_darray(). + * @defgroup PIO_set_hint_c Set a Hint + * Set an MPI Hint. + * @defgroup PIO_error_method_c Set Error Handling + * Set the error handling method in case error is encountered. + * @defgroup PIO_get_local_array_size_c Get the Local Size + * Get the local size of a distributed array. + * @defgroup PIO_iosystem_is_active_c Check IOSystem + * Is the IO system active? + * @defgroup PIO_getnumiotasks_c Get Number IO Tasks + * Get the Number of IO Tasks. + * @defgroup PIO_set_blocksize_c Set Blocksize + * Set the Blocksize. */ /** The default error handler used when iosystem cannot be located. */ diff --git a/src/clib/pioc_support.c b/src/clib/pioc_support.c index 36ce70352a6..e9b6a6258c0 100644 --- a/src/clib/pioc_support.c +++ b/src/clib/pioc_support.c @@ -1774,7 +1774,7 @@ PIOc_writemap_from_f90(const char *file, int ndims, const int *gdims, * @param filename The filename to create. * @param mode The netcdf mode for the create operation. * @returns 0 for success, error code otherwise. - * @ingroup PIO_createfile + * @ingroup PIO_createfile_c * @author Ed Hartnett */ int @@ -2014,7 +2014,7 @@ check_unlim_use(int ncid) * caller. * * @return 0 for success, error code otherwise. - * @ingroup PIO_openfile + * @ingroup PIO_openfile_c * @author Ed Hartnett */ int @@ -2217,7 +2217,7 @@ inq_file_metadata(file_desc_t *file, int ncid, int iotype, int *nvars, int **rec * classic. * * @return 0 for success, error code otherwise. - * @ingroup PIO_openfile + * @ingroup PIO_openfile_c * @author Jim Edwards, Ed Hartnett */ int diff --git a/src/flib/pio_kinds.F90 b/src/flib/pio_kinds.F90 index 856eb420213..8e4148c23f2 100644 --- a/src/flib/pio_kinds.F90 +++ b/src/flib/pio_kinds.F90 @@ -1,22 +1,11 @@ !> -!! @file pio_kinds.F90 -!! @brief basic data types +!! @file +!! This module defines default numerical data types for all common data +!! types like integer, character, logical, real4 and real8. !! !< module pio_kinds -!BOP -! !MODULE: pio_kinds -! -! !DESCRIPTION: -! This module defines default numerical data types for all common data -! types like integer, character, logical, real4 and real8. -! -! !REVISION HISTORY: -! CVS:$Id: pio_kinds.F90,v 1.1.1.1 2006/07/31 16:15:30 dennis Exp $ -! CVS:$Name: $ - -! !USES: ! uses mpi if available #ifndef NO_MPIMOD use mpi, only : MPI_OFFSET_KIND ! _EXTERNAL @@ -44,11 +33,4 @@ module pio_kinds !> Byte size of the MPI_OFFSET type. integer, parameter, public :: PIO_OFFSET_KIND=MPI_OFFSET_KIND -!EOP -!BOC -!EOC -!*********************************************************************** - end module pio_kinds - -!||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||| diff --git a/src/flib/piolib_mod.F90 b/src/flib/piolib_mod.F90 index 7c4ad1ff011..6f07e770bab 100644 --- a/src/flib/piolib_mod.F90 +++ b/src/flib/piolib_mod.F90 @@ -67,84 +67,91 @@ module piolib_mod ! module variables ! !----------------------------------------------------------------------- -!> -!! @defgroup PIO_openfile PIO_openfile -!< + !> + !! @defgroup PIO_openfile PIO_openfile + !! Open an exist netCDF file. + !< interface PIO_openfile module procedure PIO_openfile end interface -!> -!! @defgroup PIO_syncfile PIO_syncfile -!< + !> + !! @defgroup PIO_syncfile PIO_syncfile + !! Sync the file to disk, flushing all buffers. + !< interface PIO_syncfile module procedure syncfile end interface -!> -!! @defgroup PIO_createfile PIO_createfile -!< + !> + !! @defgroup PIO_createfile Create a file for use with PIO + !! Create a new netCDF file with PIO. + !< interface PIO_createfile module procedure createfile end interface -!> -!! @defgroup PIO_setframe PIO_setframe -!! @brief sets the unlimited dimension for netcdf file -!< + !> + !! @defgroup PIO_setframe PIO_setframe + !! Sets the record number for a future read/write of distributed + !! arrays (see @ref PIO_write_darray, @ref PIO_read_darray). + !< interface PIO_setframe module procedure setframe end interface -!> -!! @defgroup PIO_advanceframe PIO_advanceframe -!< + !> + !! @defgroup PIO_advanceframe PIO_advanceframe + !! Increment the record number for a future read/write of distributed + !! arrays (see @ref PIO_write_darray, @ref PIO_read_darray). + !< interface PIO_advanceframe module procedure advanceframe end interface -!> -!! @defgroup PIO_closefile PIO_closefile -!< + !> + !! @defgroup PIO_closefile PIO_closefile + !! Close an open file. + !< interface PIO_closefile module procedure closefile end interface -!> -!! @defgroup PIO_freedecomp PIO_freedecomp -!! free memory associated with a io descriptor -!< + !> + !! @defgroup PIO_freedecomp PIO_freedecomp + !! Free memory associated with a decomposition. + !< interface PIO_freedecomp module procedure freedecomp_ios module procedure freedecomp_file end interface -!> -!! @defgroup PIO_init PIO_init -!! initializes the pio subsystem -!< + !> + !! @defgroup PIO_init PIO_init + !! Initializes the PIO subsystem, creating a new IOSystem. + !< interface PIO_init module procedure init_intracom module procedure init_intercom end interface -!> -!! @defgroup PIO_finalize PIO_finalize -!! Shuts down and cleans up any memory associated with the pio library. -!< + !> + !! @defgroup PIO_finalize PIO_finalize + !! Shuts down an IOSystem and associated resources. + !< interface PIO_finalize module procedure finalize end interface -!> -!! @defgroup PIO_initdecomp PIO_initdecomp -!! @brief PIO_initdecomp is an overload interface the models decomposition to pio. -!! @details initdecomp_1dof_bin_i8, initdecomp_1dof_nf_i4, initdecomp_2dof_bin_i4, -!! and initdecomp_2dof_nf_i4 are all depreciated, but supported for backwards -!! compatibility. -!< + !> + !! @defgroup PIO_initdecomp PIO_initdecomp + !! PIO_initdecomp is an overload interface the models decomposition to pio. + !! initdecomp_1dof_bin_i8, initdecomp_1dof_nf_i4, initdecomp_2dof_bin_i4, + !! and initdecomp_2dof_nf_i4 are all depreciated, but supported for backwards + !! compatibility. + !< interface PIO_initdecomp module procedure PIO_initdecomp_dof_i4 ! previous name: initdecomop_1dof_nf_box module procedure PIO_initdecomp_dof_i8 ! previous name: initdecomop_1dof_nf_box @@ -160,14 +167,11 @@ module piolib_mod ! module procedure PIO_initdecomp_dof_dof end interface -!> - -!> -!! @defgroup PIO_getnumiotasks PIO_getnumiotasks -!! returns the actual number of IO-tasks used. PIO -!! will reset the total number of IO-tasks if certain -!! conditions are meet -!< + !> + !! @defgroup PIO_getnumiotasks PIO_getnumiotasks + !! Return the actual number of IO-tasks used. PIO will reset the + !! total number of IO-tasks if certain conditions are meet. + !< interface PIO_get_numiotasks module procedure getnumiotasks end interface @@ -175,35 +179,36 @@ module piolib_mod module procedure getnumiotasks end interface -!> -!! @defgroup PIO_setdebuglevel PIO_setdebuglevel -!! sets the level of debug information that pio will generate. -!< + !> + !! @defgroup PIO_setdebuglevel PIO_setdebuglevel + !! Set the level of debug information that PIO will generate. + !< interface PIO_setdebuglevel module procedure setdebuglevel end interface -!> -!! @defgroup PIO_seterrorhandling PIO_seterrorhandling -!! sets the form of error handling for pio. -!! -!! By default pio handles errors internally by printing a string -!! describing the error and calling mpi_abort. Application -!! developers can change this behavior for calls to the underlying netcdf -!! libraries with a call to PIO_seterrorhandling. For example if a -!! developer wanted to see if an input netcdf format file contained the variable -!! 'u' they might write the following -!! @verbinclude errorhandle -!< + !> + !! @defgroup PIO_seterrorhandling PIO_seterrorhandling + !! Set the form of error handling for PIO. + !! + !! By default pio handles errors internally by printing a string + !! describing the error and calling mpi_abort. Application + !! developers can change this behavior for calls to the underlying + !! netcdf libraries with a call to PIO_seterrorhandling. For example + !! if a developer wanted to see if an input netcdf format file + !! contained the variable 'u' they might write the following + !! @verbinclude errorhandle + !< interface PIO_seterrorhandling module procedure seterrorhandlingfile module procedure seterrorhandlingiosystem module procedure seterrorhandlingiosysid end interface -!> -!! @defgroup PIO_get_local_array_size PIO_get_local_array_size -!< + !> + !! @defgroup PIO_get_local_array_size PIO_get_local_array_size + !! Get the local size of a distributed array. + !< !eoc !*********************************************************************** @@ -222,13 +227,12 @@ module piolib_mod #define fptr(arg) arg !!$#endif -!> -!! @public -!! @ingroup PIO_file_is_open -!! @brief This logical function indicates if a file is open. -!! @details -!! @param File @copydoc file_desc_t -!< + !> + !! @public + !! @ingroup PIO_file_is_open + !! This logical function indicates if a file is open. + !! @param File @copydoc file_desc_t + !< logical function PIO_FILE_IS_OPEN(File) type(file_desc_t), intent(in) :: file interface @@ -248,14 +252,14 @@ end function PIOc_File_is_Open end function PIO_FILE_IS_OPEN -!> -!! @public -!! @ingroup PIO_get_local_array_size -!! @brief This function returns the expected local size of an array associated with iodesc -!! @details -!! @param iodesc -!! @copydoc io_desc_t -!< + !> + !! @public + !! @ingroup PIO_get_local_array_size + !! Return the expected local size of an array associated with a + !! decomposition. + !! @param iodesc the decomposition. + !! @copydoc io_desc_t + !< integer function PIO_get_local_array_size(iodesc) type(io_desc_t), intent(in) :: iodesc interface @@ -1204,13 +1208,13 @@ end function PIOc_finalize end subroutine finalize -!> -!! @public -!! @ingroup PIO_getnumiotasks -!! @brief This returns the number of IO-tasks that PIO is using -!! @param iosystem : a defined pio system descriptor, see PIO_types -!! @param numiotasks : the number of IO-tasks -!< + !> + !! @public + !! @ingroup PIO_getnumiotasks + !! @brief This returns the number of IO-tasks that PIO is using + !! @param iosystem : a defined pio system descriptor, see PIO_types + !! @param numiotasks : the number of IO-tasks + !< subroutine getnumiotasks(iosystem,numiotasks) type (iosystem_desc_t), intent(in) :: iosystem integer(i4), intent(out) :: numiotasks