Merge pull request ESMCI#1462 from NCAR/ejh_more_docs_4

More fortran doxygen stuff
jedwards4b · May 31, 2019 · 7ba0816 · 7ba0816
2 parents fe7b080 + ce207c5
commit 7ba0816
Show file tree

Hide file tree

Showing 4 changed files with 71 additions and 47 deletions.
diff --git 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.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/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.