Merge pull request ESMCI#1476 from NCAR/ejh_even_more_docs_2

Separate vara, var, var1, vars, vard get/put functions in the docs

doc/source/c_api.txt

@@ -32,8 +32,14 @@
        - \ref PIO_def_var_c
        - \ref PIO_put_att_c
      \subsection putget_c Reading/Writing Data
+       - \ref PIO_get_vara_c
        - \ref PIO_get_var_c
+       - \ref PIO_get_var1_c
+       - \ref PIO_get_vars_c
+       - \ref PIO_put_vara_c
        - \ref PIO_put_var_c
+       - \ref PIO_put_var1_c
+       - \ref PIO_put_vars_c
      \subsection inqnc_c Learn about Files and Metadata
        - \ref PIO_inq_c
        - \ref PIO_get_att_c

src/clib/pio_get_nc.c

@@ -12,8 +12,8 @@
 #include <pio_internal.h>
 
 /**
- * @addtogroup PIO_get_var_c Read Data
- * Read data from a variable in C.
+ * @addtogroup PIO_get_vars_c Read Strided Arrays
+ * Read strided arrays of data from a variable in C.
  * @{
  */
 
@@ -345,6 +345,45 @@ int PIOc_get_vars_longlong(int ncid, int varid, const PIO_Offset *start,
     return PIOc_get_vars_tc(ncid, varid, start, count, stride, NC_INT64, buf);
 }
 
