From 527b9993d5e85baffb667db3a2b6b3e75b8cfb5c Mon Sep 17 00:00:00 2001 From: Ed Hartnett Date: Sun, 19 May 2019 09:42:16 -0600 Subject: [PATCH 1/4] documentation fixes --- src/clib/pio_internal.h | 7 ---- src/clib/pio_lists.c | 86 ++++++++++++++++++++++++----------------- src/clib/pioc_support.c | 6 ++- 3 files changed, 55 insertions(+), 44 deletions(-) diff --git a/src/clib/pio_internal.h b/src/clib/pio_internal.h index 84af1407042..77ed1233717 100644 --- a/src/clib/pio_internal.h +++ b/src/clib/pio_internal.h @@ -224,13 +224,6 @@ extern "C" { /* Free a region list. */ void free_region_list(io_region *top); - /* Check and reset, if needed, rearranger opts to default values. */ - int check_and_reset_rearr_opts(rearr_opt_t *rearr_opt); - - /* Compare rearranger flow control options. */ - bool cmp_rearr_comm_fc_opts(const rearr_comm_fc_opt_t *opt, - const rearr_comm_fc_opt_t *exp_opt); - /* Create a subset rearranger. */ int subset_rearrange_create(iosystem_desc_t *ios, int maplen, PIO_Offset *compmap, const int *gsize, int ndim, io_desc_t *iodesc); diff --git a/src/clib/pio_lists.c b/src/clib/pio_lists.c index 3ac5baea25a..77bf81f527e 100644 --- a/src/clib/pio_lists.c +++ b/src/clib/pio_lists.c @@ -21,7 +21,8 @@ static file_desc_t *current_file = NULL; * @param file pointer to the file_desc_t struct for the new file. * @author Jim Edwards */ -void pio_add_to_file_list(file_desc_t *file) +void +pio_add_to_file_list(file_desc_t *file) { assert(file); @@ -43,7 +44,8 @@ void pio_add_to_file_list(file_desc_t *file) * @returns 0 for success, error code otherwise. * @author Ed Hartnett */ -int pio_get_file(int ncid, file_desc_t **cfile1) +int +pio_get_file(int ncid, file_desc_t **cfile1) { file_desc_t *cfile = NULL; @@ -57,7 +59,7 @@ int pio_get_file(int ncid, file_desc_t **cfile1) if (current_file && current_file->pio_ncid == ncid) cfile = current_file; else - HASH_FIND_INT(pio_file_list, &ncid, cfile); + HASH_FIND_INT(pio_file_list, &ncid, cfile); /* If not found, return error. */ if (!cfile) @@ -85,7 +87,8 @@ int pio_get_file(int ncid, file_desc_t **cfile1) * @returns 0 for success, error code otherwise * @author Jim Edwards, Ed Hartnett */ -int pio_delete_file_from_list(int ncid) +int +pio_delete_file_from_list(int ncid) { file_desc_t *cfile = NULL; int ret; @@ -94,24 +97,24 @@ int pio_delete_file_from_list(int ncid) if (current_file && current_file->pio_ncid == ncid) cfile = current_file; else - HASH_FIND_INT(pio_file_list, &ncid, cfile); + HASH_FIND_INT(pio_file_list, &ncid, cfile); if (cfile) { - HASH_DEL(pio_file_list, cfile); + HASH_DEL(pio_file_list, cfile); - if (current_file == cfile) - current_file = pio_file_list; + if (current_file == cfile) + current_file = pio_file_list; - /* Free the varlist entries for this file. */ - while (cfile->varlist) - if ((ret = delete_var_desc(cfile->varlist->varid, &cfile->varlist))) - return pio_err(NULL, cfile, ret, __FILE__, __LINE__); + /* Free the varlist entries for this file. */ + while (cfile->varlist) + if ((ret = delete_var_desc(cfile->varlist->varid, &cfile->varlist))) + return pio_err(NULL, cfile, ret, __FILE__, __LINE__); - /* Free the memory used for this file. */ - free(cfile); + /* Free the memory used for this file. */ + free(cfile); - return PIO_NOERR; + return PIO_NOERR; } /* No file was found. */ @@ -125,7 +128,8 @@ int pio_delete_file_from_list(int ncid) * @returns 0 on success, error code otherwise * @author Jim Edwards */ -int pio_delete_iosystem_from_list(int piosysid) +int +pio_delete_iosystem_from_list(int piosysid) { iosystem_desc_t *ciosystem, *piosystem = NULL; @@ -155,7 +159,8 @@ int pio_delete_iosystem_from_list(int piosysid) * @returns 0 on success, error code otherwise * @author Jim Edwards */ -int pio_add_to_iosystem_list(iosystem_desc_t *ios) +int +pio_add_to_iosystem_list(iosystem_desc_t *ios) { iosystem_desc_t *cios; int i = 1; @@ -189,7 +194,8 @@ int pio_add_to_iosystem_list(iosystem_desc_t *ios) * @returns pointer to iosystem_desc_t, or NULL if not found. * @author Jim Edwards */ -iosystem_desc_t *pio_get_iosystem_from_id(int iosysid) +iosystem_desc_t * +pio_get_iosystem_from_id(int iosysid) { iosystem_desc_t *ciosystem; @@ -209,7 +215,8 @@ iosystem_desc_t *pio_get_iosystem_from_id(int iosysid) * @returns 0 for success. * @author Jim Edwards */ -int pio_num_iosystem(int *niosysid) +int +pio_num_iosystem(int *niosysid) { int count = 0; @@ -234,7 +241,8 @@ int pio_num_iosystem(int *niosysid) * @returns 0 for success, error code otherwise. * @author Jim Edwards, Ed Hartnett */ -int pio_add_to_iodesc_list(io_desc_t *iodesc) +int +pio_add_to_iodesc_list(io_desc_t *iodesc) { HASH_ADD_INT(pio_iodesc_list, ioid, iodesc); current_iodesc = iodesc; @@ -248,15 +256,16 @@ int pio_add_to_iodesc_list(io_desc_t *iodesc) * @returns pointer to the iodesc struc. * @author Jim Edwards */ -io_desc_t *pio_get_iodesc_from_id(int ioid) +io_desc_t * +pio_get_iodesc_from_id(int ioid) { io_desc_t *ciodesc=NULL; if (current_iodesc && current_iodesc->ioid == ioid) - ciodesc = current_iodesc; + ciodesc = current_iodesc; else { - HASH_FIND_INT(pio_iodesc_list, &ioid, ciodesc); - current_iodesc = ciodesc; + HASH_FIND_INT(pio_iodesc_list, &ioid, ciodesc); + current_iodesc = ciodesc; } return ciodesc; } @@ -268,18 +277,19 @@ io_desc_t *pio_get_iodesc_from_id(int ioid) * @returns 0 on success, error code otherwise. * @author Jim Edwards */ -int pio_delete_iodesc_from_list(int ioid) +int +pio_delete_iodesc_from_list(int ioid) { io_desc_t *ciodesc; ciodesc = pio_get_iodesc_from_id(ioid); if (ciodesc) { - HASH_DEL(pio_iodesc_list, ciodesc); - if (current_iodesc == ciodesc) - current_iodesc = pio_iodesc_list; - free(ciodesc); - return PIO_NOERR; + HASH_DEL(pio_iodesc_list, ciodesc); + if (current_iodesc == ciodesc) + current_iodesc = pio_iodesc_list; + free(ciodesc); + return PIO_NOERR; } return PIO_EBADID; } @@ -289,12 +299,16 @@ int pio_delete_iodesc_from_list(int ioid) * * @param varid the varid of the variable. * @param rec_var non-zero if this is a record var. + * @param pio_type_size size of the PIO type in bytes + * @param mpi_type the MPI type + * @param mpi_type_size size of the MPI type in bytes. * @param varlist pointer to list to add to. * @returns 0 for success, error code otherwise. * @author Ed Hartnett */ -int add_to_varlist(int varid, int rec_var, int pio_type, int pio_type_size, MPI_Datatype mpi_type, - int mpi_type_size, var_desc_t **varlist) +int +add_to_varlist(int varid, int rec_var, int pio_type, int pio_type_size, + MPI_Datatype mpi_type, int mpi_type_size, var_desc_t **varlist) { var_desc_t *var_desc; @@ -328,7 +342,8 @@ int add_to_varlist(int varid, int rec_var, int pio_type, int pio_type_size, MPI_ * @returns 0 for success, error code otherwise. * @author Ed Hartnett */ -int get_var_desc(int varid, var_desc_t **varlist, var_desc_t **var_desc) +int +get_var_desc(int varid, var_desc_t **varlist, var_desc_t **var_desc) { var_desc_t *my_var=NULL; @@ -358,7 +373,8 @@ int get_var_desc(int varid, var_desc_t **varlist, var_desc_t **var_desc) * @returns 0 on success, error code otherwise. * @author Ed Hartnett */ -int delete_var_desc(int varid, var_desc_t **varlist) +int +delete_var_desc(int varid, var_desc_t **varlist) { var_desc_t *v; int ret; @@ -371,7 +387,7 @@ int delete_var_desc(int varid, var_desc_t **varlist) return PIO_ENOTVAR; if ((ret = get_var_desc( varid, varlist, &v))) - return ret; + return ret; HASH_DEL(*varlist, v); diff --git a/src/clib/pioc_support.c b/src/clib/pioc_support.c index 3ae2a4b1b95..f608c10880d 100644 --- a/src/clib/pioc_support.c +++ b/src/clib/pioc_support.c @@ -1199,7 +1199,8 @@ PIOc_read_nc_decomp(int iosysid, const char *filename, int *ioidp, MPI_Comm comm return ret; } -/* Write the decomp information in netCDF. This is an internal +/** + * Write the decomp information in netCDF. This is an internal * function. * * @param ios pointer to io system info. @@ -1385,7 +1386,8 @@ pioc_write_nc_decomp_int(iosystem_desc_t *ios, const char *filename, int cmode, return PIO_NOERR; } -/* Read the decomp information from a netCDF decomp file. This is an +/** + * Read the decomp information from a netCDF decomp file. This is an * internal function. * * @param iosysid the IO system ID. From dc60db67eb63db85ad7bac24b3e636f676244665 Mon Sep 17 00:00:00 2001 From: Ed Hartnett Date: Sun, 19 May 2019 09:47:09 -0600 Subject: [PATCH 2/4] last of doxygen warnings for C library --- src/clib/pio_lists.c | 5 +++-- src/clib/pioc_support.c | 6 +++--- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/src/clib/pio_lists.c b/src/clib/pio_lists.c index 77bf81f527e..2d236d5e57b 100644 --- a/src/clib/pio_lists.c +++ b/src/clib/pio_lists.c @@ -237,7 +237,7 @@ pio_num_iosystem(int *niosysid) /** * Add an iodesc. * - * @param io_desc_t pointer to data to add to list. + * @param iodesc io_desc_t pointer to data to add to list. * @returns 0 for success, error code otherwise. * @author Jim Edwards, Ed Hartnett */ @@ -299,8 +299,9 @@ pio_delete_iodesc_from_list(int ioid) * * @param varid the varid of the variable. * @param rec_var non-zero if this is a record var. + * @param pio_type the PIO type. * @param pio_type_size size of the PIO type in bytes - * @param mpi_type the MPI type + * @param mpi_type the MPI type. * @param mpi_type_size size of the MPI type in bytes. * @param varlist pointer to list to add to. * @returns 0 for success, error code otherwise. diff --git a/src/clib/pioc_support.c b/src/clib/pioc_support.c index f608c10880d..9358ea9848c 100644 --- a/src/clib/pioc_support.c +++ b/src/clib/pioc_support.c @@ -537,7 +537,7 @@ pio_err(iosystem_desc_t *ios, file_desc_t *file, int err_num, const char *fname, * @param ios pointer to the IO system info, used for error * handling. Ignored if NULL. * @param ndims the number of dimensions for the data in this region. - * @param a pointer that gets a pointer to the newly allocated + * @param regionp a pointer that gets a pointer to the newly allocated * io_region struct. * @returns 0 for success, error code otherwise. * @author Jim Edwards @@ -2740,7 +2740,7 @@ PIOc_set_rearr_opts(int iosysid, int comm_type, int fcd, bool enable_hs_c2i, * Note that memory is allocated for my_proc_list. This must be freed * by the caller. * - * @param num_io_proc the number of IO processes. + * @param num_io_procs the number of IO processes. * @param component_count the number of computational components. * @param num_procs_per_comp array (length component_count) which * contains the number of processes to assign to each computation @@ -2748,7 +2748,7 @@ PIOc_set_rearr_opts(int iosysid, int comm_type, int fcd, bool enable_hs_c2i, * @param proc_list array (length component count) of arrays (length * num_procs_per_comp_array[cmp]) which contain the list of processes * for each computation component. May be NULL. - * @param array (length component count) of arrays (length + * @param my_proc_list array (length component count) of arrays (length * num_procs_per_comp_array[cmp]) which will get the list of processes * for each computation component. * @returns 0 for success, error code otherwise From 26b530f50ad42703e6b5268793da91acd2d37d95 Mon Sep 17 00:00:00 2001 From: Ed Hartnett Date: Sun, 19 May 2019 09:55:07 -0600 Subject: [PATCH 3/4] added --enable-developer-docs option to configure --- configure.ac | 13 +++++++++++++ doc/Doxyfile.in | 5 ++--- 2 files changed, 15 insertions(+), 3 deletions(-) diff --git a/configure.ac b/configure.ac index 81dcce125bb..8e6ef0d3fe4 100644 --- a/configure.ac +++ b/configure.ac @@ -105,6 +105,19 @@ test "x$enable_docs" = xyes || enable_docs=no AC_MSG_RESULT([$enable_docs]) AM_CONDITIONAL(BUILD_DOCS, [test "x$enable_docs" = xyes]) +# Does the user want to developer documentation? +AC_MSG_CHECKING([whether PIO developer documentation should be build (only for PIO developers)]) +AC_ARG_ENABLE([developer-docs], + [AS_HELP_STRING([--enable-developer-docs], + [enable building of PIO developer documentation with doxygen.])]) +test "x$enable_developer_docs" = xyes || enable_developer_docs=no +AC_MSG_RESULT([$enable_developer_docs]) + +# Developer docs enables docs. +if test "x$enable_developer_docs" = xyes; then + enable_docs=yes +fi + # Is doxygen installed? AC_CHECK_PROGS([DOXYGEN], [doxygen]) if test -z "$DOXYGEN" -a "x$enable_docs" = xyes; then diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index 34dcdbc5946..d39cb99464f 100644 --- a/doc/Doxyfile.in +++ b/doc/Doxyfile.in @@ -770,11 +770,10 @@ WARN_LOGFILE = INPUT = @CMAKE_CURRENT_SOURCE_DIR@/../doc/source \ @CMAKE_CURRENT_SOURCE_DIR@/../src/flib \ + @CMAKE_BINARY_DIR@/src/flib \ @CMAKE_CURRENT_SOURCE_DIR@/../examples/c \ @CMAKE_CURRENT_SOURCE_DIR@/../examples/f03 \ - @CMAKE_CURRENT_SOURCE_DIR@/../src/clib \ - @CMAKE_BINARY_DIR@/src/flib \ - @C_SRC_FILES@ + @CMAKE_CURRENT_SOURCE_DIR@/../src/clib # This tag can be used to specify the character encoding of the source files From 05e3081ee72dbad6b5f37f665515f58998befee3 Mon Sep 17 00:00:00 2001 From: Ed Hartnett Date: Sun, 19 May 2019 16:18:26 -0600 Subject: [PATCH 4/4] more documentation improvements --- configure.ac | 8 +++++++- doc/Doxyfile.in | 5 ++--- 2 files changed, 9 insertions(+), 4 deletions(-) diff --git a/configure.ac b/configure.ac index 8e6ef0d3fe4..ada0f9466ed 100644 --- a/configure.ac +++ b/configure.ac @@ -128,7 +128,13 @@ fi if test "x$enable_docs" = xyes; then AC_SUBST([CMAKE_CURRENT_SOURCE_DIR], ["."]) AC_SUBST([CMAKE_BINARY_DIR], [".."]) - AC_SUBST([C_SRC_FILES], ["../src/clib/pio_nc4.c"]) + if test "x$enable_developer_docs" = xyes; then + AC_SUBST([C_SRC_FILES], ["../src/clib"]) + AC_SUBST([FORTRAN_SRC_FILES], ["../src/flib"]) + else + AC_SUBST([C_SRC_FILES], ["../src/clib/pio_nc4.c ../src/clib/pio_darray.c ../src/clib/pio_get_nc.c ../src/clib/pio_put_nc.c"]) + AC_SUBST([FORTRAN_SRC_FILES], ["../src/flib/piodarray.F90 ../src/flib/piolib_mod.F90 ../src/flib/pio_nf.F90"]) + fi AC_CONFIG_FILES([doc/Doxyfile]) fi diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index d39cb99464f..fc68b77ba94 100644 --- a/doc/Doxyfile.in +++ b/doc/Doxyfile.in @@ -769,11 +769,10 @@ WARN_LOGFILE = # Note: If this tag is empty the current directory is searched. INPUT = @CMAKE_CURRENT_SOURCE_DIR@/../doc/source \ - @CMAKE_CURRENT_SOURCE_DIR@/../src/flib \ - @CMAKE_BINARY_DIR@/src/flib \ @CMAKE_CURRENT_SOURCE_DIR@/../examples/c \ @CMAKE_CURRENT_SOURCE_DIR@/../examples/f03 \ - @CMAKE_CURRENT_SOURCE_DIR@/../src/clib + @C_SRC_FILES@ \ + @FORTRAN_SRC_FILES@ # This tag can be used to specify the character encoding of the source files