more C API documentation

rfiorella · May 22, 2019 · 828cc91 · 828cc91
1 parent 31ec493
commit 828cc91
Show file tree

Hide file tree

Showing 7 changed files with 51 additions and 37 deletions.
diff --git a/doc/Makefile.am b/doc/Makefile.am
@@ -6,6 +6,7 @@
 check: all
 all:
 	doxygen Doxyfile
+	cat doxywarn.log
 	[ ! -s doxywarn.log ]
 
 SUBDIRS = source

diff --git a/doc/source/api.txt b/doc/source/api.txt
@@ -1,14 +1,14 @@
  /*!  \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_system PIO startup and shutdown routines
-     - \ref PIO_init
-     - \ref PIO_finalize
   \section api_decomp PIO decomposition routines
     - \ref PIO_initdecomp
     - \ref PIO_freedecomp

diff --git a/doc/source/c_api.txt b/doc/source/c_api.txt
@@ -1,20 +1,20 @@
  /*!  \page c_api PIO C Interface
   This is a list of all user interface routines:
 
-  \section api_fileops_c PIO file Operations
+  \section api_system_c PIO Startup and Shutdown
+     - \ref PIO_init_c
+     - \ref PIO_finalize_c
+  \section api_fileops_c PIO File Operations
      - \ref PIO_open_file_c
      - \ref PIO_create_file_c
      - \ref PIO_sync_file_c
      - \ref PIO_close_file_c
-  \section api_system_c PIO startup and shutdown routines
-     - \ref PIO_init
-     - \ref PIO_finalize
-  \section api_decomp_c PIO decomposition routines
-    - \ref PIO_initdecomp
-    - \ref PIO_freedecomp
-  \section readwrite_c Reading and Writing distributed variables
-    - \ref PIO_read_darray
-    - \ref PIO_write_darray
+  \section api_decomp_c PIO Decompositions
+    - \ref PIO_initdecomp_c
+    - \ref PIO_freedecomp_c
+  \section readwrite_c Reading and Writing Distributed Arrays
+    - \ref PIO_read_darray_c
+    - \ref PIO_write_darray_c
   \section utility_c Utility routines
     - \ref PIO_set_hint_grp
     - \ref PIO_setframe

diff --git a/src/clib/pio_darray.c b/src/clib/pio_darray.c
@@ -13,6 +13,11 @@
 #include <pio_internal.h>
 #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
+ */
+
 /** 10MB default limit. */
 PIO_Offset pio_buffer_size_limit = PIO_BUFFER_SIZE;
 
@@ -103,7 +108,7 @@ PIOc_set_buffer_size_limit(PIO_Offset limit)
  * the fill value to be used for missing data.
  * @param flushtodisk non-zero to cause buffers to be flushed to disk.
  * @return 0 for success, error code otherwise.
- * @ingroup PIO_write_darray
+ * @ingroup PIO_write_darray_c
  * @author Jim Edwards, Ed Hartnett
  */
 int
