Merge pull request ESMCI#1751 from NCAR/ejh_docs

Fortran documentation improvments
jedwards4b · Sep 15, 2020 · 14ba346 · 14ba346
2 parents 3a77973 + d23ae96
commit 14ba346
Show file tree

Hide file tree

Showing 2 changed files with 102 additions and 0 deletions.
diff --git a/src/flib/pio_nf.F90 b/src/flib/pio_nf.F90
@@ -8,13 +8,35 @@
 !> @defgroup PIO_inquire_dimension Learn About Dimension
 !! Learn dimension name, ID, or length in Fortran.
 !!
+!! Use the generic functions to call the underlying Fortran functions.
+!!
+!! Generic Function  | Function(s)
+!! ----------------  | -----------
+!! pio_inq_dimlen()  | inq_dimlen_desc(), inq_dimlen_id(), inq_dimlen_desc_long(), inq_dimlen_id_long()
+!! pio_inq_ndims()   | inq_ndims_id()
+!! pio_inq_dimid()   | inq_dimid_desc(), inq_dimid_id()
+!! pio_inq_dimname() | inq_dimname_desc(), inq_dimname_id()
+!!
 !! @defgroup PIO_inquire Learn About a File
 !! Learn the number of variables, dimensions, global attributes, and
 !! the unlimited dimension ID in Fortran.
 !!
+!! Use the generic functions to call the underlying Fortran functions.
+!!
+!! Generic Function  | Function(s)
+!! ----------------  | -----------
+!! pio_inquire()     | inquire_desc(), inquire_id()
+!!
 !! @defgroup PIO_enddef Define Mode
 !! End or re-enter define mode in Fortran.
 !!
+!! Use the generic functions to call the underlying Fortran functions.
+!!
+!! Generic Function  | Function(s)
+!! ----------------  | -----------
+!! pio_enddef()      | enddef_desc(), enddef_id()
+!! pio_redef()       | redef_desc(), redef_id()
+!!
 !! @defgroup PIO_set_log_level Debug Logging
 !! Set debugging log level in Fortran.
 !!
@@ -24,15 +46,50 @@
 !! @defgroup PIO_def_dim Define a Dimension
 !! Define a new dimension, with name and length in Fortran.
 !!
+!! Use the generic functions to call the underlying Fortran functions.
+!!
+!! Generic Function       | Function(s)
+!! ----------------       | -----------
+!! pio_def_dim() | def_dim_desc(), def_dim_id(), def_dim_int_desc(), def_dim_int_id()
+!!
 !! @defgroup PIO_inquire_variable Learn About a Variable
 !! Learn variable name, ID, type, dimensions, compression, chunking in
 !! Fortran.
 !!
+!! Use the generic functions to call the underlying Fortran functions.
+!!
+!! Generic Function       | Function(s)
+!! ----------------       | -----------
+!! pio_inquire_variable() | inquire_variable_desc(), inquire_variable_vid(), inquire_variable_id()
+!! pio_inq_varid()        | inq_varid_desc(), inq_varid_vid(), inq_varid_id()
+!! pio_inq_vartype()      | inq_varname_desc(), inq_varname_vid(), inq_varname_id()
+!! pio_inq_varndims()     | inq_varndims_desc(), inq_varndims_vid(), inq_varndims_id()
+!! pio_inq_vardimid()     | inq_vardimid_desc(), inq_vardimid_vid(), inq_vardimid_id()
+!! pio_inq_varnatts()     | inq_varnatts_desc(), inq_varnatts_vid(), inq_varnatts_id()
+!! pio_inq_var_deflate()  | inq_var_deflate_desc(), inq_var_deflate_vid(), inq_var_deflate_id()
+!! pio_inq_var_chunking() | inq_var_chunking_desc(), inq_var_chunking_vid(), inq_var_chunking_id()
+!!
 !! @defgroup PIO_inq_att Learn About an Attribute
 !! Learn attribute name, number, type, size in Fortran.
 !!
