Merge pull request ESMCI#1458 from NCAR/ejh_more_docs

more documentation work

Makefile.am

@@ -13,3 +13,5 @@ endif
 SUBDIRS = src tests examples ${DOC} scripts
 
 EXTRA_DIST = CMakeLists.txt set_flags.am COPYRIGHT
+
+CLEANFILES = docs/* docs

doc/source/api.txt

@@ -16,7 +16,7 @@
     - \ref PIO_read_darray
     - \ref PIO_write_darray
   \section utility Utility routines
-    - \ref PIO_set_hint_grp
+    - \ref PIO_set_hint
     - \ref PIO_setframe
     - \ref PIO_advanceframe
     - \ref PIO_setdebuglevel

src/flib/pio.F90

@@ -1,7 +1,7 @@
 !>
 !! @file 
-!! @brief User interface Module for PIO, this is the only file a user program should 'use'
-!! 
+!! User interface Module for PIO, this is the only file a user program should 'use'.
+!! @author Jim Edwards
 !<
 
 module pio
@@ -77,15 +77,15 @@ module pio
   implicit none
   public
 contains
-!>
-!! @public
-!! @defgroup PIO_set_blocksize
-!<
-!>
-!! @public
-!! @ingroup PIO_set_blocksize
-!! @brief Set the target blocksize for the box rearranger
-!<
+  !>
+  !! @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
+  !! @author Jim Edwards
+  !<
   subroutine pio_set_blocksize(blocksize)
     integer :: blocksize
     integer :: ierr
@@ -100,10 +100,10 @@ end function PIOc_set_blocksize
   end subroutine pio_set_blocksize
 
 
-!>
-!! @public
-!! @brief Logical function returns true if the task is an IO task.
-!<
+  !>
+  !! Logical function returns true if the task is an IO task.
+  !! @author Jim Edwards
+  !<
   function pio_iam_iotask(iosystem) result(task)
     use iso_c_binding
     type(iosystem_desc_t), intent(in) :: iosystem
@@ -123,10 +123,10 @@ end function PIOc_iam_iotask
     task = ctask
   end function pio_iam_iotask
 
-!>
-!! @public
-!! @brief Integer function returns rank of IO task.
-!<
+  !>
+  !! Integer function returns rank of IO task.
+  !! @author Jim Edwards
+  !<
   function pio_iotask_rank(iosystem) result(rank)
     type(iosystem_desc_t), intent(in) :: iosystem
     integer :: rank, ierr
@@ -142,10 +142,10 @@ end function PIOc_iotask_rank
     ierr = PIOc_iotask_rank(iosystem%iosysid, rank)
   end function pio_iotask_rank
 
-!>
-!! @public
-!! @brief Sets active to true if IO system is active.
-!<
+  !>
+  !! Sets active to true if IO system is active.
+  !! @author Jim Edwards
+  !<
   subroutine pio_iosystem_is_active(iosystem, active)
     use iso_c_binding
     type(iosystem_desc_t), intent(in) :: iosystem
@@ -165,6 +165,5 @@ end function PIOc_iosystem_is_active
     active = lactive
   end subroutine pio_iosystem_is_active
 
-
 end module pio
 

src/flib/pio_types.F90

@@ -1,6 +1,6 @@
 !>
 !! @file
-!! @brief Derived datatypes and constants for PIO Fortran API
+!! Derived datatypes and constants for PIO Fortran API.
 !!
 !<
 module pio_types
@@ -23,7 +23,6 @@ module pio_types
     !  a file descriptor data structure
     !------------------------------------
 !>
-!! @public
 !! @struct iosystem_desc_t
 !! @brief A defined PIO system descriptor created by @ref PIO_init (see pio_types)
 !<