From 1eb2a44f08db45ac48f4599d6046e60d42017d1e Mon Sep 17 00:00:00 2001 From: "Jonas M. Gastal" Date: Tue, 28 Jun 2011 14:37:49 +0000 Subject: [PATCH] Eina: Slight improvement to eina_strbuf's documentation. SVN revision: 60761 --- legacy/eina/src/include/eina_strbuf.h | 34 ++++++++++++++++++--------- 1 file changed, 23 insertions(+), 11 deletions(-) diff --git a/legacy/eina/src/include/eina_strbuf.h b/legacy/eina/src/include/eina_strbuf.h index 8e2929bd15..ba9b7173bd 100644 --- a/legacy/eina/src/include/eina_strbuf.h +++ b/legacy/eina/src/include/eina_strbuf.h @@ -95,9 +95,9 @@ EAPI Eina_Bool eina_strbuf_append(Eina_Strbuf *buf, const char *str) EINA_ARG_NO * @param str The string to append. * @return #EINA_TRUE on success, #EINA_FALSE on failure. * - * This function appends the escaped string @p str to @p buf. If @p - * str can not be appended, #EINA_FALSE is returned, otherwise, - * #EINA_TRUE is returned. + * This function escapes and then appends the string @p str to @p buf. If @p str + * can not be appended, #EINA_FALSE is returned, otherwise, #EINA_TRUE is + * returned. */ EAPI Eina_Bool eina_strbuf_append_escaped(Eina_Strbuf *buf, const char *str) EINA_ARG_NONNULL(1, 2); @@ -111,8 +111,8 @@ EAPI Eina_Bool eina_strbuf_append_escaped(Eina_Strbuf *buf, const char *str) EIN * @return #EINA_TRUE on success, #EINA_FALSE on failure. * * This function appends at most @p maxlen characters of @p str to - * @p buf. It can't appends more than the length of @p str. It - * computes the length of @p str, so is slightly slower than + * @p buf. It can't append more than the length of @p str. It + * computes the length of @p str, so it is slightly slower than * eina_strbuf_append_length(). If the length is known beforehand, * consider using that variant (@p maxlen should then be checked so * that it is greater than the size of @p str). If @p str can not be @@ -165,6 +165,10 @@ EAPI Eina_Bool eina_strbuf_append_char(Eina_Strbuf *buf, char c) EINA_ARG_NONNUL * @param fmt The string to append. * @return #EINA_TRUE on success, #EINA_FALSE on failure. * + * This function appends the string defined by the format @p fmt to @p buf. @p + * fmt must be of a valid format for printf family of functions. If it can't + * insert it, #EINA_FALSE is returned, otherwise #EINA_TRUE is returned. + * * @see eina_strbuf_append() */ EAPI Eina_Bool eina_strbuf_append_printf(Eina_Strbuf *buf, const char *fmt, ...) EINA_ARG_NONNULL(1, 2) EINA_PRINTF(2, 3); @@ -177,7 +181,7 @@ EAPI Eina_Bool eina_strbuf_append_printf(Eina_Strbuf *buf, const char *fmt, ...) * @param args The variable arguments. * @return #EINA_TRUE on success, #EINA_FALSE on failure. * - * @see eina_strbuf_append() + * @see eina_strbuf_append_printf() */ EAPI Eina_Bool eina_strbuf_append_vprintf(Eina_Strbuf *buf, const char *fmt, va_list args) EINA_ARG_NONNULL(1, 2); @@ -206,7 +210,7 @@ EAPI Eina_Bool eina_strbuf_insert(Eina_Strbuf *buf, const char *str, size_t pos) * @param pos The position to insert the string. * @return #EINA_TRUE on success, #EINA_FALSE on failure. * - * This function inserts the escaped string @p str to @p buf at + * This function escapes and inserts the string @p str to @p buf at * position @p pos. If @p buf can't insert @p str, #EINA_FALSE is * returned, otherwise #EINA_TRUE is returned. */ @@ -221,7 +225,7 @@ EAPI Eina_Bool eina_strbuf_insert_escaped(Eina_Strbuf *buf, const char *str, siz * @param pos The position to insert the string. * @return #EINA_TRUE on success, #EINA_FALSE on failure. * - * This function inserts @p str ot @p buf at position @p pos, with at + * This function inserts @p str to @p buf at position @p pos, with at * most @p maxlen bytes. The number of inserted characters can not be * greater than the length of @p str. It computes the length of * @p str, so is slightly slower than eina_strbuf_insert_length(). If the @@ -276,6 +280,11 @@ EAPI Eina_Bool eina_strbuf_insert_char(Eina_Strbuf *buf, char c, size_t pos) EIN * @param fmt The string to insert. * @param pos The position to insert the string. * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * + * This function insert a string as described by the format @p fmt to @p buf at + * the position @p pos. @p fmt must be of a valid format for printf family of + * functions. If it can't insert it, #EINA_FALSE is returned, otherwise + * #EINA_TRUE is returned. */ EAPI Eina_Bool eina_strbuf_insert_printf(Eina_Strbuf *buf, const char *fmt, size_t pos, ...) EINA_ARG_NONNULL(1, 2) EINA_PRINTF(2, 4); @@ -287,6 +296,8 @@ EAPI Eina_Bool eina_strbuf_insert_printf(Eina_Strbuf *buf, const char *fmt, size * @param pos The position to insert the string. * @param args The variable arguments. * @return #EINA_TRUE on success, #EINA_FALSE on failure. + * + * @see eina_strbuf_insert_printf */ EAPI Eina_Bool eina_strbuf_insert_vprintf(Eina_Strbuf *buf, const char *fmt, size_t pos, va_list args) EINA_ARG_NONNULL(1, 2); @@ -298,7 +309,7 @@ EAPI Eina_Bool eina_strbuf_insert_vprintf(Eina_Strbuf *buf, const char *fmt, siz * @param str The string to prepend. * @return #EINA_TRUE on success, #EINA_FALSE on failure. * - * This macro is calling eina_strbuf_insert() at position 0.If @p buf + * This macro is calling eina_strbuf_insert() at position 0. If @p buf * can't prepend it, #EINA_FALSE is returned, otherwise #EINA_TRUE is * returned. */ @@ -417,7 +428,8 @@ EAPI Eina_Bool eina_strbuf_remove(Eina_Strbuf *buf, size_t start, size_t end) EI * This function returns the string contained in @p buf. The returned * value must not be modified and will no longer be valid if @p buf is * modified. In other words, any eina_strbuf_append() or similar will - * make that pointer invalid. + * make that pointer invalid. The pointer returned by this function must + * not be freed. * * @see eina_strbuf_string_steal() */ @@ -497,7 +509,7 @@ EAPI Eina_Bool eina_strbuf_replace(Eina_Strbuf *buf, const char *str, const char * @param with The replaceing string. * @return How often the string was replaced. * - * This function replaces all the occurrences of @p str in @ buf with + * This function replaces all the occurrences of @p str in @p buf with * the string @p with. This function returns the number of times @p str * has been replaced. On failure, it returns 0. */