From 1320ba435e6fcd3ed868d0798cc4e9a74d4ffd59 Mon Sep 17 00:00:00 2001 From: Bryce Harrington Date: Wed, 15 Aug 2018 09:54:17 +0100 Subject: [PATCH] eina: Add doxygen in/out tags for safepointer, safety_checks, slice, etc. Reviewers: netstar Reviewed By: netstar Subscribers: netstar, cedric, #reviewers, #committers, zmike Tags: #efl Differential Revision: https://phab.enlightenment.org/D6833 --- src/lib/eina/eina_safepointer.h | 6 +- src/lib/eina/eina_safety_checks.h | 38 ++++--- src/lib/eina/eina_simple_xml_parser.h | 157 +++++++++++++------------- src/lib/eina/eina_slice.h | 97 +++++++++------- 4 files changed, 159 insertions(+), 139 deletions(-) diff --git a/src/lib/eina/eina_safepointer.h b/src/lib/eina/eina_safepointer.h index d6e5ce52b5..8120e48bfa 100644 --- a/src/lib/eina/eina_safepointer.h +++ b/src/lib/eina/eina_safepointer.h @@ -65,7 +65,7 @@ typedef struct _Eina_Safepointer Eina_Safepointer; /** * @brief Register a pointer and get an Eina_Safepointer that maps to it. * - * @param target The pointer to register. + * @param[in] target The pointer to register. * @return A valid pointer that is an index to the mapped pointer. * * @note It will return @c NULL on error or if @p target is @c NULL. @@ -82,7 +82,7 @@ EAPI const Eina_Safepointer *eina_safepointer_register(const void *target); /** * @brief Unregister an Eina_Safepointer and the pointer that maps to it. * - * @param safe The index to unregister from the mapping. + * @param[in] safe The index to unregister from the mapping. * * @note This function will ignore the lower 2 bits of the given pointer. * @@ -93,7 +93,7 @@ EAPI void eina_safepointer_unregister(const Eina_Safepointer *safe); /** * @brief Get the associated pointer from an Eina_Safepointer mapping. * - * @param safe The Eina_Safepointer index to lookup at. + * @param[in] safe The Eina_Safepointer index to lookup at. * @return The pointer registered with that index or @c NULL in any other case. * * @note It is always safe to ask for a pointer for any value of the mapping. diff --git a/src/lib/eina/eina_safety_checks.h b/src/lib/eina/eina_safety_checks.h index 52d58f7231..cf29f27a21 100644 --- a/src/lib/eina/eina_safety_checks.h +++ b/src/lib/eina/eina_safety_checks.h @@ -220,69 +220,77 @@ EAPI void _eina_safety_error(const char *file, const char *func, int line, const /** * @def EINA_SAFETY_ON_NULL_RETURN * @brief The macro doesn't do anything unless EINA_SAFETY_CHECKS is defined. - * @param exp The expression to be evaluated. + * @param[in] exp The expression to be evaluated. */ #define EINA_SAFETY_ON_NULL_RETURN(exp) \ do { (void)(!(exp)); } while (0) + /** * @def EINA_SAFETY_ON_NULL_RETURN_VAL * @brief The macro doesn't do anything unless EINA_SAFETY_CHECKS is defined. - * @param exp The expression to be evaluated. - * @param val The value to be returned. + * @param[in] exp The expression to be evaluated. + * @param[in] val The value to be returned. */ #define EINA_SAFETY_ON_NULL_RETURN_VAL(exp, val) \ do { if (0 && !(exp)) { (void)val; } } while (0) + /** * @def EINA_SAFETY_ON_NULL_GOTO * @brief The macro doesn't do anything unless EINA_SAFETY_CHECKS is defined. - * @param exp The expression to be evaluated. - * @param label The label to jump to. + * @param[in] exp The expression to be evaluated. + * @param[in] label The label to jump to. */ #define EINA_SAFETY_ON_NULL_GOTO(exp, label) \ do { if (0 && (exp) == NULL) { goto label; } } while (0) + /** * @def EINA_SAFETY_ON_TRUE_RETURN * @brief The macro doesn't do anything unless EINA_SAFETY_CHECKS is defined. - * @param exp The expression to be evaluated. + * @param[in] exp The expression to be evaluated. */ #define EINA_SAFETY_ON_TRUE_RETURN(exp) \ do { (void)(exp); } while (0) + /** * @def EINA_SAFETY_ON_TRUE_RETURN_VAL * @brief The macro doesn't do anything unless EINA_SAFETY_CHECKS is defined. - * @param exp The expression to be evaluated. - * @param val The value to be returned. + * @param[in] exp The expression to be evaluated. + * @param[in] val The value to be returned. */ #define EINA_SAFETY_ON_TRUE_RETURN_VAL(exp, val) \ do { if (0 && (exp)) { (void)val; } } while (0) + /** * @def EINA_SAFETY_ON_TRUE_GOTO * @brief The macro doesn't do anything unless EINA_SAFETY_CHECKS is defined. - * @param exp The expression to be evaluated. - * @param label The label to jump to. + * @param[in] exp The expression to be evaluated. + * @param[in] label The label to jump to. */ #define EINA_SAFETY_ON_TRUE_GOTO(exp, label) \ do { if (0 && (exp)) { goto label; } } while (0) + /** * @def EINA_SAFETY_ON_FALSE_RETURN * @brief The macro doesn't do anything unless EINA_SAFETY_CHECKS is defined. - * @param exp The expression to be evaluated. + * @param[in] exp The expression to be evaluated. */ #define EINA_SAFETY_ON_FALSE_RETURN(exp) \ do { (void)(!(exp)); } while (0) + /** * @def EINA_SAFETY_ON_FALSE_RETURN_VAL * @brief The macro doesn't do anything unless EINA_SAFETY_CHECKS is defined. - * @param exp The expression to be evaluated. - * @param val The value to be returned. + * @param[in] exp The expression to be evaluated. + * @param[in] val The value to be returned. */ #define EINA_SAFETY_ON_FALSE_RETURN_VAL(exp, val) \ do { if (0 && !(exp)) { (void)val; } } while (0) + /** * @def EINA_SAFETY_ON_FALSE_GOTO * @brief The macro doesn't do anything unless EINA_SAFETY_CHECKS is defined. - * @param exp The expression to be evaluated. - * @param label The label to jump to. + * @param[in] exp The expression to be evaluated. + * @param[in] label The label to jump to. */ #define EINA_SAFETY_ON_FALSE_GOTO(exp, label) \ do { if (0 && !(exp)) { goto label; } } while (0) diff --git a/src/lib/eina/eina_simple_xml_parser.h b/src/lib/eina/eina_simple_xml_parser.h index a31a14ea96..19c0bca44f 100644 --- a/src/lib/eina/eina_simple_xml_parser.h +++ b/src/lib/eina/eina_simple_xml_parser.h @@ -221,23 +221,22 @@ typedef Eina_Bool (*Eina_Simple_XML_Attribute_Cb)(void *data, const char *key, c /** * @brief Parses a section of XML string text * - * @param buf The input string. May not contain \0 terminator. - * @param buflen The input string size. - * @param strip Whenever this parser should strip leading and trailing - * whitespace. These whitespace will still be issued, but as type - * #EINA_SIMPLE_XML_IGNORED. - * @param func What to call back while parse to do some action. The - * first parameter is the given user @a data, the second is the - * token type, the third is the pointer to content start (it's - * not a NULL terminated string!), the fourth is where this - * content is located inside @a buf (does not include tag - * start, for instance "" the offset points at - * "value"), the fifth is the size of the content. Whenever this - * function return #EINA_FALSE the parser will abort. - * @param data What to give as context to @a func. - * + * @param[in] buf The input string. May not contain \0 terminator. + * @param[in] buflen The input string size. + * @param[in] strip Whenever this parser should strip leading and trailing + * whitespace. These whitespace will still be issued, but as type + * #EINA_SIMPLE_XML_IGNORED. + * @param[in] func What to call back while parse to do some action. The + * first parameter is the given user @a data, the second is the + * token type, the third is the pointer to content start (it's + * not a NULL terminated string!), the fourth is where this + * content is located inside @a buf (does not include tag + * start, for instance "" the offset points at + * "value"), the fifth is the size of the content. Whenever this + * function return #EINA_FALSE the parser will abort. + * @param[in] data What to give as context to @a func. * @return #EINA_TRUE on success, or #EINA_FALSE if it was aborted by user or - * parsing error. + * parsing error. */ EAPI Eina_Bool eina_simple_xml_parse(const char *buf, unsigned buflen, Eina_Bool strip, @@ -247,8 +246,8 @@ EAPI Eina_Bool eina_simple_xml_parse(const char *buf, unsigned buflen, /** * @brief Given the contents of a tag, find where the attributes start. * - * @param buf The input string. May not contain \0 terminator. - * @param buflen The input string size. + * @param[in] buf The input string. May not contain \0 terminator. + * @param[in] buflen The input string size. * @return Pointer to the start of attributes, it can be used * to feed eina_simple_xml_attributes_parse(). @c NULL is returned * if no attributes were found. @@ -262,14 +261,14 @@ EAPI const char * eina_simple_xml_tag_attributes_find(const char *buf, unsigned /** * @brief Given a buffer with xml attributes, parse them to key=value pairs. * - * @param buf The input string. May not contain \0 terminator. - * @param buflen The input string size. - * @param func What to call back while parse to do some action. The - * first parameter is the given user @a data, the second is the - * key (null-terminated) and the last is the value (null - * terminated). These strings should not be modified and - * reference is just valid until the function return. - * @param data Data to pass to the callback function. + * @param[in] buf The input string. May not contain \0 terminator. + * @param[in] buflen The input string size. + * @param[in] func What to call back while parse to do some action. The + * first parameter is the given user @a data, the second is the + * key (null-terminated) and the last is the value (null + * terminated). These strings should not be modified and + * reference is just valid until the function return. + * @param[in] data Data to pass to the callback function. * * @return #EINA_TRUE on success, or #EINA_FALSE if it was aborted by user or * parsing error. @@ -280,13 +279,13 @@ EAPI Eina_Bool eina_simple_xml_attributes_parse(const char *buf, unsigned buflen /** * @brief Given a buffer with the xml value of an attributes, parse them to key:value pairs. * - * @param buf the input string. Need to contain \0 terminator. - * @param func what to call back while parse to do some action. The - * first parameter is the given user @a data, the second is the - * key (null-terminated) and the last is the value (null - * terminated). These strings should not be modified and - * reference is just valid until the function return. - * @param data data to pass to the callback function. + * @param[in] buf the input string. Need to contain \0 terminator. + * @param[in] func what to call back while parse to do some action. The + * first parameter is the given user @a data, the second is the + * key (null-terminated) and the last is the value (null + * terminated). These strings should not be modified and + * reference is just valid until the function return. + * @param[in] data data to pass to the callback function. * * @return #EINA_TRUE on success or #EINA_FALSE if it was aborted by user or * parsing error. @@ -299,10 +298,11 @@ eina_simple_xml_attribute_w3c_parse(const char *buf, Eina_Simple_XML_Attribute_C /** * @brief Creates (and appends) new attribute to tag. * - * @param parent If provided, will be set in the resulting structure - * as well as the attribute will be appended to attributes list. - * @param key Null-terminated string. Must not be @c NULL. - * @param value Null-terminated string. If @c NULL, the empty string will be used. + * @param[in,out] parent If provided, will be set in the resulting + * structure as well as the attribute will be appended to + * attributes list. + * @param[in] key Null-terminated string. Must not be @c NULL. + * @param[in] value Null-terminated string. If @c NULL, the empty string will be used. * * @return Newly allocated memory or @c NULL on error. This memory should be * released with eina_simple_xml_attribute_free() or indirectly @@ -313,17 +313,16 @@ EAPI Eina_Simple_XML_Attribute * eina_simple_xml_attribute_new(Eina_Simple_XML_N /** * @brief Removes attribute from parent and deletes it. * - * @param attr attribute to release memory. + * @param[in] attr attribute to release memory. */ EAPI void eina_simple_xml_attribute_free(Eina_Simple_XML_Attribute *attr); - /** * @brief Creates new tag. If parent is provided, it is automatically appended. * - * @param parent If provided, will be set in the resulting structure - * as well as the tag will be appended to children list. - * @param name Null-terminated string. Must not be @c NULL. + * @param[in] parent If provided, will be set in the resulting structure + * as well as the tag will be appended to children list. + * @param[in] name Null-terminated string. Must not be @c NULL. * * @return Newly allocated memory or @c NULL on error. This memory should be * released with eina_simple_xml_node_tag_free() or indirectly @@ -334,7 +333,7 @@ EAPI Eina_Simple_XML_Node_Tag * eina_simple_xml_node_tag_new(Eina_Simple_XML_Nod /** * @brief Removes tag from parent and deletes it. * - * @param tag to release memory. + * @param[in] tag to release memory. */ EAPI void eina_simple_xml_node_tag_free(Eina_Simple_XML_Node_Tag *tag); @@ -342,10 +341,10 @@ EAPI void eina_simple_xml_node_tag_free(Eina_Simple_XML_Node_Tag *tag); /** * @brief Creates new data. If parent is provided, it is automatically appended. * - * @param parent If provided, will be set in the resulting structure - * as well as the data will be appended to children list. - * @param contents String to be used. Must not be @c NULL. - * @param length Size in bytes of @a contents. + * @param[in,out] parent If provided, will be set in the resulting structure + * as well as the data will be appended to children list. + * @param[in] contents String to be used. Must not be @c NULL. + * @param[in] length Size in bytes of @a contents. * * @return Newly allocated memory or NULL on error. This memory should be * released with eina_simple_xml_node_data_free() or indirectly @@ -356,7 +355,7 @@ EAPI Eina_Simple_XML_Node_Data * eina_simple_xml_node_data_new(Eina_Simple_XML_N /** * @brief Removes data from parent and deletes it. * - * @param node to release memory. + * @param[in] node to release memory. */ EAPI void eina_simple_xml_node_data_free(Eina_Simple_XML_Node_Data *node); @@ -364,10 +363,10 @@ EAPI void eina_simple_xml_node_data_free(Eina_Simple_XML_Node_Data *node); /** * @brief Creates new cdata. If parent is provided, it is automatically appended. * - * @param parent If provided, will be set in the resulting structure + * @param[in,out] parent If provided, will be set in the resulting structure * as well as the cdata will be appended to children list. - * @param contents String to be used. Must not be @c NULL. - * @param length Size in bytes of @a content. + * @param[in] contents String to be used. Must not be @c NULL. + * @param[in] length Size in bytes of @a content. * * @return Newly allocated memory or @c NULL on error. This memory should be * released with eina_simple_xml_node_cdata_free() or indirectly @@ -378,7 +377,7 @@ EAPI Eina_Simple_XML_Node_CData * eina_simple_xml_node_cdata_new(Eina_Simple_XML /** * @brief Removes cdata from parent and deletes it. * - * @param node to release memory. + * @param[in] node to release memory. */ EAPI void eina_simple_xml_node_cdata_free(Eina_Simple_XML_Node_Data *node); @@ -386,10 +385,10 @@ EAPI void eina_simple_xml_node_cdata_free(Eina_Simple_XML_Node_Data *node); /** * @brief Creates new doctype child. If parent is provided, it is automatically appended. * - * @param parent If provided, will be set in the resulting structure - * as well as the doctype child will be appended to children list. - * @param contents String to be used. Must not be @c NULL. - * @param length size in bytes of @a content. + * @param[in,out] parent If provided, will be set in the resulting structure + * as well as the doctype child will be appended to children list. + * @param[in] contents String to be used. Must not be @c NULL. + * @param[in] length size in bytes of @a content. * * @return Newly allocated memory or @c NULL on error. This memory should be * released with eina_simple_xml_node_doctype_child_free() or indirectly @@ -402,7 +401,7 @@ EAPI Eina_Simple_XML_Node_Doctype_Child * eina_simple_xml_node_doctype_child_new /** * @brief Removes doctype child from parent and deletes it. * - * @param node to release memory. + * @param[in] node to release memory. * * @since 1.8 */ @@ -412,10 +411,10 @@ EAPI void eina_simple_xml_node_doctype_child_free(Eina_Simple_XML_Node_Data *nod /** * @brief Creates new processing. If parent is provided, it is automatically appended. * - * @param parent If provided, will be set in the resulting structure - * as well as the processing will be appended to children list. - * @param contents String to be used. Must not be @c NULL. - * @param length Size in bytes of @a contents. + * @param[in,out] parent If provided, will be set in the resulting structure + * as well as the processing will be appended to children list. + * @param[in] contents String to be used. Must not be @c NULL. + * @param[in] length Size in bytes of @a contents. * * @return Newly allocated memory or @c NULL on error. This memory should be * released with eina_simple_xml_node_processing_free() or indirectly @@ -426,7 +425,7 @@ EAPI Eina_Simple_XML_Node_Processing * eina_simple_xml_node_processing_new(Eina_ /** * @brief Removes processing from parent and deletes it. * - * @param node processing to release memory. + * @param[in] node processing to release memory. */ EAPI void eina_simple_xml_node_processing_free(Eina_Simple_XML_Node_Data *node); @@ -434,10 +433,10 @@ EAPI void eina_simple_xml_node_processing_free(Eina_Simple_XML_Node_Data *node); /** * @brief Creates new doctype. If parent is provided, it is automatically appended. * - * @param parent If provided, will be set in the resulting structure - * as well as the doctype will be appended to children list. - * @param contents String to be used. Must not be @c NULL. - * @param length Size in bytes of @a contents. + * @param[in,out] parent If provided, will be set in the resulting structure + * as well as the doctype will be appended to children list. + * @param[in] contents String to be used. Must not be @c NULL. + * @param[in] length Size in bytes of @a contents. * * @return Newly allocated memory or @c NULL on error. This memory should be * released with eina_simple_xml_node_doctype_free() or indirectly @@ -448,7 +447,7 @@ EAPI Eina_Simple_XML_Node_Doctype * eina_simple_xml_node_doctype_new(Eina_Simple /** * @brief Removes doctype from parent and deletes it. * - * @param node doctype to release memory. + * @param[in] node doctype to release memory. */ EAPI void eina_simple_xml_node_doctype_free(Eina_Simple_XML_Node_Data *node); @@ -456,10 +455,10 @@ EAPI void eina_simple_xml_node_doctype_free(Eina_Simple_XML_Node_Data *node); /** * @brief Creates new comment. If parent is provided, it is automatically appended. * - * @param parent If provided, will be set in the resulting structure - * as well as the comment will be appended to children list. - * @param contents String to be used. Must not be @c NULL. - * @param length Size in bytes of @a contents. + * @param[in,out] parent If provided, will be set in the resulting structure + * as well as the comment will be appended to children list. + * @param[in] contents String to be used. Must not be @c NULL. + * @param[in] length Size in bytes of @a contents. * * @return Newly allocated memory or @c NULL on error. This memory should be * released with eina_simple_xml_node_comment_free() or indirectly @@ -470,7 +469,7 @@ EAPI Eina_Simple_XML_Node_Comment * eina_simple_xml_node_comment_new(Eina_Simple /** * @brief Removes comment from parent and deletes it. * - * @param node comment to release memory. + * @param[in] node comment to release memory. */ EAPI void eina_simple_xml_node_comment_free(Eina_Simple_XML_Node_Data *node); @@ -478,10 +477,10 @@ EAPI void eina_simple_xml_node_comment_free(Eina_Simple_XML_Node_Data *node); /** * @brief Loads a XML node tree based on the given string. * - * @param buf The input string. May not contain \0 terminator. - * @param buflen The input string size. - * @param strip Whenever this parser should strip leading and trailing - * whitespace. + * @param[in] buf The input string. May not contain \0 terminator. + * @param[in] buflen The input string size. + * @param[in] strip Whenever this parser should strip leading and trailing + * whitespace. * * @return Document root with children tags, or @c NULL on errors. * Document with errors may return partial tree instead of @c NULL, @@ -492,15 +491,15 @@ EAPI Eina_Simple_XML_Node_Root * eina_simple_xml_node_load(const char *buf, unsi /** * @brief Frees node tree build with eina_simple_xml_node_load() * - * @param root Memory returned by eina_simple_xml_node_load() + * @param[in] root Memory returned by eina_simple_xml_node_load() */ EAPI void eina_simple_xml_node_root_free(Eina_Simple_XML_Node_Root *root); /** * @brief Converts the node tree under the given element to a XML string. * - * @param node The base node to convert. - * @param indent Indentation string, or @c NULL to disable it. + * @param[in,out] node The base node to convert. + * @param[in] indent Indentation string, or @c NULL to disable it. * * @return @c NULL on errors, or a newly allocated string on success. */ diff --git a/src/lib/eina/eina_slice.h b/src/lib/eina/eina_slice.h index 4c2efffd48..fab84e9dc8 100644 --- a/src/lib/eina/eina_slice.h +++ b/src/lib/eina/eina_slice.h @@ -123,7 +123,7 @@ struct _Eina_Rw_Slice /** * @brief Convert the Read-write slice to read-only. * - * @param rw_slice the read-write slice to convert. + * @param[in] rw_slice the read-write slice to convert. * @return the red-only slice matching the slice. */ static inline Eina_Slice eina_rw_slice_slice_get(const Eina_Rw_Slice rw_slice); @@ -131,7 +131,7 @@ static inline Eina_Slice eina_rw_slice_slice_get(const Eina_Rw_Slice rw_slice); /** * @brief Creates a duplicate of slice's memory. * - * @param slice the input to duplicate + * @param[in] slice the input to duplicate * @return a new read-write slice with new @c mem that matches @a slice * contents. The new @c mem is allocated with malloc() and must * be released with free(). @@ -146,7 +146,7 @@ static inline Eina_Rw_Slice eina_slice_dup(const Eina_Slice slice) EINA_WARN_UNU /** * @brief Creates a duplicate of slice's memory. * - * @param rw_slice the input to duplicate + * @param[in] rw_slice the input to duplicate * @return a new read-write slice with new @c mem that matches @a slice * contents. The new @c mem is allocated with malloc() and must * be released with free(). @@ -161,8 +161,8 @@ static inline Eina_Rw_Slice eina_rw_slice_dup(const Eina_Rw_Slice rw_slice) EINA /** * @brief Compare two slices, similar to memcmp() * - * @param a the first slice to compare. - * @param b the second slice to compare. + * @param[in] a the first slice to compare. + * @param[in] b the second slice to compare. * @return 0 if equal, < 0 if a < b, > 0 if a > b * * @since 1.19 @@ -172,8 +172,8 @@ static inline int eina_slice_compare(const Eina_Slice a, const Eina_Slice b); /** * @brief Compare two slices, similar to memcmp() * - * @param a the first slice to compare. - * @param b the second slice to compare. + * @param[in] a the first slice to compare. + * @param[in] b the second slice to compare. * @return 0 if equal, < 0 if a < b, > 0 if a > b * * @since 1.19 @@ -183,8 +183,8 @@ static inline int eina_rw_slice_compare(const Eina_Rw_Slice a, const Eina_Rw_Sli /** * @brief Copy a read-only slice to a read-write one, similar to memcpy(). * - * @param dest where to write the memory. - * @param src where to load memory. + * @param[in] dest where to write the memory. + * @param[in] src where to load memory. * * @return a new slice with the resulting write. Note that the length * (@c len) will be the smallest of @a dest and @a src. @@ -199,9 +199,9 @@ static inline Eina_Rw_Slice eina_rw_slice_copy(const Eina_Rw_Slice dest, const E /** * @brief Seek within a slice, similar to fseek(). * - * @param slice the containing slice to seek inside. - * @param offset how to get to the new position. - * @param whence SEEK_SET, SEEK_END as fseek(). + * @param[in] slice the containing slice to seek inside. + * @param[in] offset how to get to the new position. + * @param[in] whence SEEK_SET, SEEK_END as fseek(). * @return a new slice contained inside, it will start at the given * offset and have a length that goes until the end of the @a * slice. If an invalid @a whence, a zero-sized slice starting @@ -217,9 +217,9 @@ static inline Eina_Slice eina_slice_seek(const Eina_Slice slice, ssize_t offset, /** * @brief Seek within a read-write slice, similar to fseek(). * - * @param rw_slice the containing slice to seek inside. - * @param offset how to get to the new position. - * @param whence SEEK_SET, SEEK_END as fseek(). + * @param[in] rw_slice the containing slice to seek inside. + * @param[in] offset how to get to the new position. + * @param[in] whence SEEK_SET, SEEK_END as fseek(). * @return a new slice contained inside, it will start at the given * offset and have a length that goes until the end of the @a * rw_slice. If an invalid @a whence, a zero-sized slice @@ -236,8 +236,8 @@ static inline Eina_Rw_Slice eina_rw_slice_seek(const Eina_Rw_Slice rw_slice, ssi /** * @brief Find a character inside the slice, similar to memchr(). * - * @param slice the reference memory. - * @param c the byte (character) to find. + * @param[in] slice the reference memory. + * @param[in] c the byte (character) to find. * @return the memory within slice or @c NULL if not found. * * @since 1.19 @@ -247,8 +247,8 @@ static inline const void *eina_slice_strchr(const Eina_Slice slice, int c); /** * @brief Find a needle inside the slice, similar to memmem(). * - * @param slice the reference memory. - * @param needle what to find. + * @param[in] slice the reference memory. + * @param[in] needle what to find. * @return the memory within slice or @c NULL if not found. * * @since 1.19 @@ -258,8 +258,8 @@ static inline const void *eina_slice_find(const Eina_Slice slice, const Eina_Sli /** * @brief Checks if the slice starts with a prefix. * - * @param slice the reference memory. - * @param prefix the slice to check if @a slice starts with. + * @param[in] slice the reference memory. + * @param[in] prefix the slice to check if @a slice starts with. * @return #EINA_TRUE if @a slice starts with @a prefix, #EINA_FALSE otherwise. * * @since 1.19 @@ -269,8 +269,8 @@ static inline Eina_Bool eina_slice_startswith(const Eina_Slice slice, const Eina /** * @brief Checks if the slice ends with a suffix. * - * @param slice the reference memory. - * @param suffix the slice to check if @a slice ends with. + * @param[in] slice the reference memory. + * @param[in] suffix the slice to check if @a slice ends with. * @return #EINA_TRUE if @a slice ends with @a suffix, #EINA_FALSE otherwise. * * @since 1.19 @@ -280,8 +280,8 @@ static inline Eina_Bool eina_slice_endswith(const Eina_Slice slice, const Eina_S /** * @brief Find a character inside the slice, similar to memchr(). * - * @param rw_slice the reference memory. - * @param c the byte (character) to find. + * @param[in] rw_slice the reference memory. + * @param[in] c the byte (character) to find. * @return the memory within slice or @c NULL if not found. * * @since 1.19 @@ -291,8 +291,8 @@ static inline void *eina_rw_slice_strchr(const Eina_Rw_Slice rw_slice, int c); /** * @brief Find a needle inside the slice, similar to memmem(). * - * @param rw_slice the reference memory. - * @param needle what to find. + * @param[in] rw_slice the reference memory. + * @param[in] needle what to find. * @return the memory within slice or @c NULL if not found. * * @since 1.19 @@ -302,8 +302,8 @@ static inline void *eina_rw_slice_find(const Eina_Rw_Slice rw_slice, const Eina_ /** * @brief Checks if the slice starts with a prefix. * - * @param slice the reference memory. - * @param prefix the slice to check if @a slice starts with. + * @param[in] slice the reference memory. + * @param[in] prefix the slice to check if @a slice starts with. * @return #EINA_TRUE if @a slice starts with @a prefix, #EINA_FALSE otherwise. * * @since 1.19 @@ -313,8 +313,8 @@ static inline Eina_Bool eina_rw_slice_startswith(const Eina_Rw_Slice slice, cons /** * @brief Checks if the slice ends with a suffix. * - * @param slice the reference memory. - * @param suffix the slice to check if @a slice ends with. + * @param[in] slice the reference memory. + * @param[in] suffix the slice to check if @a slice ends with. * @return #EINA_TRUE if @a slice ends with @a suffix, #EINA_FALSE otherwise. * * @since 1.19 @@ -327,7 +327,7 @@ static inline Eina_Bool eina_rw_slice_endswith(const Eina_Rw_Slice slice, const * @note this is out-of the slice, the first byte after it ends and * must not be accessed. * - * @param slice the reference memory. + * @param[in] slice the reference memory. * @return the first byte after the slice ends. * * @since 1.19 @@ -340,7 +340,7 @@ static inline const void *eina_slice_end_get(const Eina_Slice slice); * @note this is out-of the slice, the first byte after it ends and * must not be accessed. * - * @param rw_slice the reference memory. + * @param[in] rw_slice the reference memory. * @return the first byte after the slice ends. * * @since 1.19 @@ -350,7 +350,7 @@ static inline void *eina_rw_slice_end_get(const Eina_Rw_Slice rw_slice); /** * @brief A null-terminated string for this slice. * - * @param slice the reference memory. + * @param[in] slice the reference memory. * @return newly allocated memory or @c NULL on error * * @since 1.19 @@ -360,7 +360,7 @@ static inline char *eina_slice_strdup(const Eina_Slice slice); /** * @brief A null-terminated string for this slice. * - * @param slice the reference memory. + * @param[in] slice the reference memory. * @return newly allocated memory or @c NULL on error * * @since 1.19 @@ -370,7 +370,10 @@ static inline char *eina_rw_slice_strdup(const Eina_Rw_Slice rw_slice); /** * @def EINA_SLICE_ARRAY(buf) * - * Initializer for arrays of any kind. + * @brief Initializer for arrays of any kind. + * + * @param[in] buf The array to create the slice from. + * @return The initialized slice object. * * It is often useful for globals. * @@ -398,8 +401,8 @@ static inline char *eina_rw_slice_strdup(const Eina_Rw_Slice rw_slice); * Declare a local (stack) array for storage at given @a length and * initialize an Eina_Rw_Slice called @a name. * - * @param name the name of the variable to be the Eina_Rw_Slice - * @param length the size in bytes of the storage. + * @param[in] name the name of the variable to be the Eina_Rw_Slice. + * @param[in] length the size in bytes of the storage. * * @since 1.19 */ @@ -416,6 +419,9 @@ static inline char *eina_rw_slice_strdup(const Eina_Rw_Slice rw_slice); * * It is often useful for globals. * + * @param[in] buf The array to create the slice from. + * @return The initialized slice object. + * * @note This macro is usable with both Eina_Slice or Eina_Rw_Slice. * * @code @@ -438,6 +444,9 @@ static inline char *eina_rw_slice_strdup(const Eina_Rw_Slice rw_slice); * * Initializer for strings (uses strlen()). * + * @param[in] str The string to create the slice from. + * @return The initialized slice object. + * * @note This macro is usable with both Eina_Slice or Eina_Rw_Slice. * * @code @@ -477,9 +486,12 @@ static inline char *eina_rw_slice_strdup(const Eina_Rw_Slice rw_slice); /** * @def EINA_SLICE_STR_PRINT(s) * - * To be used in printf()-like statements when EINA_SLICE_STR_FMT was + * @brief To be used in printf()-like statements when EINA_SLICE_STR_FMT was * used, it will print the slice as a string up to @c len. * + * @param[in] s The slice. + * @return The arguments for an EINA_SLICE_STR_FMT formatted printf. + * * Use with EINA_SLICE_STR_FMT. * * @note This macro is usable with both Eina_Slice or Eina_Rw_Slice. @@ -522,7 +534,8 @@ static inline char *eina_rw_slice_strdup(const Eina_Rw_Slice rw_slice); * * @note This macro is usable with both Eina_Slice or Eina_Rw_Slice. * - * @param s the slice + * @param[in] s The slice. + * @return The arguments for an EINA_SLICE_FMT formatted printf. * * @code * Eina_Slice s = EINA_SLICE_STR_LITERAL("hello"); @@ -545,8 +558,8 @@ static inline char *eina_rw_slice_strdup(const Eina_Rw_Slice rw_slice); * @note Be aware of memory alignment! Accessing unaligned memory may * not be supported in some architectures. * - * @param s the slice - * @param itr the iterator to hold each byte. Use a proper type, not + * @param[in] s The slice. + * @param[in,out] itr the iterator to hold each byte. Use a proper type, not * "void*" or "const void*" as it doesn't have an intrinsic * size. *