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
* 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
/**
* @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);
/**
* @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)
/**
* @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,
/**
* @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
* @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,
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
/**
* @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
* 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:
# 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
* 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.
*
/**
- * @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.
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.
*
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).
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.
*
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.
*
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.
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.
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.
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
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.
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.
* 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.
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.
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.
*/
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.
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.
* 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
* 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
/**
* @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.
*
/**
- * @brief Create a new array.
+ * @brief Creates a new array.
*
* @param name The name of the benchmark.
* @param run The name of the run.
const char *run);
/**
- * @brief Free a benchmark object.
+ * @brief Frees a benchmark object.
*
* @param bench The benchmark to free.
*
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.
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.
* 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
};
/**
- * @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.
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.
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.
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.
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.
typedef struct _Eina_Strbuf Eina_Binbuf;
/**
- * @brief Create a new string buffer.
+ * @brief Creates a new string buffer.
*
* @return Newly allocated string buffer instance.
*
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
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
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
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.
*
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.
*
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
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
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.
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.
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.
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.
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.
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.
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.
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
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.
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.
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.
*
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.
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
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
*/
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
*
/**
* @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().
*/
/**
* @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.
/**
* @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
* @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) \
* @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
* @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) \
* 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
*
* 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:
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.
/**
- * @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.
*
* 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.
*
* [-]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
/**
- * @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.
* [-]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
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.
* [-]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,
/**
* @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.
*/
/**
* @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.
/**
* @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
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.
*
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.
*
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.
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.
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.
*
/**
* @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.
/**
* @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.
} 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.
*/
* @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.
* @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.
* @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.
#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.
/**
* @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.
*
/**
* @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.
*
/**
* @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
* 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.
*
/**
* @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).
*
/**
* @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
};
/**
- * @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:
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.
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
*/
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.
* @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
* 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
/**
* @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
* 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,
/**
* @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.
*
/**
* @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
/**
* @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()
/**
* @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).
*
* 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()
/**
* @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
/**
* @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>
/**
* @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);
} 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.
* @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
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
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);
/**
* @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);
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
* @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
/**
* @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
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.
* @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()
*
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.
* @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
/**
- * @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);
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
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
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
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);
*
* @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
*
* @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);
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
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
#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
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
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
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
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);
*
* @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);
*
* @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);
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
/**
- * @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
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
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);
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);
*
* @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);
*
* @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);
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
/**
- * @brief Get the hamster count.
+ * @brief Gets the hamster count.
*
* @return The number of available hamsters.
*
* @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);
/**
- * @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.
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
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
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
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
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
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
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
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
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.
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.
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.
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.
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.
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.
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.
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.
*
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.
*
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.
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.
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.
* 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,
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.
*
* 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.
*
* 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
* 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,
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.
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.
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.
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.
* 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
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
/**
- * @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(),
*/
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(),
*/
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(),
*
* 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 }
/**
* @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.
/**
* @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
* @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.
*
/**
* @brief Removes every member from the array.
*
- *
* @param[in] array The array object
*
* @since 1.2
/**
* @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
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
/**
* @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.
*
/**
* @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.
*
/**
* @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()
*
/**
* @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()
*
/**
* @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.
*
/**
* @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
/**
* @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.
*
/**
* @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.
*
/**
* @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.
/**
* @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,
/**
* @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.
*
/**
* @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.
/**
* @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.
*
/**
- * 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
* 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
* 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
* 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
* 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
* 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.
*/
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.
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.
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.
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
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
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
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
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.
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
* 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:
/**
- * @brief Free an iterator.
+ * @brief Frees an iterator.
*
* @param iterator The iterator to free.
*
/**
- * @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.
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.
/**
- * @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.
/**
- * @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.
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.
/**
* @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
* 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()
*
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.
*
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.
*
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);
/**
- * @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.
/**
- * @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.
/**
- * @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.
/**
- * @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.
/**
- * @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.
/**
- * @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.
/**
- * @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.
/**
- * @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.
/**
- * @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.
/**
- * @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.
/**
- * @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.
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.
/**
- * @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
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
/**
- * @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
/**
- * @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).
/**
- * @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.
*
/**
- * @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.
/**
- * @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.
/**
- * @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.
/**
- * @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
/**
- * @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
/**
- * @brief Merge two list.
+ * @brief Merges two list.
*
* @param left Head list to merge.
* @param right Tail list to merge.
*
* 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).
*
/**
- * @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.
/**
- * @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.
* @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
* @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
* @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
* @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.
* @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
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.
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.
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
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.
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.
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.
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
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.
/**
- * @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.
/**
- * @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.
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.
/**
* @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.
/**
* @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.
/**
* @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.
/**
* @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.
/**
* @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.
* <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.
* @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.
*
*
*
} 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);
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
*
* 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()
*/
/**
* @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
*
* 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()
*/
/**
* @brief Releases a lock.
+ * @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
+ * @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).
- *
* @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
/**
* @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.
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.
* @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.
*
/**
- * @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()
/**
* @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()
/**
* @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()
*/
/**
* @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()
/**
* @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()
*/
/**
* @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()
*/
/**
* @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()
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.
*
/**
* @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.
*
* 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()
*/
/**
* @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.
*
* 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()
*/
/**
* @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()
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);
#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
* @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
*
* 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.
*/
/**
- * @brief Set the default log level.
+ * @brief Sets the default log level.
*
* @param level The log level.
*
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.
*
* 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.
/**
- * @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.
*
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.
*
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().
*
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().
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.
*
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.
*
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.
*
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.
*
/**
- * 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=<@p domain_name>:<@p level>
*
- * @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
* 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.
*
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.
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);
* @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);
*/
/**
- * 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,
...) 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.
* 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.
*/
* 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.
*/
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.
*
* 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.
*/
/**
- * 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.
*
* 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
*/
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.
/**
* @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:
*
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
*
* @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,
/**
* @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
*
* @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,
/**
* @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
* @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.
/**
* @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
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),
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
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),
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
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.
*
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
/**
* @defgroup Eina_Matrix3_Group 3x3 Matrices in floating point
*
- * @brief Matrix definition and operations
+ * @brief Matrix definition and operations.
*
* @{
*/
/**
* @defgroup Eina_Matrix4_Group 4x4 Matrices in floating point
*
- * @brief Matrix definition and operations
+ * @brief Matrix definition and operations.
*
* @{
*/
/**
* @defgroup Eina_Matrix3_F16p16_Group 3x3 Matrices in fixed point
*
- * @brief Fixed point matrix operations
+ * @brief Fixed point matrix operations.
* @{
*/
};
/**
- * @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
*
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.
/**
- * @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.
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.
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.
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.
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.
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.
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
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
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
*
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
*
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.
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.
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.
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,
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
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.
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
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
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
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
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
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.
*/
/**
- * @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.
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.
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.
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.
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.
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.
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.
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.
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
*
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
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
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.
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
const Eina_Matrix4 *mat_b);
/**
- * @brief Set orthogonality matrix
+ * @brief Sets orthogonality matrix.
*
* @param m The resulting matrix
* @param right The right value
};
/**
- * @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.
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.
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.
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
*
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
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.
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
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
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.
/* 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,
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.
*/
/* 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,
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.
*/
/* 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
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()
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.
*
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).
*/
/* 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).
*
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).
*
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).
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).
*
/* 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.
*
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.
*
/* 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
* @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
* @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!
*/
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
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
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
*
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.
* @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.
*
* @{
*
*/
/**
- * @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.
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)
*
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,
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.
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.
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.
* 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.
*/
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.
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.
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
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.
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.
/**
- * @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.
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.
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.
*
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.
*
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.
*
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.
/**
* @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,
/**
* @defgroup Eina_Quad_Group Quadrangles
*
- * @brief Quadrangles operations
+ * @brief Quadrangles operations.
*
* @{
*/
/**
- * @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.
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.
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.
/**
- * @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.
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.
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.
*/
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;
/**
/**
- * @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.
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.
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.
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.
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.
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.
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.
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.
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.
* @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);
* @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.
/**
*
- * @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
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
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.
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.
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.
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.
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.
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.
*
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.
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.
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.
*
/**
* @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.
/**
- * @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.
* 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.
*
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
/**
- * 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
* 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,
/**
- * 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.
*
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
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.
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.
*/
/**
- * 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.
*
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.
*/
/**
- * 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
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.
*/
/**
- * 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
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.
*/
/**
- * 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.
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.
*
/**
- * 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
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.
*/
/**
- * 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
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.
*/
/**
- * 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
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.
*/
/**
- * 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.
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);
/**
* @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.
/* 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.
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.
/**
- * @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.
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.
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.
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.
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.
/**
- * @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
/**
- * @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.
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.
/**
- * @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.
/**
- * @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.
*
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.
*
/**
* @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.
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.
typedef struct _Eina_Strbuf Eina_Strbuf;
/**
- * @brief Create a new string buffer.
+ * @brief Creates a new string buffer.
*
* @return Newly allocated string buffer instance.
*
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
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
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
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.
*
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.
*
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
/**
* @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.
/**
* @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.
/**
* @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.
/**
* @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.
/**
* @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.
/**
* @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.
/**
* @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.
#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
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.
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.
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.
*
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.
/**
- * @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.
*
/**
* @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.
/**
- * @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
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.
*
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.
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
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()
*
/**
- * @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().
*
* 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
* 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
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
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
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
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
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
* 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
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
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.
*
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.
/**
* @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.
*
} 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.
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
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
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()
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.
*
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
* 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
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
* 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
/**
* @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
* @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()
*
/**
* @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
* 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
*/
};
/**
- * @brief Create a new thread queue
+ * @brief Creates a new thread queue.
*
* @return A valid new thread queue, or NULL on failure
*
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
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
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()
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
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()
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
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
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
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()
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.
*
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).
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.
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.
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.
*/
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.
*
* @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
*
* @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);
*/
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
*
* 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:
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.
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.
*
* @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()
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.
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.
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
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
/**
* @typedef Eina_Trash
- * @brief The type for strcuture #_Eina_Trash.
+ * @brief The type for structure #_Eina_Trash.
*/
typedef struct _Eina_Trash 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.
*/
/**
* @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.
*
/**
* @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.
/**
* @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:
*
*
* @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(...)
/**
* @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
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,
* @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;
typedef struct _Eina_Strbuf Eina_UStrbuf;
/**
- * @brief Create a new string buffer.
+ * @brief Creates a new string buffer.
*
* @return Newly allocated string buffer instance.
*
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().
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
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.
*
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.
*
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
/**
* @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.
/**
* @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.
/**
* @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.
/**
* @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.
/**
* @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.
#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
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.
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.
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.
*
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.
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
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()
*
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().
*
* 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
/**
- * @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
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
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
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
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
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.
*/
/**
- * @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
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
#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
#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
* And now to explore conversions between two type we'll create another value:
* @until eina_value_setup
*
- * And make sure @c v and @c otherv have different types:
+ * And make sure @c v and @c others have different types:
* @until eina_value_setup
*
* We then set a value to @c v and have it converted, to do this we don't need
* value can already store struct timeval(man gettimeofday for more information)
* but it has no type to store struct timezone, so that's what this example will
* do.
- * @note struct timezone is actually obsolete, so using it in real world
+ * @note Struct timezone is actually obsolete, so using it in real world
* programs is probably not a good idea, but this is an example so, bear with
* us.
*
* instead of pointers to struct timezone, and this is a good point. The reason
* for this is that eina value doesn't know anything about our type so it must
* use a generic void pointer, casting that pointer into a proper value is the
- * job of the implementor of the new type.
+ * job of the implementer of the new type.
*
* Next we have the comparison function, which compares the @c tz_minuteswest
* field of struct timezone, we don't compare @c tz_dsttime because that field
* @until EINA_VALUE_TYPE_DOUBLE
* @until return
* @note It would be a good idea to add checks for over and underflow for these
- * types and return #EINA_FALSE in thoses cases, we omit this here for brevity.
+ * types and return #EINA_FALSE in those cases, we omit this here for brevity.
*
* For string types we use @c snprintf() to format our @c tz_minuteswest field
* and put it in a string(again @c tz_dsttime is ignored because it's not used):
* It is meant for simple data types, providing uniform access and
* release functions, useful to exchange data preserving their
* types. For more complex hierarchical data, with properties and
- * children, reference counting, inheritance and interfaces,
+ * children, reference counting, inheritance and interfaces,
*
* Examples of usage of the Eina_Value API:
* @li @ref eina_value_example_01_page
/**
* @typedef Eina_Value_Type
- * Describes the data contained by the value
+ * Describes the data contained by the value.
*
* @since 1.2
*/
* it's an exact copy of the current structure in use by value, no copies are
* done.
*
- * @note be aware that hash data is always an allocated memory of size
+ * @note Be aware that hash data is always an allocated memory of size
* defined by @c subtype->value_size. If your @c subtype is an
* integer, add as data malloc(sizeof(int)). If your @c subtype
* is an string, add as data malloc(sizeof(char*)) and this data
};
/**
- * @brief Create generic value storage.
- * @param type how to manage this value.
+ * @brief Creates generic value storage.
+ * @param type How to manage this value.
* @return The new value or @c NULL on failure.
*
* Create a new generic value storage. The members are managed using
*
* On failure, @c NULL is returned.
*
- * @note this calls creates from mempool and then uses
+ * @note This calls creates from mempool and then uses
* eina_value_setup(). Consider using eina_value_flush() and
* eina_value_setup() instead to avoid memory allocations.
*
EAPI Eina_Value *eina_value_new(const Eina_Value_Type *type) EINA_ARG_NONNULL(1) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
/**
- * @brief Free value and its data.
+ * @brief Frees value and its data.
* @param value value object
*
* @see eina_value_flush()
/**
- * @brief Initialize generic value storage.
- * @param value value object
- * @param type how to manage this value.
+ * @brief Initializes generic value storage.
+ * @param value Value object
+ * @param type How to manage this value.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* Initializes existing generic value storage. The members are managed using the
const Eina_Value_Type *type) EINA_ARG_NONNULL(1, 2);
/**
- * @brief Create generic value storage.
- * @param value value object
+ * @brief Creates generic value storage.
+ * @param value Value object
*
* Releases all the resources associated with an #Eina_Value. The
* value must be already set with eina_value_setup() or
static inline void eina_value_flush(Eina_Value *value) EINA_ARG_NONNULL(1);
/**
- * @brief Copy generic value storage.
- * @param value source value object
- * @param copy destination value object
+ * @brief Copies generic value storage.
+ * @param value Source value object
+ * @param copy Destination value object
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* The @a copy object is considered uninitialized and its existing
Eina_Value *copy) EINA_ARG_NONNULL(1, 2);
/**
- * @brief Compare generic value storage.
+ * @brief Compares generic value storage.
* @param a left side of comparison
* @param b right side of comparison
* @return less than zero if a < b, greater than zero if a > b, zero
const Eina_Value *b) EINA_ARG_NONNULL(1, 2);
/**
- * @brief Set the generic value.
- * @param value source value object
+ * @brief Sets the generic value.
+ * @param value Source value object
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* The variable argument is dependent on chosen type. The list for
...) EINA_ARG_NONNULL(1);
/**
- * @brief Get the generic value.
- * @param value source value object
+ * @brief Gets the generic value.
+ * @param value Source value object
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* The value is returned in the variable argument parameter, the
...) EINA_ARG_NONNULL(1);
/**
- * @brief Set the generic value.
- * @param value source value object
- * @param args variable argument
+ * @brief Sets the generic value.
+ * @param value Source value object
+ * @param args Variable argument
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* @note for array member see eina_value_array_vset()
va_list args) EINA_ARG_NONNULL(1);
/**
- * @brief Get the generic value.
- * @param value source value object
- * @param args variable argument
+ * @brief Gets the generic value.
+ * @param value Source value object
+ * @param args Variable argument
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* The value is returned in the variable argument parameter, the
va_list args) EINA_ARG_NONNULL(1);
/**
- * @brief Set the generic value from pointer.
- * @param value source value object
- * @param ptr pointer to specify the contents.
+ * @brief Sets the generic value from pointer.
+ * @param value Source value object
+ * @param ptr Pointer to specify the contents.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* The pointer type is dependent on chosen value type. The list for
const void *ptr) EINA_ARG_NONNULL(1, 2);
/**
- * @brief Get the generic value to pointer.
- * @param value source value object
- * @param ptr pointer to receive the contents.
+ * @brief Gets the generic value to pointer.
+ * @param value Source value object
+ * @param ptr Pointer to receive the contents.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* The value is returned in pointer contents, the actual value is
void *ptr) EINA_ARG_NONNULL(1, 2);
/**
- * @brief Convert one value to another type.
- * @param value source value object.
- * @param convert destination value object.
+ * @brief Converts one value to another type.
+ * @param value Source value object.
+ * @param convert Destination value object.
* @return #EINA_TRUE if converted, #EINA_FALSE otherwise.
*
* Converts one value to another trying first @a value type
/**
- * @brief Convert value to string.
+ * @brief Converts value to string.
* @param value value object.
* @return newly allocated memory or @c NULL on failure.
*
EAPI char *eina_value_to_string(const Eina_Value *value) EINA_ARG_NONNULL(1);
/**
- * @brief Query value type.
- * @param value value object.
- * @return type instance or @c NULL if type is invalid.
+ * @brief Queries value type.
+ * @param value Value object.
+ * @return Type instance, or @c NULL if type is invalid.
*
* Check if value type is valid and returns it. A type is invalid if
* it does not exist or if it is using a different version field.
};
/**
- * @brief Create generic value storage of type array.
- * @param subtype how to manage this array members.
- * @param step how to grow the members array.
+ * @brief Creates generic value storage of type array.
+ * @param subtype How to manage this array members.
+ * @param step How to grow the members array.
* @return The new value or @c NULL on failure.
*
* Create a new generic value storage of type array. The members are
*
* On failure, @c NULL is returned.
*
- * @note this creates from mempool and then uses
+ * @note This creates from mempool and then uses
* eina_value_array_setup(). @see eina_value_free() @see
* eina_value_array_setup()
*
unsigned int step) EINA_ARG_NONNULL(1);
/**
- * @brief Initialize generic value storage of type array.
- * @param value value object
- * @param subtype how to manage array members.
- * @param step how to grow the members array.
+ * @brief Initializes generic value storage of type array.
+ * @param value Value object
+ * @param subtype How to manage array members.
+ * @param step How to grow the members array.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* Initializes new generic value storage of type array with the given
unsigned int step) EINA_ARG_NONNULL(1, 2);
/**
- * @brief Query number of elements in value of array type.
+ * @brief Queries number of elements in value of array type.
* @param value value object.
* @return number of child elements.
* @since 1.2
static inline unsigned int eina_value_array_count(const Eina_Value *value);
/**
- * @brief Remove element at given position in value of array type.
+ * @brief Removes element at given position in value of array type.
* @param value value object.
* @param position index of the member
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
unsigned int position) EINA_ARG_NONNULL(1);
/**
- * @brief Set the generic value in an array member.
- * @param value source value object
- * @param position index of the member
+ * @brief Sets the generic value in an array member.
+ * @param value Source value object
+ * @param position Index of the member
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* The variable argument is dependent on chosen subtype. The list for
...) EINA_ARG_NONNULL(1);
/**
- * @brief Get the generic value from an array member.
- * @param value source value object
- * @param position index of the member
+ * @brief Gets the generic value from an array member.
+ * @param value Source value object
+ * @param position Index of the member
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* The value is returned in the variable argument parameter, and the
...) EINA_ARG_NONNULL(1);
/**
- * @brief Insert a generic value in an array member position.
- * @param value source value object
- * @param position index of the member
+ * @brief Inserts a generic value in an array member position.
+ * @param value Source value object
+ * @param position Index of the member
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* The variable argument is dependent on chosen subtype. The list for
/**
- * @brief Append a generic value in an array.
- * @param value source value object
+ * @brief Appends a generic value in an array.
+ * @param value Source value object
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* The variable argument is dependent on chosen subtype. The list for
...) EINA_ARG_NONNULL(1);
/**
- * @brief Set a generic value to an array member.
- * @param value source value object
- * @param position index of the member
- * @param args variable argument
+ * @brief Sets a generic value to an array member.
+ * @param value Source value object
+ * @param position Index of the member
+ * @param args Variable argument
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
* @see eina_value_array_set()
* @see eina_value_array_get()
va_list args) EINA_ARG_NONNULL(1);
/**
- * @brief Get the generic value from an array member.
- * @param value source value object
- * @param position index of the member
- * @param args variable argument
+ * @brief Gets the generic value from an array member.
+ * @param value Source value object
+ * @param position Index of the member
+ * @param args Variable argument
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* The value is returned in the variable argument parameter, the
unsigned int position,
va_list args) EINA_ARG_NONNULL(1);
/**
- * @brief Insert a generic value to an array member position.
- * @param value source value object
- * @param position index of the member
- * @param args variable argument
+ * @brief Inserts a generic value to an array member position.
+ * @param value Source value object
+ * @param position Index of the member
+ * @param args Variable argument
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
* @see eina_value_array_set()
* @see eina_value_array_get()
va_list args) EINA_ARG_NONNULL(1);
/**
- * @brief Append a generic value to an array.
- * @param value source value object
- * @param args variable argument
+ * @brief Appends a generic value to an array.
+ * @param value Source value object
+ * @param args Variable argument
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
* @see eina_value_array_set()
* @see eina_value_array_get()
/**
- * @brief Set a generic value to an array member from a pointer.
- * @param value source value object
- * @param position index of the member
- * @param ptr pointer to specify the contents.
+ * @brief Sets a generic value to an array member from a pointer.
+ * @param value Source value object
+ * @param position Index of the member
+ * @param ptr Pointer to specify the contents.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* The pointer type is dependent on chosen value type. The list for
const void *ptr) EINA_ARG_NONNULL(1, 3);
/**
- * @brief Retrieve a generic value into a pointer from an array member.
- * @param value source value object
- * @param position index of the member
- * @param ptr pointer to receive the contents.
+ * @brief Retrieves a generic value into a pointer from an array member.
+ * @param value Source value object
+ * @param position Index of the member
+ * @param ptr Pointer to receive the contents.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* The value is returned in pointer contents, the actual value is
void *ptr) EINA_ARG_NONNULL(1, 3);
/**
- * @brief Insert a generic value to an array member position from a pointer.
- * @param value source value object
- * @param position index of the member
- * @param ptr pointer to specify the contents.
+ * @brief Inserts a generic value to an array member position from a pointer.
+ * @param value Source value object
+ * @param position Index of the member
+ * @param ptr Pointer to specify the contents.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* The pointer type is dependent on chosen value type. The list for
const void *ptr) EINA_ARG_NONNULL(1);
/**
- * @brief Append a generic value to an array from a pointer.
- * @param value source value object
- * @param ptr pointer to specify the contents.
+ * @brief Appends a generic value to an array from a pointer.
+ * @param value Source value object
+ * @param ptr Pointer to specify the contents.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* The pointer type is dependent on chosen value type. The list for
/**
* @brief Retrieves a value from the array as an Eina_Value copy.
- * @param src source value object
- * @param position index of the member
- * @param dst where to return the array member
+ * @param src Source value object
+ * @param position Index of the member
+ * @param dst Where to return the array member
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* The argument @a dst is considered uninitialized and it's setup to
};
/**
- * @brief Create generic value storage of type list.
- * @param subtype how to manage this list members.
- * @return The new value or @c NULL on failure.
+ * @brief Creates generic value storage of type list.
+ * @param subtype How to manage this list members.
+ * @return The new value, or @c NULL on failure.
*
* Create a new generic value storage of type list. The members are
* managed using the description specified by @a subtype.
EAPI Eina_Value *eina_value_list_new(const Eina_Value_Type *subtype) EINA_ARG_NONNULL(1);
/**
- * @brief Initialize generic value storage of type list.
- * @param value value object
- * @param subtype how to manage this list members.
+ * @brief Initializes generic value storage of type list.
+ * @param value Value object
+ * @param subtype How to manage this list members.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* Initializes new generic value storage of type list with the given
const Eina_Value_Type *subtype) EINA_ARG_NONNULL(1, 2);
/**
- * @brief Query number of elements in value of list type.
+ * @brief Queries number of elements in value of list type.
* @param value value object.
* @return number of child elements.
* @since 1.2
static inline unsigned int eina_value_list_count(const Eina_Value *value);
/**
- * @brief Remove element at given position in value of list type.
+ * @brief Removes element at given position in value of list type.
* @param value value object.
* @param position index of the member
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
unsigned int position) EINA_ARG_NONNULL(1);
/**
- * @brief Set the generic value in an list member.
- * @param value source value object
- * @param position index of the member
+ * @brief Sets the generic value in an list member.
+ * @param value Source value object
+ * @param position Index of the member
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* The variable argument is dependent on chosen subtype. The list for
...) EINA_ARG_NONNULL(1);
/**
- * @brief Get the generic value from an list member.
- * @param value source value object
- * @param position index of the member
+ * @brief Gets the generic value from an list member.
+ * @param value Source value object
+ * @param position Index of the member
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* The value is returned in the variable argument parameter, the
...) EINA_ARG_NONNULL(1);
/**
- * @brief Insert the generic value in an list member position.
- * @param value source value object
- * @param position index of the member
+ * @brief Inserts the generic value in an list member position.
+ * @param value Source value object
+ * @param position Index of the member
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* The variable argument is dependent on chosen subtype. The list for
/**
- * @brief Append the generic value in an list.
- * @param value source value object
+ * @brief Appends the generic value in an list.
+ * @param value Source value object
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* The variable argument is dependent on chosen subtype. The list for
...) EINA_ARG_NONNULL(1);
/**
- * @brief Set the generic value in an list member.
- * @param value source value object
- * @param position index of the member
- * @param args variable argument
+ * @brief Sets the generic value in an list member.
+ * @param value Source value object
+ * @param position Index of the member
+ * @param args Variable argument
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
* @see eina_value_list_set()
* @see eina_value_list_get()
va_list args) EINA_ARG_NONNULL(1);
/**
- * @brief Get the generic value from an list member.
- * @param value source value object
- * @param position index of the member
- * @param args variable argument
+ * @brief Gets the generic value from an list member.
+ * @param value Source value object
+ * @param position Index of the member
+ * @param args Variable argument
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* The value is returned in the variable argument parameter, the
unsigned int position,
va_list args) EINA_ARG_NONNULL(1);
/**
- * @brief Insert the generic value in an list member position.
- * @param value source value object
- * @param position index of the member
- * @param args variable argument
+ * @brief Inserts the generic value in an list member position.
+ * @param value Source value object
+ * @param position Index of the member
+ * @param args Variable argument
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
* @see eina_value_list_set()
* @see eina_value_list_get()
va_list args) EINA_ARG_NONNULL(1);
/**
- * @brief Append the generic value in an list.
- * @param value source value object
- * @param args variable argument
+ * @brief Appends the generic value in an list.
+ * @param value Source value object
+ * @param args Variable argument
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
* @see eina_value_list_set()
* @see eina_value_list_get()
/**
- * @brief Set the generic value in an list member from pointer.
- * @param value source value object
- * @param position index of the member
- * @param ptr pointer to specify the contents.
+ * @brief Sets the generic value in an list member from pointer.
+ * @param value Source value object
+ * @param position Index of the member
+ * @param ptr Pointer to specify the contents.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* The pointer type is dependent on chosen value type. The list for
const void *ptr) EINA_ARG_NONNULL(1, 3);
/**
- * @brief Get the generic value to pointer from an list member.
- * @param value source value object
- * @param position index of the member
- * @param ptr pointer to receive the contents.
+ * @brief Gets the generic value to pointer from an list member.
+ * @param value Source value object
+ * @param position Index of the member
+ * @param ptr Pointer to receive the contents.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* The value is returned in pointer contents, the actual value is
void *ptr) EINA_ARG_NONNULL(1, 3);
/**
- * @brief Insert the generic value in an list member position from pointer.
- * @param value source value object
- * @param position index of the member
- * @param ptr pointer to specify the contents.
+ * @brief Inserts the generic value in an list member position from pointer.
+ * @param value Source value object
+ * @param position Index of the member
+ * @param ptr Pointer to specify the contents.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* The pointer type is dependent on chosen value type. The list for
const void *ptr) EINA_ARG_NONNULL(1);
/**
- * @brief Append the generic value in an list from pointer.
- * @param value source value object
- * @param ptr pointer to specify the contents.
+ * @brief Appends the generic value in an list from pointer.
+ * @param value Source value object
+ * @param ptr Pointer to specify the contents.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* The pointer type is dependent on chosen value type. The list for
};
/**
- * @brief Create generic value storage of type hash.
- * @param subtype how to manage this hash members.
- * @param buckets_power_size how to allocate hash buckets (2 ^
+ * @brief Creates generic value storage of type hash.
+ * @param subtype How to manage this hash members.
+ * @param buckets_power_size How to allocate hash buckets (2 ^
* buckets_power_size), if zero then a sane value is chosen.
- * @return The new value or @c NULL on failure.
+ * @return The new value, or @c NULL on failure.
*
* Create a new generic value storage of type hash. The members are
* managed using the description specified by @a subtype.
EAPI Eina_Value *eina_value_hash_new(const Eina_Value_Type *subtype, unsigned int buckets_power_size) EINA_ARG_NONNULL(1);
/**
- * @brief Initialize generic value storage of type hash.
- * @param value value object
- * @param subtype how to manage this hash members.
- * @param buckets_power_size how to allocate hash buckets (2 ^
+ * @brief Initializes generic value storage of type hash.
+ * @param value Value object
+ * @param subtype How to manage this hash members.
+ * @param buckets_power_size How to allocate hash buckets (2 ^
* buckets_power_size), if zero then a sane value is chosen.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
unsigned int buckets_power_size) EINA_ARG_NONNULL(1, 2);
/**
- * @brief Query number of elements in value of hash type.
+ * @brief Queries number of elements in value of hash type.
* @param value value object.
* @return number of child elements.
* @since 1.2
static inline unsigned int eina_value_hash_population(const Eina_Value *value);
/**
- * @brief Remove element at given position in value of hash type.
+ * @brief Removes element at given position in value of hash type.
* @param value value object.
* @param key key to find the member
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
const char *key) EINA_ARG_NONNULL(1);
/**
- * @brief Set the generic value in an hash member.
- * @param value source value object
- * @param key key to find the member
+ * @brief Sets the generic value in an hash member.
+ * @param value Source value object
+ * @param key Key to find the member
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* The variable argument is dependent on chosen subtype. The list for
...) EINA_ARG_NONNULL(1);
/**
- * @brief Get the generic value from an hash member.
- * @param value source value object
- * @param key key to find the member
+ * @brief Gets the generic value from an hash member.
+ * @param value Source value object
+ * @param key Key to find the member
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* The value is returned in the variable argument parameter, the
...) EINA_ARG_NONNULL(1);
/**
- * @brief Set the generic value in an hash member.
- * @param value source value object
- * @param key key to find the member
- * @param args variable argument
+ * @brief Sets the generic value in an hash member.
+ * @param value Source value object
+ * @param key Key to find the member
+ * @param args Variable argument
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
* @see eina_value_hash_set()
* @see eina_value_hash_get()
va_list args) EINA_ARG_NONNULL(1);
/**
- * @brief Get the generic value from an hash member.
- * @param value source value object
- * @param key key to find the member
- * @param args variable argument
+ * @brief Gets the generic value from an hash member.
+ * @param value Source value object
+ * @param key Key to find the member
+ * @param args Variable argument
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* The value is returned in the variable argument parameter, the
va_list args) EINA_ARG_NONNULL(1);
/**
- * @brief Set the generic value in an hash member from pointer.
- * @param value source value object
- * @param key key to find the member
- * @param ptr pointer to specify the contents.
+ * @brief Sets the generic value in an hash member from pointer.
+ * @param value Source value object
+ * @param key Key to find the member
+ * @param ptr Pointer to specify the contents.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* The pointer type is dependent on chosen value type. The list for
const void *ptr) EINA_ARG_NONNULL(1, 3);
/**
- * @brief Get the generic value to pointer from an hash member.
- * @param value source value object
- * @param key key to find the member
- * @param ptr pointer to receive the contents.
+ * @brief Gets the generic value to pointer from an hash member.
+ * @param value Source value object
+ * @param key Key to find the member
+ * @param ptr Pointer to receive the contents.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* The value is returned in pointer contents, the actual value is
};
/**
- * @brief Create generic value storage of type struct.
- * @param desc how to manage this struct members.
- * @return The new value or @c NULL on failure.
+ * @brief Creates generic value storage of type struct.
+ * @param desc How to manage this struct members.
+ * @return The new value, or @c NULL on failure.
*
* Create a new generic value storage of type struct. The members are
* managed using the description specified by @a desc.
EAPI Eina_Value *eina_value_struct_new(const Eina_Value_Struct_Desc *desc) EINA_ARG_NONNULL(1);
/**
- * @brief Initialize generic value storage of type struct.
- * @param value value object
- * @param desc how to manage this struct members.
+ * @brief Initializes generic value storage of type struct.
+ * @param value Value object
+ * @param desc How to manage this struct members.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* Initializes new generic value storage of type struct with the given
const Eina_Value_Struct_Desc *desc) EINA_ARG_NONNULL(1, 2);
/**
- * @brief Set the generic value in an struct member.
- * @param value source value object
- * @param name name to find the member
+ * @brief Sets the generic value in an struct member.
+ * @param value Source value object
+ * @param name Name to find the member
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* The variable argument is dependent on chosen member type. The list
...) EINA_ARG_NONNULL(1, 2);
/**
- * @brief Get the generic value from an struct member.
- * @param value source value object
- * @param name name to find the member
+ * @brief Gets the generic value from an struct member.
+ * @param value Source value object
+ * @param name Name to find the member
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* The value is returned in the variable argument parameter, the
...) EINA_ARG_NONNULL(1, 2);
/**
- * @brief Set the generic value in an struct member.
- * @param value source value object
- * @param name name to find the member
- * @param args variable argument
+ * @brief Sets the generic value in an struct member.
+ * @param value Source value object
+ * @param name Name to find the member
+ * @param args Variable argument
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
* @see eina_value_struct_set()
* @see eina_value_struct_get()
va_list args) EINA_ARG_NONNULL(1, 2);
/**
- * @brief Get the generic value from an struct member.
- * @param value source value object
- * @param name name to find the member
- * @param args variable argument
+ * @brief Gets the generic value from an struct member.
+ * @param value Source value object
+ * @param name Name to find the member
+ * @param args Variable argument
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* The value is returned in the variable argument parameter, the
va_list args) EINA_ARG_NONNULL(1, 2);
/**
- * @brief Set the generic value in an struct member from pointer.
- * @param value source value object
- * @param name name to find the member
- * @param ptr pointer to specify the contents.
+ * @brief Sets the generic value in an struct member from pointer.
+ * @param value Source value object
+ * @param name Name to find the member
+ * @param ptr Pointer to specify the contents.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* The pointer type is dependent on chosen value type. The list for
const void *ptr) EINA_ARG_NONNULL(1, 2, 3);
/**
- * @brief Get the generic value to pointer from an struct member.
- * @param value source value object
- * @param name name to find the member
- * @param ptr pointer to receive the contents.
+ * @brief Gets the generic value to pointer from an struct member.
+ * @param value Source value object
+ * @param name Name to find the member
+ * @param ptr Pointer to receive the contents.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* The value is returned in pointer contents, the actual value is
void *ptr) EINA_ARG_NONNULL(1, 2, 3);
/**
- * @brief Get the member as Eina_Value copy
- * @param src source value object
- * @param name name to find the member
- * @param dst where to return the member value.
- * @return #EINA_TRUE on success, #EINA_FALSE on failure.
+ * @brief Gets the member as Eina_Value copy
+ * @param src Source value object
+ * @param name Name to find the member
+ * @param dst Shere to return the member value.
+ * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* The argument @a dst is considered uninitialized and it's setup to
* the type of the member.
Eina_Value *dst) EINA_ARG_NONNULL(1, 2, 3);
/**
- * @brief Set the member from Eina_Value source
+ * @brief Sets the member from Eina_Value source.
* @param dst destination value object
* @param name name to find the member
* @param src source value
const Eina_Value *src) EINA_ARG_NONNULL(1, 2, 3);
/**
- * @brief Get the member as Eina_Value copy given its member description.
- * @param src source value object
- * @param member the member description to use
- * @param dst where to return the member value.
- * @return #EINA_TRUE on success, #EINA_FALSE on failure.
+ * @brief Gets the member as Eina_Value copy given its member description.
+ * @param src Source value object
+ * @param member The member description to use
+ * @param dst Where to return the member value.
+ * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*
* The argument @a dst is considered uninitialized and it's setup to
* the type of the member.
Eina_Value *dst) EINA_ARG_NONNULL(1, 2, 3);
/**
- * @brief Set the member from Eina_Value source
+ * @brief Sets the member from Eina_Value source.
* @param dst destination value object
* @param member the member description to use
* @param src source value
};
/**
- * @brief Query type name.
+ * @brief Queries type name.
* @param type type reference.
* @return string or @c NULL if type is invalid.
* @since 1.2
EAPI const char *eina_value_type_name_get(const Eina_Value_Type *type) EINA_PURE EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
/**
- * @brief Check if type is valid.
- * @param type type reference.
+ * @brief Checks if type is valid.
+ * @param type Type reference.
* @return #EINA_TRUE if valid, #EINA_FALSE otherwise.
*
* A type is invalid if it's NULL or if version field is not the same
EAPI Eina_Bool eina_value_type_check(const Eina_Value_Type *type) EINA_PURE EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
/**
- * @brief Initialize memory using type descriptor.
+ * @brief Initializes memory using type descriptor.
* @param type type reference.
* @param mem memory to operate, must be of size @c type->value_size.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
static inline Eina_Bool eina_value_type_setup(const Eina_Value_Type *type, void *mem);
/**
- * @brief Flush (clear) memory using type descriptor.
+ * @brief Flushes (clears) memory using type descriptor.
* @param type type reference.
* @param mem memory to operate, must be of size @c type->value_size.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
static inline Eina_Bool eina_value_type_flush(const Eina_Value_Type *type, void *mem);
/**
- * @brief Copy memory using type descriptor.
+ * @brief Copies memory using type descriptor.
* @param type type reference.
* @param src memory to operate, must be of size @c type->value_size.
* @param dst memory to operate, must be of size @c type->value_size.
static inline Eina_Bool eina_value_type_copy(const Eina_Value_Type *type, const void *src, void *dst);
/**
- * @brief Compare memory using type descriptor.
+ * @brief Compares memory using type descriptor.
* @param type type reference.
* @param a memory to operate, must be of size @c type->value_size.
* @param b memory to operate, must be of size @c type->value_size.
static inline int eina_value_type_compare(const Eina_Value_Type *type, const void *a, const void *b);
/**
- * @brief Convert memory using type descriptor.
+ * @brief Converts memory using type descriptor.
* @param type type reference of the source.
* @param convert type reference of the destination.
* @param type_mem memory to operate, must be of size @c type->value_size.
static inline Eina_Bool eina_value_type_convert_to(const Eina_Value_Type *type, const Eina_Value_Type *convert, const void *type_mem, void *convert_mem);
/**
- * @brief Convert memory using type descriptor.
+ * @brief Converts memory using type descriptor.
* @param type type reference of the destination.
* @param convert type reference of the source.
* @param type_mem memory to operate, must be of size @c type->value_size.
static inline Eina_Bool eina_value_type_convert_from(const Eina_Value_Type *type, const Eina_Value_Type *convert, void *type_mem, const void *convert_mem);
/**
- * @brief Set memory using type descriptor and variable argument.
+ * @brief Sets memory using type descriptor and variable argument.
* @param type type reference of the source.
* @param mem memory to operate, must be of size @c type->value_size.
* @param args input value.
static inline Eina_Bool eina_value_type_vset(const Eina_Value_Type *type, void *mem, va_list args);
/**
- * @brief Set memory using type descriptor and pointer.
+ * @brief Sets memory using type descriptor and pointer.
* @param type type reference of the source.
* @param mem memory to operate, must be of size @c type->value_size.
* @param ptr pointer to input value.
static inline Eina_Bool eina_value_type_pset(const Eina_Value_Type *type, void *mem, const void *ptr);
/**
- * @brief Get memory using type descriptor.
+ * @brief Gets memory using type descriptor.
* @param type type reference of the source.
* @param mem memory to operate, must be of size @c type->value_size.
* @param ptr pointer to output.
typedef Eina_Value_Union Eina_Value_Optional;
/**
- * @brief Create an empty optional. This is the same as eina_value_new(EINA_VALUE_TYPE_OPTIONAL).
+ * @brief Creates an empty optional. This is the same as eina_value_new(EINA_VALUE_TYPE_OPTIONAL).
* @return returns an empty optional eina value.
* @since 1.17
*/
static inline Eina_Value *eina_value_optional_empty_new(void);
/**
- * @brief Create an optional eina value with the passed value
+ * @brief Creates an optional eina value with the passed value
* @param subtype Eina_Value_Type of parameter value
* @param value The value to be used to construct optional eina value
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
Eina_Bool *is_empty) EINA_ARG_NONNULL(1, 2);
/**
- * @brief Set the optional with a value
+ * @brief Sets the optional with a value
* @param value Eina Value Optional to be set with subvalue
* @param subtype Type of subvalue
* @param subvalue Value to be set in optional
const void *subvalue) EINA_ARG_NONNULL(1, 2, 3);
/**
- * @brief Get the value from an optional
+ * @brief Gets the value from an optional
* @param value Eina Value Optional to get value from
* @param subvalue Pointer to where value is to be copied to. You must use
* the correct type according to eina_value_optional_type_get
EAPI Eina_Bool eina_value_optional_reset(Eina_Value *value) EINA_ARG_NONNULL(1);
/**
- * @brief Get type from value that is stored on Eina Value Optional
+ * @brief Gets type from value that is stored on Eina Value Optional
* @param value Eina Value Optional
* @return The optional sub-type.
* @since 1.17
*/
/**
- * @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
};
/**
- * @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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
/**
- * @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.
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.
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.
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.
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.
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.
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.
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.
projects / platform / upstream / efl.git / commitdiff