From f6086415ae5465e65c4c448b1ecbc039b08ecf80 Mon Sep 17 00:00:00 2001 From: Ed Hartnett Date: Thu, 30 May 2019 12:46:40 -0600 Subject: [PATCH 1/2] moved more defgroups to beginning of file --- src/flib/pio.F90 | 8 ++++---- src/flib/piolib_mod.F90 | 35 ++++++++++++++++++----------------- 2 files changed, 22 insertions(+), 21 deletions(-) diff --git a/src/flib/pio.F90 b/src/flib/pio.F90 index e42e2a5fe9f..86f2595da49 100644 --- a/src/flib/pio.F90 +++ b/src/flib/pio.F90 @@ -4,6 +4,10 @@ !! @author Jim Edwards !< +!> +!! @defgroup PIO_set_blocksize PIO_set_blocksize +!! Set the box rearranger blocksize. + module pio ! Package all exposed variables and functions under one roof @@ -77,10 +81,6 @@ module pio implicit none public contains - !> - !! @defgroup PIO_set_blocksize PIO_set_blocksize - !! Set the box rearranger blocksize. - !< !> !! @ingroup PIO_set_blocksize !! @brief Set the target blocksize for the box rearranger diff --git a/src/flib/piolib_mod.F90 b/src/flib/piolib_mod.F90 index c12e97b987f..5bfd828f8b3 100644 --- a/src/flib/piolib_mod.F90 +++ b/src/flib/piolib_mod.F90 @@ -4,6 +4,24 @@ !! Initialization Routines for PIO. !! !< + +!> +!! @defgroup PIO_openfile PIO_openfile +!! @defgroup PIO_syncfile PIO_syncfile +!! @defgroup PIO_createfile Create a File +!! @defgroup PIO_setframe PIO_setframe +!! @defgroup PIO_advanceframe PIO_advanceframe +!! @defgroup PIO_closefile PIO_closefile +!! @defgroup PIO_freedecomp PIO_freedecomp +!! @defgroup PIO_init PIO_init +!! @defgroup PIO_finalize PIO_finalize +!! @defgroup PIO_initdecomp PIO_initdecomp +!! @defgroup PIO_getnumiotasks PIO_getnumiotasks +!! @defgroup PIO_setdebuglevel PIO_setdebuglevel +!! @defgroup PIO_seterrorhandling PIO_seterrorhandling +!! @defgroup PIO_get_local_array_size PIO_get_local_array_size +!! @defgroup PIO_set_hint PIO_set_hint + module piolib_mod use iso_c_binding !-------------- @@ -65,7 +83,6 @@ module piolib_mod ! !----------------------------------------------------------------------- !> - !! @defgroup PIO_openfile PIO_openfile !! Open an existing netCDF file. !< interface PIO_openfile @@ -73,7 +90,6 @@ module piolib_mod end interface !> - !! @defgroup PIO_syncfile PIO_syncfile !! Sync the file to disk, flushing all buffers. !< interface PIO_syncfile @@ -81,7 +97,6 @@ module piolib_mod end interface !> - !! @defgroup PIO_createfile Create a File !! Create a new netCDF file with PIO. !< interface PIO_createfile @@ -89,7 +104,6 @@ module piolib_mod end interface !> - !! @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). !< @@ -98,7 +112,6 @@ module piolib_mod end interface !> - !! @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). !< @@ -107,7 +120,6 @@ module piolib_mod end interface !> - !! @defgroup PIO_closefile PIO_closefile !! Close an open file. !< interface PIO_closefile @@ -115,7 +127,6 @@ module piolib_mod end interface !> - !! @defgroup PIO_freedecomp PIO_freedecomp !! Free memory associated with a decomposition. !< interface PIO_freedecomp @@ -124,7 +135,6 @@ module piolib_mod end interface !> - !! @defgroup PIO_init PIO_init !! Initializes the PIO subsystem, creating a new IOSystem. !< interface PIO_init @@ -134,7 +144,6 @@ module piolib_mod end interface !> - !! @defgroup PIO_finalize PIO_finalize !! Shuts down an IOSystem and associated resources. !< interface PIO_finalize @@ -142,7 +151,6 @@ module piolib_mod end interface !> - !! @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 @@ -164,7 +172,6 @@ module piolib_mod end interface !> - !! @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. !< @@ -176,7 +183,6 @@ module piolib_mod end interface !> - !! @defgroup PIO_setdebuglevel PIO_setdebuglevel !! Set the level of debug information that PIO will generate. !< interface PIO_setdebuglevel @@ -184,7 +190,6 @@ module piolib_mod end interface !> - !! @defgroup PIO_seterrorhandling PIO_seterrorhandling !! Set the form of error handling for PIO. !! !! By default pio handles errors internally by printing a string @@ -202,7 +207,6 @@ module piolib_mod end interface !> - !! @defgroup PIO_get_local_array_size PIO_get_local_array_size !! Get the local size of a distributed array. !< @@ -1157,9 +1161,6 @@ subroutine init_intercom(component_count, peer_comm, comp_comms, io_comm, iosyst #endif end subroutine init_intercom - !> - !! @defgroup PIO_set_hint PIO_set_hint - !> @ingroup PIO_set_hint !! Set file system hints using mpi_info_set. This is a collective !! call. From bb526369b4ba18dcff9b0466fd9e6df8949d1b13 Mon Sep 17 00:00:00 2001 From: Ed Hartnett Date: Fri, 31 May 2019 06:03:27 -0600 Subject: [PATCH 2/2] more doc work --- doc/source/api.txt | 4 --- src/flib/pio_nf.F90 | 71 +++++++++++++++++++++++++++++++-------------- 2 files changed, 49 insertions(+), 26 deletions(-) diff --git a/doc/source/api.txt b/doc/source/api.txt index bad738c4718..b6fbed66242 100644 --- a/doc/source/api.txt +++ b/doc/source/api.txt @@ -48,14 +48,10 @@ - \ref PIO_inq_varndims - \ref PIO_inq_vardimid - \ref PIO_inq_varnatts - - \ref PIO_inq_dimid - - \ref PIO_inq_dimname - - \ref PIO_inq_dimlen - \ref PIO_inq_ndims - \ref PIO_inq_nvars - \ref PIO_inq_natts - \ref PIO_inquire_variable - \ref PIO_inquire_dimension - - \ref PIO_inquire_dimension */ diff --git a/src/flib/pio_nf.F90 b/src/flib/pio_nf.F90 index bfb0e3c31e9..52cf868a874 100644 --- a/src/flib/pio_nf.F90 +++ b/src/flib/pio_nf.F90 @@ -3,14 +3,9 @@ !! Code to implement the classic netCDF Fortran API in PIO. !! @author Jim Edwards !< -!> -!! @defgroup PIO_inq_dimid PIO_inq_dimid -!! -!! @defgroup PIO_inquire_dimension PIO_inquire_dimension -!! -!! @defgroup PIO_inq_dimlen PIO_inq_dimlen -!! -!! @defgroup PIO_inq_dimname PIO_inq_dimname + +!> @defgroup PIO_inquire_dimension Learn About Dimension in Fortran +!! Learn dimension name, ID, or length. !! !! @defgroup PIO_inq_ndims PIO_inq_ndims !! @@ -40,9 +35,9 @@ !! !! @defgroup PIO_inq_vartype PIO_inq_vartype !! -!! @defgroup PIO_inq_varnatts PIO_inq_varnatts +!! @defgroup PIO_inq_varnatts PIO_inq_varnatts !! -!! @defgroup PIO_inq_var_deflate PIO_inq_var_deflate +!! @defgroup PIO_inq_var_deflate PIO_inq_var_deflate !! !! @defgroup PIO_inq_varname PIO_inq_varname !! @@ -54,8 +49,9 @@ !! !! @defgroup PIO_inq_attname PIO_inq_attname !! -!! @defgroup PIO_def_var PIO_def_var -!! +!! @defgroup PIO_def_var Define a Variable in Fortran +!! Define a new variable. +!< module pio_nf #ifdef TIMING @@ -290,7 +286,8 @@ module pio_nf contains !> - !! @ingroup PIO_inq_dimid + !! @public + !! @ingroup PIO_inquire_dimension !! Returns the netcdf dimension id for the name. !! !! @note We do not want internal error checking for this function. @@ -309,7 +306,8 @@ integer function inq_dimid_desc(File ,name,dimid) result(ie end function inq_dimid_desc !> - !! @ingroup PIO_inq_dimid + !! @public + !! @ingroup PIO_inquire_dimension !! Returns the netcdf dimension id for the name. !! @author Jim Edwards !< @@ -331,6 +329,7 @@ end function PIOc_inq_dimid end function inq_dimid_id !> + !! @public !! @ingroup PIO_inquire_dimension !! Get information about a particular dimension in netcdf file. !! @@ -351,8 +350,16 @@ integer function inquire_dimension_desc(file , dimid, name, len) re end function inquire_dimension_desc !> + !! @public !! @ingroup PIO_inquire_dimension !! Get information about a particular dimension in netcdf file. + !! + !! @param ncid A netcdf file ID returned by \ref + !! PIO_openfile or \ref PIO_createfile. + !! @param dimid The netcdf dimension ID. + !! @param name The name of the dimension. + !! @param len The length of the dimesions name. + !! @retval ierr @copydoc error_return !! @author Jim Edwards !< integer function inquire_dimension_id(ncid , dimid, name, len) result(ierr) @@ -370,7 +377,8 @@ integer function inquire_dimension_id(ncid , dimid, name, len) re end function inquire_dimension_id !> - !! @ingroup PIO_inq_dimlen + !! @public + !! @ingroup PIO_inquire_dimension !! Get information about the length of a particular dimension in !! netcdf file. !! @@ -386,8 +394,10 @@ integer function inq_dimlen_desc(File , dimid, len) result(i integer , intent(out) :: len ierr = inq_dimlen_id(file%fh ,dimid,len) end function inq_dimlen_desc + !> - !! @ingroup PIO_inq_dimlen + !! @public + !! @ingroup PIO_inquire_dimension !! Get information about the length of a particular dimension in !! netcdf file. !! @author Jim Edwards @@ -400,7 +410,8 @@ integer function inq_dimlen_desc_long(File , dimid, len) result(i end function inq_dimlen_desc_long !> - !! @ingroup PIO_inq_dimlen + !! @public + !! @ingroup PIO_inquire_dimension !! Get information about the length of a particular dimension in !! netcdf file. !! @author Jim Edwards @@ -415,7 +426,8 @@ integer function inq_dimlen_id(ncid , dimid, len) result(i end function inq_dimlen_id !> - !! @ingroup PIO_inq_dimlen + !! @public + !! @ingroup PIO_inquire_dimension !! Get information about the length of a particular dimension in !! netcdf file. !! @author Jim Edwards @@ -438,7 +450,8 @@ end function PIOc_inq_dimlen end function inq_dimlen_id_long !> - !! @ingroup PIO_inq_dimname + !! @public + !! @ingroup PIO_inquire_dimension !! Get information about the name of of a dimension. !! !! @param File @copydoc file_desc_t @@ -455,7 +468,8 @@ integer function inq_dimname_desc(File , dimid, name) result( end function inq_dimname_desc !> - !! @ingroup PIO_inq_dimname + !! @public + !! @ingroup PIO_inquire_dimension !! Get information about the name of of a dimension. !! @author Jim Edwards !< @@ -480,6 +494,7 @@ end function PIOc_inq_dimname end function inq_dimname_id !> + !! @public !! @ingroup PIO_inq_ndims !! Get information about the number of dimensions of a file or !! group. @@ -496,6 +511,7 @@ integer function inq_ndims_desc(File , ndims) result(ierr) end function inq_ndims_desc !> + !! @public !! @ingroup PIO_inq_ndims !! Get information about the number of dimensions of a file or !! group. @@ -516,6 +532,7 @@ end function PIOc_inq_ndims end function inq_ndims_id !> + !! @public !! @ingroup PIO_inq_nvars !! Get information about the number of variables in a file or group. !! @@ -550,6 +567,7 @@ end function PIOc_inq_nvars end function inq_nvars_id !> + !! @public !! @ingroup PIO_inq_natts !! Get information about the number of global attributes in a file !! or group. @@ -566,6 +584,7 @@ integer function inq_natts_desc(File , natts) result(ierr) end function inq_natts_desc !> + !! @public !! @ingroup PIO_inq_natts !! Get information about the number of global attributes in a file !! or group. @@ -586,6 +605,7 @@ end function PIOc_inq_natts end function inq_natts_id !> + !! @public !! @ingroup PIO_inq_unlimdm !! Get information about the unlimited dimension in a file. !! @@ -602,6 +622,7 @@ integer function inq_unlimdim_desc(File , unlimdim) result(ier end function inq_unlimdim_desc !> + !! @public !! @ingroup PIO_inq_unlimdm !! Get information about the unlimited dimension in a file. !! @author Jim Edwards @@ -622,6 +643,7 @@ end function PIOc_inq_unlimdim end function inq_unlimdim_id !> + !! @public !! @ingroup PIO_inquire !! Gets metadata information for netcdf file. !! @@ -648,6 +670,7 @@ integer function inquire_desc(File ,nDimensions,nVariable end function inquire_desc !> + !! @public !! @ingroup PIO_inquire !! Gets metadata information for netcdf file. !! @author Jim Edwards @@ -667,6 +690,7 @@ integer function inquire_id(ncid ,nDimensions,nVariable end function inquire_id !> + !! @public !! @ingroup PIO_enddef !! Exits netcdf define mode. !! @@ -680,6 +704,7 @@ integer function enddef_desc(File) result(ierr) end function enddef_desc !> + !! @public !! @ingroup PIO_enddef !! Wrapper for the C function \ref PIOc_enddef . !! @author Jim Edwards @@ -697,6 +722,7 @@ end function PIOc_enddef end function enddef_id !> + !! @public !! @ingroup PIO_redef !! Exits netcdf define mode. !! @@ -710,6 +736,7 @@ integer function redef_desc(File) result(ierr) end function redef_desc !> + !! @public !! @ingroup PIO_set_log_level !! Sets the logging level. Only takes effect if PIO was built with !! PIO_ENABLE_LOGGING=On @@ -731,6 +758,7 @@ end function PIOc_set_log_level end function set_log_level !> + !! @public !! @ingroup PIO_strerror !! Returns a descriptive string for an error code. !! @@ -757,6 +785,7 @@ end function PIOc_strerror end function strerror !> + !! @public !! @ingroup PIO_redef !! Wrapper for the C function \ref PIOc_redef . !! @author Jim Edwards @@ -773,8 +802,6 @@ end function PIOc_redef ierr = PIOc_redef(ncid) end function redef_id - !! NetCDF files. - !< !> !! @ingroup PIO_def_dim !! Defines the netcdf dimension.