Merge pull request ESMCI#1454 from NCAR/ejh_even_more_docs

more documentation work, including some fortran code

src/clib/pio_darray.c

@@ -14,8 +14,10 @@
 #include <uthash.h>
 
 /**
- * @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. */

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

src/clib/pio_nc.c

@@ -19,21 +19,37 @@
 #include <pio_internal.h>
 
 /**
- * @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.
  */
 
 /**

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. */

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

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
-
-!|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||