diff --git a/src/lib/eina/eina_accessor.h b/src/lib/eina/eina_accessor.h
index 3de6e42106..7e24779b53 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 bb529552e1..53e706fc3e 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 5a5199eb2b..07234cd70b 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 23f27986b1..32f3b1ebfe 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 10cd6c72cd..0ec90e7a21 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 fa463d9da4..be65cc404e 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 bbbcf4b677..e7f0d20527 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 99e8e8101b..546a1e0863 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 62ad2b21ac..76f65b2a17 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 c75db25b47..ac853ad23c 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 b9010d7d4e..2b2d5b7f7c 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 45d7189316..c191218d03 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 dd2fd733c6..6c1b1cc951 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 @@
*
* @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 @@
*
* @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 d28cd52068..573562e601 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 2f9c17ec94..c03094517b 100644
--- a/src/lib/eina/eina_list.h
+++ b/src/lib/eina/eina_list.h
@@ -48,7 +48,7 @@
* Full-size
* @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 @@
* Full-size
* @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
*
* Full-size
* @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
*
* Full-size
* @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
*
* Full-size
* @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
*
* Full-size
* @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
*
* Full-size
* @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 c2ac46f61c..84e7f23655 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 d37b20f71f..b0ce44b3ea 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(...)