From c726dd7c622ac90515234e223e00429b46f6060f Mon Sep 17 00:00:00 2001 From: Dmitri Pal Date: Mon, 5 Apr 2010 10:59:33 -0400 Subject: [PATCH] Adding interface documentation Package refarray documentation by default --- common/Makefile.am | 2 +- common/refarray/Makefile.am | 16 ++ common/refarray/configure.ac | 5 +- .../ref_array.cfg.doxy.in} | 2 +- common/refarray/ref_array.h | 158 +++++++++++++++++--- contrib/sssd.spec.in | 1 + 6 files changed, 163 insertions(+), 21 deletions(-) copy common/{path_utils/path_utils.cfg.doxy.in => refarray/ref_array.cfg.doxy.in} (99%) diff --git a/common/Makefile.am b/common/Makefile.am index 0036bae9fe5ef885f9d53a5ad076676313a4d6fb..0227ee97983568735b1051e2ee1d23b93567a1c6 100644 --- a/common/Makefile.am +++ b/common/Makefile.am @@ -1,6 +1,6 @@ ACLOCAL_AMFLAGS = -I m4 SUBDIRS = trace collection ini dhash path_utils refarray -DOCDIRS = collection ini path_utils +DOCDIRS = collection ini path_utils refarray dist_noinst_DATA = \ m4 diff --git a/common/refarray/Makefile.am b/common/refarray/Makefile.am index 724131fe77f2fff9b281fe8d18184aa501b1297d..abda089d457517b070efa2815ab9e03263194514 100644 --- a/common/refarray/Makefile.am +++ b/common/refarray/Makefile.am @@ -34,6 +34,22 @@ check_PROGRAMS = ref_array_ut ref_array_ut_SOURCES = ref_array_ut.c ref_array_ut_LDADD = libref_array.la +if HAVE_DOXYGEN +docs: +# A temp way of building docs until we hook into the package build + rm -fR doc + mkdir -p doc + $(DOXYGEN) ref_array.cfg.doxy +else +docs: + @echo "Doxygen not installed, cannot generate documentation" + @exit 1 +endif + + TESTS = ref_array_ut tests: all $(check_PROGRAMS) + +clean-local: + rm -Rf doc diff --git a/common/refarray/configure.ac b/common/refarray/configure.ac index ebcfaa6d403666407b9f912f3fe95585a3263b45..55f539dbc73a26d193fca89c2eb5918da847b81e 100644 --- a/common/refarray/configure.ac +++ b/common/refarray/configure.ac @@ -24,6 +24,9 @@ AC_ARG_ENABLE([trace], AS_IF([test ["$trace_level" -gt "0"] -a ["$trace_level" -lt "8"] ],[AC_SUBST([TRACE_VAR],["-DTRACE_LEVEL=$trace_level"])]) -AC_CONFIG_FILES([Makefile ref_array.pc]) +AC_PATH_PROG([DOXYGEN], [doxygen], [false]) +AM_CONDITIONAL([HAVE_DOXYGEN], [test x$DOXYGEN != xfalse ]) + +AC_CONFIG_FILES([Makefile ref_array.cfg.doxy ref_array.pc]) AC_OUTPUT diff --git a/common/path_utils/path_utils.cfg.doxy.in b/common/refarray/ref_array.cfg.doxy.in similarity index 99% copy from common/path_utils/path_utils.cfg.doxy.in copy to common/refarray/ref_array.cfg.doxy.in index 90a7dd1bf8830ac75faa959270e673e787365ef4..455db0a94e69c63d4b957459f9ccbdd6557d2ef4 100644 --- a/common/path_utils/path_utils.cfg.doxy.in +++ b/common/refarray/ref_array.cfg.doxy.in @@ -25,7 +25,7 @@ DOXYFILE_ENCODING = UTF-8 # The PROJECT_NAME tag is a single word (or a sequence of words surrounded # by quotes) that should identify the project. -PROJECT_NAME = "path_utils" +PROJECT_NAME = "libref_array" # The PROJECT_NUMBER tag can be used to enter a project or revision number. # This could be handy for archiving the generated documentation or diff --git a/common/refarray/ref_array.h b/common/refarray/ref_array.h index 42112907e7d7deedb7e7f4a100ca6078cbeed132..004c460c079ac1240db380d945301b269c50ecdd 100644 --- a/common/refarray/ref_array.h +++ b/common/refarray/ref_array.h @@ -29,56 +29,178 @@ struct ref_array; #define EOK 0 #endif -/*************************************/ -/* Interface to the referenced array */ -/*************************************/ +/** @mainpage The Referenced Array Interface + * + * The referenced array interface is a dynamically allocated + * array of data of any type. The array can be shared by + * multiple objects to avoid data duplication. + * + * The array is created once and then any number of + * the references can be requested. The references are pointers + * to the array. Each reference must be freed after use. + * Freeing last reference to the array would free the array's storage. + * + * The array does not have any knowledge of the data type + * of the actual data stored in the array. All elements of the array + * are of the same size as prescribed by caller when the array is created. + * The caller can potentially mix different types of data in the array + * but this should be done with caution. + * + * At the moment the interface is not complete. + * It provides basic functionality required to support other + * components. In future it might make sense to add entry points + * to insert and delete elements from the array. + * Current use cases do not require this kind of + * functionality so it is left out of the implementation. + * + */ +/** + * @defgroup ref_array Interface + * @{ + */ + +/** + * @brief Enumeration of the delete modes + * + * When the array is destroyed each element of the array + * most likely needs to be freed. Same is true when an element + * is removed from the array. However the caller might need + * to do different things with the data depending on whether + * the array is destroyed or whether the element is removed. + * This enumeration defines constants that you used to indicate + * which operation was performed. + */ typedef enum { REF_ARRAY_DESTROY, REF_ARRAY_DELETE, } ref_array_del_enum; -/* Callback that can be provided by caller - * to free data when the storage is actually destroyed +/** + * @brief Element cleanup callback + * + * Callback that can be provided by a caller + * to free data when the storage is actually destroyed. */ typedef void (*ref_array_fn)(void *elem, ref_array_del_enum type, void *data); -/* Create referenced array */ +/** + * @brief Create referenced array + * + * @param[out] ra Newly created array object. + * @param[in] elem Element size in bytes. + * @param[in] grow_by Defines how many elements + * should be allocated together + * as one chunk. + * @param[in] cb Cleanup callback. + * @param[in] data Caller supplied data + * passed to cleanup callback. + * + * @return 0 - Success. + * @return ENOMEM - No memory. + * @return EINVAL - Invalid argument. + */ int ref_array_create(struct ref_array **ra, size_t elem, uint32_t grow_by, ref_array_fn cb, void *data); -/* Get new reference to an array */ +/** + * @brief Get new reference to an array + * + * @param[in] ra Existing array object. + * + * @return A new reference to an array object. + * @return NULL - Invalid argument. + */ struct ref_array *ref_array_getref(struct ref_array *ra); -/* Delete the array */ +/** + * @brief Delete the array + * + * @param[in] ra Existing array object + * or a reference. + * + */ void ref_array_destroy(struct ref_array *ra); -/* Add new element to the array */ +/** + * @brief Add new element to the array + * + * Appends an element to the end of the array. + * + * @param[in] ra Existing array object. + * @param[in] element Pointer to data. + * The number of bytes + * defined at the array creation + * as the array size will be copied + * into the array element. + * + * @return 0 - Success. + * @return ENOMEM - No memory. + * @return EINVAL - Invalid argument. + */ int ref_array_append(struct ref_array *ra, void *element); -/* Get element */ +/** + * @brief Get element data + * + * Retrieves data from the array element. + * + * @param[in] ra Existing array object. + * @param[in] idx Index of the array element. + * @param[in] acptr Pointer to the memory + * where the element's data + * will be copied. Can be NULL. + * In this case nothing is copied. + * + * @return Pointer to the data stored in the element. + * Conventionally it should be a const pointer, + * however such declaration would make using + * variable that receives the result of this + * function immutable. This is very inconvenient + * because such variable should be able to + * point to data related to multiple elements + * of the array. + * + * @return Pointer to the element's data. + * @return NULL if index is out of range. + */ void *ref_array_get(struct ref_array *ra, uint32_t idx, void *acptr); -/* Get array length */ +/** + * @brief Get array length + * + * Determines length of the array. + * + * @param[in] ra Existing array object. + * @param[out] len Variable will receive + * the length of the array. + * + * @return 0 - Success. + * @return EINVAL - Invalid argument. + */ int ref_array_getlen(struct ref_array *ra, uint32_t *len); -/* Alternative function to get length. - * Returns 0 if the array is invalid +/** + * @brief Array length + * + * Alternative function to get length. + * + * @param[in] ra Existing array object. + * + * @return Length of the array. Returns 0 if the array is invalid. */ uint32_t ref_array_len(struct ref_array *ra); - -/* In future in might make sense to add entry points - * to insert and delete elements from the array. - * Current use cases do not require this kind of - * functionality so it is left out of the implementation +/** + * @} */ + #endif diff --git a/contrib/sssd.spec.in b/contrib/sssd.spec.in index 98a0c43854c4fe88b10c4ef2cbaf73a3632d08cb..a5b8d5d1d10413dec10644ecc4284759e7c63a87 100644 --- a/contrib/sssd.spec.in +++ b/contrib/sssd.spec.in @@ -408,6 +408,7 @@ rm -rf $RPM_BUILD_ROOT %{_libdir}/libref_array.so %{_libdir}/pkgconfig/ref_array.pc %doc common/refarray/README +%doc common/refarray/doc/html/ %post -- 1.6.6.1