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

eina: make doxygen @notes consistent in eina_hash 

Summary:
These routines all have slight permutations of the same basic note, but
are each formatted a bit differently.  Fix that and a few punctuation
irregularities.

Similarly for a couple @warnings, and escalate one @note to a @warning
since what it describes might be a security issue so deserves
highlighting.

Subscribers: cedric

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

Signed-off-by: Cedric Bail <cedric@osg.samsung.com>
This commit is contained in:
Bryce Harrington 2018-02-14 12:00:06 -08:00 committed by Cedric Bail
parent d58ae6b12f
commit ba64b372d3
1 changed files with 23 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -423,8 +423,9 @@ EAPI Eina_Hash *eina_hash_string_djb2_new(Eina_Free_Cb data_free_cb);
* then be looked up with pointers other than the original key pointer
* that was used to add values.
*
* @note Don't use this kind of hash when there is a possibility to remotely
* request and push data in it. This hash is subject to denial of service.
* @warning Don't use this kind of hash when there is a possibility to
* remotely request and push data in it. This hash is subject to denial
* of service.
*/
EAPI Eina_Hash *eina_hash_string_superfast_new(Eina_Free_Cb data_free_cb);
@ -598,10 +599,9 @@ EAPI Eina_Bool eina_hash_direct_add(Eina_Hash *hash,
* match to remove, otherwise @p key is used and @p data is not
* required and can be @c NULL.
*
* @note if you know you already have the key, use
* eina_hash_del_by_key() or eina_hash_del_by_key_hash(). If you
* know you don't have the key, use eina_hash_del_by_data()
* directly.
* @note If you already have the key, use eina_hash_del_by_key() or
* eina_hash_del_by_key_hash(). If you don't have the key, use
* eina_hash_del_by_data() directly.
*/
EAPI Eina_Bool eina_hash_del(Eina_Hash *hash,
const void *key,
@ -798,8 +798,8 @@ EAPI Eina_Bool eina_hash_direct_add_by_hash(Eina_Hash *hash,
* value of @p key_length. If @p hash or @p key are @c NULL, the
* function returns #EINA_FALSE immediately.
*
* @note If you don't have the key_hash, use eina_hash_del_by_key() instead.
* @note If you don't have the key, use eina_hash_del_by_data() instead.
* @note If you don't have the key_hash, use eina_hash_del_by_key()
* instead. If you don't have the key, use eina_hash_del_by_data().
*/
EAPI Eina_Bool eina_hash_del_by_key_hash(Eina_Hash *hash,
const void *key,
@ -823,9 +823,8 @@ EAPI Eina_Bool eina_hash_del_by_key_hash(Eina_Hash *hash,
* for the data being deleted. If @p hash or @p key are @c NULL, the
* function returns #EINA_FALSE immediately.
*
* @note If you already have the key_hash, use eina_hash_del_by_key_hash()
* instead.
* @note If you don't have the key, use eina_hash_del_by_data() instead.
* @note If you already have the key_hash, use eina_hash_del_by_key_hash().
* If you don't have the key, use eina_hash_del_by_data() instead.
*/
EAPI Eina_Bool eina_hash_del_by_key(Eina_Hash *hash,
const void *key) EINA_ARG_NONNULL(1, 2);
@ -846,8 +845,8 @@ EAPI Eina_Bool eina_hash_del_by_key(Eina_Hash *hash,
* @note This version is slow since there is no quick access to nodes
* based on data.
*
* @note If you already have the key, use eina_hash_del_by_key() or
* eina_hash_del_by_key_hash() instead.
* @note If you already have the key, use eina_hash_del_by_key()
* or eina_hash_del_by_key_hash() instead.
*/
EAPI Eina_Bool eina_hash_del_by_data(Eina_Hash *hash,
const void *data) EINA_ARG_NONNULL(1, 2);
@ -876,9 +875,8 @@ EAPI Eina_Bool eina_hash_del_by_data(Eina_Hash *hash,
* and can be @c NULL. Do not forget to count '\\0' for string when
* setting the value of @p key_length.
*
* @note If you already have the key, use eina_hash_del_by_key_hash(),
* If you don't have the key, use eina_hash_del_by_data()
* directly.
* @note If you already have the key, use eina_hash_del_by_key_hash().
* If you don't have the key, use eina_hash_del_by_data() directly.
*/
EAPI Eina_Bool eina_hash_del_by_hash(Eina_Hash *hash,
const void *key,
@ -938,9 +936,9 @@ EAPI void *eina_hash_modify_by_hash(Eina_Hash *hash,
* valid iterator that will always return false on
* eina_iterator_next(), thus keeping API sane.
*
* @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!
* @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.
*/
EAPI Eina_Iterator *eina_hash_iterator_key_new(const Eina_Hash *hash) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
@ -955,7 +953,7 @@ EAPI Eina_Iterator *eina_hash_iterator_key_new(const Eina_Hash *hash) EINA_MALLO
* valid iterator that will always return false on
* eina_iterator_next(), thus keeping API sane.
*
* @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
* is undefined and your program may crash.
*/
@ -972,12 +970,12 @@ EAPI Eina_Iterator *eina_hash_iterator_data_new(const Eina_Hash *hash) EINA_MALL
* valid iterator that will always return false on
* eina_iterator_next(), thus keeping API sane.
*
* @note Iterator data will provide values as Eina_Hash_Tuple that should not
* be modified!
* @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!
* @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.
*/
EAPI Eina_Iterator *eina_hash_iterator_tuple_new(const Eina_Hash *hash) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;