xartigas pushed a commit to branch master. http://git.enlightenment.org/core/efl.git/commit/?id=0fa18c086632ec2a37c94fa6529a00d9be3202cb
commit 0fa18c086632ec2a37c94fa6529a00d9be3202cb Author: Xavi Artigas <[email protected]> Date: Fri Mar 27 11:40:57 2020 +0100 doxygen docs: Add missing docs for core Eina types Things like EINA_LIKELY or EAPI were undocumented... --- src/lib/eina/Eina.h | 2 +- src/lib/eina/eina_types.h | 47 ++++++++++++++++++++++++++++++++++++++--------- 2 files changed, 39 insertions(+), 10 deletions(-) diff --git a/src/lib/eina/Eina.h b/src/lib/eina/Eina.h index 5169c99f03..d7b4c1911a 100644 --- a/src/lib/eina/Eina.h +++ b/src/lib/eina/Eina.h @@ -138,7 +138,7 @@ * * * @defgroup Eina_Core_Group Core - * @brief Initialization and shut down and types Etc. + * @brief Initialization, shut down and core types. * @ingroup Eina * * @defgroup Eina_Data_Types_Group Data Types diff --git a/src/lib/eina/eina_types.h b/src/lib/eina/eina_types.h index 06ce47ecdc..1f0a1053a1 100644 --- a/src/lib/eina/eina_types.h +++ b/src/lib/eina/eina_types.h @@ -63,11 +63,21 @@ * @brief Used to export functions (by changing visibility). */ # define EAPI +/** + * @def EAPI_WEAK + * @brief Weak symbol, primarily useful in defining library functions which + * can be overridden in user code. + * Note: Not supported on all platforms. + */ # define EAPI_WEAK # endif #endif -/* Weak symbols part of EFL API - Note: not weak on all platforms */ +/** + * @def EWAPI + * @brief Weak symbols part of the EFL API. + * Note: Not supported on all platforms. + */ #define EWAPI EAPI EAPI_WEAK #ifdef _WIN32 @@ -85,8 +95,8 @@ # endif # else /** - * @def EAPI - * @brief Used to export functions (by changing visibility). + * @def EXPORTAPI + * @brief An alias for #EAPI. */ # define EXPORTAPI # endif @@ -98,6 +108,11 @@ # if defined(__OPENBSD__) && (INTPTR_MAX == INT32_MAX) # define __WORDSIZE 32 # else +/** + * @def __WORDSIZE + * @brief Architecture's word size (32 or 64 bits). Defined by Eina if + * its definition cannot be found in the system's headers. + */ # define __WORDSIZE 64 # endif #endif @@ -318,7 +333,8 @@ /** * @def EINA_UNUSED - * Used to warn when an argument of the function is not used. + * Used to indicate that a function parameter is purposely unused. + * This silences some compiler's warning about unused parameters. */ # define EINA_UNUSED @@ -363,21 +379,30 @@ /** * @def EINA_PRINTF - * @param[in] fmt The format to be used. - * @param[in] arg The argument to be used. + * @brief Indicates that this function accepts a printf-style format string. + * This allows some compilers to perform additional checks on the parameters + * passed to the function. + * @param[in] fmt The 1-based index of the parameter specifying the format string. + * @param[in] arg The 1-based index of the first data parameter. */ # define EINA_PRINTF(fmt, arg) /** * @def EINA_SCANF - * @param[in] fmt The format to be used. - * @param[in] arg The argument to be used. + * @brief Indicates that this function accepts a scanf-style format string. + * This allows some compilers to perform additional checks on the parameters + * passed to the function. + * @param[in] fmt The 1-based index of the parameter specifying the format string. + * @param[in] arg The 1-based index of the first data parameter. */ # define EINA_SCANF(fmt, arg) /** * @def EINA_FORMAT - * @param[in] fmt The format to be used. + * @brief Indicates that the output of this function can be used as a format string + * in printf-style functions. Some compilers will check that the return value of + * this function is consistent with the @p fmt parameter. + * @param[in] fmt The 1-based index of the parameter specifying the format string. */ # define EINA_FORMAT(fmt) @@ -395,12 +420,16 @@ /** * @def EINA_UNLIKELY + * @brief Indicates that the expression is likely to be @c FALSE. Some compilers and + * processor architectures can then optimize the more likely path. * @param[in] exp The expression to be used. */ # define EINA_UNLIKELY(exp) exp /** * @def EINA_LIKELY + * @brief Indicates that the expression is likely to be @c TRUE. Some compilers and + * processor architectures can then optimize the more likely path. * @param[in] exp The expression to be used. */ # define EINA_LIKELY(exp) exp --
