Merge pull request ESMCI#1464 from NCAR/ejh_more_docs_6

more documentation changes

doc/Doxyfile.in

@@ -771,8 +771,8 @@ WARN_LOGFILE           = doxywarn.log
 INPUT                  = @CMAKE_CURRENT_SOURCE_DIR@/../doc/source \
                          @CMAKE_CURRENT_SOURCE_DIR@/../examples/c \
                          @CMAKE_CURRENT_SOURCE_DIR@/../examples/f03 \
-			 @C_SRC_FILES@ \
-			 @FORTRAN_SRC_FILES@
+			 @FORTRAN_SRC_FILES@ \
+			 @C_SRC_FILES@ 
 
 
 # This tag can be used to specify the character encoding of the source files

doc/source/api.txt

@@ -1,57 +1,42 @@
  /*!  \page api PIO Fortran Interface
   This is a list of all user interface routines:
 
-  \section api_system PIO startup and shutdown routines
-     - \ref PIO_init
-     - \ref PIO_finalize
-  \section api_fileops PIO file Operations
-     - \ref PIO_openfile
-     - \ref PIO_createfile
-     - \ref PIO_syncfile
-     - \ref PIO_closefile
-  \section api_decomp PIO decomposition routines
-    - \ref PIO_initdecomp
-    - \ref PIO_freedecomp
-  \section readwrite Reading and Writing distributed variables
-    - \ref PIO_read_darray
-    - \ref PIO_write_darray
-  \section utility Utility routines
-    - \ref PIO_set_hint
-    - \ref PIO_setframe
-    - \ref PIO_advanceframe
-    - \ref PIO_setdebuglevel
-    - \ref PIO_seterrorhandling
-    - \ref PIO_get_local_array_size
+  \section api_system PIO Startup and Shutdown
+    - \ref PIO_init
+    - \ref PIO_finalize
     - \ref PIO_getnumiotasks
     - \ref PIO_set_blocksize
-  \section netcdf NetCDF format specific routines 
-     Also see: http://www.unidata.ucar.edu/software/netcdf/docs/
-     \subsection putget Reading/Writing netcdf metadata  
-         - \ref PIO_get_att
-         - \ref PIO_put_att
-         - \ref PIO_get_var
-         - \ref PIO_put_var
-     \subsection utilnc Netcdf utility routines
+    - \ref PIO_set_hint
+  \section api_fileops File Operations
+    - \ref PIO_openfile
+    - \ref PIO_createfile
+    - \ref PIO_syncfile
     - \ref PIO_enddef
-    - \ref PIO_redef
-    - \ref PIO_def_dim 
-    - \ref PIO_def_var
-     \subsection inqnc NetCDF file inquiry routines
+    - \ref PIO_closefile
+  \section inqnc Inquiry
     - \ref PIO_inquire
-    - \ref PIO_inq_attname
-    - \ref PIO_inq_att
-    - \ref PIO_inq_attlen
-    - \ref PIO_inquire_variable
-    - \ref PIO_inq_varid
-    - \ref PIO_inq_varname
-    - \ref PIO_inq_vartype
-    - \ref PIO_inq_varndims
-    - \ref PIO_inq_vardimid
-    - \ref PIO_inq_varnatts
-    - \ref PIO_inq_ndims
-    - \ref PIO_inq_nvars
-    - \ref PIO_inq_natts
-    - \ref PIO_inquire_variable
     - \ref PIO_inquire_dimension
+    - \ref PIO_inquire_variable
+    - \ref PIO_inq_att
+  \section metadata Defining Metadata
+    - \ref PIO_def_dim 
+    - \ref PIO_def_var
+    - \ref PIO_get_att
+    - \ref PIO_put_att
+  \section api_decomp Distributed Arrays
+    - \ref PIO_initdecomp
+    - \ref PIO_freedecomp
+    - \ref PIO_setframe
+    - \ref PIO_read_darray
+    - \ref PIO_write_darray
+    - \ref PIO_get_local_array_size
+  \section standard_arrays Standard Arrays
+    - \ref PIO_get_var
+    - \ref PIO_put_var
+  \section utility Errors
+    - \ref PIO_seterrorhandling
+    - \ref PIO_setdebuglevel
+
+Also see: http://www.unidata.ucar.edu/software/netcdf/docs/
 
 */

src/clib/pio_darray.c

