From 339ae93f82919edc15eee69b16f2cb6ec87fb140 Mon Sep 17 00:00:00 2001 From: Tae-Hwan Kim Date: Fri, 31 Oct 2014 09:28:06 +0100 Subject: [PATCH] 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 --- src/lib/eina/eina_magic.h | 204 +++++++++++++++++++++++----------------------- 1 file changed, 101 insertions(+), 103 deletions(-) diff --git a/src/lib/eina/eina_magic.h b/src/lib/eina/eina_magic.h index 847f7e0..a36a74c 100644 --- a/src/lib/eina/eina_magic.h +++ b/src/lib/eina/eina_magic.h @@ -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, @@ -318,8 +320,4 @@ EAPI void eina_magic_fail(void *d, Eina_Magic m, Eina_Magic req_m, * @} */ -/** - * @} - */ - #endif /* EINA_MAGIC_H_ */ -- 2.7.4