From 8374dea693e36620cde5cb0a13f11520a885aaad Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Iv=C3=A1n=20Briano?= Date: Wed, 8 Sep 2010 17:41:05 +0000 Subject: [PATCH] Evil patch from Evil vtorri. Some improvements to Eina docs. Yup, docs.. truly evil. SVN revision: 51993 --- legacy/eina/src/include/eina_file.h | 24 +- legacy/eina/src/include/eina_hash.h | 12 +- .../eina/src/include/eina_inline_rectangle.x | 102 ++++++++ legacy/eina/src/include/eina_list.h | 2 +- legacy/eina/src/include/eina_main.h | 2 +- legacy/eina/src/include/eina_rectangle.h | 5 + legacy/eina/src/lib/eina_array.c | 2 +- legacy/eina/src/lib/eina_log.c | 219 ++++++++++-------- legacy/eina/src/lib/eina_magic.c | 6 +- legacy/eina/src/lib/eina_rectangle.c | 43 ++++ 10 files changed, 302 insertions(+), 115 deletions(-) diff --git a/legacy/eina/src/include/eina_file.h b/legacy/eina/src/include/eina_file.h index b7a4ef63a6..709c69fdd0 100644 --- a/legacy/eina/src/include/eina_file.h +++ b/legacy/eina/src/include/eina_file.h @@ -41,19 +41,29 @@ */ /** - * @typedef Eina_File_Dir_List_Cb - * Type for a callback. + * @typedef Eina_File_Direct_Info + * A typedef to #_Eina_File_Direct_Info. */ typedef struct _Eina_File_Direct_Info Eina_File_Direct_Info; + +/** + * @typedef Eina_File_Dir_List_Cb + * Type for a callback to be called when iterating over the files of a + * directory. + */ typedef void (*Eina_File_Dir_List_Cb)(const char *name, const char *path, void *data); +/** + * @struct _Eina_File_Direct_Info + * A structure to store informations of a path. + */ struct _Eina_File_Direct_Info { - size_t path_length; /* size of the whole path */ - size_t name_length; /* size of the filename/basename component */ - size_t name_start; /* where the filename/basename component starts */ - char path[PATH_MAX]; - const struct dirent *dirent; + size_t path_length; /**< size of the whole path */ + size_t name_length; /**< size of the filename/basename component */ + size_t name_start; /**< where the filename/basename component starts */ + char path[PATH_MAX]; /**< the path */ + const struct dirent *dirent; /**< the dirent structure of the path */ }; /** diff --git a/legacy/eina/src/include/eina_hash.h b/legacy/eina/src/include/eina_hash.h index cb6b8fa675..03451339a9 100644 --- a/legacy/eina/src/include/eina_hash.h +++ b/legacy/eina/src/include/eina_hash.h @@ -41,13 +41,19 @@ * @{ */ +/** + * @typedef Eina_Hash + * Type for a generic hash table. + */ typedef struct _Eina_Hash Eina_Hash; + typedef struct _Eina_Hash_Tuple Eina_Hash_Tuple; + struct _Eina_Hash_Tuple { - const void *key; - void *data; - unsigned int key_length; + const void *key; /**< The key */ + void *data; /**< The data associated to the key */ + unsigned int key_length; /**< The length of the key */ }; typedef unsigned int (*Eina_Key_Length)(const void *key); diff --git a/legacy/eina/src/include/eina_inline_rectangle.x b/legacy/eina/src/include/eina_inline_rectangle.x index 8c5feaf5b9..eb0cecfa68 100644 --- a/legacy/eina/src/include/eina_inline_rectangle.x +++ b/legacy/eina/src/include/eina_inline_rectangle.x @@ -19,18 +19,53 @@ #ifndef EINA_INLINE_RECTANGLE_H__ #define EINA_INLINE_RECTANGLE_H__ +/** + * @brief Check if the given spans intersect. + * + * @param c1 The column of the first span. + * @param l1 The length of the first span. + * @param c2 The column of the second span. + * @param l2 The length of the second span. + * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * + * This function returns #EINA_TRUE if the given spans intersect, + * #EINA_FALSE otherwise. + */ static inline int eina_spans_intersect(int c1, int l1, int c2, int l2) { return (!(((c2 + l2) <= c1) || (c2 >= (c1 + l1)))); } +/** + * @brief Check if the given rectangle is empty. + * + * @param r The rectangle to check. + * @return #EINA_TRUE if the rectangle is empty, #EINA_FALSE otherwise. + * + * This function returns #EINA_TRUE if @p r is empty, #EINA_FALSE + * otherwise. No check is done on @p r, so it must be a valid + * rectangle. + */ static inline Eina_Bool eina_rectangle_is_empty(const Eina_Rectangle *r) { return ((r->w < 1) || (r->h < 1)) ? EINA_TRUE : EINA_FALSE; } +/** + * @brief Set the coordinates and size of the given rectangle. + * + * @param r The rectangle. + * @param x The top-left x coordinate of the rectangle. + * @param y The top-left y coordinate of the rectangle. + * @param w The width of the rectangle. + * @param h The height of the rectangle. + * + * This function sets its top-left x coordinate to @p x, its top-left + * y coordinate to @p y, its width to @p w and its height to @p h. No + * check is done on @p r, so it must be a valid rectangle. + */ static inline void eina_rectangle_coords_from(Eina_Rectangle *r, int x, int y, int w, int h) { @@ -40,30 +75,85 @@ eina_rectangle_coords_from(Eina_Rectangle *r, int x, int y, int w, int h) r->h = h; } +/** + * @brief Check if the given rectangles intersect. + * + * @param r1 The first rectangle. + * @param r2 The second rectangle. + * @return #EINA_TRUE if the rectangles intersect, #EINA_FALSE otherwise. + * + * This function returns #EINA_TRUE if @p r1 and @p r2 intersect, + * #EINA_FALSE otherwise. No check is done on @p r1 and @p r2, so they + * must be valid rectangles. + */ static inline Eina_Bool eina_rectangles_intersect(const Eina_Rectangle *r1, const Eina_Rectangle *r2) { return (eina_spans_intersect(r1->x, r1->w, r2->x, r2->w) && eina_spans_intersect(r1->y, r1->h, r2->y, r2->h)) ? EINA_TRUE : EINA_FALSE; } +/** + * @brief Check if the given x-coordinate is in the rectangle . + * + * @param r The rectangle. + * @param x The x coordinate. + * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * + * This function returns #EINA_TRUE if @p x is in @p r with respect to + * the horizontal direction, #EINA_FALSE otherwise. No check is done + * on @p r, so it must be a valid rectangle. + */ static inline Eina_Bool eina_rectangle_xcoord_inside(const Eina_Rectangle *r, int x) { return ((x >= r->x) && (x < (r->x + r->w))) ? EINA_TRUE : EINA_FALSE; } +/** + * @brief Check if the given y-coordinate is in the rectangle . + * + * @param r The rectangle. + * @param y The y coordinate. + * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * + * This function returns #EINA_TRUE if @p y is in @p r with respect to + * the vertical direction, #EINA_FALSE otherwise. No check is done + * on @p r, so it must be a valid rectangle. + */ static inline Eina_Bool eina_rectangle_ycoord_inside(const Eina_Rectangle *r, int y) { return ((y >= r->y) && (y < (r->y + r->h))) ? EINA_TRUE : EINA_FALSE; } +/** + * @brief Check if the given point is in the rectangle . + * + * @param r The rectangle. + * @param x The x coordinate of the point. + * @param y The y coordinate of the point. + * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * + * This function returns #EINA_TRUE if the point of coordinate (@p x, + * @p y) is in @p r, #EINA_FALSE otherwise. No check is done on @p r, + * so it must be a valid rectangle. + */ static inline Eina_Bool eina_rectangle_coords_inside(const Eina_Rectangle *r, int x, int y) { return (eina_rectangle_xcoord_inside(r, x) && eina_rectangle_ycoord_inside(r, y)) ? EINA_TRUE : EINA_FALSE; } +/** + * @brief Get the union of two rectangles. + * + * @param dst The first rectangle. + * @param src The second rectangle. + * + * This function get the union of the rectangles @dst and @p src. The + * result is stored in @p dst. No check is done on @p dst or @p src, + * so they must be valid rectangles. + */ static inline void eina_rectangle_union(Eina_Rectangle *dst, const Eina_Rectangle *src) { @@ -87,6 +177,18 @@ eina_rectangle_union(Eina_Rectangle *dst, const Eina_Rectangle *src) dst->h = src->y + src->h; } +/** + * @brief Get the intersection of two rectangles. + * + * @param dst The first rectangle. + * @param src The second rectangle. + * @return #EINA_TRUE if the rectangles intersect, #EINA_FALSE + * otherwise. + * + * This function get the intersection of the rectangles @p dst and + * @p src. The result is stored in @p dst. No check is done on @p dst + * or @p src, so they must be valid rectangles. + */ static inline Eina_Bool eina_rectangle_intersection(Eina_Rectangle *dst, const Eina_Rectangle *src) { diff --git a/legacy/eina/src/include/eina_list.h b/legacy/eina/src/include/eina_list.h index a549076851..835422d418 100644 --- a/legacy/eina/src/include/eina_list.h +++ b/legacy/eina/src/include/eina_list.h @@ -58,7 +58,7 @@ typedef struct _Eina_List_Accounting Eina_List_Accounting; * @struct _Eina_List * Type for a generic double linked list. */ -struct _Eina_List /** A linked list node */ +struct _Eina_List { void *data; /**< Pointer to list element payload */ Eina_List *next; /**< Next member in the list */ diff --git a/legacy/eina/src/include/eina_main.h b/legacy/eina/src/include/eina_main.h index 81d6d44acd..db80042465 100644 --- a/legacy/eina/src/include/eina_main.h +++ b/legacy/eina/src/include/eina_main.h @@ -46,7 +46,7 @@ #define EINA_VERSION_MINOR 0 /** - * @struct Eina_Version + * @typedef Eina_Version * The version of Eina. */ typedef struct _Eina_Version diff --git a/legacy/eina/src/include/eina_rectangle.h b/legacy/eina/src/include/eina_rectangle.h index 4ce3955d53..a9daf66672 100644 --- a/legacy/eina/src/include/eina_rectangle.h +++ b/legacy/eina/src/include/eina_rectangle.h @@ -34,6 +34,7 @@ */ /** + * @typedef Eina_Rectangle * Simple rectangle structure. */ typedef struct _Eina_Rectangle @@ -44,6 +45,10 @@ typedef struct _Eina_Rectangle int h; /**< height of rectangle */ } Eina_Rectangle; +/** + * @typedef Eina_Rectangle_Pool + * Type for an opaque pool of rectangle. + */ typedef struct _Eina_Rectangle_Pool Eina_Rectangle_Pool; static inline int eina_spans_intersect(int c1, int l1, int c2, int l2) EINA_WARN_UNUSED_RESULT; diff --git a/legacy/eina/src/lib/eina_array.c b/legacy/eina/src/lib/eina_array.c index 5eced22cfd..704b74f32c 100644 --- a/legacy/eina/src/lib/eina_array.c +++ b/legacy/eina/src/lib/eina_array.c @@ -449,7 +449,7 @@ eina_array_free(Eina_Array *array) * @brief Set the step of an array. * * @param array The array. - * @param sizeof_array Should be the value returned by sizeof (Eina_Array). + * @param sizeof_eina_array Should be the value returned by sizeof(Eina_Array). * @param step The count of pointers to add when increasing the array size. * * This function sets the step of @p array to @p step. For performance diff --git a/legacy/eina/src/lib/eina_log.c b/legacy/eina/src/lib/eina_log.c index 73888d80cf..a461c11147 100644 --- a/legacy/eina/src/lib/eina_log.c +++ b/legacy/eina/src/lib/eina_log.c @@ -1408,6 +1408,103 @@ eina_log_term_color_supported(const char *term) } } +static inline void +eina_log_domain_unregister_unlocked(int domain) +{ + Eina_Log_Domain *d; + + if ((unsigned int)domain >= _log_domains_count) + return; + + d = &_log_domains[domain]; + eina_log_domain_free(d); + d->deleted = 1; +} + +static inline void +eina_log_print_unlocked(int domain, + Eina_Log_Level level, + const char *file, + const char *fnc, + int line, + const char *fmt, + va_list args) +{ + Eina_Log_Domain *d; + +#ifdef EINA_SAFETY_CHECKS + if (EINA_UNLIKELY((unsigned int)domain >= _log_domains_count) || + EINA_UNLIKELY(domain < 0)) + { + if (file && fnc && fmt) + fprintf( + stderr, + "CRI: %s:%d %s() eina_log_print() unknown domain %d, original message format '%s'\n", + file, + line, + fnc, + domain, + fmt); + else + fprintf( + stderr, + "CRI: eina_log_print() unknown domain %d, original message format '%s'\n", + domain, + fmt ? fmt : ""); + + if (_abort_on_critical) + abort(); + + return; + } + +#endif + d = _log_domains + domain; +#ifdef EINA_SAFETY_CHECKS + if (EINA_UNLIKELY(d->deleted)) + { + fprintf(stderr, + "ERR: eina_log_print() domain %d is deleted\n", + domain); + return; + } + +#endif + + if (level > d->level) + return; + +#ifdef _WIN32 + { + char *wfmt; + char *tmp; + + wfmt = strdup(fmt); + if (!wfmt) + { + fprintf(stderr, "ERR: %s: can not allocate memory\n", __FUNCTION__); + return; + } + + tmp = wfmt; + while (strchr(tmp, "%")) + { + tmp++; + if (*tmp == 'z') + *tmp = 'I'; + } + _print_cb(d, level, file, fnc, line, wfmt, _print_cb_data, args); + free(wfmt); + } +#else + _print_cb(d, level, file, fnc, line, fmt, _print_cb_data, args); +#endif + + if (EINA_UNLIKELY(_abort_on_critical) && + EINA_UNLIKELY(level <= _abort_level_on_critical)) + abort(); +} + /** * @endcond */ @@ -1732,6 +1829,9 @@ eina_log_threads_enable(void) /** * Sets logging method to use. * + * @param cb The callback to call when printing a log. + * @param data The data to pass to the callback. + * * By default, eina_log_print_cb_stderr() is used. * * @note MT: safe to call from any thread. @@ -1983,20 +2083,6 @@ eina_log_domain_register(const char *name, const char *color) return r; } - -static inline void -eina_log_domain_unregister_unlocked(int domain) -{ - Eina_Log_Domain *d; - - if ((unsigned int)domain >= _log_domains_count) - return; - - d = &_log_domains[domain]; - eina_log_domain_free(d); - d->deleted = 1; -} - /** * Forget about a logging domain registered by eina_log_domain_register() * @@ -2018,7 +2104,7 @@ eina_log_domain_unregister(int domain) * Set the domain level given its name. * * This call has the same effect as setting - * EINA_LOG_LEVELS=: + * EINA_LOG_LEVELS=<@p domain_name>:<@p level> * * @param domain_name domain name to change the level. It may be of a * still not registered domain. If the domain is not registered @@ -2193,6 +2279,15 @@ eina_log_print_cb_stderr(const Eina_Log_Domain *d, /** * Alternative logging method, this will output to standard output stream. * + * @param d The domain. + * @param level The level. + * @param file The file which is logged. + * @param fnc The function which is logged. + * @param line The line which is logged. + * @param fmt The ouptut format to use. + * @param data Not used. + * @param args The arguments needed by the format. + * * This method will colorize output based on domain provided color and * message logging level. To disable color, set environment variable * EINA_LOG_COLOR_DISABLE=1. Similarly, to disable file and line @@ -2225,6 +2320,15 @@ eina_log_print_cb_stdout(const Eina_Log_Domain *d, /** * Alternative logging method, this will output to given file stream. * + * @param d The domain. + * @param level Not used. + * @param file The file which is logged. + * @param fnc The function which is logged. + * @param line The line which is logged. + * @param fmt The ouptut format to use. + * @param data The file which will store the output (as a FILE *). + * @param args The arguments needed by the format. + * * This method will never output color. * * @note MT: if threads are enabled, this function is called within locks. @@ -2265,90 +2369,6 @@ end: putc('\n', f); } -static inline void -eina_log_print_unlocked(int domain, - Eina_Log_Level level, - const char *file, - const char *fnc, - int line, - const char *fmt, - va_list args) -{ - Eina_Log_Domain *d; - -#ifdef EINA_SAFETY_CHECKS - if (EINA_UNLIKELY((unsigned int)domain >= _log_domains_count) || - EINA_UNLIKELY(domain < 0)) - { - if (file && fnc && fmt) - fprintf( - stderr, - "CRI: %s:%d %s() eina_log_print() unknown domain %d, original message format '%s'\n", - file, - line, - fnc, - domain, - fmt); - else - fprintf( - stderr, - "CRI: eina_log_print() unknown domain %d, original message format '%s'\n", - domain, - fmt ? fmt : ""); - - if (_abort_on_critical) - abort(); - - return; - } - -#endif - d = _log_domains + domain; -#ifdef EINA_SAFETY_CHECKS - if (EINA_UNLIKELY(d->deleted)) - { - fprintf(stderr, - "ERR: eina_log_print() domain %d is deleted\n", - domain); - return; - } - -#endif - - if (level > d->level) - return; - -#ifdef _WIN32 - { - char *wfmt; - char *tmp; - - wfmt = strdup(fmt); - if (!wfmt) - { - fprintf(stderr, "ERR: %s: can not allocate memory\n", __FUNCTION__); - return; - } - - tmp = wfmt; - while (strchr(tmp, "%")) - { - tmp++; - if (*tmp == 'z') - *tmp = 'I'; - } - _print_cb(d, level, file, fnc, line, wfmt, _print_cb_data, args); - free(wfmt); - } -#else - _print_cb(d, level, file, fnc, line, fmt, _print_cb_data, args); -#endif - - if (EINA_UNLIKELY(_abort_on_critical) && - EINA_UNLIKELY(level <= _abort_level_on_critical)) - abort(); -} - /** * Print out log message using given domain and level. * @@ -2422,6 +2442,7 @@ eina_log_print(int domain, Eina_Log_Level level, const char *file, * @param line originating line in @a file. * @param fmt printf-like format to use. Should not provide trailing * '\n' as it is automatically included. + * @param args the arguments needed by the format. * * @note MT: this function may be called from different threads if * eina_log_threads_enable() was called before. diff --git a/legacy/eina/src/lib/eina_magic.c b/legacy/eina/src/lib/eina_magic.c index be10303df1..83cd247d26 100644 --- a/legacy/eina/src/lib/eina_magic.c +++ b/legacy/eina/src/lib/eina_magic.c @@ -220,10 +220,10 @@ eina_magic_string_shutdown(void) * }; * @endcode * - * It is perfectly valid to use @c{struct subtype} blobs for functions - * that expect @c{struct base}, since the fields will have the same + * It is perfectly valid to use @c {struct subtype} blobs for functions + * that expect @c {struct base}, since the fields will have the same * offset (as base member is the first, at offset 0). We could give - * the functions the @c{&subtype->base} and avoid the cast, but often + * the functions the @c {&subtype->base} and avoid the cast, but often * we just cast. * * In any case, we might be safe and check if the given pointer is diff --git a/legacy/eina/src/lib/eina_rectangle.c b/legacy/eina/src/lib/eina_rectangle.c index 58b4131df0..cb04ae8d3f 100644 --- a/legacy/eina/src/lib/eina_rectangle.c +++ b/legacy/eina/src/lib/eina_rectangle.c @@ -376,6 +376,17 @@ eina_rectangle_free(Eina_Rectangle *rect) } } +/** + * @brief Add a rectangle in a new pool. + * + * @param w The width of the rectangle. + * @param h The height of the rectangle. + * @return A newly allocated pool on success, @c NULL otherwise. + * + * This function adds the rectangle of size (@p width, @p height) to a + * new pool. If the pool can not be created, @c NULL is + * returned. Otherwise the newly allocated pool is returned. + */ EAPI Eina_Rectangle_Pool * eina_rectangle_pool_new(int w, int h) { @@ -400,6 +411,14 @@ eina_rectangle_pool_new(int w, int h) return new; } +/** + * @brief Free the given pool. + * + * @param pool The pool to free. + * + * This function frees the allocated data of @p pool. If @p pool is + * @c NULL, ths function returned immediatly. + */ EAPI void eina_rectangle_pool_free(Eina_Rectangle_Pool *pool) { @@ -442,6 +461,21 @@ eina_rectangle_pool_count(Eina_Rectangle_Pool *pool) return pool->references; } +/** + * @brief Request a rectangle of given size in the given pool. + * + * @param pool The pool. + * @param w The width of the rectangle to request. + * @param h The height of the rectangle to request. + * @return The requested rectangle on success, @c NULL otherwise. + * + * This function retrieve from @p pool the rectangle of width @p w and + * height @p h. If @p pool is @c NULL, or @p w or @p h are non-positive, + * the function returns @c NULL. If @p w or @p h are greater than the + * pool size, the function returns @c NULL. On success, the function + * returns the rectangle which matches the size (@p w, @p h). + * Otherwise it returns @c NULL. + */ EAPI Eina_Rectangle * eina_rectangle_pool_request(Eina_Rectangle_Pool *pool, int w, int h) { @@ -503,6 +537,15 @@ eina_rectangle_pool_request(Eina_Rectangle_Pool *pool, int w, int h) return rect; } +/** + * @brief Remove the given rectangle from the pool. + * + * @param rect The rectangle to remove from the pool. + * + * This function removes @p rect from the pool. If @p rect is + * @c NULL, the function returns immediatly. Otherwise it remoes @p + * rect from the pool. + */ EAPI void eina_rectangle_pool_release(Eina_Rectangle *rect) {