kimcinoo
/
efl
forked from enlightenment/efl
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

docs: Fix typos and some wrong expressions in Eina API reference doxygen. 

Summary: I had fixed some typos and some wrong expressions, such as capital letters, singular, and orders of groups in Eina API reference doxygen.

Test Plan: Doxygen Revision

Reviewers: stefan, cedric, raster, Jaehyun_Cho, jpeg

Reviewed By: jpeg

Subscribers: conr2d

Differential Revision: https://phab.enlightenment.org/D4674
This commit is contained in:
Myoungwoon Roy, Kim 2017-02-20 15:18:21 +09:00 committed by Jean-Philippe Andre
parent 2ea9e7010c
commit ec71f6607a
55 changed files with 1441 additions and 1536 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
src/lib/eina/Eina.h
View File

@ -197,9 +197,9 @@
* should return properly populated @ref _Eina_Iterator and @ref _Eina_Accessor.
*
* @defgroup Eina_Tools_Group Tools
* @ingroup Eina
* @brief Eina tools aims to help application development, providing ways to
* make it safer, log errors, manage memory more efficiently and more.
* @ingroup Eina
*/
#ifdef _WIN32

51
src/lib/eina/eina_accessor.h
View File

@ -138,7 +138,7 @@ typedef Eina_Bool (*Eina_Accessor_Lock_Callback)(Eina_Accessor *it);
/**
* @typedef Eina_Accessor_Clone_Callback
* @brief Type for a callback to return a clone for the accessor
* @brief Type for a callback to return a clone for the accessor.
* @since 1.10
*/
typedef Eina_Accessor* (*Eina_Accessor_Clone_Callback)(Eina_Accessor *it);
@ -169,31 +169,31 @@ struct _Eina_Accessor
/**
* @def FUNC_ACCESSOR_GET_AT(Function)
* @brief Helper macro to cast @a Function to a Eina_Accessor_Get_At_Callback.
* @brief Definition for helper macro to cast @a Function to a Eina_Accessor_Get_At_Callback.
*/
#define FUNC_ACCESSOR_GET_AT(Function) ((Eina_Accessor_Get_At_Callback)Function)
/**
* @def FUNC_ACCESSOR_GET_CONTAINER(Function)
* @brief Helper macro to cast @a Function to a Eina_Accessor_Get_Container_Callback.
* @brief Definition for helper macro to cast @a Function to a Eina_Accessor_Get_Container_Callback.
*/
#define FUNC_ACCESSOR_GET_CONTAINER(Function) ((Eina_Accessor_Get_Container_Callback)Function)
/**
* @def FUNC_ACCESSOR_FREE(Function)
* @brief Helper macro to cast @a Function to a Eina_Accessor_Free_Callback.
* @brief Definition for helper macro to cast @a Function to a Eina_Accessor_Free_Callback.
*/
#define FUNC_ACCESSOR_FREE(Function) ((Eina_Accessor_Free_Callback)Function)
/**
* @def FUNC_ACCESSOR_LOCK(Function)
* @brief Helper macro to cast @a Function to a Eina_Iterator_Lock_Callback.
* @brief Definition for helper macro to cast @a Function to a Eina_Iterator_Lock_Callback.
*/
#define FUNC_ACCESSOR_LOCK(Function) ((Eina_Accessor_Lock_Callback)Function)
/**
* @def FUNC_ACCESSOR_CLONE(Function)
* @brief Helper macro to cast @p Function to a Eina_Iterator_Clone_Callback.
* @brief Definition for helper macro to cast @p Function to a Eina_Iterator_Clone_Callback.
* @since 1.10
*/
#define FUNC_ACCESSOR_CLONE(Function) ((Eina_Accessor_Clone_Callback)Function)
@ -201,26 +201,23 @@ struct _Eina_Accessor
/**
* @brief Frees an accessor.
*
* @details This function frees @a accessor if it is not @c NULL.
* @param[in] accessor The accessor to free
*
* @details This function frees @a accessor if it is not @c NULL.
*/
EAPI void eina_accessor_free(Eina_Accessor *accessor);
/**
* @brief Gets the data of an accessor at the given position.
*
* @details This function retrieves the data of the element pointed by
* @p accessor at the position @p position, and stores it in
* @p data. If @p accessor is @c NULL or if an error occurs, @c EINA_FALSE
* is returned, otherwise @c EINA_TRUE is returned.
* @param[in] accessor The accessor
* @param[in] position The position of the element
* @param[in] data The pointer that stores the data to retrieve
* @return #EINA_TRUE on success, otherwise #EINA_FALSE
*
* @details This function retrieves the data of the element pointed by
* @p accessor at the position @p position, and stores it in
* @p data. If @p accessor is @c NULL or if an error occurs, #EINA_FALSE
* is returned, otherwise #EINA_TRUE is returned.
*
*/
EAPI Eina_Bool eina_accessor_data_get(Eina_Accessor *accessor,
unsigned int position,
@ -228,17 +225,22 @@ EAPI Eina_Bool eina_accessor_data_get(Eina_Accessor *accessor,
/**
* @brief Gets the container of an accessor.
*
* @details This function returns the container that created @p accessor. If
* @p accessor is @c NULL, this function returns @c NULL.
* @param[in] accessor The accessor
* @return The container that created the accessor
*
* @details This function returns the container that created @p accessor. If
* @p accessor is @c NULL, this function returns @c NULL.
*/
EAPI void *eina_accessor_container_get(Eina_Accessor *accessor) EINA_ARG_NONNULL(1) EINA_PURE;
/**
* @brief Iterates over the container and executes a callback on the chosen elements.
* @details This function iterates over the elements pointed by @p accessor,
* starting from the element at position @p start and ending at the
* element at position @p end. For each element, the callback
* @p cb is called with the data @p fdata. If @p accessor is @c NULL
* or if @p start is greater than or equal to @p end, the function returns
* immediately.
*
* @param[in] accessor The accessor
* @param[in] cb The callback called on the chosen elements
@ -246,12 +248,6 @@ EAPI void *eina_accessor_container_get(Eina_Accessor *accessor) EINA_ARG_NONNULL
* @param[in] end The position of the last element
* @param[in] fdata The data passed to the callback
*
* @details This function iterates over the elements pointed by @p accessor,
* starting from the element at position @p start and ending at the
* element at position @p end. For each element, the callback
* @p cb is called with the data @p fdata. If @p accessor is @c NULL
* or if @p start is greater than or equal to @p end, the function returns
* immediately.
*/
EAPI void eina_accessor_over(Eina_Accessor *accessor,
Eina_Each_Cb cb,
@ -285,7 +281,7 @@ EAPI Eina_Bool eina_accessor_lock(Eina_Accessor *accessor) EINA_ARG_NONNULL(1);
EAPI Eina_Accessor* eina_accessor_clone(Eina_Accessor *accessor) EINA_ARG_NONNULL(1);
/**
* @brief Unlock the container of the accessor.
* @brief Unlocks the container of the accessor.
*
* @param[in] accessor The accessor
* @return #EINA_TRUE on success, otherwise #EINA_FALSE
@ -301,7 +297,9 @@ EAPI Eina_Bool eina_accessor_unlock(Eina_Accessor *accessor) EINA_ARG_NONNULL(1)
/**
* @def EINA_ACCESSOR_FOREACH
* @brief Helper macro to iterate over all the elements easily.
* @brief Definition for helper macro to iterate over all the elements easily.
* @details This macro allows a convenient way to loop over all elements in an
* accessor, very similar to EINA_LIST_FOREACH().
*
* @param accessor The accessor to use
* @param counter A counter used by eina_accessor_data_get() when
@ -310,9 +308,6 @@ EAPI Eina_Bool eina_accessor_unlock(Eina_Accessor *accessor) EINA_ARG_NONNULL(1)
* It must be a pointer to support getting
* its address since eina_accessor_data_get() requires a pointer.
*
* @details This macro allows a convenient way to loop over all elements in an
* accessor, very similar to EINA_LIST_FOREACH().
*
* This macro can be used for freeing the data of a list, like in the
* following example. It has the same goal as the one documented in
* EINA_LIST_FOREACH(), but using accessors:

2
src/lib/eina/eina_alloca.h
View File

@ -44,7 +44,7 @@ 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.
* freed when the caller returns. See alloca(3) for details.
*/
void *alloca(size_t size);
# endif

38
src/lib/eina/eina_array.h
View File

@ -177,7 +177,7 @@
* array it @b may 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
* enough memory to hold @p step additional 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.
*
@ -242,7 +242,7 @@ struct _Eina_Array
/**
* @brief Create a new array.
* @brief Creates a new array.
*
* @param step The count of pointers to add when increasing the array size.
* @return @c NULL on failure, non @c NULL otherwise.
@ -257,7 +257,7 @@ struct _Eina_Array
EAPI Eina_Array *eina_array_new(unsigned int step) EINA_WARN_UNUSED_RESULT EINA_MALLOC EINA_WARN_UNUSED_RESULT;
/**
* @brief Free an array.
* @brief Frees an array.
*
* @param array The array to free.
*
@ -269,7 +269,7 @@ EAPI Eina_Array *eina_array_new(unsigned int step) EINA_WARN_UNUSED_RESULT EINA_
EAPI void eina_array_free(Eina_Array *array);
/**
* @brief Set the step of an array.
* @brief Sets the step of an array.
*
* @param array The array.
* @param sizeof_eina_array Should be the value returned by sizeof(Eina_Array).
@ -285,7 +285,7 @@ EAPI void eina_array_step_set(Eina_Array *array,
unsigned int sizeof_eina_array,
unsigned int step) EINA_ARG_NONNULL(1);
/**
* @brief Clean an array.
* @brief Cleans an array.
*
* @param array The array to clean.
*
@ -297,7 +297,7 @@ EAPI void eina_array_step_set(Eina_Array *array,
static inline void eina_array_clean(Eina_Array *array) EINA_ARG_NONNULL(1);
/**
* @brief Flush an array.
* @brief Flushes an array.
*
* @param array The array to flush.
*
@ -309,7 +309,7 @@ static inline void eina_array_clean(Eina_Array *array) EINA_ARG_NONNULL(1);
EAPI void eina_array_flush(Eina_Array *array) EINA_ARG_NONNULL(1);
/**
* @brief Rebuild an array by specifying the data to keep.
* @brief Rebuilds an array by specifying the data to keep.
*
* @param array The array.
* @param keep The functions which selects the data to keep.
@ -329,7 +329,7 @@ EAPI Eina_Bool eina_array_remove(Eina_Array * array,
void *gdata) EINA_ARG_NONNULL(1, 2);
/**
* @brief Append a data to an array.
* @brief Appends a data to an array.
*
* @param array The array.
* @param data The data to add.
@ -345,7 +345,7 @@ 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.
* @brief Removes the last data of an array.
*
* @param array The array.
* @return The retrieved data.
@ -359,10 +359,10 @@ static inline Eina_Bool eina_array_push(Eina_Array *array,
static inline void *eina_array_pop(Eina_Array *array) EINA_ARG_NONNULL(1);
/**
* @brief Return the data at a given position in an array.
* @brief Returns the data at a given position in an array.
*
* @param array The array.
* @param idx The potition of the data to retrieve.
* @param idx The position of the data to retrieve.
* @return The retrieved data.
*
* This function returns the data at the position @p idx in @p
@ -372,7 +372,7 @@ static inline void *eina_array_pop(Eina_Array *array) EINA_ARG_NONNULL(1);
static inline void *eina_array_data_get(const Eina_Array *array,
unsigned int idx) EINA_ARG_NONNULL(1);
/**
* @brief Set the data at a given position in an array.
* @brief Sets the data at a given position in an array.
*
* @param array The array.
* @param idx The position of the data to set.
@ -388,7 +388,8 @@ 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.
* @deprecated use eina_array_count()
* @brief Returns the number of elements in an array.
*
* @param array The array.
* @return The number of elements.
@ -397,12 +398,11 @@ static inline void eina_array_data_set(const Eina_Array *array,
* 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.
* @brief Returns the number of elements in an array.
*
* @param array The array.
* @return The number of elements.
@ -414,7 +414,7 @@ static inline unsigned int eina_array_count_get(const Eina_Array *array) EINA_AR
static inline unsigned int eina_array_count(const Eina_Array *array) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
/**
* @brief Get a new iterator associated to an array.
* @brief Gets a new iterator associated to an array.
*
* @param array The array.
* @return A new iterator.
@ -427,7 +427,7 @@ static inline unsigned int eina_array_count(const Eina_Array *array) EINA_ARG_NO
EAPI Eina_Iterator *eina_array_iterator_new(const Eina_Array *array) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
/**
* @brief Get a new accessor associated to an array.
* @brief Gets a new accessor associated to an array.
*
* @param array The array.
* @return A new accessor.
@ -440,7 +440,7 @@ EAPI Eina_Iterator *eina_array_iterator_new(const Eina_Array *array) EINA
*/
EAPI Eina_Accessor *eina_array_accessor_new(const Eina_Array *array) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
/**
* @brief Provide a safe way to iterate over an array
* @brief Provides a safe way to iterate over an array.
*
* @param array The array to iterate over.
* @param cb The callback to call for each item.
@ -457,7 +457,7 @@ static inline Eina_Bool eina_array_foreach(Eina_Array *array,
void *fdata);
/**
* @def EINA_ARRAY_ITER_NEXT
* @brief Macro to iterate over an array easily.
* @brief Definition for the macro to iterate over an array easily.
*
* @param array The array to iterate over.
* @param index The integer number that is increased while iterating.

16
src/lib/eina/eina_benchmark.h
View File

@ -116,7 +116,7 @@
* The first column (specimen) is the integer passed to the work1()
* function when the test is run. The second column (experiment time)
* is the time, in nanosecond, that work1() takes. The third and
* fourth columnd are self-explicit.
* fourth column are self-explicit.
*
* You can see that the integer passed work1() starts from 200 and
* finishes at 290, with a step of 10. These values are computed withe
@ -129,7 +129,7 @@
* gnuplot bench_test_run.gnuplot
* @endcode
*
* to create the graphic of the comparison curves. The image file is
* To create the graphic of the comparison curves. The image file is
* named output_test_run.png.
*
* @section tutorial_benchmark_advanced_usage More Advanced Usage
@ -345,7 +345,7 @@ typedef void (*Eina_Benchmark_Specimens)(int request);
/**
* @def EINA_BENCHMARK
* @brief cast to an #Eina_Benchmark_Specimens.
* @brief Definition for the cast to an #Eina_Benchmark_Specimens.
*
* @param function The function to cast.
*
@ -355,7 +355,7 @@ typedef void (*Eina_Benchmark_Specimens)(int request);
/**
* @brief Create a new array.
* @brief Creates a new array.
*
* @param name The name of the benchmark.
* @param run The name of the run.
@ -374,7 +374,7 @@ EAPI Eina_Benchmark *eina_benchmark_new(const char *name,
const char *run);
/**
* @brief Free a benchmark object.
* @brief Frees a benchmark object.
*
* @param bench The benchmark to free.
*
@ -385,7 +385,7 @@ EAPI Eina_Benchmark *eina_benchmark_new(const char *name,
EAPI void eina_benchmark_free(Eina_Benchmark *bench);
/**
* @brief Add a test to a benchmark.
* @brief Adds a test to a benchmark.
*
* @param bench The benchmark.
* @param name The name of the test.
@ -413,7 +413,7 @@ EAPI Eina_Bool eina_benchmark_register(Eina_Benchmark *bench,
int count_step);
/**
* @brief Run the benchmark tests that have been registered.
* @brief Runs the benchmark tests that have been registered.
*
* @param bench The benchmark.
* @return The list of names of the test files.
@ -426,7 +426,7 @@ EAPI Eina_Bool eina_benchmark_register(Eina_Benchmark *bench,
* bench_[name]_[run]%s.gnuplot
* @endcode
*
* where [name] and [run] are the values passed to
* Where [name] and [run] are the values passed to
* eina_benchmark_new().
*
* Each registered test is executed and timed. The time is written to

10
src/lib/eina/eina_bezier.h
View File

@ -48,7 +48,7 @@ struct _Eina_Bezier
};
/**
* @brief Set the values of the points of the given floating
* @brief Sets the values of the points of the given floating
* point cubic bezier curve.
*
* @param b The floating point bezier.
@ -67,7 +67,7 @@ struct _Eina_Bezier
EAPI void eina_bezier_values_set(Eina_Bezier *b, double start_x, double start_y, double ctrl_start_x, double ctrl_start_y, double ctrl_end_x, double ctrl_end_y, double end_x, double end_y) EINA_ARG_NONNULL(1);
/**
* @brief Get the values of the points of the given floating
* @brief Gets the values of the points of the given floating
* point cubic bezier curve.
*
* @param b The floating point bezier.
@ -133,7 +133,7 @@ EAPI void eina_bezier_point_at(const Eina_Bezier *b, double t, double *px, doubl
EAPI double eina_bezier_angle_at(const Eina_Bezier *b, double t) EINA_ARG_NONNULL(1);
/**
* @brief split the bezier at given length.
* @brief Splits the bezier at given length.
*
* @param b The floating point bezier.
* @param len The given length.
@ -144,7 +144,7 @@ EAPI double eina_bezier_angle_at(const Eina_Bezier *b, double t) EINA_ARG_NONNUL
EAPI void eina_bezier_split_at_length(const Eina_Bezier *b, double len, Eina_Bezier *left, Eina_Bezier *right) EINA_ARG_NONNULL(1);
/**
* @brief get the bound of the the bezier.
* @brief Gets the bound of the the bezier.
*
* @param b The floating point bezier.
* @param x x coordinate of bounding box.
@ -158,7 +158,7 @@ EAPI void eina_bezier_split_at_length(const Eina_Bezier *b, double len, Eina_Bez
EAPI void eina_bezier_bounds_get(const Eina_Bezier *b, double *x, double *y, double *w, double *h) EINA_ARG_NONNULL(1);
/**
* @brief find the bezier at given interval.
* @brief Finds the bezier at given interval.
*
* @param b The floating point bezier.
* @param t0 The start interval.

60
src/lib/eina/eina_binbuf.h
View File

@ -34,7 +34,7 @@
typedef struct _Eina_Strbuf Eina_Binbuf;
/**
* @brief Create a new string buffer.
* @brief Creates a new string buffer.
*
* @return Newly allocated string buffer instance.
*
@ -48,12 +48,12 @@ typedef struct _Eina_Strbuf Eina_Binbuf;
EAPI Eina_Binbuf *eina_binbuf_new(void) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
/**
* @brief Create a new string buffer using the passed string. The passed
* @brief Creates a new string buffer using the passed string. The passed
* string is used directly as the buffer, it's somehow the opposite function of
* @ref eina_binbuf_string_steal . The passed string must be malloced.
*
* @param str the string to manage
* @param length the length of the string.
* @param str The string to manage.
* @param length The length of the string.
* @return Newly allocated string buffer instance.
*
* This function creates a new string buffer. On error, @c NULL is
@ -65,13 +65,13 @@ EAPI Eina_Binbuf *eina_binbuf_new(void) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
EAPI Eina_Binbuf *eina_binbuf_manage_new_length(unsigned char *str, size_t length) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_DEPRECATED;
/**
* @brief Create a new string buffer using the passed string. The passed
* @brief Creates a new string buffer using the passed string. The passed
* string is used directly as the buffer, it's somehow the opposite function of
* @ref eina_binbuf_string_steal .
*
* @param str the string to start from
* @param length the length of the string.
* @param ro the passed string will not be touched if set to EINA_TRUE.
* @param str The string to start from.
* @param length The length of the string.
* @param ro The passed string will not be touched if set to EINA_TRUE.
* @return Newly allocated string buffer instance.
*
* This function creates a new string buffer. On error, @c NULL is
@ -90,12 +90,12 @@ EAPI Eina_Binbuf *eina_binbuf_manage_new_length(unsigned char *str, size_t lengt
EAPI Eina_Binbuf *eina_binbuf_manage_new(const unsigned char *str, size_t length, Eina_Bool ro) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
/**
* @brief Create a new string buffer using the passed string. The passed
* @brief Creates a new string buffer using the passed string. The passed
* string is used directly as the buffer, it's somehow the opposite function of
* @ref eina_binbuf_string_steal . The passed string will not be touched.
*
* @param str the string to start from
* @param length the length of the string.
* @param str The string to start from.
* @param length The length of the string.
* @return Newly allocated string buffer instance.
*
* This function creates a new string buffer. On error, @c NULL is
@ -110,7 +110,7 @@ EAPI Eina_Binbuf *eina_binbuf_manage_new(const unsigned char *str, size_t length
EAPI Eina_Binbuf *eina_binbuf_manage_read_only_new_length(const unsigned char *str, size_t length) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_DEPRECATED;
/**
* @brief Free a string buffer.
* @brief Frees a string buffer.
*
* @param buf The string buffer to free.
*
@ -120,7 +120,7 @@ EAPI Eina_Binbuf *eina_binbuf_manage_read_only_new_length(const unsigned char *s
EAPI void eina_binbuf_free(Eina_Binbuf *buf) EINA_ARG_NONNULL(1);
/**
* @brief Reset a string buffer.
* @brief Resets a string buffer.
*
* @param buf The string buffer to reset.
*
@ -130,7 +130,7 @@ EAPI void eina_binbuf_free(Eina_Binbuf *buf) EINA_ARG_NONNULL(1);
EAPI void eina_binbuf_reset(Eina_Binbuf *buf) EINA_ARG_NONNULL(1);
/**
* @brief Expand a buffer, making room for at least @a minimum_unused_space.
* @brief Expands a buffer, making room for at least @a minimum_unused_space.
*
* One of the properties of the buffer is that it may overallocate
* space, thus it may have more than eina_binbuf_length_get() bytes
@ -161,7 +161,7 @@ EAPI void eina_binbuf_reset(Eina_Binbuf *buf) EINA_ARG_NONNULL(1);
EAPI Eina_Rw_Slice eina_binbuf_expand(Eina_Binbuf *buf, size_t minimum_unused_space) EINA_ARG_NONNULL(1);
/**
* @brief Mark more bytes as used.
* @brief Marks more bytes as used.
*
* This function should be used after eina_binbuf_expand(), marking
* the extra bytes returned there as used, then they will be
@ -182,7 +182,7 @@ EAPI Eina_Rw_Slice eina_binbuf_expand(Eina_Binbuf *buf, size_t minimum_unused_sp
EAPI Eina_Bool eina_binbuf_use(Eina_Binbuf *buf, size_t extra_bytes) EINA_ARG_NONNULL(1);
/**
* @brief Append a string of exact length to a buffer, reallocating as necessary.
* @brief Appends a string of exact length to a buffer, reallocating as necessary.
*
* @param buf The string buffer to append to.
* @param str The string to append.
@ -203,7 +203,7 @@ EAPI Eina_Bool eina_binbuf_use(Eina_Binbuf *buf, size_t extra_bytes) EINA_ARG_NO
EAPI Eina_Bool eina_binbuf_append_length(Eina_Binbuf *buf, const unsigned char *str, size_t length) EINA_ARG_NONNULL(1, 2);
/**
* @brief Append a slice to a buffer, reallocating as necessary.
* @brief Appends a slice to a buffer, reallocating as necessary.
*
* @param buf The string buffer to append to.
* @param slice The slice to append.
@ -217,7 +217,7 @@ EAPI Eina_Bool eina_binbuf_append_length(Eina_Binbuf *buf, const unsigned char *
EAPI Eina_Bool eina_binbuf_append_slice(Eina_Binbuf *buf, const Eina_Slice slice) EINA_ARG_NONNULL(1);
/**
* @brief Append an Eina_Binbuf to a buffer, reallocating as necessary.
* @brief Appends an Eina_Binbuf to a buffer, reallocating as necessary.
*
* @param buf The string buffer to append to.
* @param data The string buffer to append.
@ -236,7 +236,7 @@ EAPI Eina_Bool eina_binbuf_append_slice(Eina_Binbuf *buf, const Eina_Slice slice
EAPI Eina_Bool eina_binbuf_append_buffer(Eina_Binbuf *buf, const Eina_Binbuf *data) EINA_ARG_NONNULL(1, 2);
/**
* @brief Append a character to a string buffer, reallocating as
* @brief Appends a character to a string buffer, reallocating as
* necessary.
*
* @param buf The string buffer to append to.
@ -249,7 +249,7 @@ EAPI Eina_Bool eina_binbuf_append_buffer(Eina_Binbuf *buf, const Eina_Binbuf *da
EAPI Eina_Bool eina_binbuf_append_char(Eina_Binbuf *buf, unsigned char c) EINA_ARG_NONNULL(1);
/**
* @brief Insert a string of exact length to a buffer, reallocating as necessary.
* @brief Inserts a string of exact length to a buffer, reallocating as necessary.
*
* @param buf The string buffer to insert to.
* @param str The string to insert.
@ -271,7 +271,7 @@ EAPI Eina_Bool eina_binbuf_append_char(Eina_Binbuf *buf, unsigned char c) EINA_A
EAPI Eina_Bool eina_binbuf_insert_length(Eina_Binbuf *buf, const unsigned char *str, size_t length, size_t pos) EINA_ARG_NONNULL(1, 2);
/**
* @brief Insert a slice to a buffer, reallocating as necessary.
* @brief Inserts a slice to a buffer, reallocating as necessary.
*
* @param buf The string buffer to insert to.
* @param slice The slice to insert.
@ -287,7 +287,7 @@ EAPI Eina_Bool eina_binbuf_insert_length(Eina_Binbuf *buf, const unsigned char *
EAPI Eina_Bool eina_binbuf_insert_slice(Eina_Binbuf *buf, const Eina_Slice slice, size_t pos) EINA_ARG_NONNULL(1);
/**
* @brief Insert a character to a string buffer, reallocating as
* @brief Inserts a character to a string buffer, reallocating as
* necessary.
*
* @param buf The string buffer to insert to.
@ -302,7 +302,7 @@ EAPI Eina_Bool eina_binbuf_insert_slice(Eina_Binbuf *buf, const Eina_Slice slice
EAPI Eina_Bool eina_binbuf_insert_char(Eina_Binbuf *buf, unsigned char c, size_t pos) EINA_ARG_NONNULL(1);
/**
* @brief Remove a slice of the given string buffer.
* @brief Removes a slice of the given string buffer.
*
* @param buf The string buffer to remove a slice.
* @param start The initial (inclusive) slice position to start
@ -319,7 +319,7 @@ EAPI Eina_Bool eina_binbuf_insert_char(Eina_Binbuf *buf, unsigned char c, size_t
EAPI Eina_Bool eina_binbuf_remove(Eina_Binbuf *buf, size_t start, size_t end) EINA_ARG_NONNULL(1);
/**
* @brief Retrieve a pointer to the contents of a string buffer
* @brief Retrieves a pointer to the contents of a string buffer.
*
* @param buf The string buffer.
* @return The current string in the string buffer.
@ -334,7 +334,7 @@ EAPI Eina_Bool eina_binbuf_remove(Eina_Binbuf *buf, size_t start, size_t end) EI
EAPI const unsigned char *eina_binbuf_string_get(const Eina_Binbuf *buf) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
/**
* @brief Steal the contents of a string buffer.
* @brief Steals the contents of a string buffer.
*
* @param buf The string buffer to steal.
* @return The current string in the string buffer.
@ -349,7 +349,7 @@ EAPI const unsigned char *eina_binbuf_string_get(const Eina_Binbuf *buf) EINA_AR
EAPI unsigned char *eina_binbuf_string_steal(Eina_Binbuf *buf) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
/**
* @brief Free the contents of a string buffer but not the buffer.
* @brief Frees the contents of a string buffer but not the buffer.
*
* @param buf The string buffer to free the string of.
*
@ -359,7 +359,7 @@ EAPI unsigned char *eina_binbuf_string_steal(Eina_Binbuf *buf) EINA_MALLOC EINA_
EAPI void eina_binbuf_string_free(Eina_Binbuf *buf) EINA_ARG_NONNULL(1);
/**
* @brief Retrieve the length of the string buffer content.
* @brief Retrieves the length of the string buffer content.
*
* @param buf The string buffer.
* @return The current length of the string, in bytes.
@ -369,7 +369,7 @@ EAPI void eina_binbuf_string_free(Eina_Binbuf *buf) EINA_ARG_NONNULL(1);
EAPI size_t eina_binbuf_length_get(const Eina_Binbuf *buf) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
/**
* @brief Get a read-only slice representing the current binbuf contents.
* @brief Gets a read-only slice representing the current binbuf contents.
*
* @param buf the src buffer.
* @return a read-only slice for the current contents. It may become
@ -380,7 +380,7 @@ EAPI size_t eina_binbuf_length_get(const Eina_Binbuf *buf) EINA_ARG_NONNULL(1
EAPI Eina_Slice eina_binbuf_slice_get(const Eina_Binbuf *buf) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
/**
* @brief Get a read-write slice representing the current binbuf contents.
* @brief Gets a read-write slice representing the current binbuf contents.
*
* @param buf the src buffer.
* @return a read-write slice for the current contents. It may become
@ -393,7 +393,7 @@ EAPI Eina_Slice eina_binbuf_slice_get(const Eina_Binbuf *buf) EINA_WARN_UNUSED_R
*/
EAPI Eina_Rw_Slice eina_binbuf_rw_slice_get(const Eina_Binbuf *buf) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
/**
* @brief Get the content of the buffer and free the buffer
* @brief Gets the content of the buffer and free the buffer.
*
* @param buf the buffer to get the content from and which will be freed
*

14
src/lib/eina/eina_binshare.h
View File

@ -129,14 +129,12 @@ EAPI void eina_binshare_del(const void *obj);
/**
* @brief Notes that the given object @b must be shared.
*
* @details This function is a cheap way to know the length of a shared
* object.
* @param[in] obj The shared object to know the length \n
* It is safe to give @c NULL, in which case @c -1 is returned
* @return The length of the shared object
*
* @details This function is a cheap way to know the length of a shared
* object.
*
* @warning If the given pointer is not shared, bad things happen, mostly a
* segmentation fault. If in doubt, try strlen().
*/
@ -152,16 +150,14 @@ EAPI void eina_binshare_dump(void);
/**
* @brief Retrieves an instance of a blob for use in a program.
*
* @param ptr The binary blob to retrieve an instance of
* @return A pointer to an instance of the string on success,
* otherwise @c NULL on failure
*
* @details This macro retrieves an instance of @p obj. If @p obj is
* @c NULL, then @c NULL is returned. If @p obj is already stored, it
* is just returned and its reference counter is increased. Otherwise
* it is added to the blobs to be searched and a duplicated blob
* of @p obj is returned.
* @param ptr The binary blob to retrieve an instance of
* @return A pointer to an instance of the string on success,
* otherwise @c NULL on failure
*
* @note This macro essentially calls eina_binshare_add_length with ptr and sizeof(*ptr)
* as the parameters. It's useful for pointers to structures.

13
src/lib/eina/eina_clist.h
View File

@ -169,14 +169,13 @@ static inline void eina_clist_add_tail(Eina_Clist *list, Eina_Clist *elem);
/**
* @brief Inits an (unlinked) element.
* @details This function is called on elements that have not been added to the list
* so that eina_clist_element_init() works correctly.
*
* @param[in] elem An element
* @pre The element is not in any list.
* @post The element is marked as not being in any list.
*
* @details This function is called on elements that have not been added to the list
* so that eina_clist_element_init() works correctly.
*
* @note It is not necessary to call this before adding an element to this list.
*
* @since 1.1.0
@ -324,7 +323,7 @@ static inline void eina_clist_move_head(Eina_Clist *dst, Eina_Clist *src);
* @brief Iterates through the list, with safety against removal.
*
* @param cursor The pointer to be used during the interaction
* @param cursor2 The auxiliar pointer to be used during the interaction
* @param cursor2 The auxiliary pointer to be used during the interaction
* @param list The list to be interacted with
*/
#define EINA_CLIST_FOR_EACH_SAFE(cursor, cursor2, list) \
@ -351,7 +350,7 @@ static inline void eina_clist_move_head(Eina_Clist *dst, Eina_Clist *src);
* @brief Iterates through the list using a list entry, with safety against removal.
*
* @param cursor The pointer to be used during the interaction
* @param cursor2 The auxiliar pointer to be used during the interaction
* @param cursor2 The auxiliary pointer to be used during the interaction
* @param list The list to be interacted with
* @param type The type of the list
* @param field The field of the element
@ -378,7 +377,7 @@ static inline void eina_clist_move_head(Eina_Clist *dst, Eina_Clist *src);
* @brief Iterates through the list in the reverse order, with safety against removal.
*
* @param cursor The pointer to be used during the interaction
* @param cursor2 The auxiliar pointer to be used during the interaction
* @param cursor2 The auxiliary pointer to be used during the interaction
* @param list The list to be interacted with
*/
#define EINA_CLIST_FOR_EACH_SAFE_REV(cursor, cursor2, list) \
@ -406,7 +405,7 @@ static inline void eina_clist_move_head(Eina_Clist *dst, Eina_Clist *src);
* removal.
*
* @param cursor The pointer to be used during the interaction
* @param cursor2 The auxiliar pointer to be used during the interaction
* @param cursor2 The auxiliary pointer to be used during the interaction
* @param list The list to be interacted with
* @param type The type of the list
* @param field The field of the element

56
src/lib/eina/eina_convert.h
View File

@ -92,15 +92,15 @@
*
* To convert a string to a double, eina_convert_atod() should be
* used. The format of the string must be as above. Then, the double
* has the following mantiss and exponent:
* has the following mantissas and exponent:
*
* @code
* mantiss : [-]hhhhhh
* exponent : 2^([+-]e - 4 * n)
* @endcode
*
* with n being number of cypers after the point in the string
* format. To obtain the double number from the mantiss and exponent,
* with n being number of cyphers after the point in the string
* format. To obtain the double number from the mantissas and exponent,
* use ldexp().
*
* Here is an example of use:
@ -163,31 +163,31 @@ EAPI extern Eina_Error EINA_ERROR_CONVERT_0X_NOT_FOUND; /**< Not used, perhaps a
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.
* @brief Converts an integer number to a string in decimal base.
*
* @param n The integer to convert.
* @param s The buffer to store the converted integer.
* @return The length of the string, including the nul terminated
* @return The length of the string, including the null terminated
* character.
*
* This function converts @p n to a nul terminated string. The
* This function converts @p n to a null terminated string. The
* converted string is in decimal base. As no check is done, @p s must
* be a buffer that is sufficiently large to store the integer.
*
* The returned value is the length of the string, including the nul
* The returned value is the length of the string, including the null
* terminated character.
*/
EAPI int eina_convert_itoa(int n, char *s) EINA_ARG_NONNULL(2);
/**
* @brief Convert an integer number to a string in hexadecimal base.
* @brief Converts an integer number to a string in hexadecimal base.
*
* @param n The integer to convert.
* @param s The buffer to store the converted integer.
* @return The length of the string, including the nul terminated
* @return The length of the string, including the null terminated
* character.
*
* This function converts @p n to a nul terminated string. The
* This function converts @p n to a null terminated string. The
* converted string is in hexadecimal base and the alphabetical
* cyphers are in lower case. As no check is done, @p s must be a
* buffer that is sufficiently large to store the integer.
@ -199,7 +199,7 @@ EAPI int eina_convert_xtoa(unsigned int n, char *s) EINA_ARG_NONNULL(2);
/**
* @brief Convert a double to a string.
* @brief Converts a double to a string.
*
* @param d The double to convert.
* @param des The destination buffer to store the converted double.
@ -207,27 +207,27 @@ EAPI int eina_convert_xtoa(unsigned int n, char *s) EINA_ARG_NONNULL(2);
*
* This function converts the double @p d to a string. The string is
* stored in the buffer pointed by @p des and must be sufficiently
* large to contain the converted double. The returned string is nul
* large to contain the converted double. The returned string is null
* terminated and has the following format:
*
* @code
* [-]0xh.hhhhhp[+-]e
* @endcode
*
* where the h are the hexadecimal cyphers of the mantiss and e the
* where the h are the hexadecimal cyphers of the mantissas and e the
* exponent (a decimal number).
*
* The returned value is the length of the string, including the nul
* The returned value is the length of the string, including the null
* character.
*/
EAPI int eina_convert_dtoa(double d, char *des) EINA_ARG_NONNULL(2);
/**
* @brief Convert a string to a double.
* @brief Converts a string to a double.
*
* @param src The string to convert.
* @param length The length of the string.
* @param m The mantisse.
* @param m The mantissa.
* @param e The exponent.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
@ -242,16 +242,16 @@ EAPI int eina_convert_dtoa(double d, char *des) EINA_ARG_NONNULL(2);
* [-]0xh.hhhhhp[+-]e
* @endcode
*
* where the h are the hexadecimal cyphers of the mantiss and e the
* exponent (a decimal number). If n is the number of cypers after the
* point, the returned mantiss and exponents are:
* where the h are the hexadecimal cyphers of the mantissas and e the
* exponent (a decimal number). If n is the number of cyphers after the
* point, the returned mantissas and exponents are:
*
* @code
* mantiss : [-]hhhhhh
* exponent : 2^([+-]e - 4 * n)
* @endcode
*
* The mantiss and exponent are stored in the buffers pointed
* The mantissas and exponent are stored in the buffers pointed
* respectively by @p m and @p e.
*
* If the string is invalid #EINA_FALSE is returned, otherwise #EINA_TRUE is
@ -264,7 +264,7 @@ EAPI Eina_Bool eina_convert_atod(const char *src,
/**
* @brief Convert a 32.32 fixed point number to a string.
* @brief Converts a 32.32 fixed point number to a string.
*
* @param fp The fixed point number to convert.
* @param des The destination buffer to store the converted fixed point number.
@ -280,10 +280,10 @@ EAPI Eina_Bool eina_convert_atod(const char *src,
* [-]0xh.hhhhhp[+-]e
* @endcode
*
* where the h are the hexadecimal cyphers of the mantiss and e the
* where the h are the hexadecimal cyphers of the mantissas and e the
* exponent (a decimal number).
*
* The returned value is the length of the string, including the nul
* The returned value is the length of the string, including the null
* character.
*
* @note The code is the same than eina_convert_dtoa() except that it
@ -294,7 +294,7 @@ EAPI int eina_convert_fptoa(Eina_F32p32 fp,
char *des) EINA_ARG_NONNULL(2);
/**
* @brief Convert a string to a 32.32 fixed point number.
* @brief Converts a string to a 32.32 fixed point number.
*
* @param src The string to convert.
* @param length The length of the string.
@ -312,16 +312,16 @@ EAPI int eina_convert_fptoa(Eina_F32p32 fp,
* [-]0xh.hhhhhp[+-]e
* @endcode
*
* where the h are the hexadecimal cyphers of the mantiss and e the
* exponent (a decimal number). If n is the number of cypers after the
* point, the returned mantiss and exponents are:
* where the h are the hexadecimal cyphers of the mantissas and e the
* exponent (a decimal number). If n is the number of cyphers after the
* point, the returned mantissas and exponents are:
*
* @code
* mantiss : [-]hhhhhh
* exponent : 2^([+-]e - 4 * n)
* @endcode
*
* The mantiss and exponent are stored in the buffers pointed
* The mantissas and exponent are stored in the buffers pointed
* respectively by @p m and @p e.
*
* If the string is invalid, #EINA_FALSE is returned,

31
src/lib/eina/eina_counter.h
View File

@ -114,14 +114,13 @@ typedef struct _Eina_Counter Eina_Counter;
/**
* @brief Returns a counter.
*
* @param[in] name The name of the counter
* @return A newly allocated counter
*
* @details This function returns a new counter. It is characterized by @p
* name. If @p name is @c NULL, the function returns @c NULL
* immediately. If memory allocation fails, @c NULL is returned.
*
* @param[in] name The name of the counter
* @return A newly allocated counter
*
* @note Whe the new counter is not needed anymore, use eina_counter_free() to
* free the allocated memory.
*/
@ -129,25 +128,23 @@ EAPI Eina_Counter *eina_counter_new(const char *name) EINA_WARN_UNUSED_RESULT EI
/**
* @brief Deletes a counter.
*
* @param[in] counter The counter to delete
*
* @details This function removes the clock of @p counter from the used clocks
* (see eina_counter_start()) and frees the memory allocated for
* @p counter. If @p counter is @c NULL, the function returns
* immediately.
* @param[in] counter The counter to delete
*
*/
EAPI void eina_counter_free(Eina_Counter *counter) EINA_ARG_NONNULL(1);
/**
* @brief Starts the time count.
*
* @param[in] counter The counter
*
* @details This function specifies that the part of the code beginning just
* after its call is being timed, using @p counter. If
* @p counter is @c NULL, this function returns immediately.
*
* @param[in] counter The counter
*
* @note This function adds the clock associated to @p counter in a list. If
* the memory needed by that clock can not be allocated, the function
* returns and nothing is done.
@ -159,30 +156,28 @@ EAPI void eina_counter_start(Eina_Counter *counter) EINA_ARG_NONNULL(1)
/**
* @brief Stops the time count.
*
* @param[in] counter The counter
* @param[in] specimen The number of the test
*
* @details This function stops the timing that has been started with
* eina_counter_start(). @p counter must be the same as the one used
* with eina_counter_start(). @p specimen is the number of the
* test. If @p counter or its associated clock is @c NULL, or if the
* time can't be retrieved the function exits.
* @param[in] counter The counter
* @param[in] specimen The number of the test
*
*/
EAPI void eina_counter_stop(Eina_Counter *counter,
int specimen) EINA_ARG_NONNULL(1);
/**
* @brief Dumps the result of all the clocks of a counter to a stream.
*
* @param[in] counter The counter
* @return A string with a summary of the test
*
* @details This function returns an malloc'd string containing the dump of
* all the valid clocks of @p counter.
* If @p counter is @c NULL, the functions exits
* immediately. Otherwise, the output is formatted like this:
*
* @param[in] counter The counter
* @return A string with a summary of the test
*
* @verbatim
* \# specimen experiment time starting time ending time
* 1 208 120000 120208

22
src/lib/eina/eina_cow.h
View File

@ -52,33 +52,33 @@ typedef struct _Eina_Cow Eina_Cow;
typedef void Eina_Cow_Data;
/**
* @brief Instantiate a new Eina_Cow pool.
* @brief Instantiates a new Eina_Cow pool.
*
* @param name The name of this pool, used for debug.
* @param struct_size The size of the object from this pool.
* @param step How many objects to allocate when the pool gets empty.
* @param default_value The default value returned by this pool.
* @param gc Is it possible to run garbage collection on this pool.
* @return a valid new Eina_Cow or @c NULL on error.
* @return A valid new Eina_Cow, or @c NULL on error.
*/
EAPI Eina_Cow *eina_cow_add(const char *name, unsigned int struct_size, unsigned int step, const void *default_value, Eina_Bool gc) EINA_WARN_UNUSED_RESULT;
/**
* @brief Destroy an Eina_Cow pool and all the allocated memory
* @brief Destroys an Eina_Cow pool and all the allocated memory.
*
* @param cow The pool to destroy
*/
EAPI void eina_cow_del(Eina_Cow *cow);
/**
* @brief Return an initialized pointer from the pool.
* @brief Returns 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;
/**
* @brief Free a pointer from the pool.
* @brief Frees a pointer from the pool.
* @param cow The pool to gave back memory to.
* @param data The data to give back.
*
@ -88,7 +88,7 @@ EAPI const Eina_Cow_Data *eina_cow_alloc(Eina_Cow *cow) EINA_WARN_UNUSED_RESULT;
EAPI void eina_cow_free(Eina_Cow *cow, const Eina_Cow_Data **data);
/**
* @brief Get a writable pointer from a const pointer.
* @brief Gets a writeable pointer from a const pointer.
* @param cow The pool the pointer come from.
* @param src The pointer you want to write to.
*
@ -97,7 +97,7 @@ EAPI void eina_cow_free(Eina_Cow *cow, const Eina_Cow_Data **data);
EAPI void *eina_cow_write(Eina_Cow *cow,
const Eina_Cow_Data * const *src) EINA_WARN_UNUSED_RESULT;
/**
* @brief Set back a pointer into read only.
* @brief Sets back a pointer into read only.
* @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.
@ -110,7 +110,7 @@ EAPI void eina_cow_done(Eina_Cow *cow,
const void *data,
Eina_Bool needed_gc);
/**
* @brief Make the destination contain the same thing as the source pointer.
* @brief Makes the destination contain the same thing as the source pointer.
* @param cow The pool the pointers come from.
* @param dst The destination to update.
* @param src The source of information to copy.
@ -120,7 +120,7 @@ EAPI void eina_cow_memcpy(Eina_Cow *cow,
const Eina_Cow_Data *src);
/**
* @brief Try to find entries that have the same content and update them.
* @brief Tries to find entries that have the same content and update them.
* @param cow The cow to try to compact.
* @return EINA_TRUE if something was compacted, EINA_FALSE if nothing was.
*
@ -132,7 +132,7 @@ EAPI Eina_Bool eina_cow_gc(Eina_Cow *cow);
/**
* @def EINA_COW_WRITE_BEGIN
* @brief This macro setup a writable pointer from a const one.
* @brief Definition for the macro to setup a writeable pointer from a const one.
* @param Cow The Eina_Cow where the const pointer come from.
* @param Read The const pointer to get a writable handler from.
* @param Write_Type The type of the pointer you want to write to.
@ -151,7 +151,7 @@ EAPI Eina_Bool eina_cow_gc(Eina_Cow *cow);
/**
* @def EINA_COW_WRITE_END
* @brief This macro close the writable pointer.
* @brief Definition for the macro to close the writeable pointer.
* @param Cow The Eina_Cow where the const pointer come from.
* @param Read The const pointer to get a writable handler from.
* @param Write The name of the variable where to put the writeable pointer to.

18
src/lib/eina/eina_cpu.h
View File

@ -59,31 +59,31 @@ typedef enum _Eina_Cpu_Features
} Eina_Cpu_Features;
/**
* @brief Global hardware architecture handler
* @brief Global hardware architecture handler.
*
* @return the current cpu features
*/
EAPI extern Eina_Cpu_Features eina_cpu_features;
/**
* @brief Cpu features accessor
* @brief Cpu features accessor.
*
* @return the current cpu features
*/
EAPI Eina_Cpu_Features eina_cpu_features_get(void);
/**
* @brief Get the current number of processors
* @brief Gets the current number of processors.
*
* @return the number of processors that are online, that
* @return The number of processors that are online, that
* is available when the function is called.
*/
EAPI int eina_cpu_count(void);
/**
* @brief Get the current virtual page size
* @brief Gets the current virtual page size.
*
* @return the fixed length that represents the smallest unit of data for memory
* @return The fixed length that represents the smallest unit of data for memory
* allocation performed by the operating system on behalf of the program, and
* for transfers between the main memory and any other auxiliary store.
*/
@ -93,7 +93,7 @@ EAPI int eina_cpu_page_size(void);
* @brief Reverses the byte order of a 16-bit (destination) register.
*
* @param x The binary word to swap
* @return a byte order swapped 16-bit integer.
* @return A byte order swapped 16-bit integer.
*
* On big endian systems, the number is converted to little endian byte order.
* On little endian systems, the number is converted to big endian byte order.
@ -104,7 +104,7 @@ static inline unsigned short eina_swap16(unsigned short x);
* @brief Reverses the byte order of a 32-bit (destination) register.
*
* @param x The binary word to swap
* @return a byte order swapped 32-bit integer.
* @return A byte order swapped 32-bit integer.
*
* On big endian systems, the number is converted to little endian byte order.
* On little endian systems, the number is converted to big endian byte order.
@ -115,7 +115,7 @@ static inline unsigned int eina_swap32(unsigned int x);
* @brief Reverses the byte order of a 64-bit (destination) register.
*
* @param x The binary word to swap
* @return a byte order swapped 64-bit integer.
* @return A byte order swapped 64-bit integer.
*
* On big endian systems, the number is converted to little endian byte order.
* On little endian systems, the number is converted to big endian byte order.

2
src/lib/eina/eina_crc.h
View File

@ -12,7 +12,7 @@
#include "eina_magic.h"
/**
* @brief Generate a crc checksum for the given data using crc-32 algorithm.
* @brief Generates a crc checksum for the given data using crc-32 algorithm.
*
* @param key The data for which crc checksum has to be generated.
* @param len The length of the data.

49
src/lib/eina/eina_error.h
View File

@ -107,16 +107,15 @@ EAPI extern Eina_Error EINA_ERROR_OUT_OF_MEMORY EINA_DEPRECATED; /* use ENOMEM *
/**
* @brief Registers a new error type.
*
* @param[in] msg The description of the error \n
* It is duplicated using eina_stringshare_add().
* @return The unique number identifier for this error
*
* @details This function stores the error message described by
* @p msg in a list. The returned value is a unique identifier greater than or equal
* to @c 1. The description can be retrieved later by passing
* the returned value to eina_error_msg_get().
*
* @param[in] msg The description of the error \n
* It is duplicated using eina_stringshare_add().
* @return The unique number identifier for this error
*
* @note There is no need to register messages that exist in libC's @c
* errno.h, such as @c ENOMEM or @c EBADF.
*
@ -126,17 +125,16 @@ EAPI Eina_Error eina_error_msg_register(const char *msg) EINA_ARG_NONNULL(1) EI
/**
* @brief Registers a new error type, statically allocated message.
* @details This function stores the error message described by
* @p msg in a list. The returned value is a unique identifier greater than or equal
* to @c 1. The description can be retrieved later by passing
* the returned value to eina_error_msg_get().
*
* @param[in] msg The description of the error \n
* This string is not duplicated and thus
* the given pointer should live during the usage of eina_error.
* @return The unique number identifier for this error
*
* @details This function stores the error message described by
* @p msg in a list. The returned value is a unique identifier greater than or equal
* to @c 1. The description can be retrieved later by passing
* the returned value to eina_error_msg_get().
*
* @note There is no need to register messages that exist in libC's @c
* errno.h, such as @c ENOMEM or @c EBADF.
*
@ -146,6 +144,10 @@ EAPI Eina_Error eina_error_msg_static_register(const char *msg) EINA_ARG_NONNUL
/**
* @brief Changes the message of an already registered message.
* @details This function modifies the message associated with @p error and changes
* it to @p msg. If the error is previously registered by @ref eina_error_msg_static_register
* then the string is not duplicated, otherwise the previous message
* is unrefed and @p msg is copied.
*
* @param[in] error The Eina_Error to change the message of
* @param[in] msg The description of the error \n
@ -153,11 +155,6 @@ EAPI Eina_Error eina_error_msg_static_register(const char *msg) EINA_ARG_NONNUL
* otherwise it must remain intact for the duration.
* @return #EINA_TRUE if successful, otherwise #EINA_FALSE on error
*
* @details This function modifies the message associated with @p error and changes
* it to @p msg. If the error is previously registered by @ref eina_error_msg_static_register
* then the string is not duplicated, otherwise the previous message
* is unrefed and @p msg is copied.
*
* @note It is not possible to modify messages that exist in libC's @c
* errno.h, such as @c ENOMEM or @c EBADF.
*
@ -169,24 +166,22 @@ EAPI Eina_Bool eina_error_msg_modify(Eina_Error error,
/**
* @brief Returns the last set error.
*
* @return The last error or 0 (#EINA_ERROR_NO_ERROR).
*
* @details This function returns the last error set by eina_error_set(). The
* description of the message is returned by eina_error_msg_get().
*
* @return The last error or 0 (#EINA_ERROR_NO_ERROR).
*
* @note This function is thread safe @since 1.10, but slower to use.
*/
EAPI Eina_Error eina_error_get(void);
/**
* @brief Sets the last error.
*
* @param[in] err The error identifier
*
* @details This function sets the last error identifier. The last error can be
* retrieved by eina_error_get().
*
* @param[in] err The error identifier
*
* @note This is also used to clear previous errors, in which case @p err should
* be @c 0 (#EINA_ERROR_NO_ERROR).
*
@ -196,25 +191,23 @@ EAPI void eina_error_set(Eina_Error err);
/**
* @brief Returns the description of the given error number.
*
* @param[in] error The error number
* @return The description of the error
*
* @details This function returns the description of an error that has been
* registered by eina_error_msg_register(). If an incorrect error is
* given, then @c NULL is returned.
* @param[in] error The error number
* @return The description of the error
*
*/
EAPI const char *eina_error_msg_get(Eina_Error error) EINA_PURE;
/**
* @brief Finds the #Eina_Error corresponding to a message string.
* @details This function attempts to match @p msg with its corresponding #Eina_Error value.
* If no such value is found, @c 0 is returned.
*
* @param[in] msg The error message string to match (NOT @c NULL)
* @return The #Eina_Error matching @p msg, otherwise @c 0 on failure
*
* @details This function attempts to match @p msg with its corresponding #Eina_Error value.
* If no such value is found, @c 0 is returned.
*
* @note this function only works for explicitly registered errors
* such as the messages given to eina_error_msg_register(),
* eina_error_msg_static_register() or modified with

8
src/lib/eina/eina_evlog.h
View File

@ -56,7 +56,7 @@ struct _Eina_Evlog_Buf
};
/**
* @brief Log an event in our event log for profiling data
* @brief Logs an event in our event log for profiling data.
*
* Log some interesting event inside of EFL, eg a wakeup (and why etc.).
* The @p event string must alwasy be provided and be of the form:
@ -117,7 +117,7 @@ EAPI void
eina_evlog(const char *event, void *obj, double srctime, const char *detail);
/**
* @brief Steal an event log buffer from the evlog core
* @brief Steals an event log buffer from the evlog core.
*
* Only one buffer can be stolen at any time. If you steal a new buffer, the
* old stolen buffer is "released" back to the evlog core.
@ -130,7 +130,7 @@ EAPI Eina_Evlog_Buf *
eina_evlog_steal(void);
/**
* @brief Begin logging - until now eina_evlog is a NOOP
* @brief Begins logging - until now eina_evlog is a NOOP.
*
* @since 1.15
*/
@ -138,7 +138,7 @@ EAPI void
eina_evlog_start(void);
/**
* @brief Stop logging
* @brief Stops logging.
*
* You must not be using any evlog buffers stolen by eina_evlog_steal() by
* the time you call this function.

156
src/lib/eina/eina_file.h
View File

@ -71,7 +71,7 @@
* @brief This group discusses the functions to handle files and directories.
*
* @details These functions make it easier to do a number of file and directory operations
* such as getting the list of files in a directory, spliting paths, and finding
* such as getting the list of files in a directory, splitting paths, and finding
* out file size and type.
*
* @warning All functions in this group are @b blocking, which means they may
@ -159,7 +159,7 @@ typedef enum {
* it never happens */
/**
* @def EINA_PATH_MAX
* @brief The constant defined as the highest value for PATH_MAX.
* @brief Definition for the constant defined as the highest value for PATH_MAX.
*/
#define EINA_PATH_MAX 8192
@ -239,23 +239,15 @@ struct _Eina_File_Line
/**
* @def EINA_FILE_DIR_LIST_CB
* @brief The macro to cast to an #Eina_File_Dir_List_Cb.
*
* @details This macro casts @p function to #Eina_File_Dir_List_Cb.
* @param function The function to cast
*
* @details This macro casts @p function to #Eina_File_Dir_List_Cb.
*/
#define EINA_FILE_DIR_LIST_CB(function) ((Eina_File_Dir_List_Cb)function)
/**
* @brief Lists all the files on the directory by calling the function for every file found.
*
* @param[in] dir The directory name
* @param[in] recursive Iterate recursively in the directory
* @param[in] cb The callback to be called
* @param[in] data The data to pass to the callback
* @return #EINA_TRUE on success, otherwise #EINA_FALSE
*
* @details This function calls @p cb for each file that is in @p dir. To have @p cb
* called on the files that are in subdirectories of @p dir, @p recursive should
* be #EINA_TRUE. In other words, if @p recursive is #EINA_FALSE, only direct children
@ -265,6 +257,12 @@ struct _Eina_File_Line
* If @p cb or @p dir is @c NULL or if @p dir is a string of size 0,
* or if @p dir cannot be opened, this function returns #EINA_FALSE
* immediately. Otherwise, it returns #EINA_TRUE.
*
* @param[in] dir The directory name
* @param[in] recursive Iterate recursively in the directory
* @param[in] cb The callback to be called
* @param[in] data The data to pass to the callback
* @return #EINA_TRUE on success, otherwise #EINA_FALSE
*/
EAPI Eina_Bool eina_file_dir_list(const char *dir,
Eina_Bool recursive,
@ -273,28 +271,27 @@ EAPI Eina_Bool eina_file_dir_list(const char *dir,
/**
* @brief Splits a path according to the delimiter of the filesystem.
*
* @param[in] path The path to split
* @return An array of the parts of the path to split
*
* @details This function splits @p path according to the delimiter of the used
* filesystem. If @p path is @c NULL or if the array cannot be
* created, @c NULL is returned, otherwise an array with each part of @p path
* is returned.
*
* @param[in] path The path to split
* @return An array of the parts of the path to split
*
*/
EAPI Eina_Array *eina_file_split(char *path) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
/**
* @brief Gets an iterator to list the content of a directory.
* @details This returns an iterator for shared strings, the name of each file in @p dir is
* only fetched when advancing the iterator, which means there is very little
* cost associated with creating the list and stopping halfway through it.
*
* @param [in] dir The name of the directory to list
* @return An #Eina_Iterator that walks over the files and directories
* in @p dir. On failure, it returns @c NULL.
*
* @details This returns an iterator for shared strings, the name of each file in @p dir is
* only fetched when advancing the iterator, which means there is very little
* cost associated with creating the list and stopping halfway through it.
*
* @note The iterator hands the user a stringshared value with the full
* path. The user must free the string using eina_stringshare_del() on it.
*
@ -308,16 +305,15 @@ EAPI Eina_Iterator *eina_file_ls(const char *dir) EINA_WARN_UNUSED_RESULT EINA_A
/**
* @brief Gets an iterator to list the content of a directory, with direct
* information.
* @details This returns an iterator for #Eina_File_Direct_Info, the name of each file in @p
* dir is only fetched when advancing the iterator, which means there is
* cost associated with creating the list and stopping halfway through it.
*
* @param [in] dir The name of the directory to list
*
* @return An #Eina_Iterator that walks over the files and
* directories in @p dir. On failure, it returns @c NULL.
*
* @details This returns an iterator for #Eina_File_Direct_Info, the name of each file in @p
* dir is only fetched when advancing the iterator, which means there is
* cost associated with creating the list and stopping halfway through it.
*
* @warning The #Eina_File_Direct_Info returned by the iterator <b>must not</b>
* be modified in any way.
* @warning When the iterator is advanced or deleted the #Eina_File_Direct_Info
@ -336,14 +332,13 @@ EAPI Eina_Iterator *eina_file_stat_ls(const char *dir) EINA_WARN_UNUSED_RESULT E
/**
* @brief Uses information provided by #Eina_Iterator of eina_file_stat_ls() or eina_file_direct_ls()
* to call stat in the most efficient way on your system.
* @details This function calls fstatat or stat depending on what your system supports. This makes it efficient and simple
* to use on your side without complex detection already done inside Eina on what the system can do.
*
* @param[in] container The container returned by #Eina_Iterator using eina_iterator_container_get()
* @param[in] info The content of the current #Eina_File_Direct_Info provided by #Eina_Iterator
* @param[in] buf The location put the result of the stat
* @return @c 0 is returnedon success, otherwise @c -1 is returned on error and errno is set appropriately
*
* @details This function calls fstatat or stat depending on what your system supports. This makes it efficient and simple
* to use on your side without complex detection already done inside Eina on what the system can do.
* @return @c 0 is returned on success, otherwise @c -1 is returned on error and errno is set appropriately
*
* @see eina_file_direct_ls()
* @see eina_file_stat_ls()
@ -355,19 +350,18 @@ EAPI int eina_file_statat(void *container, Eina_File_Direct_Info *info, Eina_Sta
/**
* @brief Generates and creates a uniquely named temporary file from a template name.
* The generated file is opened with the open(2) @c O_EXCL flag.
* @details This function calls mkstemp(), generates a unique temporary filename
* from template, creates and opens the file, and returns an open file
* descriptor for the file.
*
* @param[in] templatename This is a string. It must contain the six characters 'XXXXXX'
* at the end or directly followed by an extension as in
* at the end or directly followed by an extension as in
* 'prefixXXXXXX.ext'.
* @param[out] path The path to the created temporary file, or @c NULL in case of failure.
* It must be released by eina_tmpstr_del().
* @return On success @c file descriptor of the temporary file is returned,
* @return On success @c file descriptor of the temporary file is returned,
* On error @c -1 is returned, in which case @c errno is set appropriately.
*
* @details This function calls mkstemp(), generates a unique temporary filename
* from template, creates and opens the file, and returns an open file
* descriptor for the file.
*
* @note If a filename extension was specified in @p templatename, then the new @p path
* will also contain this extension (since 1.10).
*
@ -376,7 +370,7 @@ EAPI int eina_file_statat(void *container, Eina_File_Direct_Info *info, Eina_Sta
* the system temporary directory (@see eina_environment_tmp_get()). If the
* @p templatename contains a directory separator ('/', or '\\' on Windows)
* then the file will be created inside this directory, which must exist and
* be writable. Use ./filename.XXXXXX to create files in the current
* be writeable. Use ./filename.XXXXXX to create files in the current
* working directory. (since 1.17)
*
* @see eina_file_mkdtemp()
@ -386,23 +380,22 @@ EAPI int eina_file_mkstemp(const char *templatename, Eina_Tmpstr **path) EINA_AR
/**
* @brief Generates and creates a uniquely named temporary directory from a template name.
* @details This function calls mkdtemp(). The directory is then created with
* permissions 0700.
*
* @param[in] templatename This is a string. The last six characters of @p templatename
* @param[in] templatename This is a string. The last six characters of @p templatename
* must be XXXXXX.
* @param[out] path The path to the created temporary directory, or @c NULL in case of failure.
* It must be released by eina_tmpstr_del().
* @return On success @c EINA_TRUE is returned, On error @c EINA_FALSE is returned,
* @return On success @c EINA_TRUE is returned, On error @c EINA_FALSE is returned,
* in which case @c errno is set appropriately.
*
* @details This function calls mkdtemp(). The directory is then created with
* permissions 0700.
*
* @note If the @p templatename is a simple directory name (no relative or absolute
* path to another directory), then a temporary directory will be created inside
* the system temporary directory (@see eina_environment_tmp_get()). If the
* @p templatename contains a directory separator ('/', or '\\' on Windows)
* then the temporary directory will be created inside that other directory,
* which must exist and be writable. (since 1.17)
* which must exist and be writeable. (since 1.17)
*
* @see eina_file_mkstemp()
* @since 1.8
@ -412,16 +405,15 @@ EAPI Eina_Bool eina_file_mkdtemp(const char *templatename, Eina_Tmpstr **path) E
/**
* @brief Gets an iterator to list the content of a directory, with direct
* information.
* @details This returns an iterator for #Eina_File_Direct_Info, the name of each file in
* @p dir is only fetched when advancing the iterator, which means there is
* cost associated with creating the list and stopping halfway through it.
*
* @param [in] dir The name of the directory to list
*
* @return An Eina_Iterator that walks over the files and
* directories in @p dir. On failure, it returns @c NULL.
*
* @details This returns an iterator for #Eina_File_Direct_Info, the name of each file in
* @p dir is only fetched when advancing the iterator, which means there is
* cost associated with creating the list and stopping halfway through it.
*
* @warning If readdir_r doesn't contain file type information, file type is
* EINA_FILE_UNKNOWN.
* @warning The #Eina_File_Direct_Info returned by the iterator <b>must not</b>
@ -441,15 +433,14 @@ EAPI Eina_Iterator *eina_file_direct_ls(const char *dir) EINA_WARN_UNUSED_RESULT
/**
* @brief Sanitizes the file path.
* @details This function takes care of adding the current working directory if its a
* relative path and also removes all '..' and '//' references in the original
* path.
*
* @param[in] path The path to sanitize
*
* @return An allocated string with the sanitized path
*
* @details This function takes care of adding the current working directory if its a
* relative path and also removes all '..' and '//' references in the original
* path.
*
* @since 1.1
*/
EAPI char *eina_file_path_sanitize(const char *path);
@ -475,7 +466,9 @@ typedef enum {
} Eina_File_Copy_Flags;
/**
* @brief Copy one file to another using the fastest possible way and report progress.
* @brief Copies one file to another using the fastest possible way and report progress.
* @details This function tries to splice if it is available. It is blocked
* until the whole file is copied or it fails.
*
* @param[in] src The source file.
* @param[in] dst The destination file.
@ -485,31 +478,27 @@ typedef enum {
* @return #EINA_TRUE on success, #EINA_FALSE otherwise (and @p dst
* will be deleted)
*
* @details This function tries to splice if it is available. It is blocked
* until the whole file is copied or it fails.
*
* @note During the progress it may call back @p cb with the progress summary.
*/
EAPI Eina_Bool eina_file_copy(const char *src, const char *dst, Eina_File_Copy_Flags flags, Eina_File_Copy_Progress cb, const void *cb_data) EINA_ARG_NONNULL(1, 2);
/**
* @brief Gets a read-only handler to a file.
* @details This opens a file in the read-only mode. @p name should be an absolute path. An
* #Eina_File handle can be shared among multiple instances if @p shared
* is #EINA_TRUE, otherwise.
*
* @param[in] name The filename to open
* @param[in] shared Requested a shm
* @return An #Eina_File handle to the file
*
* @details This opens a file in the read-only mode. @p name should be an absolute path. An
* #Eina_File handle can be shared among multiple instances if @p shared
* is #EINA_TRUE, otherwise.
*
* @since 1.1
*/
EAPI Eina_File *eina_file_open(const char *name, Eina_Bool shared) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
/**
* @brief Create a virtual file from a memory pointer.
* @brief Creates a virtual file from a memory pointer.
*
* @param[in] virtual_name A virtual name for Eina_File, if @c NULL, a generated one will be given
* @param[in] data The memory pointer to take data from
@ -523,7 +512,7 @@ EAPI Eina_File *
eina_file_virtualize(const char *virtual_name, const void *data, unsigned long long length, Eina_Bool copy) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
/**
* @brief Tells if a file is a real file or only exist in memory
* @brief Tells if a file is a real file or only exist in memory.
*
* @param file The file to test
* @return #EINA_TRUE if the file is a virtual file
@ -534,14 +523,13 @@ EAPI Eina_Bool
eina_file_virtual(Eina_File *file) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
/**
* @brief Refreshes file information
* @brief Refreshes file information.
* @details All current map continue to exist. You need to manually delete
* and recreate them to have the new correct mapping.
*
* @param file The file to refresh
* @return #EINA_TRUE if the file has changed
*
* @details All current map continue to exist. You need to manually delete
* and recreate them to have the new correct mapping.
*
* @since 1.8
*/
EAPI Eina_Bool eina_file_refresh(Eina_File *file);
@ -560,11 +548,10 @@ EAPI Eina_File * eina_file_dup(const Eina_File *file);
/**
* @brief Unrefs the file handler.
* @details This decrements the file's reference count and if it reaches zero it closes the file.
*
* @param[in] file The file handler to unref
*
* @details This decrements the file's reference count and if it reaches zero it closes the file.
*
* @since 1.1
*/
EAPI void eina_file_close(Eina_File *file);
@ -666,7 +653,10 @@ EAPI void *eina_file_map_new(Eina_File *file, Eina_File_Populate rule,
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
* @brief Asks the OS to populate or otherwise pages of memory in file mapping.
* @details This advises the operating system as to what to do with the memory mapped
* to the given @p file. This affects a specific range of memory and may not
* be honoured if the system chooses to ignore the request.
*
* @param[in] file The file handle from which the map comes
* @param[in] rule The rule to apply to the mapped memory
@ -674,10 +664,6 @@ EAPI void eina_file_map_free(Eina_File *file, void *map);
* @param[in] offset The offset in bytes from the start of the map address
* @param [in]length The length in bytes of the memory region to populate
*
* @details This advises the operating system as to what to do with the memory mapped
* to the given @p file. This affects a specific range of memory and may not
* be honored if the system chooses to ignore the request.
*
* @since 1.8
*/
EAPI void
@ -686,20 +672,19 @@ eina_file_map_populate(Eina_File *file, Eina_File_Populate rule, const void *map
/**
* @brief Maps line by line in the memory efficiently using an #Eina_Iterator.
*
* @param[in] file The file to run over
* @return An Eina_Iterator that produces #Eina_File_Line
*
* @details This function returns an iterator that acts like fgets without
* useless memcpy. Be aware that once eina_iterator_next has been called,
* nothing can guarantee that the memory is still going to be mapped.
*
* @param[in] file The file to run over
* @return An Eina_Iterator that produces #Eina_File_Line
*
* @since 1.3
*/
EAPI Eina_Iterator *eina_file_map_lines(Eina_File *file);
/**
* @brief Tells whether there has been an IO error during the life of a mmaped file,
* @brief Tells whether there has been an IO error during the life of a mmaped file.
*
* @param[in] file The file handler to the mmaped file
* @param[in] map The memory map to check if an error occurred on it
@ -710,7 +695,9 @@ EAPI Eina_Iterator *eina_file_map_lines(Eina_File *file);
EAPI Eina_Bool eina_file_map_faulted(Eina_File *file, void *map);
/**
* @brief Join two paths of known length.
* @brief Joins two paths of known length.
* @details This function is similar to eina_str_join_len(), but the separator
* is '\' on Windows and '/' otherwise.
*
* @param dst The buffer to store the result.
* @param size Size (in byte) of the buffer.
@ -720,9 +707,6 @@ EAPI Eina_Bool eina_file_map_faulted(Eina_File *file, void *map);
* @param b_len length of @p b.
* @return The number of characters printed.
*
* This function is similar to eina_str_join_len(), but the separator
* is '\' on Windows and '/' otherwise.
*
* @see eina_str_join_len()
* @see eina_file_path_join()
*
@ -736,7 +720,10 @@ static inline size_t eina_file_path_join_len(char *dst,
size_t b_len);
/**
* @brief Join two paths of known length.
* @brief Joins two paths of known length.
* @details This function is similar to eina_file_path_join_len(), but will compute
* the length of @p a and @p b using strlen(). The path separator is
* '\' on Windows and '/' otherwise.
*
* @param dst The buffer to store the result.
* @param size Size (in byte) of the buffer.
@ -744,10 +731,6 @@ static inline size_t eina_file_path_join_len(char *dst,
* @param b Second string to use.
* @return The number of characters printed.
*
* This function is similar to eina_file_path_join_len(), but will compute
* the length of @p a and @p b using strlen(). The path separator is
* '\' on Windows and '/' otherwise.
*
* @see eina_file_path_join_len()
*
* @since 1.16
@ -759,14 +742,13 @@ static inline size_t eina_file_path_join(char *dst,
/**
* @brief Unlink file
* @brief Unlinks file.
* @details This function is a wrapper around the unlink() system call. It removes a link to
* a file.
*
* @param pathname File name to unlink.
* @return #EINA_TRUE if the unlink was successfull, #EINA_FALSE otherwise..
*
* This function is a wrapper around the unlink() system call. It removes a link to
* a file.
*
* @since 1.19
*/
EAPI Eina_Bool eina_file_unlink(const char *pathname);

72
src/lib/eina/eina_fp.h
View File

@ -76,7 +76,7 @@ typedef int32_t Eina_F16p16;
typedef int32_t Eina_F8p24;
/**
* @brief Create a new Eina_F32p32 floating point number from standard 32-bit
* @brief Creates a new Eina_F32p32 floating point number from standard 32-bit
* integer
*
* @param v 32-bit integer value to convert
@ -85,7 +85,7 @@ typedef int32_t Eina_F8p24;
static inline Eina_F32p32 eina_f32p32_int_from(int32_t v);
/**
* @brief Create a new standard 32-bit integer from Eina_F32p32 floating point
* @brief Creates a new standard 32-bit integer from Eina_F32p32 floating point
* number
*
* @param v Eina_F32p32 value to convert
@ -94,15 +94,15 @@ static inline Eina_F32p32 eina_f32p32_int_from(int32_t v);
static inline int32_t eina_f32p32_int_to(Eina_F32p32 v);
/**
* @brief Create a new Eina_F32p32 floating point number from standard double
* @brief Creates a new Eina_F32p32 floating point number from standard double
*
* @param v double value to convert
* @param v Double value to convert
* @return The value converted into Eina_F32p32 format
*/
static inline Eina_F32p32 eina_f32p32_double_from(double v);
/**
* @brief Create a new standard double from Eina_F32p32 floating point
* @brief Creates a new standard double from Eina_F32p32 floating point
* number
*
* @param v Eina_F32p32 value to convert
@ -120,11 +120,11 @@ static inline double eina_f32p32_double_to(Eina_F32p32 v);
static inline Eina_F32p32 eina_f32p32_add(Eina_F32p32 a, Eina_F32p32 b);
/**
* @brief Calculates the substraction of two Eina_F32p32 floating point numbers
* @brief Calculates the subtraction of two Eina_F32p32 floating point numbers
*
* @param a The first number
* @param b The substracted number
* @return The substaction result of the two numbers @p a - @p b
* @param b The subtracted number
* @return The subtraction result of the two numbers @p a - @p b
*/
static inline Eina_F32p32 eina_f32p32_sub(Eina_F32p32 a, Eina_F32p32 b);
@ -133,7 +133,7 @@ static inline Eina_F32p32 eina_f32p32_sub(Eina_F32p32 a, Eina_F32p32 b);
*
* @param a The first number
* @param b The second number
* @return The mutliplication result of the two numbers @p a * @p b
* @return The multiplication result of the two numbers @p a * @p b
*
* To prevent overflow during multiplication we need to reduce the precision of
* the fraction part Shift both values to only contain 16 bit of the fraction
@ -148,7 +148,7 @@ static inline Eina_F32p32 eina_f32p32_mul(Eina_F32p32 a, Eina_F32p32 b);
*
* @param a The Eina_F32p32 number
* @param b The integer value
* @return The mutliplication result of the two numbers @p a * @p b
* @return The multiplication result of the two numbers @p a * @p b
*/
static inline Eina_F32p32 eina_f32p32_scale(Eina_F32p32 a, int b);
@ -170,7 +170,7 @@ static inline Eina_F32p32 eina_f32p32_div(Eina_F32p32 a, Eina_F32p32 b);
static inline Eina_F32p32 eina_f32p32_sqrt(Eina_F32p32 a);
/**
* @brief Get the absolute value of the integer part of and Eina_F32p32 floating
* @brief Gets the absolute value of the integer part of and Eina_F32p32 floating
* point number
*
* @param v The floating point number
@ -179,7 +179,7 @@ static inline Eina_F32p32 eina_f32p32_sqrt(Eina_F32p32 a);
static inline unsigned int eina_f32p32_fracc_get(Eina_F32p32 v);
/**
* @brief Get the absolute value of an Eina_F32p32 floating point number
* @brief Gets the absolute value of an Eina_F32p32 floating point number
*
* @param a The floating point number
* @return The absolute value for the number @p a
@ -220,7 +220,7 @@ EAPI Eina_F32p32 eina_f32p32_sin(Eina_F32p32 a);
#define EINA_F16P16_HALF (1 << 15)
/**
* @brief Create a new Eina_F16p316 floating point number from standard 32-bit
* @brief Creates a new Eina_F16p316 floating point number from standard 32-bit
* integer
*
* @param v 32-bit integer value to convert
@ -229,7 +229,7 @@ EAPI Eina_F32p32 eina_f32p32_sin(Eina_F32p32 a);
static inline Eina_F16p16 eina_f16p16_int_from(int32_t v);
/**
* @brief Create a new standard 32-bit integer from Eina_F16p16 floating point
* @brief Creates a new standard 32-bit integer from Eina_F16p16 floating point
* number
*
* @param v Eina_F16p16 value to convert
@ -238,15 +238,15 @@ static inline Eina_F16p16 eina_f16p16_int_from(int32_t v);
static inline int32_t eina_f16p16_int_to(Eina_F16p16 v);
/**
* @brief Create a new Eina_F16p16 floating point number from standard double
* @brief Creates a new Eina_F16p16 floating point number from standard double
*
* @param v double value to convert
* @param v Double value to convert
* @return The value converted into Eina_F16p16 format
*/
static inline Eina_F16p16 eina_f16p16_double_from(double v);
/**
* @brief Create a new standard double from Eina_F16p16 floating point
* @brief Creates a new standard double from Eina_F16p16 floating point
* number
*
* @param v Eina_F16p16 value to convert
@ -255,15 +255,15 @@ static inline Eina_F16p16 eina_f16p16_double_from(double v);
static inline double eina_f16p16_double_to(Eina_F16p16 v);
/**
* @brief Create a new Eina_F16p16 floating point number from standard float
* @brief Creates a new Eina_F16p16 floating point number from standard float
*
* @param v float value to convert
* @param v Float value to convert
* @return The value converted into Eina_F16p16 format
*/
static inline Eina_F16p16 eina_f16p16_float_from(float v);
/**
* @brief Create a new standard float from Eina_F16p16 floating point
* @brief Creates a new standard float from Eina_F16p16 floating point
* number
*
* @param v Eina_F16p16 value to convert
@ -281,11 +281,11 @@ static inline float eina_f16p16_float_to(Eina_F16p16 v);
static inline Eina_F16p16 eina_f16p16_add(Eina_F16p16 a, Eina_F16p16 b);
/**
* @brief Calculates the substraction of two Eina_F16p16 floating point numbers
* @brief Calculates the subtraction of two Eina_F16p16 floating point numbers
*
* @param a The first number
* @param b The substracted number
* @return The substaction result of the two numbers @p a - @p b
* @param b The subtracted number
* @return The subtraction result of the two numbers @p a - @p b
*/
static inline Eina_F16p16 eina_f16p16_sub(Eina_F16p16 a, Eina_F16p16 b);
@ -294,7 +294,7 @@ static inline Eina_F16p16 eina_f16p16_sub(Eina_F16p16 a, Eina_F16p16 b);
*
* @param a The first number
* @param b The second number
* @return The mutliplication result of the two numbers @p a * @p b
* @return The multiplication result of the two numbers @p a * @p b
*/
static inline Eina_F16p16 eina_f16p16_mul(Eina_F16p16 a, Eina_F16p16 b);
@ -304,7 +304,7 @@ static inline Eina_F16p16 eina_f16p16_mul(Eina_F16p16 a, Eina_F16p16 b);
*
* @param a The Eina_F16p16 number
* @param b The integer value
* @return The mutliplication result of the two numbers @p a * @p b
* @return The multiplication result of the two numbers @p a * @p b
*/
static inline Eina_F16p16 eina_f16p16_scale(Eina_F16p16 a, int b);
@ -326,7 +326,7 @@ static inline Eina_F16p16 eina_f16p16_div(Eina_F16p16 a, Eina_F16p16 b);
static inline Eina_F16p16 eina_f16p16_sqrt(Eina_F16p16 a);
/**
* @brief Get the absolute value of the integer part of and Eina_F16p16 floating
* @brief Gets the absolute value of the integer part of and Eina_F16p16 floating
* point number
*
* @param v The floating point number
@ -336,7 +336,7 @@ static inline unsigned int eina_f16p16_fracc_get(Eina_F16p16 v);
/**
* @brief Create a new Eina_F16p316 floating point number from standard 32-bit
* @brief Creates a new Eina_F16p316 floating point number from standard 32-bit
* integer
*
* @param v 32-bit integer value to convert
@ -345,7 +345,7 @@ static inline unsigned int eina_f16p16_fracc_get(Eina_F16p16 v);
static inline Eina_F8p24 eina_f8p24_int_from(int32_t v);
/**
* @brief Create a new standard 32-bit integer from Eina_F8p24 floating point
* @brief Creates a new standard 32-bit integer from Eina_F8p24 floating point
* number
*
* @param v Eina_F8p24 value to convert
@ -354,9 +354,9 @@ static inline Eina_F8p24 eina_f8p24_int_from(int32_t v);
static inline int32_t eina_f8p24_int_to(Eina_F8p24 v);
/**
* @brief Create a new Eina_F8p24 floating point number from standard float
* @brief Creates a new Eina_F8p24 floating point number from standard float
*
* @param v float value to convert
* @param v Float value to convert
* @return The value converted into Eina_F8p24 format
*/
static inline Eina_F8p24 eina_f8p24_float_from(float v);
@ -379,11 +379,11 @@ static inline float eina_f8p24_float_to(Eina_F8p24 v);
static inline Eina_F8p24 eina_f8p24_add(Eina_F8p24 a, Eina_F8p24 b);
/**
* @brief Calculates the substraction of two Eina_F8p24 floating point numbers
* @brief Calculates the subtraction of two Eina_F8p24 floating point numbers
*
* @param a The first number
* @param b The substracted number
* @return The substaction result of the two numbers @p a - @p b
* @param b The subtracted number
* @return The subtraction result of the two numbers @p a - @p b
*/
static inline Eina_F8p24 eina_f8p24_sub(Eina_F8p24 a, Eina_F8p24 b);
@ -392,7 +392,7 @@ static inline Eina_F8p24 eina_f8p24_sub(Eina_F8p24 a, Eina_F8p24 b);
*
* @param a The first number
* @param b The second number
* @return The mutliplication result of the two numbers @p a * @p b
* @return The multiplication result of the two numbers @p a * @p b
*/
static inline Eina_F8p24 eina_f8p24_mul(Eina_F8p24 a, Eina_F8p24 b);
@ -402,7 +402,7 @@ static inline Eina_F8p24 eina_f8p24_mul(Eina_F8p24 a, Eina_F8p24 b);
*
* @param a The Eina_F16p16 number
* @param b The integer value
* @return The mutliplication result of the two numbers @p a * @p b
* @return The multiplication result of the two numbers @p a * @p b
*/
static inline Eina_F8p24 eina_f8p24_scale(Eina_F8p24 a, int b);
@ -424,7 +424,7 @@ static inline Eina_F8p24 eina_f8p24_div(Eina_F8p24 a, Eina_F8p24 b);
static inline Eina_F8p24 eina_f8p24_sqrt(Eina_F8p24 a);
/**
* @brief Get the absolute value of the integer part of and Eina_F8p24 floating
* @brief Gets the absolute value of the integer part of and Eina_F8p24 floating
* point number
*
* @param v The floating point number

2
src/lib/eina/eina_hamster.h
View File

@ -39,7 +39,7 @@
/**
* @brief Get the hamster count.
* @brief Gets the hamster count.
*
* @return The number of available hamsters.
*

84
src/lib/eina/eina_hash.h
View File

@ -77,7 +77,7 @@
* @until printf("\n");
*
* There are different ways of iterate over the entries of a hash. Here we show
* two of them: using @ref eina_hash_foreach and @ref Eina_Iterator .
* two of them: using @ref eina_hash_foreach and @ref Eina_Iterator.
*
* @skip List of phones
* @until eina_iterator_free(it);
@ -346,7 +346,7 @@ typedef Eina_Bool (*Eina_Hash_Foreach)(const Eina_Hash *hash, const void *key
/**
* @brief Create a new hash table.
* @brief Creates a new hash table.
*
* @param key_length_cb The function called when getting the size of the key.
* @param key_cmp_cb The function called when comparing the keys.
@ -381,7 +381,7 @@ EAPI Eina_Hash *eina_hash_new(Eina_Key_Length key_length_cb,
int buckets_power_size) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(2, 3);
/**
* @brief Redefine the callback that clean the data of a hash
* @brief Redefines the callback that clean the data of a hash.
*
* @param hash The given hash table
* @param data_free_cb The function called on each value when the hash
@ -397,7 +397,7 @@ EAPI Eina_Hash *eina_hash_new(Eina_Key_Length key_length_cb,
EAPI void eina_hash_free_cb_set(Eina_Hash *hash, Eina_Free_Cb data_free_cb) EINA_ARG_NONNULL(1);
/**
* @brief Create a new hash table using the djb2 algorithm.
* @brief Creates a new hash table using the djb2 algorithm.
*
* @param data_free_cb The function called on each value when the hash table
* is freed, or when an item is deleted from it. @c NULL can be passed as
@ -412,7 +412,7 @@ EAPI void eina_hash_free_cb_set(Eina_Hash *hash, Eina_Free_Cb data_free_cb) EINA
EAPI Eina_Hash *eina_hash_string_djb2_new(Eina_Free_Cb data_free_cb);
/**
* @brief Create a new hash table for use with strings.
* @brief Creates a new hash table for use with strings.
*
* @param data_free_cb The function called on each value when the hash table
* is freed, or when an item is deleted from it. @c NULL can be passed as
@ -431,7 +431,7 @@ EAPI Eina_Hash *eina_hash_string_djb2_new(Eina_Free_Cb data_free_cb);
EAPI Eina_Hash *eina_hash_string_superfast_new(Eina_Free_Cb data_free_cb);
/**
* @brief Create a new hash table for use with strings with small bucket size.
* @brief Creates a new hash table for use with strings with small bucket size.
*
* @param data_free_cb The function called on each value when the hash table
* is freed, or when an item is deleted from it. @c NULL can be passed as
@ -449,7 +449,7 @@ EAPI Eina_Hash *eina_hash_string_superfast_new(Eina_Free_Cb data_free_cb);
EAPI Eina_Hash *eina_hash_string_small_new(Eina_Free_Cb data_free_cb);
/**
* @brief Create a new hash table for use with 32bit integers.
* @brief Creates a new hash table for use with 32bit integers.
*
* @param data_free_cb The function called on each value when the hash table
* is freed, or when an item is deleted from it. @c NULL can be passed as
@ -468,7 +468,7 @@ EAPI Eina_Hash *eina_hash_string_small_new(Eina_Free_Cb data_free_cb);
EAPI Eina_Hash *eina_hash_int32_new(Eina_Free_Cb data_free_cb);
/**
* @brief Create a new hash table for use with 64bit integers.
* @brief Creates a new hash table for use with 64bit integers.
*
* @param data_free_cb The function called on each value when the hash table
* is freed, or when an item is deleted from it. @c NULL can be passed as
@ -486,7 +486,7 @@ EAPI Eina_Hash *eina_hash_int32_new(Eina_Free_Cb data_free_cb);
EAPI Eina_Hash *eina_hash_int64_new(Eina_Free_Cb data_free_cb);
/**
* @brief Create a new hash table for use with pointers.
* @brief Creates a new hash table for use with pointers.
*
* @param data_free_cb The function called on each value when the hash table
* is freed, or when an item is deleted from it. @c NULL can be passed as
@ -512,7 +512,7 @@ EAPI Eina_Hash *eina_hash_int64_new(Eina_Free_Cb data_free_cb);
EAPI Eina_Hash *eina_hash_pointer_new(Eina_Free_Cb data_free_cb);
/**
* @brief Create a new hash table optimized for stringshared values.
* @brief Creates a new hash table optimized for stringshared values.
*
* @param data_free_cb The function called on each value when the hash table
* is freed, or when an item is deleted from it. @c NULL can be passed as
@ -538,7 +538,7 @@ EAPI Eina_Hash *eina_hash_pointer_new(Eina_Free_Cb data_free_cb);
EAPI Eina_Hash *eina_hash_stringshared_new(Eina_Free_Cb data_free_cb);
/**
* @brief Add an entry to the given hash table.
* @brief Adds an entry to the given hash table.
*
* @param hash The given hash table. Cannot be @c NULL.
* @param key A unique key. Cannot be @c NULL.
@ -563,7 +563,7 @@ EAPI Eina_Bool eina_hash_add(Eina_Hash *hash,
const void *data) EINA_ARG_NONNULL(1, 2, 3);
/**
* @brief Add an entry to the given hash table without duplicating the string
* @brief Adds an entry to the given hash table without duplicating the string.
* key.
*
* @param hash The given hash table. Cannot be @c NULL.
@ -591,7 +591,7 @@ EAPI Eina_Bool eina_hash_direct_add(Eina_Hash *hash,
const void *data) EINA_ARG_NONNULL(1, 2, 3);
/**
* @brief Remove the entry identified by a key or a data from the given
* @brief Removes the entry identified by a key or a data from the given
* hash table.
*
* @param hash The given hash table.
@ -618,7 +618,7 @@ EAPI Eina_Bool eina_hash_del(Eina_Hash *hash,
const void *data) EINA_ARG_NONNULL(1);
/**
* @brief Retrieve a specific entry in the given hash table.
* @brief Retrieves a specific entry in the given hash table.
*
* @param hash The given hash table.
* @param key The key of the entry to find.
@ -634,7 +634,7 @@ EAPI void *eina_hash_find(const Eina_Hash *hash,
const void *key) EINA_ARG_NONNULL(2);
/**
* @brief Modify the entry pointer at the specified key and return the old
* @brief Modifies the entry pointer at the specified key and return the old
* entry.
* @param hash The given hash table.
* @param key The key of the entry to modify.
@ -651,7 +651,7 @@ EAPI void *eina_hash_modify(Eina_Hash *hash,
const void *data) EINA_ARG_NONNULL(1, 2, 3);
/**
* @brief Modify the entry pointer at the specified key and return the
* @brief Modifies the entry pointer at the specified key and return the
* old entry or add the entry if not found.
*
* @param hash The given hash table.
@ -670,7 +670,7 @@ EAPI void *eina_hash_set(Eina_Hash *hash,
const void *data) EINA_ARG_NONNULL(1, 2);
/**
* @brief Change the key associated with a data without triggering the
* @brief Changes the key associated with a data without triggering the
* free callback.
*
* @param hash The given hash table.
@ -687,7 +687,7 @@ EAPI Eina_Bool eina_hash_move(Eina_Hash *hash,
const void *new_key) EINA_ARG_NONNULL(1, 2, 3);
/**
* Free the given hash table resources.
* @brief Frees the given hash table resources.
*
* @param hash The hash table to be freed.
*
@ -711,7 +711,7 @@ EAPI Eina_Bool eina_hash_move(Eina_Hash *hash,
EAPI void eina_hash_free(Eina_Hash *hash) EINA_ARG_NONNULL(1);
/**
* Free the given hash table buckets resources.
* @brief Frees the given hash table buckets resources.
*
* @param hash The hash table whose buckets have to be freed.
*
@ -736,7 +736,7 @@ EAPI void eina_hash_free_buckets(Eina_Hash *hash) EINA_ARG_NONNULL(1);
EAPI int eina_hash_population(const Eina_Hash *hash) EINA_ARG_NONNULL(1);
/**
* @brief Add an entry to the given hash table.
* @brief Adds an entry to the given hash table.
*
* @param hash The given hash table. Cannot be @c NULL.
* @param key A unique key. Cannot be @c NULL.
@ -766,7 +766,7 @@ EAPI Eina_Bool eina_hash_add_by_hash(Eina_Hash *hash,
const void *data) EINA_ARG_NONNULL(1, 2, 5);
/**
* @brief Add an entry to the given hash table and do not duplicate the string
* @brief Adds an entry to the given hash table and do not duplicate the string
* key.
*
* @param hash The given hash table. Cannot be @c NULL.
@ -800,7 +800,7 @@ EAPI Eina_Bool eina_hash_direct_add_by_hash(Eina_Hash *hash,
const void *data) EINA_ARG_NONNULL(1, 2, 5);
/**
* @brief Remove the entry identified by a key and a key hash from the given
* @brief Removes the entry identified by a key and a key hash from the given
* hash table.
*
* @param hash The given hash table. Cannot be @c NULL.
@ -817,8 +817,8 @@ EAPI Eina_Bool eina_hash_direct_add_by_hash(Eina_Hash *hash,
* functions returns immediately #EINA_FALSE. This function
* returns #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
*
* @note if you don't have the key_hash, use eina_hash_del_by_key() instead.
* @note if you don't have the key, use eina_hash_del_by_data() instead.
* @note If you don't have the key_hash, use eina_hash_del_by_key() instead.
* @note If you don't have the key, use eina_hash_del_by_data() instead.
*/
EAPI Eina_Bool eina_hash_del_by_key_hash(Eina_Hash *hash,
const void *key,
@ -826,7 +826,7 @@ EAPI Eina_Bool eina_hash_del_by_key_hash(Eina_Hash *hash,
int key_hash) EINA_ARG_NONNULL(1, 2);
/**
* @brief Remove the entry identified by a key from the given hash table.
* @brief Removes the entry identified by a key from the given hash table.
*
* This version will calculate key length and hash by using functions
* provided to hash creation function.
@ -837,21 +837,21 @@ EAPI Eina_Bool eina_hash_del_by_key_hash(Eina_Hash *hash,
*
* This function removes the entry identified by @p key from @p
* hash. The key length and hash will be calculated automatically by
* using functiond provided to has creation function. If a free
* using function provided to has creation function. If a free
* function was given to the callback on creation, it will be called
* for the data being deleted. If @p hash or @p key are @c NULL, the
* functions returns immediately #EINA_FALSE. This function
* returns #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
*
* @note if you already have the key_hash, use eina_hash_del_by_key_hash()
* @note If you already have the key_hash, use eina_hash_del_by_key_hash()
* instead.
* @note if you don't have the key, use eina_hash_del_by_data() instead.
* @note If you don't have the key, use eina_hash_del_by_data() instead.
*/
EAPI Eina_Bool eina_hash_del_by_key(Eina_Hash *hash,
const void *key) EINA_ARG_NONNULL(1, 2);
/**
* @brief Remove the entry identified by a data from the given hash table.
* @brief Removes the entry identified by a data from the given hash table.
*
* This version is slow since there is no quick access to nodes based on data.
*
@ -867,14 +867,14 @@ EAPI Eina_Bool eina_hash_del_by_key(Eina_Hash *hash,
* function returns #EINA_FALSE if an error occurred, #EINA_TRUE
* otherwise.
*
* @note if you already have the key, use eina_hash_del_by_key() or
* @note If you already have the key, use eina_hash_del_by_key() or
* eina_hash_del_by_key_hash() instead.
*/
EAPI Eina_Bool eina_hash_del_by_data(Eina_Hash *hash,
const void *data) EINA_ARG_NONNULL(1, 2);
/**
* @brief Remove the entry identified by a key and a key hash or a
* @brief Removes the entry identified by a key and a key hash or a
* data from the given hash table.
*
* If @p key is @c NULL, then @p data is used to find a match to
@ -898,8 +898,8 @@ EAPI Eina_Bool eina_hash_del_by_data(Eina_Hash *hash,
* string when setting the value of @p key_length. This function
* returns #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
*
* @note if you know you already have the key, use eina_hash_del_by_key_hash(),
* if you know you don't have the key, use eina_hash_del_by_data()
* @note If you know you already have the key, use eina_hash_del_by_key_hash(),
* If you know you don't have the key, use eina_hash_del_by_data()
* directly.
*/
EAPI Eina_Bool eina_hash_del_by_hash(Eina_Hash *hash,
@ -909,7 +909,7 @@ EAPI Eina_Bool eina_hash_del_by_hash(Eina_Hash *hash,
const void *data) EINA_ARG_NONNULL(1);
/**
* @brief Retrieve a specific entry in the given hash table.
* @brief Retrieves a specific entry in the given hash table.
*
* @param hash The given hash table. Cannot be @c NULL.
* @param key The key of the entry to find.
@ -931,7 +931,7 @@ EAPI void *eina_hash_find_by_hash(const Eina_Hash *hash,
int key_hash) EINA_ARG_NONNULL(1, 2);
/**
* @brief Modify the entry pointer at the specified key and returns
* @brief Modifies the entry pointer at the specified key and returns
* the old entry.
*
* @param hash The given hash table.
@ -952,7 +952,7 @@ EAPI void *eina_hash_modify_by_hash(Eina_Hash *hash,
const void *data) EINA_ARG_NONNULL(1, 2, 5);
/**
* @brief Returned a new iterator associated to hash keys.
* @brief Returns a new iterator associated to hash keys.
*
* @param hash The hash.
* @return A new iterator.
@ -972,7 +972,7 @@ EAPI void *eina_hash_modify_by_hash(Eina_Hash *hash,
EAPI Eina_Iterator *eina_hash_iterator_key_new(const Eina_Hash *hash) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
/**
* @brief Returned a new iterator associated to hash data.
* @brief Returns a new iterator associated to hash data.
*
* @param hash The hash.
* @return A new iterator.
@ -1005,7 +1005,7 @@ EAPI Eina_Iterator *eina_hash_iterator_data_new(const Eina_Hash *hash) EINA_MALL
* If the memory can not be allocated, @c NULL is returned.
* Otherwise, a valid iterator is returned.
*
* @note iterator data will provide values as Eina_Hash_Tuple that should not
* @note Iterator data will provide values as Eina_Hash_Tuple that should not
* be modified!
*
* @warning if the hash structure changes then the iterator becomes
@ -1015,7 +1015,7 @@ EAPI Eina_Iterator *eina_hash_iterator_data_new(const Eina_Hash *hash) EINA_MALL
EAPI Eina_Iterator *eina_hash_iterator_tuple_new(const Eina_Hash *hash) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
/**
* @brief Call a function on every member stored in the hash table
* @brief Calls a function on every member stored in the hash table.
*
* @param hash The hash table whose members will be walked
* @param func The function to call on each parameter
@ -1055,7 +1055,7 @@ EAPI void eina_hash_foreach(const Eina_Hash *hash,
/**
* @brief Append data to an #Eina_List inside a hash
* @brief Appends data to an #Eina_List inside a hash.
*
* This function is identical to the sequence of calling
* eina_hash_find(), eina_list_append(), eina_hash_set(),
@ -1067,7 +1067,7 @@ EAPI void eina_hash_foreach(const Eina_Hash *hash,
*/
EAPI void eina_hash_list_append(Eina_Hash *hash, const void *key, const void *data) EINA_ARG_NONNULL(1, 2, 3);
/**
* @brief Prepend data to an #Eina_List inside a hash
* @brief Prepends data to an #Eina_List inside a hash.
*
* This function is identical to the sequence of calling
* eina_hash_find(), eina_list_prepend(), eina_hash_set(),
@ -1079,7 +1079,7 @@ EAPI void eina_hash_list_append(Eina_Hash *hash, const void *key, const void *da
*/
EAPI void eina_hash_list_prepend(Eina_Hash *hash, const void *key, const void *data) EINA_ARG_NONNULL(1, 2, 3);
/**
* @brief Remove data from an #Eina_List inside a hash
* @brief Removes data from an #Eina_List inside a hash.
*
* This function is identical to the sequence of calling
* eina_hash_find(), eina_list_remove(), eina_hash_set(),

105
src/lib/eina/eina_inarray.h
View File

@ -166,7 +166,7 @@
*
* We then add element using eina_inarray_insert and print. Then remove that
* element and add again using eina_inarray_insert_sorted and prints. This
* shows the 2 different positions the elment gets added. Then searches an
* shows the 2 different positions the element gets added. Then searches an
* element in the unsorted array using eina_inarray_search, then sorts the
* array and then searches the same element using eina_inarray_search_sorted.
* @until }
@ -236,15 +236,14 @@ struct _Eina_Inarray
/**
* @brief Creates a new inline array.
* @details This creates a new array where members are inlined in a sequence. Each
* member has @a member_size bytes.
*
* @param[in] member_size The size of each member in the array
* @param[in] step The step size by which to resize the array, do this using the following
* extra amount
* @return The new inline array table, otherwise @c NULL on failure
*
* @details This creates a new array where members are inlined in a sequence. Each
* member has @a member_size bytes.
*
* @note If the @a step is @c 0, then a safe default is chosen.
*
* @note On failure, @c NULL is returned. If @p member_size is zero, then @c NULL is returned.
@ -269,6 +268,8 @@ EAPI void eina_inarray_free(Eina_Inarray *array) EINA_ARG_NONNULL(1);
/**
* @brief Initializes an inline array.
* @details This initializes an array. If the @p step is @c 0, then a safe default is
* chosen.
*
* @param[in] array The array object to initialize
* @param[in] sizeof_eina_inarray The size of array object
@ -276,9 +277,6 @@ EAPI void eina_inarray_free(Eina_Inarray *array) EINA_ARG_NONNULL(1);
* @param[in] step The step size by which to resize the array, do this using the following
* extra amount
*
* @details This initializes an array. If the @p step is @c 0, then a safe default is
* chosen.
*
* @note This is useful for arrays inlined into other structures or
* allocated to a stack.
*
@ -294,7 +292,6 @@ EAPI void eina_inarray_step_set(Eina_Inarray *array,
/**
* @brief Removes every member from the array.
*
*
* @param[in] array The array object
*
* @since 1.2
@ -303,15 +300,14 @@ EAPI void eina_inarray_flush(Eina_Inarray *array) EINA_ARG_NONNULL(1);
/**
* @brief Copies the data as the last member of the array.
* @details This copies the given pointer contents at the end of the array. The
* pointer is not referenced, instead its contents are copied to the
* members array using the previously defined @c member_size.
*
* @param[in] array The array object
* @param[in] data The data to be copied at the end
* @return The index of the new member, otherwise @c -1 on errors
*
* @details This copies the given pointer contents at the end of the array. The
* pointer is not referenced, instead its contents are copied to the
* members array using the previously defined @c member_size.
*
* @see eina_inarray_insert_at()
*
* @since 1.2
@ -320,7 +316,7 @@ EAPI int eina_inarray_push(Eina_Inarray *array,
const void *data) EINA_ARG_NONNULL(1, 2);
/**
* @brief Allocate new item at the end of the array.
* @brief Allocates new item at the end of the array.
*
* @param[in] array The array object
* @param[in] size The number of new item to allocate
@ -334,17 +330,16 @@ EAPI void *eina_inarray_grow(Eina_Inarray *array, unsigned int size);
/**
* @brief Copies the data to the array at a position found by the comparison function.
* @details This copies the given pointer contents at the array position defined by the
* given @a compare function. The pointer is not referenced, instead
* its contents are copied to the members array using the previously
* defined @c member_size.
*
* @param[in] array The array object
* @param[in] data The data to be copied
* @param[in] compare The compare function
* @return The index of the new member, otherwise @c -1 on errors
*
* @details This copies the given pointer contents at the array position defined by the
* given @a compare function. The pointer is not referenced, instead
* its contents are copied to the members array using the previously
* defined @c member_size.
*
* @note The data given to the @p compare function is a pointer to the member
* memory itself, do no change it.
*
@ -360,17 +355,16 @@ EAPI int eina_inarray_insert(Eina_Inarray *array,
/**
* @brief Copies the data to the array at a position found by the comparison function.
* @details This copies the given pointer contents at the array position defined by the
* given @p compare function. The pointer is not referenced, instead
* its contents are copied to the members array using the previously
* defined @p member_size.
*
* @param[in] array The array object
* @param[in] data The data to be copied
* @param[in] compare The compare function
* @return The index of the new member, otherwise @c -1 on errors
*
* @details This copies the given pointer contents at the array position defined by the
* given @p compare function. The pointer is not referenced, instead
* its contents are copied to the members array using the previously
* defined @p member_size.
*
* @note The data given to the @p compare function is a pointer to the member
* memory itself, do no change it.
*
@ -387,15 +381,14 @@ EAPI int eina_inarray_insert_sorted(Eina_Inarray *array,
/**
* @brief Finds data and removes the matching member.
* @details This finds data in the array and removes it. Data may be an existing
* member of the array (then optimized) or the contents are matched
* using memcmp().
*
* @param[in] array The array object
* @param[in] data The data to be found and removed
* @return The index of the removed member, otherwise @c -1 on errors
*
* @details This finds data in the array and removes it. Data may be an existing
* member of the array (then optimized) or the contents are matched
* using memcmp().
*
* @see eina_inarray_pop()
* @see eina_inarray_remove_at()
*
@ -418,16 +411,15 @@ EAPI void *eina_inarray_pop(Eina_Inarray *array) EINA_ARG_NONNULL(1);
/**
* @brief Gets the member at the given position.
*
* @param[in] array The array object
* @param[in] position The member position
* @return A pointer to current the member memory
*
* @details This gets the member given that its position in the array is provided. It is a pointer to
* its current memory, then it can be invalidated with functions that
* change the array such as eina_inarray_push(),
* eina_inarray_insert_at(), or eina_inarray_remove_at(), or variants.
*
* @param[in] array The array object
* @param[in] position The member position
* @return A pointer to current the member memory
*
* @see eina_inarray_lookup()
* @see eina_inarray_lookup_sorted()
*
@ -438,17 +430,16 @@ EAPI void *eina_inarray_nth(const Eina_Inarray *array,
/**
* @brief Copies the data at the given position in the array.
* @details This copies the given pointer contents at the given @p position in the
* array. The pointer is not referenced, instead its contents are
* copied to the members array using the previously defined
* @p member_size.
*
* @param[in] array The array object
* @param[in] position The position to insert the member at
* @param[in] data The data to be copied at the position
* @return #EINA_TRUE on success, otherwise #EINA_FALSE on failure
*
* @details This copies the given pointer contents at the given @p position in the
* array. The pointer is not referenced, instead its contents are
* copied to the members array using the previously defined
* @p member_size.
*
* @note All the members from @a position to the end of the array are
* shifted to the end.
*
@ -495,17 +486,16 @@ EAPI void *eina_inarray_alloc_at(Eina_Inarray *array,
/**
* @brief Copies the data to the given position.
* @details This copies the given pointer contents at the given @p position in the
* array. The pointer is not referenced, instead its contents are
* copied to the members array using the previously defined
* @p member_size.
*
* @param[in] array The array object
* @param[in] position The position to copy the member at
* @param[in] data The data to be copied at the position
* @return #EINA_TRUE on success, otherwise #EINA_FALSE on failure
*
* @details This copies the given pointer contents at the given @p position in the
* array. The pointer is not referenced, instead its contents are
* copied to the members array using the previously defined
* @p member_size.
*
* @note If @p position does not exist, it fails.
*
* @since 1.2
@ -548,12 +538,11 @@ EAPI void eina_inarray_reverse(Eina_Inarray *array) EINA_ARG_NONNULL(1);
/**
* @brief Applies a quick sort to the array.
* @details This applies a quick sort to the @a array.
*
* @param[in] array The array object
* @param[in] compare The compare function
*
* @details This applies a quick sort to the @a array.
*
* @note The data given to the @a compare function is a pointer to the member
* memory itself, do no change it.
*
@ -566,15 +555,14 @@ EAPI void eina_inarray_sort(Eina_Inarray *array,
/**
* @brief Searches for a member (linear walk).
* @details This walks through an array by linearly looking for the given data compared by
* the @p compare function.
*
* @param[in] array The array object
* @param[in] data The member to search using the @p compare function
* @param[in] compare The compare function
* @return The member index, otherwise @c -1 if not found
*
* @details This walks through an array by linearly looking for the given data compared by
* the @p compare function.
*
* @note The data given to the @p compare function is a pointer to the member
* memory itself, do no change it.
*
@ -607,14 +595,13 @@ EAPI int eina_inarray_search_sorted(const Eina_Inarray *array,
/**
* @brief Calls @p function for each array member.
* @details This calls @p function for every given data in @p array.
*
* @param[in] array The array object
* @param[in] function The callback function
* @param[in] user_data The user data given to a callback @a function
* @return #EINA_TRUE if it successfully iterates all the items of the array
*
* @details This calls @p function for every given data in @p array.
*
* @note This is a safe way to iterate over an array. @p function should return #EINA_TRUE
* as long as you want the function to continue iterating, by
* returning #EINA_FALSE it stops and returns #EINA_FALSE as the result.
@ -631,15 +618,14 @@ EAPI Eina_Bool eina_inarray_foreach(const Eina_Inarray *array,
/**
* @brief Removes all the members that match.
* @details This removes all the entries in @p array, where the @p match function
* returns #EINA_TRUE.
*
* @param[in] array The array object
* @param[in] match The match function
* @param[in] user_data The user data given to callback @p match
* @return The number of removed entries, otherwise @c -1 on error
*
* @details This removes all the entries in @p array, where the @p match function
* returns #EINA_TRUE.
*
* @since 1.2
*/
EAPI int eina_inarray_foreach_remove(Eina_Inarray *array,
@ -669,13 +655,12 @@ EAPI unsigned int eina_inarray_count(const Eina_Inarray *array) EINA_ARG_NONNULL
/**
* @brief Returns a new iterator associated to an array.
* @details This function returns a newly allocated iterator associated to
* @p array.
*
* @param[in] array The array object
* @return A new iterator
*
* @details This function returns a newly allocated iterator associated to
* @p array.
*
* @note If the memory cannot be allocated, @c NULL is returned.
* Otherwise, a valid iterator is returned.
*
@ -689,13 +674,12 @@ EAPI Eina_Iterator *eina_inarray_iterator_new(const Eina_Inarray *array) EINA_MA
/**
* @brief Returns a new reversed iterator associated to an array.
* @details This function returns a newly allocated iterator associated to
* @p array.
*
* @param[in] array The array object
* @return A new iterator
*
* @details This function returns a newly allocated iterator associated to
* @p array.
*
* @note Unlike eina_inarray_iterator_new(), this walks through the array backwards.
*
* @note If the memory cannot be allocated, @c NULL is returned.
@ -711,13 +695,12 @@ EAPI Eina_Iterator *eina_inarray_iterator_reversed_new(const Eina_Inarray *array
/**
* @brief Returns a new accessor associated to an array.
* @details This function returns a newly allocated accessor associated to
* @p array.
*
* @param[in] array The array object
* @return A new accessor
*
* @details This function returns a newly allocated accessor associated to
* @p array.
*
* @note If the memory cannot be allocated, @c NULL is returned
* Otherwise, a valid accessor is returned.
*

102
src/lib/eina/eina_inlist.h
View File

@ -420,9 +420,9 @@ struct _Eina_Inlist
/**
* Add a new node to end of a list.
* @brief Adds a new node to end of a list.
*
* @note this code is meant to be fast: appends are O(1) and do not
* @note This code is meant to be fast: appends are O(1) and do not
* walk @a in_list.
*
* @note @a in_item is considered to be in no list. If it was in another
@ -430,18 +430,18 @@ struct _Eina_Inlist
* check of @a new_l prev and next pointers is done, so it's safe
* to have them uninitialized.
*
* @param in_list existing list head or @c NULL to create a new list.
* @param in_item new list node, must not be @c NULL.
* @param in_list Existing list head or @c NULL to create a new list.
* @param in_item New list node, must not be @c NULL.
*
* @return the new list head. Use it and not @a in_list anymore.
* @return The new list head. Use it and not @a in_list anymore.
*/
EAPI Eina_Inlist *eina_inlist_append(Eina_Inlist *in_list,
Eina_Inlist *in_item) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
/**
* Add a new node to beginning of list.
* @brief Adds a new node to beginning of list.
*
* @note this code is meant to be fast: appends are O(1) and do not
* @note This code is meant to be fast: appends are O(1) and do not
* walk @a in_list.
*
* @note @a new_l is considered to be in no list. If it was in another
@ -449,18 +449,18 @@ EAPI Eina_Inlist *eina_inlist_append(Eina_Inlist *in_list,
* check of @a new_l prev and next pointers is done, so it's safe
* to have them uninitialized.
*
* @param in_list existing list head or @c NULL to create a new list.
* @param in_item new list node, must not be @c NULL.
* @param in_list Existing list head or @c NULL to create a new list.
* @param in_item New list node, must not be @c NULL.
*
* @return the new list head. Use it and not @a in_list anymore.
* @return The new list head. Use it and not @a in_list anymore.
*/
EAPI Eina_Inlist *eina_inlist_prepend(Eina_Inlist *in_list,
Eina_Inlist *in_item) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
/**
* Add a new node after the given relative item in list.
* @brief Adds a new node after the given relative item in list.
*
* @note this code is meant to be fast: appends are O(1) and do not
* @note This code is meant to be fast: appends are O(1) and do not
* walk @a in_list.
*
* @note @a in_item_l is considered to be in no list. If it was in another
@ -473,20 +473,20 @@ EAPI Eina_Inlist *eina_inlist_prepend(Eina_Inlist *in_list,
* will lead to problems. Giving NULL @a in_relative is the same as
* eina_list_append().
*
* @param in_list existing list head or @c NULL to create a new list.
* @param in_item new list node, must not be @c NULL.
* @param in_relative reference node, @a in_item will be added after it.
* @param in_list Existing list head or @c NULL to create a new list.
* @param in_item New list node, must not be @c NULL.
* @param in_relative Reference node, @a in_item will be added after it.
*
* @return the new list head. Use it and not @a list anymore.
* @return The new list head. Use it and not @a list anymore.
*/
EAPI Eina_Inlist *eina_inlist_append_relative(Eina_Inlist *in_list,
Eina_Inlist *in_item,
Eina_Inlist *in_relative) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
/**
* Add a new node before the given relative item in list.
* @brief Adds a new node before the given relative item in list.
*
* @note this code is meant to be fast: appends are O(1) and do not
* @note This code is meant to be fast: appends are O(1) and do not
* walk @a in_list.
*
* @note @a in_item is considered to be in no list. If it was in another
@ -499,20 +499,20 @@ EAPI Eina_Inlist *eina_inlist_append_relative(Eina_Inlist *in_list,
* will lead to problems. Giving NULL @a in_relative is the same as
* eina_list_prepend().
*
* @param in_list existing list head or @c NULL to create a new list.
* @param in_item new list node, must not be @c NULL.
* @param in_relative reference node, @a in_item will be added before it.
* @param in_list Existing list head or @c NULL to create a new list.
* @param in_item New list node, must not be @c NULL.
* @param in_relative Reference node, @a in_item will be added before it.
*
* @return the new list head. Use it and not @a in_list anymore.
* @return The new list head. Use it and not @a in_list anymore.
*/
EAPI Eina_Inlist *eina_inlist_prepend_relative(Eina_Inlist *in_list,
Eina_Inlist *in_item,
Eina_Inlist *in_relative) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
/**
* Remove node from list.
* @brief Removes node from list.
*
* @note this code is meant to be fast: appends are O(1) and do not
* @note This code is meant to be fast: appends are O(1) and do not
* walk @a list.
*
* @note @a in_item is considered to be inside @a in_list, no checks are
@ -521,22 +521,22 @@ EAPI Eina_Inlist *eina_inlist_prepend_relative(Eina_Inlist *in_list,
* it will be different from @a list and the wrong new head will
* be returned.
*
* @param in_list existing list head, must not be @c NULL.
* @param in_item existing list node, must not be @c NULL.
* @param in_list Existing list head, must not be @c NULL.
* @param in_item Existing list node, must not be @c NULL.
*
* @return the new list head. Use it and not @a list anymore.
* @return The new list head. Use it and not @a list anymore.
*/
EAPI Eina_Inlist *eina_inlist_remove(Eina_Inlist *in_list,
Eina_Inlist *in_item) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT;
/**
* Find given node in list, returns itself if found, NULL if not.
* @brief Finds given node in list, returns itself if found, NULL if not.
*
* @warning this is an expensive call and has O(n) cost, possibly
* @warning This is an expensive call and has O(n) cost, possibly
* walking the whole list.
*
* @param in_list existing list to search @a in_item in, must not be @c NULL.
* @param in_item what to search for, must not be @c NULL.
* @param in_list Existing list to search @a in_item in, must not be @c NULL.
* @param in_item What to search for, must not be @c NULL.
*
* @return @a in_item if found, @c NULL if not.
*/
@ -544,43 +544,43 @@ EAPI Eina_Inlist *eina_inlist_find(Eina_Inlist *in_list,
Eina_Inlist *in_item) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
/**
* Move existing node to beginning of list.
* @brief Moves existing node to beginning of list.
*
* @note this code is meant to be fast: appends are O(1) and do not
* @note This code is meant to be fast: appends are O(1) and do not
* walk @a list.
*
* @note @a item is considered to be inside @a list. No checks are
* done to confirm this, and giving nodes from different lists
* will lead to problems.
*
* @param list existing list head or @c NULL to create a new list.
* @param item list node to move to beginning (head), must not be @c NULL.
* @param list Existing list head or @c NULL to create a new list.
* @param item List node to move to beginning (head), must not be @c NULL.
*
* @return the new list head. Use it and not @a list anymore.
* @return The new list head. Use it and not @a list anymore.
*/
EAPI Eina_Inlist *eina_inlist_promote(Eina_Inlist *list,
Eina_Inlist *item) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT;
/**
* Move existing node to end of list.
* @brief Moves existing node to end of list.
*
* @note this code is meant to be fast: appends are O(1) and do not
* @note This code is meant to be fast: appends are O(1) and do not
* walk @a list.
*
* @note @a item is considered to be inside @a list. No checks are
* done to confirm this, and giving nodes from different lists
* will lead to problems.
*
* @param list existing list head or @c NULL to create a new list.
* @param item list node to move to end (tail), must not be @c NULL.
* @param list Existing list head or @c NULL to create a new list.
* @param item List node to move to end (tail), must not be @c NULL.
*
* @return the new list head. Use it and not @a list anymore.
* @return The new list head. Use it and not @a list anymore.
*/
EAPI Eina_Inlist *eina_inlist_demote(Eina_Inlist *list,
Eina_Inlist *item) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT;
/**
* @brief Get the first list node in the list.
* @brief Gets the first list node in the list.
*
* @param list The list to get the first list node from.
* @return The first list node in the list.
@ -596,7 +596,7 @@ EAPI Eina_Inlist *eina_inlist_demote(Eina_Inlist *list,
static inline Eina_Inlist *eina_inlist_first(const Eina_Inlist *list) EINA_PURE EINA_WARN_UNUSED_RESULT;
/**
* @brief Get the last list node in the list.
* @brief Gets the last list node in the list.
*
* @param list The list to get the last list node from.
* @return The last list node in the list.
@ -612,7 +612,7 @@ static inline Eina_Inlist *eina_inlist_first(const Eina_Inlist *list) EINA_PURE
static inline Eina_Inlist *eina_inlist_last(const Eina_Inlist *list) EINA_PURE EINA_WARN_UNUSED_RESULT;
/**
* @brief Get the count of the number of items in a list.
* @brief Gets the count of the number of items in a list.
*
* @param list The list whose count to return.
* @return The number of members in the list.
@ -663,10 +663,10 @@ EAPI Eina_Iterator *eina_inlist_iterator_new(const Eina_Inlist *in_list) EINA_MA
EAPI Eina_Accessor *eina_inlist_accessor_new(const Eina_Inlist *in_list) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
/**
* @brief Insert a new node into a sorted list.
* @brief Inserts a new node into a sorted list.
*
* @param list The given linked list, @b must be sorted.
* @param item list node to insert, must not be @c NULL.
* @param item List node to insert, must not be @c NULL.
* @param func The function called for the sort.
* @return A list pointer.
* @since 1.1.0
@ -686,7 +686,7 @@ EAPI Eina_Accessor *eina_inlist_accessor_new(const Eina_Inlist *in_list) EINA_MA
EAPI Eina_Inlist *eina_inlist_sorted_insert(Eina_Inlist *list, Eina_Inlist *item, Eina_Compare_Cb func) EINA_ARG_NONNULL(2, 3) EINA_WARN_UNUSED_RESULT;
/**
* @brief Create state with valid data in it.
* @brief Creates state with valid data in it.
*
* @return A valid Eina_Inlist_Sorted_State.
* @since 1.1.0
@ -696,7 +696,7 @@ EAPI Eina_Inlist *eina_inlist_sorted_insert(Eina_Inlist *list, Eina_Inlist *item
EAPI Eina_Inlist_Sorted_State *eina_inlist_sorted_state_new(void);
/**
* @brief Force an Eina_Inlist_Sorted_State to match the content of a list.
* @brief Forces an Eina_Inlist_Sorted_State to match the content of a list.
*
* @param state The state to update
* @param list The list to match
@ -710,7 +710,7 @@ EAPI Eina_Inlist_Sorted_State *eina_inlist_sorted_state_new(void);
EAPI int eina_inlist_sorted_state_init(Eina_Inlist_Sorted_State *state, Eina_Inlist *list);
/**
* @brief Free an Eina_Inlist_Sorted_State.
* @brief Frees an Eina_Inlist_Sorted_State.
*
* @param state The state to destroy
* @since 1.1.0
@ -720,7 +720,7 @@ EAPI int eina_inlist_sorted_state_init(Eina_Inlist_Sorted_State *state, Eina_Inl
EAPI void eina_inlist_sorted_state_free(Eina_Inlist_Sorted_State *state);
/**
* @brief Insert a new node into a sorted list.
* @brief Inserts a new node into a sorted list.
*
* @param list The given linked list, @b must be sorted.
* @param item list node to insert, must not be @c NULL.
@ -752,7 +752,7 @@ EAPI Eina_Inlist *eina_inlist_sorted_state_insert(Eina_Inlist *list,
Eina_Compare_Cb func,
Eina_Inlist_Sorted_State *state);
/**
* @brief Sort a list according to the ordering func will return.
* @brief Sorts a list according to the ordering func will return.
*
* @param head The list handle to sort.
* @param func A function pointer that can handle comparing the list data

18
src/lib/eina/eina_iterator.h
View File

@ -67,7 +67,7 @@
* also printed, so now we go to the cool stuff and use an iterator to do same
* stuff to a list:
* @until eina_iterator_free
* @note The only significant diference to the block above is in the
* @note The only significant difference to the block above is in the
* function used to create the iterator.
*
* And now we free the list and shut eina down:
@ -197,7 +197,7 @@ struct _Eina_Iterator
/**
* @brief Free an iterator.
* @brief Frees an iterator.
*
* @param iterator The iterator to free.
*
@ -207,7 +207,7 @@ EAPI void eina_iterator_free(Eina_Iterator *iterator);
/**
* @brief Return the container of an iterator.
* @brief Returns the container of an iterator.
*
* @param iterator The iterator.
* @return The container which created the iterator.
@ -218,7 +218,7 @@ EAPI void eina_iterator_free(Eina_Iterator *iterator);
EAPI void *eina_iterator_container_get(Eina_Iterator *iterator) EINA_ARG_NONNULL(1) EINA_PURE;
/**
* @brief Return the value of the current element and go to the next one.
* @brief Returns the value of the current element and go to the next one.
*
* @param iterator The iterator.
* @param data The data of the element.
@ -234,7 +234,7 @@ EAPI Eina_Bool eina_iterator_next(Eina_Iterator *iterator,
/**
* @brief Iterate over the container and execute a callback on each element.
* @brief Iterates over the container and execute a callback on each element.
*
* @param iterator The iterator.
* @param callback The callback called on each iteration.
@ -253,7 +253,7 @@ EAPI void eina_iterator_foreach(Eina_Iterator *iterator,
/**
* @brief Lock the container of the iterator.
* @brief Locks the container of the iterator.
*
* @param iterator The iterator.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
@ -269,7 +269,7 @@ EAPI void eina_iterator_foreach(Eina_Iterator *iterator,
EAPI Eina_Bool eina_iterator_lock(Eina_Iterator *iterator) EINA_ARG_NONNULL(1);
/**
* @brief Unlock the container of the iterator.
* @brief Unlocks the container of the iterator.
*
* @param iterator The iterator.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
@ -317,7 +317,7 @@ EAPI Eina_Iterator* eina_iterator_filter_new(Eina_Iterator *original, Eina_Each_
/**
* @def EINA_ITERATOR_FOREACH
* @brief Macro to iterate over all elements easily.
* @brief Definition for the macro to iterate over all elements easily.
*
* @param itr The iterator to use.
* @param data Where to store * data, must be a pointer support getting
@ -346,7 +346,7 @@ EAPI Eina_Iterator* eina_iterator_filter_new(Eina_Iterator *original, Eina_Each_
* eina_list_free(list);
* @endcode
*
* @note this example is not optimal algorithm to release a list since
* @note This example is not optimal algorithm to release a list since
* it will walk the list twice, but it serves as an example. For
* optimized version use EINA_LIST_FREE()
*

14
src/lib/eina/eina_lalloc.h
View File

@ -65,12 +65,12 @@ typedef void (*Eina_Lalloc_Free)(void *user_data);
typedef struct _Eina_Lalloc Eina_Lalloc;
/**
* @brief Create a new lazy allocator.
* @brief Creates 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.
* @param num_init The number of @p data items to initially allocate space for.
*
* @return A new lazy allocator.
*
@ -81,7 +81,7 @@ EAPI Eina_Lalloc *eina_lalloc_new(void *data,
int num_init) EINA_ARG_NONNULL(2, 3);
/**
* @brief Free the resources for a lazy allocator.
* @brief Frees the resources for a lazy allocator.
*
* @param a The lazy allocator to free.
*
@ -89,23 +89,23 @@ EAPI Eina_Lalloc *eina_lalloc_new(void *data,
EAPI void eina_lalloc_free(Eina_Lalloc *a) EINA_ARG_NONNULL(1);
/**
* @brief Add several elements to a lazy allocator.
* @brief Adds 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.
* @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.
* @brief Allocates 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.
* @return #EINA_TRUE on success, else #EINA_FALSE.
*
*/
EAPI Eina_Bool eina_lalloc_element_add(Eina_Lalloc *a) EINA_ARG_NONNULL(1);

112
src/lib/eina/eina_list.h
View File

@ -342,7 +342,7 @@ struct _Eina_List_Accounting
/**
* @brief Append the given data to the given linked list.
* @brief Appends the given data to the given linked list.
*
* @param list The given list.
* @param data The data to append.
@ -397,7 +397,7 @@ EAPI Eina_List *eina_list_prepend(Eina_List *list, const void *data)
/**
* @brief Insert the given data into the given linked list after the specified data.
* @brief Inserts the given data into the given linked list after the specified data.
*
* @param list The given linked list.
* @param data The data to insert.
@ -430,7 +430,7 @@ EAPI Eina_List *eina_list_append_relative(Eina_List *list, const void
/**
* @brief Append a list node to a linked list after the specified member
* @brief Appends a list node to a linked list after the specified member.
*
* @param list The given linked list.
* @param data The data to insert.
@ -452,7 +452,7 @@ EAPI Eina_List *eina_list_append_relative_list(Eina_List *list, const
/**
* @brief Prepend a data pointer to a linked list before the specified member
* @brief Prepends a data pointer to a linked list before the specified member.
*
* @param list The given linked list.
* @param data The data to insert.
@ -485,7 +485,7 @@ EAPI Eina_List *eina_list_prepend_relative(Eina_List *list, const voi
/**
* @brief Prepend a list node to a linked list before the specified member
* @brief Prepends a list node to a linked list before the specified member.
*
* @param list The given linked list.
* @param data The data to insert.
@ -507,7 +507,7 @@ EAPI Eina_List *eina_list_prepend_relative_list(Eina_List *list, cons
/**
* @brief Insert a new node into a sorted list.
* @brief Inserts a new node into a sorted list.
*
* @param list The given linked list, @b must be sorted.
* @param func The function called for the sort.
@ -533,7 +533,7 @@ EAPI Eina_List *eina_list_sorted_insert(Eina_List *list, Eina_Compare
/**
* @brief Remove the first instance of the specified data from the given list.
* @brief Removes the first instance of the specified data from the given list.
*
* @param list The given list.
* @param data The specified data.
@ -552,7 +552,7 @@ EAPI Eina_List *eina_list_remove(Eina_List *list, const void *data) E
/**
* @brief Remove the specified list node.
* @brief Removes the specified list node.
*
* @param list The given linked list.
* @param remove_list The list node which is to be removed.
@ -590,7 +590,7 @@ EAPI Eina_List *eina_list_remove_list(Eina_List *list, Eina_List *rem
/**
* @brief Move the specified data to the head of the list.
* @brief Moves the specified data to the head of the list.
*
* @param list The list handle to move the data.
* @param move_list The list node to move.
@ -624,7 +624,7 @@ EAPI Eina_List *eina_list_promote_list(Eina_List *list, Eina_List *mo
/**
* @brief Move the specified data to the tail of the list.
* @brief Moves the specified data to the tail of the list.
*
* @param list The list handle to move the data.
* @param move_list The list node to move.
@ -658,7 +658,7 @@ EAPI Eina_List *eina_list_demote_list(Eina_List *list, Eina_List *mov
/**
* @brief Find a member of a list and return the member.
* @brief Finds a member of a list and return the member.
*
* @param list The list to search for a data.
* @param data The data pointer to find in the list.
@ -684,7 +684,7 @@ EAPI Eina_List *eina_list_demote_list(Eina_List *list, Eina_List *mov
EAPI void *eina_list_data_find(const Eina_List *list, const void *data) EINA_PURE EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
/**
* @brief Find a member of a list and return the list node containing that member.
* @brief Finds a member of a list and return the list node containing that member.
*
* @param list The list to search for data.
* @param data The data pointer to find in the list.
@ -701,7 +701,7 @@ EAPI Eina_List *eina_list_data_find_list(const Eina_List *list, const
/**
* @brief Move a data pointer from one list to another
* @brief Moves a data pointer from one list to another.
*
* @param to The list to move the data to
* @param from The list to move from
@ -717,7 +717,7 @@ EAPI Eina_List *eina_list_data_find_list(const Eina_List *list, const
EAPI Eina_Bool eina_list_move(Eina_List **to, Eina_List **from, void *data);
/**
* @brief Move a list node from one list to another
* @brief Moves a list node from one list to another.
*
* @param to The list to move the data to
* @param from The list to move from
@ -734,7 +734,7 @@ EAPI Eina_Bool eina_list_move_list(Eina_List **to, Eina_List **from,
/**
* @brief Free an entire list and all the nodes, ignoring the data contained.
* @brief Frees an entire list and all the nodes, ignoring the data contained.
* @param list The list to free
* @return A @c NULL pointer
@ -746,7 +746,7 @@ EAPI Eina_List *eina_list_free(Eina_List *list);
/**
* @brief Get the nth member's data pointer in a list.
* @brief Gets the nth member's data pointer in a list.
*
* @param list The list to get the specified member number from.
* @param n The number of the element (0 being the first).
@ -765,9 +765,9 @@ EAPI void *eina_list_nth(const Eina_List *list, unsigned int n)
/**
* @brief Get the nth member's list node in a list.
* @brief Gets the nth member's list node in a list.
*
* @param list The list to get the specfied member number from.
* @param list The list to get the specified member number from.
* @param n The number of the element (0 being the first).
* @return The list node stored in the numbered element.
*
@ -786,14 +786,14 @@ EAPI Eina_List *eina_list_nth_list(const Eina_List *list, unsigned in
/**
* @brief Reverse all the elements in the list.
* @brief Reverses all the elements in the list.
*
* @param list The list to reverse.
* @return The list head after it has been reversed.
*
* This function reverses the order of all elements in @p list, so the
* last member is now first, and so on. If @p list is @c NULL, this
* functon returns @c NULL.
* function returns @c NULL.
*
* @note @b in-place: this will change the given list, so you should
* now point to the new list head that is returned by this function.
@ -807,14 +807,14 @@ EAPI Eina_List *eina_list_reverse(Eina_List *list) EINA_WARN_UNUSED_R
/**
* @brief Clone (copy) all the elements in the list in reverse order.
* @brief Clones (copies) all the elements in the list in reverse order.
*
* @param list The list to reverse.
* @return The new list that has been reversed.
*
* This function reverses the order of all elements in @p list, so the
* last member is now first, and so on. If @p list is @c NULL, this
* functon returns @c NULL. This returns a copy of the given list.
* function returns @c NULL. This returns a copy of the given list.
*
* @note @b copy: this will copy the list and you should then
* eina_list_free() when it is not required anymore.
@ -828,7 +828,7 @@ EAPI Eina_List *eina_list_reverse_clone(const Eina_List *list) EINA_W
/**
* @brief Clone (copy) all the elements in the list in exactly same order.
* @brief Clones (copies) all the elements in the list in exactly same order.
*
* @param list The list to clone.
* @return The new list that has been cloned.
@ -848,13 +848,13 @@ EAPI Eina_List *eina_list_clone(const Eina_List *list) EINA_WARN_UNUS
/**
* @brief Sort a list according to the ordering func will return.
* @brief Sorts a list according to the ordering func will return.
*
* @param list The list handle to sort.
* @param limit The maximum number of list elements to sort.
* @param func A function pointer that can handle comparing the list data
* nodes.
* @return the new head of list.
* @return The new head of list.
*
* This function sorts @p list. If @p limit is 0 or greater than the number of
* elements in @p list, all the elements are sorted. @p func is used to
@ -891,17 +891,17 @@ EAPI Eina_List *eina_list_sort(Eina_List *list, unsigned int limit, E
/**
* @brief Shuffle list.
* @brief Shuffles list.
*
* @param list The list handle to shuffle.
* @param func A function pointer that can return an int between 2 inclusive values
* @return the new head of list.
* @return The new head of list.
*
* This function shuffles @p list.
* @p func is used to generate random list indexes within the range of
* unshuffled list items. If @p func is @c NULL, rand is used.
*
* @note @b in-place: this will change the given list, so you should
* @note @b in-place: This will change the given list, so you should
* now point to the new list head that is returned by this function.
*
* @since 1.8
@ -912,7 +912,7 @@ EAPI Eina_List *eina_list_shuffle(Eina_List *list, Eina_Random_Cb fun
/**
* @brief Merge two list.
* @brief Merges two list.
*
* @param left Head list to merge.
* @param right Tail list to merge.
@ -922,7 +922,7 @@ EAPI Eina_List *eina_list_shuffle(Eina_List *list, Eina_Random_Cb fun
*
* Both left and right do not exist anymore after the merge.
*
* @note merge cost is O(n), being @b n the size of the smallest
* @note Merge cost is O(n), being @b n the size of the smallest
* list. This is due the need to fix accounting of that segment,
* making count and last access O(1).
*
@ -932,7 +932,7 @@ EAPI Eina_List *eina_list_merge(Eina_List *left, Eina_List *right) EI
/**
* @brief Merge two sorted list according to the ordering func will return.
* @brief Merges two sorted list according to the ordering func will return.
*
* @param left First list to merge.
* @param right Second list to merge.
@ -972,7 +972,7 @@ EAPI Eina_List *eina_list_sorted_merge(Eina_List *left, Eina_List *ri
/**
* @brief Split a list into 2 lists.
* @brief Splits a list into 2 lists.
*
* @param list List to split.
* @param relative The list will be split after @p relative.
@ -997,12 +997,12 @@ EAPI Eina_List *eina_list_split_list(Eina_List *list, Eina_List *rela
* @param list The list to search for data, @b must be sorted.
* @param func A function pointer that can handle comparing the list data nodes.
* @param data reference value to search.
* @param result_cmp if provided returns the result of
* @param result_cmp If provided returns the result of
* func(node->data, data) node being the last (returned) node. If node
* was found (exact match), then it is 0. If returned node is smaller
* than requested data, it is less than 0 and if it's bigger it's
* greater than 0. It is the last value returned by func().
* @return the nearest node, @c NULL if not found.
* @return The nearest node, @c NULL if not found.
*
* This function searches for a node containing @p data as its data in @p list,
* if such a node exists it will be returned and @p result_cmp will be @p 0. If
@ -1059,7 +1059,7 @@ EAPI Eina_List *eina_list_search_sorted_near_list(const Eina_List *li
* @param list The list to search for data, @b must be sorted.
* @param func A function pointer that can handle comparing the list data nodes.
* @param data reference value to search.
* @return the node if func(node->data, data) == 0, @c NULL if not found.
* @return The node if func(node->data, data) == 0, @c NULL if not found.
*
* This can be used to check if some value is inside the list and get
* the container node in this case. It should be used when list is
@ -1095,8 +1095,8 @@ EAPI Eina_List *eina_list_search_sorted_list(const Eina_List *list, E
* @param list The list to search for data, @b must be sorted.
* @param func A function pointer that can handle comparing the list data nodes.
* @param data reference value to search.
* @return the node value (@c node->data) if func(node->data, data) == 0,
* NULL if not found.
* @return The node value (@c node->data) if func(node->data, data) == 0,
* @c NULL if not found.
*
* This can be used to check if some value is inside the list and get
* the existing instance in this case. It should be used when list is
@ -1131,7 +1131,7 @@ EAPI void *eina_list_search_sorted(const Eina_List *list, Eina_C
* @param list The list to search for data, may be unsorted.
* @param func A function pointer that can handle comparing the list data nodes.
* @param data reference value to search.
* @return the node if func(node->data, data) == 0, @c NULL if not found.
* @return The node if func(node->data, data) == 0, @c NULL if not found.
*
* This can be used to check if some value is inside the list and get
* the container node in this case.
@ -1157,7 +1157,7 @@ EAPI Eina_List *eina_list_search_unsorted_list(const Eina_List *list,
* @param list The list to search for data, may be unsorted.
* @param func A function pointer that can handle comparing the list data nodes.
* @param data reference value to search.
* @return the node value (@c node->data) if func(node->data, data) == 0,
* @return The node value (@c node->data) if func(node->data, data) == 0,
* @c NULL if not found.
*
* This can be used to check if some value is inside the list and get
@ -1178,7 +1178,7 @@ EAPI Eina_List *eina_list_search_unsorted_list(const Eina_List *list,
EAPI void *eina_list_search_unsorted(const Eina_List *list, Eina_Compare_Cb func, const void *data);
/**
* @brief Get the last list node in the list.
* @brief Gets the last list node in the list.
*
* @param list The list to get the last list node from.
* @return The last list node in the list.
@ -1194,7 +1194,7 @@ EAPI void *eina_list_search_unsorted(const Eina_List *list, Eina
static inline Eina_List *eina_list_last(const Eina_List *list) EINA_PURE EINA_WARN_UNUSED_RESULT;
/**
* @brief Get the next list node after the specified list node.
* @brief Gets the next list node after the specified list node.
*
* @param list The list node to get the next list node from
* @return The next list node on success, @c NULL otherwise.
@ -1208,10 +1208,10 @@ static inline Eina_List *eina_list_last(const Eina_List *list) EINA_PURE EINA_
static inline Eina_List *eina_list_next(const Eina_List *list) EINA_PURE EINA_WARN_UNUSED_RESULT;
/**
* @brief Get the previous list node before the specified list node.
* @brief Gets the previous list node before the specified list node.
*
* @param list The list node to get the previous list node from.
* @return The previous list node o success, @c NULL otherwise.
* @return The previous list node on success, @c NULL otherwise.
* if no previous list node exists
*
* This function returns the previous list node before the current one
@ -1223,7 +1223,7 @@ static inline Eina_List *eina_list_next(const Eina_List *list) EINA_PURE EINA_
static inline Eina_List *eina_list_prev(const Eina_List *list) EINA_PURE EINA_WARN_UNUSED_RESULT;
/**
* @brief Get the list node data member.
* @brief Gets the list node data member.
*
* @param list The list node to get the data member of.
* @return The data member from the list node.
@ -1237,7 +1237,7 @@ static inline Eina_List *eina_list_prev(const Eina_List *list) EINA_PURE EINA_
static inline void *eina_list_data_get(const Eina_List *list) EINA_PURE EINA_WARN_UNUSED_RESULT;
/**
* @brief Set the list node data member.
* @brief Sets the list node data member.
*
* @param list The list node to get the data member of.
* @param data The data member to the list node.
@ -1252,7 +1252,7 @@ static inline void *eina_list_data_get(const Eina_List *list) EINA_PURE E
static inline void *eina_list_data_set(Eina_List *list, const void *data);
/**
* @brief Get the count of the number of items in a list.
* @brief Gets the count of the number of items in a list.
*
* @param list The list whose count to return.
* @return The number of members in the list.
@ -1268,7 +1268,7 @@ static inline void *eina_list_data_set(Eina_List *list, const void *data)
static inline unsigned int eina_list_count(const Eina_List *list) EINA_PURE;
/**
* @brief Returns the last list node's data
* @brief Returns the last list node's data.
*
* @param list The list
* @return The node's data, or @c NULL on being passed a @c NULL pointer
@ -1279,7 +1279,7 @@ static inline unsigned int eina_list_count(const Eina_List *list) EINA_PURE;
static inline void *eina_list_last_data_get(const Eina_List *list);
/**
* @brief Returned a new iterator associated to a list.
* @brief Returns a new iterator associated to a list.
*
* @param list The list.
* @return A new iterator.
@ -1303,7 +1303,7 @@ EAPI Eina_Iterator *eina_list_iterator_new(const Eina_List *list) EINA_MA
/**
* @brief Returned a new reversed iterator associated to a list.
* @brief Returns a new reversed iterator associated to a list.
*
* @param list The list.
* @return A new iterator.
@ -1329,7 +1329,7 @@ EAPI Eina_Iterator *eina_list_iterator_reversed_new(const Eina_List *list
/**
* @brief Returned a new accessor associated to a list.
* @brief Returns a new accessor associated to a list.
*
* @param list The list.
* @return A new accessor.
@ -1345,7 +1345,7 @@ EAPI Eina_Iterator *eina_list_iterator_reversed_new(const Eina_List *list
EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
/**
* @brief Find the member of the list and return the index.
* @brief Finds the member of the list and return the index.
*
* @param list The list.
* @param data The data member.
@ -1363,7 +1363,7 @@ EAPI int eina_list_data_idx(const Eina_List *list, void *data)
/**
* @def EINA_LIST_FOREACH
* @brief Macro to iterate over a list.
* @brief Definition for the macro to iterate over a list.
*
* @param list The list to iterate over.
* @param l A list that is used as an iterator and points to the current node.
@ -1424,7 +1424,7 @@ EAPI int eina_list_data_idx(const Eina_List *list, void *data)
/**
* @def EINA_LIST_REVERSE_FOREACH
* @brief Macro to iterate over a list in the reverse order.
* @brief Definition for the macro to iterate over a list in the reverse order.
*
* @param list The list to iterate over.
* @param l A list that is used as an iterator and points to the current node.
@ -1484,7 +1484,7 @@ EAPI int eina_list_data_idx(const Eina_List *list, void *data)
/**
* @def EINA_LIST_FOREACH_SAFE
* @brief Macro to iterate over a list with support for node deletion.
* @brief Definition for the macro to iterate over a list with support for node deletion.
*
* @param list The list to iterate over.
* @param l A list that is used as an iterator and points to the current node.
@ -1543,7 +1543,7 @@ EAPI int eina_list_data_idx(const Eina_List *list, void *data)
/**
* @def EINA_LIST_REVERSE_FOREACH_SAFE
* @brief Macro to iterate over a list in the reverse order with support
* @brief Definition for the macro to iterate over a list in the reverse order with support
* for deletion.
*
* @param list The list to iterate over.
@ -1604,7 +1604,7 @@ EAPI int eina_list_data_idx(const Eina_List *list, void *data)
/**
* @def EINA_LIST_FREE
* @brief Macro to remove each list node while having access to each node's data.
* @brief Definition for the macro to remove each list node while having access to each node's data.
*
* @param list The list that will be cleared.
* @param data Current node's data.

224
src/lib/eina/eina_lock.h
View File

@ -37,7 +37,7 @@
* <a href="https://computing.llnl.gov/tutorials/pthreads/">here</a>
*
* The Eina lock functions are grouped into several categories to handle different
* thread locking and sychronization methods:
* thread locking and synchronization methods:
* @li eina_lock_* - Functions that implement locking.
* @li eina_condition_* - Functions that implement condition variables.
* @li eina_rwlock_* - Functions that implement read/write locks.
@ -45,7 +45,7 @@
* @li eina_semaphore_* - Functions that implement semaphores.
* @li eina_barrier_* - Functions that implement barriers.
* @li eina_spinlock_* - Functions that implement spinlocks if they are available
* on the platform. If they are not available, these functuions degrade to plain locks.
* on the platform. If they are not available, these functions degrade to plain locks.
*
*
*
@ -93,7 +93,7 @@ typedef enum
} Eina_Lock_Result;
/**
* @brief A callback type for deallocation of thread level sotrage data.
* @brief A callback type for deallocation of thread level storage data.
*/
typedef void (*Eina_TLS_Delete_Cb)(void *ptr);
@ -136,19 +136,22 @@ static inline Eina_Bool eina_lock_new(Eina_Lock *mutex);
static inline Eina_Bool eina_lock_recursive_new(Eina_Lock *mutex);
/**
* @brief Deallocates an #Eina_Lock
*
* @param[in] mutex The #Eina_Lock structure to be deallocated
*
* @brief Deallocates an #Eina_Lock.
* @details This function deallocates an #Eina_Lock allocated by eina_lock_new()
* and does any platform dependent cleanup that is required.
*
* @param[in] mutex The #Eina_Lock structure to be deallocated
*
* @see eina_lock_new()
*/
static inline void eina_lock_free(Eina_Lock *mutex);
/**
* @brief Attempts to take a lock.
* @details This function attempts to gain a lock on the indicated #Eina_Lock. If the
* underlying #Eina_Lock is locked already, this call can be blocked until
* the lock is released. This is appropriate in many cases, but consider using
* eina_lock_take_try() if you don't need to block.
*
* @param[in] mutex The #Eina_Lock to take
*
@ -156,11 +159,6 @@ static inline void eina_lock_free(Eina_Lock *mutex);
* a deadlock condition exists, it returns #EINA_LOCK_DEADLOCK. If some other
* condition causes the take to fail, #EINA_LOCK_FAIL is returned.
*
* @details This function attempts to gain a lock on the indicated #Eina_Lock. If the
* underlying #Eina_Lock is locked already, this call can be blocked until
* the lock is released. This is appropriate in many cases, but consider using
* eina_lock_take_try() if you don't need to block.
*
* @see eina_lock_take_try()
* @see eina_lock_release()
*/
@ -168,6 +166,8 @@ static inline Eina_Lock_Result eina_lock_take(Eina_Lock *mutex);
/**
* @brief Attempts to take a lock if possible.
* @details This function attempts to gain a lock on the indicated #Eina_Lock.
Identical eina_lock_take(), but returns immediately if the lock is already taken.
*
* @param[in] mutex The #Eina_Lock to take
*
@ -175,9 +175,6 @@ static inline Eina_Lock_Result eina_lock_take(Eina_Lock *mutex);
* a deadlock condition exists, it returns #EINA_LOCK_DEADLOCK. If some other
* condition causes the take to fail, #EINA_LOCK_FAIL is returned.
*
* @details This function attempts to gain a lock on the indicated #Eina_Lock.
Identical eina_lock_take(), but returns immediately if the lock is already taken.
*
* @see eina_lock_take()
* @see eina_lock_release()
*/
@ -185,30 +182,28 @@ static inline Eina_Lock_Result eina_lock_take_try(Eina_Lock *mutex);
/**
* @brief Releases a lock.
*
* @param[in] mutex The #Eina_Lock to release
*
* @return Returns #EINA_LOCK_SUCCEED on success. If it fails, #EINA_LOCK_FAIL is
* returned.
*
* @details This function releases the lock on the indicated #Eina_Lock. If successful,
* and @c EINA_HAVE_DEBUG_THREADS is defined, @p mutex is updated and information
* about the locking process is removed (e.g. thread number and backtrace for POSIX).
*
* @param[in] mutex The #Eina_Lock to release
*
* @return Returns #EINA_LOCK_SUCCEED on success, If it fails, #EINA_LOCK_FAIL is
* returned.
*
* @see eina_lock_take()
* @see eina_lock_take_try()
*/
static inline Eina_Lock_Result eina_lock_release(Eina_Lock *mutex);
/**
* @brief Print debug information about a lock.
*
* @param[in] mutex The #Eina_Lock to print debug info for.
*
* @brief Prints debug information about a lock.
* @details This function prints debug information for @p mutex. The information is
* platform dependant. On POSIX systems it prints the address of @p mutex,
* lock state, thread number and a backtrace.
*
* @param[in] mutex The #Eina_Lock to print debug info for.
*
* @note If @c EINA_HAVE_DEBUG_THREADS is not defined, this function does nothing.
*
* @since 1.19
@ -217,15 +212,14 @@ EAPI void eina_lock_debug(const Eina_Lock *mutex);
/**
* @brief Initializes a new condition variable.
* @details This function initializes an #Eina_Condition structure and associates it with
* an existing lock.
*
* @param[in] cond The condition variable to create
* @param[in] mutex The #Eina_Lock structure that controls access to this condition variable
*
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* @details This function initializes an #Eina_Condition structure and associates it with
* an existing lock.
*
* Condition variables are used to coordinate actions between threads. See
* <a href="https://computing.llnl.gov/tutorials/pthreads/#ConVarOverview"> Condition Varable Overview </a>
* for an introduction to condition variables and their use.
@ -235,33 +229,33 @@ EAPI void eina_lock_debug(const Eina_Lock *mutex);
static inline Eina_Bool eina_condition_new(Eina_Condition *cond, Eina_Lock *mutex);
/**
* @brief Deallocates a condition variable
*
* @param[in] cond The condition variable to be deallocated.
*
* @brief Deallocates a condition variable.
* @details This function deallocates a condition variable and does any platform dependent
* cleanup that is required.
*
* @param[in] cond The condition variable to be deallocated.
*
* @see eina_condition_new()
*/
static inline void eina_condition_free(Eina_Condition *cond);
/**
* @brief Causes a thread to wait until signaled by the condition.
* @details This function makes a thread block until a signal is sent to it via @p cond.
*
* @param[in] cond The #Eina_Condition upon which the thread waits.
*
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* @details This function makes a thread block until a signal is sent to it via @p cond.
*
* @see eina_condition_timedwait()
*/
static inline Eina_Bool eina_condition_wait(Eina_Condition *cond);
/**
* @brief Causes a thread to wait until signaled by the condition or a
* @brief Causes a thread to wait until signalled by the condition or a
* timeout is reached.
* @details This function makes a thread block until either a signal is sent to it via
* @p cond or @p t seconds have passed.
*
* @param[in] cond The #Eina_Condition upon which the thread waits.
* @param[in] t The maximum amount of time to wait, in seconds.
@ -269,39 +263,34 @@ static inline Eina_Bool eina_condition_wait(Eina_Condition *cond);
* @return #EINA_TRUE on success, #EINA_FALSE otherwise. If the operation
* timed out, eina error will be set to #ETIMEDOUT.
*
* @details This function makes a thread block until either a signal is sent to it via
* @p cond or @p t seconds have passed.
*
* @see eina_condition_wait()
*/
static inline Eina_Bool eina_condition_timedwait(Eina_Condition *cond, double t);
/**
* @brief Signal all threads waiting for a condition.
* @brief Signals all threads waiting for a condition.
* @details This function sends a signal to all the threads waiting on the condition @p cond.
* If you know for sure that there is only one thread waiting, use eina_condition_signal()
* instead to gain a little optimization.
*
* @param[in] cond The #Eina_Condition that signals all its waiting threads.
*
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* @details This function sends a signal to all the threads waiting on the condition @p cond.
* If you know for sure that there is only one thread waiting, use eina_condition_signal()
* instead to gain a little optimization.
*
* @see eina_condition_signal()
*/
static inline Eina_Bool eina_condition_broadcast(Eina_Condition *cond);
/**
* @brief Signal a thread waiting for a condition.
* @brief Signals a thread waiting for a condition.
* @details This function sends a signal to a thread waiting on the condition @p cond.
* If you do not know for sure that there is only one thread waiting, use
* eina_condition_broadcast() instead.
*
* @param[in] cond The #Eina_Condition that signals its waiting thread.
*
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* @details This function sends a signal to a thread waiting on the condition @p cond.
* If you do not know for sure that there is only one thread waiting, use
* eina_condition_broadcast() instead.
*
* @note If there is more than one thread waiting on this condition, one of them is
* signalled, but which one is undefined.
*
@ -311,43 +300,40 @@ static inline Eina_Bool eina_condition_signal(Eina_Condition *cond);
/**
* @brief Initializes a new #Eina_RWLock
* @brief Initializes a new #Eina_RWLock.
* @details This function initializes an #Eina_RWLock with appropriate values.
* These values are platform dependent as is the structure of the #Eina_RWLock
* itself.
*
* @param[in] mutex The #Eina_RWLock to be initialized.
*
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* @details This function initializes an #Eina_RWLock with appropriate values.
* These values are platform dependent as is the structure of the #Eina_RWLock
* itself.
*
* @see eina_rwlock_free()
*/
static inline Eina_Bool eina_rwlock_new(Eina_RWLock *mutex);
/**
* @brief Deallocates an #Eina_RWLock
*
* @param[in] mutex The #Eina_RWLock structure to be deallocated.
*
* @brief Deallocates an #Eina_RWLock.
* @details This function deallocates an #Eina_RWLock and does any platform dependent
* cleanup that is required.
*
* @param[in] mutex The #Eina_RWLock structure to be deallocated.
*
* @see eina_rwlock_new()
*/
static inline void eina_rwlock_free(Eina_RWLock *mutex);
/**
* @brief Attempts to take a read lock.
* @details This function attempts to gain a read lock on the indicated #Eina_RWLock. If
* the #Eina_RWLock is write locked, this call can be blocked until
* the lock is released.
*
* @param[in] mutex The #Eina_RWLock to take.
*
* @return Returns #EINA_LOCK_SUCCEED on success, #EINA_LOCK_FAIL on failure.
*
* @details This function attempts to gain a read lock on the indicated #Eina_RWLock. If
* the #Eina_RWLock is write locked, this call can be blocked until
* the lock is released.
*
* @note This function never return #EINA_LOCK_DEADLOCK.
*
* @see eina_rwlock_release()
@ -356,15 +342,14 @@ static inline Eina_Lock_Result eina_rwlock_take_read(Eina_RWLock *mutex);
/**
* @brief Attempts to take a write lock.
* @details This function attempts to gain a write lock on the indicated #Eina_RWLock. If
* the #Eina_RWLock is locked for reading or writing, this call can be
* blocked until the lock is released.
*
* @param[in] mutex The #Eina_RWLock to take.
*
* @return Returns #EINA_LOCK_SUCCEED on success, #EINA_LOCK_FAIL on failure.
*
* @details This function attempts to gain a write lock on the indicated #Eina_RWLock. If
* the #Eina_RWLock is locked for reading or writing, this call can be
* blocked until the lock is released.
*
* @note This function never return #EINA_LOCK_DEADLOCK.
*
* @see eina_rwlock_release()
@ -373,14 +358,13 @@ static inline Eina_Lock_Result eina_rwlock_take_write(Eina_RWLock *mutex);
/**
* @brief Releases a lock.
* @details This function releases the lock on the indicated #Eina_RWLock.
*
* @param[in] mutex The #Eina_RWLock to release.
*
* @return Returns #EINA_LOCK_SUCCEED on success. If it fails, #EINA_LOCK_FAIL is
* returned.
*
* @details This function releases the lock on the indicated #Eina_RWLock.
*
* @see eina_rwlock_take_read()
* @see eina_rwlock_take_write()
*/
@ -389,15 +373,14 @@ static inline Eina_Lock_Result eina_rwlock_release(Eina_RWLock *mutex);
/**
* @brief Initializes a new #Eina_TLS, or thread level storage, to store thread
* specific data.
* @details This function initializes an #Eina_TLS with @p key but does not set a
* callback to deallocate @p key when the thread exits. The implementation
* is platform dependent as is the structure of the #Eina_TLS itself.
*
* @param[in] key The #Eina_TLS to be initialized.
*
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* @details This function initializes an #Eina_TLS with @p key but does not set a
* callback to deallocate @p key when the thread exits. The implementation
* is platform dependent as is the structure of the #Eina_TLS itself.
*
* @note use eina_tls_cb_new() instead to set a callback for deallocating @p key.
*
* @see eina_tls_cb_new()
@ -408,16 +391,15 @@ static inline Eina_Bool eina_tls_new(Eina_TLS *key);
/**
* @brief Initializes a new #Eina_TLS, or thread level storage, to store thread
* specific data.
* @details This function initializes an #Eina_TLS with @p key and sets a
* callback to deallocate @p key when the thread exits. The implementation
* is platform dependent as is the structure of the #Eina_TLS itself.
*
* @param[in] key The #Eina_TLS to be initialized.
* @param[in] delete_cb A pointer to a function that deallocates @p key.
*
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* @details This function initializes an #Eina_TLS with @p key and sets a
* callback to deallocate @p key when the thread exits. The implementation
* is platform dependent as is the structure of the #Eina_TLS itself.
*
* @see eina_tls_new()
* @see eina_tls_free()
*/
@ -425,12 +407,11 @@ static inline Eina_Bool eina_tls_cb_new(Eina_TLS *key, Eina_TLS_Delete_Cb delete
/**
* @brief Frees an allocated #Eina_TLS.
*
* @param[in] key The #Eina_TLS to be freed.
*
* @details This function frees the #Eina_TLS @p key. The implementation
* is platform dependent.
*
* @param[in] key The #Eina_TLS to be freed.
*
* @see eina_tls_new()
* @see eina_tls_cb_new()
*/
@ -438,27 +419,25 @@ static inline void eina_tls_free(Eina_TLS key);
/**
* @brief Gets the value in #Eina_TLS for this thread.
* @details This function gets a pointer to the data associated with #Eina_TLS @p key for
* this thread. The implementation is platform dependent.
*
* @param[in] key The #Eina_TLS to be retrieved.
*
* @return A pointer to the data associated with @p key.
*
* @details This function gets a pointer to the data associated with #Eina_TLS @p key for
* this thread. The implementation is platform dependent.
*
* @see eina_tls_set()
*/
static inline void *eina_tls_get(Eina_TLS key);
/**
* @brief Sets the value in Eina_TLS for this thread.
* @details This function sets the value associated with @p key to the pointer to the data
* @p data. The implementation is platform dependent.
*
* @param[in] key The #Eina_TLS to be set.
* @param[in] data A pointer to the data to be stored.
*
* @details This function sets the value associated with @p key to the pointer to the data
* @p data. The implementation is platform dependent.
*
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* @see eina_tls_get()
@ -466,113 +445,105 @@ static inline void *eina_tls_get(Eina_TLS key);
static inline Eina_Bool eina_tls_set(Eina_TLS key, const void *data);
/**
* @brief Initializes a new #Eina_Semaphore
* @brief Initializes a new #Eina_Semaphore.
* @details This function initializes an unnamed #Eina_Semaphore with appropriate values.
* These values are platform dependent.
*
* @param[in] sem The #Eina_Semaphore to be initialized.
* @param[in] count_init Indicates the initial count of threads waiting on this semaphore.
*
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* @details This function initializes an unnamed #Eina_Semaphore with appropriate values.
* These values are platform dependent.
*
* @see eina_semaphore_free()
*/
static inline Eina_Bool eina_semaphore_new(Eina_Semaphore *sem, int count_init);
/**
* @brief Frees an allocated #Eina_Semaphore.
* @details This function frees the #Eina_Semaphore @p sem. The implementation
* is platform dependent.
*
* @param[in] sem The #Eina_Semaphore to be freed.
*
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* @details This function frees the #Eina_Semaphore @p sem. The implementation
* is platform dependent.
*
* @see eina_semaphore_new()
*/
static inline Eina_Bool eina_semaphore_free(Eina_Semaphore *sem);
/**
* @brief Gets a lock on an #Eina_Semaphore.
* @details This function locks the #Eina_Semaphore @p sem. The implementation
* is platform dependent.
*
* @param[in] sem The #Eina_Semaphore to lock.
*
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* @details This function locks the #Eina_Semaphore @p sem. The implementation
* is platform dependent.
*
* @see eina_semaphore_release()
*/
static inline Eina_Bool eina_semaphore_lock(Eina_Semaphore *sem);
/**
* @brief Releases a lock on an #Eina_Semaphore.
* @details This function releases a lock on the #Eina_Semaphore @p sem. The implementation
* is platform dependent.
*
* @param[in] sem The #Eina_Semaphore to release.
* @param[in] count_release Not used.
*
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* @details This function releases a lock on the #Eina_Semaphore @p sem. The implementation
* is platform dependent.
*
* @see eina_semaphore_lock()
*/
static inline Eina_Bool eina_semaphore_release(Eina_Semaphore *sem, int count_release);
/**
* @brief Initializes a new #Eina_Barrier
* @brief Initializes a new #Eina_Barrier.
* @details This function initializes a new #Eina_Barrier. It sets the @c needed flag
* to the value of @p needed, sets the barrier's @c count member to 0 and
* creates new #Eina_Lock and #Eina_Condition objects for the barrier.
*
* @param[in] barrier The #Eina_Barrier to be initialized.
* @param[in] needed The number of thread waits that causes this barrier to be reset.
*
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* @details This function initializes a new #Eina_Barrier. It sets the @c needed flag
* to the value of @p needed, sets the barrier's @c count member to 0 and
* creates new #Eina_Lock and #Eina_Condition objects for the barrier.
*
* @see eina_barrier_free()
*/
static inline Eina_Bool eina_barrier_new(Eina_Barrier *barrier, int needed);
/**
* @brief Frees an allocated #Eina_Barrier.
* @details This function frees the #Eina_Barrier @p barrier.
*
* @param[in] barrier The #Eina_Barrier to be freed.
*
* @details This function frees the #Eina_Barrier @p barrier.
*
* @see eina_barrier_new()
*/
static inline void eina_barrier_free(Eina_Barrier *barrier);
/**
* @brief Increments the count of threads that are waiting on @p barrier.
*
* @details When the count of threads reaches the @c needed value for the barrier, all
* waiting threads are notified via eina_condition_broadcast().
* @param[in] barrier The #Eina_Barrier to be incremented.
*
* @return #EINA_TRUE on success, else #EINA_FALSE otherwise.
*
* @details When the count of threads reaches the @c needed value for the barrier, all
* waiting threads are notified via eina_condition_broadcast().
*/
static inline Eina_Bool eina_barrier_wait(Eina_Barrier *barrier);
/**
* @brief Initializes a new #Eina_Spinlock
* @brief Initializes a new #Eina_Spinlock.
* @details This function initializes a new #Eina_Spinlock, if spinlocks are available. If
* spinlocks are not available, it creates a new #Eina_Lock.
*
* @param[in] spinlock The #Eina_Spinlock to be initialized.
*
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* @details This function initializes a new #Eina_Spinlock, if spinlocks are available. If
* spinlocks are not avialable, it creates a new #Eina_Lock.
*
* @note Spinlocks are only implemented on the POSIX platform and are only available
* if #EINA_HAVE_POSIX_SPINLOCK is defined. you get a new #Eina_Lock on All other platforms.
*
@ -582,6 +553,10 @@ static inline Eina_Bool eina_spinlock_new(Eina_Spinlock *spinlock);
/**
* @brief Attempts to take a spinlock.
* @details This function attempts to gain a lock on the indicated #Eina_Spinlock. If the
* underlying #Eina_Spinlock is locked already, this call can be blocked until
* the lock is released. This is appropriate in many cases, but consider using
* eina_spinlock_take_try() if you don't need to block.
*
* @param[in] spinlock The #Eina_Spinlock to take.
*
@ -589,11 +564,6 @@ static inline Eina_Bool eina_spinlock_new(Eina_Spinlock *spinlock);
* a deadlock condition exists, it returns #EINA_LOCK_DEADLOCK. If some other
* condition causes the take to fail, #EINA_LOCK_FAIL is returned.
*
* @details This function attempts to gain a lock on the indicated #Eina_Spinlock. If the
* underlying #Eina_Spinlock is locked already, this call can be blocked until
* the lock is released. This is appropriate in many cases, but consider using
* eina_spinlock_take_try() if you don't need to block.
*
* @see eina_spinlock_take_try()
* @see eina_spinlock_release()
*/
@ -601,6 +571,8 @@ static inline Eina_Lock_Result eina_spinlock_take(Eina_Spinlock *spinlock);
/**
* @brief Attempts to take a spinlock if possible.
* @details This function attempts to gain a lock on the indicated #Eina_Spinlock. Identical
* to eina_lock_take(), but returns immediately if the lock is already taken.
*
* @param[in] spinlock The #Eina_Spinlock to take.
*
@ -608,9 +580,6 @@ static inline Eina_Lock_Result eina_spinlock_take(Eina_Spinlock *spinlock);
* a deadlock condition exists, it returns #EINA_LOCK_DEADLOCK. If some other
* condition causes the take to fail, #EINA_LOCK_FAIL is returned.
*
* @details This function attempts to gain a lock on the indicated #Eina_Spinlock. Identical
* to eina_lock_take(), but returns immediately if the lock is already taken.
*
* @see eina_spinlock_take_try()
* @see eina_spinlock_release()
*/
@ -618,15 +587,14 @@ static inline Eina_Lock_Result eina_spinlock_take_try(Eina_Spinlock *spinlock);
/**
* @brief Releases a spinlock.
* @details This function will release the lock on the indicated #Eina_Spinlock. If successful,
* and @c EINA_HAVE_DEBUG_THREADS is defined, @p mutex is updated and information
* about the locking process is removed (e.g. thread number and backtrace for POSIX).
*
* @param[in] spinlock The #Eina_Spinlock to release.
*
* @return Returns #EINA_LOCK_SUCCEED on success, #EINA_LOCK_FAIL otherwise.
*
* @details This function will release the lock on the indicated #Eina_Spinlock. If successful,
* and @c EINA_HAVE_DEBUG_THREADS is defined, @p mutex is updated and information
* about the locking process is removed (e.g. thread number and backtrace for POSIX).
*
* @see eina_spinlock_take()
* @see eina_spinlock_take_try()
@ -634,12 +602,12 @@ static inline Eina_Lock_Result eina_spinlock_take_try(Eina_Spinlock *spinlock);
static inline Eina_Lock_Result eina_spinlock_release(Eina_Spinlock *spinlock);
/**
* @brief Deallocates an #Eina_Spinlock
* @brief Deallocates an #Eina_Spinlock.
* @details This function deallocates an #Eina_Spinlock and does any platform dependent
* cleanup that is required.
*
* @param[in] spinlock The #Eina_Spinlock to be deallocated.
*
* @details This function deallocates an #Eina_Spinlock and does any platform dependent
* cleanup that is required.
*/
static inline void eina_spinlock_free(Eina_Spinlock *spinlock);
@ -671,13 +639,13 @@ static inline void eina_spinlock_free(Eina_Spinlock *spinlock);
#else
/**
* @def EINA_MAIN_LOOP_CHECK_RETURN_VAL
* @brief The macro doesn't do anything unless @c EINA_HAVE_DEBUG_THREADS is defined.
* @brief Definition for the macro that doesn't do anything unless @c EINA_HAVE_DEBUG_THREADS is defined.
* @param[in] val The value to be returned
*/
# define EINA_MAIN_LOOP_CHECK_RETURN_VAL(val)
/**
* @def EINA_MAIN_LOOP_CHECK_RETURN
* @brief The macro doesn't do anything unless @c EINA_HAVE_DEBUG_THREADS is defined.
* @brief Definition for the macro that doesn't do anything unless @c EINA_HAVE_DEBUG_THREADS is defined.
*/
# define EINA_MAIN_LOOP_CHECK_RETURN
#endif

156
src/lib/eina/eina_log.h
View File

@ -289,7 +289,7 @@ EAPI extern int EINA_LOG_DOMAIN_GLOBAL;
* @def EINA_LOG(DOM, LEVEL, fmt, ...)
* Logs a message on the specified domain, level and format.
*
* @note if @c EINA_LOG_LEVEL_MAXIMUM is defined, then messages larger
* @note If @c EINA_LOG_LEVEL_MAXIMUM is defined, then messages larger
* than this value will be ignored regardless of current domain
* level, the eina_log_print() is not even called! Most
* compilers will just detect the two integers make the branch
@ -498,9 +498,9 @@ typedef enum _Eina_Log_State
*
* By default, eina_log_print_cb_stderr() is used.
*
* @note MT: safe to call from any thread.
* @note MT: Safe to call from any thread.
*
* @note MT: given function @a cb will be called protected by mutex.
* @note MT: Given function @a cb will be called protected by mutex.
* This means you're safe from other calls but you should never
* call eina_log_print(), directly or indirectly.
*/
@ -508,7 +508,7 @@ EAPI void eina_log_print_cb_set(Eina_Log_Print_Cb cb, void *data) EINA_ARG_NONNU
/**
* @brief Set the default log level.
* @brief Sets the default log level.
*
* @param level The log level.
*
@ -522,16 +522,16 @@ EAPI void eina_log_print_cb_set(Eina_Log_Print_Cb cb, void *data) EINA_ARG_NONNU
EAPI void eina_log_level_set(int level);
/**
* @brief Get the default log level.
* @brief Gets the default log level.
*
* @return the log level that limits eina_log_print().
* @return The log level that limits eina_log_print().
*
* @see eina_log_level_set()
*/
EAPI int eina_log_level_get(void) EINA_WARN_UNUSED_RESULT;
/**
* @brief Determine if a given @p level should be logged.
* @brief Determines if a given @p level should be logged.
*
* @return #EINA_TRUE if the @p level should be logged, else #EINA_FALSE.
*
@ -546,7 +546,7 @@ static inline Eina_Bool eina_log_level_check(int level);
* 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).
* main thread).
*
* @return #EINA_TRUE if the current thread is the one that called
* eina_log_threads_init(), otherwise #EINA_FALSE.
@ -555,7 +555,7 @@ EAPI Eina_Bool eina_log_main_thread_check(void) EINA_CONST EINA_WARN_UN
/**
* @brief Enable or disable colored text in the logs.
* @brief Enables or disables colored text in the logs.
*
* @param disabled If #EINA_TRUE, color logging should be disabled.
*
@ -566,7 +566,7 @@ 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 Determine if color logging is enabled or disabled.
* @brief Determines if color logging is enabled or disabled.
*
* @return If #EINA_TRUE, color logging is disabled.
*
@ -575,9 +575,9 @@ EAPI void eina_log_color_disable_set(Eina_Bool disabled);
EAPI Eina_Bool eina_log_color_disable_get(void) EINA_WARN_UNUSED_RESULT;
/**
* @brief Set if originating file name logging should be disabled.
* @brief Sets if originating file name logging should be disabled.
*
* @param disabled if #EINA_TRUE, file name logging should be disabled.
* @param disabled If #EINA_TRUE, file name logging should be disabled.
*
* @note this is initially set to envvar EINA_LOG_FILE_DISABLE by eina_init().
*
@ -586,18 +586,18 @@ EAPI Eina_Bool eina_log_color_disable_get(void) EINA_WARN_UNUSED_RESULT
EAPI void eina_log_file_disable_set(Eina_Bool disabled);
/**
* @brief Get if originating file name logging should be disabled.
* @brief Gets if originating file name logging should be disabled.
*
* @return if #EINA_TRUE, file name logging should be disabled.
* @return If #EINA_TRUE, file name logging should be disabled.
*
* @see eina_log_file_disable_set()
*/
EAPI Eina_Bool eina_log_file_disable_get(void) EINA_WARN_UNUSED_RESULT;
/**
* @brief Set if originating function name logging should be disabled.
* @brief Sets if originating function name logging should be disabled.
*
* @param disabled if #EINA_TRUE, function name logging should be disabled.
* @param disabled If #EINA_TRUE, function name logging should be disabled.
*
* @note this is initially set to envvar EINA_LOG_FUNCTION_DISABLE by
* eina_init().
@ -607,18 +607,18 @@ EAPI Eina_Bool eina_log_file_disable_get(void) EINA_WARN_UNUSED_RESULT;
EAPI void eina_log_function_disable_set(Eina_Bool disabled);
/**
* @brief Get if originating function name logging should be disabled.
* @brief Gets if originating function name logging should be disabled.
*
* @return if #EINA_TRUE, function name logging should be disabled.
* @return If #EINA_TRUE, function name logging should be disabled.
*
* @see eina_log_function_disable_set()
*/
EAPI Eina_Bool eina_log_function_disable_get(void) EINA_WARN_UNUSED_RESULT;
/**
* @brief Set if critical messages should abort the program.
* @brief Sets if critical messages should abort the program.
*
* @param abort_on_critical if #EINA_TRUE, messages with level equal
* @param abort_on_critical If #EINA_TRUE, messages with level equal
* or smaller than eina_log_abort_on_critical_level_get() will
* abort the program.
*
@ -631,9 +631,9 @@ EAPI Eina_Bool eina_log_function_disable_get(void) EINA_WARN_UNUSED_RES
EAPI void eina_log_abort_on_critical_set(Eina_Bool abort_on_critical);
/**
* @brief Get if critical messages should abort the program.
* @brief Gets if critical messages should abort the program.
*
* @return if #EINA_TRUE, any messages with level equal or smaller
* @return If #EINA_TRUE, any messages with level equal or smaller
* than eina_log_abort_on_critical_level_get() will abort the
* program.
*
@ -643,9 +643,9 @@ EAPI void eina_log_abort_on_critical_set(Eina_Bool abort_on_critic
EAPI Eina_Bool eina_log_abort_on_critical_get(void) EINA_WARN_UNUSED_RESULT;
/**
* @brief Set level that triggers abort if abort-on-critical is set.
* @brief Sets level that triggers abort if abort-on-critical is set.
*
* @param critical_level levels equal or smaller than the given value
* @param critical_level Levels equal or smaller than the given value
* will trigger program abortion if
* eina_log_abort_on_critical_get() returns #EINA_TRUE.
*
@ -658,9 +658,9 @@ EAPI Eina_Bool eina_log_abort_on_critical_get(void) EINA_WARN_UNUSED_RE
EAPI void eina_log_abort_on_critical_level_set(int critical_level);
/**
* @brief Get level that triggers abort if abort-on-critical is set.
* @brief Gets level that triggers abort if abort-on-critical is set.
*
* @return critical level equal or smaller than value will trigger
* @return Critical level equal or smaller than value will trigger
* program abortion if eina_log_abort_on_critical_get()
* returns #EINA_TRUE.
*
@ -671,23 +671,23 @@ EAPI int eina_log_abort_on_critical_level_get(void) EINA_WARN_UNU
/**
* Set the domain level given its name.
* @brief Sets the domain level given its name.
*
* This call has the same effect as setting
* EINA_LOG_LEVELS=&lt;@p domain_name&gt;:&lt;@p level&gt;
*
* @param domain_name domain name to change the level. It may be of a
* @param domain_name Domain name to change the level. It may be of a
* still not registered domain. If the domain is not registered
* yet, it will be saved as a pending set and applied upon
* registration.
* @param level level to use to limit eina_log_print() for given domain.
* @param level Level to use to limit eina_log_print() for given domain.
*/
EAPI void eina_log_domain_level_set(const char *domain_name, int level) EINA_ARG_NONNULL(1);
/**
* Get the domain level given its name.
* @brief Gets the domain level given its name.
*
* @param domain_name domain name to retrieve the level. It may be of
* @param domain_name Domain name to retrieve the level. It may be of
* a still not registered domain. If the domain is not
* registered yet, but there is a pending value, either from
* eina_log_domain_level_set(),EINA_LOG_LEVELS environment
@ -695,7 +695,7 @@ EAPI void eina_log_domain_level_set(const char *domain_name, int l
* returned. If nothing else was found, then the global/default
* level (eina_log_level_get()) is returned.
*
* @return level to use to limit eina_log_print() for given
* @return Level to use to limit eina_log_print() for given
* domain. On error (@p domain_name == NULL),
* EINA_LOG_LEVEL_UNKNOWN is returned.
*
@ -705,9 +705,9 @@ EAPI void eina_log_domain_level_set(const char *domain_name, int l
EAPI int eina_log_domain_level_get(const char *domain_name) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
/**
* Get the domain level given its identifier.
* @brief Gets the domain level given its identifier.
*
* @param domain identifier, so it must be previously registered with
* @param domain Identifier, so it must be previously registered with
* eina_log_domain_register(). It's a much faster version of
* eina_log_domain_level_get(), but relies on domain being
* present.
@ -718,13 +718,13 @@ EAPI int eina_log_domain_level_get(const char *domain_name) EINA_
EAPI int eina_log_domain_registered_level_get(int domain) EINA_WARN_UNUSED_RESULT;
/**
* Set the domain level given its identifier.
* @brief Sets the domain level given its identifier.
*
* @param domain identifier, so it must be previously registered with
* @param domain Identifier, so it must be previously registered with
* eina_log_domain_register(). It's a much faster version of
* eina_log_domain_level_get(), but relies on domain being
* present.
* @param level level to use to limit eina_log_print() for given domain.
* @param level Level to use to limit eina_log_print() for given domain.
* @since 1.10
*/
EAPI void eina_log_domain_registered_level_set(int domain, int level);
@ -742,17 +742,17 @@ static inline Eina_Bool eina_log_domain_level_check(int domain, int level);
* @return Domain index that will be used as the DOMAIN parameter on log
* macros. A negative return value means an log occurred.
*
* @note MT: safe to call from any thread.
* @note MT: Safe to call from any thread.
*/
EAPI int eina_log_domain_register(const char *name, const char *color) EINA_ARG_NONNULL(1);
/**
* Forget about a logging domain registered by eina_log_domain_register()
* @brief Forgets about a logging domain registered by eina_log_domain_register()
*
* @param domain domain identifier as reported by eina_log_domain_register(),
* @param domain Domain identifier as reported by eina_log_domain_register(),
* must be >= 0.
*
* @note MT: safe to call from any thread.
* @note MT: Safe to call from any thread.
*/
EAPI void eina_log_domain_unregister(int domain);
@ -761,26 +761,26 @@ EAPI void eina_log_domain_unregister(int domain);
*/
/**
* Print out log message using given domain and level.
* @brief Prints out log message using given domain and level.
*
* @note Usually you'll not use this function directly but the helper
* macros EINA_LOG(), EINA_LOG_DOM_CRIT(), EINA_LOG_CRIT() and
* so on. See eina_log.h
*
* @param domain logging domain to use or @c EINA_LOG_DOMAIN_GLOBAL if
* @param domain Logging domain to use or @c EINA_LOG_DOMAIN_GLOBAL if
* you registered none. It is recommended that modules and
* applications have their own logging domain.
* @param level message level, those with level greater than user
* @param level Message level, those with level greater than user
* specified value (eina_log_level_set() or environment
* variables EINA_LOG_LEVEL, EINA_LOG_LEVELS) will be ignored.
* @param file filename that originated the call, must @b not be @c NULL.
* @param function function that originated the call, must @b not be @c NULL.
* @param line originating line in @a file.
* @param fmt printf-like format to use. Should not provide trailing
* @param file Filename that originated the call, must @b not be @c NULL.
* @param function Function that originated the call, must @b not be @c NULL.
* @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.
* @param ... Variadic args.
*
* @note MT: this function may be called from different threads if
* @note MT: This function may be called from different threads if
* eina_log_threads_enable() was called before.
*/
EAPI void eina_log_print(int domain,
@ -792,24 +792,24 @@ EAPI void eina_log_print(int domain,
...) EINA_ARG_NONNULL(3, 4, 6) EINA_PRINTF(6, 7) EINA_NOINSTRUMENT;
/**
* Print out log message using given domain and level.
* @brief Prints out log message using given domain and level.
*
* @note Usually you'll not use this function directly but the helper
* macros EINA_LOG(), EINA_LOG_DOM_CRIT(), EINA_LOG_CRIT() and
* so on. See eina_log.h
*
* @param domain logging domain to use or @c EINA_LOG_DOMAIN_GLOBAL if
* @param domain Logging domain to use or @c EINA_LOG_DOMAIN_GLOBAL if
* you registered none. It is recommended that modules and
* applications have their own logging domain.
* @param level message level, those with level greater than user
* @param level Message level, those with level greater than user
* specified value (eina_log_level_set() or environment
* variables EINA_LOG_LEVEL, EINA_LOG_LEVELS) will be ignored.
* @param file filename that originated the call, must @b not be @c NULL.
* @param fnc function that originated the call, must @b not be @c NULL.
* @param line originating line in @a file.
* @param fmt printf-like format to use. Should not provide trailing
* @param file Filename that originated the call, must @b not be @c NULL.
* @param fnc Function that originated the call, must @b not be @c NULL.
* @param line Originating line in @a file.
* @param fmt Printf-like format to use. Should not provide trailing
* '\n' as it is automatically included.
* @param args the arguments needed by the format.
* @param args The arguments needed by the format.
*
* @note MT: this function may be called from different threads if
* eina_log_threads_enable() was called before.
@ -850,7 +850,7 @@ EAPI void eina_log_vprint(int domain,
* EINA_LOG_FUNCTION_DISABLE will be considered and file information
* will be printed anyways.
*
* @note MT: if threads are enabled, this function is called within locks.
* @note MT: If threads are enabled, this function is called within locks.
* @note MT: Threads different from main thread will have thread id
* appended to domain name.
*/
@ -893,7 +893,7 @@ EAPI void eina_log_print_cb_stdout(const Eina_Log_Domain *d,
* EINA_LOG_FUNCTION_DISABLE will be considered and file information
* will be printed anyways.
*
* @note MT: if threads are enabled, this function is called within locks.
* @note MT: If threads are enabled, this function is called within locks.
* @note MT: Threads different from main thread will have thread id
* appended to domain name.
*/
@ -907,7 +907,7 @@ EAPI void eina_log_print_cb_stderr(const Eina_Log_Domain *d,
va_list args) EINA_ARG_NONNULL(1);
/**
* Alternative logging method, this will output to given file stream.
* @brief Alternative logging method, this will output to given file stream.
*
* @param d The domain.
* @param level Not used.
@ -920,7 +920,7 @@ EAPI void eina_log_print_cb_stderr(const Eina_Log_Domain *d,
*
* This method will never output color.
*
* @note MT: if threads are enabled, this function is called within locks.
* @note MT: If threads are enabled, this function is called within locks.
* @note MT: Threads different from main thread will have thread id
* appended to domain name.
*/
@ -935,7 +935,7 @@ EAPI void eina_log_print_cb_file(const Eina_Log_Domain *d,
/**
* Alternative logging method, this will output to systemd journal.
* @brief Alternative logging method, this will output to systemd journal.
*
* @param d The domain.
* @param level Not used.
@ -948,8 +948,8 @@ EAPI void eina_log_print_cb_file(const Eina_Log_Domain *d,
*
* This method will never output color.
*
* @note if systemd journal is not there it will display error on stderr.
* @note if the process has been started by systemd this will be the default logging method.
* @note If systemd journal is not there it will display error on stderr.
* @note If the process has been started by systemd this will be the default logging method.
*
* @since 1.8
*/
@ -963,35 +963,37 @@ EAPI void eina_log_print_cb_journald(const Eina_Log_Domain *d,
va_list args) EINA_ARG_NONNULL(1);
/**
* Configure console color of given file.
* @brief Configures 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 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.
*
* @note if color is disabled, nothing is done. See
* @note If color is disabled, nothing is done. See
* eina_log_color_disable_get()
* @note on windows, both @a fp and @a color is converted automatically.
* @note On windows, both @a fp and @a color is converted automatically.
*
* @since 1.7
*/
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 */
/** 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 */
/** 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
/**
* @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
/**
* @def EINA_LOG_STATE_SHUTDOWN
* String that indicates the log system is shutting down
*/
#define EINA_LOG_STATE_SHUTDOWN _eina_log_state_shutdown
/**
* @brief Start or stop the timing of a phase.
* @brief Starts or stops the timing of a phase.
*
* @param domain The domain.
* @param state State indicating if we are starting or stopping a phase.

40
src/lib/eina/eina_magic.h
View File

@ -134,14 +134,13 @@ typedef unsigned int Eina_Magic;
/**
* @brief Gets the string associated to the given magic identifier.
*
* @param[in] magic The magic identifier
* @return The string associated to the identifier
*
* @details This function returns the string associated to @p magic. Even if none are
* found this function still returns non @c NULL, in this case an identifier
* such as "(none)", "(undefined)", or "(unknown)".
*
* @param[in] magic The magic identifier
* @return The string associated to the identifier
*
* @note The following identifiers may be returned whenever magic is
* invalid, with their meanings:
*
@ -154,6 +153,9 @@ typedef unsigned int Eina_Magic;
EAPI const char *eina_magic_string_get(Eina_Magic magic) EINA_WARN_UNUSED_RESULT;
/**
* @brief Sets the string associated to the given magic identifier.
* @details This function sets the string @p magic_name to @p magic. It is not
* checked if number or string are already set, in which case you end with
* duplicates. Internally, eina makes a copy of @p magic_name.
*
* @param[in] magic The magic identifier
* @param[in] magic_name The string associated to the identifier, must not
@ -161,10 +163,6 @@ EAPI const char *eina_magic_string_get(Eina_Magic magic) EINA_WARN_UNUSED_RESULT
*
* @return #EINA_TRUE on success, otherwise #EINA_FALSE on failure
*
* @details This function sets the string @p magic_name to @p magic. It is not
* checked if number or string are already set, in which case you end with
* duplicates. Internally, eina makes a copy of @p magic_name.
*
* @see eina_magic_string_static_set()
*/
EAPI Eina_Bool eina_magic_string_set(Eina_Magic magic,
@ -172,6 +170,10 @@ EAPI Eina_Bool eina_magic_string_set(Eina_Magic magic,
/**
* @brief Sets the string associated to the given magic identifier.
* @details This function sets the string @p magic_name to @p magic. It is not checked if
* number or string are already set, in which case you might end with
* duplicates. Eina does @b not make a copy of @p magic_name, this means that
* @p magic_name has to be a valid pointer for as long as @p magic is used.
*
* @param[in] magic The magic identifier
* @param[in] magic_name The string associated to the identifier, must not be
@ -179,11 +181,6 @@ EAPI Eina_Bool eina_magic_string_set(Eina_Magic magic,
*
* @return #EINA_TRUE on success, otherwise #EINA_FALSE on failure
*
* @details This function sets the string @p magic_name to @p magic. It is not checked if
* number or string are already set, in which case you might end with
* duplicates. Eina does @b not make a copy of @p magic_name, this means that
* @p magic_name has to be a valid pointer for as long as @p magic is used.
*
* @see eina_magic_string_set()
*/
EAPI Eina_Bool eina_magic_string_static_set(Eina_Magic magic,
@ -269,6 +266,14 @@ EAPI extern Eina_Error EINA_ERROR_MAGIC_FAILED;
/**
* @brief Displays a message or aborts if a magic check failed.
* @details This function displays an error message if a magic check has
* failed, using the following logic in the following order:
* @li If @p d is @c NULL, a message warns about a @c NULL pointer.
* @li Otherwise, if @p m is equal to #EINA_MAGIC_NONE, a message
* warns about a handle that is already freed.
* @li Otherwise, if @p m is equal to @p req_m, a message warns about
* a handle that is of the wrong type.
* @li Otherwise, a message warns you about abusing that function...
*
* @param[in] d The checked data pointer
* @param[in] m The magic identifier to check
@ -280,15 +285,6 @@ EAPI extern Eina_Error EINA_ERROR_MAGIC_FAILED;
* @warning You should @b strongly consider using @ref EINA_MAGIC_FAIL(d, m)
* instead.
*
* @details This function displays an error message if a magic check has
* failed, using the following logic in the following order:
* @li If @p d is @c NULL, a message warns about a @c NULL pointer.
* @li Otherwise, if @p m is equal to #EINA_MAGIC_NONE, a message
* warns about a handle that is already freed.
* @li Otherwise, if @p m is equal to @p req_m, a message warns about
* a handle that is of the wrong type.
* @li Otherwise, a message warns you about abusing that function...
*
* @note If the environment variable EINA_LOG_ABORT is set, abort() is
* called and the program stops. It is useful for debugging programs
* with gdb.

24
src/lib/eina/eina_main.h
View File

@ -44,13 +44,13 @@
/**
* @def EINA_VERSION_MAJOR
* @brief Major version of Eina
* @brief Definition for the major version of Eina.
*/
#define EINA_VERSION_MAJOR EFL_VERSION_MAJOR
/**
* @def EINA_VERSION_MINOR
* @brief Minor version of Eina
* @brief Definition for the minor version of Eina.
*/
#define EINA_VERSION_MINOR EFL_VERSION_MINOR
@ -69,9 +69,9 @@ typedef struct _Eina_Version
EAPI extern Eina_Version *eina_version;
/**
* @brief Initialize the Eina library.
* @brief Initializes the Eina library.
*
* @return 1 or greater on success, 0 on error.
* @return @c 1 or greater on success, @c 0 on error.
*
* This function sets up all the eina modules. It returns 0 on
* failure (that is, when one of the module fails to initialize),
@ -176,9 +176,9 @@ EAPI extern Eina_Version *eina_version;
EAPI int eina_init(void);
/**
* @brief Shut down the Eina library.
* @brief Shuts down the Eina library.
*
* @return 0 when all the modules are completely shut down, 1 or
* @return @c 0 when all the modules are completely shut down, @c 1 or
* greater otherwise.
*
* This function shuts down the Eina library. It returns 0 when it has
@ -192,9 +192,9 @@ EAPI int eina_init(void);
EAPI int eina_shutdown(void);
/**
* @brief Initialize the mutexes of the Eina library.
* @brief Initializes the mutexes of the Eina library.
*
* @return 1 or greater on success, 0 on error.
* @return @c 1 or greater on success, @c 0 on error.
*
* This function sets up all the mutexes in all eina modules. It returns 0 on
* failure (that is, when one of the module fails to initialize),
@ -209,9 +209,9 @@ EAPI int eina_shutdown(void);
EAPI int eina_threads_init(void);
/**
* @brief Shut down mutexes in the Eina library.
* @brief Shuts down mutexes in the Eina library.
*
* @return 0 when all mutexes are completely shut down, 1 or
* @return @c 0 when all mutexes are completely shut down, @c 1 or
* greater otherwise.
*
* This function shuts down the mutexes in the Eina library. It returns 0 when it has
@ -227,7 +227,7 @@ EAPI int eina_threads_init(void);
EAPI int eina_threads_shutdown(void);
/**
* @brief Check if you are calling this function from the same thread Eina was initialized or not
* @brief Checks if you are calling this function from the same thread Eina was initialized or not.
*
* @return #EINA_TRUE is the calling function is the same thread, #EINA_FALSE otherwise.
*
@ -240,7 +240,7 @@ EAPI int eina_threads_shutdown(void);
EAPI Eina_Bool eina_main_loop_is(void);
/**
* @brief You should never use that function excpet if you really really know what your are doing.
* @brief You should never use that function except if you really really know what your are doing.
* @since 1.1.0
*
* If you are reading this documentation, that certainly means you don't know what is the purpose of

104
src/lib/eina/eina_matrix.h
View File

@ -54,7 +54,7 @@ typedef enum _Eina_Matrix_Type
/**
* @defgroup Eina_Matrix3_Group 3x3 Matrices in floating point
*
* @brief Matrix definition and operations
* @brief Matrix definition and operations.
*
* @{
*/
@ -91,7 +91,7 @@ struct _Eina_Matrix3
/**
* @defgroup Eina_Matrix4_Group 4x4 Matrices in floating point
*
* @brief Matrix definition and operations
* @brief Matrix definition and operations.
*
* @{
*/
@ -136,7 +136,7 @@ struct _Eina_Matrix4
/**
* @defgroup Eina_Matrix3_F16p16_Group 3x3 Matrices in fixed point
*
* @brief Fixed point matrix operations
* @brief Fixed point matrix operations.
* @{
*/
@ -166,7 +166,7 @@ struct _Eina_Matrix3_F16p16
};
/**
* @brief Set the given fixed point matrix to the identity matrix.
* @brief Sets the given fixed point matrix to the identity matrix.
*
* @param m The fixed point matrix to set
*
@ -185,7 +185,7 @@ EAPI void eina_matrix3_f16p16_compose(const Eina_Matrix3_F16p16 *m1,
Eina_Matrix3_F16p16 *dst);
/**
* @brief Return the type of the given fixed point matrix.
* @brief Returns the type of the given fixed point matrix.
*
* @param m The fixed point matrix.
* @return The type of the matrix.
@ -217,7 +217,7 @@ EAPI Eina_Matrix_Type eina_matrix3_f16p16_type_get(const Eina_Matrix3_F16p16 *m)
/**
* @brief Return the type of the given floating point matrix.
* @brief Returns the type of the given floating point matrix.
*
* @param m The floating point matrix.
* @return The type of the matrix.
@ -230,7 +230,7 @@ EAPI Eina_Matrix_Type eina_matrix3_f16p16_type_get(const Eina_Matrix3_F16p16 *m)
EAPI Eina_Matrix_Type eina_matrix3_type_get(const Eina_Matrix3 *m);
/**
* @brief Set the values of the coefficients of the given floating
* @brief Sets the values of the coefficients of the given floating
* point matrix.
*
* @param m The floating point matrix.
@ -257,7 +257,7 @@ EAPI void eina_matrix3_values_set(Eina_Matrix3 *m,
double zx, double zy, double zz);
/**
* @brief Get the values of the coefficients of the given floating
* @brief Gets the values of the coefficients of the given floating
* point matrix.
*
* @param m The floating point matrix.
@ -284,7 +284,7 @@ EAPI void eina_matrix3_values_get(const Eina_Matrix3 *m,
double *zx, double *zy, double *zz);
/**
* @brief Get the values of the coefficients of the given fixed
* @brief Gets the values of the coefficients of the given fixed
* point matrix.
*
* @param m The fixed point matrix.
@ -311,7 +311,7 @@ EAPI void eina_matrix3_fixed_values_get(const Eina_Matrix3 *m,
Eina_F16p16 *zx, Eina_F16p16 *zy, Eina_F16p16 *zz);
/**
* @brief Transform the given floating point matrix to the given fixed
* @brief Transforms the given floating point matrix to the given fixed
* point matrix.
*
* @param m The floating point matrix.
@ -327,11 +327,11 @@ EAPI void eina_matrix3_matrix3_f16p16_to(const Eina_Matrix3 *m,
Eina_Matrix3_F16p16 *fm);
/**
* @brief Check whether the two given matrices are equal or not.
* @brief Checks whether the two given matrices are equal or not.
*
* @param m1 The first matrix.
* @param m2 The second matrix.
* @return EINA_TRUE if the two matrices are equal, 0 otherwise.
* @return EINA_TRUE if the two matrices are equal, @c 0 otherwise.
*
* This function return EINA_TRUE if thematrices @p m1 and @p m2 are
* equal, EINA_FALSE otherwise. No check is done on the matrices.
@ -348,7 +348,7 @@ EAPI void eina_matrix3_compose(const Eina_Matrix3 *m1,
Eina_Matrix3 *dst);
/**
* Set the matrix values for a translation
* @brief Sets the matrix values for a translation.
* @param[in] m The matrix to set the translation values
* @param[in] tx The X coordinate translate
* @param[in] ty The Y coordinate translate
@ -358,7 +358,7 @@ EAPI void eina_matrix3_compose(const Eina_Matrix3 *m1,
EAPI void eina_matrix3_translate(Eina_Matrix3 *t, double tx, double ty);
/**
* Set the matrix values for a scale
* @brief Sets the matrix values for a scale.
* @param[in] m The matrix to set the scale values
* @param[in] sx The X coordinate scale
* @param[in] sy The Y coordinate scale
@ -368,7 +368,7 @@ EAPI void eina_matrix3_translate(Eina_Matrix3 *t, double tx, double ty);
EAPI void eina_matrix3_scale(Eina_Matrix3 *t, double sx, double sy);
/**
* Set the matrix values for a rotation
* @brief Sets the matrix values for a rotation.
* @param[in] t The matrix to set the rotation values
* @param[in] rad The radius to rotate the matrix
*
@ -377,7 +377,7 @@ EAPI void eina_matrix3_scale(Eina_Matrix3 *t, double sx, double sy);
EAPI void eina_matrix3_rotate(Eina_Matrix3 *t, double rad);
/**
* @brief Set the given floating point matrix to the identity matrix.
* @brief Sets the given floating point matrix to the identity matrix.
*
* @param m The floating point matrix to set
*
@ -389,7 +389,7 @@ EAPI void eina_matrix3_rotate(Eina_Matrix3 *t, double rad);
EAPI void eina_matrix3_identity(Eina_Matrix3 *t);
/**
* @brief Return the determinant of the given matrix.
* @brief Returns the determinant of the given matrix.
*
* @param m The matrix.
* @return The determinant.
@ -402,7 +402,7 @@ EAPI void eina_matrix3_identity(Eina_Matrix3 *t);
EAPI double eina_matrix3_determinant(const Eina_Matrix3 *m);
/**
* @brief Divide the given matrix by the given scalar.
* @brief Divides the given matrix by the given scalar.
*
* @param m The matrix.
* @param scalar The scalar number.
@ -415,7 +415,7 @@ EAPI double eina_matrix3_determinant(const Eina_Matrix3 *m);
EAPI void eina_matrix3_divide(Eina_Matrix3 *m, double scalar);
/**
* @brief Compute the inverse of the given matrix.
* @brief Computes the inverse of the given matrix.
*
* @param m The matrix to inverse.
* @param m2 The inverse matrix.
@ -457,7 +457,7 @@ EAPI void eina_matrix3_rectangle_transform(const Eina_Matrix3 *m,
const Eina_Quad *q);
/**
* @brief Creates a projective matrix that maps a quadrangle to a quadrangle
* @brief Creates a projective matrix that maps a quadrangle to a quadrangle.
*/
EAPI Eina_Bool eina_matrix3_quad_quad_map(Eina_Matrix3 *m,
const Eina_Quad *src,
@ -476,7 +476,7 @@ EAPI Eina_Bool eina_matrix3_quad_square_map(Eina_Matrix3 *m,
const Eina_Quad *q);
/**
* @brief Set array to matrix.
* @brief Sets array to matrix.
*
* @param m The result matrix
* @param v The the array[9] for set
@ -488,7 +488,7 @@ EAPI Eina_Bool eina_matrix3_quad_square_map(Eina_Matrix3 *m,
EAPI void eina_matrix3_array_set(Eina_Matrix3 *m, const double *v);
/**
* @brief Copy matrix.
* @brief Copies matrix.
*
* @param dst The matrix copy
* @param src The matrix for copy.
@ -498,7 +498,7 @@ EAPI void eina_matrix3_array_set(Eina_Matrix3 *m, const double *v);
EAPI void eina_matrix3_copy(Eina_Matrix3 *dst, const Eina_Matrix3 *src);
/**
* @brief Multiply two matrix
* @brief Multiplies two matrix.
*
* @param out The resulting matrix
* @param mat_a The first member of the multiplication
@ -510,7 +510,7 @@ EAPI void eina_matrix3_multiply(Eina_Matrix3 *out, const Eina_Matrix3 *mat_a,
const Eina_Matrix3 *mat_b);
/**
* @brief Multiply two matrix
* @brief Multiplies two matrix.
*
* @param out The resulting matrix
* @param mat_a The first member of the multiplication
@ -522,7 +522,7 @@ EAPI void eina_matrix3_multiply_copy(Eina_Matrix3 *out, const Eina_Matrix3 *mat_
const Eina_Matrix3 *mat_b);
/**
* @brief Transform scale of matrix
* @brief Transforms scale of matrix.
*
* @param out The resulting matrix
* @param s_x The scale value for x
@ -533,7 +533,7 @@ EAPI void eina_matrix3_multiply_copy(Eina_Matrix3 *out, const Eina_Matrix3 *mat_
EAPI void eina_matrix3_scale_transform_set(Eina_Matrix3 *out, double s_x, double s_y);
/**
* @brief Transform position of matrix
* @brief Transforms position of matrix.
*
* @param out The resulting matrix
* @param p_x The position value for x
@ -545,7 +545,7 @@ EAPI void eina_matrix3_position_transform_set(Eina_Matrix3 *out, const double p_
const double p_y);
/**
* @brief Set normal of the given matrix.
* @brief Sets normal of the given matrix.
*
* @param out The result mtrix of normal
* @param m The matrix
@ -555,7 +555,7 @@ EAPI void eina_matrix3_position_transform_set(Eina_Matrix3 *out, const double p_
EAPI void eina_normal3_matrix_get(Eina_Matrix3 *out, const Eina_Matrix4 *m);
/**
* @brief Convert an Eina_Matrix3 into an Eina_Matrix4.
* @brief Converts an Eina_Matrix3 into an Eina_Matrix4.
*
* @param m3 The destination Eina_Matrix3.
* @param m4 The source Eina_Matrix4.
@ -575,7 +575,7 @@ EAPI void eina_matrix3_matrix4_to(Eina_Matrix4 *m4, const Eina_Matrix3 *m3);
*/
/**
* @brief Return the type of the given floating point matrix.
* @brief Returns the type of the given floating point matrix.
*
* @param m The floating point matrix.
* @return The type of the matrix.
@ -588,7 +588,7 @@ EAPI void eina_matrix3_matrix4_to(Eina_Matrix4 *m4, const Eina_Matrix3 *m3);
EAPI Eina_Matrix_Type eina_matrix4_type_get(const Eina_Matrix4 *m);
/**
* @brief Set the values of the coefficients of the given floating
* @brief Sets the values of the coefficients of the given floating
* point matrix.
*
* @param m The floating point matrix.
@ -623,7 +623,7 @@ EAPI void eina_matrix4_values_set(Eina_Matrix4 *m,
double wx, double wy, double wz, double ww);
/**
* @brief Get the values of the coefficients of the given floating
* @brief Gets the values of the coefficients of the given floating
* point matrix.
*
* @param m The floating point matrix.
@ -658,7 +658,7 @@ EAPI void eina_matrix4_values_get(const Eina_Matrix4 *m,
double *wx, double *wy, double *wz, double *ww);
/**
* @brief Return the determinant of the given matrix.
* @brief Returns the determinant of the given matrix.
*
* @param m The matrix.
* @return The determinant.
@ -671,7 +671,7 @@ EAPI void eina_matrix4_values_get(const Eina_Matrix4 *m,
EAPI double eina_matrix4_determinant(const Eina_Matrix4 *m);
/**
* @brief Return the determinant of the given matrix.
* @brief Returns the determinant of the given matrix.
*
* @param m The matrix.
* @return The determinant.
@ -685,7 +685,7 @@ EAPI Eina_Bool eina_matrix4_normalized(Eina_Matrix4 *out,
const Eina_Matrix4 *in);
/**
* @brief Return the inverse of the given matrix.
* @brief Returns the inverse of the given matrix.
*
* @param out The inverse matrix
* @param in The matrix.
@ -696,7 +696,7 @@ EAPI Eina_Bool eina_matrix4_normalized(Eina_Matrix4 *out,
EAPI Eina_Bool eina_matrix4_inverse(Eina_Matrix4 *out, const Eina_Matrix4 *in);
/**
* @brief Return the transpose of the given matrix.
* @brief Returns the transpose of the given matrix.
*
* @param out The transpose matrix
* @param in The matrix.
@ -708,7 +708,7 @@ EAPI Eina_Bool eina_matrix4_inverse(Eina_Matrix4 *out, const Eina_Matrix4 *in);
EAPI void eina_matrix4_transpose(Eina_Matrix4 *out, const Eina_Matrix4 *in);
/**
* @brief Convert an Eina_Matrix4 into an Eina_Matrix3.
* @brief Converts an Eina_Matrix4 into an Eina_Matrix3.
*
* @param m3 The destination Eina_Matrix3.
* @param m4 The source Eina_Matrix4.
@ -718,7 +718,7 @@ EAPI void eina_matrix4_transpose(Eina_Matrix4 *out, const Eina_Matrix4 *in);
EAPI void eina_matrix4_matrix3_to(Eina_Matrix3 *m3, const Eina_Matrix4 *m4);
/**
* @brief Set an identity matrix
* @brief Sets an identity matrix
*
* @param out The matrix to set
*
@ -727,7 +727,7 @@ EAPI void eina_matrix4_matrix3_to(Eina_Matrix3 *m3, const Eina_Matrix4 *m4);
EAPI void eina_matrix4_identity(Eina_Matrix4 *out);
/**
* @brief Multiply two matrix
* @brief Multiplies two matrix.
*
* @param out The resulting matrix
* @param a The first member of the multiplication
@ -739,7 +739,7 @@ EAPI void eina_matrix4_multiply_copy(Eina_Matrix4 *out,
const Eina_Matrix4 *mat_a, const Eina_Matrix4 *mat_b);
/**
* @brief Set array to matrix.
* @brief Sets array to matrix.
*
* @param m The result matrix
* @param v The the array[16] for set
@ -751,7 +751,7 @@ EAPI void eina_matrix4_multiply_copy(Eina_Matrix4 *out,
EAPI void eina_matrix4_array_set(Eina_Matrix4 *m, const double *v);
/**
* @brief Copy matrix.
* @brief Copies matrix.
*
* @param dst The matrix copy
* @param src The matrix for copy.
@ -761,7 +761,7 @@ EAPI void eina_matrix4_array_set(Eina_Matrix4 *m, const double *v);
EAPI void eina_matrix4_copy(Eina_Matrix4 *dst, const Eina_Matrix4 *src);
/**
* @brief Multiply two matrix with check
* @brief Multiplies two matrix with check.
*
* @param out The resulting matrix
* @param a The first member of the multiplication
@ -773,7 +773,7 @@ EAPI void eina_matrix4_multiply(Eina_Matrix4 *out, const Eina_Matrix4 *mat_a,
const Eina_Matrix4 *mat_b);
/**
* @brief Set orthogonality matrix
* @brief Sets orthogonality matrix.
*
* @param m The resulting matrix
* @param right The right value
@ -821,7 +821,7 @@ struct _Eina_Matrix2
};
/**
* @brief Set the values of the coefficients of the given floating
* @brief Sets the values of the coefficients of the given floating
* point matrix.
*
* @param m The floating point matrix.
@ -841,7 +841,7 @@ EAPI void eina_matrix2_values_set(Eina_Matrix2 *m, double xx, double xy,
double yx, double yy);
/**
* @brief Get the values of the coefficients of the given floating
* @brief Gets the values of the coefficients of the given floating
* point matrix.
*
* @param m The floating point matrix.
@ -861,7 +861,7 @@ EAPI void eina_matrix2_values_get(const Eina_Matrix2 *m, double *xx, double *xy,
double *yx, double *yy);
/**
* @brief Compute the inverse with check of the given matrix.
* @brief Computes the inverse with check of the given matrix.
*
* @param m The matrix to inverse.
* @param m2 The inverse matrix.
@ -875,7 +875,7 @@ EAPI void eina_matrix2_values_get(const Eina_Matrix2 *m, double *xx, double *xy,
EAPI void eina_matrix2_inverse(Eina_Matrix2 *out, const Eina_Matrix2 *mat);
/**
* @brief Set the given floating point matrix to the identity matrix.
* @brief Sets the given floating point matrix to the identity matrix.
*
* @param m The floating point matrix to set
*
@ -887,9 +887,9 @@ EAPI void eina_matrix2_inverse(Eina_Matrix2 *out, const Eina_Matrix2 *mat);
EAPI void eina_matrix2_identity(Eina_Matrix2 *m);
/**
* @brief Set array to matrix.
* @brief Sets array to matrix.
*
* @param m The rsult matrix
* @param m The result matrix
* @param v The the array[4] for set
*
* Set to matrix first 4 elements from array
@ -899,7 +899,7 @@ EAPI void eina_matrix2_identity(Eina_Matrix2 *m);
EAPI void eina_matrix2_array_set(Eina_Matrix2 *m, const double *v);
/**
* @brief Copy matrix.
* @brief Copies matrix.
*
* @param dst The matrix copy
* @param src The matrix for copy.
@ -909,7 +909,7 @@ EAPI void eina_matrix2_array_set(Eina_Matrix2 *m, const double *v);
EAPI void eina_matrix2_copy(Eina_Matrix2 *dst, const Eina_Matrix2 *src);
/**
* @brief Multiply two matrix
* @brief Multiplies two matrix.
*
* @param out The resulting matrix
* @param a The first member of the multiplication
@ -921,7 +921,7 @@ EAPI void eina_matrix2_multiply(Eina_Matrix2 *out, const Eina_Matrix2 *mat_a,
const Eina_Matrix2 *mat_b);
/**
* @brief Multiply two matrix with check
* @brief Multiplies two matrix with check.
*
* @param out The resulting matrix
* @param a The first member of the multiplication
@ -933,7 +933,7 @@ EAPI void eina_matrix2_multiply_copy(Eina_Matrix2 *out, const Eina_Matrix2 *mat_
const Eina_Matrix2 *mat_b);
/**
* @brief Return the type of the given floating point matrix.
* @brief Returns the type of the given floating point matrix.
*
* @param m The floating point matrix.
* @return The type of the matrix.

138
src/lib/eina/eina_matrixsparse.h
View File

@ -74,20 +74,20 @@ typedef struct _Eina_Matrixsparse_Cell Eina_Matrixsparse_Cell;
/* constructors and destructors */
/**
* @brief Create a new Sparse Matrix.
* @brief Creates a new Sparse Matrix.
*
* @param rows number of rows in matrix. Operations with rows greater than this
* @param rows Number of rows in matrix. Operations with rows greater than this
* value will fail.
* @param cols number of columns in matrix. Operations with columns greater
* @param cols Number of columns in matrix. Operations with columns greater
* than this value will fail.
* @param free_func used to delete cell data contents, used by
* @param free_func Used to delete cell data contents, used by
* eina_matrixsparse_free(), eina_matrixsparse_size_set(),
* eina_matrixsparse_row_idx_clear(),
* eina_matrixsparse_column_idx_clear(),
* eina_matrixsparse_cell_idx_clear() and possible others.
* @param user_data given to @a free_func as first parameter.
* @param user_data Given to @a free_func as first parameter.
*
* @return Newly allocated matrix or @c NULL if allocation failed.
* @return Newly allocated matrix, or @c NULL if allocation failed.
*/
EAPI Eina_Matrixsparse *eina_matrixsparse_new(unsigned long rows,
unsigned long cols,
@ -96,7 +96,7 @@ EAPI Eina_Matrixsparse *eina_matrixsparse_new(unsigned long rows,
const void *user_data);
/**
* @brief Free resources allocated to Sparse Matrix.
* @brief Frees resources allocated to Sparse Matrix.
*
* @param m The Sparse Matrix instance to free, must @b not be @c NULL.
*/
@ -105,15 +105,15 @@ EAPI void eina_matrixsparse_free(Eina_Matrixsparse *m);
/* size manipulation */
/**
* @brief Get the current size of Sparse Matrix.
* @brief Gets the current size of Sparse Matrix.
*
* The given parameters are guaranteed to be set if they're not @c NULL,
* even if this function fails (ie: @a m is not a valid matrix instance).
*
* @param m the sparse matrix to operate on.
* @param rows returns the number of rows, may be @c NULL. If @a m is invalid,
* @param m The sparse matrix to operate on.
* @param rows Returns the number of rows, may be @c NULL. If @a m is invalid,
* returned value is zero, otherwise it's a positive integer.
* @param cols returns the number of columns, may be @c NULL. If @a m is
* @param cols Returns the number of columns, may be @c NULL. If @a m is
* invalid, returned value is zero, otherwise it's a positive integer.
*/
EAPI void eina_matrixsparse_size_get(const Eina_Matrixsparse *m,
@ -121,17 +121,17 @@ EAPI void eina_matrixsparse_size_get(const Eina_Matrixsparse *m,
unsigned long *cols);
/**
* @brief Resize the Sparse Matrix.
* @brief Resizes the Sparse Matrix.
*
* This will resize the sparse matrix, possibly freeing cells on rows
* and columns that will cease to exist.
*
* @param m the sparse matrix to operate on.
* @param rows the new number of rows, must be greater than zero.
* @param cols the new number of columns, must be greater than zero.
* @param m The sparse matrix to operate on.
* @param rows The new number of rows, must be greater than zero.
* @param cols The new number of columns, must be greater than zero.
* @return #EINA_TRUE on success, #EINA_FALSE on failure.
*
* @warning cells, rows or columns are not reference counted and thus
* @warning Cells, rows or columns are not reference counted and thus
* after this call any reference might be invalid if instance were
* freed.
*/
@ -142,12 +142,12 @@ EAPI Eina_Bool eina_matrixsparse_size_set(Eina_Matrixsparse *m,
/* data getting */
/**
* Get the cell reference inside Sparse Matrix.
* @brief Gets the cell reference inside Sparse Matrix.
*
* @param m the sparse matrix to operate on.
* @param row the new number of row to clear.
* @param col the new number of column to clear.
* @param cell pointer to return cell reference, if any exists.
* @param m The sparse matrix to operate on.
* @param row The new number of row to clear.
* @param col The new number of column to clear.
* @param cell Pointer to return cell reference, if any exists.
*
* @return @c 1 on success, @c 0 on failure. It is considered success if did not
* exist but index is inside matrix size, in this case @c *cell == NULL
@ -158,11 +158,11 @@ EAPI Eina_Bool eina_matrixsparse_size_set(Eina_Matrixsparse *m,
EAPI Eina_Bool eina_matrixsparse_cell_idx_get(const Eina_Matrixsparse *m, unsigned long row, unsigned long col, Eina_Matrixsparse_Cell **cell);
/**
* Get data associated with given cell reference.
* @brief Gets data associated with given cell reference.
*
* @param cell given cell reference, must @b not be @c NULL.
* @param cell Given cell reference, must @b not be @c NULL.
*
* @return data associated with given cell.
* @return Data associated with given cell.
*
* @see eina_matrixsparse_cell_idx_get()
* @see eina_matrixsparse_data_idx_get()
@ -170,11 +170,11 @@ EAPI Eina_Bool eina_matrixsparse_cell_idx_get(const Eina_Matrixsparse *m, unsign
EAPI void *eina_matrixsparse_cell_data_get(const Eina_Matrixsparse_Cell *cell);
/**
* Get data associated with given cell given its indexes.
* @brief Gets data associated with given cell given its indexes.
*
* @param m the sparse matrix to operate on.
* @param row the new number of row to clear.
* @param col the new number of column to clear.
* @param m The sparse matrix to operate on.
* @param row The new number of row to clear.
* @param col The new number of column to clear.
*
* @return Data associated with given cell or @c NULL if nothing is associated.
*
@ -184,11 +184,11 @@ EAPI void *eina_matrixsparse_cell_data_get(const Eina_Matrixsparse_Cell *cel
EAPI void *eina_matrixsparse_data_idx_get(const Eina_Matrixsparse *m, unsigned long row, unsigned long col);
/**
* Get position (indexes) of the given cell.
* @brief Gets position (indexes) of the given cell.
*
* @param cell the cell reference, must @b not be @c NULL.
* @param row where to store cell row number, may be @c NULL.
* @param col where to store cell column number, may be @c NULL.
* @param cell The cell reference, must @b not be @c NULL.
* @param row Where to store cell row number, may be @c NULL.
* @param col Where to store cell column number, may be @c NULL.
*
* @return #EINA_TRUE on success, #EINA_FALSE otherwise (@c cell is @c NULL).
*/
@ -197,11 +197,11 @@ EAPI Eina_Bool eina_matrixsparse_cell_position_get(const Eina_Matrixsparse_Cell
/* data setting */
/**
* Change cell reference value without freeing the possibly existing old value.
* @brief Changes cell reference value without freeing the possibly existing old value.
*
* @param cell the cell reference, must @b not be @c NULL.
* @param data new data to set.
* @param p_old returns the old value intact (not freed).
* @param cell The cell reference, must @b not be @c NULL.
* @param data New data to set.
* @param p_old Returns the old value intact (not freed).
*
* @return #EINA_TRUE on success, #EINA_FALSE otherwise (@a cell is @c NULL).
*
@ -211,13 +211,13 @@ EAPI Eina_Bool eina_matrixsparse_cell_position_get(const Eina_Matrixsparse_Cell
EAPI Eina_Bool eina_matrixsparse_cell_data_replace(Eina_Matrixsparse_Cell *cell, const void *data, void **p_old);
/**
* Change cell value freeing the possibly existing old value.
* @brief Changes cell value freeing the possibly existing old value.
*
* In contrast to eina_matrixsparse_cell_data_replace(), this function will
* call @c free_func() on existing value.
*
* @param cell the cell reference, must @b not be @c NULL.
* @param data new data to set.
* @param cell The cell reference, must @b not be @c NULL.
* @param data New data to set.
*
* @return #EINA_TRUE on success, #EINA_FALSE otherwise (@a cell is @c NULL).
*
@ -227,13 +227,13 @@ EAPI Eina_Bool eina_matrixsparse_cell_data_replace(Eina_Matrixsparse_Cell *cell,
EAPI Eina_Bool eina_matrixsparse_cell_data_set(Eina_Matrixsparse_Cell *cell, const void *data);
/**
* Change cell value without freeing the possibly existing old value, using
* @brief Changes cell value without freeing the possibly existing old value, using
* indexes.
*
* @param m the sparse matrix, must @b not be @c NULL.
* @param row the row number to set the value.
* @param col the column number to set the value.
* @param data new data to set.
* @param m The sparse matrix, must @b not be @c NULL.
* @param row The row number to set the value.
* @param col The column number to set the value.
* @param data New data to set.
* @param p_old returns the old value intact (not freed).
*
* @return #EINA_TRUE on success, #EINA_FALSE otherwise (@a m is @c NULL, indexes are not valid).
@ -244,16 +244,16 @@ EAPI Eina_Bool eina_matrixsparse_cell_data_set(Eina_Matrixsparse_Cell *cell, con
EAPI Eina_Bool eina_matrixsparse_data_idx_replace(Eina_Matrixsparse *m, unsigned long row, unsigned long col, const void *data, void **p_old);
/**
* Change cell value freeing the possibly existing old value, using
* @brief Changes cell value freeing the possibly existing old value, using
* indexes.
*
* In contrast to eina_matrixsparse_data_idx_replace(), this function will
* call @c free_func() on existing value.
*
* @param m the sparse matrix, must @b not be @c NULL.
* @param row the row number to set the value.
* @param col the column number to set the value.
* @param data new data to set.
* @param m The sparse matrix, must @b not be @c NULL.
* @param row The row number to set the value.
* @param col The column number to set the value.
* @param data New data to set.
*
* @return #EINA_TRUE on success, #EINA_FALSE otherwise (@a m is @c NULL, indexes are not valid).
*
@ -264,57 +264,57 @@ EAPI Eina_Bool eina_matrixsparse_data_idx_set(Eina_Matrixsparse *m, unsigned lon
/* data deleting */
/**
* Clear (erase all cells) of row given its index.
* @brief Clears (erases all cells) of row given its index.
*
* Existing cells will be cleared with @c free_func() given to
* eina_matrixsparse_new().
*
* @param m the sparse matrix to operate on.
* @param row the new number of row to clear.
* @param m The sparse matrix to operate on.
* @param row The new number of row to clear.
*
* @return #EINA_TRUE on success, #EINA_FALSE on failure. It is considered success if row
* had no cells filled. Failure is asking for clear row outside
* matrix size.
*
* @warning cells, rows or columns are not reference counted and thus
* @warning Cells, rows or columns are not reference counted and thus
* after this call any reference might be invalid if instance were
* freed.
*/
EAPI Eina_Bool eina_matrixsparse_row_idx_clear(Eina_Matrixsparse *m, unsigned long row);
/**
* Clear (erase all cells) of column given its index.
* @brief Clears (erases all cells) of column given its index.
*
* Existing cells will be cleared with @c free_func() given to
* eina_matrixsparse_new().
*
* @param m the sparse matrix to operate on.
* @param col the new number of column to clear.
* @param m The sparse matrix to operate on.
* @param col The new number of column to clear.
*
* @return #EINA_TRUE on success, #EINA_FALSE on failure. It is considered success if column
* had no cells filled. Failure is asking for clear column outside
* matrix size.
*
* @warning cells, rows or columns are not reference counted and thus
* @warning Cells, rows or columns are not reference counted and thus
* after this call any reference might be invalid if instance were
* freed.
*/
EAPI Eina_Bool eina_matrixsparse_column_idx_clear(Eina_Matrixsparse *m, unsigned long col);
/**
* Clear (erase) cell given its indexes.
* @brief Clears (erases) cell given its indexes.
*
* Existing cell will be cleared with @c free_func() given to
* eina_matrixsparse_new().
*
* @param m the sparse matrix to operate on.
* @param row the new number of row to clear.
* @param col the new number of column to clear.
* @param m The sparse matrix to operate on.
* @param row The new number of row to clear.
* @param col The new number of column to clear.
*
* @return #EINA_TRUE on success, #EINA_FALSE on failure. It is considered success if did not
* exist but index is inside matrix size.
*
* @warning cells, rows or columns are not reference counted and thus
* @warning Cells, rows or columns are not reference counted and thus
* after this call any reference might be invalid if instance were
* freed.
*
@ -324,13 +324,13 @@ EAPI Eina_Bool eina_matrixsparse_column_idx_clear(Eina_Matrixsparse *m, unsigned
EAPI Eina_Bool eina_matrixsparse_cell_idx_clear(Eina_Matrixsparse *m, unsigned long row, unsigned long col);
/**
* Clear (erase) cell given its reference.
* @brief Clears (erases) cell given its reference.
*
* @param cell the cell reference, must @b not be @c NULL.
* @param cell The cell reference, must @b not be @c NULL.
*
* @return #EINA_TRUE on success, #EINA_FALSE on failure.
*
* @warning cells, rows or columns are not reference counted and thus
* @warning Cells, rows or columns are not reference counted and thus
* after this call any reference might be invalid if instance were
* freed.
*
@ -342,7 +342,7 @@ EAPI Eina_Bool eina_matrixsparse_cell_clear(Eina_Matrixsparse_Cell *cell);
/* iterators */
/**
* Creates a new iterator over existing matrix cells.
* @brief Creates a new iterator over existing matrix cells.
*
* This is a cheap walk, it will just report existing cells and holes
* in the sparse matrix will be ignored. That means the reported
@ -355,14 +355,14 @@ EAPI Eina_Bool eina_matrixsparse_cell_clear(Eina_Matrixsparse_Cell *cell);
* @param m The Sparse Matrix reference, must @b not be @c NULL.
* @return A new iterator.
*
* @warning if the matrix structure changes then the iterator becomes
* @warning If the matrix structure changes then the iterator becomes
* invalid! That is, if you add or remove cells this iterator
* behavior is undefined and your program may crash!
*/
EAPI Eina_Iterator *eina_matrixsparse_iterator_new(const Eina_Matrixsparse *m);
/**
* Creates a new iterator over all matrix cells.
* @brief Creates a new iterator over all matrix cells.
*
* Unlike eina_matrixsparse_iterator_new() this one will report all
* matrix cells, even those that are still empty (holes). These will
@ -381,7 +381,7 @@ EAPI Eina_Iterator *eina_matrixsparse_iterator_new(const Eina_Matrixsparse *m);
* @param m The Sparse Matrix reference, must @b not be @c NULL.
* @return A new iterator.
*
* @warning if the matrix structure changes then the iterator becomes
* @warning If the matrix structure changes then the iterator becomes
* invalid! That is, if you add or remove cells this iterator
* behavior is undefined and your program may crash!
*/

10
src/lib/eina/eina_mempool.h
View File

@ -125,7 +125,7 @@ static inline void *eina_mempool_realloc(Eina_Mempool *mp, void *element, unsign
static inline void *eina_mempool_malloc(Eina_Mempool *mp, unsigned int size) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
/**
* @brief Allocate and zero memory using the given mempool.
* @brief Allocates and zeros memory using the given mempool.
*
* @param[in] mp The mempool
* @param[in] size The size in bytes to allocate
@ -142,7 +142,7 @@ static inline void *eina_mempool_malloc(Eina_Mempool *mp, unsigned int size) EIN
static inline void *eina_mempool_calloc(Eina_Mempool *mp, unsigned int size) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
/**
* @brief Free resources previously allocated by the given mempool.
* @brief Frees resources previously allocated by the given mempool.
*
* @param[in] mp The mempool
* @param[in] element The data to free
@ -172,14 +172,14 @@ static inline void eina_mempool_free(Eina_Mempool *mp, void *element) EINA_ARG_
EAPI void eina_mempool_repack(Eina_Mempool *mp, Eina_Mempool_Repack_Cb cb, void *data) EINA_ARG_NONNULL(1, 2);
/**
* @brief Run a garbage collection cycle.
* @brief Runs a garbage collection cycle.
*
* @param[in] mp The mempool
*/
EAPI void eina_mempool_gc(Eina_Mempool *mp) EINA_ARG_NONNULL(1);
/**
* @brief Have the backend update its internal statistics.
* @brief Has the backend update its internal statistics.
*
* @param[in] mp The mempool
*
@ -203,7 +203,7 @@ EAPI Eina_Bool eina_mempool_register(Eina_Mempool_Backend *be) EINA_ARG_NON
EAPI void eina_mempool_unregister(Eina_Mempool_Backend *be) EINA_ARG_NONNULL(1);
/**
* @brief Computers the alignment that would be used when allocating a object of size @p size.
* @brief Computes the alignment that would be used when allocating a object of size @p size.
*
* @param[in] size
* @return The alignment for an allocation of size @p size.

6
src/lib/eina/eina_mmap.h
View File

@ -5,7 +5,7 @@
* @addtogroup Eina_Mmap_Group Mmap Group
* @ingroup Eina
*
* @brief These functions provide helpers for safe mmap handling
* @brief These functions provide helpers for safe mmap handling.
*
* @{
*
@ -13,7 +13,7 @@
*/
/**
* @brief Enable or disable safe mmaped IO handling
* @brief Enables or disables safe mmaped IO handling.
*
* @param enabled The enabled state (to enable, pass #EINA_TRUE)
* @return #EINA_TRUE on success, #EINA_FALSE on failure.
@ -43,7 +43,7 @@ EAPI Eina_Bool
eina_mmap_safety_enabled_set(Eina_Bool enabled);
/**
* @brief Get the enabled state of mmap safety.
* @brief Gets the enabled state of mmap safety.
*
* @return The safety state (#EINA_TRUE if enabled)
*

32
src/lib/eina/eina_module.h
View File

@ -110,7 +110,7 @@ extern EAPI Eina_Error EINA_ERROR_WRONG_MODULE;
extern EAPI Eina_Error EINA_ERROR_MODULE_INIT_FAILED;
/**
* @brief Return a new module.
* @brief Returns a new module.
*
* @param file The name of the file module to load.
* @return A new module. If @p file is @c NULL, or if it does not exist,
@ -127,7 +127,7 @@ EAPI Eina_Module *
eina_module_new(const char *file) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
/**
* @brief Delete a module.
* @brief Deletes a module.
*
* @param module The module to delete.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
@ -141,7 +141,7 @@ EAPI Eina_Bool
eina_module_free(Eina_Module *module) EINA_ARG_NONNULL(1);
/**
* @brief Load a module.
* @brief Loads a module.
*
* @param module The module to load.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
@ -162,7 +162,7 @@ EAPI Eina_Bool
eina_module_load(Eina_Module *module) EINA_ARG_NONNULL(1);
/**
* @brief Unload a module.
* @brief Unloads a module.
*
* @param module The module to load.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
@ -171,7 +171,7 @@ EAPI Eina_Bool
* loaded by eina_module_load(). If the reference counter of @p module is
* strictly greater than @c 1, #EINA_FALSE is returned. Otherwise, the
* shared object file is closed and if it is a internal Eina module, it
* is shutted down just before. In that case, #EINA_TRUE is
* is shut down just before. In that case, #EINA_TRUE is
* returned. In all case, the reference counter is decreased. If @p module
* is @c NULL, the function returns immediately #EINA_FALSE.
*/
@ -179,7 +179,7 @@ EAPI Eina_Bool
eina_module_unload(Eina_Module *module) EINA_ARG_NONNULL(1);
/**
* @brief Retrieve the data associated to a symbol.
* @brief Retrieves the data associated to a symbol.
*
* @param module The module.
* @param symbol The symbol.
@ -194,7 +194,7 @@ EAPI void *
eina_module_symbol_get(const Eina_Module *module, const char *symbol) EINA_PURE EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT;
/**
* @brief Return the file name associated to the module.
* @brief Returns the file name associated to the module.
*
* @param module The module.
* @return The file name.
@ -207,7 +207,7 @@ EAPI const char *
eina_module_file_get(const Eina_Module *module) EINA_PURE EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
/**
* @brief Define if on module load we should expose all symbol
* @brief Defines if on module load we should expose all symbol
*
* @param module The module to turn off/on symbol to be exposed
* @since 1.11
@ -215,7 +215,7 @@ EAPI const char *
EAPI void eina_module_symbol_global_set(Eina_Module *module, Eina_Bool global) EINA_ARG_NONNULL(1);
/**
* @brief Return the path built from the location of a library and a
* @brief Returns the path built from the location of a library and a
* given sub directory.
*
* @param symbol The symbol to search for.
@ -232,7 +232,7 @@ EAPI char *
eina_module_symbol_path_get(const void *symbol, const char *sub_dir) EINA_PURE EINA_MALLOC EINA_ARG_NONNULL(1, 2);
/**
* @brief Return the path built from the value of an environment variable and a
* @brief Returns the path built from the value of an environment variable and a
* given sub directory.
*
* @param env The environment variable to expand.
@ -250,7 +250,7 @@ EAPI char *
/**
* @brief Get an array of modules found on the directory path matching an arch type.
* @brief Gets an array of modules found on the directory path matching an arch type.
*
* @param array The array that stores the list of the modules.
* @param path The directory's path to search for modules.
@ -266,7 +266,7 @@ EAPI Eina_Array *
eina_module_arch_list_get(Eina_Array *array, const char *path, const char *arch);
/**
* @brief Get a list of modules found on the directory path.
* @brief Gets a list of modules found on the directory path.
*
* @param array The array that stores the list of the modules.
* @param path The directory's path to search for modules.
@ -288,7 +288,7 @@ EAPI Eina_Array *
eina_module_list_get(Eina_Array *array, const char *path, Eina_Bool recursive, Eina_Module_Cb cb, void *data) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
/**
* @brief Load every module on the list of modules.
* @brief Loads every module on the list of modules.
*
* @param array The array of modules to load.
*
@ -299,7 +299,7 @@ EAPI void
eina_module_list_load(Eina_Array *array) EINA_ARG_NONNULL(1);
/**
* @brief Unload every module on the list of modules.
* @brief Unloads every module on the list of modules.
*
* @param array The array of modules to unload.
*
@ -310,7 +310,7 @@ EAPI void
eina_module_list_unload(Eina_Array *array) EINA_ARG_NONNULL(1);
/**
* @p Free every module on the list of modules.
* @p Frees every module on the list of modules.
*
* @param array The array of modules to free.
*
@ -321,7 +321,7 @@ EAPI void
eina_module_list_free(Eina_Array *array) EINA_ARG_NONNULL(1);
/**
* @brief Find an module in array.
* @brief Finds an module in array.
*
* @param array The array to find the module.
* @param module The name of module to be searched.

2
src/lib/eina/eina_prefix.h
View File

@ -15,7 +15,7 @@
/**
* @typedef Eina_Prefix
* @brief An opaque type for prefix handle
* @brief An opaque type for prefix handle.
* @details This is a prefix object that is returned by eina_prefix_new() when trying
* to determine the runtime location of the software in question so that other
* data files such as images, sound files, other executable utilities,

2
src/lib/eina/eina_quad.h
View File

@ -34,7 +34,7 @@
/**
* @defgroup Eina_Quad_Group Quadrangles
*
* @brief Quadrangles operations
* @brief Quadrangles operations.
*
* @{
*/

14
src/lib/eina/eina_rbtree.h
View File

@ -149,9 +149,9 @@ typedef void (*Eina_Rbtree_Free_Cb)(Eina_Rbtree *node, void *data);
/**
* @brief Insert a new node inside an existing red black tree.
* @brief Inserts a new node inside an existing red black tree.
*
* @param root The root of an exisiting valid red black tree.
* @param root The root of an existing valid red black tree.
* @param node The new node to insert.
* @param cmp The callback that is able to compare two nodes.
* @param data Private data to help the compare function.
@ -164,7 +164,7 @@ typedef void (*Eina_Rbtree_Free_Cb)(Eina_Rbtree *node, void *data);
EAPI Eina_Rbtree *eina_rbtree_inline_insert(Eina_Rbtree *root, Eina_Rbtree *node, Eina_Rbtree_Cmp_Node_Cb cmp, const void *data) EINA_ARG_NONNULL(2, 3) EINA_WARN_UNUSED_RESULT;
/**
* @brief Remove a node from an existing red black tree.
* @brief Removes a node from an existing red black tree.
*
* @param root The root of a valid red black tree.
* @param node The node to remove from the tree.
@ -179,7 +179,7 @@ EAPI Eina_Rbtree *eina_rbtree_inline_insert(Eina_Rbtree *root, Eina_Rbt
EAPI Eina_Rbtree *eina_rbtree_inline_remove(Eina_Rbtree *root, Eina_Rbtree *node, Eina_Rbtree_Cmp_Node_Cb cmp, const void *data) EINA_ARG_NONNULL(2, 3) EINA_WARN_UNUSED_RESULT;
/**
* @brief Delete all nodes from a valid red black tree.
* @brief Deletes all nodes from a valid red black tree.
*
* @param root The root of a valid red black tree.
* @param func The callback that will free each node.
@ -192,7 +192,7 @@ static inline Eina_Rbtree *eina_rbtree_inline_lookup(const Eina_Rbtree *root, co
/**
* @brief Returned a new prefix iterator associated to a rbtree.
* @brief Returns a new prefix iterator associated to a rbtree.
*
* @param root The root of rbtree.
* @return A new iterator.
@ -212,7 +212,7 @@ static inline Eina_Rbtree *eina_rbtree_inline_lookup(const Eina_Rbtree *root, co
EAPI Eina_Iterator *eina_rbtree_iterator_prefix(const Eina_Rbtree *root) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
/**
* @brief Returned a new prefix iterator associated to a rbtree.
* @brief Returns a new prefix iterator associated to a rbtree.
*
* @param root The root of rbtree.
* @return A new iterator.
@ -232,7 +232,7 @@ EAPI Eina_Iterator *eina_rbtree_iterator_prefix(const Eina_Rbtree *root)
EAPI Eina_Iterator *eina_rbtree_iterator_infix(const Eina_Rbtree *root) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
/**
* @brief Returned a new prefix iterator associated to a rbtree.
* @brief Returns a new prefix iterator associated to a rbtree.
*
* @param root The root of rbtree.
* @return A new iterator.

68
src/lib/eina/eina_rectangle.h
View File

@ -68,10 +68,10 @@ typedef struct _Eina_Rectangle_Pool Eina_Rectangle_Pool;
*/
typedef enum {
Eina_Packing_Descending, /**< Current */
Eina_Packing_Ascending, /**< sorting in assending order */
Eina_Packing_Bottom_Left, /**< sorting in bottemleft fasion */
Eina_Packing_Bottom_Left_Skyline, /**< bottemleft skyline */
Eina_Packing_Bottom_Left_Skyline_Improved /**< optimized bottemleft skyline */
Eina_Packing_Ascending, /**< sorting in ascending order */
Eina_Packing_Bottom_Left, /**< sorting in bottom left fashion */
Eina_Packing_Bottom_Left_Skyline, /**< bottom left skyline */
Eina_Packing_Bottom_Left_Skyline_Improved /**< optimized bottom left skyline */
} Eina_Rectangle_Packing;
/**
@ -88,7 +88,7 @@ typedef enum {
/**
* @brief Check if the given spans intersect.
* @brief Checks if the given spans intersect.
*
* @param c1 The column of the first span.
* @param l1 The length of the first span.
@ -102,7 +102,7 @@ typedef enum {
static inline int eina_spans_intersect(int c1, int l1, int c2, int l2) EINA_WARN_UNUSED_RESULT;
/**
* @brief Check if the given rectangle is empty.
* @brief Checks if the given rectangle is empty.
*
* @param r The rectangle to check.
* @return #EINA_TRUE if the rectangle is empty, #EINA_FALSE otherwise.
@ -114,7 +114,7 @@ static inline int eina_spans_intersect(int c1, int l1, int c2, int l2) E
static inline Eina_Bool eina_rectangle_is_empty(const Eina_Rectangle *r) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
/**
* @brief Set the coordinates and size of the given rectangle.
* @brief Sets the coordinates and size of the given rectangle.
*
* @param r The rectangle.
* @param x The top-left x coordinate of the rectangle.
@ -129,7 +129,7 @@ static inline Eina_Bool eina_rectangle_is_empty(const Eina_Rectangle *r) EINA_
static inline void eina_rectangle_coords_from(Eina_Rectangle *r, int x, int y, int w, int h) EINA_ARG_NONNULL(1);
/**
* @brief Check if the given rectangles intersect.
* @brief Checks if the given rectangles intersect.
*
* @param r1 The first rectangle.
* @param r2 The second rectangle.
@ -142,7 +142,7 @@ static inline void eina_rectangle_coords_from(Eina_Rectangle *r, int x, i
static inline Eina_Bool eina_rectangles_intersect(const Eina_Rectangle *r1, const Eina_Rectangle *r2) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT;
/**
* @brief Check if the given x-coordinate is in the rectangle .
* @brief Checks if the given x-coordinate is in the rectangle .
*
* @param r The rectangle.
* @param x The x coordinate.
@ -155,7 +155,7 @@ static inline Eina_Bool eina_rectangles_intersect(const Eina_Rectangle *r1, co
static inline Eina_Bool eina_rectangle_xcoord_inside(const Eina_Rectangle *r, int x) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
/**
* @brief Check if the given y-coordinate is in the rectangle .
* @brief Checks if the given y-coordinate is in the rectangle .
*
* @param r The rectangle.
* @param y The y coordinate.
@ -168,7 +168,7 @@ static inline Eina_Bool eina_rectangle_xcoord_inside(const Eina_Rectangle *r,
static inline Eina_Bool eina_rectangle_ycoord_inside(const Eina_Rectangle *r, int y) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
/**
* @brief Check if the given point is in the rectangle .
* @brief Checks if the given point is in the rectangle .
*
* @param r The rectangle.
* @param x The x coordinate of the point.
@ -182,7 +182,7 @@ static inline Eina_Bool eina_rectangle_ycoord_inside(const Eina_Rectangle *r,
static inline Eina_Bool eina_rectangle_coords_inside(const Eina_Rectangle *r, int x, int y) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
/**
* @brief Get the union of two rectangles.
* @brief Gets the union of two rectangles.
*
* @param dst The first rectangle.
* @param src The second rectangle.
@ -194,7 +194,7 @@ static inline Eina_Bool eina_rectangle_coords_inside(const Eina_Rectangle *r,
static inline void eina_rectangle_union(Eina_Rectangle *dst, const Eina_Rectangle *src) EINA_ARG_NONNULL(1, 2);
/**
* @brief Get the intersection of two rectangles.
* @brief Gets the intersection of two rectangles.
*
* @param dst The first rectangle.
* @param src The second rectangle.
@ -245,10 +245,10 @@ static inline Eina_Bool eina_rectangle_is_valid(const Eina_Rectangle *r) EINA_
* @brief Gives the rectangle maximum x coordinate.
*
* @param thiz The rectangle
* @return the maximum x coordinate
* @return The maximum x coordinate
*
* This function calculates the maximum x coordinate of the rectangle by summing
* the @p width with the current @p x coodinate of the rectangle.
* the @p width with the current @p x coordinate of the rectangle.
*/
static inline int eina_rectangle_max_x(Eina_Rectangle *thiz) EINA_ARG_NONNULL(1);
@ -257,7 +257,7 @@ static inline int eina_rectangle_max_x(Eina_Rectangle *thiz) EINA_ARG_NO
* @brief Gives the rectangle maximum y coordinate.
*
* @param thiz The rectangle
* @return the maximum y coordinate
* @return The maximum y coordinate
*
* This function calculates the maximum y coordinate of the rectangle by summing
* the @p height with the current @p y coodinate of the rectangle.
@ -266,7 +266,7 @@ static inline int eina_rectangle_max_y(Eina_Rectangle *thiz) EINA_ARG_NO
/**
*
* @brief Slices a rectangle vertically into two subrectangles starting from left edge
* @brief Slices a rectangle vertically into two subrectangles starting from left edge.
*
* @param thiz The rectangle to slice
* @param slice The sliced part of the rectangle
@ -340,7 +340,7 @@ static inline Eina_Bool eina_rectangle_width_cut(Eina_Rectangle *thiz, Eina_Re
static inline Eina_Bool eina_rectangle_height_cut(Eina_Rectangle *thiz, Eina_Rectangle *slice, Eina_Rectangle *remainder, int amount) EINA_ARG_NONNULL(1);
/**
* @brief Subtract two rectangles.
* @brief Subtracts two rectangles.
*
* @param thiz The minuend rectangle
* @param other The subtrahend rectangle
@ -352,7 +352,7 @@ static inline Eina_Bool eina_rectangle_height_cut(Eina_Rectangle *thiz, Eina_R
static inline Eina_Bool eina_rectangle_subtract(Eina_Rectangle *thiz, Eina_Rectangle *other, Eina_Rectangle out[4]) EINA_ARG_NONNULL(1);
/**
* @brief Add a rectangle in a new pool.
* @brief Adds a rectangle in a new pool.
*
* @param w The width of the rectangle.
* @param h The height of the rectangle.
@ -365,7 +365,7 @@ static inline Eina_Bool eina_rectangle_subtract(Eina_Rectangle *thiz, Eina_Rec
EAPI Eina_Rectangle_Pool *eina_rectangle_pool_new(int w, int h) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
/**
* @brief Return the pool of the given rectangle.
* @brief Returns the pool of the given rectangle.
*
* @param rect The rectangle.
* @return The pool of the given rectangle.
@ -376,7 +376,7 @@ EAPI Eina_Rectangle_Pool *eina_rectangle_pool_new(int w, int h) EINA_MALLOC EINA
EAPI Eina_Rectangle_Pool *eina_rectangle_pool_get(Eina_Rectangle *rect) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
/**
* @brief Return the width and height of the given pool.
* @brief Returns the width and height of the given pool.
*
* @param pool The pool.
* @param w The returned width.
@ -391,7 +391,7 @@ EAPI Eina_Rectangle_Pool *eina_rectangle_pool_get(Eina_Rectangle *rect) EINA_WAR
EAPI Eina_Bool eina_rectangle_pool_geometry_get(Eina_Rectangle_Pool *pool, int *w, int *h) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
/**
* @brief Get the data from the given pool.
* @brief Gets the data from the given pool.
*
* @param pool The pool.
* @return The returned data.
@ -403,7 +403,7 @@ EAPI Eina_Bool eina_rectangle_pool_geometry_get(Eina_Rectangle_Pool *
EAPI void *eina_rectangle_pool_data_get(Eina_Rectangle_Pool *pool) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
/**
* @brief Set the data to the given pool.
* @brief Sets the data to the given pool.
*
* @param pool The pool.
* @param data The data to set.
@ -414,7 +414,7 @@ EAPI void *eina_rectangle_pool_data_get(Eina_Rectangle_Pool *pool
EAPI void eina_rectangle_pool_data_set(Eina_Rectangle_Pool *pool, const void *data) EINA_ARG_NONNULL(1);
/**
* @brief Free the given pool.
* @brief Frees the given pool.
*
* @param pool The pool to free.
*
@ -424,7 +424,7 @@ EAPI void eina_rectangle_pool_data_set(Eina_Rectangle_Pool *pool
EAPI void eina_rectangle_pool_free(Eina_Rectangle_Pool *pool) EINA_ARG_NONNULL(1);
/**
* @brief Return the number of rectangles in the given pool.
* @brief Returns the number of rectangles in the given pool.
*
* @param pool The pool.
* @return The number of rectangles in the pool.
@ -434,7 +434,7 @@ EAPI void eina_rectangle_pool_free(Eina_Rectangle_Pool *pool) EI
EAPI int eina_rectangle_pool_count(Eina_Rectangle_Pool *pool) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
/**
* @brief Request a rectangle of given size in the given pool.
* @brief Requests a rectangle of given size in the given pool.
*
* @param pool The pool.
* @param w The width of the rectangle to request.
@ -451,7 +451,7 @@ EAPI int eina_rectangle_pool_count(Eina_Rectangle_Pool *pool) E
EAPI Eina_Rectangle *eina_rectangle_pool_request(Eina_Rectangle_Pool *pool, int w, int h) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
/**
* @brief Remove the given rectangle from the pool.
* @brief Removes the given rectangle from the pool.
*
* @param rect The rectangle to remove from the pool.
*
@ -463,7 +463,7 @@ EAPI void eina_rectangle_pool_release(Eina_Rectangle *rect) EINA
/**
* @def EINA_RECTANGLE_SET
* @brief Macro to set the values of a #Eina_Rectangle.
* @brief Definition for the macro to set the values of a #Eina_Rectangle.
*
* @param Rectangle The rectangle to set the values.
* @param X The X coordinate of the top left corner of the rectangle.
@ -485,7 +485,7 @@ EAPI void eina_rectangle_pool_release(Eina_Rectangle *rect) EINA
/**
* @brief Create a new rectangle.
* @brief Creates a new rectangle.
*
* @param x The X coordinate of the top left corner of the rectangle.
* @param y The Y coordinate of the top left corner of the rectangle.
@ -496,12 +496,12 @@ EAPI void eina_rectangle_pool_release(Eina_Rectangle *rect) EINA
* This function creates a rectangle which top left corner has the
* coordinates (@p x, @p y), with height @p w and height @p h and adds
* it to the rectangles pool. No check is done on @p w and @p h. This
* function returns a new rectangle on success, @c NULL otherwhise.
* function returns a new rectangle on success, @c NULL otherwise.
*/
EAPI Eina_Rectangle *eina_rectangle_new(int x, int y, int w, int h) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
/**
* @brief Free the given rectangle.
* @brief Frees the given rectangle.
*
* @param rect The rectangle to free.
*
@ -521,10 +521,10 @@ EAPI void eina_rectangle_free(Eina_Rectangle *rect) EINA_ARG_NONNULL(
EAPI void eina_rectangle_pool_packing_set(Eina_Rectangle_Pool *pool,Eina_Rectangle_Packing type) EINA_ARG_NONNULL(1);
/**
* @brief calculate where rect2 is outside of rect1
* @brief calculates where rect2 is outside of rect1.
*
* @param rect1 the rect to use as anchor
* @param rect2 the rect to look for outside positions
* @param rect1 The rect to use as anchor
* @param rect2 The rect to look for outside positions
*
* @return A or'ed map of Eina_Rectangle_Outside values
* @since 1.19

112
src/lib/eina/eina_simple_xml_parser.h
View File

@ -219,14 +219,14 @@ typedef Eina_Bool (*Eina_Simple_XML_Attribute_Cb)(void *data, const char *key, c
/**
* Parse a section of XML string text
* @brief Parses a section of XML string text
*
* @param buf the input string. May not contain \0 terminator.
* @param buflen the input string size.
* @param strip whenever this parser should strip leading and trailing
* @param buf The input string. May not contain \0 terminator.
* @param buflen The input string size.
* @param strip Whenever this parser should strip leading and trailing
* whitespace. These whitespace will still be issued, but as type
* #EINA_SIMPLE_XML_IGNORED.
* @param func what to call back while parse to do some action. The
* @param func What to call back while parse to do some action. The
* first parameter is the given user @a data, the second is the
* token type, the third is the pointer to content start (it's
* not a NULL terminated string!), the forth is where this
@ -234,9 +234,9 @@ typedef Eina_Bool (*Eina_Simple_XML_Attribute_Cb)(void *data, const char *key, c
* start, for instance "<!DOCTYPE value>" the offset points at
* "value"), the fifth is the size of the content. Whenever this
* function return #EINA_FALSE the parser will abort.
* @param data what to give as context to @a func.
* @param data What to give as context to @a func.
*
* @return #EINA_TRUE on success or #EINA_FALSE if it was aborted by user or
* @return #EINA_TRUE on success, or #EINA_FALSE if it was aborted by user or
* parsing error.
*/
EAPI Eina_Bool eina_simple_xml_parse(const char *buf, unsigned buflen,
@ -245,11 +245,11 @@ EAPI Eina_Bool eina_simple_xml_parse(const char *buf, unsigned buflen,
/**
* Given the contents of a tag, find where the attributes start.
* @brief Given the contents of a tag, find where the attributes start.
*
* @param buf the input string. May not contain \0 terminator.
* @param buflen the input string size.
* @return pointer to the start of attributes, it can be used
* @param buf The input string. May not contain \0 terminator.
* @param buflen The input string size.
* @return Pointer to the start of attributes, it can be used
* to feed eina_simple_xml_attributes_parse(). @c NULL is returned
* if no attributes were found.
*
@ -260,25 +260,25 @@ EAPI Eina_Bool eina_simple_xml_parse(const char *buf, unsigned buflen,
EAPI const char * eina_simple_xml_tag_attributes_find(const char *buf, unsigned buflen);
/**
* Given a buffer with xml attributes, parse them to key=value pairs.
* @brief Given a buffer with xml attributes, parse them to key=value pairs.
*
* @param buf the input string. May not contain \0 terminator.
* @param buflen the input string size.
* @param func what to call back while parse to do some action. The
* @param buf The input string. May not contain \0 terminator.
* @param buflen The input string size.
* @param func What to call back while parse to do some action. The
* first parameter is the given user @a data, the second is the
* key (null-terminated) and the last is the value (null
* terminated). These strings should not be modified and
* reference is just valid until the function return.
* @param data data to pass to the callback function.
* @param data Data to pass to the callback function.
*
* @return #EINA_TRUE on success or #EINA_FALSE if it was aborted by user or
* @return #EINA_TRUE on success, or #EINA_FALSE if it was aborted by user or
* parsing error.
*/
EAPI Eina_Bool eina_simple_xml_attributes_parse(const char *buf, unsigned buflen,
Eina_Simple_XML_Attribute_Cb func, const void *data);
/**
* Given a buffer with the xml value of an attributes, parse them to key:value pairs.
* @brief Given a buffer with the xml value of an attributes, parse them to key:value pairs.
*
* @param buf the input string. Need to contain \0 terminator.
* @param func what to call back while parse to do some action. The
@ -297,9 +297,9 @@ EAPI Eina_Bool
eina_simple_xml_attribute_w3c_parse(const char *buf, Eina_Simple_XML_Attribute_Cb func, const void *data);
/**
* Create (and append) new attribute to tag.
* @brief Creates (and appends) new attribute to tag.
*
* @param parent if provided, will be set in the resulting structure
* @param parent If provided, will be set in the resulting structure
* as well as the attribute will be appended to attributes list.
* @param key Null-terminated string. Must not be @c NULL.
* @param value Null-terminated string. If @c NULL, the empty string will be used.
@ -311,7 +311,7 @@ eina_simple_xml_attribute_w3c_parse(const char *buf, Eina_Simple_XML_Attribute_C
EAPI Eina_Simple_XML_Attribute * eina_simple_xml_attribute_new(Eina_Simple_XML_Node_Tag *parent, const char *key, const char *value);
/**
* Remove attribute from parent and delete it.
* @brief Removes attribute from parent and delete it.
*
* @param attr attribute to release memory.
*/
@ -319,9 +319,9 @@ EAPI void eina_simple_xml_attribute_free(Eina_Simple_XML_Attribute *attr);
/**
* Create new tag. If parent is provided, it is automatically appended.
* @brief Creates new tag. If parent is provided, it is automatically appended.
*
* @param parent if provided, will be set in the resulting structure
* @param parent If provided, will be set in the resulting structure
* as well as the tag will be appended to children list.
* @param name Null-terminated string. Must not be @c NULL.
*
@ -332,7 +332,7 @@ EAPI void eina_simple_xml_attribute_free(Eina_Simple_XML_Attribute *attr);
EAPI Eina_Simple_XML_Node_Tag * eina_simple_xml_node_tag_new(Eina_Simple_XML_Node_Tag *parent, const char *name);
/**
* Remove tag from parent and delete it.
* @brief Removes tag from parent and delete it.
*
* @param tag to release memory.
*/
@ -340,12 +340,12 @@ EAPI void eina_simple_xml_node_tag_free(Eina_Simple_XML_Node_Tag *tag);
/**
* Create new data. If parent is provided, it is automatically appended.
* @brief Creates new data. If parent is provided, it is automatically appended.
*
* @param parent if provided, will be set in the resulting structure
* @param parent If provided, will be set in the resulting structure
* as well as the data will be appended to children list.
* @param contents String to be used. Must not be @c NULL.
* @param length size in bytes of @a contents.
* @param length Size in bytes of @a contents.
*
* @return Newly allocated memory or NULL on error. This memory should be
* released with eina_simple_xml_node_data_free() or indirectly
@ -354,7 +354,7 @@ EAPI void eina_simple_xml_node_tag_free(Eina_Simple_XML_Node_Tag *tag);
EAPI Eina_Simple_XML_Node_Data * eina_simple_xml_node_data_new(Eina_Simple_XML_Node_Tag *parent, const char *contents, size_t length);
/**
* Remove data from parent and delete it.
* @brief Removes data from parent and delete it.
*
* @param node to release memory.
*/
@ -362,12 +362,12 @@ EAPI void eina_simple_xml_node_data_free(Eina_Simple_XML_Node_Data *node);
/**
* Create new cdata. If parent is provided, it is automatically appended.
* @brief Creates new cdata. If parent is provided, it is automatically appended.
*
* @param parent if provided, will be set in the resulting structure
* @param parent If provided, will be set in the resulting structure
* as well as the cdata will be appended to children list.
* @param contents String to be used. Must not be @c NULL.
* @param length size in bytes of @a content.
* @param length Size in bytes of @a content.
*
* @return Newly allocated memory or @c NULL on error. This memory should be
* released with eina_simple_xml_node_cdata_free() or indirectly
@ -376,7 +376,7 @@ EAPI void eina_simple_xml_node_data_free(Eina_Simple_XML_Node_Data *node);
EAPI Eina_Simple_XML_Node_CData * eina_simple_xml_node_cdata_new(Eina_Simple_XML_Node_Tag *parent, const char *contents, size_t length);
/**
* Remove cdata from parent and delete it.
* @brief Removes cdata from parent and delete it.
*
* @param node to release memory.
*/
@ -384,9 +384,9 @@ EAPI void eina_simple_xml_node_cdata_free(Eina_Simple_XML_Node_Data *node);
/**
* Create new doctype child. If parent is provided, it is automatically appended.
* @brief Creates new doctype child. If parent is provided, it is automatically appended.
*
* @param parent if provided, will be set in the resulting structure
* @param parent If provided, will be set in the resulting structure
* as well as the doctype child will be appended to children list.
* @param contents String to be used. Must not be @c NULL.
* @param length size in bytes of @a content.
@ -400,7 +400,7 @@ EAPI void eina_simple_xml_node_cdata_free(Eina_Simple_XML_Node_Data *node);
EAPI Eina_Simple_XML_Node_Doctype_Child * eina_simple_xml_node_doctype_child_new(Eina_Simple_XML_Node_Tag *parent, const char *contents, size_t length);
/**
* Remove doctype child from parent and delete it.
* @brief Removes doctype child from parent and delete it.
*
* @param node to release memory.
*
@ -410,12 +410,12 @@ EAPI void eina_simple_xml_node_doctype_child_free(Eina_Simple_XML_Node_Data *nod
/**
* Create new processing. If parent is provided, it is automatically appended.
* @brief Creates new processing. If parent is provided, it is automatically appended.
*
* @param parent if provided, will be set in the resulting structure
* @param parent If provided, will be set in the resulting structure
* as well as the processing will be appended to children list.
* @param contents String to be used. Must not be @c NULL.
* @param length size in bytes of @a contents.
* @param length Size in bytes of @a contents.
*
* @return Newly allocated memory or @c NULL on error. This memory should be
* released with eina_simple_xml_node_processing_free() or indirectly
@ -424,7 +424,7 @@ EAPI void eina_simple_xml_node_doctype_child_free(Eina_Simple_XML_Node_Data *nod
EAPI Eina_Simple_XML_Node_Processing * eina_simple_xml_node_processing_new(Eina_Simple_XML_Node_Tag *parent, const char *contents, size_t length);
/**
* Remove processing from parent and delete it.
* @brief Removes processing from parent and delete it.
*
* @param node processing to release memory.
*/
@ -432,12 +432,12 @@ EAPI void eina_simple_xml_node_processing_free(Eina_Simple_XML_Node_Data *node);
/**
* Create new doctype. If parent is provided, it is automatically appended.
* @brief Creates new doctype. If parent is provided, it is automatically appended.
*
* @param parent if provided, will be set in the resulting structure
* @param parent If provided, will be set in the resulting structure
* as well as the doctype will be appended to children list.
* @param contents String to be used. Must not be @c NULL.
* @param length size in bytes of @a contents.
* @param length Size in bytes of @a contents.
*
* @return Newly allocated memory or @c NULL on error. This memory should be
* released with eina_simple_xml_node_doctype_free() or indirectly
@ -446,7 +446,7 @@ EAPI void eina_simple_xml_node_processing_free(Eina_Simple_XML_Node_Data *node);
EAPI Eina_Simple_XML_Node_Doctype * eina_simple_xml_node_doctype_new(Eina_Simple_XML_Node_Tag *parent, const char *contents, size_t length);
/**
* Remove doctype from parent and delete it.
* @brief Removes doctype from parent and delete it.
*
* @param node doctype to release memory.
*/
@ -454,12 +454,12 @@ EAPI void eina_simple_xml_node_doctype_free(Eina_Simple_XML_Node_Data *node);
/**
* Create new comment. If parent is provided, it is automatically appended.
* @brief Creates new comment. If parent is provided, it is automatically appended.
*
* @param parent if provided, will be set in the resulting structure
* @param parent If provided, will be set in the resulting structure
* as well as the comment will be appended to children list.
* @param contents String to be used. Must not be @c NULL.
* @param length size in bytes of @a contents.
* @param length Size in bytes of @a contents.
*
* @return Newly allocated memory or @c NULL on error. This memory should be
* released with eina_simple_xml_node_comment_free() or indirectly
@ -468,7 +468,7 @@ EAPI void eina_simple_xml_node_doctype_free(Eina_Simple_XML_Node_Data *node);
EAPI Eina_Simple_XML_Node_Comment * eina_simple_xml_node_comment_new(Eina_Simple_XML_Node_Tag *parent, const char *contents, size_t length);
/**
* Remove comment from parent and delete it.
* @brief Removes comment from parent and delete it.
*
* @param node comment to release memory.
*/
@ -476,11 +476,11 @@ EAPI void eina_simple_xml_node_comment_free(Eina_Simple_XML_Node_Data *node);
/**
* Load a XML node tree based on the given string.
* @brief Loads a XML node tree based on the given string.
*
* @param buf the input string. May not contain \0 terminator.
* @param buflen the input string size.
* @param strip whenever this parser should strip leading and trailing
* @param buf The input string. May not contain \0 terminator.
* @param buflen The input string size.
* @param strip Whenever this parser should strip leading and trailing
* whitespace.
*
* @return Document root with children tags, or @c NULL on errors.
@ -490,19 +490,19 @@ EAPI void eina_simple_xml_node_comment_free(Eina_Simple_XML_Node_Data *node);
EAPI Eina_Simple_XML_Node_Root * eina_simple_xml_node_load(const char *buf, unsigned buflen, Eina_Bool strip);
/**
* Free node tree build with eina_simple_xml_node_load()
* @brief Frees node tree build with eina_simple_xml_node_load()
*
* @param root memory returned by eina_simple_xml_node_load()
* @param root Memory returned by eina_simple_xml_node_load()
*/
EAPI void eina_simple_xml_node_root_free(Eina_Simple_XML_Node_Root *root);
/**
* Converts the node tree under the given element to a XML string.
* @brief Converts the node tree under the given element to a XML string.
*
* @param node the base node to convert.
* @param node The base node to convert.
* @param indent Indentation string, or @c NULL to disable it.
*
* @return @c NULL on errors or a newly allocated string on success.
* @return @c NULL on errors, or a newly allocated string on success.
*/
EAPI char * eina_simple_xml_node_dump(Eina_Simple_XML_Node *node, const char *indent);

40
src/lib/eina/eina_str.h
View File

@ -55,7 +55,7 @@
/**
* @addtogroup Eina_String_Group String
*
* @brief Provide useful functions for C string manipulation.
* @brief Provides useful functions for C string manipulation.
*
* This group of functions allow you to more easily manipulate strings, they
* provide functionality not available through string.h.
@ -83,7 +83,7 @@
/* strlcpy implementation for libc's lacking it */
/**
* @brief Copy a c-string to another.
* @brief Copies a c-string to another.
*
* @param dst The destination string.
* @param src The source string.
@ -103,7 +103,7 @@
EAPI size_t eina_strlcpy(char *dst, const char *src, size_t siz) EINA_ARG_NONNULL(1, 2);
/**
* @brief Append a c-string.
* @brief Appends a c-string.
*
* @param dst The destination string.
* @param src The source string.
@ -121,7 +121,7 @@ EAPI size_t eina_strlcat(char *dst, const char *src, size_t siz) EINA_A
/**
* @brief Check if the given string has the given prefix.
* @brief Checks if the given string has the given prefix.
*
* @param str The string to work with.
* @param prefix The prefix to check for.
@ -134,7 +134,7 @@ EAPI size_t eina_strlcat(char *dst, const char *src, size_t siz) EINA_A
EAPI Eina_Bool eina_str_has_prefix(const char *str, const char *prefix) EINA_PURE EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT;
/**
* @brief Check if the given string has the given suffix.
* @brief Checks if the given string has the given suffix.
*
* @param str The string to work with.
* @param suffix The suffix to check for.
@ -147,7 +147,7 @@ EAPI Eina_Bool eina_str_has_prefix(const char *str, const char *prefix) EI
EAPI Eina_Bool eina_str_has_suffix(const char *str, const char *suffix) EINA_PURE EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT;
/**
* @brief Check if the given string has the given extension.
* @brief Checks if the given string has the given extension.
*
* @param str The string to work with.
* @param ext The extension to check for.
@ -159,7 +159,7 @@ EAPI Eina_Bool eina_str_has_suffix(const char *str, const char *suffix) EI
EAPI Eina_Bool eina_str_has_extension(const char *str, const char *ext) EINA_PURE EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT;
/**
* @brief Split a string using a delimiter.
* @brief Splits a string using a delimiter.
*
* @param string The string to split.
* @param delimiter The string which specifies the places at which to split the string.
@ -185,7 +185,7 @@ EAPI Eina_Bool eina_str_has_extension(const char *str, const char *ext) EI
EAPI char **eina_str_split(const char *string, const char *delimiter, int max_tokens) EINA_ARG_NONNULL(1, 2) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
/**
* @brief Split a string using a delimiter and returns number of elements.
* @brief Splits a string using a delimiter and returns number of elements.
*
* @param string The string to split.
* @param delimiter The string which specifies the places at which to split the string.
@ -219,15 +219,15 @@ EAPI char **eina_str_split_full(const char *string, const char *delimit
/**
* @brief Join two strings of known length.
* @brief Joins two strings of known length.
*
* @param dst The buffer to store the result.
* @param size Size (in byte) of the buffer.
* @param sep The separator character to use.
* @param a First string to use, before @p sep.
* @param a_len length of @p a.
* @param a_len Length of @p a.
* @param b Second string to use, after @p sep.
* @param b_len length of @p b.
* @param b_len Length of @p b.
* @return The number of characters printed.
*
* This function joins the strings @p a and @p b (in that order) and
@ -248,7 +248,7 @@ EAPI size_t eina_str_join_len(char *dst, size_t size, char sep, const c
/**
* @brief Use Iconv to convert a text string from one encoding to another.
* @brief Uses Iconv to convert a text string from one encoding to another.
*
* @param enc_from Encoding to convert from.
* @param enc_to Encoding to convert to.
@ -267,7 +267,7 @@ EAPI size_t eina_str_join_len(char *dst, size_t size, char sep, const c
EAPI char *eina_str_convert(const char *enc_from, const char *enc_to, const char *text) EINA_WARN_UNUSED_RESULT EINA_MALLOC EINA_ARG_NONNULL(1, 2, 3);
/**
* @brief Use Iconv to convert a text string from one encoding to another.
* @brief Uses Iconv to convert a text string from one encoding to another.
*
* @param enc_from Encoding to convert from.
* @param enc_to Encoding to convert to.
@ -288,7 +288,7 @@ EAPI char *eina_str_convert_len(const char *enc_from, const char *enc_
/**
* @brief Escape slashes, spaces and apostrophes in strings.
* @brief Escapes slashes, spaces and apostrophes in strings.
*
* @param str The string to escape.
* @return The escaped string.
@ -303,7 +303,7 @@ EAPI char *eina_str_escape(const char *str) EINA_WARN_UNUSED_RESULT EI
/**
* @brief Lowercase all the characters in range [A-Z] in the given string.
* @brief Lowercases all the characters in range [A-Z] in the given string.
*
* @param str The string to lowercase.
*
@ -314,7 +314,7 @@ EAPI char *eina_str_escape(const char *str) EINA_WARN_UNUSED_RESULT EI
EAPI void eina_str_tolower(char **str);
/**
* @brief Uppercase all the characters in range [a-z] in the given string.
* @brief Uppercases all the characters in range [a-z] in the given string.
*
* @param str The string to uppercase.
*
@ -328,7 +328,7 @@ static inline size_t eina_str_join(char *dst, size_t size, char sep, const char
/**
* @def eina_str_join_static(dst, sep, a, b)
* @brief Join two static strings and store the result in a static buffer.
* @brief Joins two static strings and store the result in a static buffer.
*
* @param dst The buffer to store the result.
* @param sep The separator character to use.
@ -347,17 +347,17 @@ static inline size_t eina_str_join(char *dst, size_t size, char sep, const char
static inline size_t eina_strlen_bounded(const char *str, size_t maxlen) EINA_PURE EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
/**
* @brief memory duplication function with optional termination for strings
* @brief Memory duplication function with optional termination for strings
* @param mem The memory to copy
* @param size The size of @p mem
* @param terminate If true, the returned memory will be nul terminated with '\0'
* @return the copied memory, must be freed
* @return The copied memory, must be freed
* @since 1.13
*/
EAPI unsigned char *eina_memdup(unsigned char *mem, size_t size, Eina_Bool terminate);
/**
* @brief Create and update the buffer based on strftime output.
* @brief Creates and update the buffer based on strftime output.
*
* @param tm Pointer to a tm structure needed by strftime.
* @param format String containing format specifiers needed by strftime.

128
src/lib/eina/eina_strbuf.h
View File

@ -66,7 +66,7 @@
typedef struct _Eina_Strbuf Eina_Strbuf;
/**
* @brief Create a new string buffer.
* @brief Creates a new string buffer.
*
* @return Newly allocated string buffer instance.
*
@ -80,11 +80,11 @@ typedef struct _Eina_Strbuf Eina_Strbuf;
EAPI Eina_Strbuf *eina_strbuf_new(void) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
/**
* @brief Create a new string buffer using the passed string. The passed
* @brief Creates a new string buffer using the passed string. The passed
* string is used directly as the buffer, it's somehow the opposite function of
* @ref eina_strbuf_string_steal . The passed string must be malloced.
*
* @param str the string to manage
* @param str The string to manage
* @return Newly allocated string buffer instance.
*
* This function creates a new string buffer. On error, @c NULL is
@ -98,12 +98,12 @@ EAPI Eina_Strbuf *eina_strbuf_new(void) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
EAPI Eina_Strbuf *eina_strbuf_manage_new(char *str) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
/**
* @brief Create a new string buffer using the passed string. The passed
* @brief Creates a new string buffer using the passed string. The passed
* string is used directly as the buffer, it's somehow the opposite function of
* @ref eina_strbuf_string_steal . The passed string must be malloced.
*
* @param str the string to manage
* @param length the length of the string.
* @param str The string to manage
* @param length The length of the string.
* @return Newly allocated string buffer instance.
*
* This function creates a new string buffer. On error, @c NULL is
@ -115,12 +115,12 @@ EAPI Eina_Strbuf *eina_strbuf_manage_new(char *str) EINA_MALLOC EINA_WARN_UNUSED
EAPI Eina_Strbuf *eina_strbuf_manage_new_length(char *str, size_t length) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
/**
* @brief Create a new string buffer using the passed string. The passed
* @brief Creates a new string buffer using the passed string. The passed
* string is used directly as the buffer, it's somehow the opposite function of
* @ref eina_strbuf_string_steal . The passed string must be malloced.
*
* @param str the string to manage
* @param length the length of the string.
* @param str The string to manage
* @param length The length of the string.
* @return Newly allocated string buffer instance.
*
* This function creates a new string buffer. On error, @c NULL is
@ -132,7 +132,7 @@ EAPI Eina_Strbuf *eina_strbuf_manage_new_length(char *str, size_t length) EINA_M
EAPI Eina_Strbuf *eina_strbuf_manage_read_only_new_length(const char *str, size_t length) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
/**
* @brief Free a string buffer.
* @brief Frees a string buffer.
*
* @param buf The string buffer to free.
*
@ -142,7 +142,7 @@ EAPI Eina_Strbuf *eina_strbuf_manage_read_only_new_length(const char *str, size_
EAPI void eina_strbuf_free(Eina_Strbuf *buf) EINA_ARG_NONNULL(1);
/**
* @brief Reset a string buffer.
* @brief Resets a string buffer.
*
* @param buf The string buffer to reset.
*
@ -152,7 +152,7 @@ EAPI void eina_strbuf_free(Eina_Strbuf *buf) EINA_ARG_NONNULL(1);
EAPI void eina_strbuf_reset(Eina_Strbuf *buf) EINA_ARG_NONNULL(1);
/**
* @brief Append a string to a buffer, reallocating as necessary.
* @brief Appends a string to a buffer, reallocating as necessary.
*
* @param buf The string buffer to append to.
* @param str The string to append.
@ -170,7 +170,7 @@ EAPI void eina_strbuf_reset(Eina_Strbuf *buf) EINA_ARG_NONNULL(1);
EAPI Eina_Bool eina_strbuf_append(Eina_Strbuf *buf, const char *str) EINA_ARG_NONNULL(1, 2);
/**
* @brief Append an escaped string to a buffer, reallocating as necessary.
* @brief Appends an escaped string to a buffer, reallocating as necessary.
*
* @param buf The string buffer to append to.
* @param str The string to append.
@ -183,7 +183,7 @@ EAPI Eina_Bool eina_strbuf_append(Eina_Strbuf *buf, const char *str) EINA_ARG_NO
EAPI Eina_Bool eina_strbuf_append_escaped(Eina_Strbuf *buf, const char *str) EINA_ARG_NONNULL(1, 2);
/**
* @brief Append a string to a buffer, reallocating as necessary,
* @brief Appends a string to a buffer, reallocating as necessary,
* limited by the given length.
*
* @param buf The string buffer to append to.
@ -206,7 +206,7 @@ EAPI Eina_Bool eina_strbuf_append_escaped(Eina_Strbuf *buf, const char *str) EIN
EAPI Eina_Bool eina_strbuf_append_n(Eina_Strbuf *buf, const char *str, size_t maxlen) EINA_ARG_NONNULL(1, 2);
/**
* @brief Append a string of exact length to a buffer, reallocating as necessary.
* @brief Appends a string of exact length to a buffer, reallocating as necessary.
*
* @param buf The string buffer to append to.
* @param str The string to append.
@ -241,7 +241,7 @@ EAPI Eina_Bool eina_strbuf_append_length(Eina_Strbuf *buf, const char *str, size
EAPI Eina_Bool eina_strbuf_append_slice(Eina_Strbuf *buf, const Eina_Slice slice) EINA_ARG_NONNULL(1);
/**
* @brief Append an Eina_Strbuf to a buffer, reallocating as necessary.
* @brief Appends an Eina_Strbuf to a buffer, reallocating as necessary.
*
* @param buf The string buffer to append to.
* @param data The string buffer to append.
@ -260,7 +260,7 @@ EAPI Eina_Bool eina_strbuf_append_slice(Eina_Strbuf *buf, const Eina_Slice slice
EAPI Eina_Bool eina_strbuf_append_buffer(Eina_Strbuf *buf, const Eina_Strbuf *data) EINA_ARG_NONNULL(1, 2);
/**
* @brief Append a character to a string buffer, reallocating as
* @brief Appends a character to a string buffer, reallocating as
* necessary.
*
* @param buf The string buffer to append to.
@ -273,7 +273,7 @@ EAPI Eina_Bool eina_strbuf_append_buffer(Eina_Strbuf *buf, const Eina_Strbuf *da
EAPI Eina_Bool eina_strbuf_append_char(Eina_Strbuf *buf, char c) EINA_ARG_NONNULL(1);
/**
* @brief Append a string to a buffer, reallocating as necessary.
* @brief Appends a string to a buffer, reallocating as necessary.
*
* @param buf The string buffer to append to.
* @param fmt The string to append.
@ -288,7 +288,7 @@ EAPI Eina_Bool eina_strbuf_append_char(Eina_Strbuf *buf, char c) EINA_ARG_NONNUL
EAPI Eina_Bool eina_strbuf_append_printf(Eina_Strbuf *buf, const char *fmt, ...) EINA_ARG_NONNULL(1, 2) EINA_PRINTF(2, 3);
/**
* @brief Append a string to a buffer, reallocating as necessary.
* @brief Appends a string to a buffer, reallocating as necessary.
*
* @param buf The string buffer to append to.
* @param fmt The string to append.
@ -300,7 +300,7 @@ EAPI Eina_Bool eina_strbuf_append_printf(Eina_Strbuf *buf, const char *fmt, ...)
EAPI Eina_Bool eina_strbuf_append_vprintf(Eina_Strbuf *buf, const char *fmt, va_list args) EINA_ARG_NONNULL(1, 2);
/**
* @brief Insert a string to a buffer, reallocating as necessary.
* @brief Inserts a string to a buffer, reallocating as necessary.
*
* @param buf The string buffer to insert.
* @param str The string to insert.
@ -316,7 +316,7 @@ EAPI Eina_Bool eina_strbuf_append_vprintf(Eina_Strbuf *buf, const char *fmt, va_
EAPI Eina_Bool eina_strbuf_insert(Eina_Strbuf *buf, const char *str, size_t pos) EINA_ARG_NONNULL(1, 2);
/**
* @brief Insert an escaped string to a buffer, reallocating as
* @brief Inserts an escaped string to a buffer, reallocating as
* necessary.
*
* @param buf The string buffer to insert to.
@ -331,7 +331,7 @@ EAPI Eina_Bool eina_strbuf_insert(Eina_Strbuf *buf, const char *str, size_t pos)
EAPI Eina_Bool eina_strbuf_insert_escaped(Eina_Strbuf *buf, const char *str, size_t pos) EINA_ARG_NONNULL(1, 2);
/**
* @brief Insert a string to a buffer, reallocating as necessary. Limited by maxlen.
* @brief Inserts a string to a buffer, reallocating as necessary. Limited by maxlen.
*
* @param buf The string buffer to insert to.
* @param str The string to insert.
@ -351,7 +351,7 @@ EAPI Eina_Bool eina_strbuf_insert_escaped(Eina_Strbuf *buf, const char *str, siz
EAPI Eina_Bool eina_strbuf_insert_n(Eina_Strbuf *buf, const char *str, size_t maxlen, size_t pos) EINA_ARG_NONNULL(1, 2);
/**
* @brief Insert a string of exact length to a buffer, reallocating as necessary.
* @brief Inserts a string of exact length to a buffer, reallocating as necessary.
*
* @param buf The string buffer to insert to.
* @param str The string to insert.
@ -389,7 +389,7 @@ EAPI Eina_Bool eina_strbuf_insert_length(Eina_Strbuf *buf, const char *str, size
EAPI Eina_Bool eina_strbuf_insert_slice(Eina_Strbuf *buf, const Eina_Slice slice, size_t pos) EINA_ARG_NONNULL(1);
/**
* @brief Insert a character to a string buffer, reallocating as
* @brief Inserts a character to a string buffer, reallocating as
* necessary.
*
* @param buf The string buffer to insert to.
@ -404,7 +404,7 @@ EAPI Eina_Bool eina_strbuf_insert_slice(Eina_Strbuf *buf, const Eina_Slice slice
EAPI Eina_Bool eina_strbuf_insert_char(Eina_Strbuf *buf, char c, size_t pos) EINA_ARG_NONNULL(1);
/**
* @brief Insert a string to a buffer, reallocating as necessary.
* @brief Inserts a string to a buffer, reallocating as necessary.
*
* @param buf The string buffer to insert.
* @param fmt The string to insert.
@ -419,7 +419,7 @@ EAPI Eina_Bool eina_strbuf_insert_char(Eina_Strbuf *buf, char c, size_t pos) EIN
EAPI Eina_Bool eina_strbuf_insert_printf(Eina_Strbuf *buf, const char *fmt, size_t pos, ...) EINA_ARG_NONNULL(1, 2) EINA_PRINTF(2, 4);
/**
* @brief Insert a string to a buffer, reallocating as necessary.
* @brief Inserts a string to a buffer, reallocating as necessary.
*
* @param buf The string buffer to insert.
* @param fmt The string to insert.
@ -433,7 +433,7 @@ EAPI Eina_Bool eina_strbuf_insert_vprintf(Eina_Strbuf *buf, const char *fmt, siz
/**
* @def eina_strbuf_prepend(buf, str)
* @brief Prepend the given string to the given buffer
* @brief Prepends the given string to the given buffer.
*
* @param buf The string buffer to prepend to.
* @param str The string to prepend.
@ -447,7 +447,7 @@ EAPI Eina_Bool eina_strbuf_insert_vprintf(Eina_Strbuf *buf, const char *fmt, siz
/**
* @def eina_strbuf_prepend_escaped(buf, str)
* @brief Prepend the given escaped string to the given buffer
* @brief Prepends the given escaped string to the given buffer.
*
* @param buf The string buffer to prepend to.
* @param str The string to prepend.
@ -461,7 +461,7 @@ EAPI Eina_Bool eina_strbuf_insert_vprintf(Eina_Strbuf *buf, const char *fmt, siz
/**
* @def eina_strbuf_prepend_n(buf, str)
* @brief Prepend the given escaped string to the given buffer
* @brief Prepends the given escaped string to the given buffer.
*
* @param buf The string buffer to prepend to.
* @param str The string to prepend.
@ -476,7 +476,7 @@ EAPI Eina_Bool eina_strbuf_insert_vprintf(Eina_Strbuf *buf, const char *fmt, siz
/**
* @def eina_strbuf_prepend_length(buf, str)
* @brief Prepend the given escaped string to the given buffer
* @brief Prepends the given escaped string to the given buffer.
*
* @param buf The string buffer to prepend to.
* @param str The string to prepend.
@ -491,7 +491,7 @@ EAPI Eina_Bool eina_strbuf_insert_vprintf(Eina_Strbuf *buf, const char *fmt, siz
/**
* @def eina_strbuf_prepend_char(buf, str)
* @brief Prepend the given character to the given buffer
* @brief Prepends the given character to the given buffer.
*
* @param buf The string buffer to prepend to.
* @param c The character to prepend.
@ -505,7 +505,7 @@ EAPI Eina_Bool eina_strbuf_insert_vprintf(Eina_Strbuf *buf, const char *fmt, siz
/**
* @def eina_strbuf_prepend_printf(buf, fmt, ...)
* @brief Prepend the given string to the given buffer
* @brief Prepends the given string to the given buffer.
*
* @param buf The string buffer to prepend to.
* @param fmt The string to prepend.
@ -519,7 +519,7 @@ EAPI Eina_Bool eina_strbuf_insert_vprintf(Eina_Strbuf *buf, const char *fmt, siz
/**
* @def eina_strbuf_prepend_vprintf(buf, fmt, args)
* @brief Prepend the given string to the given buffer
* @brief Prepends the given string to the given buffer.
*
* @param buf The string buffer to prepend to.
* @param fmt The string to prepend.
@ -533,7 +533,7 @@ EAPI Eina_Bool eina_strbuf_insert_vprintf(Eina_Strbuf *buf, const char *fmt, siz
#define eina_strbuf_prepend_vprintf(buf, fmt, args) eina_strbuf_insert_vprintf(buf, fmt, 0, args)
/**
* @brief Remove a slice of the given string buffer.
* @brief Removes a slice of the given string buffer.
*
* @param buf The string buffer to remove a slice.
* @param start The initial (inclusive) slice position to start
@ -550,7 +550,7 @@ EAPI Eina_Bool eina_strbuf_insert_vprintf(Eina_Strbuf *buf, const char *fmt, siz
EAPI Eina_Bool eina_strbuf_remove(Eina_Strbuf *buf, size_t start, size_t end) EINA_ARG_NONNULL(1);
/**
* @brief Retrieve a pointer to the contents of a string buffer
* @brief Retrieves a pointer to the contents of a string buffer.
*
* @param buf The string buffer.
* @return The current string in the string buffer.
@ -566,7 +566,7 @@ EAPI Eina_Bool eina_strbuf_remove(Eina_Strbuf *buf, size_t start, size_t end) EI
EAPI const char *eina_strbuf_string_get(const Eina_Strbuf *buf) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
/**
* @brief Steal the contents of a string buffer.
* @brief Steals the contents of a string buffer.
*
* @param buf The string buffer to steal.
* @return The current string in the string buffer.
@ -581,7 +581,7 @@ EAPI const char *eina_strbuf_string_get(const Eina_Strbuf *buf) EINA_ARG_NONNULL
EAPI char *eina_strbuf_string_steal(Eina_Strbuf *buf) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
/**
* @brief Free the contents of a string buffer but not the buffer.
* @brief Frees the contents of a string buffer but not the buffer.
*
* @param buf The string buffer to free the string of.
*
@ -591,7 +591,7 @@ EAPI char *eina_strbuf_string_steal(Eina_Strbuf *buf) EINA_MALLOC EINA_WARN_UNUS
EAPI void eina_strbuf_string_free(Eina_Strbuf *buf) EINA_ARG_NONNULL(1);
/**
* @brief Retrieve the length of the string buffer content.
* @brief Retrieves the length of the string buffer content.
*
* @param buf The string buffer.
* @return The current length of the string, in bytes.
@ -602,11 +602,11 @@ EAPI size_t eina_strbuf_length_get(const Eina_Strbuf *buf) EINA_ARG_NONNULL(1
/**
* @brief Replace the n-th string with an other string.
* @brief Replaces the n-th string with an other string.
*
* @param buf The string buffer to work with.
* @param str The string to replace.
* @param with The replaceing string.
* @param with The replacing string.
* @param n The number of the fitting string.
* @return #EINA_TRUE on success, #EINA_FALSE on failure.
*
@ -617,7 +617,7 @@ EAPI Eina_Bool eina_strbuf_replace(Eina_Strbuf *buf, const char *str, const char
/**
* @def eina_strbuf_replace_first(buf, str, with)
* @brief Prepend the given character to the given buffer
* @brief Prepends the given character to the given buffer.
*
* @param buf The string buffer to work with.
* @param str The string to replace.
@ -632,11 +632,11 @@ EAPI Eina_Bool eina_strbuf_replace(Eina_Strbuf *buf, const char *str, const char
/**
* @brief Replace all strings with an other string.
* @brief Replaces all strings with an other string.
* @param buf the string buffer to work with.
* @param buf The string buffer to work with.
* @param str The string to replace.
* @param with The replaceing string.
* @param with The replacing string.
* @return How often the string was replaced.
*
* This function replaces all the occurrences of @p str in @p buf with
@ -646,36 +646,36 @@ EAPI Eina_Bool eina_strbuf_replace(Eina_Strbuf *buf, const char *str, const char
EAPI int eina_strbuf_replace_all(Eina_Strbuf *buf, const char *str, const char *with) EINA_ARG_NONNULL(1, 2, 3);
/**
* @brief Trim the string buffer
* @brief Trims the string buffer.
* @param buf the string buffer to work with.
* @param buf The string buffer to work with.
*
* This function skips whitespaces in the beginning and the end of the buffer.
*/
EAPI void eina_strbuf_trim(Eina_Strbuf *buf) EINA_ARG_NONNULL(1);
/**
* @brief Left trim the string buffer
* @brief Left trims the string buffer.
* @param buf the string buffer to work with.
* @param buf The string buffer to work with.
*
* This function skips whitespaces in the beginning of the buffer.
*/
EAPI void eina_strbuf_ltrim(Eina_Strbuf *buf) EINA_ARG_NONNULL(1);
/**
* @brief Right trim the string buffer
* @brief Right trims the string buffer.
* @param buf the string buffer to work with.
* @param buf The string buffer to work with.
*
* This function skips whitespaces in the end of the buffer.
*/
EAPI void eina_strbuf_rtrim(Eina_Strbuf *buf) EINA_ARG_NONNULL(1);
/**
* @brief Convert the string to lower case.
* @brief Converts the string to lower case.
*
* @param buf the string buffer to work with.
* @param buf The string buffer to work with.
*
* This function converts all the characters in the strbuf to lower case.
*
@ -684,13 +684,13 @@ EAPI void eina_strbuf_rtrim(Eina_Strbuf *buf) EINA_ARG_NONNULL(1);
EAPI void eina_strbuf_tolower(Eina_Strbuf *buf) EINA_ARG_NONNULL(1);
/**
* @brief Obtain substring from the src.
* @brief Obtains substring from the src.
*
* @param buf the src string.
* @param pos the position in the source string from which the substring
* @param buf The src string.
* @param pos The position in the source string from which the substring
* should be created. The first character is denoted by a
* value of 0 (not 1).
* @param len the length from pos that should be copied to substring.
* @param len The length from pos that should be copied to substring.
*
* This function creates a Eina_Strbuf which is a substring of buf which
* is passed from pos position with len length.
@ -702,10 +702,10 @@ EAPI void eina_strbuf_tolower(Eina_Strbuf *buf) EINA_ARG_NONNULL(1);
EAPI Eina_Strbuf * eina_strbuf_substr_get(Eina_Strbuf *buf, size_t pos, size_t len) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
/**
* @brief Get a read-only slice representing the current strbuf contents.
* @brief Gets a read-only slice representing the current strbuf contents.
*
* @param buf the source string.
* @return a read-only slice for the current contents. It may become
* @param buf The source string.
* @return A read-only slice for the current contents. It may become
* invalid as soon as the @a buf is changed.
*
* @since 1.19
@ -713,10 +713,10 @@ EAPI Eina_Strbuf * eina_strbuf_substr_get(Eina_Strbuf *buf, size_t pos, size_t l
EAPI Eina_Slice eina_strbuf_slice_get(const Eina_Strbuf *buf) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
/**
* @brief Get a read-write slice representing the current strbuf contents.
* @brief Gets a read-write slice representing the current strbuf contents.
*
* @param buf the source string.
* @return a read-write slice for the current contents. It may become
* @param buf The source string.
* @return A read-write slice for the current contents. It may become
* invalid as soon as the @a buf is changed with calls such as
* eina_strbuf_append(), eina_strbuf_remove()
*
@ -726,9 +726,9 @@ EAPI Eina_Rw_Slice eina_strbuf_rw_slice_get(const Eina_Strbuf *buf) EINA_WARN_UN
/**
* @brief Get the string of the buffer and free the buffer
* @brief Gets the string of the buffer and free the buffer
*
* @param buf the buffer to get the string from and which will be freed
* @param buf The buffer to get the string from and which will be freed
*
* @return The string contained by bug. The caller must release the memory of the returned string by calling
* free().

38
src/lib/eina/eina_stringshare.h
View File

@ -29,9 +29,9 @@
*
* The above copyright notice and this permission notice shall be included in
* all copies of the Software and its Copyright notices. In addition publicly
* documented acknowledgment must be given that this software has been used if no
* documented acknowledgement must be given that this software has been used if no
* source code of this software is made available publicly. This includes
* acknowledgments in either Copyright notices, Manuals, Publicity and Marketing
* acknowledgements in either Copyright notices, Manuals, Publicity and Marketing
* documents or any documentation provided with any product containing this
* software. This License does not apply to any software that links to the
* libraries provided by this software (statically or dynamically), but only to
@ -93,7 +93,7 @@
* value you should use eina_stringshare_replace():
* @until printf
* @warning @b Don't use eina_stringshare_del() followed by
* eina_share_common_add(), under some circunstances you might end up deleting
* eina_share_common_add(), under some circumstances you might end up deleting
* a shared string some other piece of code is using.
*
* We created str but haven't deleted it yet, and while we called
@ -175,12 +175,12 @@
typedef const char Eina_Stringshare;
/**
* @brief Retrieve an instance of a string with a specific size for use in a
* @brief Retrieves an instance of a string with a specific size for use in a
* program.
*
* @param str The string to retrieve an instance of.
* @param slen The string size (<= strlen(str)).
* @return A pointer to an instance of the string on success.
* @return A pointer to an instance of the string on success,
* @c NULL on failure.
*
* This function retrieves an instance of @p str. If @p str is
@ -197,10 +197,10 @@ typedef const char Eina_Stringshare;
EAPI Eina_Stringshare *eina_stringshare_add_length(const char *str, unsigned int slen) EINA_WARN_UNUSED_RESULT;
/**
* @brief Retrieve an instance of a string for use in a program.
* @brief Retrieves an instance of a string for use in a program.
*
* @param str The NULL-terminated string to retrieve an instance of.
* @return A pointer to an instance of the string on success.
* @return A pointer to an instance of the string on success,
* @c NULL on failure.
*
* This function retrieves an instance of @p str. If @p str is
@ -217,11 +217,11 @@ EAPI Eina_Stringshare *eina_stringshare_add_length(const char *str, unsigned in
EAPI Eina_Stringshare *eina_stringshare_add(const char *str) EINA_WARN_UNUSED_RESULT;
/**
* @brief Retrieve an instance of a string for use in a program
* @brief Retrieves an instance of a string for use in a program
* from a format string.
*
* @param fmt The NULL-terminated format string to retrieve an instance of.
* @return A pointer to an instance of the string on success.
* @return A pointer to an instance of the string on success,
* @c NULL on failure.
*
* This function retrieves an instance of @p fmt. If @p fmt is
@ -238,12 +238,12 @@ EAPI Eina_Stringshare *eina_stringshare_add(const char *str) EINA_WARN_UNUSED_R
EAPI Eina_Stringshare *eina_stringshare_printf(const char *fmt, ...) EINA_WARN_UNUSED_RESULT EINA_PRINTF(1, 2);
/**
* @brief Retrieve an instance of a string for use in a program
* @brief Retrieves an instance of a string for use in a program
* from a format string.
*
* @param fmt The NULL-terminated format string to retrieve an instance of.
* @param args The va_args for @p fmt
* @return A pointer to an instance of the string on success.
* @return A pointer to an instance of the string on success,
* @c NULL on failure.
*
* This function retrieves an instance of @p fmt with @p args. If @p fmt is
@ -260,11 +260,11 @@ EAPI Eina_Stringshare *eina_stringshare_printf(const char *fmt, ...) EINA_WARN_
EAPI Eina_Stringshare *eina_stringshare_vprintf(const char *fmt, va_list args) EINA_WARN_UNUSED_RESULT;
/**
* @brief Retrieve an instance of a string for use in a program
* @brief Retrieves an instance of a string for use in a program
* from a format string with size limitation.
* @param len The length of the format string to use
* @param fmt The format string to retrieve an instance of.
* @return A pointer to an instance of the string on success.
* @return A pointer to an instance of the string on success,
* @c NULL on failure.
*
* This function retrieves an instance of @p fmt limited by @p len. If @p fmt is
@ -283,7 +283,7 @@ EAPI Eina_Stringshare *eina_stringshare_nprintf(unsigned int len, const char *f
* Increment references of the given shared string.
*
* @param str The shared string.
* @return A pointer to an instance of the string on success.
* @return A pointer to an instance of the string on success,
* @c NULL on failure.
*
* This is similar to eina_share_common_add(), but it's faster since it will
@ -296,9 +296,9 @@ EAPI Eina_Stringshare *eina_stringshare_nprintf(unsigned int len, const char *f
EAPI Eina_Stringshare *eina_stringshare_ref(Eina_Stringshare *str);
/**
* @brief Note that the given string has lost an instance.
* @brief Notes that the given string has lost an instance.
*
* @param str string The given string.
* @param str String the given string.
*
* This function decreases the reference counter associated to @p str
* if it exists. If that counter reaches 0, the memory associated to
@ -311,9 +311,9 @@ EAPI Eina_Stringshare *eina_stringshare_ref(Eina_Stringshare *str);
EAPI void eina_stringshare_del(Eina_Stringshare *str);
/**
* @brief Note that the given string @b must be shared.
* @brief Notes that the given string @b must be shared.
*
* @param str the shared string to know the length. It is safe to
* @param str The shared string to know the length. It is safe to
* give @c NULL, in that case @c 0 is returned.
* @return The length of a shared string.
*
@ -326,7 +326,7 @@ EAPI void eina_stringshare_del(Eina_Stringshare *str);
EAPI int eina_stringshare_strlen(Eina_Stringshare *str) EINA_PURE EINA_WARN_UNUSED_RESULT;
/**
* @brief Dump the contents of the share_common.
* @brief Dumps the contents of the share_common.
*
* This function dumps all strings in the share_common to stdout with a
* DDD: prefix per line and a memory usage summary.

34
src/lib/eina/eina_thread.h
View File

@ -34,7 +34,7 @@
/**
* @defgroup Eina_Thread_Group Thread
*
* Abstracts platform threads, providing an uniform API. It's modeled
* Abstracts platform threads, providing an uniform API. It's modelled
* after POSIX THREADS (pthreads), on Linux they are almost 1:1
* mapping.
*
@ -69,14 +69,14 @@ typedef enum _Eina_Thread_Priority
} Eina_Thread_Priority;
/**
* Return identifier of the current thread.
* @brief Returns identifier of the current thread.
* @return identifier of current thread.
* @since 1.8
*/
EAPI Eina_Thread eina_thread_self(void) EINA_WARN_UNUSED_RESULT;
/**
* Check if two thread identifiers are the same.
* @brief Checks if two thread identifiers are the same.
* @param t1 first thread identifier to compare.
* @param t2 second thread identifier to compare.
* @return #EINA_TRUE if they are equal, #EINA_FALSE otherwise.
@ -85,7 +85,7 @@ EAPI Eina_Thread eina_thread_self(void) EINA_WARN_UNUSED_RESULT;
EAPI Eina_Bool eina_thread_equal(Eina_Thread t1, Eina_Thread t2) EINA_WARN_UNUSED_RESULT;
/**
* Create a new thread, setting its priority and affinity.
* @brief Creates a new thread, setting its priority and affinity.
*
* @param t[out] where to return the thread identifier. Must @b not be @c NULL.
* @param prio thread priority to use, usually #EINA_THREAD_BACKGROUND
@ -100,7 +100,7 @@ EAPI Eina_Bool eina_thread_create(Eina_Thread *t,
Eina_Thread_Cb func, const void *data) EINA_ARG_NONNULL(1, 4) EINA_WARN_UNUSED_RESULT;
/**
* The return value of eina_thread_join() if it was canceled with
* @brief The return value of eina_thread_join() if it was canceled with
* eina_thread_cancel().
*
* A thread must be explicitly flagged as cancellable with
@ -114,7 +114,7 @@ EAPI Eina_Bool eina_thread_create(Eina_Thread *t,
EAPI extern const void *EINA_THREAD_JOIN_CANCELED;
/**
* Join a currently running thread, waiting until it finishes.
* @brief Joins a currently running thread, waiting until it finishes.
*
* This function will block the current thread until @a t
* finishes. The returned value is the one returned by @a t @c func()
@ -131,11 +131,11 @@ EAPI extern const void *EINA_THREAD_JOIN_CANCELED;
EAPI void *eina_thread_join(Eina_Thread t);
/**
* Set the name of a given thread for debugging purposes.
* @brief Sets the name of a given thread for debugging purposes.
*
* This maps to the pthread_setname_np() GNU extension or similar
* if available. The name may be limited in size (possibly 16
* characters including the nul byte terminator). This is useful
* characters including the null byte terminator). This is useful
* for debugging to name a thread so external tools can display a
* meaningful name attached to the thread.
*
@ -148,7 +148,7 @@ EAPI void *eina_thread_join(Eina_Thread t);
EAPI Eina_Bool eina_thread_name_set(Eina_Thread t, const char *name);
/**
* Attempt to cancel a running thread.
* @brief Attempts to cancel a running thread.
*
* This function sends a cancellation request to the thread, however
* that request is only fulfilled if the thread is cancellable
@ -160,7 +160,7 @@ EAPI Eina_Bool eina_thread_name_set(Eina_Thread t, const char *name);
* A thread that was canceled will return EINA_THREAD_JOIN_CANCELED
* when eina_thread_join() is called.
*
* @param t thread to cancel.
* @param t Thread to cancel.
*
* @return EINA_FALSE if thread was not running, EINA_TRUE
* otherwise. Note that if a thread is not cancellable and it
@ -171,7 +171,7 @@ EAPI Eina_Bool eina_thread_name_set(Eina_Thread t, const char *name);
EAPI Eina_Bool eina_thread_cancel(Eina_Thread t);
/**
* Enable or disable if the current thread can be canceled.
* @brief Enables or disables if the current thread can be canceled.
*
* By default eina_thread_create() will return a thread with
* cancellation disabled. One can enable the cancellation by using
@ -189,10 +189,10 @@ EAPI Eina_Bool eina_thread_cancel(Eina_Thread t);
* or the helper function eina_thread_cancellable_run() which does the
* pair for you.
*
* @param cancellable if EINA_TRUE, this thread will be accept
* @param cancellable If EINA_TRUE, this thread will be accept
* cancellation requests. If EINA_FALSE -- the default, it will
* ignore cancellation requests.
* @param was_cancellable if non-NULL, will return the previous state,
* @param was_cancellable If non-NULL, will return the previous state,
* shall you want to restore.
*
* @return EINA_TRUE if it succeeds in setting the cancellable state
@ -227,7 +227,7 @@ EAPI void eina_thread_cancel_checkpoint(void);
/**
* @def EINA_THREAD_CLEANUP_PUSH(cleanup, data)
*
* @brief Push a cleanup function to be executed when the thread is
* @brief Pushes a cleanup function to be executed when the thread is
* canceled.
*
* This macro will schedule a function cleanup(data) to be executed if
@ -246,8 +246,8 @@ EAPI void eina_thread_cancel_checkpoint(void);
* @b not be executed! To avoid problems prefer to use
* eina_thread_cancellable_run()!
*
* @param cleanup the function to execute on cancellation.
* @param data the context to give to cleanup function.
* @param cleanup The function to execute on cancellation.
* @param data The context to give to cleanup function.
*
* @see eina_thread_cancellable_run()
*
@ -259,7 +259,7 @@ EAPI void eina_thread_cancel_checkpoint(void);
/**
* @def EINA_THREAD_CLEANUP_POP(exec_cleanup)
*
* @brief Pop a cleanup function to be executed when the thread is
* @brief Pops a cleanup function to be executed when the thread is
* canceled.
*
* This macro will remove a previously pushed cleanup function, thus

30
src/lib/eina/eina_thread_queue.h
View File

@ -48,7 +48,7 @@ typedef struct _Eina_Thread_Queue_Msg Eina_Thread_Queue_Msg;
* queues. This is the only Message type for a parent message queue and
* it indicates which child queue was woken up with a new message to read.
* When this message is retrieved, the caller should then also fetch the
* message from the inidcated child queue too.
* message from the indicated child queue too.
*
* @since 1.11
*/
@ -66,7 +66,7 @@ struct _Eina_Thread_Queue_Msg_Sub
};
/**
* @brief Create a new thread queue
* @brief Creates a new thread queue.
*
* @return A valid new thread queue, or NULL on failure
*
@ -76,7 +76,7 @@ EAPI Eina_Thread_Queue *
eina_thread_queue_new(void);
/**
* @brief Free a thread queue
* @brief Frees a thread queue.
*
* This frees a thread queue. It must no longer be in use by anything waiting
* on messages or sending them. Any pending messages will be freed without
@ -90,7 +90,7 @@ EAPI void
eina_thread_queue_free(Eina_Thread_Queue *thq) EINA_ARG_NONNULL(1);
/**
* @brief Allocate a message to send down a thread queue
* @brief Allocates a message to send down a thread queue.
*
* @param thq The thread queue to allocate the message on
* @param size The size, in bytes, of the message, including standard header
@ -109,7 +109,7 @@ EAPI void *
eina_thread_queue_send(Eina_Thread_Queue *thq, int size, void **allocref) EINA_ARG_NONNULL(1, 3);
/**
* @brief Finish sending the allocated message
* @brief Finishes sending the allocated message.
*
* @param thq The thread queue the message was placed on
* @param allocref The allocref returned by eina_thread_queue_send()
@ -123,7 +123,7 @@ EAPI void
eina_thread_queue_send_done(Eina_Thread_Queue *thq, void *allocref) EINA_ARG_NONNULL(1, 2);
/**
* @brief Fetch a message from a thread queue
* @brief Fetches a message from a thread queue.
*
* @param thq The thread queue to fetch the message from
* @param allocref A pointer to store a general reference handle for the message
@ -143,7 +143,7 @@ EAPI void *
eina_thread_queue_wait(Eina_Thread_Queue *thq, void **allocref) EINA_ARG_NONNULL(1, 2);
/**
* @brief Finish fetching a message from a thread queue
* @brief Finishes fetching a message from a thread queue.
*
* @param thq The thread queue the message was fetched from
* @param allocref The allocref returned by eina_thread_queue_wait()
@ -157,7 +157,7 @@ EAPI void
eina_thread_queue_wait_done(Eina_Thread_Queue *thq, void *allocref) EINA_ARG_NONNULL(1, 2);
/**
* @brief Fetch a message from a thread queue, but return immediately if there is none with NULL
* @brief Fetches a message from a thread queue, but return immediately if there is none with NULL.
*
* @param thq The thread queue to fetch the message from
* @param allocref A pointer to store a general reference handle for the message
@ -175,7 +175,7 @@ EAPI void *
eina_thread_queue_poll(Eina_Thread_Queue *thq, void **allocref) EINA_ARG_NONNULL(1, 2);
/**
* @brief Get the number of messages on a queue as yet unfetched
* @brief Gets the number of messages on a queue as yet unfetched.
*
* @param thq The thread queue to query for pending count
* @return The number of messages waiting to be fetched
@ -189,7 +189,7 @@ EAPI int
eina_thread_queue_pending_get(const Eina_Thread_Queue *thq) EINA_ARG_NONNULL(1);
/**
* @brief Set the parent of a thread queue (make this one a child)
* @brief Sets the parent of a thread queue (make this one a child).
*
* @param thq The thread queue to alter the parent of
* @param thq_parent The new parent to set
@ -206,12 +206,12 @@ EAPI void
eina_thread_queue_parent_set(Eina_Thread_Queue *thq, Eina_Thread_Queue *thq_parent) EINA_ARG_NONNULL(1);
/**
* @brief Get the parent of a thread queue
* @brief Gets the parent of a thread queue.
*
* @param thq The thread queue to get the parent of
* @return The parent thread queue
*
* This gets the paren set by eina_thread_queue_parent_get(). If no parent
* This gets the parent set by eina_thread_queue_parent_get(). If no parent
* is set, NULL is returned.
*
* @see eina_thread_queue_parent_set()
@ -222,14 +222,14 @@ EAPI Eina_Thread_Queue *
eina_thread_queue_parent_get(const Eina_Thread_Queue *thq) EINA_ARG_NONNULL(1);
/**
* @brief Set a file descriptor to write a byte to on a message send
* @brief Sets a file descriptor to write a byte to on a message send.
*
* @param thq The thread queue to set the file descriptor of
* @param fd The fd to set, or -1 to unset it
*
* This sets a file descriptor to write to when a message is written to the
* thread queue. This can be used to glue a thread queue to something like
* an Ecore_Pipe that can wake up the mainloop and call a callbck whenever
* an Ecore_Pipe that can wake up the mainloop and call a callback whenever
* data is available on the pipe. The number of bytes available will be
* the number of messages to fetch from the associated thread queue.
*
@ -242,7 +242,7 @@ EAPI void
eina_thread_queue_fd_set(Eina_Thread_Queue *thq, int fd) EINA_ARG_NONNULL(1);
/**
* @brief Get the file descriptor written to on message sends
* @brief Gets the file descriptor written to on message sends.
*
* @param thq The thread queue to get the file descriptor of
* @return The file descriptor set (or -1 if none is set).

36
src/lib/eina/eina_tiler.h
View File

@ -207,7 +207,7 @@ EAPI void eina_tiler_free(Eina_Tiler *t);
EAPI void eina_tiler_tile_size_set(Eina_Tiler *t, int w, int h);
/**
* @brief Change the size of the area covered by the tiler.
* @brief Changes the size of the area covered by the tiler.
*
* @param t The tiler whose area size will be set.
* @param w Width of the area.
@ -220,7 +220,7 @@ EAPI void eina_tiler_tile_size_set(Eina_Tiler *t, int w, int h);
EAPI void eina_tiler_area_size_set(Eina_Tiler *t, int w, int h);
/**
* @brief Get the size of the area covered by the tiler.
* @brief Gets the size of the area covered by the tiler.
*
* @param t The tiler whose area size will be fetched.
* @param w Width of the area.
@ -231,19 +231,19 @@ EAPI void eina_tiler_area_size_set(Eina_Tiler *t, int w, int h);
EAPI void eina_tiler_area_size_get(const Eina_Tiler *t, int *w, int *h);
/**
* @brief Define if we need to follow a strict grid of tile or a loosy one
* @brief Defines if we need to follow a strict grid of tile or a loose one.
*
* @param t The tiler to apply the strict rules to.
* @param strict Define if it will be strict or loosy
* @param strict Define if it will be strict or loose
*
* By default it will be loosy.
* By default it will be loose.
*
* @since 1.8
*/
EAPI void eina_tiler_strict_set(Eina_Tiler *t, Eina_Bool strict);
/**
* @brief Tell if a tiler is empty or not
* @brief Tells if a tiler is empty or not.
*
* @param t The tiler to apply the strict rules to.
* @return EINA_TRUE when empty, EINA_FALSE when not.
@ -281,7 +281,7 @@ EAPI void eina_tiler_rect_del(Eina_Tiler *t, const Eina_Rectangle
*/
EAPI void eina_tiler_clear(Eina_Tiler *t);
/**
* @brief Create a iterator to access the tilers calculated rectangles.
* @brief Creates a iterator to access the tilers calculated rectangles.
*
* @param t The tiler to iterate over.
* @return A iterator containing Eina_Rectangle.
@ -293,10 +293,10 @@ EAPI Eina_Iterator *eina_tiler_iterator_new(const Eina_Tiler *t);
*
* @param x X axis coordinate.
* @param y Y axis coordinate.
* @param w width.
* @param h height.
* @param tile_w tile width.
* @param tile_h tile height.
* @param w Width.
* @param h Height.
* @param tile_w Tile width.
* @param tile_h Tile height.
* @return A pointer to the Eina_Iterator. @c NULL on failure.
*
* The region defined by @a x, @a y, @a w, @a h will be divided in to a grid of
@ -305,7 +305,7 @@ EAPI Eina_Iterator *eina_tiler_iterator_new(const Eina_Tiler *t);
*
* @note This is a convenience function, iterating over the returned iterator is
* equivalent to calling eina_tile_grid_slicer_setup() and calling
* eina_tile_grid_slicer_next() untill it returns #EINA_FALSE.
* eina_tile_grid_slicer_next() until it returns #EINA_FALSE.
*/
EAPI Eina_Iterator *eina_tile_grid_slicer_iterator_new(int x, int y, int w, int h, int tile_w, int tile_h);
@ -377,16 +377,16 @@ EAPI Eina_Bool eina_tiler_equal(Eina_Tiler *t1, Eina_Tiler *t2);
*/
static inline Eina_Bool eina_tile_grid_slicer_next(Eina_Tile_Grid_Slicer *slc, const Eina_Tile_Grid_Info **rect);
/**
* @brief Setup an Eina_Tile_Grid_Slicer struct.
* @brief Sets up an Eina_Tile_Grid_Slicer struct.
*
* @param slc Pointer to an Eina_Tile_Grid_Slicer struct.
* @param x X axis coordinate.
* @param y Y axis coordinate.
* @param w width.
* @param h height.
* @param tile_w tile width.
* @param tile_h tile height.
* @return A pointer to the Eina_Iterator. @c NULL on failure.
* @param w Width.
* @param h Height.
* @param tile_w Tile width.
* @param tile_h Tile height.
* @return A pointer to the Eina_Iterator, @c NULL on failure.
*
* The region defined by @a x, @a y, @a w, @a h will be divided in to a grid of
* tiles of width @a tile_w and height @p tile_h, @p slc can then be used with

24
src/lib/eina/eina_tmpstr.h
View File

@ -58,11 +58,11 @@
*
* Eina tmpstr is intended for being able to conveniently pass strings back
* to a calling parent without having to use single static buffers (which
* don't work with multiple threads or when returning multilpe times as
* don't work with multiple threads or when returning multiple times as
* parameters to a single function.
*
* The traditional way to "return" a string in C is either to provide a buffer
* as a paramater to return it in, return a pointer to a single static buffer,
* as a parameter to return it in, return a pointer to a single static buffer,
* which has issues, or return a duplicated string. All cases are inconvenient
* and return special handling. This is intended to make this easier. Now you
* can do something like this:
@ -121,7 +121,7 @@
typedef const char Eina_Tmpstr;
/**
* @brief Add a new temporary string based on the input string.
* @brief Adds a new temporary string based on the input string.
*
* @param str This is the input stringthat is copied into the temp string.
* @return A pointer to the tmp string that is a standard C string.
@ -165,7 +165,7 @@ typedef const char Eina_Tmpstr;
EAPI Eina_Tmpstr *eina_tmpstr_add(const char *str) EINA_WARN_UNUSED_RESULT;
/**
* @brief Add a new temporary string based on the input string and length.
* @brief Adds a new temporary string based on the input string and length.
*
* @param str This is the input string that is copied into the temp string.
* @param length This is the maximum length and the allocated length of the temp string.
@ -202,7 +202,7 @@ EAPI Eina_Tmpstr *eina_tmpstr_add_length(const char *str, size_t length);
*
* @param tmpstr This is any C string pointer, but if it is a tmp string
* it will return the length faster.
* @return The length of the string including the '\0';
* @return The length of the string including the '\0'
*
* @deprecated
* @see eina_tmpstr_len()
@ -211,7 +211,7 @@ EAPI Eina_Tmpstr *eina_tmpstr_add_length(const char *str, size_t length);
EINA_DEPRECATED EAPI size_t eina_tmpstr_strlen(Eina_Tmpstr *tmpstr);
/**
* @brief Return the length of a temporary string.
* @brief Returns the length of a temporary string.
*
* @param tmpstr This is any C string pointer, but if it is a tmp string
* it will return the length faster.
@ -222,7 +222,7 @@ EINA_DEPRECATED EAPI size_t eina_tmpstr_strlen(Eina_Tmpstr *tmpstr);
EAPI size_t eina_tmpstr_len(Eina_Tmpstr *tmpstr);
/**
* @brief Delete the temporary string if it is one, or ignore it if it is not.
* @brief Deletes the temporary string if it is one, or ignore it if it is not.
*
* @param tmpstr This is any C string pointer, but if it is a tmp string
* it is freed.
@ -238,10 +238,10 @@ EAPI size_t eina_tmpstr_len(Eina_Tmpstr *tmpstr);
EAPI void eina_tmpstr_del(Eina_Tmpstr *tmpstr) EINA_ARG_NONNULL(1);
/**
* @brief Add a new temporary string using the passed string. The passed
* @brief Adds a new temporary string using the passed string. The passed
* string is used directly as the buffer. The passed string must be malloced.
*
* @param str the input string to manage.
* @param str The input string to manage.
* @return A pointer to the tmp string that is a standard C string.
*
* This function creates a new temporary string. On error, @c NULL is
@ -253,11 +253,11 @@ EAPI void eina_tmpstr_del(Eina_Tmpstr *tmpstr) EINA_ARG_NONNULL(1);
EAPI Eina_Tmpstr *eina_tmpstr_manage_new(char *str) EINA_WARN_UNUSED_RESULT;
/**
* @brief Add a new temporary string using the passed string. The passed
* @brief Adds a new temporary string using the passed string. The passed
* string is used directly as the buffer. The passed string must be malloced.
*
* @param str the input string to manage.
* @param length the length of the string.
* @param str The input string to manage.
* @param length The length of the string.
* @return A pointer to the tmp string that is a standard C string.
*
* This function creates a new temporary string. On error, @c NULL is

26
src/lib/eina/eina_trash.h
View File

@ -29,7 +29,7 @@
/**
* @typedef Eina_Trash
* @brief The type for strcuture #_Eina_Trash.
* @brief The type for structure #_Eina_Trash.
*/
typedef struct _Eina_Trash Eina_Trash;
@ -44,12 +44,11 @@ struct _Eina_Trash
/**
* @brief Initializes a trash before using it.
*
* @param[in] trash The trash
*
* @details This function just set to zero the trash to correctly
* initialize it.
*
* @param[in] trash The trash
*
* @note You can just set *trash to @c NULL and you will have
* the same result.
*/
@ -57,14 +56,13 @@ static inline void eina_trash_init(Eina_Trash **trash) EINA_ARG_NONNULL(1);
/**
* @brief Pushes an unused pointer in the trash instead of freeing it.
*
* @param[in] trash A pointer to an Eina_Trash
* @param data An unused pointer big enougth to put a (void*)
*
* @details Instead of freeing a pointer and put pressure on malloc/free
* you can push it in a trash for a later use. This function just
* provide a fast way to push a now unused pointer into a trash.
*
* @param[in] trash A pointer to an Eina_Trash
* @param data An unused pointer big enough to put a (void*)
*
* @note Do not use the pointer after insertion or bad things will
* happens.
*
@ -75,12 +73,11 @@ static inline void eina_trash_push(Eina_Trash **trash, void *data) EINA_ARG_NON
/**
* @brief Pops an available pointer from the trash if possible.
*
* @param[in] trash A #Eina_Trash handle
*
* @details Instead of calling malloc, and putting pressure on malloc/free
* you can recycle the content of the trash, if it's not empty.
*
* @param[in] trash A #Eina_Trash handle
*
* @note This trash will not resize, nor do anything with the size of
* the region pointed by pointer inside the trash, so it's your duty
* to manage the size of the returned pointer.
@ -89,14 +86,13 @@ static inline void *eina_trash_pop(Eina_Trash **trash) EINA_ARG_NONNULL(1) EINA_
/**
* @def EINA_TRASH_CLEAN
* @brief Definition of a macro to remove all the pointers from the trash.
* @brief Definition for a macro to remove all the pointers from the trash.
* @details This macro allows the cleaning of @a trash in an easy way. It
* removes all the pointers from @a trash until it's empty.
*
* @param trash The trash to clean
* @param data The pointer extracted from the trash
*
* @details This macro allows the cleaning of @a trash in an easy way. It
* removes all the pointers from @a trash until it's empty.
*
* @note This macro can be used for freeing the data in the trash, like in
* the following example:
*

4
src/lib/eina/eina_types.h
View File

@ -293,7 +293,7 @@
*
* @param ... Oridnals of the parameters to check for nullity (1..n)
*
* @returns Nothing, but Doxygen will complain if it's not documented :-P
* @return Nothing, but Doxygen will complain if it's not documented :-P
*
*/
# define EINA_ARG_NONNULL(...)
@ -454,7 +454,7 @@ typedef int (*Eina_Compare_Cb)(const void *data1, const void *data2);
/**
* @typedef Eina_Random_Cb
* Function used in shuffling functions. An integer betwen min and max
* Function used in shuffling functions. An integer between min and max
* inclusive must be returned.
*
* @since 1.8

2
src/lib/eina/eina_unicode.h
View File

@ -127,6 +127,7 @@ EAPI Eina_Unicode *eina_unicode_escape(const Eina_Unicode *str) EINA_ARG_NONNULL
static inline Eina_Unicode eina_unicode_utf8_next_get(const char *buf, int *iindex) EINA_ARG_NONNULL(1, 2);
/**
* @deprecated use eina_unicode_utf8_next_get
* Reads UTF8 bytes from @p buf, starting at @p iindex and returns
* the decoded code point at @p iindex offset, and advances @p iindex
* to the next code point after this. @p iindex is always advanced,
@ -138,7 +139,6 @@ static inline Eina_Unicode eina_unicode_utf8_next_get(const char *buf, int *iind
* @param iindex the index to look at and return by.
* @return the codepoint found, 0 if @p buf or @p iindex are NULL
* @since 1.1.0
* @deprecated use eina_unicode_utf8_next_get
*/
EAPI Eina_Unicode eina_unicode_utf8_get_next(const char *buf, int *iindex) EINA_ARG_NONNULL(1, 2) EINA_DEPRECATED;

78
src/lib/eina/eina_ustrbuf.h
View File

@ -34,7 +34,7 @@
typedef struct _Eina_Strbuf Eina_UStrbuf;
/**
* @brief Create a new string buffer.
* @brief Creates a new string buffer.
*
* @return Newly allocated string buffer instance.
*
@ -48,12 +48,12 @@ typedef struct _Eina_Strbuf Eina_UStrbuf;
EAPI Eina_UStrbuf *eina_ustrbuf_new(void) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
/**
* @brief Create a new string buffer using the passed string. The passed
* @brief Creates a new string buffer using the passed string. The passed
* string is used directly as the buffer, it's somehow the opposite function of
* @ref eina_ustrbuf_string_steal . The passed string must be malloced.
*
* @param str the string to manage
* @return Newly allocated string buffer instance.
* @param str The string to manage
* @return Newly allocated string buffer instance
*
* This function creates a new string buffer. On error, @c NULL is
* returned. To free the resources, use eina_strbuf_free().
@ -66,12 +66,12 @@ EAPI Eina_UStrbuf *eina_ustrbuf_new(void) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
EAPI Eina_UStrbuf *eina_ustrbuf_manage_new(Eina_Unicode *str) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
/**
* @brief Create a new string buffer using the passed string. The passed
* @brief Creates a new string buffer using the passed string. The passed
* string is used directly as the buffer, it's somehow the opposite function of
* @ref eina_ustrbuf_string_steal . The passed string must be malloced.
*
* @param str the string to manage
* @param length the length of the string.
* @param str The string to manage
* @param length The length of the string.
* @return Newly allocated string buffer instance.
*
* This function creates a new string buffer. On error, @c NULL is
@ -83,7 +83,7 @@ EAPI Eina_UStrbuf *eina_ustrbuf_manage_new(Eina_Unicode *str) EINA_MALLOC EINA_W
EAPI Eina_UStrbuf *eina_ustrbuf_manage_new_length(Eina_Unicode *str, size_t length) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
/**
* @brief Free a string buffer.
* @brief Frees a string buffer.
*
* @param buf The string buffer to free.
*
@ -93,7 +93,7 @@ EAPI Eina_UStrbuf *eina_ustrbuf_manage_new_length(Eina_Unicode *str, size_t leng
EAPI void eina_ustrbuf_free(Eina_UStrbuf *buf) EINA_ARG_NONNULL(1);
/**
* @brief Reset a string buffer.
* @brief Resets a string buffer.
*
* @param buf The string buffer to reset.
*
@ -103,7 +103,7 @@ EAPI void eina_ustrbuf_free(Eina_UStrbuf *buf) EINA_ARG_NONNULL(1);
EAPI void eina_ustrbuf_reset(Eina_UStrbuf *buf) EINA_ARG_NONNULL(1);
/**
* @brief Append a string to a buffer, reallocating as necessary.
* @brief Appends a string to a buffer, reallocating as necessary.
*
* @param buf The string buffer to append to.
* @param str The string to append.
@ -121,7 +121,7 @@ EAPI void eina_ustrbuf_reset(Eina_UStrbuf *buf) EINA_ARG_NONNULL(1);
EAPI Eina_Bool eina_ustrbuf_append(Eina_UStrbuf *buf, const Eina_Unicode *str) EINA_ARG_NONNULL(1, 2);
/**
* @brief Append an escaped string to a buffer, reallocating as necessary.
* @brief Appends an escaped string to a buffer, reallocating as necessary.
*
* @param buf The string buffer to append to.
* @param str The string to append.
@ -134,7 +134,7 @@ EAPI Eina_Bool eina_ustrbuf_append(Eina_UStrbuf *buf, const Eina_Unicode *str) E
EAPI Eina_Bool eina_ustrbuf_append_escaped(Eina_UStrbuf *buf, const Eina_Unicode *str) EINA_ARG_NONNULL(1, 2);
/**
* @brief Append a string to a buffer, reallocating as necessary,
* @brief Appends a string to a buffer, reallocating as necessary,
* limited by the given length.
*
* @param buf The string buffer to append to.
@ -157,7 +157,7 @@ EAPI Eina_Bool eina_ustrbuf_append_escaped(Eina_UStrbuf *buf, const Eina_Unicode
EAPI Eina_Bool eina_ustrbuf_append_n(Eina_UStrbuf *buf, const Eina_Unicode *str, size_t maxlen) EINA_ARG_NONNULL(1, 2);
/**
* @brief Append a string of exact length to a buffer, reallocating as necessary.
* @brief Appends a string of exact length to a buffer, reallocating as necessary.
*
* @param buf The string buffer to append to.
* @param str The string to append.
@ -178,7 +178,7 @@ EAPI Eina_Bool eina_ustrbuf_append_n(Eina_UStrbuf *buf, const Eina_Unicode *str,
EAPI Eina_Bool eina_ustrbuf_append_length(Eina_UStrbuf *buf, const Eina_Unicode *str, size_t length) EINA_ARG_NONNULL(1, 2);
/**
* @brief Append a slice to a buffer, reallocating as necessary.
* @brief Appends a slice to a buffer, reallocating as necessary.
*
* @param buf The string buffer to append to.
* @param slice The slice to append.
@ -192,7 +192,7 @@ EAPI Eina_Bool eina_ustrbuf_append_length(Eina_UStrbuf *buf, const Eina_Unicode
EAPI Eina_Bool eina_ustrbuf_append_slice(Eina_UStrbuf *buf, const Eina_Slice slice) EINA_ARG_NONNULL(1);
/**
* @brief Append a character to a string buffer, reallocating as
* @brief Appends a character to a string buffer, reallocating as
* necessary.
*
* @param buf The string buffer to append to.
@ -205,7 +205,7 @@ EAPI Eina_Bool eina_ustrbuf_append_slice(Eina_UStrbuf *buf, const Eina_Slice sli
EAPI Eina_Bool eina_ustrbuf_append_char(Eina_UStrbuf *buf, Eina_Unicode c) EINA_ARG_NONNULL(1);
/**
* @brief Insert a string to a buffer, reallocating as necessary.
* @brief Inserts a string to a buffer, reallocating as necessary.
*
* @param buf The string buffer to insert.
* @param str The string to insert.
@ -221,7 +221,7 @@ EAPI Eina_Bool eina_ustrbuf_append_char(Eina_UStrbuf *buf, Eina_Unicode c) EINA_
EAPI Eina_Bool eina_ustrbuf_insert(Eina_UStrbuf *buf, const Eina_Unicode *str, size_t pos) EINA_ARG_NONNULL(1, 2);
/**
* @brief Insert an escaped string to a buffer, reallocating as
* @brief Inserts an escaped string to a buffer, reallocating as
* necessary.
*
* @param buf The string buffer to insert to.
@ -236,7 +236,7 @@ EAPI Eina_Bool eina_ustrbuf_insert(Eina_UStrbuf *buf, const Eina_Unicode *str, s
EAPI Eina_Bool eina_ustrbuf_insert_escaped(Eina_UStrbuf *buf, const Eina_Unicode *str, size_t pos) EINA_ARG_NONNULL(1, 2);
/**
* @brief Insert a string to a buffer, reallocating as necessary. Limited by maxlen.
* @brief Inserts a string to a buffer, reallocating as necessary. Limited by maxlen.
*
* @param buf The string buffer to insert to.
* @param str The string to insert.
@ -256,7 +256,7 @@ EAPI Eina_Bool eina_ustrbuf_insert_escaped(Eina_UStrbuf *buf, const Eina_Unicode
EAPI Eina_Bool eina_ustrbuf_insert_n(Eina_UStrbuf *buf, const Eina_Unicode *str, size_t maxlen, size_t pos) EINA_ARG_NONNULL(1, 2);
/**
* @brief Insert a string of exact length to a buffer, reallocating as necessary.
* @brief Inserts a string of exact length to a buffer, reallocating as necessary.
*
* @param buf The string buffer to insert to.
* @param str The string to insert.
@ -278,7 +278,7 @@ EAPI Eina_Bool eina_ustrbuf_insert_n(Eina_UStrbuf *buf, const Eina_Unicode *str,
EAPI Eina_Bool eina_ustrbuf_insert_length(Eina_UStrbuf *buf, const Eina_Unicode *str, size_t length, size_t pos) EINA_ARG_NONNULL(1, 2);
/**
* @brief Insert a slice to a buffer, reallocating as necessary.
* @brief Inserts a slice to a buffer, reallocating as necessary.
*
* @param buf The string buffer to insert to.
* @param slice The slice to insert.
@ -294,7 +294,7 @@ EAPI Eina_Bool eina_ustrbuf_insert_length(Eina_UStrbuf *buf, const Eina_Unicode
EAPI Eina_Bool eina_ustrbuf_insert_slice(Eina_UStrbuf *buf, const Eina_Slice slice, size_t pos) EINA_ARG_NONNULL(1);
/**
* @brief Insert a character to a string buffer, reallocating as
* @brief Inserts a character to a string buffer, reallocating as
* necessary.
*
* @param buf The string buffer to insert to.
@ -310,7 +310,7 @@ EAPI Eina_Bool eina_ustrbuf_insert_char(Eina_UStrbuf *buf, Eina_Unicode c, size_
/**
* @def eina_ustrbuf_prepend(buf, str)
* @brief Prepend the given string to the given buffer
* @brief Prepends the given string to the given buffer.
*
* @param buf The string buffer to prepend to.
* @param str The string to prepend.
@ -324,7 +324,7 @@ EAPI Eina_Bool eina_ustrbuf_insert_char(Eina_UStrbuf *buf, Eina_Unicode c, size_
/**
* @def eina_ustrbuf_prepend_escaped(buf, str)
* @brief Prepend the given escaped string to the given buffer
* @brief Prepends the given escaped string to the given buffer.
*
* @param buf The string buffer to prepend to.
* @param str The string to prepend.
@ -338,7 +338,7 @@ EAPI Eina_Bool eina_ustrbuf_insert_char(Eina_UStrbuf *buf, Eina_Unicode c, size_
/**
* @def eina_ustrbuf_prepend_n(buf, str)
* @brief Prepend the given escaped string to the given buffer
* @brief Prepends the given escaped string to the given buffer.
*
* @param buf The string buffer to prepend to.
* @param str The string to prepend.
@ -353,7 +353,7 @@ EAPI Eina_Bool eina_ustrbuf_insert_char(Eina_UStrbuf *buf, Eina_Unicode c, size_
/**
* @def eina_ustrbuf_prepend_length(buf, str)
* @brief Prepend the given escaped string to the given buffer
* @brief Prepends the given escaped string to the given buffer.
*
* @param buf The string buffer to prepend to.
* @param str The string to prepend.
@ -368,7 +368,7 @@ EAPI Eina_Bool eina_ustrbuf_insert_char(Eina_UStrbuf *buf, Eina_Unicode c, size_
/**
* @def eina_ustrbuf_prepend_char(buf, c)
* @brief Prepend the given unicode character to the given buffer
* @brief Prepends the given unicode character to the given buffer.
*
* @param buf The string buffer to prepend to.
* @param c The Eina_Unicode character to prepend.
@ -381,7 +381,7 @@ EAPI Eina_Bool eina_ustrbuf_insert_char(Eina_UStrbuf *buf, Eina_Unicode c, size_
#define eina_ustrbuf_prepend_char(buf, c) eina_ustrbuf_insert_char(buf, c, 0)
/**
* @brief Remove a slice of the given string buffer.
* @brief Removes a slice of the given string buffer.
*
* @param buf The string buffer to remove a slice.
* @param start The initial (inclusive) slice position to start
@ -398,7 +398,7 @@ EAPI Eina_Bool
eina_ustrbuf_remove(Eina_UStrbuf *buf, size_t start, size_t end) EINA_ARG_NONNULL(1);
/**
* @brief Retrieve a pointer to the contents of a string buffer
* @brief Retrieves a pointer to the contents of a string buffer.
*
* @param buf The string buffer.
* @return The current string in the string buffer.
@ -414,7 +414,7 @@ EAPI const Eina_Unicode *
eina_ustrbuf_string_get(const Eina_UStrbuf *buf) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
/**
* @brief Steal the contents of a string buffer.
* @brief Steals the contents of a string buffer.
*
* @param buf The string buffer to steal.
* @return The current string in the string buffer.
@ -430,7 +430,7 @@ EAPI Eina_Unicode *
eina_ustrbuf_string_steal(Eina_UStrbuf *buf) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
/**
* @brief Free the contents of a string buffer but not the buffer.
* @brief Frees the contents of a string buffer but not the buffer.
*
* @param buf The string buffer to free the string of.
*
@ -441,7 +441,7 @@ EAPI void
eina_ustrbuf_string_free(Eina_UStrbuf *buf) EINA_ARG_NONNULL(1);
/**
* @brief Retrieve the length of the string buffer content.
* @brief Retrieves the length of the string buffer content.
*
* @param buf The string buffer.
* @return The current length of the string, in bytes.
@ -452,10 +452,10 @@ EAPI size_t
eina_ustrbuf_length_get(const Eina_UStrbuf *buf) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
/**
* @brief Get a read-only slice representing the current ustrbuf contents.
* @brief Gets a read-only slice representing the current ustrbuf contents.
*
* @param buf the source string.
* @return a read-only slice for the current contents. It may become
* @param buf The source string.
* @return A read-only slice for the current contents. It may become
* invalid as soon as the @a buf is changed.
*
* @since 1.19
@ -463,10 +463,10 @@ eina_ustrbuf_length_get(const Eina_UStrbuf *buf) EINA_ARG_NONNULL(1) EINA_WARN_U
EAPI Eina_Slice eina_ustrbuf_slice_get(const Eina_UStrbuf *buf) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
/**
* @brief Get a read-write slice representing the current ustrbuf contents.
* @brief Gets a read-write slice representing the current ustrbuf contents.
*
* @param buf the source string.
* @return a read-write slice for the current contents. It may become
* @param buf The source string.
* @return A read-write slice for the current contents. It may become
* invalid as soon as the @a buf is changed with calls such as
* eina_ustrbuf_append(), eina_ustrbuf_remove()
*
@ -475,9 +475,9 @@ EAPI Eina_Slice eina_ustrbuf_slice_get(const Eina_UStrbuf *buf) EINA_WARN_UNUSED
EAPI Eina_Rw_Slice eina_ustrbuf_rw_slice_get(const Eina_UStrbuf *buf) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
/**
* @brief Get the string of the buffer and free the buffer
* @brief Gets the string of the buffer and free the buffer
*
* @param buf the buffer to get the string from and which will be freed
* @param buf The buffer to get the string from and which will be freed
*
* @return The string contained by buf. The caller must release the memory of the returned string by calling
* free().

26
src/lib/eina/eina_ustringshare.h
View File

@ -29,9 +29,9 @@
*
* The above copyright notice and this permission notice shall be included in
* all copies of the Software and its Copyright notices. In addition publicly
* documented acknowledgment must be given that this software has been used if no
* documented acknowledgement must be given that this software has been used if no
* source code of this software is made available publicly. This includes
* acknowledgments in either Copyright notices, Manuals, Publicity and Marketing
* acknowledgements in either Copyright notices, Manuals, Publicity and Marketing
* documents or any documentation provided with any product containing this
* software. This License does not apply to any software that links to the
* libraries provided by this software (statically or dynamically), but only to
@ -90,11 +90,11 @@
/**
* @brief Retrieve an instance of a string for use in a program.
* @brief Retrieves an instance of a string for use in a program.
*
* @param str The string to retrieve an instance of.
* @param slen The string size (<= strlen(str)).
* @return A pointer to an instance of the string on success.
* @return A pointer to an instance of the string on success,
* @c NULL on failure.
*
* This function retrieves an instance of @p str. If @p str is
@ -112,10 +112,10 @@
EAPI const Eina_Unicode *eina_ustringshare_add_length(const Eina_Unicode *str, unsigned int slen) EINA_WARN_UNUSED_RESULT;
/**
* @brief Retrieve an instance of a string for use in a program.
* @brief Retrieves an instance of a string for use in a program.
*
* @param str The NULL-terminated string to retrieve an instance of.
* @return A pointer to an instance of the string on success.
* @return A pointer to an instance of the string on success,
* @c NULL on failure.
*
* This function retrieves an instance of @p str. If @p str is
@ -133,10 +133,10 @@ EAPI const Eina_Unicode *eina_ustringshare_add_length(const Eina_Unicode *str, u
EAPI const Eina_Unicode *eina_ustringshare_add(const Eina_Unicode *str) EINA_WARN_UNUSED_RESULT;
/**
* Increment references of the given shared string.
* @brief Increments references of the given shared string.
*
* @param str The shared string.
* @return A pointer to an instance of the string on success.
* @return A pointer to an instance of the string on success,
* @c NULL on failure.
*
* This is similar to eina_share_common_add(), but it's faster since it will
@ -149,9 +149,9 @@ EAPI const Eina_Unicode *eina_ustringshare_add(const Eina_Unicode *str) EINA_WAR
EAPI const Eina_Unicode *eina_ustringshare_ref(const Eina_Unicode *str);
/**
* @brief Note that the given string has lost an instance.
* @brief Notes that the given string has lost an instance.
*
* @param str string The given string.
* @param str String The given string.
*
* This function decreases the reference counter associated to @p str
* if it exists. If that counter reaches 0, the memory associated to
@ -164,9 +164,9 @@ EAPI const Eina_Unicode *eina_ustringshare_ref(const Eina_Unicode *str);
EAPI void eina_ustringshare_del(const Eina_Unicode *str);
/**
* @brief Note that the given string @b must be shared.
* @brief Notes that the given string @b must be shared.
*
* @param str the shared string to know the length. It is safe to
* @param str The shared string to know the length. It is safe to
* give @c NULL, in that case @c -1 is returned.
*
* This function is a cheap way to known the length of a shared
@ -178,7 +178,7 @@ EAPI void eina_ustringshare_del(const Eina_Unicode *str);
EAPI int eina_ustringshare_strlen(const Eina_Unicode *str) EINA_PURE EINA_WARN_UNUSED_RESULT;
/**
* @brief Dump the contents of the share_common.
* @brief Dumps the contents of the share_common.
*
* This function dumps all strings in the share_common to stdout with a
* DDD: prefix per line and a memory usage summary.

8
src/lib/eina/eina_util.h
View File

@ -29,7 +29,7 @@
*/
/**
* @brief Return the content of the environment refered by HOME on this system.
* @brief Returns the content of the environment referred by HOME on this system.
* @return A temporary string to the content refered by HOME on this system.
*
* @note The result of this call is highly system dependent and you better use
@ -40,7 +40,7 @@
EAPI const char *eina_environment_home_get(void);
/**
* @brief Return the content of the environment refered as TMPDIR on this system.
* @brief Returns the content of the environment referred as TMPDIR on this system.
* @return A temporary string to the content refered by TMPDIR on this system.
*
* @note The result of this call is highly system dependent and you better use
@ -81,7 +81,7 @@ static inline Eina_Bool eina_flt_exact(float a, float b);
#define EINA_FLT_EQ(a, b) (!!(fabsf((float)a - (float)b) <= FLT_EPSILON))
/**
* @brief Determine if a float is not zero
* @brief Determines if a float is not zero
* @param a The float
*
* @return @c true if float is not zero
@ -100,7 +100,7 @@ static inline Eina_Bool eina_flt_exact(float a, float b);
#define EINA_DBL_EQ(a, b) (!!(fabs((double)a - (double)b) <= DBL_EPSILON))
/**
* @brief Determine if a double is not zero
* @brief Determines if a double is not zero
* @param a The double
*
* @return @c true if double is not zero

470
src/lib/eina/eina_value.h
View File

File diff suppressed because it is too large Load Diff

4
src/lib/eina/eina_value_util.h
View File

@ -29,14 +29,14 @@
*/
/**
* @brief Create a basic #Eina_Value struct desc with refcounting
* @brief Creates a basic #Eina_Value struct desc with refcounting.
* @return The #Eina_Value_Struct_Desc on success, @c NULL on failure
* @since 1.12
*/
EAPI Eina_Value_Struct_Desc *eina_value_util_struct_desc_new(void);
/**
* @brief Create a new #Eina_Value containing the passed parameter
* @brief Creates a new #Eina_Value containing the passed parameter.
* @param timestr The value to use
* @return The #Eina_Value
* @since 1.12

40
src/lib/eina/eina_xattr.h
View File

@ -49,7 +49,7 @@ struct _Eina_Xattr
};
/**
* @brief Get an iterator that list all extended attribute of a file.
* @brief Gets an iterator that list all extended attribute of a file.
*
* @param file The filename to retrieve the extended attribute list from.
* @return an iterator.
@ -62,10 +62,10 @@ struct _Eina_Xattr
EAPI Eina_Iterator *eina_xattr_ls(const char *file) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
/**
* @brief Get an iterator that list all extended attribute value related to a fd.
* @brief Gets an iterator that list all extended attribute value related to a fd.
*
* @param file The filename to retrieve the extended attribute list from.
* @return an iterator.
* @return An iterator.
*
* The iterator will not allocate any data during the iteration step, so you need to copy them yourself
* if you need. The iterator will provide an Eina_Xattr structure.
@ -75,7 +75,7 @@ EAPI Eina_Iterator *eina_xattr_ls(const char *file) EINA_ARG_NONNULL(1) EINA_WAR
EAPI Eina_Iterator *eina_xattr_value_ls(const char *file) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
/**
* @brief Get an iterator that list all extended attribute related to a fd.
* @brief Gets an iterator that list all extended attribute related to a fd.
*
* @param fd The file descriptor to retrieve the extended attribute list from.
* @return an iterator.
@ -88,10 +88,10 @@ EAPI Eina_Iterator *eina_xattr_value_ls(const char *file) EINA_ARG_NONNULL(1) EI
EAPI Eina_Iterator *eina_xattr_fd_ls(int fd) EINA_WARN_UNUSED_RESULT;
/**
* @brief Get an iterator that list all extended attribute value related to a fd.
* @brief Gets an iterator that list all extended attribute value related to a fd.
*
* @param fd The file descriptor to retrieve the extended attribute list from.
* @return an iterator.
* @return An iterator.
*
* The iterator will not allocate any data during the iteration step, so you need to copy them yourself
* if you need. The iterator will provide an Eina_Xattr structure.
@ -101,7 +101,7 @@ EAPI Eina_Iterator *eina_xattr_fd_ls(int fd) EINA_WARN_UNUSED_RESULT;
EAPI Eina_Iterator *eina_xattr_value_fd_ls(int fd) EINA_WARN_UNUSED_RESULT;
/**
* @brief Copy the extended attribute from one file to another.
* @brief Copies the extended attribute from one file to another.
* @param src source file to use as input.
* @param dst destination file to use as output.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
@ -111,7 +111,7 @@ EAPI Eina_Iterator *eina_xattr_value_fd_ls(int fd) EINA_WARN_UNUSED_RESULT;
EAPI Eina_Bool eina_xattr_copy(const char *src, const char *dst) EINA_ARG_NONNULL(1, 2);
/**
* @brief Copy the extended attribute from one file descriptor to another.
* @brief Copies the extended attribute from one file descriptor to another.
* @param src source file descriptor to use as input.
* @param dst destination file descriptor to use as output.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
@ -121,7 +121,7 @@ EAPI Eina_Bool eina_xattr_copy(const char *src, const char *dst) EINA_ARG_NONNUL
EAPI Eina_Bool eina_xattr_fd_copy(int src, int dst);
/**
* @brief Retrieve an extended attribute from a file.
* @brief Retrieves an extended attribute from a file.
*
* @param file The file to retrieve the extended attribute from.
* @param attribute The extended attribute name to retrieve.
@ -135,7 +135,7 @@ EAPI Eina_Bool eina_xattr_fd_copy(int src, int dst);
EAPI void *eina_xattr_get(const char *file, const char *attribute, ssize_t *size) EINA_ARG_NONNULL(1, 2, 3) EINA_WARN_UNUSED_RESULT;
/**
* @brief Retrieve an extended attribute from a file descriptor.
* @brief Retrieves an extended attribute from a file descriptor.
*
* @param fd The file descriptor to retrieve the extended attribute from.
* @param attribute The extended attribute name to retrieve.
@ -149,7 +149,7 @@ EAPI void *eina_xattr_get(const char *file, const char *attribute, ssize_t *size
EAPI void *eina_xattr_fd_get(int fd, const char *attribute, ssize_t *size) EINA_ARG_NONNULL(2, 3) EINA_WARN_UNUSED_RESULT;
/**
* @brief Set an extended attribute on a file.
* @brief Sets an extended attribute on a file.
*
* @param file The file to set the extended attribute to.
* @param attribute The attribute to set.
@ -163,7 +163,7 @@ EAPI void *eina_xattr_fd_get(int fd, const char *attribute, ssize_t *size) EINA_
EAPI Eina_Bool eina_xattr_set(const char *file, const char *attribute, const void *data, ssize_t length, Eina_Xattr_Flags flags) EINA_ARG_NONNULL(1, 2, 3);
/**
* @brief Set an extended attribute on a file descriptor.
* @brief Sets an extended attribute on a file descriptor.
*
* @param fd The file descriptor to set the extended attribute to.
* @param attribute The attribute to set.
@ -178,7 +178,7 @@ EAPI Eina_Bool eina_xattr_fd_set(int fd, const char *attribute, const void *data
/**
* @brief Delete (remove) an extended attribute from a file.
* @brief Deletes (removes) an extended attribute from a file.
*
* @param file The file to del the extended attribute from.
* @param attribute The attribute to del.
@ -189,7 +189,7 @@ EAPI Eina_Bool eina_xattr_fd_set(int fd, const char *attribute, const void *data
EAPI Eina_Bool eina_xattr_del(const char *file, const char *attribute) EINA_ARG_NONNULL(1, 2);
/**
* @brief Delete (remove) an extended attribute from a file descriptor.
* @brief Deletes (removes) an extended attribute from a file descriptor.
*
* @param fd The file descriptor to del the extended attribute from.
* @param attribute The attribute to del.
@ -200,7 +200,7 @@ EAPI Eina_Bool eina_xattr_del(const char *file, const char *attribute) EINA_ARG_
EAPI Eina_Bool eina_xattr_fd_del(int fd, const char *attribute) EINA_ARG_NONNULL(2);
/**
* @brief Set a string as a extended attribute properties.
* @brief Sets a string as a extended attribute properties.
*
* @param file The file to set the string to.
* @param attribute The attribute to set.
@ -213,7 +213,7 @@ EAPI Eina_Bool eina_xattr_fd_del(int fd, const char *attribute) EINA_ARG_NONNULL
EAPI Eina_Bool eina_xattr_string_set(const char *file, const char *attribute, const char *data, Eina_Xattr_Flags flags);
/**
* @brief Get a string from an extended attribute properties.
* @brief Gets a string from an extended attribute properties.
*
* @param file The file to get the string from.
* @param attribute The attribute to get.
@ -226,7 +226,7 @@ EAPI Eina_Bool eina_xattr_string_set(const char *file, const char *attribute, co
EAPI char *eina_xattr_string_get(const char *file, const char *attribute);
/**
* @brief Set a double as a extended attribute properties.
* @brief Sets a double as a extended attribute properties.
*
* @param file The file to set the double to.
* @param attribute The attribute to set.
@ -239,7 +239,7 @@ EAPI char *eina_xattr_string_get(const char *file, const char *attribute);
EAPI Eina_Bool eina_xattr_double_set(const char *file, const char *attribute, double value, Eina_Xattr_Flags flags);
/**
* @brief Get a double from an extended attribute properties.
* @brief Gets a double from an extended attribute properties.
*
* @param file The file to get the string from.
* @param attribute The attribute to get.
@ -253,7 +253,7 @@ EAPI Eina_Bool eina_xattr_double_set(const char *file, const char *attribute, do
EAPI Eina_Bool eina_xattr_double_get(const char *file, const char *attribute, double *value);
/**
* @brief Set an int as a extended attribute properties.
* @brief Sets an int as a extended attribute properties.
*
* @param file The file to set the int to.
* @param attribute The attribute to set.
@ -266,7 +266,7 @@ EAPI Eina_Bool eina_xattr_double_get(const char *file, const char *attribute, do
EAPI Eina_Bool eina_xattr_int_set(const char *file, const char *attribute, int value, Eina_Xattr_Flags flags);
/**
* @brief Get a int from an extended attribute properties.
* @brief Gets a int from an extended attribute properties.
*
* @param file The file to get the string from.
* @param attribute The attribute to get.