cedric pushed a commit to branch master.
http://git.enlightenment.org/core/efl.git/commit/?id=339ae93f82919edc15eee69b16f2cb6ec87fb140
commit 339ae93f82919edc15eee69b16f2cb6ec87fb140
Author: Tae-Hwan Kim <the81....@samsung.com>
Date: Fri Oct 31 09:28:06 2014 +0100
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 <ced...@osg.samsung.com>
---
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_ */
--