+/**
+ * Get strided, muti-dimensional subset of a variable of the same type
+ * as the variable in the file.
+ *
+ * This routine is called collectively by all tasks in the
+ * communicator ios.union_comm.
+ *
+ * @param ncid identifies the netCDF file
+ * @param varid the variable ID number
+ * @param start an array of start indicies (must have same number of
+ * entries as variable has dimensions). If NULL, indices of 0 will be
+ * used.
+ * @param count an array of counts (must have same number of entries
+ * as variable has dimensions). If NULL, counts matching the size of
+ * the variable will be used.
+ * @param stride an array of strides (must have same number of
+ * entries as variable has dimensions). If NULL, strides of 1 will be
+ * used.
+ * @param buf pointer that will get the data.
+ * @return PIO_NOERR on success, error code otherwise.
+ * @author Ed Hartnett
+ */
+int PIOc_get_vars(int ncid, int varid, const PIO_Offset *start, const PIO_Offset *count,
+                  const PIO_Offset *stride, void *buf)
+{
+    return PIOc_get_vars_tc(ncid, varid, start, count, stride, NC_NAT, buf);
+}
+
+/**
+ * @}
+ */
+
+/**
+ * @addtogroup PIO_get_vara_c Read Arrays
+ * Read arrays of data from a variable in C, specifying start and
+ * count arrays.
+ * @{
+ */
+
 /**
  * Get a muti-dimensional subset of a text variable.
  *
@@ -635,6 +674,41 @@ int PIOc_get_vara_longlong(int ncid, int varid, const PIO_Offset *start,
     return PIOc_get_vars_tc(ncid, varid, start, count, NULL, NC_INT64, buf);
 }
 
+/**
+ * Get a muti-dimensional subset of a variable the same type
+ * as the variable in the file.
+ *
+ * This routine is called collectively by all tasks in the
+ * communicator ios.union_comm.
+ *
+ * @param ncid identifies the netCDF file
+ * @param varid the variable ID number
+ * @param start an array of start indicies (must have same number of
+ * entries as variable has dimensions). If NULL, indices of 0 will be
+ * used.
+ * @param count an array of counts (must have same number of entries
+ * as variable has dimensions). If NULL, counts matching the size of
+ * the variable will be used.
+ * @param buf pointer that will get the data.
+ * @return PIO_NOERR on success, error code otherwise.
+ * @author Ed Hartnett
+ */
+int PIOc_get_vara(int ncid, int varid, const PIO_Offset *start, const PIO_Offset *count,
+                  void *buf)
+{
+    return PIOc_get_vars_tc(ncid, varid, start, count, NULL, NC_NAT, buf);
+}
+
+/**
+ * @}
+ */
+
+/**
+ * @addtogroup PIO_get_var_c Read Entire Variable
+ * Read the entire variable at one time into an array in C.
+ * @{
+ */
+
 /**
  * Get all data of a text variable.
  *
@@ -839,6 +913,34 @@ int PIOc_get_var_longlong(int ncid, int varid, long long *buf)
     return PIOc_get_var_tc(ncid, varid, NC_INT64, buf);
 }
 
+/**
+ * Get all data from a variable the same type as the variable in the
+ * file.
+ *
+ * This routine is called collectively by all tasks in the
+ * communicator ios.union_comm.
+ *
+ * @param ncid identifies the netCDF file
+ * @param varid the variable ID number
+ * @param buf pointer that will get the data.
+ * @return PIO_NOERR on success, error code otherwise.
+ * @author Ed Hartnett
+ */
+int PIOc_get_var(int ncid, int varid, void *buf)
+{
+    return PIOc_get_var_tc(ncid, varid, NC_NAT, buf);
+}
+
+/**
+ * @}
+ */
+
+/**
+ * @addtogroup PIO_get_var1_c Read One Value
+ * Read one value from a variable in C.
+ * @{
+ */
+
 /**
  * Get one value of a text variable.
  *
@@ -1083,24 +1185,6 @@ int PIOc_get_var1_longlong(int ncid, int varid, const PIO_Offset *index,
     return PIOc_get_var1_tc(ncid, varid, index, NC_INT64, buf);
 }
 
-/**
- * Get all data from a variable the same type as the variable in the
- * file.
- *
- * This routine is called collectively by all tasks in the
- * communicator ios.union_comm.
- *
- * @param ncid identifies the netCDF file
- * @param varid the variable ID number
- * @param buf pointer that will get the data.
- * @return PIO_NOERR on success, error code otherwise.
- * @author Ed Hartnett
- */
-int PIOc_get_var(int ncid, int varid, void *buf)
-{
-    return PIOc_get_var_tc(ncid, varid, NC_NAT, buf);
-}
-
 /**
  * Get one value from a variable the same type as the variable in the
  * file.
@@ -1122,59 +1206,6 @@ int PIOc_get_var1(int ncid, int varid, const PIO_Offset *index, void *buf)
     return PIOc_get_var1_tc(ncid, varid, index, NC_NAT, buf);
 }
 
-/**
- * Get a muti-dimensional subset of a variable the same type
- * as the variable in the file.
- *
- * This routine is called collectively by all tasks in the
- * communicator ios.union_comm.
- *
- * @param ncid identifies the netCDF file
- * @param varid the variable ID number
- * @param start an array of start indicies (must have same number of
- * entries as variable has dimensions). If NULL, indices of 0 will be
- * used.
- * @param count an array of counts (must have same number of entries
- * as variable has dimensions). If NULL, counts matching the size of
- * the variable will be used.
- * @param buf pointer that will get the data.
- * @return PIO_NOERR on success, error code otherwise.
- * @author Ed Hartnett
- */
-int PIOc_get_vara(int ncid, int varid, const PIO_Offset *start, const PIO_Offset *count,
-                  void *buf)
-{
-    return PIOc_get_vars_tc(ncid, varid, start, count, NULL, NC_NAT, buf);
-}
-
-/**
- * Get strided, muti-dimensional subset of a variable of the same type
- * as the variable in the file.
- *
- * This routine is called collectively by all tasks in the
- * communicator ios.union_comm.
- *
- * @param ncid identifies the netCDF file
- * @param varid the variable ID number
- * @param start an array of start indicies (must have same number of
- * entries as variable has dimensions). If NULL, indices of 0 will be
- * used.
- * @param count an array of counts (must have same number of entries
- * as variable has dimensions). If NULL, counts matching the size of
- * the variable will be used.
- * @param stride an array of strides (must have same number of
- * entries as variable has dimensions). If NULL, strides of 1 will be
- * used.
- * @param buf pointer that will get the data.
- * @return PIO_NOERR on success, error code otherwise.
- * @author Ed Hartnett
- */
-int PIOc_get_vars(int ncid, int varid, const PIO_Offset *start, const PIO_Offset *count,
-                  const PIO_Offset *stride, void *buf)
-{
-    return PIOc_get_vars_tc(ncid, varid, start, count, stride, NC_NAT, buf);
-}
-
 /**
  * @}
  */

src/clib/pio_get_vard.c

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