diff --git a/src/lib/eina/eina_accessor.h b/src/lib/eina/eina_accessor.h index aed6d9d307..3586d3c197 100644 --- a/src/lib/eina/eina_accessor.h +++ b/src/lib/eina/eina_accessor.h @@ -301,10 +301,10 @@ EAPI Eina_Bool eina_accessor_unlock(Eina_Accessor *accessor) EINA_ARG_NONNULL(1) * @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 - * iterating over the container. - * @param data A pointer to store the data \n + * @param[in] accessor The accessor to use + * @param[out] counter A counter used by eina_accessor_data_get() when + * iterating over the container. + * @param[out] data A pointer to store the data \n * It must be a pointer to support getting * its address since eina_accessor_data_get() requires a pointer. * diff --git a/src/lib/eina/eina_file.h b/src/lib/eina/eina_file.h index ea3e79481d..78c2b65596 100644 --- a/src/lib/eina/eina_file.h +++ b/src/lib/eina/eina_file.h @@ -288,7 +288,7 @@ EAPI Eina_Array *eina_file_split(char *path) EINA_WARN_UNUSED_RESULT EINA_ARG * 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 + * @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. * @@ -309,7 +309,7 @@ EAPI Eina_Iterator *eina_file_ls(const char *dir) EINA_WARN_UNUSED_RESULT EINA_A * 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 + * @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. @@ -409,7 +409,7 @@ EAPI Eina_Bool eina_file_mkdtemp(const char *templatename, Eina_Tmpstr **path) E * @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 + * @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. diff --git a/src/lib/eina/eina_file_common.h b/src/lib/eina/eina_file_common.h index c7ee3f87eb..142ee2d852 100644 --- a/src/lib/eina/eina_file_common.h +++ b/src/lib/eina/eina_file_common.h @@ -269,8 +269,8 @@ extern int _eina_file_log_dom; /** * @brief Map the entire contents of a virtual file to a buffer. * - * @param file The virtual file to map in memory - * + * @param[in] file The virtual file to map in memory + * @return The buffer */ void *eina_file_virtual_map_all(Eina_File *file); @@ -280,7 +280,7 @@ void *eina_file_virtual_map_all(Eina_File *file); * @param[in,out] file The virtual file to map in memory * @param[in] offset The offset inside the file to start mapping * @param[in] length The length of the region to map - * + * @return The buffer */ void *eina_file_virtual_map_new(Eina_File *file, unsigned long int offset, unsigned long int length); diff --git a/src/lib/eina/eina_hash.h b/src/lib/eina/eina_hash.h index 6efdfce34b..16344cfed4 100644 --- a/src/lib/eina/eina_hash.h +++ b/src/lib/eina/eina_hash.h @@ -311,7 +311,7 @@ typedef unsigned int (*Eina_Key_Length)(const void *key); /** * @def EINA_KEY_LENGTH - * @param Function The function used to calculate length of hash key. + * @param[in] Function The function used to calculate length of hash key. */ #define EINA_KEY_LENGTH(Function) ((Eina_Key_Length)Function) @@ -322,7 +322,7 @@ typedef unsigned int (*Eina_Key_Length)(const void *key); typedef int (*Eina_Key_Cmp)(const void *key1, int key1_length, const void *key2, int key2_length); /** * @def EINA_KEY_CMP - * @param Function The function used to compare hash key. + * @param[in]Function The function used to compare hash key. */ #define EINA_KEY_CMP(Function) ((Eina_Key_Cmp)Function) @@ -333,7 +333,7 @@ typedef int (*Eina_Key_Cmp)(const void *key1, int key1_length, const vo typedef int (*Eina_Key_Hash)(const void *key, int key_length); /** * @def EINA_KEY_HASH - * @param Function The function used to hash key. + * @param[in] Function The function used to hash key. */ #define EINA_KEY_HASH(Function) ((Eina_Key_Hash)Function) @@ -347,13 +347,13 @@ typedef Eina_Bool (*Eina_Hash_Foreach)(const Eina_Hash *hash, const void *key /** * @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. - * @param key_hash_cb The function called when getting the values. - * @param data_free_cb The function called on each value when the hash table is + * @param[in] key_length_cb The function called when getting the size of the key. + * @param[in] key_cmp_cb The function called when comparing the keys. + * @param[in] key_hash_cb The function called when getting the values. + * @param[in] 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 a * callback. - * @param buckets_power_size The size of the buckets. + * @param[in] buckets_power_size The size of the buckets. * @return The new hash table, or @c NULL on failure. * * This function creates a new hash table using user-defined callbacks @@ -382,8 +382,8 @@ EAPI Eina_Hash *eina_hash_new(Eina_Key_Length key_length_cb, /** * @brief Sets the data cleanup callback for a hash. * - * @param hash The given hash table. - * @param data_free_cb The function called on each value when the hash + * @param[in,out] hash The given hash table. + * @param[in] 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 * callback to remove an existing callback. * @@ -398,7 +398,7 @@ EAPI void eina_hash_free_cb_set(Eina_Hash *hash, Eina_Free_Cb data_free_cb) EINA /** * @brief Creates a new hash table using the djb2 algorithm. * - * @param data_free_cb The function called on each value when the hash table + * @param[in] 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 * callback. * @return The new hash table, or @c NULL on failure. @@ -413,7 +413,7 @@ EAPI Eina_Hash *eina_hash_string_djb2_new(Eina_Free_Cb data_free_cb); /** * @brief Creates a new hash table for use with strings. * - * @param data_free_cb The function called on each value when the hash table + * @param[in] 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 * callback. * @return The new hash table, or @c NULL on failure. @@ -432,7 +432,7 @@ EAPI Eina_Hash *eina_hash_string_superfast_new(Eina_Free_Cb data_free_cb); /** * @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 + * @param[in] 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 * callback. * @return The new hash table, or @c NULL on failure. @@ -449,7 +449,7 @@ EAPI Eina_Hash *eina_hash_string_small_new(Eina_Free_Cb data_free_cb); /** * @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 + * @param[in] 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 * callback. * @return The new hash table, or @c NULL on failure. @@ -467,7 +467,7 @@ EAPI Eina_Hash *eina_hash_int32_new(Eina_Free_Cb data_free_cb); /** * @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 + * @param[in] 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 * callback. * @return The new hash table, or @c NULL on failure. @@ -484,7 +484,7 @@ EAPI Eina_Hash *eina_hash_int64_new(Eina_Free_Cb data_free_cb); /** * @brief Creates a new hash table for use with pointers. * - * @param data_free_cb The function called on each value when the hash table + * @param[in] 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 * callback. * @return The new hash table, or @c NULL on failure. @@ -510,7 +510,7 @@ EAPI Eina_Hash *eina_hash_pointer_new(Eina_Free_Cb data_free_cb); /** * @brief Creates a new hash table optimized for stringshared values. * - * @param data_free_cb The function called on each value when the hash table + * @param[in] 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 * callback. * @return The new hash table, or @c NULL on failure. @@ -535,9 +535,9 @@ EAPI Eina_Hash *eina_hash_stringshared_new(Eina_Free_Cb data_free_cb); /** * @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. - * @param data The data to associate with the string given by @p key. Cannot be @c + * @param[in,out] hash The given hash table. Cannot be @c NULL. + * @param[in] key A unique key. Cannot be @c NULL. + * @param[in] data The data to associate with the string given by @p key. Cannot be @c * NULL. * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. * @@ -562,9 +562,9 @@ EAPI Eina_Bool eina_hash_add(Eina_Hash *hash, /** * @brief Adds an entry to the given hash table without duplicating the string. * - * @param hash The given hash table. Cannot be @c NULL. - * @param key A unique key. Cannot be @c NULL. - * @param data The data to associate with the string given by @p + * @param[in,out] hash The given hash table. Cannot be @c NULL. + * @param[in] key A unique key. Cannot be @c NULL. + * @param[in] data The data to associate with the string given by @p * key. Cannot be @c NULL * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. * @@ -592,9 +592,9 @@ EAPI Eina_Bool eina_hash_direct_add(Eina_Hash *hash, * @brief Removes the entry identified by a key or a data from the given * hash table. * - * @param hash The given hash table. - * @param key The key. - * @param data The data pointer to remove if the key is @c NULL. + * @param[in,out] hash The given hash table. + * @param[in] key The key. + * @param[in] data The data pointer to remove if the key is @c NULL. * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. * * This function removes the entry identified by @p key or @p data @@ -616,8 +616,8 @@ EAPI Eina_Bool eina_hash_del(Eina_Hash *hash, /** * @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. + * @param[in] hash The given hash table. + * @param[in] key The key of the entry to find. * @return The data pointer for the stored entry on success, or @c NULL * otherwise. * @@ -630,9 +630,9 @@ EAPI void *eina_hash_find(const Eina_Hash *hash, /** * @brief Modifies the entry pointer at the specified key and returns * the previous entry. - * @param hash The given hash table. - * @param key The key of the entry to modify. - * @param data The new data. + * @param[in,out] hash The given hash table. + * @param[in] key The key of the entry to modify. + * @param[in] data The new data. * @return The data pointer for the previously stored entry on success, * or @c NULL otherwise. * @@ -647,9 +647,9 @@ EAPI void *eina_hash_modify(Eina_Hash *hash, * @brief Modifies the entry pointer at the specified key and returns the * previous entry or adds the entry if not found. * - * @param hash The given hash table. - * @param key The key of the entry to modify. - * @param data The data to replace the previous entry. + * @param[in,out] hash The given hash table. + * @param[in] key The key of the entry to modify. + * @param[in] data The data to replace the previous entry. * @return The data pointer for the previous stored entry, or @c NULL * otherwise. * @@ -665,9 +665,9 @@ EAPI void *eina_hash_set(Eina_Hash *hash, * @brief Changes the key of an entry in a hash without triggering the * free callback. * - * @param hash The given hash table. - * @param old_key The current key associated with the data. - * @param new_key The new key to associate data with. + * @param[in,out] hash The given hash table. + * @param[in] old_key The current key associated with the data. + * @param[in] new_key The new key to associate data with. * @return #EINA_FALSE in any case but success, #EINA_TRUE on success. * * This function moves data from one key to another, @@ -681,7 +681,7 @@ EAPI Eina_Bool eina_hash_move(Eina_Hash *hash, /** * @brief Frees the given hash table's resources. * - * @param hash The hash table to be freed. + * @param[in] hash The hash table to be freed. * * This function frees memory allocated for the @p hash and to its * internal buckets. @@ -706,7 +706,7 @@ EAPI void eina_hash_free(Eina_Hash *hash) EINA_ARG_NONNULL(1); /** * @brief Frees the given hash table buckets resources. * - * @param hash The hash table whose buckets have to be freed. + * @param[in] hash The hash table whose buckets have to be freed. * * This function frees memory allocated to internal buckets for @p hash. * @@ -722,7 +722,7 @@ EAPI void eina_hash_free_buckets(Eina_Hash *hash) EINA_ARG_NONNULL(1); /** * @brief Returns the number of entries in the given hash table. * - * @param hash The given hash table. + * @param[in] hash The given hash table. * @return The number of entries in the hash table, or @c 0 on error or * if @p hash is @c NULL. */ @@ -731,11 +731,11 @@ EAPI int eina_hash_population(const Eina_Hash *hash) EINA_ARG_NONNULL(1); /** * @brief Adds an entry to the given hash table by its key hash. * - * @param hash The given hash table. Cannot be @c NULL. - * @param key A unique key. Cannot be @c NULL. - * @param key_length The length of @p key (including terminating '\\0'). - * @param key_hash The hash of @p key. - * @param data The data to associate with the string given by the key. Cannot be + * @param[in,out] hash The given hash table. Cannot be @c NULL. + * @param[in] key A unique key. Cannot be @c NULL. + * @param[in] key_length The length of @p key (including terminating '\\0'). + * @param[in] key_hash The hash of @p key. + * @param[in] data The data to associate with the string given by the key. Cannot be * @c NULL. * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. * @@ -758,11 +758,11 @@ EAPI Eina_Bool eina_hash_add_by_hash(Eina_Hash *hash, /** * @brief Adds an entry to a hash table by its key hash without duplicating the string key. * - * @param hash The given hash table. Cannot be @c NULL. - * @param key A unique key. Cannot be @c NULL. - * @param key_length The length of @p key (including terminating '\\0'). - * @param key_hash The hash of @p key. - * @param data The data to associate with the string given by @p key. Cannot be @c + * @param[in,out] hash The given hash table. Cannot be @c NULL. + * @param[in] key A unique key. Cannot be @c NULL. + * @param[in] key_length The length of @p key (including terminating '\\0'). + * @param[in] key_hash The hash of @p key. + * @param[in] data The data to associate with the string given by @p key. Cannot be @c * NULL. * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. * @@ -790,10 +790,10 @@ EAPI Eina_Bool eina_hash_direct_add_by_hash(Eina_Hash *hash, * @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. - * @param key The key. Cannot be @c NULL. - * @param key_length The length of the key (including terminating '\\0'). - * @param key_hash The hash that always matches the key. + * @param[in,out] hash The given hash table. Cannot be @c NULL. + * @param[in] key The key. Cannot be @c NULL. + * @param[in] key_length The length of the key (including terminating '\\0'). + * @param[in] key_hash The hash that always matches the key. * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. * * This function removes the entry identified by @p key and @@ -816,8 +816,8 @@ EAPI Eina_Bool eina_hash_del_by_key_hash(Eina_Hash *hash, * This version will calculate key length and hash by using functions * provided to the hash creation function. * - * @param hash The given hash table. Cannot be @c NULL. - * @param key The key. Cannot be @c NULL. + * @param[in,out] hash The given hash table. Cannot be @c NULL. + * @param[in] key The key. Cannot be @c NULL. * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. * * This function removes the entry identified by @p key from @p @@ -836,8 +836,8 @@ EAPI Eina_Bool eina_hash_del_by_key(Eina_Hash *hash, /** * @brief Removes an entry from a hash table identified by its data value. * - * @param hash The given hash table. Cannot be @c NULL. - * @param data The data value to search and remove. Cannot be @c NULL. + * @param[in,out] hash The given hash table. Cannot be @c NULL. + * @param[in] data The data value to search and remove. Cannot be @c NULL. * @return #EINA_FALSE if an error occurred or if @p hash or @p data are * @c NULL, #EINA_TRUE otherwise. * thing goes fine. @@ -862,11 +862,11 @@ EAPI Eina_Bool eina_hash_del_by_data(Eina_Hash *hash, * If @p key is @c NULL, then @p data is used to find a match to * remove. * - * @param hash The given hash table. Cannot be @c NULL. - * @param key The key. - * @param key_length The length of the key. - * @param key_hash The hash that always match the key. - * @param data The data pointer to remove if the key is @c NULL. + * @param[in,out] hash The given hash table. Cannot be @c NULL. + * @param[in] key The key. + * @param[in] key_length The length of the key. + * @param[in] key_hash The hash that always match the key. + * @param[in] data The data pointer to remove if the key is @c NULL. * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. * * This function removes the entry identified by @p key and @p key_hash, @@ -891,10 +891,10 @@ EAPI Eina_Bool eina_hash_del_by_hash(Eina_Hash *hash, /** * @brief Retrieves a specific entry from the given hash table. * - * @param hash The given hash table. Cannot be @c NULL. - * @param key The key of the entry to find. - * @param key_length The length of the key. - * @param key_hash The hash that always matches the key + * @param[in] hash The given hash table. Cannot be @c NULL. + * @param[in] key The key of the entry to find. + * @param[in] key_length The length of the key. + * @param[in] key_hash The hash that always matches the key * @return The data pointer for the stored entry on success, or @c NULL * if @p hash is @c NULL or if the data pointer could not be retrieved. * @@ -912,13 +912,13 @@ EAPI void *eina_hash_find_by_hash(const Eina_Hash *hash, * @brief Modifies the entry pointer at the specified key and returns * the previous entry. * - * @param hash The given hash table. - * @param key The key of the entry to modify. - * @param key_length Should be the length of @p key (don't forget to count + * @param[in,out] hash The given hash table. + * @param[in] key The key of the entry to modify. + * @param[in] key_length Should be the length of @p key (don't forget to count * '\\0' for string). - * @param key_hash The hash that always matches the key. Ignored if @p + * @param[in] key_hash The hash that always matches the key. Ignored if @p * key is @c NULL. - * @param data The data to replace the current entry, if it exists. + * @param[in] data The data to replace the current entry, if it exists. * @return The data pointer for the previously stored entry, or @c NULL * if not found. If an existing entry is not found, nothing is added to * the hash. @@ -932,7 +932,7 @@ EAPI void *eina_hash_modify_by_hash(Eina_Hash *hash, /** * @brief Returns a new iterator associated with hash keys. * - * @param hash The hash. + * @param[in] hash The hash. * @return A new iterator, or @c NULL if memory could not be allocated. * * This function returns a newly allocated iterator associated with @p @@ -948,7 +948,7 @@ EAPI Eina_Iterator *eina_hash_iterator_key_new(const Eina_Hash *hash) EINA_MALLO /** * @brief Returns a new iterator associated with a hash. * - * @param hash The hash. + * @param[in] hash The hash. * @return A new iterator, or @c NULL if memory could not be allocated. * * This function returns a newly allocated iterator associated with @@ -964,7 +964,7 @@ EAPI Eina_Iterator *eina_hash_iterator_data_new(const Eina_Hash *hash) EINA_MALL /** * @brief Returned a new iterator associated with hash keys and data. * - * @param hash The hash. + * @param[in] hash The hash. * @return A new iterator, or @c NULL if memory could not be allocated. * * This function returns a newly allocated iterator associated with @p @@ -983,9 +983,9 @@ EAPI Eina_Iterator *eina_hash_iterator_tuple_new(const Eina_Hash *hash) EINA_MAL /** * @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. - * @param fdata The data pointer to pass to the function being called. + * @param[in] hash The hash table whose members will be walked. + * @param[in] func The function to call on each parameter. + * @param[in] fdata The data pointer to pass to the function being called. * * This function iterates over the hash table @p hash, calling the * function @p func on each member. If @p func modifies the contents @@ -1026,33 +1026,41 @@ EAPI void eina_hash_foreach(const Eina_Hash *hash, * This function is identical to the sequence of calling * eina_hash_find(), eina_list_append(), eina_hash_set(), * but with one fewer required hash lookup. - * @param hash The hash table. - * @param key The key associated with the data. - * @param data The data to append to the list. + * + * @param[in,out] hash The hash table. + * @param[in] key The key associated with the data. + * @param[in] data The data to append to the list. + * * @since 1.10 */ EAPI void eina_hash_list_append(Eina_Hash *hash, const void *key, const void *data) EINA_ARG_NONNULL(1, 2, 3); + /** * @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(), * but with one fewer required hash lookup. - * @param hash The hash table. - * @param key The key associated with the data. - * @param data The data to prepend to the list. + * + * @param[in,out] hash The hash table. + * @param[in] key The key associated with the data. + * @param[in] data The data to prepend to the list. + * * @since 1.10 */ EAPI void eina_hash_list_prepend(Eina_Hash *hash, const void *key, const void *data) EINA_ARG_NONNULL(1, 2, 3); + /** * @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(), * but with one fewer required hash lookup. - * @param hash The hash table. - * @param key The key associated with the data. - * @param data The data to remove from the list. + * + * @param[in,out] hash The hash table. + * @param[in] key The key associated with the data. + * @param[in] data The data to remove from the list. + * * @since 1.10 */ EAPI void eina_hash_list_remove(Eina_Hash *hash, const void *key, const void *data) EINA_ARG_NONNULL(1, 2, 3); @@ -1061,8 +1069,8 @@ EAPI void eina_hash_list_remove(Eina_Hash *hash, const void *key, const void *da * @brief * Paul Hsieh (http://www.azillionmonkeys.com/qed/hash.html) hash function used by WebCore (http://webkit.org/blog/8/hashtables-part-2/) * - * @param key The key to hash. - * @param len The length of the key. + * @param[in] key The key to hash. + * @param[in] len The length of the key. * @return The hash value. */ EAPI int eina_hash_superfast(const char *key, @@ -1072,8 +1080,8 @@ EAPI int eina_hash_superfast(const char *key, * @brief * Hash function first reported by Dan Bernstein many years ago in comp.lang.c * - * @param key The key to hash. - * @param len The length of the key. + * @param[in] key The key to hash. + * @param[in] len The length of the key. * @return The hash value. */ static inline int eina_hash_djb2(const char *key, @@ -1083,8 +1091,8 @@ static inline int eina_hash_djb2(const char *key, * @brief * Hash function first reported by Dan Bernstein many years ago in comp.lang.c * - * @param key The key to hash. - * @param plen The length of the key. + * @param[in] key The key to hash. + * @param[in] plen The length of the key. * @return The hash value. */ static inline int eina_hash_djb2_len(const char *key, @@ -1094,8 +1102,8 @@ static inline int eina_hash_djb2_len(const char *key, * @brief * Hash function from http://web.archive.org/web/20071223173210/http://www.concentric.net/~Ttwang/tech/inthash.htm * - * @param pkey The key to hash. - * @param len The length of the key. + * @param[in] pkey The key to hash. + * @param[in] len The length of the key. * @return The hash value. */ static inline int eina_hash_int32(const unsigned int *pkey, @@ -1105,8 +1113,8 @@ static inline int eina_hash_int32(const unsigned int *pkey, * @brief * Hash function from http://web.archive.org/web/20071223173210/http://www.concentric.net/~Ttwang/tech/inthash.htm * - * @param pkey The key to hash. - * @param len The length of the key. + * @param[in] pkey The key to hash. + * @param[in] len The length of the key. * @return The hash value. */ static inline int eina_hash_int64(const unsigned long long int *pkey, @@ -1116,8 +1124,8 @@ static inline int eina_hash_int64(const unsigned long long int *pkey, * @brief * Hash function from http://sites.google.com/site/murmurhash/ * - * @param key The key to hash. - * @param len The length of the key. + * @param[in] key The key to hash. + * @param[in] len The length of the key. * @return The hash value. */ static inline int eina_hash_murmur3(const char *key, @@ -1127,8 +1135,8 @@ static inline int eina_hash_murmur3(const char *key, * @brief * Hash function using crc-32 algorithm and and 0xEDB88320 polynomial * - * @param key The key to hash. - * @param len The length of the key. + * @param[in] key The key to hash. + * @param[in] len The length of the key. * @return The hash value. */ static inline int eina_hash_crc(const char *key, diff --git a/src/lib/eina/eina_lalloc.h b/src/lib/eina/eina_lalloc.h index 114d0a9eae..bb14a7163c 100644 --- a/src/lib/eina/eina_lalloc.h +++ b/src/lib/eina/eina_lalloc.h @@ -39,9 +39,10 @@ * */ typedef Eina_Bool (*Eina_Lalloc_Alloc)(void *user_data, int num); + /** * @def EINA_LALLOC_ALLOC - * @param function The function to allocate. + * @param[in] function The function to allocate. */ #define EINA_LALLOC_ALLOC(function) ((Eina_Lalloc_Alloc)function) diff --git a/src/lib/eina/eina_matrix.h b/src/lib/eina/eina_matrix.h index ade4249b04..ed12f6f0db 100644 --- a/src/lib/eina/eina_matrix.h +++ b/src/lib/eina/eina_matrix.h @@ -421,7 +421,7 @@ EAPI void eina_matrix3_identity(Eina_Matrix3 *t); /** * @brief Calculates the determinant of the given matrix. * - * @param m[in] The matrix. + * @param[in] m The matrix. * @return The determinant. * * This function returns the determinant of the matrix @p m. No check diff --git a/src/lib/eina/eina_promise.h b/src/lib/eina/eina_promise.h index 769e02233e..1a142208b8 100644 --- a/src/lib/eina/eina_promise.h +++ b/src/lib/eina/eina_promise.h @@ -149,7 +149,7 @@ struct _Eina_Future_Scheduler { * * @note Must not be @c NULL. * - * @param entry The scheduled event to cancel + * @param[in,out] entry The scheduled event to cancel */ void (*recall)(Eina_Future_Schedule_Entry *entry); }; @@ -1196,7 +1196,7 @@ EAPI Eina_Future_Desc eina_future_cb_console_from_desc(const Eina_Future_Cb_Cons * next future in the chain. * * @param[in] err The error to be ignored. - * @param A future descriptor to be used with eina_future_then() or eina_future_chain() + * @return A future descriptor to be used with eina_future_then() or eina_future_chain() */ EAPI Eina_Future_Desc eina_future_cb_ignore_error(Eina_Error err); diff --git a/src/lib/eina/eina_slstr.h b/src/lib/eina/eina_slstr.h index 881276f615..ce93e23b78 100644 --- a/src/lib/eina/eina_slstr.h +++ b/src/lib/eina/eina_slstr.h @@ -36,7 +36,7 @@ typedef const char Eina_Slstr; /** * @brief Create a new short lived string by duplicating another string. * - * @param string An existing string, it will be copied. + * @param[in] string An existing string, it will be copied. * @return A new Eina_Slstr or NULL if out of memory. * * Usage example: @@ -54,7 +54,7 @@ eina_slstr_copy_new(const char *string); /** * @brief Create a new short lived string by taking ownership of a string. * - * @param string An existing string. It will not be duplicated. + * @param[in] string An existing string. It will not be duplicated. * @return A new Eina_Slstr or NULL if out of memory. * * Usage example: @@ -71,7 +71,7 @@ eina_slstr_steal_new(char *string); /** * @brief Create a new short lived string by taking ownership of a stringshare. * - * @param string An existing stringshare, one reference belongs to this slstr. + * @param[in] string An existing stringshare, one reference belongs to this slstr. * @return A new Eina_Slstr or NULL if out of memory. * * Usage example: @@ -88,7 +88,7 @@ eina_slstr_stringshare_new(Eina_Stringshare *string); /** * @brief Create a new short lived string by taking ownership of a tmpstr. * - * @param string An existing tmpstr, it will be freed later. + * @param[in] string An existing tmpstr, it will be freed later. * @return A new Eina_Slstr or NULL if out of memory. * * Usage example: @@ -105,7 +105,7 @@ eina_slstr_tmpstr_new(Eina_Tmpstr *string); /** * @brief Create a new short lived string by taking ownership of a strbuf. * - * @param string An existing strbuf, that will be released (i.e.. steal + free). + * @param[in] string An existing strbuf, that will be released (i.e.. steal + free). * @return A new Eina_Slstr or NULL if out of memory. * * Usage example: @@ -126,8 +126,8 @@ eina_slstr_strbuf_new(Eina_Strbuf *string); /** * @brief Create a new short lived string using sprintf. * - * @param fmt Format string for printf - * @param args List of format parameters for printf + * @param[in] fmt Format string for printf + * @param[in] args List of format parameters for printf * @return A new Eina_Slstr or NULL if out of memory. * * @since 1.19 @@ -138,8 +138,8 @@ eina_slstr_vasprintf_new(const char *fmt, va_list args); /** * @brief Create a new short lived string using sprintf. * - * @param fmt Format string for printf - * @param args List of format parameters for printf + * @param[in] fmt Format string for printf + * @param[in] args List of format parameters for printf * @return A new Eina_Slstr or NULL if out of memory. * * Usage example: diff --git a/src/lib/eina/eina_str.h b/src/lib/eina/eina_str.h index 742c02be55..e8bf685067 100644 --- a/src/lib/eina/eina_str.h +++ b/src/lib/eina/eina_str.h @@ -85,9 +85,9 @@ /** * @brief Copies a c-string to another. * - * @param dst The destination string. - * @param src The source string. - * @param siz The size of the destination string. + * @param[out] dst The destination string. + * @param[in] src The source string. + * @param[in] siz The size of the destination string. * @return The length of the source string. * * This function copies up to @p siz - 1 characters from the @@ -105,9 +105,9 @@ EAPI size_t eina_strlcpy(char *dst, const char *src, size_t siz) EINA_A /** * @brief Appends a c-string. * - * @param dst The destination string. - * @param src The source string. - * @param siz The size of the destination string. + * @param[out] dst The destination string. + * @param[in] src The source string. + * @param[in] siz The size of the destination string. * @return The length of the source string plus MIN(siz, strlen(initial dst)) * * This function appends @p src to @p dst of size @p siz (unlike @@ -123,8 +123,8 @@ EAPI size_t eina_strlcat(char *dst, const char *src, size_t siz) EINA_A /** * @brief Checks if the given string has the given prefix. * - * @param str The string to work with. - * @param prefix The prefix to check for. + * @param[in] str The string to work with. + * @param[in] prefix The prefix to check for. * @return #EINA_TRUE if the string has the given prefix, #EINA_FALSE otherwise. * * This function returns #EINA_TRUE if @p str has the prefix @@ -136,8 +136,8 @@ EAPI Eina_Bool eina_str_has_prefix(const char *str, const char *prefix) EI /** * @brief Checks if the given string has the given suffix. * - * @param str The string to work with. - * @param suffix The suffix to check for. + * @param[in] str The string to work with. + * @param[in] suffix The suffix to check for. * @return #EINA_TRUE if the string has the given suffix, #EINA_FALSE otherwise. * * This function returns #EINA_TRUE if @p str has the suffix @@ -149,8 +149,8 @@ EAPI Eina_Bool eina_str_has_suffix(const char *str, const char *suffix) EI /** * @brief Checks if the given string has the given extension. * - * @param str The string to work with. - * @param ext The extension to check for. + * @param[in] str The string to work with. + * @param[in] ext The extension to check for. * @return #EINA_TRUE if the string has the given extension, #EINA_FALSE otherwise. * * This function does the same as eina_str_has_suffix(), except it's case @@ -161,9 +161,9 @@ EAPI Eina_Bool eina_str_has_extension(const char *str, const char *ext) EI /** * @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. - * @param max_tokens The maximum number of strings to split string into, or a number less + * @param[in] string The string to split. + * @param[in] delimiter The string which specifies the places at which to split the string. + * @param[in] max_tokens The maximum number of strings to split string into, or a number less * than 1 to split as many times as possible. This parameter * IGNORES the added @c NULL terminator. * @return A newly-allocated NULL-terminated array of strings or @c NULL if it @@ -187,12 +187,12 @@ EAPI char **eina_str_split(const char *string, const char *delimiter, i /** * @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. - * @param max_tokens The maximum number of strings to split string into, or a number less + * @param[in] string The string to split. + * @param[in] delimiter The string which specifies the places at which to split the string. + * @param[in] max_tokens The maximum number of strings to split string into, or a number less * than 1 to split as many times as possible. This parameter * IGNORES the added @c NULL terminator. - * @param elements Where to return the number of elements in returned + * @param[out] elements Where to return the number of elements in returned * array. This array is guaranteed to be no greater than @p max_tokens, and * it will NOT count the @c NULL terminator element. * @return A newly-allocated NULL-terminated array of strings or @c NULL if it @@ -221,13 +221,13 @@ EAPI char **eina_str_split_full(const char *string, const char *delimit /** * @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 b Second string to use, after @p sep. - * @param b_len Length of @p b. + * @param[out] dst The buffer to store the result. + * @param[in] size Size (in byte) of the buffer. + * @param[in] sep The separator character to use. + * @param[in] a First string to use, before @p sep. + * @param[in] a_len Length of @p a. + * @param[in] b Second string to use, after @p sep. + * @param[in] 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 @@ -250,9 +250,9 @@ EAPI size_t eina_str_join_len(char *dst, size_t size, char sep, const c /** * @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. - * @param text The text to convert. + * @param[in] enc_from Encoding to convert from. + * @param[in] enc_to Encoding to convert to. + * @param[in] text The text to convert. * @return The converted text. * * This function converts @p text, encoded in @p enc_from. On success, @@ -269,11 +269,11 @@ EAPI char *eina_str_convert(const char *enc_from, const char *enc_to, /** * @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. - * @param text The text to convert. - * @param len The size in bytes of the text to convert. - * @param retlen The size in bytes of the converted text. + * @param[in] enc_from Encoding to convert from. + * @param[in] enc_to Encoding to convert to. + * @param[in] text The text to convert. + * @param[in] len The size in bytes of the text to convert. + * @param[in] retlen The size in bytes of the converted text. * @return The converted text. * * This function converts @p text, encoded in @p enc_from. On success, @@ -290,7 +290,7 @@ EAPI char *eina_str_convert_len(const char *enc_from, const char *enc_ /** * @brief Escapes slashes, spaces and apostrophes in strings. * - * @param str The string to escape. + * @param[in] str The string to escape. * @return The escaped string. * * Escaping is done by adding a slash "\" before any occurrence of slashes "\" @@ -305,7 +305,7 @@ EAPI char *eina_str_escape(const char *str) EINA_WARN_UNUSED_RESULT EI /** * @brief Lowercases all the characters in range [A-Z] in the given string. * - * @param str The string to lowercase. + * @param[in,out] str The string to lowercase. * * This function modifies the original string, changing all characters * in [A-Z] to lowercase. If @p str is @c NULL or is an empty string, @@ -316,7 +316,7 @@ EAPI void eina_str_tolower(char **str); /** * @brief Uppercases all the characters in range [a-z] in the given string. * - * @param str The string to uppercase. + * @param[in,out] str The string to uppercase. * * This function modifies the original string, changing all characters * in [a-z] to uppercase. If @p str is @c NULL or is an empty string, @@ -330,10 +330,10 @@ static inline size_t eina_str_join(char *dst, size_t size, char sep, const char * @def eina_str_join_static(dst, sep, a, b) * @brief 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. - * @param a First string to use, before @p sep. - * @param b Second string to use, after @p sep. + * @param[out] dst The buffer to store the result. + * @param[in] sep The separator character to use. + * @param[in] a First string to use, before @p sep. + * @param[in] b Second string to use, after @p sep. * @return The number of characters printed. * * This function is similar to eina_str_join_len(), but will assume @@ -348,9 +348,9 @@ static inline size_t eina_strlen_bounded(const char *str, size_t maxlen) EINA_PU /** * @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' + * @param[in] mem The memory to copy + * @param[in] size The size of @p mem + * @param[in] terminate If true, the returned memory will be nul terminated with '\0' * @return The copied memory, must be freed * @since 1.13 */ @@ -359,8 +359,8 @@ EAPI unsigned char *eina_memdup(unsigned char *mem, size_t size, Eina_Bool termi /** * @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. + * @param[in] tm Pointer to a tm structure needed by strftime. + * @param[in] format String containing format specifiers needed by strftime. * @return Updated buffer based on strftime output * * This will create a buffer of exact required size based on strftime output diff --git a/src/lib/eina/eina_stringshare.h b/src/lib/eina/eina_stringshare.h index 3c4b836486..ccb865075f 100644 --- a/src/lib/eina/eina_stringshare.h +++ b/src/lib/eina/eina_stringshare.h @@ -178,8 +178,8 @@ typedef const char Eina_Stringshare; * @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)). + * @param[in] str The string to retrieve an instance of. + * @param[in] slen The string size (<= strlen(str)). * @return A pointer to an instance of the string on success, * @c NULL on failure. * @@ -199,7 +199,7 @@ EAPI Eina_Stringshare *eina_stringshare_add_length(const char *str, unsigned in /** * @brief Retrieves an instance of a string for use in a program. * - * @param str The NULL-terminated string to retrieve an instance of. + * @param[in] str The NULL-terminated string to retrieve an instance of. * @return A pointer to an instance of the string on success, * @c NULL on failure. * @@ -220,7 +220,7 @@ EAPI Eina_Stringshare *eina_stringshare_add(const char *str) EINA_WARN_UNUSED_R * @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[in] fmt The NULL-terminated format string to retrieve an instance of. * @return A pointer to an instance of the string on success, * @c NULL on failure. * @@ -241,8 +241,8 @@ EAPI Eina_Stringshare *eina_stringshare_printf(const char *fmt, ...) EINA_WARN_ * @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 + * @param[in] fmt The NULL-terminated format string to retrieve an instance of. + * @param[in] args The va_args for @p fmt * @return A pointer to an instance of the string on success, * @c NULL on failure. * @@ -262,8 +262,9 @@ EAPI Eina_Stringshare *eina_stringshare_vprintf(const char *fmt, va_list args) /** * @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. + * + * @param[in] len The length of the format string to use + * @param[in] fmt The format string to retrieve an instance of. * @return A pointer to an instance of the string on success, * @c NULL on failure. * @@ -282,7 +283,7 @@ EAPI Eina_Stringshare *eina_stringshare_nprintf(unsigned int len, const char *f /** * Increment references of the given shared string. * - * @param str The shared string. + * @param[in,out] str The shared string. * @return A pointer to an instance of the string on success, * @c NULL on failure. * @@ -298,7 +299,7 @@ EAPI Eina_Stringshare *eina_stringshare_ref(Eina_Stringshare *str); /** * @brief Notes that the given string has lost an instance. * - * @param str String the given string. + * @param[in,out] 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 @@ -313,7 +314,7 @@ EAPI void eina_stringshare_del(Eina_Stringshare *str); /** * @brief Notes that the given string @b must be shared. * - * @param str The shared string to know the length. It is safe to + * @param[in] 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. * diff --git a/src/lib/eina/eina_thread.h b/src/lib/eina/eina_thread.h index 076a36d247..15e522fc4c 100644 --- a/src/lib/eina/eina_thread.h +++ b/src/lib/eina/eina_thread.h @@ -77,8 +77,8 @@ EAPI Eina_Thread eina_thread_self(void) EINA_WARN_UNUSED_RESULT; /** * @brief Checks if two thread identifiers are the same. - * @param t1 first thread identifier to compare. - * @param t2 second thread identifier to compare. + * @param[in] t1 first thread identifier to compare. + * @param[in] t2 second thread identifier to compare. * @return #EINA_TRUE if they are equal, #EINA_FALSE otherwise. * @since 1.8 */ @@ -88,10 +88,10 @@ EAPI Eina_Bool eina_thread_equal(Eina_Thread t1, Eina_Thread t2) EINA_WARN_UNUSE * @brief Creates a new thread, setting its priority and affinity. * * @param[out] t where to return the thread identifier. Must @b not be @c NULL. - * @param prio thread priority to use, usually EINA_THREAD_BACKGROUND - * @param affinity thread affinity to use. To not set affinity use @c -1. - * @param func function to run in the thread. Must @b not be @c NULL. - * @param data context data to provide to @a func as first argument. + * @param[in] prio thread priority to use, usually EINA_THREAD_BACKGROUND + * @param[in] affinity thread affinity to use. To not set affinity use @c -1. + * @param[in] func function to run in the thread. Must @b not be @c NULL. + * @param[in] data context data to provide to @a func as first argument. * @return #EINA_TRUE if thread was created, #EINA_FALSE on errors. * @since 1.8 */ @@ -121,7 +121,7 @@ EAPI extern const void *EINA_THREAD_JOIN_CANCELED; * and may be @c NULL on errors. See @ref Eina_Error_Group to identify * problems. * - * @param t thread identifier to wait. + * @param[in] t thread identifier to wait. * @return value returned by @a t creation function @c func() or * @c NULL on errors. Check error with @ref Eina_Error_Group. * If the thread was canceled, it will return @@ -139,8 +139,8 @@ EAPI void *eina_thread_join(Eina_Thread t); * for debugging to name a thread so external tools can display a * meaningful name attached to the thread. * - * @param t thread to set the name of - * @param name a string to name the thread - this cannot be NULL + * @param[in] t thread to set the name of + * @param[in] name a string to name the thread - this cannot be NULL * @return EINA_TRUE if it succeeds in setting the name or EINA_FALSE * otherwise. * @since 1.16 @@ -160,7 +160,7 @@ EAPI Eina_Bool eina_thread_name_set(Eina_Thread t, const char *name); * A thread that was canceled will return EINA_THREAD_JOIN_CANCELED * when eina_thread_join() is called. * - * @param t Thread to cancel. + * @param[in] 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 @@ -189,10 +189,10 @@ EAPI Eina_Bool eina_thread_cancel(Eina_Thread t); * or the helper function eina_thread_cancellable_run() which does the * pair for you. * - * @param cancellable If EINA_TRUE, this thread will be accept + * @param[in] 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[in] 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 @@ -246,8 +246,8 @@ EAPI void eina_thread_cancel_checkpoint(void); * @b not be executed! To avoid problems prefer to use * eina_thread_cancellable_run()! * - * @param cleanup The function to execute on cancellation. - * @param data The context to give to cleanup function. + * @param[in] cleanup The function to execute on cancellation. + * @param[in] data The context to give to cleanup function. * * @see eina_thread_cancellable_run() * @@ -276,7 +276,7 @@ EAPI void eina_thread_cancel_checkpoint(void); * @b not be executed even if exec_cleanup is EINA_TRUE! To * avoid problems prefer to use eina_thread_cancellable_run()! * - * @param exec_cleanup if EINA_TRUE, the function registered with + * @param[in] exec_cleanup if EINA_TRUE, the function registered with * EINA_THREAD_CLEANUP_PUSH() will be executed. * * @see eina_thread_cancellable_run() @@ -320,16 +320,16 @@ typedef void *(*Eina_Thread_Cancellable_Run_Cb)(void *data); * return ret; * @endcode * - * @param cb a cancellable callback to possibly run. The callback @b + * @param[in] cb a cancellable callback to possibly run. The callback @b * may not be executed if the thread had a pending cancellation * request. During its execution the callback may be canceled * at explicit cancellation points using * eina_thread_cancel_checkpoint(), as well as some syscalls * defined in man:pthreads(7). - * @param cleanup_cb a cleanup callback to be executed regardless of + * @param[in] cleanup_cb a cleanup callback to be executed regardless of * the thread being canceled or not. This function will be * executed even if @a cb wasn't. - * @param data context to give to both @a cb and @a cleanup_cb. + * @param[in] data context to give to both @a cb and @a cleanup_cb. * * @return the return value of @a cb. If the thread was canceled, * this function will not return. diff --git a/src/lib/eina/eina_thread_queue.h b/src/lib/eina/eina_thread_queue.h index 4009a0efb5..dd8f90d455 100644 --- a/src/lib/eina/eina_thread_queue.h +++ b/src/lib/eina/eina_thread_queue.h @@ -83,7 +83,7 @@ eina_thread_queue_new(void); * on messages or sending them. Any pending messages will be freed without * being processed by a listener. * - * @param thq The thread queue to free + * @param[in] thq The thread queue to free * * @since 1.11 */ @@ -93,9 +93,9 @@ eina_thread_queue_free(Eina_Thread_Queue *thq) EINA_ARG_NONNULL(1); /** * @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 - * @param allocref A pointer to store a general reference handle for the message + * @param[in,out] thq The thread queue to allocate the message on + * @param[in] size The size, in bytes, of the message, including standard header + * @param[out] allocref A pointer to store a general reference handle for the message * @return A pointer to the message data to fill in * * This allocates space for a new message on the message queue, but does not @@ -112,8 +112,8 @@ eina_thread_queue_send(Eina_Thread_Queue *thq, int size, void **allocref) EINA_A /** * @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() + * @param[in,out] thq The thread queue the message was placed on + * @param[in,out] allocref The allocref returned by eina_thread_queue_send() * * This completes the send and triggers the thread queue to wake up any * listeners. @@ -126,8 +126,8 @@ eina_thread_queue_send_done(Eina_Thread_Queue *thq, void *allocref) EINA_ARG_NON /** * @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 + * @param[in,out] thq The thread queue to fetch the message from + * @param[out] allocref A pointer to store a general reference handle for the message * @return A pointer to the message data * * This will fetch the next message to read from the thread queue and return @@ -146,8 +146,8 @@ eina_thread_queue_wait(Eina_Thread_Queue *thq, void **allocref) EINA_ARG_NONNULL /** * @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() + * @param[in,out] thq The thread queue the message was fetched from + * @param[in,out] allocref The allocref returned by eina_thread_queue_wait() * * This should be used after eina_thread_queue_wait() or * eina_thread_queue_poll() to indicate the caller is done with the message. @@ -160,8 +160,8 @@ eina_thread_queue_wait_done(Eina_Thread_Queue *thq, void *allocref) EINA_ARG_NON /** * @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 + * @param[in,out] thq The thread queue to fetch the message from + * @param[out] allocref A pointer to store a general reference handle for the message * @return A pointer to the message data * * This is the same as eina_thread_queue_wait(), but if no messages are @@ -178,7 +178,7 @@ eina_thread_queue_poll(Eina_Thread_Queue *thq, void **allocref) EINA_ARG_NONNULL /** * @brief Gets the number of messages on a queue as yet unfetched. * - * @param thq The thread queue to query for pending count + * @param[in] thq The thread queue to query for pending count * @return The number of messages waiting to be fetched * * This returns the number of messages waiting to be fetched with @@ -192,8 +192,8 @@ eina_thread_queue_pending_get(const Eina_Thread_Queue *thq) EINA_ARG_NONNULL(1); /** * @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 + * @param[in,out] thq The thread queue to alter the parent of + * @param[in] thq_parent The new parent to set * * This sets the parent queue where messages will be reported to. This is * how you can listen to multiple queues at once - set multiple queues to @@ -209,7 +209,7 @@ eina_thread_queue_parent_set(Eina_Thread_Queue *thq, Eina_Thread_Queue *thq_pare /** * @brief Gets the parent of a thread queue. * - * @param thq The thread queue to get the parent of + * @param[in] thq The thread queue to get the parent of * @return The parent thread queue * * This gets the parent set by eina_thread_queue_parent_get(). If no parent @@ -225,8 +225,8 @@ eina_thread_queue_parent_get(const Eina_Thread_Queue *thq) EINA_ARG_NONNULL(1); /** * @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 + * @param[in,out] thq The thread queue to set the file descriptor of + * @param[in] 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 @@ -245,7 +245,7 @@ eina_thread_queue_fd_set(Eina_Thread_Queue *thq, int fd) EINA_ARG_NONNULL(1); /** * @brief Gets the file descriptor written to on message sends. * - * @param thq The thread queue to get the file descriptor of + * @param[in] thq The thread queue to get the file descriptor of * @return The file descriptor set (or -1 if none is set). * * This returns the file descriptor set by eina_thread_queue_fd_set() and diff --git a/src/lib/eina/eina_tiler.h b/src/lib/eina/eina_tiler.h index c6dd492d2f..28492efc4f 100644 --- a/src/lib/eina/eina_tiler.h +++ b/src/lib/eina/eina_tiler.h @@ -177,8 +177,8 @@ typedef struct _Eina_Tile_Grid_Slicer Eina_Tile_Grid_Slicer; /** * @brief Creates a new tiler with @p w width and @p h height. * - * @param w Width of the tiler - * @param h Height of the tiler + * @param[in] w Width of the tiler + * @param[in] h Height of the tiler * @return The newly created tiler * * @see eina_tiler_free() @@ -188,7 +188,7 @@ EAPI Eina_Tiler *eina_tiler_new(int w, int h); /** * @brief Frees a tiler. * - * @param t The tiler to free. + * @param[in] t The tiler to free. * * This function frees @p t. It does not free the memory allocated for the * elements of @p t. @@ -198,9 +198,9 @@ EAPI void eina_tiler_free(Eina_Tiler *t); /** * @brief Sets the size of tiles for a tiler. * - * @param t The tiler whose tile size will be set. - * @param w Width of the tiles. - * @param h Height of the tiles. + * @param[in,out] t The tiler whose tile size will be set. + * @param[in] w Width of the tiles. + * @param[in] h Height of the tiles. * * @warning @p w and @p h @b must be greater than zero, otherwise tile size * won't be changed. @@ -211,9 +211,9 @@ EAPI void eina_tiler_tile_size_set(Eina_Tiler *t, int w, int h); /** * @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. - * @param h Height of the area. + * @param[in,out] t The tiler whose area size will be set. + * @param[in] w Width of the area. + * @param[in] h Height of the area. * * @since 1.8 * @@ -224,9 +224,9 @@ EAPI void eina_tiler_area_size_set(Eina_Tiler *t, int w, int h); /** * @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. - * @param h Height of the area. + * @param[in] t The tiler whose area size will be fetched. + * @param[out] w Width of the area. + * @param[out] h Height of the area. * * @since 1.8 */ @@ -235,8 +235,8 @@ EAPI void eina_tiler_area_size_get(const Eina_Tiler *t, int *w, in /** * @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 loose + * @param[in,out] t The tiler to apply the strict rules to. + * @param[in] strict Define if it will be strict or loose * * By default it will be loose. * @@ -247,7 +247,7 @@ EAPI void eina_tiler_strict_set(Eina_Tiler *t, Eina_Bool strict); /** * @brief Tells if a tiler is empty or not. * - * @param t The tiler to apply the strict rules to. + * @param[in] t The tiler to apply the strict rules to. * @return #EINA_TRUE when empty, #EINA_FALSE when not. * * @since 1.8 @@ -257,8 +257,8 @@ EAPI Eina_Bool eina_tiler_empty(const Eina_Tiler *t); /** * @brief Adds a rectangle to a tiler. * - * @param t The tiler in which to add a container. - * @param r The rectangle to be added. + * @param[in,out] t The tiler in which to add a container. + * @param[in] r The rectangle to be added. * @return #EINA_TRUE on success, #EINA_FALSE on failure. * * @see eina_tiler_rect_del() @@ -268,8 +268,8 @@ EAPI Eina_Bool eina_tiler_rect_add(Eina_Tiler *t, const Eina_Rectangle /** * @brief Removes a rectangle from a tiler. * - * @param t The tiler in which to add a container. - * @param r The rectangle to be removed. + * @param[in,out] t The tiler in which to add a container. + * @param[in] r The rectangle to be removed. * * @see eina_tiler_rect_add() * @see eina_tiler_clear() @@ -279,7 +279,7 @@ EAPI void eina_tiler_rect_del(Eina_Tiler *t, const Eina_Rectangle /** * @brief Removes all rectangles from tiles. * - * @param t The tiler to clear. + * @param[in,out] t The tiler to clear. * * @see eina_tiler_rect_del() */ @@ -288,7 +288,7 @@ EAPI void eina_tiler_clear(Eina_Tiler *t); /** * @brief Creates a iterator to access the tilers calculated rectangles. * - * @param t The tiler to iterate over. + * @param[in] t The tiler to iterate over. * @return A iterator containing Eina_Rectangle. */ EAPI Eina_Iterator *eina_tiler_iterator_new(const Eina_Tiler *t); @@ -296,12 +296,12 @@ EAPI Eina_Iterator *eina_tiler_iterator_new(const Eina_Tiler *t); /** * @brief Creates a new Eina_Iterator that iterates over a list of tiles. * - * @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[in] x X axis coordinate. + * @param[in] y Y axis coordinate. + * @param[in] w Width. + * @param[in] h Height. + * @param[in] tile_w Tile width. + * @param[in] 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 @@ -317,8 +317,8 @@ EAPI Eina_Iterator *eina_tile_grid_slicer_iterator_new(int x, int y, int w, /** * @brief Gets the union of two tilers. * - * @param dst The first tiler, will store the result. - * @param src The second tiler. + * @param[in,out] dst The first tiler, will store the result. + * @param[in] src The second tiler. * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * * This function gets the union of tilers @p dst and @p src. @@ -330,8 +330,8 @@ EAPI Eina_Bool eina_tiler_union(Eina_Tiler *dst, Eina_Tiler *src); /** * @brief Subtracts two tilers. * - * @param dst The first tiler, will store the result. - * @param src The second tiler. + * @param[in,out] dst The first tiler, will store the result. + * @param[in] src The second tiler. * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * * This function subtracts two tilers @p dst and @p src. @@ -343,8 +343,8 @@ EAPI Eina_Bool eina_tiler_subtract(Eina_Tiler *dst, Eina_Tiler *src); /** * @brief Gets the intersection of two tilers. * - * @param t1 The first tile. - * @param t2 The second tiler. + * @param[in] t1 The first tile. + * @param[in] t2 The second tiler. * @return A pointer of intersection result. @c NULL if intersection doesn't exist. * * This function gets the intersection of two tilers @p t1 and @p t2. @@ -356,8 +356,8 @@ EAPI Eina_Tiler *eina_tiler_intersection(Eina_Tiler *t1, Eina_Tiler *t2); /** * @brief Gets whether two tilers are equal in rects or not. * - * @param t1 The first tiler. - * @param t2 The second tiler. + * @param[in] t1 The first tiler. + * @param[in] t2 The second tiler. * @return #EINA_TRUE if equal, #EINA_FALSE if unequal. * * This function gets result of comparison for @p t1 and @p t2. @@ -369,8 +369,8 @@ EAPI Eina_Bool eina_tiler_equal(const Eina_Tiler *t1, const Eina_Tiler /** * @brief Iterates over the tiles set by eina_tile_grid_slicer_setup(). * - * @param slc Pointer to an Eina_Tile_Grid_Slicer struct. - * @param rect Pointer to a struct Eina_Tile_Grid_Info *. + * @param[in,out] slc Pointer to an Eina_Tile_Grid_Slicer struct. + * @param[out] rect Pointer to a struct Eina_Tile_Grid_Info *. * @return #EINA_TRUE if the current rect is valid. #EINA_FALSE if there * are no more rects to iterate over (and thus the current one isn't valid). * @@ -385,13 +385,13 @@ static inline Eina_Bool eina_tile_grid_slicer_next(Eina_Tile_Grid_Slicer *slc, c /** * @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. + * @param[out] slc Pointer to an Eina_Tile_Grid_Slicer struct. + * @param[in] x X axis coordinate. + * @param[in] y Y axis coordinate. + * @param[in] w Width. + * @param[in] h Height. + * @param[in] tile_w Tile width. + * @param[in] 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 into a grid of diff --git a/src/lib/eina/eina_tmpstr.h b/src/lib/eina/eina_tmpstr.h index f300be13c3..164fe43aa5 100644 --- a/src/lib/eina/eina_tmpstr.h +++ b/src/lib/eina/eina_tmpstr.h @@ -123,7 +123,7 @@ typedef const char Eina_Tmpstr; /** * @brief Adds a new temporary string based on the input string. * - * @param str This is the input string that is copied into the temp string. + * @param[in] str This is the input string that is copied into the temp string. * @return A pointer to the tmp string that is a standard C string. * * When you add a temporary string (tmpstr) it is expected to have a very @@ -167,8 +167,8 @@ EAPI Eina_Tmpstr *eina_tmpstr_add(const char *str) EINA_WARN_UNUSED_RESULT; /** * @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[in] str This is the input string that is copied into the temp string. + * @param[in] length This is the maximum length and the allocated length of the temp string. * @return A pointer to the tmp string that is a standard C string. * * When you add a temporary string (tmpstr) it is expected to have a very @@ -213,7 +213,7 @@ EINA_DEPRECATED EAPI size_t eina_tmpstr_strlen(Eina_Tmpstr *tmpstr); /** * @brief Returns the length of a temporary string. * - * @param tmpstr This is any C string pointer, but if it is a tmp string + * @param[in] 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. * @@ -224,7 +224,7 @@ EAPI size_t eina_tmpstr_len(Eina_Tmpstr *tmpstr); /** * @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 + * @param[in] tmpstr This is any C string pointer, but if it is a tmp string * it is freed. * * This will delete the given temporary string @p tmpstr if it is a valid @@ -241,7 +241,7 @@ EAPI void eina_tmpstr_del(Eina_Tmpstr *tmpstr) EINA_ARG_NONNULL(1); * @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[in] 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 @@ -256,8 +256,8 @@ EAPI Eina_Tmpstr *eina_tmpstr_manage_new(char *str) EINA_WARN_UNUSED_RESULT; * @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[in] str The input string to manage. + * @param[in] 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 diff --git a/src/lib/eina/eina_trash.h b/src/lib/eina/eina_trash.h index 549d9359c4..78935ec5f1 100644 --- a/src/lib/eina/eina_trash.h +++ b/src/lib/eina/eina_trash.h @@ -60,8 +60,8 @@ static inline void eina_trash_init(Eina_Trash **trash) EINA_ARG_NONNULL(1); * 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*) + * @param[in,out] trash A pointer to an Eina_Trash + * @param[in] data An unused pointer big enough to put a (void*) * * @note Do not use the pointer after insertion or bad things will * happens. @@ -90,8 +90,8 @@ static inline void *eina_trash_pop(Eina_Trash **trash) EINA_ARG_NONNULL(1) EINA_ * @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 + * @param[in,out] trash The trash to clean + * @param[out] data The pointer extracted from the trash * * @note This macro can be used for freeing the data in the trash, like in * the following example: diff --git a/src/lib/eina/eina_types.h b/src/lib/eina/eina_types.h index 84979022c9..131003c61c 100644 --- a/src/lib/eina/eina_types.h +++ b/src/lib/eina/eina_types.h @@ -312,7 +312,7 @@ * @def EINA_ARG_NONNULL * Used to warn when the specified arguments of the function are @c NULL. * - * @param ... Ordinals of the parameters to check for nullity (1..n) + * @param[in] ... Ordinals of the parameters to check for nullity (1..n) * * @return Nothing, but Doxygen will complain if it's not documented :-P * @@ -343,21 +343,21 @@ /** * @def EINA_PRINTF - * @param fmt The format to be used. - * @param arg The argument to be used. + * @param[in] fmt The format to be used. + * @param[in] arg The argument to be used. */ # define EINA_PRINTF(fmt, arg) /** * @def EINA_SCANF - * @param fmt The format to be used. - * @param arg The argument to be used. + * @param[in] fmt The format to be used. + * @param[in] arg The argument to be used. */ # define EINA_SCANF(fmt, arg) /** * @def EINA_FORMAT - * @param fmt The format to be used. + * @param[in] fmt The format to be used. */ # define EINA_FORMAT(fmt) @@ -375,13 +375,13 @@ /** * @def EINA_UNLIKELY - * @param exp The expression to be used. + * @param[in] exp The expression to be used. */ # define EINA_UNLIKELY(exp) exp /** * @def EINA_LIKELY - * @param exp The expression to be used. + * @param[in] exp The expression to be used. */ # define EINA_LIKELY(exp) exp diff --git a/src/lib/eina/eina_unicode.h b/src/lib/eina/eina_unicode.h index e32d0591f3..1f798ef52e 100644 --- a/src/lib/eina/eina_unicode.h +++ b/src/lib/eina/eina_unicode.h @@ -47,8 +47,8 @@ EAPI size_t eina_unicode_strlen(const Eina_Unicode *ustr) EINA_ARG_NONNUL * of n. If the terminating character is not found in the string, it returns * n. * - * @param ustr String to search - * @param n Max length to search + * @param[in] ustr String to search + * @param[in] n Max length to search * @return Number of characters or n. */ EAPI size_t eina_unicode_strnlen(const Eina_Unicode *ustr, int n) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT EINA_PURE; @@ -56,7 +56,7 @@ EAPI size_t eina_unicode_strnlen(const Eina_Unicode *ustr, int n) EINA_AR /** * @brief Same as the standard strdup just with Eina_Unicode instead of char. * - * @param text The text to duplicate. + * @param[in] text The text to duplicate. * @return The duplicated string. */ EAPI Eina_Unicode *eina_unicode_strdup(const Eina_Unicode *text) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; @@ -64,8 +64,8 @@ EAPI Eina_Unicode *eina_unicode_strdup(const Eina_Unicode *text) EINA_WARN_UNUSE /** * @brief Same as strdup but cuts on the given size. Assumes n < len * - * @param text The text to duplicate. - * @param n The maximum size of the text to duplicate. + * @param[in] text The text to duplicate. + * @param[in] n The maximum size of the text to duplicate. * @return The duplicated string. * * This function duplicates @p text. The resulting string is cut on @p @@ -79,8 +79,8 @@ EAPI Eina_Unicode *eina_unicode_strndup(const Eina_Unicode *text, size_t n) EINA /** * @brief Same as the standard strcmp just with Eina_Unicode instead of char. * - * @param a The text to be compared. - * @param b The text to be compared. + * @param[in] a The text to be compared. + * @param[in] b The text to be compared. * @return An integer value indicating the ordinal relation of @p a to @p b. */ EAPI int eina_unicode_strcmp(const Eina_Unicode *a, const Eina_Unicode *b) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2) EINA_PURE; @@ -88,8 +88,8 @@ EAPI int eina_unicode_strcmp(const Eina_Unicode *a, const Eina_Unicode /** * @brief Same as the standard strcpy just with Eina_Unicode instead of char. * - * @param dest The text which @p source is to be copied. - * @param source The text to copy from. + * @param[out] dest The text which @p source is to be copied. + * @param[in] source The text to copy from. * @return @p dest is returned. */ EAPI Eina_Unicode *eina_unicode_strcpy(Eina_Unicode *dest, const Eina_Unicode *source) EINA_ARG_NONNULL(1, 2); @@ -97,8 +97,8 @@ EAPI Eina_Unicode *eina_unicode_strcpy(Eina_Unicode *dest, const Eina_Unicode *s /** * @brief Same as the standard strstr just with Eina_Unicode instead of char. * - * @param haystack The text to be searched. - * @param needle The text to search for + * @param[in] haystack The text to be searched. + * @param[in] needle The text to search for * @return The substring of @p haystack which starts with @p needle * when @p needle is founded in @p haystack, or NULL is returned. */ @@ -107,9 +107,9 @@ EAPI Eina_Unicode *eina_unicode_strstr(const Eina_Unicode *haystack, const Eina_ /** * @brief Same as the standard strncpy just with Eina_Unicode instead of char. * - * @param dest The text which @p source is to be copied. - * @param source The text to copy from. - * @param n Maximum number of characters to be copied from @p source. + * @param[out] dest The text which @p source is to be copied. + * @param[in] source The text to copy from. + * @param[in] n Maximum number of characters to be copied from @p source. * @return @p dest is returned. */ EAPI Eina_Unicode *eina_unicode_strncpy(Eina_Unicode *dest, const Eina_Unicode *source, size_t n) EINA_ARG_NONNULL(1, 2); @@ -117,7 +117,7 @@ EAPI Eina_Unicode *eina_unicode_strncpy(Eina_Unicode *dest, const Eina_Unicode * /** * @see eina_str_escape() * - * @param str The string to escape. + * @param[in] str The string to escape. * @return The escaped string. */ EAPI Eina_Unicode *eina_unicode_escape(const Eina_Unicode *str) EINA_ARG_NONNULL(1) EINA_MALLOC EINA_WARN_UNUSED_RESULT; @@ -133,8 +133,8 @@ EAPI Eina_Unicode *eina_unicode_escape(const Eina_Unicode *str) EINA_ARG_NONNULL * On error: return a codepoint between DC80 to DCFF where the low 8 bits * are the byte's value. * - * @param buf the string - * @param iindex the index to look at and return by. + * @param[in] buf the string + * @param[in,out] iindex the index to look at and return by. * @return the codepoint found, 0 if @p buf or @p iindex are NULL * * @since 1.8.0 @@ -151,8 +151,8 @@ static inline Eina_Unicode eina_unicode_utf8_next_get(const char *buf, int *iind * On error: return a codepoint between DC80 to DCFF where the low 8 bits * are the byte's value. * - * @param buf the string - * @param iindex the index to look at and return by. + * @param[in] buf the string + * @param[in,out] 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 @@ -168,8 +168,8 @@ EAPI Eina_Unicode eina_unicode_utf8_get_next(const char *buf, int *iindex) EINA_ * On error: return a codepoint between DC80 to DCFF where the low 8 bits * are the byte's value. * - * @param buf the string - * @param iindex the index to look at and return by. + * @param[in] buf the string + * @param[in,out] iindex the index to look at and return by. * @return the codepoint found. * * @since 1.1.0 @@ -181,7 +181,7 @@ EAPI Eina_Unicode eina_unicode_utf8_get_prev(const char *buf, int *iindex) EINA_ * the number of Eina_Unicodes it'll take to store this string in * an Eina_Unicode string. * - * @param buf the string + * @param[in] buf the string * @return the number of unicode characters (not bytes) in the string * * @since 1.1.0 @@ -191,9 +191,10 @@ EAPI int eina_unicode_utf8_get_len(const char *buf) EINA_ARG_NONNULL(1); /** * Converts a utf-8 string to a newly allocated Eina_Unicode string. * - * @param utf the string in utf-8 - * @param _len the length of the returned Eina_Unicode string. + * @param[in] utf the string in utf-8 + * @param[out] _len the length of the returned Eina_Unicode string. * @return the newly allocated Eina_Unicode string. + * * @since 1.1.0 */ EAPI Eina_Unicode *eina_unicode_utf8_to_unicode(const char *utf, int *_len) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; @@ -201,9 +202,9 @@ EAPI Eina_Unicode *eina_unicode_utf8_to_unicode(const char *utf, int *_len) EINA /** * Converts an Eina_Unicode string to a newly allocated utf-8 substring at given length. * - * @param uni the Eina_Unicode string - * @param ulen the length in the unicode string to convert. - * @param _len the length byte length of the return utf8 substring. + * @param[in] uni the Eina_Unicode string + * @param[in] ulen the length in the unicode string to convert. + * @param[out] _len the length byte length of the return utf8 substring. * @return the newly allocated utf-8 substring. * * @since 1.17 @@ -213,8 +214,8 @@ EAPI char * eina_unicode_unicode_to_utf8_range(const Eina_Unicode *uni, int ulen /** * Converts an Eina_Unicode string to a newly allocated utf-8 string. * - * @param uni the Eina_Unicode string - * @param _len the length byte length of the return utf8 string. + * @param[in] uni the Eina_Unicode string + * @param[out] _len the length byte length of the return utf8 string. * @return the newly allocated utf-8 string. * * @since 1.1.0 diff --git a/src/lib/eina/eina_ustringshare.h b/src/lib/eina/eina_ustringshare.h index 7e74076611..5c92e5f67e 100644 --- a/src/lib/eina/eina_ustringshare.h +++ b/src/lib/eina/eina_ustringshare.h @@ -92,8 +92,8 @@ /** * @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)). + * @param[in] str The string to retrieve an instance of. + * @param[in] slen The string size (<= strlen(str)). * @return A pointer to an instance of the string on success, * @c NULL on failure. * @@ -114,7 +114,7 @@ EAPI const Eina_Unicode *eina_ustringshare_add_length(const Eina_Unicode *str, u /** * @brief Retrieves an instance of a string for use in a program. * - * @param str The NULL-terminated string to retrieve an instance of. + * @param[in] str The NULL-terminated string to retrieve an instance of. * @return A pointer to an instance of the string on success, * @c NULL on failure. * @@ -135,7 +135,7 @@ EAPI const Eina_Unicode *eina_ustringshare_add(const Eina_Unicode *str) EINA_WAR /** * @brief Increments references of the given shared string. * - * @param str The shared string. + * @param[in] str The shared string. * @return A pointer to an instance of the string on success, * @c NULL on failure. * @@ -151,7 +151,7 @@ EAPI const Eina_Unicode *eina_ustringshare_ref(const Eina_Unicode *str); /** * @brief Notes that the given string has lost an instance. * - * @param str String The given string. + * @param[in] 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 @@ -166,7 +166,7 @@ EAPI void eina_ustringshare_del(const Eina_Unicode *str); /** * @brief Notes that the given string @b must be shared. * - * @param str The shared string to know the length. It is safe to + * @param[in] str The shared string to know the length. It is safe to * give @c NULL, in that case @c -1 is returned. * @return The length of a shared string. * diff --git a/src/lib/eina/eina_util.h b/src/lib/eina/eina_util.h index dacd9cdd65..6afd424921 100644 --- a/src/lib/eina/eina_util.h +++ b/src/lib/eina/eina_util.h @@ -52,8 +52,8 @@ EAPI const char *eina_environment_tmp_get(void); /** * @brief Warningless comparison of doubles using == - * @param a First member to compare - * @param b Second member to compare + * @param[in] a First member to compare + * @param[in] b Second member to compare * * @return @c true if two doubles match * @since 1.19 @@ -62,8 +62,8 @@ static inline Eina_Bool eina_dbl_exact(double a, double b); /** * @brief Warningless comparison of floats using == - * @param a First member to compare - * @param b Second member to compare + * @param[in] a First member to compare + * @param[in] b Second member to compare * * @return @c true if two floats match * @since 1.19 @@ -72,8 +72,8 @@ static inline Eina_Bool eina_flt_exact(float a, float b); /** * @brief Safe comparison of float - * @param a First member to compare - * @param b Second member to compare + * @param[in] a First member to compare + * @param[in] b Second member to compare * @since 1.19 * * @return @c true if two floats match @@ -82,7 +82,7 @@ static inline Eina_Bool eina_flt_exact(float a, float b); /** * @brief Determines if a float is not zero - * @param a The float + * @param[in] a The float * * @return @c true if float is not zero * @since 1.19 @@ -91,8 +91,8 @@ static inline Eina_Bool eina_flt_exact(float a, float b); /** * @brief Safe comparison of double - * @param a First member to compare - * @param b Second member to compare + * @param[in] a First member to compare + * @param[in] b Second member to compare * @since 1.19 * * @return @c true if two double match @@ -101,7 +101,7 @@ static inline Eina_Bool eina_flt_exact(float a, float b); /** * @brief Determines if a double is not zero - * @param a The double + * @param[in] a The double * * @return @c true if double is not zero * @since 1.19 diff --git a/src/lib/eina/eina_value.h b/src/lib/eina/eina_value.h index 7124cbf07d..b3a702456e 100644 --- a/src/lib/eina/eina_value.h +++ b/src/lib/eina/eina_value.h @@ -951,8 +951,8 @@ static inline Eina_Bool eina_value_vget(const Eina_Value *value, /** * @brief Sets the generic value from pointer. * - * @param [in,out] value Source value object - * @param [in] ptr Pointer to specify the contents. + * @param[in,out] value Source value object + * @param[in] 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 @@ -1188,8 +1188,8 @@ struct _Eina_Value_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. + * @param[in] subtype How to manage this array members. + * @param[in] 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 @@ -1208,9 +1208,9 @@ EAPI Eina_Value *eina_value_array_new(const Eina_Value_Type *subtype, /** * @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. + * @param[out] value Value object + * @param[in] subtype How to manage array members. + * @param[in] 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 @@ -1235,7 +1235,7 @@ static inline Eina_Bool eina_value_array_setup(Eina_Value *value, /** * @brief Queries number of elements in value of array type. - * @param value value object. + * @param[in] value value object. * @return number of child elements. * @since 1.2 */ @@ -1243,8 +1243,8 @@ static inline unsigned int eina_value_array_count(const Eina_Value *value); /** * @brief Removes element at given position in value of array type. - * @param value value object. - * @param position index of the member + * @param[in,out] value value object. + * @param[in] position index of the member * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * @since 1.2 */ @@ -1253,8 +1253,8 @@ static inline Eina_Bool eina_value_array_remove(Eina_Value *value, /** * @brief Sets the generic value in an array member. - * @param value Source value object - * @param position Index of the member + * @param[in,out] value Source value object + * @param[in] position Index of the member * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * * The variable argument is dependent on chosen subtype. The list for @@ -1312,8 +1312,8 @@ static inline Eina_Bool eina_value_array_set(Eina_Value *value, /** * @brief Gets the generic value from an array member. - * @param value Source value object - * @param position Index of the member + * @param[in] value Source value object + * @param[in] position Index of the member * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * * The value is returned in the variable argument parameter, and the @@ -1369,8 +1369,9 @@ static inline Eina_Bool eina_value_array_get(const Eina_Value *value, /** * @brief Inserts a generic value in an array member position. - * @param value Source value object - * @param position Index of the member + * @param[in] value Source value object + * @param[in] position Index of the member + * @param[in] ... Variable arguments of data to insert * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * * The variable argument is dependent on chosen subtype. The list for @@ -1429,7 +1430,8 @@ static inline Eina_Bool eina_value_array_insert(Eina_Value *value, /** * @brief Appends a generic value in an array. * - * @param value Source value object + * @param[in,out] value Source value object + * @param[in] ... Variable arguments * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * * The variable argument is dependent on chosen subtype. The list for @@ -1486,9 +1488,9 @@ static inline Eina_Bool eina_value_array_append(Eina_Value *value, /** * @brief Sets a generic value to an array member. * - * @param value Source value object - * @param position Index of the member - * @param args Variable argument + * @param[in,out] value Source value object + * @param[in] position Index of the member + * @param[in] args Variable argument * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * * @see eina_value_array_set() @@ -1510,9 +1512,9 @@ static inline Eina_Bool eina_value_array_vset(Eina_Value *value, /** * @brief Gets the generic value from an array member. * - * @param value Source value object - * @param position Index of the member - * @param args Variable argument + * @param[in] value Source value object + * @param[in] position Index of the member + * @param[out] args Variable argument * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * * The value is returned in the variable argument parameter, the @@ -1532,9 +1534,9 @@ static inline Eina_Bool eina_value_array_vget(const Eina_Value *value, /** * @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 + * @param[in,out] value Source value object + * @param[in] position Index of the member + * @param[in] args Variable argument * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * * @see eina_value_array_set() @@ -1556,8 +1558,8 @@ static inline Eina_Bool eina_value_array_vinsert(Eina_Value *value, /** * @brief Appends a generic value to an array. * - * @param value Source value object - * @param args Variable argument + * @param[in,out] value Source value object + * @param[in] args Variable argument * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * * @see eina_value_array_set() @@ -1579,9 +1581,9 @@ static inline Eina_Bool eina_value_array_vappend(Eina_Value *value, /** * @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. + * @param[in,out] value Source value object + * @param[in] position Index of the member + * @param[in] 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 @@ -1643,9 +1645,9 @@ static inline Eina_Bool eina_value_array_pset(Eina_Value *value, /** * @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. + * @param[in] value Source value object + * @param[in] position Index of the member + * @param[out] 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 @@ -1702,9 +1704,9 @@ static inline Eina_Bool eina_value_array_pget(const Eina_Value *value, /** * @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. + * @param[in,out] value Source value object + * @param[in] position Index of the member + * @param[in] 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 @@ -1764,8 +1766,9 @@ static inline Eina_Bool eina_value_array_pinsert(Eina_Value *value, /** * @brief Appends a generic value to an array from a pointer. - * @param value Source value object - * @param ptr Pointer to specify the contents. + * + * @param[in,out] value Source value object + * @param[in] 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 @@ -1825,9 +1828,9 @@ static inline Eina_Bool eina_value_array_pappend(Eina_Value *value, /** * @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[in] src Source value object + * @param[in] position Index of the member + * @param[out] 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 set to @@ -1844,10 +1847,10 @@ static inline Eina_Bool eina_value_array_value_get(const Eina_Value *src, * @brief Definition for the macro to iterate over an array contained in an Eina_Value. * @since 1.21 * - * @param array The list to iterate over. - * @param length Contain the length of the array - * @param it Contain the current position walked over - * @param value Contain the value at the current position. + * @param[in] array The list to iterate over. + * @param[in] length Contain the length of the array + * @param[out] it Contain the current position walked over + * @param[out] value Contain the value at the current position. * * This macro iterates over @p array from the first element to * the last. @p value is the data related to the current element. @@ -1916,7 +1919,7 @@ struct _Eina_Value_List /** * @brief Creates generic value storage of type list. * - * @param subtype How to manage this list members. + * @param[in] 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 @@ -1937,8 +1940,8 @@ EAPI Eina_Value *eina_value_list_new(const Eina_Value_Type *subtype) EINA_ARG_NO /** * @brief Initializes generic value storage of type list. * - * @param value Value object - * @param subtype How to manage this list members. + * @param[out] value Value object + * @param[in] 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 @@ -1963,7 +1966,7 @@ static inline Eina_Bool eina_value_list_setup(Eina_Value *value, /** * @brief Queries number of elements in value of list type. * - * @param value value object. + * @param[in]value value object. * @return number of child elements. * * @since 1.2 @@ -1973,8 +1976,8 @@ static inline unsigned int eina_value_list_count(const Eina_Value *value); /** * @brief Removes element at given position in value of list type. * - * @param value value object. - * @param position index of the member + * @param[in,out] value value object. + * @param[in] position index of the member * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * * @since 1.2 @@ -1985,8 +1988,8 @@ static inline Eina_Bool eina_value_list_remove(Eina_Value *value, /** * @brief Sets the generic value in a list member. * - * @param value Source value object - * @param position Index of the member + * @param[in,out] value Source value object + * @param[in] position Index of the member * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * * The variable argument is dependent on chosen subtype. The list for @@ -2044,8 +2047,8 @@ static inline Eina_Bool eina_value_list_set(Eina_Value *value, /** * @brief Gets the generic value from a list member. * - * @param value Source value object - * @param position Index of the member + * @param[in] value Source value object + * @param[in] position Index of the member * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * * The value is returned in the variable argument parameter, the @@ -2101,8 +2104,8 @@ static inline Eina_Bool eina_value_list_get(const Eina_Value *value, /** * @brief Inserts the generic value in a list member position. * - * @param value Source value object - * @param position Index of the member + * @param[in,out] value Source value object + * @param[in] position Index of the member * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * * The variable argument is dependent on chosen subtype. The list for @@ -2160,7 +2163,8 @@ static inline Eina_Bool eina_value_list_insert(Eina_Value *value, /** * @brief Appends the generic value in a list. * - * @param value Source value object + * @param[in,out] value Source value object + * @param[in] ... Variable arguments * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * * The variable argument is dependent on chosen subtype. The list for @@ -2216,9 +2220,9 @@ static inline Eina_Bool eina_value_list_append(Eina_Value *value, /** * @brief Sets the generic value in a list member. * - * @param value Source value object - * @param position Index of the member - * @param args Variable argument + * @param[in,out] value Source value object + * @param[in] position Index of the member + * @param[in] args Variable argument * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * * @see eina_value_list_set() @@ -2240,9 +2244,9 @@ static inline Eina_Bool eina_value_list_vset(Eina_Value *value, /** * @brief Gets the generic value from a list member. * - * @param value Source value object - * @param position Index of the member - * @param args Variable argument + * @param[in] value Source value object + * @param[in] position Index of the member + * @param[in] args Variable argument * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * * The value is returned in the variable argument parameter, the @@ -2262,9 +2266,9 @@ static inline Eina_Bool eina_value_list_vget(const Eina_Value *value, /** * @brief Inserts the generic value in a list member position. * - * @param value Source value object - * @param position Index of the member - * @param args Variable argument + * @param[in,out] value Source value object + * @param[in] position Index of the member + * @param[in] args Variable argument * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * * @see eina_value_list_set() @@ -2286,8 +2290,8 @@ static inline Eina_Bool eina_value_list_vinsert(Eina_Value *value, /** * @brief Appends the generic value in a list. * - * @param value Source value object - * @param args Variable argument + * @param[in,out] value Source value object + * @param[in] args Variable argument * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * * @see eina_value_list_set() @@ -2309,9 +2313,9 @@ static inline Eina_Bool eina_value_list_vappend(Eina_Value *value, /** * @brief Sets the generic value in a list member from pointer. * - * @param value Source value object - * @param position Index of the member - * @param ptr Pointer to specify the contents. + * @param[in,out] value Source value object + * @param[in] position Index of the member + * @param[in] 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 @@ -2372,9 +2376,9 @@ static inline Eina_Bool eina_value_list_pset(Eina_Value *value, /** * @brief Gets the generic value to pointer from a list member. * - * @param value Source value object - * @param position Index of the member - * @param ptr Pointer to receive the contents. + * @param[in] value Source value object + * @param[in] position Index of the member + * @param[out] 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 @@ -2430,9 +2434,9 @@ static inline Eina_Bool eina_value_list_pget(const Eina_Value *value, /** * @brief Inserts the generic value in a list member position from pointer. * - * @param value Source value object - * @param position Index of the member - * @param ptr Pointer to specify the contents. + * @param[in,out] value Source value object + * @param[in] position Index of the member + * @param[in] 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 @@ -2492,8 +2496,8 @@ static inline Eina_Bool eina_value_list_pinsert(Eina_Value *value, /** * @brief Appends the generic value in a list from pointer. * - * @param value Source value object - * @param ptr Pointer to specify the contents. + * @param[in,out] value Source value object + * @param[in] 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 @@ -2583,8 +2587,8 @@ struct _Eina_Value_Hash /** * @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 ^ + * @param[in] subtype How to manage this hash members. + * @param[in] 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. * @@ -2606,9 +2610,9 @@ EAPI Eina_Value *eina_value_hash_new(const Eina_Value_Type *subtype, unsigned in /** * @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 ^ + * @param[in] value Value object + * @param[in] subtype How to manage this hash members. + * @param[in] 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. * @@ -2635,7 +2639,7 @@ static inline Eina_Bool eina_value_hash_setup(Eina_Value *value, /** * @brief Queries number of elements in value of hash type. * - * @param value value object. + * @param[in] value value object. * @return number of child elements. * * @since 1.2 @@ -2645,8 +2649,8 @@ static inline unsigned int eina_value_hash_population(const Eina_Value *value); /** * @brief Removes element at given position in value of hash type. * - * @param value value object. - * @param key key to find the member + * @param[in,out] value value object. + * @param[in] key key to find the member * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * * @since 1.2 @@ -2657,8 +2661,9 @@ static inline Eina_Bool eina_value_hash_del(Eina_Value *value, /** * @brief Sets the generic value in an hash member. * - * @param value Source value object - * @param key Key to find the member + * @param[in,out] value Source value object + * @param[in] key Key to find the member + * @param[in] ... Variable arguments of data to set * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * * The variable argument is dependent on chosen subtype. The list for @@ -2709,8 +2714,9 @@ static inline Eina_Bool eina_value_hash_set(Eina_Value *value, /** * @brief Gets the generic value from an hash member. * - * @param value Source value object - * @param key Key to find the member + * @param[in] value Source value object + * @param[in] key Key to find the member + * @param[out] ... * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * * The value is returned in the variable argument parameter, the @@ -2765,9 +2771,9 @@ static inline Eina_Bool eina_value_hash_get(const Eina_Value *value, /** * @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 + * @param[in,out] value Source value object + * @param[in] key Key to find the member + * @param[in] args Variable argument * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * * @see eina_value_hash_set() @@ -2783,9 +2789,9 @@ static inline Eina_Bool eina_value_hash_vset(Eina_Value *value, /** * @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 + * @param[in] value Source value object + * @param[in] key Key to find the member + * @param[out] args Variable argument * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * * The value is returned in the variable argument parameter, the @@ -2806,9 +2812,9 @@ static inline Eina_Bool eina_value_hash_vget(const Eina_Value *value, /** * @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. + * @param[in,out] value Source value object + * @param[in] key Key to find the member + * @param[in] 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 @@ -2861,9 +2867,9 @@ static inline Eina_Bool eina_value_hash_pset(Eina_Value *value, /** * @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. + * @param[in] value Source value object + * @param[in] key Key to find the member + * @param[out] 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 @@ -3201,7 +3207,7 @@ struct _Eina_Value_Struct /** * @brief Creates generic value storage of type struct. * - * @param desc How to manage this struct members. + * @param[in] 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 @@ -3222,8 +3228,8 @@ EAPI Eina_Value *eina_value_struct_new(const Eina_Value_Struct_Desc *desc) EINA_ /** * @brief Initializes generic value storage of type struct. * - * @param value Value object - * @param desc How to manage this struct members. + * @param[out] value Value object + * @param[in] 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 @@ -3248,7 +3254,7 @@ static inline Eina_Bool eina_value_struct_setup(Eina_Value *value, /** * @brief Checks for a struct and get its description. * - * @param value Value object + * @param[in] value Value object * @return structure description, with all members and size. * on failure, #NULL is returned. * @@ -3259,8 +3265,9 @@ static inline const Eina_Value_Struct_Desc *eina_value_struct_desc_get(const Ein /** * @brief Sets the generic value in a struct member. * - * @param value Source value object - * @param name Name to find the member + * @param[in,out] value Source value object + * @param[in] name Name to find the member + * @param[in] ... Variable arguments * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * * The variable argument is dependent on chosen member type. The list @@ -3326,8 +3333,9 @@ static inline Eina_Bool eina_value_struct_set(Eina_Value *value, /** * @brief Gets the generic value from a struct member. * - * @param value Source value object - * @param name Name to find the member + * @param[in] value Source value object + * @param[in] name Name to find the member + * @param[out] ... Variable arguments * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * * The value is returned in the variable argument parameter, the @@ -3398,9 +3406,9 @@ static inline Eina_Bool eina_value_struct_get(const Eina_Value *value, /** * @brief Sets the generic value in a struct member. * - * @param value Source value object - * @param name Name to find the member - * @param args Variable argument + * @param[in,out] value Source value object + * @param[in] name Name to find the member + * @param[in] args Variable argument * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * * @see eina_value_struct_set() @@ -3416,9 +3424,9 @@ static inline Eina_Bool eina_value_struct_vset(Eina_Value *value, /** * @brief Gets the generic value from a struct member. * - * @param value Source value object - * @param name Name to find the member - * @param args Variable argument + * @param[in] value Source value object + * @param[in] name Name to find the member + * @param[in,out] args Variable argument * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * * The value is returned in the variable argument parameter, the @@ -3439,9 +3447,9 @@ static inline Eina_Bool eina_value_struct_vget(const Eina_Value *value, /** * @brief Sets the generic value in a struct member from pointer. * - * @param value Source value object - * @param name Name to find the member - * @param ptr Pointer to specify the contents. + * @param[in,out] value Source value object + * @param[in] name Name to find the member + * @param[in] 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 @@ -3510,9 +3518,9 @@ static inline Eina_Bool eina_value_struct_pset(Eina_Value *value, /** * @brief Gets the generic value to pointer from a struct member. * - * @param value Source value object - * @param name Name to find the member - * @param ptr Pointer to receive the contents. + * @param[in] value Source value object + * @param[in] name Name to find the member + * @param[out] 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 @@ -3583,9 +3591,9 @@ static inline Eina_Bool eina_value_struct_pget(const Eina_Value *value, /** * @brief Gets 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. + * @param[in] src Source value object + * @param[in] name Name to find the member + * @param[out] 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 @@ -3600,9 +3608,9 @@ static inline Eina_Bool eina_value_struct_value_get(const Eina_Value *src, /** * @brief Sets the member from Eina_Value source. * - * @param dst destination value object - * @param name name to find the member - * @param src source value + * @param[in,out] dst destination value object + * @param[in] name name to find the member + * @param[in] src source value * @return #EINA_TRUE on success, #EINA_FALSE on failure. * * @since 1.2 @@ -3614,9 +3622,9 @@ static inline Eina_Bool eina_value_struct_value_set(Eina_Value *dst, /** * @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. + * @param[in] src Source value object + * @param[in] member The member description to use + * @param[out] 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 @@ -3631,9 +3639,9 @@ static inline Eina_Bool eina_value_struct_member_value_get(const Eina_Value *src /** * @brief Sets the member from Eina_Value source. * - * @param dst destination value object - * @param member the member description to use - * @param src source value + * @param[out] dst destination value object + * @param[in] member the member description to use + * @param[in] src source value * @return #EINA_TRUE on success, #EINA_FALSE on failure. * * @since 1.2 @@ -3685,7 +3693,7 @@ struct _Eina_Value_Type /** * @brief Queries type name. * - * @param type type reference. + * @param[in] type type reference. * @return string or @c NULL if type is invalid. * * @since 1.2 @@ -3695,7 +3703,7 @@ EAPI const char *eina_value_type_name_get(const Eina_Value_Type *type) EINA_PURE /** * @brief Checks if type is valid. * - * @param type Type reference. + * @param[in] 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 @@ -3708,8 +3716,8 @@ EAPI Eina_Bool eina_value_type_check(const Eina_Value_Type *type) EINA_PURE EINA /** * @brief Initializes memory using type descriptor. * - * @param type type reference. - * @param mem memory to operate, must be of size @c type->value_size. + * @param[in] type type reference. + * @param[out] mem memory to operate, must be of size @c type->value_size. * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * * @since 1.2 @@ -3719,8 +3727,8 @@ static inline Eina_Bool eina_value_type_setup(const Eina_Value_Type *type, void /** * @brief Flushes (clears) memory using type descriptor. * - * @param type type reference. - * @param mem memory to operate, must be of size @c type->value_size. + * @param[in] type type reference. + * @param[out] mem memory to operate, must be of size @c type->value_size. * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * * @since 1.2 @@ -3730,9 +3738,9 @@ static inline Eina_Bool eina_value_type_flush(const Eina_Value_Type *type, void /** * @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. + * @param[in] type type reference. + * @param[in] src memory to operate, must be of size @c type->value_size. + * @param[out] dst memory to operate, must be of size @c type->value_size. * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * * @since 1.2 @@ -3742,9 +3750,9 @@ static inline Eina_Bool eina_value_type_copy(const Eina_Value_Type *type, const /** * @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. + * @param[in] type type reference. + * @param[in] a memory to operate, must be of size @c type->value_size. + * @param[in] b memory to operate, must be of size @c type->value_size. * @return less than zero if a < b, greater than zero if a > b, zero if equal. * * @since 1.2 @@ -3754,10 +3762,10 @@ static inline int eina_value_type_compare(const Eina_Value_Type *type, const voi /** * @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. - * @param convert_mem memory to operate, must be of size @c convert->value_size. + * @param[in] type type reference of the source. + * @param[in] convert type reference of the destination. + * @param[in] type_mem memory to operate, must be of size @c type->value_size. + * @param[out] convert_mem memory to operate, must be of size @c convert->value_size. * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * * @since 1.2 @@ -3767,10 +3775,10 @@ static inline Eina_Bool eina_value_type_convert_to(const Eina_Value_Type *type, /** * @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. - * @param convert_mem memory to operate, must be of size @c convert->value_size. + * @param[in] type type reference of the destination. + * @param[in] convert type reference of the source. + * @param[out] type_mem memory to operate, must be of size @c type->value_size. + * @param[in] convert_mem memory to operate, must be of size @c convert->value_size. * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * * @since 1.2 @@ -3780,9 +3788,9 @@ static inline Eina_Bool eina_value_type_convert_from(const Eina_Value_Type *type /** * @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. + * @param[in] type type reference of the source. + * @param[out] mem memory to operate, must be of size @c type->value_size. + * @param[in] args input value. * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * * @since 1.2 @@ -3792,9 +3800,9 @@ static inline Eina_Bool eina_value_type_vset(const Eina_Value_Type *type, void * /** * @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. + * @param[in] type type reference of the source. + * @param[out] mem memory to operate, must be of size @c type->value_size. + * @param[in] ptr pointer to input value. * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * * @since 1.2 @@ -3804,9 +3812,9 @@ static inline Eina_Bool eina_value_type_pset(const Eina_Value_Type *type, void * /** * @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. + * @param[in] type type reference of the source. + * @param[in] mem memory to operate, must be of size @c type->value_size. + * @param[out] ptr pointer to output. * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * * @since 1.2 @@ -3850,8 +3858,8 @@ static inline Eina_Value *eina_value_optional_empty_new(void); /** * @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 + * @param[in] subtype Eina_Value_Type of parameter value + * @param[in] value The value to be used to construct optional eina value * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * * @since 1.17 @@ -3862,8 +3870,8 @@ EAPI Eina_Value *eina_value_optional_new(const Eina_Value_Type *subtype, /** * @brief Function to know if an eina optional is empty or not * - * @param value Eina Value Optional - * @param is_empty #EINA_TRUE if optional is empty, #EINA_FALSE otherwise. + * @param[in] value Eina Value Optional + * @param[out] is_empty #EINA_TRUE if optional is empty, #EINA_FALSE otherwise. * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * * @since 1.17 @@ -3874,9 +3882,9 @@ static inline Eina_Bool eina_value_optional_empty_is(const Eina_Value *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 + * @param[in,out] value Eina Value Optional to be set with subvalue + * @param[in] subtype Type of subvalue + * @param[in] subvalue Value to be set in optional * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * * @since 1.17 @@ -3888,8 +3896,8 @@ EAPI Eina_Bool eina_value_optional_pset(Eina_Value *value, /** * @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 + * @param[in] value Eina Value Optional to get value from + * @param[out] subvalue Pointer to where value is to be copied to. You must use * the correct type according to eina_value_optional_type_get * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * @@ -3901,7 +3909,7 @@ EAPI Eina_Bool eina_value_optional_pget(Eina_Value *value, /** * @brief Resets eina optional to empty * - * @param value Eina Value Optional + * @param[in,out] value Eina Value Optional * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * * @since 1.17 @@ -3911,7 +3919,8 @@ EAPI Eina_Bool eina_value_optional_reset(Eina_Value *value) EINA_ARG_NONNULL(1); /** * * @brief Gets type from value that is stored on Eina Value Optional - * @param value Eina Value Optional + * + * @param[in] value Eina Value Optional * @return The optional sub-type. * * @since 1.17 diff --git a/src/lib/eina/eina_vector.h b/src/lib/eina/eina_vector.h index 039114b8f1..df4508b675 100644 --- a/src/lib/eina/eina_vector.h +++ b/src/lib/eina/eina_vector.h @@ -64,9 +64,9 @@ struct _Eina_Vector3 /** * @brief Set parameters to vector. * - * @param dst The resulting vector. - * @param x The x component. - * @param y The y component. + * @param[out] dst The resulting vector. + * @param[in] x The x component. + * @param[in] y The y component. * * @since 1.17 */ @@ -75,8 +75,8 @@ static inline void eina_vector2_set(Eina_Vector2 *dst, double x, double y); /** * @brief Set array to vector. * - * @param dst The resulting vector. - * @param v The the array[2] for set. + * @param[out] dst The resulting vector. + * @param[in] v The the array[2] for set. * * Set to vector first 2 elements from array. * @@ -87,8 +87,8 @@ static inline void eina_vector2_array_set(Eina_Vector2 *dst, const double *v); /** * @brief Copy vector. * - * @param dst The vector copy. - * @param src The vector for copy. + * @param[out] dst The vector copy. + * @param[in] src The vector for copy. * * @since 1.17 */ @@ -97,8 +97,8 @@ static inline void eina_vector2_copy(Eina_Vector2 *dst, const Eina_Vector2 *src) /** * @brief Make negative vector. * - * @param out The resulting vector. - * @param v The current vector. + * @param[out] out The resulting vector. + * @param[in] v The current vector. * * @since 1.17 */ @@ -107,9 +107,9 @@ static inline void eina_vector2_negate(Eina_Vector2 *out, const Eina_Vector2 *v) /** * @brief Add two vectors. * - * @param out The resulting vector. - * @param a The first member of the add. - * @param b The second member of the add. + * @param[out] out The resulting vector. + * @param[in] a The first member of the add. + * @param[in] b The second member of the add. * * @since 1.17 */ @@ -118,9 +118,9 @@ static inline void eina_vector2_add(Eina_Vector2 *out, const Eina_Vector2 *a, co /** * @brief Subtract two vectors * - * @param out The resulting vector - * @param a The first member of the subtract - * @param b The second member of the subtract + * @param[out] out The resulting vector + * @param[in] a The first member of the subtract + * @param[in] b The second member of the subtract * * @since 1.17 */ @@ -129,9 +129,9 @@ static inline void eina_vector2_subtract(Eina_Vector2 *out, const Eina_Vector2 * /** * @brief Scale vector. * - * @param out The resulting vector. - * @param v The vector for scale. - * @param scale The scale value. + * @param[out] out The resulting vector. + * @param[in] v The vector for scale. + * @param[in] scale The scale value. * * @since 1.17 */ @@ -140,8 +140,8 @@ static inline void eina_vector2_scale(Eina_Vector2 *out, const Eina_Vector2 *v, /** * @brief Return the dot product of the two vectors. * - * @param a The first member. - * @param b The second member. + * @param[in] a The first member. + * @param[in] b The second member. * @return The dot product. * * @since 1.17 @@ -151,7 +151,7 @@ static inline double eina_vector2_dot_product(const Eina_Vector2 *a, const Eina_ /** * @brief Return the length of the given vector. * - * @param v The vector. + * @param[in] v The vector. * @return The length. * * @since 1.17 @@ -161,7 +161,7 @@ static inline double eina_vector2_length_get(const Eina_Vector2 *v); /** * @brief Return the length in square of the given vector. * - * @param v The vector. + * @param[in] v The vector. * @return The length in square. * * @since 1.17 @@ -171,8 +171,8 @@ static inline double eina_vector2_length_square_get(const Eina_Vector2 *v); /** * @brief Return the distance between of two vectors. * - * @param a The first vector. - * @param b The second vector. + * @param[in] a The first vector. + * @param[in] b The second vector. * @return The distance. * * @since 1.17 @@ -182,8 +182,8 @@ static inline double eina_vector2_distance_get(const Eina_Vector2 *a, const Eina /** * @brief Return the distance in square between of two vectors. * - * @param a The first vector. - * @param b The second vector. + * @param[in] a The first vector. + * @param[in] b The second vector. * @return The distance in square. * * @since 1.17 @@ -193,8 +193,8 @@ static inline double eina_vector2_distance_square_get(const Eina_Vector2 *a, con /** * @brief normalize vector. * - * @param out The resulting vector. - * @param v The vector for normalize. + * @param[out] out The resulting vector. + * @param[in] v The vector for normalize. * * @since 1.17 */ @@ -203,9 +203,9 @@ static inline void eina_vector2_normalize(Eina_Vector2 *out, const Eina_Vector2 /** * @brief Transform vector. * - * @param out The resulting vector. - * @param m The matrix for transform. - * @param v The vector for transform. + * @param[out] out The resulting vector. + * @param[in] m The matrix for transform. + * @param[in] v The vector for transform. * * @since 1.17 */ @@ -214,9 +214,9 @@ static inline void eina_vector2_transform(Eina_Vector2 *out, const Eina_Matrix2 /** * @brief Homogeneous position transform vector. * - * @param out The resulting vector. - * @param m The matrix for transform. - * @param v The vector for transform. + * @param[out] out The resulting vector. + * @param[in] m The matrix for transform. + * @param[in] v The vector for transform. * * @since 1.17 */ @@ -225,9 +225,9 @@ static inline void eina_vector2_homogeneous_position_transform(Eina_Vector2 *out /** * @brief Homogeneous direction transform vector. * - * @param out The resulting vector. - * @param m The matrix for transform. - * @param v The vector for transform. + * @param[out] out The resulting vector. + * @param[in] m The matrix for transform. + * @param[in] v The vector for transform. * * @since 1.17 */ @@ -236,10 +236,10 @@ static inline void eina_vector2_homogeneous_direction_transform(Eina_Vector2 *ou /** * @brief Set parameters to vector. * - * @param dst The resulting vector. - * @param x The x component. - * @param y The y component. - * @param z The z component. + * @param[out] dst The resulting vector. + * @param[in] x The x component. + * @param[in] y The y component. + * @param[in] z The z component. * * @since 1.18 */ @@ -248,8 +248,8 @@ static inline void eina_vector3_set(Eina_Vector3 *dst, double x, double y, doubl /** * @brief Set array to vector. * - * @param dst The resulting vector. - * @param v The the array[3] for set. + * @param[out] dst The resulting vector. + * @param[in] v The the array[3] for set. * * Set to vector first 3 elements from array. * @@ -260,8 +260,8 @@ static inline void eina_vector3_array_set(Eina_Vector3 *dst, const double *v); /** * @brief Copy vector. * - * @param dst The vector copy. - * @param src The vector for copy. + * @param[out] dst The vector copy. + * @param[in] src The vector for copy. * * @since 1.18 */ @@ -270,8 +270,8 @@ static inline void eina_vector3_copy(Eina_Vector3 *dst, const Eina_Vector3 *src) /** * @brief Make negative vector. * - * @param out The resulting vector. - * @param v The current vector. + * @param[out] out The resulting vector. + * @param[in] v The current vector. * * @since 1.18 */ @@ -280,9 +280,9 @@ static inline void eina_vector3_negate(Eina_Vector3 *out, const Eina_Vector3 *v) /** * @brief Add two vectors. * - * @param out The resulting vector. - * @param a The first member of the add. - * @param b The second member of the add. + * @param[out] out The resulting vector. + * @param[in] a The first member of the add. + * @param[in] b The second member of the add. * * @since 1.18 */ @@ -292,9 +292,9 @@ static inline void eina_vector3_add(Eina_Vector3 *out, const Eina_Vector3 *a, /** * @brief Subtract two vectors * - * @param out The resulting vector - * @param a The first member of the subtract - * @param b The second member of the subtract + * @param[out] out The resulting vector + * @param[in] a The first member of the subtract + * @param[in] b The second member of the subtract * * @since 1.18 */ @@ -304,9 +304,9 @@ static inline void eina_vector3_subtract(Eina_Vector3 *out, const Eina_Vector3 * /** * @brief Scale vector. * - * @param out The resulting vector. - * @param v The vector for scale. - * @param scale The scale value. + * @param[out] out The resulting vector. + * @param[in] v The vector for scale. + * @param[in] scale The scale value. * * @since 1.18 */ @@ -315,9 +315,9 @@ static inline void eina_vector3_scale(Eina_Vector3 *out, const Eina_Vector3 *v, /** * @brief Multiply two vectors * - * @param out The resulting vector - * @param a The first member - * @param b The second member + * @param[out] out The resulting vector + * @param[in] a The first member + * @param[in] b The second member * * @since 1.18 */ @@ -327,8 +327,8 @@ static inline void eina_vector3_multiply(Eina_Vector3 *out, const Eina_Vector3 * /** * @brief Return the dot product of the two vectors. * - * @param a The first member. - * @param b The second member. + * @param[in] a The first member. + * @param[in] b The second member. * @return The dot product. * * @since 1.18 @@ -338,9 +338,9 @@ static inline double eina_vector3_dot_product(const Eina_Vector3 *a, const Eina_ /** * @brief Create the cross product of the two vectors. * - * @param out The resulting vector. - * @param a The first member. - * @param b The second member. + * @param[out] out The resulting vector. + * @param[in] a The first member. + * @param[in] b The second member. * * @since 1.18 */ @@ -350,7 +350,7 @@ static inline void eina_vector3_cross_product(Eina_Vector3 *out, const Eina_Vect /** * @brief Return the length of the given vector. * - * @param v The vector. + * @param[in] v The vector. * @return The length. * * @since 1.18 @@ -360,7 +360,7 @@ static inline double eina_vector3_length_get(const Eina_Vector3 *v); /** * @brief Return the length in square of the given vector. * - * @param v The vector. + * @param[in] v The vector. * @return The length in square. * * @since 1.18 @@ -370,8 +370,8 @@ static inline double eina_vector3_length_square_get(const Eina_Vector3 *v); /** * @brief Return the distance between of two vectors. * - * @param a The first vector. - * @param b The second vector. + * @param[in] a The first vector. + * @param[in] b The second vector. * @return The distance. * * @since 1.18 @@ -381,8 +381,8 @@ static inline double eina_vector3_distance_get(const Eina_Vector3 *a, const Eina /** * @brief Return the distance in square between of two vectors. * - * @param a The first vector. - * @param b The second vector. + * @param[in] a The first vector. + * @param[in] b The second vector. * @return The distance in square. * * @since 1.18 @@ -393,8 +393,8 @@ static inline double eina_vector3_distance_square_get(const Eina_Vector3 *a, /** * @brief Return the angle between of two vectors. * - * @param a The first vector. - * @param b The second vector. + * @param[in] a The first vector. + * @param[in] b The second vector. * @return The angle. * * @since 1.18 @@ -404,8 +404,8 @@ static inline double eina_vector3_angle_get(const Eina_Vector3 *a, const Eina_Ve /** * @brief normalize vector. * - * @param out The resulting vector. - * @param v The not NULL vector for normalize. + * @param[out] out The resulting vector. + * @param[in] v The not NULL vector for normalize. * * @since 1.18 */ @@ -414,9 +414,9 @@ static inline void eina_vector3_normalize(Eina_Vector3 *out, const Eina_Vector3 /** * @brief Transform vector. * - * @param out The resulting vector. - * @param m The matrix for transform. - * @param v The vector for transform. + * @param[out] out The resulting vector. + * @param[in] m The matrix for transform. + * @param[in] v The vector for transform. * * @since 1.18 */ @@ -426,9 +426,9 @@ static inline void eina_vector3_transform(Eina_Vector3 *out, const Eina_Matrix3 /** * @brief Homogeneous direction transform vector. * - * @param out The resulting vector. - * @param m The matrix for transform. - * @param v The vector for transform. + * @param[out] out The resulting vector. + * @param[in] m The matrix for transform. + * @param[in] v The vector for transform. * * @since 1.18 */ @@ -438,9 +438,9 @@ static inline void eina_vector3_homogeneous_direction_transform(Eina_Vector3 *ou /** * @brief Homogeneous position transform vector. * - * @param out The resulting vector. - * @param m The matrix for transform. - * @param v The vector for transform. + * @param[out] out The resulting vector. + * @param[in] m The matrix for transform. + * @param[in] v The vector for transform. * * @since 1.18 */ @@ -451,9 +451,9 @@ static inline void eina_vector3_homogeneous_position_transform(Eina_Vector3 *out /** * @brief Rotate vector. * - * @param out The resulting vector. - * @param v The vector for rotate. - * @param q The quaternion in radians for rotate. + * @param[out] out The resulting vector. + * @param[in] v The vector for rotate. + * @param[in] q The quaternion in radians for rotate. * * @since 1.18 */ @@ -463,9 +463,9 @@ static inline void eina_vector3_quaternion_rotate(Eina_Vector3 *out, const Eina_ /** * @brief Create orthogonal projection on plane between vector and normal. * - * @param out The resulting vector. - * @param v The vector for projection. - * @param normal The normal for projection. + * @param[out] out The resulting vector. + * @param[in] v The vector for projection. + * @param[in] normal The normal for projection. * * @since 1.18 */ @@ -475,10 +475,10 @@ static inline void eina_vector3_orthogonal_projection_on_plane(Eina_Vector3 *out /** * @brief Plane by points between three vectors. * - * @param out The resulting quaternion of plane. - * @param a The first member. - * @param b The second member. - * @param c The third member. + * @param[out] out The resulting quaternion of plane. + * @param[in] a The first member. + * @param[in] b The second member. + * @param[in] c The third member. * * @since 1.18 */ @@ -488,8 +488,8 @@ static inline void eina_vector3_plane_by_points(Eina_Quaternion *out, const Eina /** * @brief Homogeneous position set. * - * @param out The resulting vector. - * @param v The quaternion for position. + * @param[out] out The resulting vector. + * @param[in] v The quaternion for position. * * @since 1.18 */ @@ -498,8 +498,8 @@ static inline void eina_vector3_homogeneous_position_set(Eina_Vector3 *out, cons /** * @brief Homogeneous direction set. * - * @param out The resulting vector. - * @param v The quaternion for direction. + * @param[out] out The resulting vector. + * @param[in] v The quaternion for direction. * * @since 1.18 */ @@ -508,8 +508,8 @@ static inline void eina_vector3_homogeneous_direction_set(Eina_Vector3 *out, con /** * @brief Check the equivalent between of two vectors. * - * @param a The first vector. - * @param b The second vector. + * @param[in] a The first vector. + * @param[in] b The second vector. * @return The EINA_TRUE if equivalent. * * @since 1.18 @@ -519,12 +519,12 @@ static inline Eina_Bool eina_vector3_equivalent(Eina_Vector3 *a, const Eina_Vect /** * @brief Check the equivalent between of two triangles of vectors. * - * @param v0 The first member of first triangle. - * @param v1 The second member of first triangle. - * @param v2 The third member of first triangle. - * @param w0 The first member of second triangle. - * @param w1 The second member of second triangle. - * @param w2 The third member of second triangle. + * @param[in] v0 The first member of first triangle. + * @param[in] v1 The second member of first triangle. + * @param[in] v2 The third member of first triangle. + * @param[in] w0 The first member of second triangle. + * @param[in] w1 The second member of second triangle. + * @param[in] w2 The third member of second triangle. * @return The EINA_TRUE if equivalent. * * @since 1.18 diff --git a/src/lib/eina/eina_vpath.h b/src/lib/eina/eina_vpath.h index 44b172c38c..788ff3602a 100644 --- a/src/lib/eina/eina_vpath.h +++ b/src/lib/eina/eina_vpath.h @@ -84,9 +84,10 @@ */ typedef const char * Eina_Vpath; -/* +/** * Translate a virtual path into a normal path. * + * @param[in] path The path. * @return NULL if failed, or a full normal string file path that is resolved * * @since 1.21 @@ -94,13 +95,13 @@ typedef const char * Eina_Vpath; */ EAPI char *eina_vpath_resolve(Eina_Vpath path); -/* +/** * Translate a virtual path into a normal path, and print it into str. * - * @param str the buffer to stuff the characters into - * @param size the size of the buffer - * @param format A snprintf style format string, which will get evaluated after the vpath strings are getting replaced - * @param ... The arguments for the format string + * @param[out] str the buffer to stuff the characters into + * @param[in] size the size of the buffer + * @param[in] format A snprintf style format string, which will get evaluated after the vpath strings are getting replaced + * @param[in] ... The arguments for the format string * * @return the number of characters that are written into str, on a error a value < 0 is returned. * diff --git a/src/lib/eina/eina_xattr.h b/src/lib/eina/eina_xattr.h index a31fcfae8e..711c40e86f 100644 --- a/src/lib/eina/eina_xattr.h +++ b/src/lib/eina/eina_xattr.h @@ -53,7 +53,7 @@ struct _Eina_Xattr /** * @brief Gets an iterator that lists all extended attribute of a file. * - * @param file The filename to retrieve the extended attribute list from. + * @param[in] file The filename to retrieve the extended attribute list from. * @return an iterator. * * The iterator will not allocate any data during the iteration step, so you need to copy them yourself @@ -66,7 +66,7 @@ EAPI Eina_Iterator *eina_xattr_ls(const char *file) EINA_ARG_NONNULL(1) EINA_WAR /** * @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. + * @param[in] file The filename to retrieve the extended attribute list from. * @return An iterator. * * The iterator will not allocate any data during the iteration step, so you need to copy them yourself @@ -79,7 +79,7 @@ EAPI Eina_Iterator *eina_xattr_value_ls(const char *file) EINA_ARG_NONNULL(1) EI /** * @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. + * @param[in] fd The file descriptor to retrieve the extended attribute list from. * @return an iterator. * * The iterator will not allocate any data during the iteration step, so you need to copy them yourself @@ -92,7 +92,7 @@ EAPI Eina_Iterator *eina_xattr_fd_ls(int fd) EINA_WARN_UNUSED_RESULT; /** * @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. + * @param[in] fd The file descriptor to retrieve the extended attribute list from. * @return An iterator. * * The iterator will not allocate any data during the iteration step, so you need to copy them yourself @@ -105,8 +105,8 @@ EAPI Eina_Iterator *eina_xattr_value_fd_ls(int fd) EINA_WARN_UNUSED_RESULT; /** * @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. + * @param[in] src source file to use as input. + * @param[in] dst destination file to use as output. * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * * @see eina_xattr_fd_copy() @@ -118,8 +118,8 @@ EAPI Eina_Bool eina_xattr_copy(const char *src, const char *dst) EINA_ARG_NONNUL /** * @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. + * @param[in] src source file descriptor to use as input. + * @param[in] dst destination file descriptor to use as output. * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * * @see eina_xattr_copy() @@ -131,9 +131,9 @@ EAPI Eina_Bool eina_xattr_fd_copy(int src, int dst); /** * @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. - * @param size The size of the retrieved extended attribute. + * @param[in] file The file to retrieve the extended attribute from. + * @param[in] attribute The extended attribute name to retrieve. + * @param[out] size The size of the retrieved extended attribute. * @return the allocated data that hold the extended attribute value. * * It will return @c NULL and *size will be @c 0 if it fails. @@ -145,9 +145,9 @@ EAPI void *eina_xattr_get(const char *file, const char *attribute, ssize_t *size /** * @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. - * @param size The size of the retrieved extended attribute. + * @param[in] fd The file descriptor to retrieve the extended attribute from. + * @param[in] attribute The extended attribute name to retrieve. + * @param[out] size The size of the retrieved extended attribute. * @return the allocated data that hold the extended attribute value. * * It will return @c NULL and *size will be @c 0 if it fails. @@ -159,11 +159,11 @@ EAPI void *eina_xattr_fd_get(int fd, const char *attribute, ssize_t *size) EINA_ /** * @brief Sets an extended attribute on a file. * - * @param file The file to set the extended attribute to. - * @param attribute The attribute to set. - * @param data The data to set. - * @param length The length of the data to set. - * @param flags Define the set policy. + * @param[in] file The file to set the extended attribute to. + * @param[in] attribute The attribute to set. + * @param[in] data The data to set. + * @param[in] length The length of the data to set. + * @param[in] flags Define the set policy. * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * * @since 1.1 @@ -173,11 +173,11 @@ EAPI Eina_Bool eina_xattr_set(const char *file, const char *attribute, const voi /** * @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. - * @param data The data to set. - * @param length The length of the data to set. - * @param flags Define the set policy. + * @param[in] fd The file descriptor to set the extended attribute to. + * @param[in] attribute The attribute to set. + * @param[in] data The data to set. + * @param[in] length The length of the data to set. + * @param[in] flags Define the set policy. * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * * @since 1.8 @@ -188,8 +188,8 @@ EAPI Eina_Bool eina_xattr_fd_set(int fd, const char *attribute, const void *data /** * @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. + * @param[in] file The file to del the extended attribute from. + * @param[in] attribute The attribute to del. * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * * @since 1.8 @@ -199,8 +199,8 @@ EAPI Eina_Bool eina_xattr_del(const char *file, const char *attribute) EINA_ARG_ /** * @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. + * @param[in] fd The file descriptor to del the extended attribute from. + * @param[in] attribute The attribute to del. * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * * @since 1.8 @@ -210,10 +210,10 @@ EAPI Eina_Bool eina_xattr_fd_del(int fd, const char *attribute) EINA_ARG_NONNULL /** * @brief Sets a string as a extended attribute properties. * - * @param file The file to set the string to. - * @param attribute The attribute to set. - * @param data The NULL-terminated string to set. - * @param flags Define the set policy. + * @param[in] file The file to set the string to. + * @param[in] attribute The attribute to set. + * @param[in] data The NULL-terminated string to set. + * @param[in] flags Define the set policy. * @return EINA_TRUE on success, EINA_FALSE otherwise. * * @since 1.1 @@ -223,8 +223,8 @@ EAPI Eina_Bool eina_xattr_string_set(const char *file, const char *attribute, co /** * @brief Gets a string from an extended attribute properties. * - * @param file The file to get the string from. - * @param attribute The attribute to get. + * @param[in] file The file to get the string from. + * @param[in] attribute The attribute to get. * @return A valid string on success, @c NULL otherwise. * * This call check that the string is properly NULL-terminated before returning it. @@ -236,10 +236,10 @@ EAPI char *eina_xattr_string_get(const char *file, const char *attribute); /** * @brief Sets a double as a extended attribute properties. * - * @param file The file to set the double to. - * @param attribute The attribute to set. - * @param value The NULL-terminated double to set. - * @param flags Define the set policy. + * @param[in] file The file to set the double to. + * @param[in] attribute The attribute to set. + * @param[in] value The NULL-terminated double to set. + * @param[in] flags Define the set policy. * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * * @since 1.1 @@ -249,9 +249,9 @@ EAPI Eina_Bool eina_xattr_double_set(const char *file, const char *attribute, do /** * @brief Gets a double from an extended attribute properties. * - * @param file The file to get the string from. - * @param attribute The attribute to get. - * @param value Where to put the extracted value + * @param[in] file The file to get the string from. + * @param[in] attribute The attribute to get. + * @param[out] value Where to put the extracted value * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * * This call check that the double is correctly set. @@ -263,10 +263,10 @@ EAPI Eina_Bool eina_xattr_double_get(const char *file, const char *attribute, do /** * @brief Sets an int as a extended attribute properties. * - * @param file The file to set the int to. - * @param attribute The attribute to set. - * @param value The NULL-terminated int to set. - * @param flags Define the set policy. + * @param[in] file The file to set the int to. + * @param[in] attribute The attribute to set. + * @param[in] value The NULL-terminated int to set. + * @param[in] flags Define the set policy. * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * * @since 1.1 @@ -276,9 +276,9 @@ EAPI Eina_Bool eina_xattr_int_set(const char *file, const char *attribute, int v /** * @brief Gets a int from an extended attribute properties. * - * @param file The file to get the string from. - * @param attribute The attribute to get. - * @param value Where to put the extracted value + * @param[in] file The file to get the string from. + * @param[in] attribute The attribute to get. + * @param[out] value Where to put the extracted value * @return #EINA_TRUE on success, #EINA_FALSE otherwise. * * This call check that the int is correctly set.