@@ -412,7 +417,7 @@ PIOc_write_darray_multi(int ncid, const int *varids, int ioid, int nvars,
  * @param fillvalue Pointer that will get the fill value.
  *
  * @return 0 for success, error code otherwise.
- * @ingroup PIO_write_darray
+ * @ingroup PIO_write_darray_c
  * @author Ed Hartnett
  */
 static int
@@ -514,7 +519,7 @@ pio_inq_var_fill_expected(int ncid, int varid, int pio_type, PIO_Offset type_siz
  * @param varid the variable ID.
  * @param vdesc pointer to var_desc_t info for this var.
  * @returns 0 for success, non-zero error code for failure.
- * @ingroup PIO_write_darray
+ * @ingroup PIO_write_darray_c
  * @author Ed Hartnett
  */
 int
@@ -608,7 +613,7 @@ find_var_fillvalue(file_desc_t *file, int varid, var_desc_t *vdesc)
  * @param fillvalue pointer to the fill value to be used for missing
  * data.
  * @returns 0 for success, non-zero error code for failure.
- * @ingroup PIO_write_darray
+ * @ingroup PIO_write_darray_c
  * @author Jim Edwards, Ed Hartnett
  */
 int
@@ -854,7 +859,7 @@ PIOc_write_darray(int ncid, int varid, int ioid, PIO_Offset arraylen, void *arra
  * pointer to the distributed portion of the array that is on this
  * processor.
  * @return 0 for success, error code otherwise.
- * @ingroup PIO_read_darray
+ * @ingroup PIO_read_darray_c
  * @author Jim Edwards, Ed Hartnett
  */
 int

diff --git a/src/clib/pio_darray_int.c b/src/clib/pio_darray_int.c
@@ -318,7 +318,7 @@ int get_vard_mpidatatype(io_desc_t *iodesc, MPI_Offset gdim0, PIO_Offset unlimdi
  * @param count an already-allocated array which gets the count
  * values.
  * @return 0 for success, error code otherwise.
- * @ingroup PIO_write_darray
+ * @ingroup PIO_write_darray_c
  * @author Ed Hartnett
  */
 int
@@ -394,7 +394,7 @@ find_start_count(int ndims, int fndims, var_desc_t *vdesc,
  * @param frame the record dimension for each of the nvars variables
  * in iobuf. NULL if this iodesc contains non-record vars.
  * @return 0 for success, error code otherwise.
- * @ingroup PIO_write_darray
+ * @ingroup PIO_write_darray_c
  * @author Jim Edwards, Ed Hartnett
  */
 int
@@ -745,7 +745,7 @@ write_darray_multi_par(file_desc_t *file, int nvars, int fndims, const int *vari
  * fndims * maxregions. This array will get the count values for all
  * regions.
  * @returns 0 for success, error code otherwise.
- * @ingroup PIO_read_darray
+ * @ingroup PIO_read_darray_c
  * @author Jim Edwards, Ed Hartnett
  **/
 int
@@ -813,7 +813,7 @@ find_all_start_count(io_region *region, int maxregions, int fndims,
  * than IO task 0. It is called by write_darray_multi_serial().
  *
  * @return 0 for success, error code otherwise.
- * @ingroup PIO_write_darray
+ * @ingroup PIO_write_darray_c
  * @author Jim Edwards, Ed Hartnett
  */
 int
@@ -893,7 +893,7 @@ send_all_start_count(iosystem_desc_t *ios, io_desc_t *iodesc, PIO_Offset llen,
  * less than blocksize*numiotasks then some iotasks will have a NULL
  * iobuf.
  * @return 0 for success, error code otherwise.
- * @ingroup PIO_write_darray
+ * @ingroup PIO_write_darray_c
  * @author Jim Edwards, Ed Hartnett
  */
 int
@@ -1053,7 +1053,7 @@ recv_and_write_data(file_desc_t *file, const int *varids, const int *frame,
  * @param frame the record dimension for each of the nvars variables
  * in iobuf. NULL if this iodesc contains non-record vars.
  * @return 0 for success, error code otherwise.
- * @ingroup PIO_write_darray
+ * @ingroup PIO_write_darray_c
  * @author Jim Edwards, Ed Hartnett
  */
 int
@@ -1146,7 +1146,7 @@ write_darray_multi_serial(file_desc_t *file, int nvars, int fndims, const int *v
  * less than blocksize*numiotasks then some iotasks will have a NULL
  * iobuf.
  * @return 0 on success, error code otherwise.
- * @ingroup PIO_read_darray
+ * @ingroup PIO_read_darray_c
  * @author Jim Edwards, Ed Hartnett
  */
 int
@@ -1419,7 +1419,7 @@ pio_read_darray_nc(file_desc_t *file, io_desc_t *iodesc, int vid, void *iobuf)
  * less than blocksize * numiotasks then some iotasks will have a NULL
  * iobuf.
  * @returns 0 for success, error code otherwise.
- * @ingroup PIO_read_darray
+ * @ingroup PIO_read_darray_c
  * @author Jim Edwards, Ed Hartnett
  */
 int
@@ -1716,7 +1716,7 @@ pio_read_darray_nc_serial(file_desc_t *file, io_desc_t *iodesc, int vid,
  * @param force true to force the flushing of the buffer
  * @param addsize additional size to add to buffer (in bytes)
  * @return 0 for success, error code otherwise.
- * @ingroup PIO_write_darray
+ * @ingroup PIO_write_darray_c
  * @author Jim Edwards, Ed Hartnett
  */
 int
@@ -1837,7 +1837,7 @@ flush_output_buffer(file_desc_t *file, bool force, PIO_Offset addsize)
  *
  * @param ios pointer to the IO system structure
  * @param collective true if collective report is desired
- * @ingroup PIO_write_darray
+ * @ingroup PIO_write_darray_c
  * @author Jim Edwards
  */
 void
@@ -1887,7 +1887,7 @@ cn_buffer_report(iosystem_desc_t *ios, bool collective)
  * non zero), this function does nothing.
  *
  * @param ios pointer to the IO system structure.
- * @ingroup PIO_write_darray
+ * @ingroup PIO_write_darray_c
  * @author Jim Edwards
  */
 void
@@ -1914,7 +1914,7 @@ free_cn_buffer_pool(iosystem_desc_t *ios)
  * @param wmb pointer to the wmulti_buffer structure.
  * @param flushtodisk if true, then flush data to disk.
  * @returns 0 for success, error code otherwise.
- * @ingroup PIO_write_darray
+ * @ingroup PIO_write_darray_c
  * @author Jim Edwards, Ed Hartnett
  */
 int
@@ -1977,7 +1977,7 @@ flush_buffer(int ncid, wmulti_buffer *wmb, bool flushtodisk)
  * @param nvars number of variables.
  * @param direction sort direction.
  * @returns 0 for success, error code otherwise.
- * @ingroup PIO_write_darray
+ * @ingroup PIO_write_darray_c
  * @author Jim Edwards
  */
 int

diff --git a/src/clib/pioc.c b/src/clib/pioc.c
@@ -10,6 +10,13 @@
 #include <pio.h>
 #include <pio_internal.h>
 
+/**
+ * @defgroup PIO_init_c Initialize the IO System
+ * @defgroup PIO_finalize_c Shut Down the IO System
+ * @defgroup PIO_initdecomp_c Initialize a Decomposition
+ * @defgroup PIO_freedecomp_c Free a Decomposition
+ */
+
 /** The default error handler used when iosystem cannot be located. */
 int default_error_handler = PIO_INTERNAL_ERROR;
 
@@ -440,7 +447,7 @@ compare( const void* a, const void* b)
  * rearranger is used. If NULL and SUBSET rearranger is used, the
  * iostarts are generated.
  * @returns 0 on success, error code otherwise
- * @ingroup PIO_initdecomp
+ * @ingroup PIO_initdecomp_c
  * @author Jim Edwards, Ed Hartnett
  */
 int
@@ -704,7 +711,7 @@ PIOc_InitDecomp(int iosysid, int pio_type, int ndims, const int *gdimlen, int ma
  * @param iocount An array of count values for block cyclic
  * decompositions. If NULL ???
  * @returns 0 on success, error code otherwise
- * @ingroup PIO_initdecomp
+ * @ingroup PIO_initdecomp_c
  * @author Jim Edwards, Ed Hartnett
  */
 int
@@ -757,7 +764,7 @@ PIOc_init_decomp(int iosysid, int pio_type, int ndims, const int *gdimlen, int m
  * @param count count array
  * @param ioidp pointer that gets the IO ID.
  * @returns 0 for success, error code otherwise
- * @ingroup PIO_initdecomp
+ * @ingroup PIO_initdecomp_c
  * @author Jim Edwards
  */
 int
@@ -861,7 +868,7 @@ PIOc_InitDecomp_bc(int iosysid, int pio_type, int ndims, const int *gdimlen,
  * until the decomposition is initialized.
  * @param iosysidp index of the defined system descriptor.
  * @return 0 on success, otherwise a PIO error code.
- * @ingroup PIO_init
+ * @ingroup PIO_init_c
  * @author Jim Edwards, Ed Hartnett
  */
 int
@@ -1094,7 +1101,7 @@ PIOc_set_hint(int iosysid, const char *hint, const char *hintval)
  *
  * @param iosysid: the io system ID provided by PIOc_Init_Intracomm().
  * @returns 0 for success or non-zero for error.
- * @ingroup PIO_finalize
+ * @ingroup PIO_finalize_c
  * @author Jim Edwards, Ed Hartnett
  */
 int
@@ -1351,7 +1358,7 @@ PIOc_iotype_available(int iotype)
  * gets the iosysid for each component.
  *
  * @return PIO_NOERR on success, error code otherwise.
- * @ingroup PIO_init
+ * @ingroup PIO_init_c
  * @author Ed Hartnett
  */
 int

diff --git a/src/clib/pioc_support.c b/src/clib/pioc_support.c
@@ -757,6 +757,7 @@ free_region_list(io_region *top)
  * @param iosysid the IO system ID.
  * @param ioid the ID of the decomposition map to free.
  * @returns 0 for success, error code otherwise.
+ * @ingroup PIO_freedecomp_c
  * @author Jim Edwards
  */
 int