@@ -14,12 +14,11 @@
 #include <uthash.h>
 
 /**
- * @defgroup PIO_read_darray_c Reading Distributes Arrays in C
- * Read data from a netCDF file to a distributed array with the C API.
+ * @defgroup PIO_read_darray_c Reading Distributes Arrays
+ * Read data from a netCDF file to a distributed array in C.
  *
- * @defgroup PIO_write_darray_c Writing Distributes Arrays in C
- * Write data from a distributed array to a netCDF file with the C
- * API.
+ * @defgroup PIO_write_darray_c Writing Distributes Arrays
+ * Write data from a distributed array to a netCDF file in C.
  */
 
 /** 10MB default limit. */

src/clib/pio_file.c

@@ -8,17 +8,17 @@
 #include <uthash.h>
 
 /**
- * @defgroup PIO_open_file_c Open a File in C
- * Open an existing netCDF file with PIO with the C API.
+ * @defgroup PIO_open_file_c Open a File
+ * Open an existing netCDF file with PIO in C.
  *
- * @defgroup PIO_create_file_c Create a File in C
- * Create a new netCDF file with PIO with the C API.
+ * @defgroup PIO_create_file_c Create a File
+ * Create a new netCDF file with PIO in C.
  *
- * @defgroup PIO_sync_file_c Sync a File in C
- * Flush buffers and sync data to disk with the C API.
+ * @defgroup PIO_sync_file_c Sync a File
+ * Flush buffers and sync data to disk in C.
  *
- * @defgroup PIO_close_file_c Close a File in C
- * Close a file with the C API.
+ * @defgroup PIO_close_file_c Close a File
+ * Close a file in C.
  *
  */
 

src/clib/pio_get_nc.c

@@ -12,7 +12,8 @@
 #include <pio_internal.h>
 
 /**
- * @addtogroup PIO_get_var_c Get Data from a Variable
+ * @addtogroup PIO_get_var_c Read Data
+ * Read data from a variable in C.
  * @{
  */
 

src/clib/pio_nc.c

@@ -19,51 +19,51 @@
 #include <pio_internal.h>
 
 /**
- * @defgroup PIO_inq_c Learn About File in C
+ * @defgroup PIO_inq_c Learn About File
  * Learn the number of variables, dimensions, and global atts, and the
- * unlimited dimension.
+ * unlimited dimension in C.
  *
- * @defgroup PIO_typelen_c Learn Aboue a Data Type in C
- * Learn the length of a data type.
+ * @defgroup PIO_typelen_c Learn Aboue a Data Type
+ * Learn the length of a data type in C.
  *
- * @defgroup PIO_inq_format_c Learn About Binary Format in C
- * Learn about the binary format.
+ * @defgroup PIO_inq_format_c Learn About Binary Format
+ * Learn about the binary format in C.
  *
- * @defgroup PIO_inq_dim_c Learn About a Dimension in C
- * Learn dimension name and length.
+ * @defgroup PIO_inq_dim_c Learn About a Dimension
+ * Learn dimension name and length in C.
  *
- * @defgroup PIO_inq_var_c Learn About a Variable in C
- * Learn variable name, dimensions, and type.
+ * @defgroup PIO_inq_var_c Learn About a Variable
+ * Learn variable name, dimensions, and type in C.
  *
- * @defgroup PIO_inq_att_c Learn About an Attribute in C
- * Learn length, type, and name of an attribute.
+ * @defgroup PIO_inq_att_c Learn About an Attribute
+ * Learn length, type, and name of an attribute in C.
  *
- * @defgroup PIO_rename_dim_c Rename a Dimension in C
- * Rename a dimension.
+ * @defgroup PIO_rename_dim_c Rename a Dimension
+ * Rename a dimension in C.
  *
- * @defgroup PIO_rename_var_c Rename a Variable in C
- * Rename a variable.
+ * @defgroup PIO_rename_var_c Rename a Variable
+ * Rename a variable in C.
  *
- * @defgroup PIO_rename_att_c Rename an Attribute in C
- * Rename an attribute.
+ * @defgroup PIO_rename_att_c Rename an Attribute
+ * Rename an attribute in C.
  *
- * @defgroup PIO_del_att_c Delete an Attribute in C
- * Delete an attribute.
+ * @defgroup PIO_del_att_c Delete an Attribute
+ * Delete an attribute in C.
  *
- * @defgroup PIO_set_fill_c Set Fill Value in C
- * Set the fill value for a variable.
+ * @defgroup PIO_set_fill_c Set Fill Value
+ * Set the fill value for a variable in C.
  *
- * @defgroup PIO_enddef_c End Define Mode in C
- * End define mode.
+ * @defgroup PIO_enddef_c End Define Mode
+ * End define mode in C.
  *
- * @defgroup PIO_redef_c Re-enter Define Mode in C
- * Re-enter Define Mode.
+ * @defgroup PIO_redef_c Re-enter Define Mode
+ * Re-enter Define Mode in C.
  *
- * @defgroup PIO_def_dim_c Define a Dimension in C
- * Define a new dimension in the file.
+ * @defgroup PIO_def_dim_c Define a Dimension
+ * Define a new dimension in the file in C.
  *
- * @defgroup PIO_def_var_c Define a Variable in C
- * Define a new variable in the file.
+ * @defgroup PIO_def_var_c Define a Variable
+ * Define a new variable in the file in C.
  */
 
 /**
@@ -2633,6 +2633,7 @@ PIOc_inq_var_fill(int ncid, int varid, int *no_fill, void *fill_valuep)
 
 /**
  * @addtogroup PIO_get_att_c Get Attribute Values
+ * Get the values stored in an attribute in C.
  * @{
  */
 
