diff --git a/legacy/eina/src/include/eina_binshare.h b/legacy/eina/src/include/eina_binshare.h index 6a2f02a25d..ab6464a90c 100644 --- a/legacy/eina/src/include/eina_binshare.h +++ b/legacy/eina/src/include/eina_binshare.h @@ -53,6 +53,28 @@ #include "eina_types.h" +/** + * @page tutorial_binshare_page Binary Share Tutorial + * + * Should call eina_binshare_init() before usage and eina_binshare_shutdown() after. + * to be written... + * + */ + +/** + * @addtogroup Eina_Binshare_Group Binary Share + * + * These functions allow you to store one copy of an object, and use it + * throughout your program. + * + * This is a method to reduce the number of duplicated objects kept in + * memory. + * + * For more information, you can look at the @ref tutorial_binshare_page. + * + * @{ + */ + /** * @addtogroup Eina_Data_Types_Group Data Types * @@ -65,11 +87,81 @@ * @{ */ + +/** + * @brief Retrieve an instance of an object for use in a program. + * + * @param obj The binary object to retrieve an instance of. + * @param olen The byte size + * @return A pointer to an instance of the object on success. + * @c NULL on failure. + * + * This function retrieves an instance of @p obj. If @p obj is + * @c NULL, then @c NULL is returned. If @p obj is already stored, it + * is just returned and its reference counter is increased. Otherwise + * it is added to the objects to be searched and a duplicated object + * of @p obj is returned. + * + * This function does not check object size, but uses the + * exact given size. This can be used to share part of a larger + * object or subobject. + * + * @see eina_binshare_add() + */ EAPI const void *eina_binshare_add_length(const void *obj, unsigned int olen) EINA_PURE EINA_WARN_UNUSED_RESULT; + +/** + * Increment references of the given shared object. + * + * @param obj The shared object. + * @return A pointer to an instance of the object on success. + * @c NULL on failure. + * + * This is similar to eina_share_common_add(), but it's faster since it will + * avoid lookups if possible, but on the down side it requires the parameter + * to be shared before, in other words, it must be the return of a previous + * eina_binshare_add(). + * + * There is no unref since this is the work of eina_binshare_del(). + */ EAPI const void *eina_binshare_ref(const void *obj); + +/** + * @brief Note that the given object has lost an instance. + * + * @param obj object The given object. + * + * This function decreases the reference counter associated to @p obj + * if it exists. If that counter reaches 0, the memory associated to + * @p obj is freed. If @p obj is NULL, the function returns + * immediately. + * + * Note that if the given pointer is not shared or NULL, bad things + * will happen, likely a segmentation fault. + */ EAPI void eina_binshare_del(const void *obj); + +/** + * @brief Note that the given object @b must be shared. + * + * @param obj the shared object to know the length. It is safe to + * give NULL, in that case -1 is returned. + * @return The length of the shared object. + * + * This function is a cheap way to known the length of a shared + * object. Note that if the given pointer is not shared, bad + * things will happen, likely a segmentation fault. If in doubt, try + * strlen(). + */ EAPI int eina_binshare_length(const void *obj) EINA_WARN_UNUSED_RESULT; + +/** + * @brief Dump the contents of the share_common. + * + * This function dumps all objects in the share_common to stdout with a + * DDD: prefix per line and a memory usage summary. + */ EAPI void eina_binshare_dump(void); /** @@ -100,4 +192,8 @@ EAPI void eina_binshare_dump(void); * @} */ +/** + * @} + */ + #endif /* EINA_STRINGSHARE_H_ */ diff --git a/legacy/eina/src/include/eina_hamster.h b/legacy/eina/src/include/eina_hamster.h index 0818b15616..74bd69ea15 100644 --- a/legacy/eina/src/include/eina_hamster.h +++ b/legacy/eina/src/include/eina_hamster.h @@ -19,6 +19,14 @@ #ifndef EINA_HAMSTER_H_ #define EINA_HAMSTER_H_ +/** + * @addtogroup Eina_Hamster_Group Hamster + * + * @brief These functions provide hamster calls. + * + * @{ + */ + /** * @addtogroup Eina_Core_Group Core * @@ -31,6 +39,14 @@ * @{ */ + +/** + * @brief Get the hamster count. + * + * @return The number of available hamsters. + * + * This function returns how many hamsters you have. + */ EAPI int eina_hamster_count(void); /** @@ -41,4 +57,8 @@ EAPI int eina_hamster_count(void); * @} */ +/** + * @} + */ + #endif /* EINA_HAMSTER_H_ */ diff --git a/legacy/eina/src/lib/eina_binshare.c b/legacy/eina/src/lib/eina_binshare.c index 793650fcfd..68a82fc54d 100644 --- a/legacy/eina/src/lib/eina_binshare.c +++ b/legacy/eina/src/lib/eina_binshare.c @@ -20,13 +20,6 @@ * if not, see . */ -/** - * @page tutorial_binshare_page Binary Share Tutorial - * - * Should call eina_binshare_init() before usage and eina_binshare_shutdown() after. - * to be written... - * - */ #include "eina_share_common.h" #include "eina_unicode.h" @@ -97,33 +90,6 @@ eina_binshare_shutdown(void) * API * *============================================================================*/ -/** - * @addtogroup Eina_Binshare_Group Binary Share - * - * These functions allow you to store one copy of an object, and use it - * throughout your program. - * - * This is a method to reduce the number of duplicated objects kept in - * memory. - * - * For more information, you can look at the @ref tutorial_binshare_page. - * - * @{ - */ - -/** - * @brief Note that the given object has lost an instance. - * - * @param obj object The given object. - * - * This function decreases the reference counter associated to @p obj - * if it exists. If that counter reaches 0, the memory associated to - * @p obj is freed. If @p obj is NULL, the function returns - * immediately. - * - * Note that if the given pointer is not shared or NULL, bad things - * will happen, likely a segmentation fault. - */ EAPI void eina_binshare_del(const void *obj) { @@ -133,26 +99,6 @@ eina_binshare_del(const void *obj) eina_share_common_del(binshare_share, obj); } -/** - * @brief Retrieve an instance of an object for use in a program. - * - * @param obj The binary object to retrieve an instance of. - * @param olen The byte size - * @return A pointer to an instance of the object on success. - * @c NULL on failure. - * - * This function retrieves an instance of @p obj. If @p obj is - * @c NULL, then @c NULL is returned. If @p obj is already stored, it - * is just returned and its reference counter is increased. Otherwise - * it is added to the objects to be searched and a duplicated object - * of @p obj is returned. - * - * This function does not check object size, but uses the - * exact given size. This can be used to share part of a larger - * object or subobject. - * - * @see eina_binshare_add() - */ EAPI const void * eina_binshare_add_length(const void *obj, unsigned int olen) { @@ -162,57 +108,20 @@ eina_binshare_add_length(const void *obj, unsigned int olen) 0); } -/** - * Increment references of the given shared object. - * - * @param obj The shared object. - * @return A pointer to an instance of the object on success. - * @c NULL on failure. - * - * This is similar to eina_share_common_add(), but it's faster since it will - * avoid lookups if possible, but on the down side it requires the parameter - * to be shared before, in other words, it must be the return of a previous - * eina_binshare_add(). - * - * There is no unref since this is the work of eina_binshare_del(). - */ EAPI const void * eina_binshare_ref(const void *obj) { return eina_share_common_ref(binshare_share, obj); } -/** - * @brief Note that the given object @b must be shared. - * - * @param obj the shared object to know the length. It is safe to - * give NULL, in that case -1 is returned. - * @return The length of the shared object. - * - * This function is a cheap way to known the length of a shared - * object. Note that if the given pointer is not shared, bad - * things will happen, likely a segmentation fault. If in doubt, try - * strlen(). - */ EAPI int eina_binshare_length(const void *obj) { return eina_share_common_length(binshare_share, obj); } -/** - * @brief Dump the contents of the share_common. - * - * This function dumps all objects in the share_common to stdout with a - * DDD: prefix per line and a memory usage summary. - */ EAPI void eina_binshare_dump(void) { eina_share_common_dump(binshare_share, NULL, 0); } - -/** - * @} - */ - diff --git a/legacy/eina/src/lib/eina_hamster.c b/legacy/eina/src/lib/eina_hamster.c index 2f68777cc6..556f59f438 100644 --- a/legacy/eina/src/lib/eina_hamster.c +++ b/legacy/eina/src/lib/eina_hamster.c @@ -51,21 +51,6 @@ static int _eina_hamsters = -1; * API * *============================================================================*/ -/** - * @addtogroup Eina_Hamster_Group Hamster - * - * @brief These functions provide hamster calls. - * - * @{ - */ - -/** - * @brief Get the hamster count. - * - * @return The number of available hamsters. - * - * This function returns how many hamsters you have. - */ EAPI int eina_hamster_count(void) {