eina: enhance doxygen in eina_magic.h
Summary: Add @brief for brief description Add @details for detailed description Add @note for noted description Add [in] & [out] for parameters Add @see more Add links for EINA_TRUE, EINA_FALSE, etc. Fix indentation & Fix typeof Use @p instead of @a for the consistency Reviewers: raster, cedric Reviewed By: cedric Subscribers: cedric Differential Revision: https://phab.enlightenment.org/D1620 Signed-off-by: Cedric BAIL <cedric@osg.samsung.com>
This commit is contained in:
Tae-Hwan Kim
Cedric BAIL
parent
2dad982410
commit
339ae93f82
|
|
@ -35,28 +35,28 @@
|
|||
* going to add EINA_MAGIC to our classes:
|
||||
* @until struct _pilot pilot
|
||||
* @note The values of BASETYPE_MAGIC and SUBTYPE_MAGIC have no meaning, the
|
||||
* only important thing about them is that they be unique.
|
||||
* only important thing about them is that they are unique.
|
||||
*
|
||||
* Here we have a function to create a perso given a name, nothing too fancy:
|
||||
* Here we have a function to create a person given a name, nothing too fancy:
|
||||
* @until }
|
||||
*
|
||||
* And now the counterpart, a function the free a person.
|
||||
* And now the counterpart, a function to free a person.
|
||||
* @until {
|
||||
* Before we start releasing resources we check that the pointer we were given
|
||||
* actually points to a person, and if not we will print an error message and
|
||||
* Before we start releasing resources we check that the pointer we are given
|
||||
* actually points to a person, and if not we print an error message and
|
||||
* quit:
|
||||
* @until }
|
||||
* @note EINA_MAGIC_FAIL is a macro that make's it easy to print an appropriate
|
||||
* @note EINA_MAGIC_FAIL is a macro that makes it easy to print an appropriate
|
||||
* (and consistent) error message.
|
||||
* Now knowing that ptr is indeed of type person we prooced to set EINA_MAGIC to
|
||||
* EINA_MAGIC_NONE and free alocated memory:
|
||||
* Now knowing that ptr is indeed of type person we proceed to set EINA_MAGIC to
|
||||
* EINA_MAGIC_NONE and free the allocated memory:
|
||||
* @until }
|
||||
* @note Setting EINA_MAGIC to EINA_MAGIC_NONE is important to prevent the
|
||||
* struct from being used after freed.
|
||||
* struct from being used after it is freed.
|
||||
*
|
||||
* Now we have our function to create a pilot, this one is a little more complex
|
||||
* because we need to set EINA_MAGIC for the pilot and pilot->base, this is very
|
||||
* important so that checking the EINA_MAGIC of (person*)my_pilot will work:
|
||||
* important so that checking the EINA_MAGIC of (person*)my_pilot works:
|
||||
* @until }
|
||||
*
|
||||
* The function to free a pilot is not too different from the one that frees a
|
||||
|
|
@ -69,7 +69,7 @@
|
|||
* @until }
|
||||
* @until }
|
||||
*
|
||||
* And on to our main function where we declare some variables and initialize
|
||||
* And for our main function where we declare some variables and initialize
|
||||
* Eina:
|
||||
* @until eina_init
|
||||
*
|
||||
|
|
@ -81,10 +81,10 @@
|
|||
* can set the name without eina making a copy of the string:
|
||||
* @until static_set
|
||||
*
|
||||
* Now we create a person, a pilot and print both as persons:
|
||||
* Now we create a person, a pilot, and print both as persons:
|
||||
* @until person *
|
||||
*
|
||||
* Now we try to print both as pilots, which will obvisouly not work since base
|
||||
* Now we try to print both as pilots, which obviously does not work since base
|
||||
* is not a pilot:
|
||||
* @until pilot(sub
|
||||
*
|
||||
|
|
@ -93,36 +93,34 @@
|
|||
*
|
||||
* See full source @ref eina_magic_example_01_c "here".
|
||||
*/
|
||||
|
||||
/**
|
||||
* @page eina_magic_example_01_c Eina_Magic
|
||||
* @include eina_magic_01.c
|
||||
* @example eina_magic_01.c
|
||||
*/
|
||||
/**
|
||||
* @addtogroup Eina_Tools_Group Tools
|
||||
*
|
||||
* @{
|
||||
*/
|
||||
|
||||
/**
|
||||
* @defgroup Eina_Magic_Group Magic
|
||||
* @ingroup Eina_Tools_Group
|
||||
*
|
||||
* @brief Eina_Magic provides run-time type-checking.
|
||||
* @brief #Eina_Magic provides run-time type-checking.
|
||||
*
|
||||
* C is a weak statically typed language, in other words, it will just check for
|
||||
* types during compile time and any cast will make the compiler believe the
|
||||
* type is correct.
|
||||
* C is a weak statically typed language, in other words, it just checks for
|
||||
* types during compile time and any cast that makes the compiler believe the
|
||||
* type is correct.
|
||||
*
|
||||
* In real world code we often need to deal with casts, either explicit or
|
||||
* implicit by means of @c void*. We also need to resort to casts when doing
|
||||
* In the real world code, we often need to deal with casts, either explicit or
|
||||
* implicit, by means of @c void*. We also need to resort to casts when doing
|
||||
* inheritance in C.
|
||||
*
|
||||
* Eina_Magic give us a way to do casts and still be certain of the type we are
|
||||
* opearting on.
|
||||
* Eina_Magic gives us a way to do casts and still be certain of the type we are
|
||||
* operating on.
|
||||
*
|
||||
* @note It should be noted that it is considered good practice to @b disable
|
||||
* Eina_Magic for production code. The reasoning is that any Eina_Magic errors
|
||||
* @note It should be noted that it is considered a good practice to @b disable
|
||||
* #Eina_Magic for production code. The reasoning is that any #Eina_Magic errors
|
||||
* should have been caught during testing and therefore there is no reason to
|
||||
* incur the performance downside of Eina_Magic.
|
||||
* incur the performance downside of #Eina_Magic.
|
||||
*
|
||||
* An @ref eina_magic_example_01_page "example" should elucidate matters.
|
||||
*
|
||||
|
|
@ -130,42 +128,42 @@
|
|||
*/
|
||||
|
||||
/**
|
||||
* An abstract type for a magic number.
|
||||
* @brief An abstract type for a magic number.
|
||||
*/
|
||||
typedef unsigned int Eina_Magic;
|
||||
|
||||
/**
|
||||
* @brief Return the string associated to the given magic identifier.
|
||||
* @brief Gets the string associated to the given magic identifier.
|
||||
*
|
||||
* @param magic The magic identifier.
|
||||
* @return The string associated to the identifier.
|
||||
* @param[in] magic The magic identifier
|
||||
* @return The string associated to the identifier
|
||||
*
|
||||
* This function returns the string associated to @p magic. Even if none are
|
||||
* found this function still returns non @c NULL, in this case an identifier
|
||||
* such as "(none)", "(undefined)" or "(unknown)".
|
||||
* @details This function returns the string associated to @p magic. Even if none are
|
||||
* found this function still returns non @c NULL, in this case an identifier
|
||||
* such as "(none)", "(undefined)", or "(unknown)".
|
||||
*
|
||||
* The following identifiers may be returned whenever magic is
|
||||
* invalid, with their meanings:
|
||||
* @note The following identifiers may be returned whenever magic is
|
||||
* invalid, with their meanings:
|
||||
*
|
||||
* - (none): no magic was registered exists at all.
|
||||
* - (undefined): magic was registered and found, but no string associated.
|
||||
* - (unknown): magic was not found in the registry.
|
||||
* - (none): No magic that had been registered exists at all.
|
||||
* - (undefined): Magic is registered and found, but no string is associated.
|
||||
* - (unknown): Magic is not found in the registry.
|
||||
*
|
||||
* @warning The returned value must not be freed.
|
||||
*/
|
||||
EAPI const char *eina_magic_string_get(Eina_Magic magic) EINA_WARN_UNUSED_RESULT;
|
||||
/**
|
||||
* @brief Set the string associated to the given magic identifier.
|
||||
* @brief Sets the string associated to the given magic identifier.
|
||||
*
|
||||
* @param magic The magic identifier.
|
||||
* @param magic_name The string associated to the identifier, must not
|
||||
* be @c NULL.
|
||||
* @param[in] magic The magic identifier
|
||||
* @param[in] magic_name The string associated to the identifier, must not
|
||||
* be @c NULL
|
||||
*
|
||||
* @return #EINA_TRUE on success, #EINA_FALSE on failure.
|
||||
* @return #EINA_TRUE on success, otherwise #EINA_FALSE on failure
|
||||
*
|
||||
* This function sets the string @p magic_name to @p magic. It is not
|
||||
* checked if number or string are already set, in which case you will end with
|
||||
* duplicates. Internally, eina will make a copy of @p magic_name.
|
||||
* @details This function sets the string @p magic_name to @p magic. It is not
|
||||
* checked if number or string are already set, in which case you end with
|
||||
* duplicates. Internally, eina makes a copy of @p magic_name.
|
||||
*
|
||||
* @see eina_magic_string_static_set()
|
||||
*/
|
||||
|
|
@ -173,18 +171,18 @@ EAPI Eina_Bool eina_magic_string_set(Eina_Magic magic,
|
|||
const char *magic_name) EINA_ARG_NONNULL(2);
|
||||
|
||||
/**
|
||||
* @brief Set the string associated to the given magic identifier.
|
||||
* @brief Sets the string associated to the given magic identifier.
|
||||
*
|
||||
* @param magic The magic identifier.
|
||||
* @param magic_name The string associated to the identifier, must not be
|
||||
* @c NULL.
|
||||
* @param[in] magic The magic identifier
|
||||
* @param[in] magic_name The string associated to the identifier, must not be
|
||||
* @c NULL
|
||||
*
|
||||
* @return #EINA_TRUE on success, #EINA_FALSE on failure.
|
||||
* @return #EINA_TRUE on success, otherwise #EINA_FALSE on failure
|
||||
*
|
||||
* This function sets the string @p magic_name to @p magic. It is not checked if
|
||||
* number or string are already set, in which case you might end with
|
||||
* duplicates. Eina will @b not make a copy of @p magic_name, this means that
|
||||
* @p magic_name has to be a valid pointer for as long as @p magic is used.
|
||||
* @details This function sets the string @p magic_name to @p magic. It is not checked if
|
||||
* number or string are already set, in which case you might end with
|
||||
* duplicates. Eina does @b not make a copy of @p magic_name, this means that
|
||||
* @p magic_name has to be a valid pointer for as long as @p magic is used.
|
||||
*
|
||||
* @see eina_magic_string_set()
|
||||
*/
|
||||
|
|
@ -193,23 +191,27 @@ EAPI Eina_Bool eina_magic_string_static_set(Eina_Magic magic,
|
|||
|
||||
/**
|
||||
* @def EINA_MAGIC_NONE
|
||||
* Random value for specifying that a structure using the magic
|
||||
* feature has already been freed. It is used by eina_magic_fail().
|
||||
* @brief Definition of a random value for specifying that a structure using the magic
|
||||
* feature has already been freed. It is used by eina_magic_fail().
|
||||
*
|
||||
* If the magic feature of Eina is disabled, #EINA_MAGIC_NONE is just
|
||||
* @c 0.
|
||||
* @note If the magic feature of Eina is disabled, #EINA_MAGIC_NONE is just
|
||||
* @c 0.
|
||||
*/
|
||||
#define EINA_MAGIC_NONE 0x1234fedc
|
||||
|
||||
/**
|
||||
* @var EINA_ERROR_MAGIC_FAILED
|
||||
* @brief The error identifier corresponding to the magic check failure.
|
||||
*/
|
||||
EAPI extern Eina_Error EINA_ERROR_MAGIC_FAILED;
|
||||
|
||||
#ifdef EINA_MAGIC_DEBUG
|
||||
|
||||
/**
|
||||
* @def EINA_MAGIC
|
||||
* Declaration of a variable of type #Eina_Magic. To put in a structure
|
||||
* when one wants to use the magic feature of Eina with the functions
|
||||
* of that structure, like that:
|
||||
* @brief Definition of of a variable of type #Eina_Magic. To put in a structure
|
||||
* when one wants to use the magic feature of Eina with the functions
|
||||
* of that structure, like this:
|
||||
*
|
||||
* @code
|
||||
* struct Foo
|
||||
|
|
@ -220,42 +222,42 @@ EAPI extern Eina_Error EINA_ERROR_MAGIC_FAILED;
|
|||
* };
|
||||
* @endcode
|
||||
*
|
||||
* If the magic feature of Eina is disabled, #EINA_MAGIC does nothing.
|
||||
* @note If the magic feature of Eina is disabled, #EINA_MAGIC does nothing.
|
||||
*/
|
||||
#define EINA_MAGIC Eina_Magic __magic;
|
||||
|
||||
/**
|
||||
* @def EINA_MAGIC_SET(d, m)
|
||||
* Set the magic number of @p d to @p m. @p d must be a valid pointer
|
||||
* to a structure holding an Eina magic number declaration.
|
||||
* Use #EINA_MAGIC to add such declaration.
|
||||
* @brief Definition to set the magic number of @p d to @p m. @p d must be a valid pointer
|
||||
* to a structure holding an Eina magic number declaration.
|
||||
* Use #EINA_MAGIC to add such a declaration.
|
||||
*
|
||||
* If the magic feature of Eina is disabled, #EINA_MAGIC_CHECK is just
|
||||
* the value @c 0.
|
||||
* @note If the magic feature of Eina is disabled, #EINA_MAGIC_CHECK is just
|
||||
* the value @c 0.
|
||||
*/
|
||||
#define EINA_MAGIC_SET(d, m) (d)->__magic = (m)
|
||||
|
||||
/**
|
||||
* @def EINA_MAGIC_CHECK(d, m)
|
||||
* Test if @p d is @c NULL or not, and if not @c NULL, if
|
||||
* @p d->__eina_magic is equal to @p m. @p d must be a structure that
|
||||
* holds an Eina magic number declaration. Use #EINA_MAGIC to add such
|
||||
* declaration.
|
||||
* @brief Definition to test if @p d is @c NULL or not, and if not @c NULL, if
|
||||
* @p d->__eina_magic is equal to @p m. @p d must be a structure that
|
||||
* holds an Eina magic number declaration. Use #EINA_MAGIC to add such a
|
||||
* declaration.
|
||||
*
|
||||
* If the magic feature of Eina is disabled, #EINA_MAGIC_CHECK is just
|
||||
* the value @c 1.
|
||||
* @note If the magic feature of Eina is disabled, #EINA_MAGIC_CHECK is just
|
||||
* the value @c 1.
|
||||
*/
|
||||
#define EINA_MAGIC_CHECK(d, m) (EINA_LIKELY((d) && ((d)->__magic == (m))))
|
||||
|
||||
/**
|
||||
* @def EINA_MAGIC_FAIL(d, m)
|
||||
* Call eina_magic_fail() with the parameters @p d, @p d->__magic, @p
|
||||
* m, __FILE__, __FUNCTION__ and __LINE__. @p d must be a structure that
|
||||
* holds an Eina magic number declaration. Use #EINA_MAGIC to add such
|
||||
* declaration.
|
||||
* @brief Definition to call eina_magic_fail() with the parameters @p d, @p d->__magic,
|
||||
* @p m, __FILE__, __FUNCTION__, and __LINE__. @p d must be a structure that
|
||||
* holds an Eina magic number declaration. Use #EINA_MAGIC to add such a
|
||||
* declaration.
|
||||
*
|
||||
* If the magic feature of Eina is disabled, #EINA_MAGIC_FAIL does
|
||||
* nothing.
|
||||
* @note If the magic feature of Eina is disabled, #EINA_MAGIC_FAIL does
|
||||
* nothing.
|
||||
*/
|
||||
#define EINA_MAGIC_FAIL(d, m) \
|
||||
eina_magic_fail((void *)(d), \
|
||||
|
|
@ -266,30 +268,30 @@ EAPI extern Eina_Error EINA_ERROR_MAGIC_FAILED;
|
|||
__LINE__);
|
||||
|
||||
/**
|
||||
* @brief Display a message or abort if a magic check failed.
|
||||
* @brief Displays a message or aborts if a magic check failed.
|
||||
*
|
||||
* @param d The checked data pointer.
|
||||
* @param m The magic identifer to check.
|
||||
* @param req_m The requested magic identifier to check.
|
||||
* @param file The file in which the magic check failed.
|
||||
* @param fnc The function in which the magic check failed.
|
||||
* @param line The line at which the magic check failed.
|
||||
* @param[in] d The checked data pointer
|
||||
* @param[in] m The magic identifier to check
|
||||
* @param[in] req_m The requested magic identifier to check
|
||||
* @param[in] file The file in which the magic check failed
|
||||
* @param[in] fnc The function in which the magic check failed
|
||||
* @param[in] line The line at which the magic check failed
|
||||
*
|
||||
* @warning You should @b strongly consider using @ref EINA_MAGIC_FAIL(d, m)
|
||||
* instead.
|
||||
* instead.
|
||||
*
|
||||
* This function displays an error message if a magic check has
|
||||
* failed, using the following logic in the following order:
|
||||
* @details This function displays an error message if a magic check has
|
||||
* failed, using the following logic in the following order:
|
||||
* @li If @p d is @c NULL, a message warns about a @c NULL pointer.
|
||||
* @li Otherwise, if @p m is equal to #EINA_MAGIC_NONE, a message
|
||||
* warns about a handle that was already freed.
|
||||
* warns about a handle that is already freed.
|
||||
* @li Otherwise, if @p m is equal to @p req_m, a message warns about
|
||||
* a handle that is of wrong type.
|
||||
* @li Otherwise, a message warns you about ab-using that function...
|
||||
* a handle that is of the wrong type.
|
||||
* @li Otherwise, a message warns you about abusing that function...
|
||||
*
|
||||
* If the environment variable EINA_LOG_ABORT is set, abort() is
|
||||
* called and the program stops. It is useful for debugging programs
|
||||
* with gdb.
|
||||
* @note If the environment variable EINA_LOG_ABORT is set, abort() is
|
||||
* called and the program stops. It is useful for debugging programs
|
||||
* with gdb.
|
||||
*/
|
||||
EAPI void eina_magic_fail(void *d, Eina_Magic m, Eina_Magic req_m,
|
||||
const char *file, const char *fnc,
|
||||
|
|
@ -314,10 +316,6 @@ EAPI void eina_magic_fail(void *d, Eina_Magic m, Eina_Magic req_m,
|
|||
|
||||
#endif
|
||||
|
||||
/**
|
||||
* @}
|
||||
*/
|
||||
|
||||
/**
|
||||
* @}
|
||||
*/
|
||||
|
|
|
|||
Loading…
Reference in New Issue