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 * then be looked up with pointers other than the original key pointer
* that was used to add values. * that was used to add values.
* *
* @note Don't use this kind of hash when there is a possibility to remotely * @warning Don't use this kind of hash when there is a possibility to
* request and push data in it. This hash is subject to denial of service. * 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); 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 * match to remove, otherwise @p key is used and @p data is not
* required and can be @c NULL. * required and can be @c NULL.
* *
* @note if you know you already have the key, use * @note If you already have the key, use eina_hash_del_by_key() or
* eina_hash_del_by_key() or eina_hash_del_by_key_hash(). If you * eina_hash_del_by_key_hash(). If you don't have the key, use
* know you don't have the key, use eina_hash_del_by_data() * eina_hash_del_by_data() directly.
* directly.
*/ */
EAPI Eina_Bool eina_hash_del(Eina_Hash *hash, EAPI Eina_Bool eina_hash_del(Eina_Hash *hash,
const void *key, 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 * value of @p key_length. If @p hash or @p key are @c NULL, the
* function returns #EINA_FALSE immediately. * 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_hash, use eina_hash_del_by_key()
* @note If you don't have the key, use eina_hash_del_by_data() instead. * 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, EAPI Eina_Bool eina_hash_del_by_key_hash(Eina_Hash *hash,
const void *key, 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 * for the data being deleted. If @p hash or @p key are @c NULL, the
* function returns #EINA_FALSE immediately. * function returns #EINA_FALSE immediately.
* *
* @note If you already have the key_hash, use eina_hash_del_by_key_hash() * @note If you already have the key_hash, use eina_hash_del_by_key_hash().
* instead. * If you don't have the key, use eina_hash_del_by_data() instead.
* @note If you don't have the key, use eina_hash_del_by_data() instead.
*/ */
EAPI Eina_Bool eina_hash_del_by_key(Eina_Hash *hash, EAPI Eina_Bool eina_hash_del_by_key(Eina_Hash *hash,
const void *key) EINA_ARG_NONNULL(1, 2); 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 * @note This version is slow since there is no quick access to nodes
* based on data. * based on data.
* *
* @note If you already have the key, use eina_hash_del_by_key() or * @note If you already have the key, use eina_hash_del_by_key()
* eina_hash_del_by_key_hash() instead. * or eina_hash_del_by_key_hash() instead.
*/ */
EAPI Eina_Bool eina_hash_del_by_data(Eina_Hash *hash, EAPI Eina_Bool eina_hash_del_by_data(Eina_Hash *hash,
const void *data) EINA_ARG_NONNULL(1, 2); 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 * and can be @c NULL. Do not forget to count '\\0' for string when
* setting the value of @p key_length. * setting the value of @p key_length.
* *
* @note If you already have the key, use eina_hash_del_by_key_hash(), * @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() * If you don't have the key, use eina_hash_del_by_data() directly.
* directly.
*/ */
EAPI Eina_Bool eina_hash_del_by_hash(Eina_Hash *hash, EAPI Eina_Bool eina_hash_del_by_hash(Eina_Hash *hash,
const void *key, 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 * valid iterator that will always return false on
* eina_iterator_next(), thus keeping API sane. * 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 * invalid. That is, if you add or remove items this iterator behavior
* behavior is undefined and your program may 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;
@ -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 * valid iterator that will always return false on
* eina_iterator_next(), thus keeping API sane. * 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 * invalid. That is, if you add or remove items this iterator behavior
* is undefined and your program may crash. * 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 * valid iterator that will always return false on
* eina_iterator_next(), thus keeping API sane. * eina_iterator_next(), thus keeping API sane.
* *
* @note Iterator data will provide values as Eina_Hash_Tuple that should not * @note Iterator data will provide values as Eina_Hash_Tuple that
* 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 * invalid. That is, if you add or remove items this iterator behavior
* behavior is undefined and your program may 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;