Skip to content

Commit

Permalink
Merge pull request ESMCI#1435 from NCAR/ejh_docs_4
Browse files Browse the repository at this point in the history 
more documentation work
  • Loading branch information
@edhartnett
edhartnett authored May 20, 2019
2 parents 52ac338 + 05e3081 commit 298090c
Show file tree
Hide file tree
Showing 5 changed files with 82 additions and 53 deletions.
21 changes: 20 additions & 1 deletion configure.ac
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -115,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

Expand Down
6 changes: 2 additions & 4 deletions doc/Doxyfile.in
View file
Original file line number Diff line number Diff line change
Expand Up @@ -769,12 +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_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@
@C_SRC_FILES@ \
@FORTRAN_SRC_FILES@


# This tag can be used to specify the character encoding of the source files
Expand Down
7 changes: 0 additions & 7 deletions src/clib/pio_internal.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down
89 changes: 53 additions & 36 deletions src/clib/pio_lists.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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);

Expand All @@ -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;

Expand All @@ -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)
Expand Down Expand Up @@ -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;
Expand All @@ -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. */
Expand All @@ -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;

Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -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;

Expand All @@ -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;

Expand All @@ -230,11 +237,12 @@ int 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
*/
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;
Expand All @@ -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;
}
Expand All @@ -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;
}
Expand All @@ -289,12 +299,17 @@ 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 the PIO type.
* @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;

Expand Down Expand Up @@ -328,7 +343,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;

Expand Down Expand Up @@ -358,7 +374,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;
Expand All @@ -371,7 +388,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);

Expand Down
12 changes: 7 additions & 5 deletions src/clib/pioc_support.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -2738,15 +2740,15 @@ 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
* component.
* @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
Expand Down

0 comments on commit 298090c

Please sign in to comment.