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);
/**
* @brief Modifies the entry pointer at the specified key and returns the old
* entry.
* @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.
* @return The data pointer for the old stored entry on success, or
* @c NULL otherwise.
* @return The data pointer for the previously stored entry on success,
* or @c NULL otherwise.
*
* 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.
@ -639,12 +639,12 @@ EAPI void *eina_hash_modify(Eina_Hash *hash,
/**
* @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 key The key of the entry to modify.
* @param data The data to replace the old entry
* @return The data pointer for the old stored entry, or @c NULL
* @param data The data to replace the previous entry.
* @return The data pointer for the previous stored entry, or @c NULL
* otherwise.
*
* 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
* the old entry.
* the previous entry.
*
* @param hash The given hash table.
* @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).
* @param key_hash The hash that always matches the key. Ignored if @p
* key is @c NULL.
* @param data The data to replace the old entry, if it exists.
* @return The data pointer for the old stored entry, or @c NULL if not
* found. If an existing entry is not found, nothing is added to the
* hash.
* @param 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.
*/
EAPI void *eina_hash_modify_by_hash(Eina_Hash *hash,
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
* hash. If @p hash is not populated, this function still returns a
* 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
* invalid. That is, if you add or remove items this iterator behavior
* is undefined and your program may crash.
* invalid; adding or removing items may lead to program crash.
*/
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
* @p hash. If @p hash is not populated, this function still returns a
* 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
* invalid. That is, if you add or remove items this iterator behavior
* is undefined and your program may crash.
* invalid; adding or removing items may lead to program crash.
*/
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
* hash. If @p hash is not populated, this function still returns a
* 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
* should not be modified!
*
* @warning If the hash structure changes then the iterator becomes
* invalid. That is, if you add or remove items this iterator behavior
* is undefined and your program may crash.
* invalid; adding or removing items may lead to program crash.
*/
EAPI Eina_Iterator *eina_hash_iterator_tuple_new(const Eina_Hash *hash) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;