cedric pushed a commit to branch master. http://git.enlightenment.org/core/efl.git/commit/?id=cf5192025f3aa21115580aa6577eb0f12c2f6ec2
commit cf5192025f3aa21115580aa6577eb0f12c2f6ec2 Author: Jeff Grimshaw <[email protected]> Date: Thu Mar 20 16:35:41 2014 +0900 efl/eina: General cleanup of Eina documentation Summary: I've combed through the Eina source files and made enhancements to the documentation, including: - Document the undocumented - Fixed some errors in Doxygen markup - Moved some function documentation from implementation (.c or .x) to definition (.h) - Edited some of the entries to improve clarity Test Plan: Reviewers Reviewers: cedric Reviewed By: cedric CC: cedric Differential Revision: https://phab.enlightenment.org/D639 --- src/lib/eina/eina_accessor.h | 1 + src/lib/eina/eina_alloca.h | 4 + src/lib/eina/eina_array.h | 128 +++++++++++++----- src/lib/eina/eina_binbuf.h | 2 +- src/lib/eina/eina_clist.h | 7 +- src/lib/eina/eina_convert.h | 6 +- src/lib/eina/eina_cow.h | 2 + src/lib/eina/eina_file.h | 74 ++++++----- src/lib/eina/eina_file_common.h | 272 +++++++++++++++++++++++++++++++++------ src/lib/eina/eina_hash.h | 86 ++++++++++++- src/lib/eina/eina_inarray.h | 1 + src/lib/eina/eina_inline_array.x | 61 +-------- src/lib/eina/eina_inlist.h | 6 +- src/lib/eina/eina_lalloc.h | 53 ++++++++ src/lib/eina/eina_list.h | 14 +- src/lib/eina/eina_log.h | 58 ++++++--- src/lib/eina/eina_types.h | 5 + 17 files changed, 581 insertions(+), 199 deletions(-) diff --git a/src/lib/eina/eina_accessor.h b/src/lib/eina/eina_accessor.h index 3de6e42..7e24779 100644 --- a/src/lib/eina/eina_accessor.h +++ b/src/lib/eina/eina_accessor.h @@ -157,6 +157,7 @@ typedef Eina_Accessor* (*Eina_Accessor_Clone_Callback)(Eina_Accessor *it); * Type to provide random access to data structures. * * If creating an accessor remember to set the type using @ref EINA_MAGIC_SET. + * */ struct _Eina_Accessor { diff --git a/src/lib/eina/eina_alloca.h b/src/lib/eina/eina_alloca.h index bb52955..53e706f 100644 --- a/src/lib/eina/eina_alloca.h +++ b/src/lib/eina/eina_alloca.h @@ -39,6 +39,10 @@ # ifdef __cplusplus extern "C" # endif +/** + * Allocates memory in the stack frame of the caller, so it's automatically + * freed when the caller returns. See alloca(3) for detials. + */ void *alloca (long); # endif #endif diff --git a/src/lib/eina/eina_array.h b/src/lib/eina/eina_array.h index 5a5199e..07234cd 100644 --- a/src/lib/eina/eina_array.h +++ b/src/lib/eina/eina_array.h @@ -49,13 +49,13 @@ * Before we can start using any array function we need to initialize eina: * @until eina_init * - * So now to actually creating our array. The only interesting thing here is the - * argument given to the eina_array_new() function, this argument sets how fast + * So now to actually create our array. The only interesting thing here is the + * argument given to the eina_array_new() function. This argument sets how fast * the array grows. * @until array_new * * If you know before hand how big the array will need to be you should set the - * step to that. In our case we can set it to the number of string we have and + * step to that. In our case we can set it to the number of strings we have and * since we didn't do that in the eina_array_new() we can do it now: * @until array_step_set * @@ -82,8 +82,8 @@ * And finally shutdown eina and exit: * @until } * - * The full source code can be found on the examples folder - * on the @ref eina_array_01_c "eina_array_01.c" file. + * The full source code can be found in the examples folder + * in the @ref eina_array_01_c "eina_array_01.c" file. */ /** @@ -102,7 +102,7 @@ * @until Eina.h * * This the callback we are going to use to decide which strings stay on the - * array and which will be removed, we use something simple, but this can be as + * array and which will be removed. We use something simple, but this can be as * complex as you like: * @until } * @@ -127,8 +127,8 @@ * Since this time we didn't use strdup we don't need to free each string: * @until } * - * The full source code can be found on the examples folder - * on the @ref eina_array_02_c "eina_array_02.c" file. + * The full source code can be found in the examples folder + * in the @ref eina_array_02_c "eina_array_02.c" file. */ /** @@ -146,7 +146,7 @@ * The Array data type in Eina is designed to have very fast access to * its data (compared to the Eina @ref Eina_List_Group). On the other hand, * data can be added or removed only at the end of the array. To insert - * data at any place, the Eina @ref Eina_List_Group is the correct container + * data at any position, the Eina @ref Eina_List_Group is the correct container * to use. * * To use the array data type, eina_init() must be called before any @@ -155,11 +155,11 @@ * * An array must be created with eina_array_new(). It allocates all * the necessary data for an array. When not needed anymore, an array - * is freed with eina_array_free(). This function does not free any - * allocated memory used to store the data of each element. For that, - * just iterate over the array to free them. A convenient way to do - * that is by using #EINA_ARRAY_ITER_NEXT. An example of code is given - * in the description of this macro. + * is freed with eina_array_free(). This frees the memory used by the Eina_Array + * itself, but does not free any memory used to store the data of each element. + * To free that memory you must iterate over the array and free each data element + * individually. A convenient way to do that is by using #EINA_ARRAY_ITER_NEXT. + * An example of that pattern is given in the description of @ref EINA_ARRAY_ITER_NEXT. * * @warning Functions do not check if the used array is valid or not. It's up to * the user to be sure of that. It is designed like that for performance @@ -176,16 +176,15 @@ * element to a full array it grows and that when you remove an element from an * array it @b may shrink. * - * When the array needs to grow it allocates memory not just for the element - * currently being added since that would mean allocating memory(which is - * computationally expensive) often, instead it grows to be able to hold @p step - * more elements. Similarly if you remove elements in such a way that that the - * array is left holding its capacity - @p step elements it will shrink. + * Allocating memory is expensive, so when the array needs to grow it allocates + * enough memory to hold @p step additonal elements, not just the element + * currently being added. Similarly if you remove elements, it won't free space + * until you have removed @p step elements. * * The following image illustrates how an Eina_Array grows: * * @image html eina_array-growth.png - * @image latex eina_array-growth.eps width=\textwidth + * @image latex eina_array-growth.eps "" width=\textwidth * * Eina_Array only stores pointers but it can store data of any type in the form * of void pointers. @@ -234,10 +233,10 @@ struct _Eina_Array #define EINA_ARRAY_VERSION 1 int version; /**< Should match EINA_ARRAY_VERSION used when compiled your apps, provided for ABI compatibility */ - void **data; /**< Pointer to a vector of pointer to payload */ - unsigned int total; /**< Total number of slots in the vector */ - unsigned int count; /**< Number of active slots in the vector */ - unsigned int step; /**< How much must we grow the vector when it is full */ + void **data; /**< Pointer to a vector of pointer to payload */ + unsigned int total; /**< Number of allocated slots in the vector */ + unsigned int count; /**< Number of slots in the vector that actually point to data */ + unsigned int step; /**< Number of slots to grow or shrink the vector */ EINA_MAGIC }; @@ -264,8 +263,8 @@ EAPI Eina_Array *eina_array_new(unsigned int step) EINA_WARN_UNUSED_RESULT EINA_ * * This function frees @p array. It calls first eina_array_flush() then * free the memory of the pointer. It does not free the memory - * allocated for the elements of @p array. To free them, - * use #EINA_ARRAY_ITER_NEXT. For performance reasons, there is no check + * allocated for the elements of @p array. To free them, walk the array with + * #EINA_ARRAY_ITER_NEXT. For performance reasons, there is no check * of @p array. */ EAPI void eina_array_free(Eina_Array *array) EINA_ARG_NONNULL(1); @@ -329,9 +328,48 @@ EAPI void eina_array_flush(Eina_Array *array) EINA_ARG_NONNULL(1); EAPI Eina_Bool eina_array_remove(Eina_Array * array, Eina_Bool (*keep)(void *data, void *gdata), void *gdata) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Append a data to an array. + * + * @param array The array. + * @param data The data to add. + * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * + * This function appends @p data to @p array. For performance + * reasons, there is no check of @p array. If it is @c NULL or + * invalid, the program may crash. If @p data is @c NULL, or if an + * allocation is necessary and fails, #EINA_FALSE is returned + * Otherwise, #EINA_TRUE is returned. + */ static inline Eina_Bool eina_array_push(Eina_Array *array, const void *data) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Remove the last data of an array. + * + * @param array The array. + * @return The retrieved data. + * + * This function removes the last data of @p array, decreases the count + * of @p array and returns the data. For performance reasons, there + * is no check of @p array. If it is @c NULL or invalid, the program + * may crash. If the count member is less or equal than 0, @c NULL is + * returned. + */ static inline void *eina_array_pop(Eina_Array *array) EINA_ARG_NONNULL(1); + +/** + * @brief Return the data at a given position in an array. + * + * @param array The array. + * @param idx The potition of the data to retrieve. + * @return The retrieved data. + * + * This function returns the data at the position @p idx in @p + * array. For performance reasons, there is no check of @p array or @p + * idx. If it is @c NULL or invalid, the program may crash. + */ static inline void *eina_array_data_get(const Eina_Array *array, unsigned int idx) EINA_ARG_NONNULL(1); /** @@ -350,11 +388,34 @@ static inline void *eina_array_data_get(const Eina_Array *array, static inline void eina_array_data_set(const Eina_Array *array, unsigned int idx, const void *data) EINA_ARG_NONNULL(1); +/** + * @brief Return the number of elements in an array. + * + * @param array The array. + * @return The number of elements. + * + * This function returns the number of elements in @p array (array->count). For + * performance reasons, there is no check of @p array. If it is + * @c NULL or invalid, the program may crash. + * + * @deprecated use eina_array_count() + */ static inline unsigned int eina_array_count_get(const Eina_Array *array) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; + +/** + * @brief Return the number of elements in an array. + * + * @param array The array. + * @return The number of elements. + * + * This function returns the number of elements in @p array (array->count). For + * performance reasons, there is no check of @p array. If it is + * @c NULL or invalid, the program may crash. + */ static inline unsigned int eina_array_count(const Eina_Array *array) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; /** - * @brief Returned a new iterator associated to an array. + * @brief Get a new iterator associated to an array. * * @param array The array. * @return A new iterator. @@ -362,12 +423,12 @@ static inline unsigned int eina_array_count(const Eina_Array *array) EINA_ARG_NO * This function returns a newly allocated iterator associated to * @p array. If @p array is @c NULL or the count member of @p array is * less or equal than 0, this function returns @c NULL. If the memory can - * not be allocated, NULL is returned. Otherwise, a valid iterator is returned. + * not be allocated, @c NULL is returned. Otherwise, a valid iterator is returned. */ EAPI Eina_Iterator *eina_array_iterator_new(const Eina_Array *array) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; /** - * @brief Returned a new accessor associated to an array. + * @brief Get a new accessor associated to an array. * * @param array The array. * @return A new accessor. @@ -375,7 +436,7 @@ EAPI Eina_Iterator *eina_array_iterator_new(const Eina_Array *array) EINA * This function returns a newly allocated accessor associated to * @p array. If @p array is @c NULL or the count member of @p array is * less or equal than 0, this function returns @c NULL. If the memory can - * not be allocated, @c NULL is returned Otherwise, a valid accessor is + * not be allocated, @c NULL is returned. Otherwise, a valid accessor is * returned. */ EAPI Eina_Accessor *eina_array_accessor_new(const Eina_Array *array) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; @@ -387,9 +448,10 @@ EAPI Eina_Accessor *eina_array_accessor_new(const Eina_Array *array) EINA * @param fdata The user data to pass to the callback. * @return #EINA_TRUE if it successfully iterate all items of the array. * - * This function provide a safe way to iterate over an array. @p cb should - * return #EINA_TRUE as long as you want the function to continue iterating, - * by returning #EINA_FALSE it will stop and return #EINA_FALSE as a result. + * This function provides a safe way to iterate over an array. @p cb should + * return #EINA_TRUE as long as you want the function to continue iterating. + * If @p cb returns #EINA_FALSE, iterations will stop and the function will also + * return #EINA_FALSE. */ static inline Eina_Bool eina_array_foreach(Eina_Array *array, Eina_Each_Cb cb, diff --git a/src/lib/eina/eina_binbuf.h b/src/lib/eina/eina_binbuf.h index 23f2798..32f3b1e 100644 --- a/src/lib/eina/eina_binbuf.h +++ b/src/lib/eina/eina_binbuf.h @@ -133,7 +133,7 @@ EAPI Eina_Bool eina_binbuf_append_length(Eina_Binbuf *buf, const unsigned char * * @return #EINA_TRUE on success, #EINA_FALSE on failure. * * This function appends @p data to @p buf. @p data must be allocated and - * different from @NULL. It is slightly faster than eina_binbuf_append() as + * different from @c NULL. It is slightly faster than eina_binbuf_append() as * it does not compute the size of @p str. If @p buf can't append it, * #EINA_FALSE is returned, otherwise #EINA_TRUE is returned. * diff --git a/src/lib/eina/eina_clist.h b/src/lib/eina/eina_clist.h index 10cd6c7..0ec90e7 100644 --- a/src/lib/eina/eina_clist.h +++ b/src/lib/eina/eina_clist.h @@ -111,13 +111,14 @@ typedef struct _Eina_Clist Eina_Clist; /** * @struct _Eina_Clist * Compact list type + * * @note This structure is used as both the list head and the list entry. * @since 1.1.0 */ struct _Eina_Clist { - Eina_Clist *next; - Eina_Clist *prev; + Eina_Clist *next; /**< The next entry in the list */ + Eina_Clist *prev; /**< The previous entry in the list */ }; /** @@ -191,7 +192,7 @@ static inline void eina_clist_element_init(Eina_Clist *elem); * Check if an element is in a list or not. * * @param elem An element - * + * @return TRUE if the element is in a list, else FALSE. * @pre Either eina_clist_element_init() has been called on @a elem, * it has been added to a list or remove from a list. * @since 1.1.0 diff --git a/src/lib/eina/eina_convert.h b/src/lib/eina/eina_convert.h index fa463d9..be65cc4 100644 --- a/src/lib/eina/eina_convert.h +++ b/src/lib/eina/eina_convert.h @@ -158,9 +158,9 @@ * @{ */ -EAPI extern Eina_Error EINA_ERROR_CONVERT_P_NOT_FOUND; -EAPI extern Eina_Error EINA_ERROR_CONVERT_0X_NOT_FOUND; -EAPI extern Eina_Error EINA_ERROR_CONVERT_OUTRUN_STRING_LENGTH; +EAPI extern Eina_Error EINA_ERROR_CONVERT_P_NOT_FOUND; /**< Not used, perhaps a placeholder? Defined as 0 in eina_convert.c*/ +EAPI extern Eina_Error EINA_ERROR_CONVERT_0X_NOT_FOUND; /**< Not used, perhaps a placeholder? Defined as 0 in eina_convert.c*/ +EAPI extern Eina_Error EINA_ERROR_CONVERT_OUTRUN_STRING_LENGTH; /**< Not used, perhaps a placeholder? Defined as 0 in eina_convert.c*/ /** * @brief Convert an integer number to a string in decimal base. diff --git a/src/lib/eina/eina_cow.h b/src/lib/eina/eina_cow.h index bbbcf4b..e7f0d20 100644 --- a/src/lib/eina/eina_cow.h +++ b/src/lib/eina/eina_cow.h @@ -73,6 +73,7 @@ EAPI void eina_cow_del(Eina_Cow *cow); /** * @brief Return an initialized pointer from the pool. * @param cow The pool to take things from. + * @return A pointer to the new pool instance */ EAPI const Eina_Cow_Data *eina_cow_alloc(Eina_Cow *cow) EINA_WARN_UNUSED_RESULT; @@ -100,6 +101,7 @@ EAPI void *eina_cow_write(Eina_Cow *cow, * @param cow The pool the pointer come from. * @param dst The read only version of the pointer. * @param data The pointer to which data was written to. + * @param needed_gc Does this pool need to be garbage collected? * * NOTE: this function is not thread safe, be careful. */ diff --git a/src/lib/eina/eina_file.h b/src/lib/eina/eina_file.h index 99e8e81..546a1e0 100644 --- a/src/lib/eina/eina_file.h +++ b/src/lib/eina/eina_file.h @@ -99,8 +99,8 @@ typedef struct _Eina_File_Direct_Info Eina_File_Direct_Info; typedef struct _Eina_Stat Eina_Stat; /** - * @typedef Eina_File_Lines - * A typedef to #_Eina_File_Lines. + * @typedef Eina_File_Line + * A typedef to #_Eina_File_Line. */ typedef struct _Eina_File_Line Eina_File_Line; @@ -108,7 +108,7 @@ typedef struct _Eina_File_Line Eina_File_Line; * @typedef Eina_File_Dir_List_Cb * Type for a callback to be called when iterating over the files of a * directory. - * @param The file name EXCLUDING the path + * @param name The file name EXCLUDING the path * @param path The path passed to eina_file_dir_list() * @param data The data passed to eina_file_dir_list() */ @@ -130,7 +130,12 @@ typedef enum { EINA_FILE_WHT /**< Whiteout file type (unused on Windows). */ } Eina_File_Type; +/** + * @typedef Eina_File + * A file handle. + */ typedef struct _Eina_File Eina_File; + /** * @typedef Eina_File_Populate * File access type used in Eina_File_Direct_info. @@ -145,12 +150,12 @@ typedef enum { } Eina_File_Populate; /* Why do this? Well PATH_MAX may vary from when eina itself is compiled - * to when the app using eina is compiled. exposing the path buffer below - * can't safely and portably vary based on how/when you compile. it should + * to when the app using eina is compiled. Exposing the path buffer below + * can't safely and portably vary based on how/when you compile. It should * always be the same for both eina inside AND for apps outside that use eina * so define this to 8192 - most PATH_MAX values are like 4096 or 1024 (with - * windows i think being 260), so 8192 should cover almost all cases. there - * is a possibility that PATH_MAX could be more than 8192. if anyone spots + * windows i think being 260), so 8192 should cover almost all cases. There + * is a possibility that PATH_MAX could be more than 8192. If anyone spots * a path_max that is bigger - let us know, but, for now we will assume * it never happens */ /** @@ -164,36 +169,36 @@ typedef enum { */ 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 */ - Eina_File_Type type; /**< file type */ + 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 */ + Eina_File_Type type; /**< file type */ char path[EINA_PATH_MAX]; /**< the path */ }; /** * @struct _Eina_Stat - * A structure to store informations of a path. + * A structure to store some file statistics. * @since 1.2 */ struct _Eina_Stat { - unsigned long int dev; - unsigned long int ino; - unsigned int mode; - unsigned int nlink; - unsigned int uid; - unsigned int gid; - unsigned long int rdev; - unsigned long int size; - unsigned long int blksize; - unsigned long int blocks; - unsigned long int atime; - unsigned long int atimensec; - unsigned long int mtime; - unsigned long int mtimensec; - unsigned long int ctime; - unsigned long int ctimensec; + unsigned long int dev; /**< The device where this file is located */ + unsigned long int ino; /**< The inode */ + unsigned int mode; /**< The mode */ + unsigned int nlink; /**< The link number */ + unsigned int uid; /**< The owner user id */ + unsigned int gid; /**< The owner group id */ + unsigned long int rdev; /**< The remote device */ + unsigned long int size; /**< The file size in bytes */ + unsigned long int blksize; /**< The block size in bytes */ + unsigned long int blocks; /**< The number of blocks allocated */ + unsigned long int atime; /**< The timestamp when the file was last accessed */ + unsigned long int atimensec; /**< The nano version of the timestamp when the file was last accessed */ + unsigned long int mtime; /**< The timestamp when the file was last modified */ + unsigned long int mtimensec; /**< The nano version of the timestamp when the file was modified */ + unsigned long int ctime; /**< The timestamp when the file was created */ + unsigned long int ctimensec; /**< The nano version of the timestamp when the file was created */ }; /** @@ -203,10 +208,10 @@ struct _Eina_Stat */ struct _Eina_File_Line { - const char *start; - const char *end; - unsigned int index; - unsigned long long length; + const char *start; /**< The start of the line */ + const char *end; /**< The end of the line */ + unsigned int index; /**< The line number */ + unsigned long long length; /**< The number of characters in the line */ }; /** @@ -462,7 +467,7 @@ EAPI Eina_File *eina_file_open(const char *name, Eina_Bool shared) EINA_WARN_UNU /** * @brief Create a virtual file from a memory pointer. * - * @param virtual_name A virtual name for Eina_File, if #NULL, a generated one will be given + * @param virtual_name A virtual name for Eina_File, if @c NULL, a generated one will be given * @param data The memory pointer to take data from * @param length The length of the data in memory * @param copy #EINA_TRUE if the data must be copied @@ -618,6 +623,7 @@ EAPI void eina_file_map_free(Eina_File *file, void *map); * @brief Ask the OS to populate or otherwise pages of memory in file mapping * * @param file The file handle from which the map comes + * @param rule The rule to apply to the mapped memory * @param map Memory that was mapped inside of which the memory range is * @param offset The offset in bytes from the start of the map address * @param length The length in bytes of the memory region to populate @@ -635,7 +641,7 @@ eina_file_map_populate(Eina_File *file, Eina_File_Populate rule, const void *map /** * @brief Map line by line in memory efficiently with an Eina_Iterator * @param file The file to run over - * @return an Eina_Iterator that will produce @typedef Eina_File_Lines. + * @return an Eina_Iterator that will produce @ref Eina_File_Line. * * This function return an iterator that will act like fgets without the * useless memcpy. Be aware that once eina_iterator_next has been called, diff --git a/src/lib/eina/eina_file_common.h b/src/lib/eina/eina_file_common.h index 62ad2b2..76f65b2 100644 --- a/src/lib/eina/eina_file_common.h +++ b/src/lib/eina/eina_file_common.h @@ -26,125 +26,323 @@ #define EINA_FILE_MAGIC 0xFEEDBEEF +/** + * @addtogroup Eina_Tools_Group Tools + * + * @{ + */ +/** + * @addtogroup Eina_File_Group File + * + * @brief Functions to handle files and directories. + * + * This module performs internal housekeeping and utility tasks for Eina_File. + * It also provides the underlying data types for things like file handles, file + * maps and file iterators. + * + * @{ + */ + +/** + * @typedef Eina_File_Map + * + * Type definition for an Eina File Map. + * + */ typedef struct _Eina_File_Map Eina_File_Map; + +/** + * @typedef Eina_Lines_Iterator + * + * Type definition for an Eina Lines Iterator. + * + */ typedef struct _Eina_Lines_Iterator Eina_Lines_Iterator; +/** + * @struct _Eina_File + * + * This is the underlying data structure that represents a file in Eina. + * + */ struct _Eina_File { - EINA_MAGIC; - const char *filename; - - Eina_Hash *map; - Eina_Hash *rmap; - void *global_map; - - Eina_Lock lock; + EINA_MAGIC; /**< Indicates whether Eina Magic should be used. */ + const char *filename; /**< The absolute path of the file. Note that the path given when calling @ref eina_file_open will be run through @ref eina_file_path_sanitize before it is stored here. */ + Eina_Hash *map; /**< Tracks portions of a file that have been mapped with mmap(2). The key is a tuple offset/length and the data is a pointer to the mapped region. */ + Eina_Hash *rmap; /**< Similar function to #map, but used to look up mapped areas by pointer rather than offset/length. */ + void *global_map; /**< A pointer to the entire contents of the file that have been mapped with mmap(2). This is the common case, and EFL and is optimized for it. */ + Eina_Lock lock; /**< A file locking mechanism. */ #ifndef _WIN32 - unsigned long long length; - time_t mtime; - ino_t inode; + unsigned long long length; /**< The length of the file in bytes. */ + time_t mtime; /**< The last modified time. */ + ino_t inode; /**< The inode. */ #ifdef _STAT_VER_LINUX - unsigned long int mtime_nsec; + unsigned long int mtime_nsec; /**< The nano version of the last modified time. */ #endif #else - ULONGLONG length; - ULONGLONG mtime; + ULONGLONG length; /**< The length of the file in bytes. */ + ULONGLONG mtime; /**< The last modified time. */ #endif - int refcount; - int global_refcount; + int refcount; /**< Keeps track of references to #map. */ + int global_refcount; /**< Keeps track of references to #global_map. */ #ifndef _WIN32 - int fd; + int fd; /**< The file descriptor. */ #else - HANDLE handle; - HANDLE fm; + HANDLE handle; /**< A Win32 file handle for this file. */ + HANDLE fm; /**< A Win32 file handle to a file mapping object for this file. */ #endif - Eina_List *dead_map; + Eina_List *dead_map; /**< Tracks regions that get a failure from mmap(2). */ - Eina_Bool shared : 1; - Eina_Bool delete_me : 1; - Eina_Bool global_faulty : 1; - Eina_Bool virtual : 1; + Eina_Bool shared : 1; /**< Indicates whether this file can be shared */ + Eina_Bool delete_me : 1; /**< Indicates that this file should be deleted */ + Eina_Bool global_faulty : 1; /**< Indicates whether #global_map is bad */ + Eina_Bool virtual : 1; /**< Indicates that this is a virtual file */ }; +/** + * @struct _Eina_File_Map + * + * This represents a memory mapped region of a file. + * + */ struct _Eina_File_Map { - void *map; + void *map; /**< A pointer to the mapped region */ - unsigned long int offset; - unsigned long int length; + unsigned long int offset; /**< The offset in the file */ + unsigned long int length; /**< The length of the region */ - int refcount; + int refcount; /**< Tracks references to this region */ - Eina_Bool hugetlb : 1; - Eina_Bool faulty : 1; + Eina_Bool hugetlb : 1; /**< Indicates if we are using HugeTLB */ + Eina_Bool faulty : 1; /**< Indicates if this region was not mapped correctly (i.e. the call to mmap(2) failed). */ }; +/** + * @struct _Eina_Lines_Iterator + * + * This represents a line iterator a file. + * + */ struct _Eina_Lines_Iterator { - Eina_Iterator iterator; + Eina_Iterator iterator; /**< The iterator itself */ - Eina_File *fp; - const char *map; - const char *end; + Eina_File *fp; /**< The file this iterator is associated with */ + const char *map; /**< A pointer to the head of the file that has been mapped with mmap(2). */ + const char *end; /**< A pointer to the end of the file that has been mapped with mmap(2). */ - int boundary; + int boundary; /**< Curretnly hard coded to 4096. */ - Eina_File_Line current; + Eina_File_Line current; /**< The current line */ }; + #ifndef EINA_LOG_COLOR_DEFAULT +/** Set the color for Eina log entries */ #define EINA_LOG_COLOR_DEFAULT EINA_COLOR_CYAN #endif #ifdef ERR #undef ERR #endif +/** Macro for logging Eina errors */ #define ERR(...) EINA_LOG_DOM_ERR(_eina_file_log_dom, __VA_ARGS__) #ifdef WRN #undef WRN #endif +/** Macro for logging Eina warnings */ #define WRN(...) EINA_LOG_DOM_WARN(_eina_file_log_dom, __VA_ARGS__) #ifdef INF #undef INF #endif +/** Macro for logging Eina info messages */ #define INF(...) EINA_LOG_DOM_INFO(_eina_file_log_dom, __VA_ARGS__) #ifdef DBG #undef DBG #endif +/** Macro for logging Eina debug messages */ #define DBG(...) EINA_LOG_DOM_DBG(_eina_file_log_dom, __VA_ARGS__) +/** + * @brief Determines if a path is relative or absolute. + * The implementation simply chekcs if the fist char in the path is '/'. If it + * is not, the path is considered relative. + * + * @param path The path to check. + * @return EINA_TRUE if the path is relative, EINA_FALSE otherwise. + * + */ Eina_Bool eina_file_path_relative(const char *path); + +/** + * @brief Gets the current directory and optionally appends a path to it. + * If a string was passed in via the @p path parameter, it will + * be appended to the current working directory. Presumably, this will be a + * relative path. + * + * @param path The path to append to the current directory. + * @param len The length of @p path. + * + * @return A pointer to a string that contains the absolute path to the current + * working directory plus any path you send in. + * + */ Eina_Tmpstr *eina_file_current_directory_get(const char *path, size_t len); + +/** + * @brief Cleans up Eina after a file is no longer needed. + * + * @param path The path of the file. + * + * @return On success, it will return the @p path string. If @p path is @c NULL, + * it will return and empty string. + * + */ char *eina_file_cleanup(Eina_Tmpstr *path); + +/** + * @brief Closes and cleans up after an Eina file. + * + * @param file The path of the file. + * + * + */ void eina_file_clean_close(Eina_File *file); + +/** + * @brief Closes a file from the OS perspective. + * + * @param file The path of the file. + * + * + */ void eina_file_real_close(Eina_File *file); + +/** + * @brief Resets the internal housekeeping structures after a file has changed. + * Despite the name, this routine does not write anything to disk. It invalidates + * the memory maps for the file. If the file has shrunk, it also adds any mapped + * regions past the end of the file to the dead_map. + * + * @param file The file. + * @param length The current length of the file after the change. + * + * + */ void eina_file_flush(Eina_File *file, unsigned long int length); + +/** + * @brief Removes a mapped region from the file and frees the resources. + * This routine will remove a previously mapped region from the internal Eina File + * housekeeping and free the resources associated with it. In the case where + * the map is part of the dead_map, @p free_func will be called to handle the actual + * deallocation. + * + * @param file The file. + * @param map The memory mapped region that is to be freed. + * @param free_func A pointer to a function that will be called to free up the + * resources used by the map. + * + * + */ void eina_file_common_map_free(Eina_File *file, void *map, void (*free_func)(Eina_File_Map *map)); - +/** A pointer to the global Eina file cache. */ extern Eina_Hash *_eina_file_cache; + +/** The global file lock cache */ extern Eina_Lock _eina_file_lock_cache; + +/** The global Eina log file domain. */ extern int _eina_file_log_dom; // Common function to handle virtual file +/** + * @brief Map the entire contents fo a virtual file to a buffer. + * + * @param file The virtual file to map in memory + * + */ void *eina_file_virtual_map_all(Eina_File *file); + +/** + * @brief Map a part of a virtual file to a buffer. + * + * @param file The virtual file to map in memory + * @param offset The offset inside the file to start mapping + * @param length The length of the region to map + * + */ void *eina_file_virtual_map_new(Eina_File *file, unsigned long int offset, unsigned long int length); + +/** + * @brief Unref and unmap memory if possible. + * + * @param file The file handler to unmap memory from. + * @param map Memory map to unref and unmap. + * + */ void eina_file_virtual_map_free(Eina_File *file, void *map); // Common hash function +/** + * @brief Get the length of a map key. + * @warning This function is not yet implemented. At present it ony returns + * @code sizeof (unsigned long int) * 2 @endcode + * + * @param key The key for which length will be calcualted. + * + * @return The length of the key. + * + */ unsigned int eina_file_map_key_length(const void *key); + +/** + * @brief Compares two map keys. + * The implementation assumes that @p key1 and @p key2 are both pointers to an + * array with 2 elements, as is the case with the Eina file map keys. + * + * @param key1 The first key. + * @param key1_length The length of the first key. + * @param key2 The second key. + * @param key2_length The length of the second key. + * + * @return Positive number if Key1 > Key2, else a negative number. Will return + * zero if both elements of the key are exactly the same. + * + */ int eina_file_map_key_cmp(const unsigned long long int *key1, int key1_length, const unsigned long long int *key2, int key2_length); + +/** + * @brief Creates a hash from a map key. + * + * @param key A pointer to the key. + * @param key_length The length of the key. + * + * @return A key hash. + * + */ int eina_file_map_key_hash(const unsigned long long int *key, int key_length); +/** + * @} + */ + +/** + * @} + */ + #endif /* EINA_FILE_COMMON_H_ */ diff --git a/src/lib/eina/eina_hash.h b/src/lib/eina/eina_hash.h index c75db25..ac853ad 100644 --- a/src/lib/eina/eina_hash.h +++ b/src/lib/eina/eina_hash.h @@ -287,8 +287,16 @@ */ typedef struct _Eina_Hash Eina_Hash; +/** + * @typedef Eina_Hash_Tuple + * Type for a hash table of key/value pairs. + */ typedef struct _Eina_Hash_Tuple Eina_Hash_Tuple; +/** + * @struct _Eina_Hash_Tuple + * Data for a hash table of key/value pairs. + */ struct _Eina_Hash_Tuple { const void *key; /**< The key */ @@ -296,24 +304,44 @@ struct _Eina_Hash_Tuple unsigned int key_length; /**< The length of the key */ }; +/** + * @typedef Eina_Key_Length + * Type for a function to determine the length of a hash key. + */ typedef unsigned int (*Eina_Key_Length)(const void *key); + /** * @def EINA_KEY_LENGTH * @param Function The function used to calculate length of hash key. */ #define EINA_KEY_LENGTH(Function) ((Eina_Key_Length)Function) + +/** + * @typedef Eina_Key_Cmp + * Type for a function to compare two hash keys. + */ typedef int (*Eina_Key_Cmp)(const void *key1, int key1_length, const void *key2, int key2_length); /** * @def EINA_KEY_CMP * @param Function The function used to compare hash key. */ #define EINA_KEY_CMP(Function) ((Eina_Key_Cmp)Function) + +/** + * @typedef Eina_Key_Hash + * Type for a function to create a hash key. + */ typedef int (*Eina_Key_Hash)(const void *key, int key_length); /** * @def EINA_KEY_HASH * @param Function The function used to hash key. */ #define EINA_KEY_HASH(Function) ((Eina_Key_Hash)Function) + +/** + * @typedef Eina_Hash_Foreach + * Type for a function to iterate over a hash table. + */ typedef Eina_Bool (*Eina_Hash_Foreach)(const Eina_Hash *hash, const void *key, void *data, void *fdata); @@ -1015,22 +1043,72 @@ EAPI Eina_Iterator *eina_hash_iterator_tuple_new(const Eina_Hash *hash) EINA_MAL EAPI void eina_hash_foreach(const Eina_Hash *hash, Eina_Hash_Foreach func, const void *fdata) EINA_ARG_NONNULL(1, 2); -/* Paul Hsieh (http://www.azillionmonkeys.com/qed/hash.html) hash function used by WebCore (http://webkit.org/blog/8/hashtables-part-2/) */ + + +/** + * @brief + * Paul Hsieh (http://www.azillionmonkeys.com/qed/hash.html) hash function used by WebCore (http://webkit.org/blog/8/hashtables-part-2/) + * + * @param key The key to hash + * @param len The length of the key + * @return The hash value + */ EAPI int eina_hash_superfast(const char *key, int len) EINA_ARG_NONNULL(1); -/* Hash function first reported by dan bernstein many years ago in comp.lang.c */ + +/** + * @brief + * Hash function first reported by Dan Bernstein many years ago in comp.lang.c + * + * @param key The key to hash + * @param len The length of the key + * @return The hash value + */ static inline int eina_hash_djb2(const char *key, int len) EINA_ARG_NONNULL(1); +/** + * @brief + * Hash function first reported by Dan Bernstein many years ago in comp.lang.c + * + * @param key The key to hash + * @param plen The length of the key + * @return The hash value + */ static inline int eina_hash_djb2_len(const char *key, int *plen) EINA_ARG_NONNULL(1, 2); -/* Hash function from http://www.concentric.net/~Ttwang/tech/inthash.htm */ + +/** + * @brief + * Hash function from http://www.concentric.net/~Ttwang/tech/inthash.htm + * + * @param pkey The key to hash + * @param len The length of the key + * @return The hash value + */ static inline int eina_hash_int32(const unsigned int *pkey, int len) EINA_ARG_NONNULL(1); +/** + * @brief + * Hash function from http://www.concentric.net/~Ttwang/tech/inthash.htm + * + * @param pkey The key to hash + * @param len The length of the key + * @return The hash value + */ static inline int eina_hash_int64(const unsigned long long int *pkey, int len) EINA_ARG_NONNULL(1); -/* http://sites.google.com/site/murmurhash/ */ + +/** + * @brief + * Hash function from http://sites.google.com/site/murmurhash/ + * + * @param key The key to hash + * @param len The length of the key + * @return The hash value + */ static inline int eina_hash_murmur3(const char *key, int len) EINA_ARG_NONNULL(1); + #include "eina_inline_hash.x" /** diff --git a/src/lib/eina/eina_inarray.h b/src/lib/eina/eina_inarray.h index b9010d7..2b2d5b7 100644 --- a/src/lib/eina/eina_inarray.h +++ b/src/lib/eina/eina_inarray.h @@ -247,6 +247,7 @@ EAPI void eina_inarray_free(Eina_Inarray *array) EINA_ARG_NONNULL(1); /** * @brief Initialize inline array. * @param array array object to initialize. + * @param sizeof_eina_inarray the initial size of the array. * @param member_size size of each member in the array. * @param step when resizing the array, do this using the following * extra amount. diff --git a/src/lib/eina/eina_inline_array.x b/src/lib/eina/eina_inline_array.x index 45d7189..c191218 100644 --- a/src/lib/eina/eina_inline_array.x +++ b/src/lib/eina/eina_inline_array.x @@ -41,20 +41,6 @@ EAPI Eina_Bool eina_array_grow(Eina_Array *array); * @{ */ -/** - * @brief Append a data to an array. - * - * @param array The array. - * @param data The data to add. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. - * - * This function appends @p data to @p array. For performance - * reasons, there is no check of @p array. If it is @c NULL or - * invalid, the program may crash. If @p data is @c NULL, or if an - * allocation is necessary and fails, #EINA_FALSE is returned - * Otherwise, #EINA_TRUE is returned. - */ - static inline Eina_Bool eina_array_push(Eina_Array *array, const void *data) { @@ -69,18 +55,6 @@ eina_array_push(Eina_Array *array, const void *data) return EINA_TRUE; } -/** - * @brief Remove the last data of an array. - * - * @param array The array. - * @return The retrieved data. - * - * This function removes the last data of @p array, decreases the count - * of @p array and returns the data. For performance reasons, there - * is no check of @p array. If it is @c NULL or invalid, the program - * may crash. If the count member is less or equal than 0, @c NULL is - * returned. - */ static inline void * eina_array_pop(Eina_Array *array) { @@ -95,17 +69,6 @@ eina_array_pop(Eina_Array *array) return ret; } -/** - * @brief Return the data at a given position in an array. - * - * @param array The array. - * @param idx The potition of the data to retrieve. - * @return The retrieved data. - * - * This function returns the data at the position @p idx in @p - * array. For performance reasons, there is no check of @p array or @p - * idx. If it is @c NULL or invalid, the program may crash. - */ static inline void * eina_array_data_get(const Eina_Array *array, unsigned int idx) { @@ -118,34 +81,14 @@ eina_array_data_set(const Eina_Array *array, unsigned int idx, const void *data) array->data[idx] = (void*) data; } -/** - * @brief Return the number of elements in an array. - * - * @param array The array. - * @return The number of elements. - * - * This function returns the number of elements in @p array. For - * performance reasons, there is no check of @p array. If it is - * @c NULL or invalid, the program may crash. - * - * @deprecated use eina_array_count() - */ + static inline unsigned int eina_array_count_get(const Eina_Array *array) { return array->count; } -/** - * @brief Return the number of elements in an array. - * - * @param array The array. - * @return The number of elements. - * - * This function returns the number of elements in @p array. For - * performance reasons, there is no check of @p array. If it is - * @c NULL or invalid, the program may crash. - */ + static inline unsigned int eina_array_count(const Eina_Array *array) { diff --git a/src/lib/eina/eina_inlist.h b/src/lib/eina/eina_inlist.h index dd2fd73..6c1b1cc 100644 --- a/src/lib/eina/eina_inlist.h +++ b/src/lib/eina/eina_inlist.h @@ -70,7 +70,7 @@ * * @image html eina_inlist-node_eg1-inlist.png * @image rtf eina_inlist-node_eg1-inlist.png - * @image latex eina_inlist-node_eg1-inlist.eps width=\textwidth + * @image latex eina_inlist-node_eg1-inlist.eps "" width=\textwidth * * The macro @ref EINA_INLIST_FOREACH can be used to iterate over the list: * @@ -157,7 +157,7 @@ * <img src="eina_inlist-node_eg2-list-inlist.png" style="max-width: 100%;"/> * @endhtmlonly * @image rtf eina_inlist-node_eg2-list-inlist.png - * @image latex eina_inlist-node_eg2-list-inlist.eps width=\textwidth + * @image latex eina_inlist-node_eg2-list-inlist.eps "" width=\textwidth * * Accessing both lists is done normally, as if they didn't have any elements in * common: @@ -233,7 +233,7 @@ * <img src="eina_inlist-node_eg3-two-inlists.png" style="max-width: 100%;"/> * @endhtmlonly * @image rtf eina_inlist-node_eg3-two-inlists.png - * @image latex eina_inlist-node_eg3-two-inlists.eps width=\textwidth + * @image latex eina_inlist-node_eg3-two-inlists.eps "" width=\textwidth * * For the first list, we can use the macro @ref EINA_INLIST_FOREACH to iterate * over its elements: diff --git a/src/lib/eina/eina_lalloc.h b/src/lib/eina/eina_lalloc.h index d28cd52..573562e 100644 --- a/src/lib/eina/eina_lalloc.h +++ b/src/lib/eina/eina_lalloc.h @@ -33,12 +33,23 @@ * @{ */ +/** + * @typedef Eina_Lalloc_Alloc + * Type definition for the callback used to allocate new items in a lazy allocator. + * + */ typedef Eina_Bool (*Eina_Lalloc_Alloc)(void *user_data, int num); /** * @def EINA_LALLOC_ALLOC * @param function The function to allocate. */ #define EINA_LALLOC_ALLOC(function) ((Eina_Lalloc_Alloc)function) + +/** + * @typedef Eina_Lalloc_Free + * Type definition for the callback used to allocate new items in a lazy allocator. + * + */ typedef void (*Eina_Lalloc_Free)(void *user_data); /** * @def EINA_LALLOC_FREE @@ -46,15 +57,57 @@ typedef void (*Eina_Lalloc_Free)(void *user_data); */ #define EINA_LALLOC_FREE(function) ((Eina_Lalloc_Free)function) +/** + * @typedef Eina_Lalloc + * Public type definition for a lazy allocator. + * + */ typedef struct _Eina_Lalloc Eina_Lalloc; +/** + * @brief Create a new lazy allocator. + * + * @param data The data for which memory will be allocated. + * @param alloc_cb The callback to allocate memory for @p data items. + * @param free_cb The callback to free memory for @p data items. + * @param num_init The number of @p data items to initally allocate space for. + * + * @return A new lazy allocator. + * + */ EAPI Eina_Lalloc *eina_lalloc_new(void *data, Eina_Lalloc_Alloc alloc_cb, Eina_Lalloc_Free free_cb, int num_init) EINA_ARG_NONNULL(2, 3); + +/** + * @brief Free the resources for a lazy allocator. + * + * @param a The lazy allocator to free. + * + */ EAPI void eina_lalloc_free(Eina_Lalloc *a) EINA_ARG_NONNULL(1); + +/** + * @brief Add several elements to a lazy allocator. + * + * @param a The lazy allocater to add items to. + * @param num The number of elements to add. + * + * @return EINA_TRUE on success, else EINA_FALSE. + * + */ EAPI Eina_Bool eina_lalloc_elements_add(Eina_Lalloc *a, int num) EINA_ARG_NONNULL(1); + +/** + * @brief Allocate one more of whatever the lazy allocator is allocating. + * + * @param a The lazy allocator to add an item to. + * + * @return EINA_TRUE on success, else EINA_FALSE. + * + */ EAPI Eina_Bool eina_lalloc_element_add(Eina_Lalloc *a) EINA_ARG_NONNULL(1); /** diff --git a/src/lib/eina/eina_list.h b/src/lib/eina/eina_list.h index 2f9c17e..c030945 100644 --- a/src/lib/eina/eina_list.h +++ b/src/lib/eina/eina_list.h @@ -48,7 +48,7 @@ * <a href="eina_list_example_01_a.png">Full-size</a> * @endhtmlonly * @image rtf eina_list_example_01_a.png - * @image latex eina_list_example_01_a.eps width=\textwidth + * @image latex eina_list_example_01_a.eps "" width=\textwidth * @until roslin * There are a couple of interesting things happening here, first is that we are * passing a NULL pointer to the first @ref eina_list_append() call, when this @@ -81,7 +81,7 @@ * <a href="eina_list_example_01_b.png">Full-size</a> * @endhtmlonly * @image rtf eina_list_example_01_b.png - * @image latex eina_list_example_01_b.eps width=\textwidth + * @image latex eina_list_example_01_b.eps "" width=\textwidth * * Once done using the list it needs to be freed, and since we are done with * eina that also need to be shutdown: @@ -1352,7 +1352,7 @@ EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EINA_MA * <img src="eina-list-foreach.png" style="max-width: 100%;" /> * <a href="eina-list-foreach.png">Full-size</a> * @endhtmlonly - * @image latex eina-list-foreach.eps width=\textwidth + * @image latex eina-list-foreach.eps "" width=\textwidth * * It can be used to free list data, as in the following example: * @@ -1410,7 +1410,7 @@ EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EINA_MA * <img src="eina-list-reverse-foreach.png" style="max-width: 100%;" /> * <a href="eina-list-reverse-foreach.png">Full-size</a> * @endhtmlonly - * @image latex eina-list-reverse-foreach.eps width=\textwidth + * @image latex eina-list-reverse-foreach.eps "" width=\textwidth * * It can be used to free list data, as in the following example: * @@ -1471,7 +1471,7 @@ EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EINA_MA * <img src="eina-list-foreach-safe.png" style="max-width: 100%;" /> * <a href="eina-list-foreach-safe.png">Full-size</a> * @endhtmlonly - * @image latex eina-list-foreach-safe.eps width=\textwidth + * @image latex eina-list-foreach-safe.eps "" width=\textwidth * * This macro can be used to free list nodes, as in the following example: * @@ -1528,7 +1528,7 @@ EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EINA_MA * <img src="eina-list-reverse-foreach-safe.png" style="max-width: 100%;" /> * <a href="eina-list-reverse-foreach-safe.png">Full-size</a> * @endhtmlonly - * @image latex eina-list-reverse-foreach-safe.eps width=\textwidth + * @image latex eina-list-reverse-foreach-safe.eps "" width=\textwidth * * This macro can be used to free list nodes, as in the following example: * @@ -1577,7 +1577,7 @@ EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EINA_MA * <img src="eina-list-free.png" style="max-width: 100%;" /> * <a href="eina-list-free.png">Full-size</a> * @endhtmlonly - * @image latex eina-list-free.eps width=\textwidth + * @image latex eina-list-free.eps "" width=\textwidth * * If you do not need to release node data, it is easier to call #eina_list_free(). * diff --git a/src/lib/eina/eina_log.h b/src/lib/eina/eina_log.h index c2ac46f..84e7f23 100644 --- a/src/lib/eina/eina_log.h +++ b/src/lib/eina/eina_log.h @@ -443,6 +443,11 @@ struct _Eina_Log_Domain */ EAPI void eina_log_threads_enable(void); + +/** + * @typedef Eina_Log_Level + * List of available logging levels. + */ /** * @enum _Eina_Log_Level * List of available logging levels. @@ -467,6 +472,14 @@ typedef void (*Eina_Log_Print_Cb)(const Eina_Log_Domain *d, const char *file, const char *fnc, int line, const char *fmt, void *data, va_list args); +/** + * @typedef Eina_Log_State + * List of available log states. + */ +/** + * @enum _Eina_Log_State + * List of available log states. + */ typedef enum _Eina_Log_State { EINA_LOG_STATE_START, @@ -517,27 +530,34 @@ EAPI void eina_log_level_set(int level); */ EAPI int eina_log_level_get(void) EINA_WARN_UNUSED_RESULT; +/** + * @brief Determine if a given @p level should be logged. + * + * @return #EINA_TRUE if the @p level should be logged, else #EINA_FALSE. + * + * @see eina_log_level_set() + */ static inline Eina_Bool eina_log_level_check(int level); /** - * Checks if current thread is the main thread. + * @brief Checks if current thread is the main thread. * - * @return #EINA_TRUE if threads were enabled and the current thread - * is the one that called eina_log_threads_init(). If there is - * no thread support (compiled with --disable-pthreads) or - * they were not enabled, then #EINA_TRUE is also - * returned. The only case where #EINA_FALSE is returned is - * when threads were successfully enabled but the current - * thread is not the main (one that called - * eina_log_threads_init()). + * If there is no thread support (compiled with --disable-pthreads) or + * threads were not enabled, then #EINA_TRUE is returned. The only case where + * #EINA_FALSE is returned is when threads were successfully enabled but the + * current thread is not the one that called eina_log_threads_init() (the + * manin thread). + * + * @return #EINA_TRUE if the current thread is the one that called + * eina_log_threads_init(), otherwise #EINA_FALSE. */ EAPI Eina_Bool eina_log_main_thread_check(void) EINA_CONST EINA_WARN_UNUSED_RESULT; /** - * @brief Set if color logging should be disabled. + * @brief Enable or disable colored text in the logs. * - * @param disabled if #EINA_TRUE, color logging should be disabled. + * @param disabled If #EINA_TRUE, color logging should be disabled. * * @note this is initially set to envvar EINA_LOG_COLOR_DISABLE by eina_init(). * @@ -546,9 +566,9 @@ EAPI Eina_Bool eina_log_main_thread_check(void) EINA_CONST EINA_WARN_UN EAPI void eina_log_color_disable_set(Eina_Bool disabled); /** - * @brief Get if color logging should be disabled. + * @brief Determine if color logging is enabled or disabled. * - * @return if #EINA_TRUE, color logging should be disabled. + * @return If #EINA_TRUE, color logging is disabled. * * @see eina_log_color_disable_set() */ @@ -758,6 +778,7 @@ EAPI void eina_log_domain_unregister(int domain); * @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 ... variadic args. * * @note MT: this function may be called from different threads if * eina_log_threads_enable() was called before. @@ -945,7 +966,7 @@ EAPI void eina_log_print_cb_journald(const Eina_Log_Domain *d, * Configure console color of given file. * * @param fp file to configure console color (usually stderr or stdout). - * @param color a VT color code such as #EINA_COLOR_RED or #EINA_COLOR_RESET. + * @param color a VT color code such as EINA_COLOR_RED or EINA_COLOR_RESET. * * @note if color is disabled, nothing is done. See * eina_log_color_disable_get() @@ -956,10 +977,17 @@ EAPI void eina_log_print_cb_journald(const Eina_Log_Domain *d, EAPI void eina_log_console_color_set(FILE *fp, const char *color) EINA_ARG_NONNULL(1, 2); +/** String that indicates the log system is initializing */ extern EAPI const char *_eina_log_state_init; +/** String that indicates the log system is shutting down */ extern EAPI const char *_eina_log_state_shutdown; - +/** @def EINA_LOG_STATE_INIT + *String that indicates the log system is initializing + */ #define EINA_LOG_STATE_INIT _eina_log_state_init +/** @def EINA_LOG_STATE_SHUTDOWN + *String that indicates the log system is shutting down + */ #define EINA_LOG_STATE_SHUTDOWN _eina_log_state_shutdown /** diff --git a/src/lib/eina/eina_types.h b/src/lib/eina/eina_types.h index d37b20f..b0ce44b 100644 --- a/src/lib/eina/eina_types.h +++ b/src/lib/eina/eina_types.h @@ -226,6 +226,11 @@ /** * @def EINA_ARG_NONNULL * Used to warn when the specified arguments of the function are @c NULL. + * + * @param ... Oridnals of the parameters to check for nullity (1..n) + * + * @returns Nothing, but Doxygen will complain if it's not documented :-P + * */ # define EINA_ARG_NONNULL(...) --