+!! Use the generic functions to call the underlying Fortran functions.
+!!
+!! Generic Function   | Function(s)
+!! ----------------   | -----------
+!! pio_inq_attname()  | inq_attname_desc(), inq_attname_vid(), inq_attname_id()
+!! pio_inq_att()      | inq_att_desc(), inq_att_vid(), inq_att_id()
+!! pio_inq_attlen()   | inq_attlen_desc(), inq_attlen_vid(), inq_attlen_id()
+!!
 !! @defgroup PIO_def_var Define a Variable
 !! Define a new variable in Fortran.
+!!
+!! Use the generic functions to call the underlying Fortran functions.
+!!
+!! Generic Function       | Function(s)
+!! ----------------       | -----------
+!! pio_def_var()          | def_var_0d_desc(), def_var_md_desc(), def_var_0d_id(), def_var_md_id()
+!! pio_def_var_deflate()  | def_var_deflate_desc(), def_var_deflate_id()
+!! pio_def_var_chunking() | def_var_chunking_desc()
 !<
 
 module pio_nf

diff --git a/src/flib/piolib_mod.F90 b/src/flib/piolib_mod.F90
@@ -30,13 +30,52 @@
 !! Create a new IO System, designating numbers of I/O and computation
 !! tasks in Fortran.
 !!
+!! Use the Fortran generic function PIO_init() to initialize the IO
+!! System. The PIO_init() function will call init_intracom().
+!!
+!! This code from examples/f03/examplePio.F90 demonstrates how to
+!! initialize the IO system for intracom mode.
+!!
+!! @code
+!!        call PIO_init(this%myRank,      & ! MPI rank
+!!            MPI_COMM_WORLD,             & ! MPI communicator
+!!            this%niotasks,              & ! Number of iotasks (ntasks/stride)
+!!            this%numAggregator,         & ! number of aggregators to use
+!!            this%stride,                & ! stride
+!!            PIO_rearr_subset,           & ! do not use any form of rearrangement
+!!            this%pioIoSystem,           & ! iosystem
+!!            base=this%optBase)            ! base (optional argument)
+!! @endcode
+!!
 !! @defgroup PIO_finalize Free an IOSystem
 !! Free an IO System, releasing all resources in Fortran.
 !!
+!! Use the Fortran generic function PIO_finalize() to finalize the IO
+!! System, freeing all associated resources. The PIO_finalize()
+!! function will call finalize().
+!!
+!! This code from examples/f03/examplePio.F90 demonstrates how to
+!! finalize the IO system.
+!!
+!! @code
+!!        call PIO_finalize(this%pioIoSystem, ierr)
+!! @endcode
+!!
 !! @defgroup PIO_initdecomp Define a Decomposition
 !! Define a new decomposition of variables to distributed arrays in
 !! Fortran.
 !!
+!! Use the generic function PIO_initdecomp() to call the underlying Fortran functions.
+!!
+!! - PIO_initdecomp_dof_i4()
+!! - PIO_initdecomp_dof_i8()
+!! - initdecomp_1dof_nf_i4()
+!! - initdecomp_1dof_nf_i8()
+!! - initdecomp_1dof_bin_i4()
+!! - initdecomp_1dof_bin_i8()
+!! - initdecomp_2dof_nf_i4()
+!! - initdecomp_2dof_nf_i8()
+!!
 !! @defgroup PIO_getnumiotasks Get Number IO Tasks
 !! Get the number of IO tasks in Fortran.
 !!
@@ -46,6 +85,12 @@
 !! @defgroup PIO_seterrorhandling Error Handling for Fortran
 !! Set the behavior if an error is encountered in Fortran.
 !!
+!! Use the generic functions to call the underlying Fortran functions.
+!!
+!! Generic Function       | Function(s)
+!! ----------------       | -----------
+!! PIO_seterrorhandling() | seterrorhandlingfile(), seterrorhandlingiosystem(), seterrorhandlingiosysid()
+!!
 !! @defgroup PIO_get_local_array_size Get Local Array Size
 !! Get the local size of the distributed array in a decomposition in
 !! Fortran.