@@ -2925,6 +2926,7 @@ PIOc_get_att_float(int ncid, int varid, const char *name, float *ip)
 
 /**
  * @addtogroup PIO_put_att_c Write an Attribute
+ * Create an attribute in C.
  * @{
  */
 

src/clib/pio_put_nc.c

@@ -11,7 +11,8 @@
 #include <pio_internal.h>
 
 /**
- * @addtogroup PIO_put_var_c Write Data to a Variable
+ * @addtogroup PIO_put_var_c Write Data
+ * Write data to a Variable in C.
  * @{
  */
 

src/clib/pioc.c

@@ -13,38 +13,38 @@
 /**
  * @defgroup PIO_init_c Initialize the IO System
  * Initialize the IOSystem, including specifying number of IO and
- * computation tasks.
+ * computation tasks in C.
  *
- * @defgroup PIO_finalize_c Shut Down the IO System in C
- * Shut down an IOSystem, freeing all associated resources.
+ * @defgroup PIO_finalize_c Shut Down the IO System
+ * Shut down an IOSystem, freeing all associated resources in C.
  *
  * @defgroup PIO_initdecomp_c Initialize a Decomposition
- * Intiailize a decomposition of data into distributed arrays.
+ * Intiailize a decomposition of data into distributed arrays in C.
  *
- * @defgroup PIO_freedecomp_c Free a Decomposition in C
- * Free a decomposition, and associated resources.
+ * @defgroup PIO_freedecomp_c Free a Decomposition
+ * Free a decomposition, and associated resources in C.
  *
- * @defgroup PIO_setframe_c Set the Record Number in C
+ * @defgroup PIO_setframe_c Set the Record Number
  * Set the record number for a future call to PIOc_write_darray() or
- * PIOc_read_darray().
+ * PIOc_read_darray() in C.
  *
- * @defgroup PIO_set_hint_c Set a Hint in C
- * Set an MPI Hint.
+ * @defgroup PIO_set_hint_c Set a Hint
+ * Set an MPI Hint in C.
  *
- * @defgroup PIO_error_method_c Set Error Handling in C
- * Set the error handling method in case error is encountered.
+ * @defgroup PIO_error_method_c Set Error Handling
+ * Set the error handling method in case error is encountered in C.
  *
- * @defgroup PIO_get_local_array_size_c Get the Local Size in C
- * Get the local size of a distributed array.
+ * @defgroup PIO_get_local_array_size_c Get the Local Size
+ * Get the local size of a distributed array in C.
  *
- * @defgroup PIO_iosystem_is_active_c Check IOSystem in C
- * Is the IO system active?
+ * @defgroup PIO_iosystem_is_active_c Check IOSystem
+ * Is the IO system active (in C)?
  *
- * @defgroup PIO_getnumiotasks_c Get Number IO Tasks in C
- * Get the Number of IO Tasks.
+ * @defgroup PIO_getnumiotasks_c Get Number IO Tasks
+ * Get the Number of IO Tasks in C.
  *
- * @defgroup PIO_set_blocksize_c Set Blocksize in C
- * Set the Blocksize.
+ * @defgroup PIO_set_blocksize_c Set Blocksize
+ * Set the Blocksize in C.
  */
 
 /** The default error handler used when iosystem cannot be located. */

src/flib/pio.F90

@@ -5,8 +5,8 @@
 !<
 
 !>
-!! @defgroup PIO_set_blocksize PIO_set_blocksize
-!! Set the box rearranger blocksize.
+!! @defgroup PIO_set_blocksize Box Rearranger Settings
+!! Set the box rearranger blocksize in Fortran.
 
 module pio
 ! Package all exposed variables and functions under one roof