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

eina: tighten grammar in eina_hash API docs. 

Summary:
Improve the verbage in the doxygen comments.  Refer to the value being
changed as the 'previous' rather than the 'old' value, to be more
precise.  Drop the phrase 'keeping API sane' as it is unnecessary and
is an odd thing to say.  Try to avoid referring to 'your program' as we
shouldn't assume the reader's situation.

Reviewers: cedric

Differential Revision: https://phab.enlightenment.org/D5834

Signed-off-by: Cedric Bail <cedric@osg.samsung.com>
This commit is contained in:
Bryce Harrington 2018-03-06 16:59:34 -08:00 committed by Cedric Bail
parent 3b508dfc19
commit c96f3d5ba5
1 changed files with 18 additions and 21 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -622,13 +622,13 @@ EAPI void *eina_hash_find(const Eina_Hash *hash,
const void *key) EINA_ARG_NONNULL(2); const void *key) EINA_ARG_NONNULL(2);
/** /**
* @brief Modifies the entry pointer at the specified key and returns the old * @brief Modifies the entry pointer at the specified key and returns
* entry. * the previous entry.
* @param hash The given hash table. * @param hash The given hash table.
* @param key The key of the entry to modify. * @param key The key of the entry to modify.
* @param data The new data. * @param data The new data.
* @return The data pointer for the old stored entry on success, or * @return The data pointer for the previously stored entry on success,
* @c NULL otherwise. * or @c NULL otherwise.
* *
* This function modifies the data of @p key with @p data in @p * This function modifies the data of @p key with @p data in @p
* hash. If no entry is found, nothing is added to @p hash. * hash. If no entry is found, nothing is added to @p hash.
@ -639,12 +639,12 @@ EAPI void *eina_hash_modify(Eina_Hash *hash,
/** /**
* @brief Modifies the entry pointer at the specified key and returns the * @brief Modifies the entry pointer at the specified key and returns the
* old entry or adds the entry if not found. * previous entry or adds the entry if not found.
* *
* @param hash The given hash table. * @param hash The given hash table.
* @param key The key of the entry to modify. * @param key The key of the entry to modify.
* @param data The data to replace the old entry * @param data The data to replace the previous entry.
* @return The data pointer for the old stored entry, or @c NULL * @return The data pointer for the previous stored entry, or @c NULL
* otherwise. * otherwise.
* *
* This function modifies the value of @p key to @p data in @p * This function modifies the value of @p key to @p data in @p
@ -906,7 +906,7 @@ EAPI void *eina_hash_find_by_hash(const Eina_Hash *hash,
/** /**
* @brief Modifies the entry pointer at the specified key and returns * @brief Modifies the entry pointer at the specified key and returns
* the old entry. * the previous entry.
* *
* @param hash The given hash table. * @param hash The given hash table.
* @param key The key of the entry to modify. * @param key The key of the entry to modify.
@ -914,10 +914,10 @@ EAPI void *eina_hash_find_by_hash(const Eina_Hash *hash,
* '\\0' for string). * '\\0' for string).
* @param key_hash The hash that always matches the key. Ignored if @p * @param key_hash The hash that always matches the key. Ignored if @p
* key is @c NULL. * key is @c NULL.
* @param data The data to replace the old entry, if it exists. * @param data The data to replace the current entry, if it exists.
* @return The data pointer for the old stored entry, or @c NULL if not * @return The data pointer for the previously stored entry, or @c NULL
* found. If an existing entry is not found, nothing is added to the * if not found. If an existing entry is not found, nothing is added to
* hash. * the hash.
*/ */
EAPI void *eina_hash_modify_by_hash(Eina_Hash *hash, EAPI void *eina_hash_modify_by_hash(Eina_Hash *hash,
const void *key, const void *key,
@ -934,11 +934,10 @@ EAPI void *eina_hash_modify_by_hash(Eina_Hash *hash,
* This function returns a newly allocated iterator associated with @p * This function returns a newly allocated iterator associated with @p
* hash. If @p hash is not populated, this function still returns a * hash. If @p hash is not populated, this function still returns a
* valid iterator that will always return false on * valid iterator that will always return false on
* eina_iterator_next(), thus keeping API sane. * eina_iterator_next().
* *
* @warning If the hash structure changes then the iterator becomes * @warning If the hash structure changes then the iterator becomes
* invalid. That is, if you add or remove items this iterator behavior * invalid; adding or removing items may lead to program crash.
* is undefined and your program may crash.
*/ */
EAPI Eina_Iterator *eina_hash_iterator_key_new(const Eina_Hash *hash) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; EAPI Eina_Iterator *eina_hash_iterator_key_new(const Eina_Hash *hash) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
@ -951,11 +950,10 @@ EAPI Eina_Iterator *eina_hash_iterator_key_new(const Eina_Hash *hash) EINA_MALLO
* This function returns a newly allocated iterator associated with * This function returns a newly allocated iterator associated with
* @p hash. If @p hash is not populated, this function still returns a * @p hash. If @p hash is not populated, this function still returns a
* valid iterator that will always return false on * valid iterator that will always return false on
* eina_iterator_next(), thus keeping API sane. * eina_iterator_next().
* *
* @warning If the hash structure changes then the iterator becomes * @warning If the hash structure changes then the iterator becomes
* invalid. That is, if you add or remove items this iterator behavior * invalid; adding or removing items may lead to program crash.
* is undefined and your program may crash.
*/ */
EAPI Eina_Iterator *eina_hash_iterator_data_new(const Eina_Hash *hash) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; EAPI Eina_Iterator *eina_hash_iterator_data_new(const Eina_Hash *hash) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
@ -968,14 +966,13 @@ EAPI Eina_Iterator *eina_hash_iterator_data_new(const Eina_Hash *hash) EINA_MALL
* This function returns a newly allocated iterator associated with @p * This function returns a newly allocated iterator associated with @p
* hash. If @p hash is not populated, this function still returns a * hash. If @p hash is not populated, this function still returns a
* valid iterator that will always return false on * valid iterator that will always return false on
* eina_iterator_next(), thus keeping API sane. * eina_iterator_next().
* *
* @note Iterator data will provide values as Eina_Hash_Tuple that * @note Iterator data will provide values as Eina_Hash_Tuple that
* should not be modified! * should not be modified!
* *
* @warning If the hash structure changes then the iterator becomes * @warning If the hash structure changes then the iterator becomes
* invalid. That is, if you add or remove items this iterator behavior * invalid; adding or removing items may lead to program crash.
* is undefined and your program may crash.
*/ */
EAPI Eina_Iterator *eina_hash_iterator_tuple_new(const Eina_Hash *hash) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; EAPI Eina_Iterator *eina_hash_iterator_tuple_new(const Eina_Hash *hash) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;