eina: enhance doxygen in eina_error.h
Summary: Arrange grouping Add @brief for brief description Add @details for detailed description Add @note for noted description Add [in] & [out] for parameters Fix indentation & Fix typeof Reviewers: raster, cedric Reviewed By: cedric Subscribers: cedric Differential Revision: https://phab.enlightenment.org/D1588 Signed-off-by: Cedric BAIL <cedric@osg.samsung.com>
This commit is contained in:
parent
76e33a2081
commit
7da1647167
|
@ -32,19 +32,18 @@
|
||||||
* The error module can provide a system that mimics the errno system
|
* The error module can provide a system that mimics the errno system
|
||||||
* of the C standard library. It consists in 2 parts:
|
* of the C standard library. It consists in 2 parts:
|
||||||
*
|
*
|
||||||
* @li a way of registering new messages with
|
* @li A way of registering new messages with
|
||||||
* eina_error_msg_register() and eina_error_msg_get(),
|
* eina_error_msg_register() and eina_error_msg_get(),
|
||||||
* @li a way of setting / getting last error message with
|
* @li A way of setting / getting the last error message with
|
||||||
* eina_error_set() / eina_error_get().
|
* eina_error_set() / eina_error_get().
|
||||||
*
|
*
|
||||||
* So one has to fisrt register all the error messages that a program
|
* So one has to first register all the error messages that a program
|
||||||
* or a lib should manage. Then, when an error can occur, use
|
* or a library should manage. Then, when an error occurs, use
|
||||||
* eina_error_set(), and when errors are managed, use
|
* eina_error_set(), and when errors are managed, use
|
||||||
* eina_error_get(). If eina_error_set() is used to set an error, do
|
* eina_error_get(). If eina_error_set() is used to set an error, do
|
||||||
* not forget to call before eina_error_set(), to remove previous set
|
* not forget to remove previous set errors before calling eina_error_set().
|
||||||
* errors.
|
|
||||||
*
|
*
|
||||||
* Here is an example of use:
|
* Here is an example for use:
|
||||||
*
|
*
|
||||||
* @include eina_error_01.c
|
* @include eina_error_01.c
|
||||||
*
|
*
|
||||||
|
@ -53,90 +52,80 @@
|
||||||
*/
|
*/
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* @addtogroup Eina_Error_Group Error
|
* @defgroup Eina_Error_Group Error
|
||||||
|
* @ingroup Eina_Tools_Group
|
||||||
*
|
*
|
||||||
* @brief These functions provide error management for projects.
|
* @brief This group discusses the functions that provide error management for projects.
|
||||||
*
|
*
|
||||||
* The Eina error module provides a way to manage errors in a simple but
|
* The Eina error module provides a way to manage errors in a simple but
|
||||||
* powerful way in libraries and modules. It is also used in Eina itself.
|
* powerful way in libraries and modules. It is also used in Eina itself.
|
||||||
* Similar to libC's @c errno and strerror() facilities, this is extensible and
|
* Similar to libC's @c errno and strerror() facilities, this is extensible and
|
||||||
* recommended for other libraries and applications.
|
* recommended for other libraries and applications as well.
|
||||||
*
|
*
|
||||||
* A simple example of how to use this can be seen @ref tutorial_error_page
|
* A simple example of how to use this can be seen @ref tutorial_error_page
|
||||||
* "here".
|
* "here".
|
||||||
*/
|
|
||||||
|
|
||||||
/**
|
|
||||||
* @addtogroup Eina_Tools_Group Tools
|
|
||||||
*
|
|
||||||
* @{
|
|
||||||
*/
|
|
||||||
|
|
||||||
/**
|
|
||||||
* @defgroup Eina_Error_Group Error
|
|
||||||
*
|
*
|
||||||
* @{
|
* @{
|
||||||
*/
|
*/
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* @typedef Eina_Error
|
* @typedef Eina_Error
|
||||||
* Error type.
|
* @brief The integer type containing the error type.
|
||||||
*/
|
*/
|
||||||
typedef int Eina_Error;
|
typedef int Eina_Error;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* @var EINA_ERROR_OUT_OF_MEMORY
|
* @var EINA_ERROR_OUT_OF_MEMORY
|
||||||
* Error identifier corresponding to a lack of memory.
|
* @brief The error identifier corresponding to lack of memory.
|
||||||
*/
|
*/
|
||||||
|
|
||||||
EAPI extern Eina_Error EINA_ERROR_OUT_OF_MEMORY;
|
EAPI extern Eina_Error EINA_ERROR_OUT_OF_MEMORY;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* @brief Register a new error type.
|
* @brief Registers a new error type.
|
||||||
*
|
*
|
||||||
* @param msg The description of the error. It will be duplicated using
|
* @param[in] msg The description of the error \n
|
||||||
* eina_stringshare_add().
|
* It is duplicated using eina_stringshare_add().
|
||||||
* @return The unique number identifier for this error.
|
* @return The unique number identifier for this error
|
||||||
*
|
*
|
||||||
* This function stores in a list the error message described by
|
* @details This function stores the error message described by
|
||||||
* @p msg. The returned value is a unique identifier greater or equal
|
* @p msg in a list. The returned value is a unique identifier greater than or equal
|
||||||
* than 1. The description can be retrieve later by passing to
|
* to @c 1. The description can be retrieved later by passing
|
||||||
* eina_error_msg_get() the returned value.
|
* the returned value to eina_error_msg_get().
|
||||||
*
|
*
|
||||||
* @see eina_error_msg_static_register()
|
* @see eina_error_msg_static_register()
|
||||||
*/
|
*/
|
||||||
EAPI Eina_Error eina_error_msg_register(const char *msg) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
|
EAPI Eina_Error eina_error_msg_register(const char *msg) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* @brief Register a new error type, statically allocated message.
|
* @brief Registers a new error type, statically allocated message.
|
||||||
*
|
*
|
||||||
* @param msg The description of the error. This string will not be
|
* @param[in] msg The description of the error \n
|
||||||
* duplicated and thus the given pointer should live during
|
* This string is not duplicated and thus
|
||||||
* usage of eina_error.
|
* the given pointer should live during the usage of eina_error.
|
||||||
* @return The unique number identifier for this error.
|
* @return The unique number identifier for this error
|
||||||
*
|
*
|
||||||
* This function stores in a list the error message described by
|
* @details This function stores the error message described by
|
||||||
* @p msg. The returned value is a unique identifier greater or equal
|
* @p msg in a list. The returned value is a unique identifier greater than or equal
|
||||||
* than 1. The description can be retrieve later by passing to
|
* to @c 1. The description can be retrieved later by passing
|
||||||
* eina_error_msg_get() the returned value.
|
* the returned value to eina_error_msg_get().
|
||||||
*
|
*
|
||||||
* @see eina_error_msg_register()
|
* @see eina_error_msg_register()
|
||||||
*/
|
*/
|
||||||
EAPI Eina_Error eina_error_msg_static_register(const char *msg) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
|
EAPI Eina_Error eina_error_msg_static_register(const char *msg) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* @brief Change the message of an already registered message
|
* @brief Changes the message of an already registered message.
|
||||||
*
|
*
|
||||||
* @param error The Eina_Error to change the message of
|
* @param[in] error The Eina_Error to change the message of
|
||||||
* @param msg The description of the error. This string will be
|
* @param[in] msg The description of the error \n
|
||||||
* duplicated only if the error was registered with @ref eina_error_msg_register
|
* This string is duplicated only if the error is registered with @ref eina_error_msg_register,
|
||||||
* otherwise it must remain intact for the duration.
|
* otherwise it must remain intact for the duration.
|
||||||
* @return #EINA_TRUE if successful, #EINA_FALSE on error.
|
* @return #EINA_TRUE if successful, otherwise #EINA_FALSE on error
|
||||||
*
|
*
|
||||||
* This function modifies the message associated with @p error and changes
|
* @details This function modifies the message associated with @p error and changes
|
||||||
* it to @p msg. If the error was previously registered by @ref eina_error_msg_static_register
|
* it to @p msg. If the error is previously registered by @ref eina_error_msg_static_register
|
||||||
* then the string will not be duplicated, otherwise the previous message
|
* then the string is not duplicated, otherwise the previous message
|
||||||
* will be unrefed and @p msg copied.
|
* is unrefed and @p msg is copied.
|
||||||
*
|
*
|
||||||
* @see eina_error_msg_register()
|
* @see eina_error_msg_register()
|
||||||
*/
|
*/
|
||||||
|
@ -144,57 +133,55 @@ EAPI Eina_Bool eina_error_msg_modify(Eina_Error error,
|
||||||
const char *msg) EINA_ARG_NONNULL(2);
|
const char *msg) EINA_ARG_NONNULL(2);
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* @brief Return the last set error.
|
* @brief Returns the last set error.
|
||||||
*
|
*
|
||||||
* @return The last error.
|
* @return The last error
|
||||||
*
|
*
|
||||||
* This function returns the last error set by eina_error_set(). The
|
* @details This function returns the last error set by eina_error_set(). The
|
||||||
* description of the message is returned by eina_error_msg_get().
|
* description of the message is returned by eina_error_msg_get().
|
||||||
*
|
*
|
||||||
* This function is thread safe @since 1.10, but slower to use.
|
* @note This function is thread safe @since 1.10, but slower to use.
|
||||||
*/
|
*/
|
||||||
EAPI Eina_Error eina_error_get(void);
|
EAPI Eina_Error eina_error_get(void);
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* @brief Set the last error.
|
* @brief Sets the last error.
|
||||||
*
|
*
|
||||||
* @param err The error identifier.
|
* @param[in] err The error identifier
|
||||||
*
|
*
|
||||||
* This function sets the last error identifier. The last error can be
|
* @details This function sets the last error identifier. The last error can be
|
||||||
* retrieved with eina_error_get().
|
* retrieved by eina_error_get().
|
||||||
*
|
*
|
||||||
* @note This is also used to clear previous errors, in that case @p err should
|
* @note This is also used to clear previous errors, in which case @p err should
|
||||||
* be @c 0.
|
* be @c 0.
|
||||||
*
|
*
|
||||||
* This function is thread safe @since 1.10, but slower to use.
|
* @note This function is thread safe @since 1.10, but slower to use.
|
||||||
*/
|
*/
|
||||||
EAPI void eina_error_set(Eina_Error err);
|
EAPI void eina_error_set(Eina_Error err);
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* @brief Return the description of the given an error number.
|
* @brief Returns the description of the given error number.
|
||||||
*
|
*
|
||||||
* @param error The error number.
|
* @param[in] error The error number
|
||||||
* @return The description of the error.
|
* @return The description of the error
|
||||||
*
|
*
|
||||||
* This function returns the description of an error that has been
|
* @details This function returns the description of an error that has been
|
||||||
* registered with eina_error_msg_register(). If an incorrect error is
|
* registered by eina_error_msg_register(). If an incorrect error is
|
||||||
* given, then @c NULL is returned.
|
* given, then @c NULL is returned.
|
||||||
*/
|
*/
|
||||||
EAPI const char *eina_error_msg_get(Eina_Error error) EINA_PURE;
|
EAPI const char *eina_error_msg_get(Eina_Error error) EINA_PURE;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* @brief Find the #Eina_Error corresponding to a message string
|
* @brief Finds the #Eina_Error corresponding to a message string.
|
||||||
* @param msg The error message string to match (NOT @c NULL)
|
*
|
||||||
* @return The #Eina_Error matching @p msg, or 0 on failure
|
* @param[in] msg The error message string to match (NOT @c NULL)
|
||||||
* This function attempts to match @p msg with its corresponding #Eina_Error value.
|
* @return The #Eina_Error matching @p msg, otherwise @c 0 on failure
|
||||||
* If no such value is found, 0 is returned.
|
*
|
||||||
|
* @details This function attempts to match @p msg with its corresponding #Eina_Error value.
|
||||||
|
* If no such value is found, @c 0 is returned.
|
||||||
*/
|
*/
|
||||||
EAPI Eina_Error eina_error_find(const char *msg) EINA_ARG_NONNULL(1) EINA_PURE;
|
EAPI Eina_Error eina_error_find(const char *msg) EINA_ARG_NONNULL(1) EINA_PURE;
|
||||||
|
|
||||||
/**
|
|
||||||
* @}
|
|
||||||
*/
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* @}
|
* @}
|
||||||
*/
|
*/
|
||||||
|
|
Loading…
Reference in New Issue