summaryrefslogtreecommitdiff
path: root/src/lib/eina
diff options
context:
space:
mode:
authorBryce Harrington <bryce@osg.samsung.com>2018-07-04 11:12:57 +0900
committerHermet Park <hermetpark@gmail.com>2018-07-04 11:12:57 +0900
commitcc345edccd19ac1e4b9f74743d42bbf5b83dde0c (patch)
tree4237512b3a343519f93c4902dce7c4f7658cdeff /src/lib/eina
parentb0e0fcf3d60eac53229ce107b01c6d31ce8aa817 (diff)
eina: Improve eina_binbuf function documentation
Summary: Define return values as part of @return. Cleanup grammar. Reviewers: devilhorns Subscribers: cedric, #committers, zmike Tags: #efl Differential Revision: https://phab.enlightenment.org/D6503
Diffstat (limited to 'src/lib/eina')
-rw-r--r--src/lib/eina/eina_binbuf.h95
1 files changed, 44 insertions, 51 deletions
diff --git a/src/lib/eina/eina_binbuf.h b/src/lib/eina/eina_binbuf.h
index cea0c93f38..27da52351a 100644
--- a/src/lib/eina/eina_binbuf.h
+++ b/src/lib/eina/eina_binbuf.h
@@ -37,10 +37,10 @@ typedef struct _Eina_Strbuf Eina_Binbuf;
37/** 37/**
38 * @brief Creates a new string buffer. 38 * @brief Creates a new string buffer.
39 * 39 *
40 * @return Newly allocated string buffer instance. 40 * @return Newly allocated string buffer instance, or @c NULL on error.
41 * 41 *
42 * This function creates a new string buffer. On error, @c NULL is 42 * This function creates a new string buffer. To free the resources, use
43 * returned. To free the resources, use eina_binbuf_free(). 43 * eina_binbuf_free().
44 * 44 *
45 * @see eina_binbuf_free() 45 * @see eina_binbuf_free()
46 * @see eina_binbuf_append() 46 * @see eina_binbuf_append()
@@ -55,10 +55,10 @@ EAPI Eina_Binbuf *eina_binbuf_new(void) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
55 * 55 *
56 * @param str The string to manage. 56 * @param str The string to manage.
57 * @param length The length of the string. 57 * @param length The length of the string.
58 * @return Newly allocated string buffer instance. 58 * @return Newly allocated string buffer instance, or @c NULL on error.
59 * 59 *
60 * This function creates a new string buffer. On error, @c NULL is 60 * This function creates a new string buffer. To free the resources, use
61 * returned. To free the resources, use eina_binbuf_free(). 61 * eina_binbuf_free().
62 * 62 *
63 * @see eina_binbuf_manage_new() 63 * @see eina_binbuf_manage_new()
64 * @since 1.2.0 64 * @since 1.2.0
@@ -73,14 +73,13 @@ EAPI Eina_Binbuf *eina_binbuf_manage_new_length(unsigned char *str, size_t lengt
73 * @param str The string to start from. 73 * @param str The string to start from.
74 * @param length The length of the string. 74 * @param length The length of the string.
75 * @param ro The passed string will not be touched if set to EINA_TRUE. 75 * @param ro The passed string will not be touched if set to EINA_TRUE.
76 * @return Newly allocated string buffer instance. 76 * @return Newly allocated string buffer instance, or @c NULL on error.
77 * 77 *
78 * This function creates a new string buffer. On error, @c NULL is 78 * This function creates a new string buffer. To free the resources, use
79 * returned. To free the resources, use eina_binbuf_free(). It will 79 * eina_binbuf_free(). It will not touch the buffer if ro is set to @c
80 * not touch the buffer if ro is set to @c EINA_TRUE, but it will also not 80 * EINA_TRUE, but it will also not copy it. If ro is set to @c EINA_TRUE
81 * copy it. If ro is set to @c EINA_TRUE any change operation will 81 * any change operation will create a fresh new memory, copy old data
82 * create a fresh new memory, copy old data there and starting modifying 82 * there and starting modifying that one.
83 * that one.
84 * 83 *
85 * @see eina_binbuf_manage_new() 84 * @see eina_binbuf_manage_new()
86 * @see eina_binbuf_manage_new_length() 85 * @see eina_binbuf_manage_new_length()
@@ -97,13 +96,12 @@ EAPI Eina_Binbuf *eina_binbuf_manage_new(const unsigned char *str, size_t length
97 * 96 *
98 * @param str The string to start from. 97 * @param str The string to start from.
99 * @param length The length of the string. 98 * @param length The length of the string.
100 * @return Newly allocated string buffer instance. 99 * @return Newly allocated string buffer instance, or @c NULL on error.
101 * 100 *
102 * This function creates a new string buffer. On error, @c NULL is 101 * This function creates a new string buffer. To free the resources, use
103 * returned. To free the resources, use eina_binbuf_free(). It will 102 * eina_binbuf_free(). It will not touch the internal buffer. Any
104 * not touch the internal buffer. Any changing operation will 103 * changing operation will create a fresh new memory, copy old data
105 * create a fresh new memory, copy old data there and starting modifying 104 * there and starting modifying that one.
106 * that one.
107 * 105 *
108 * @see eina_binbuf_manage_new() 106 * @see eina_binbuf_manage_new()
109 * @since 1.9.0 107 * @since 1.9.0
@@ -188,14 +186,13 @@ EAPI Eina_Bool eina_binbuf_use(Eina_Binbuf *buf, size_t extra_bytes) EINA_ARG_NO
188 * @param buf The string buffer to append to. 186 * @param buf The string buffer to append to.
189 * @param str The string to append. 187 * @param str The string to append.
190 * @param length The exact length to use. 188 * @param length The exact length to use.
191 * @return #EINA_TRUE on success, #EINA_FALSE on failure. 189 * @return #EINA_TRUE on success, #EINA_FALSE on failure such as if @p
190 * buf can't be appended.
192 * 191 *
193 * This function appends @p str to @p buf. @p str must be of size at 192 * This function appends @p str to @p buf. @p str must be of size at
194 * most @p length. It is slightly faster than eina_binbuf_append() as 193 * most @p length. It is slightly faster than eina_binbuf_append() as
195 * it does not compute the size of @p str. It is useful when dealing 194 * it does not compute the size of @p str. It is useful when dealing
196 * with strings of known size, such as eina_stringshare. If @p buf 195 * with strings of known size, such as eina_stringshare.
197 * can't append it, #EINA_FALSE is returned, otherwise #EINA_TRUE is
198 * returned.
199 * 196 *
200 * @see eina_stringshare_length() 197 * @see eina_stringshare_length()
201 * @see eina_binbuf_append() 198 * @see eina_binbuf_append()
@@ -208,10 +205,10 @@ EAPI Eina_Bool eina_binbuf_append_length(Eina_Binbuf *buf, const unsigned char *
208 * 205 *
209 * @param buf The string buffer to append to. 206 * @param buf The string buffer to append to.
210 * @param slice The slice to append. 207 * @param slice The slice to append.
211 * @return #EINA_TRUE on success, #EINA_FALSE on failure. 208 * @return #EINA_TRUE on success, #EINA_FALSE on failure such as if
209 * @p buf can't be appended.
212 * 210 *
213 * This function appends @p slice to @p buf. If @p buf can't append 211 * This function appends @p slice to @p buf.
214 * it, #EINA_FALSE is returned, otherwise #EINA_TRUE is returned.
215 * 212 *
216 * @since 1.19 213 * @since 1.19
217 */ 214 */
@@ -222,12 +219,12 @@ EAPI Eina_Bool eina_binbuf_append_slice(Eina_Binbuf *buf, const Eina_Slice slice
222 * 219 *
223 * @param buf The string buffer to append to. 220 * @param buf The string buffer to append to.
224 * @param data The string buffer to append. 221 * @param data The string buffer to append.
225 * @return #EINA_TRUE on success, #EINA_FALSE on failure. 222 * @return #EINA_TRUE on success, #EINA_FALSE on failure such as if @p
223 * buf can't be appended.
226 * 224 *
227 * This function appends @p data to @p buf. @p data must be allocated and 225 * This function appends @p data to @p buf. @p data must be allocated and
228 * different from @c NULL. It is slightly faster than eina_binbuf_append() as 226 * different from @c NULL. It is slightly faster than eina_binbuf_append() as
229 * it does not compute the size of @p str. If @p buf can't append it, 227 * it does not compute the size of @p str.
230 * #EINA_FALSE is returned, otherwise #EINA_TRUE is returned.
231 * 228 *
232 * @see eina_binbuf_append() 229 * @see eina_binbuf_append()
233 * @see eina_binbuf_append_n() 230 * @see eina_binbuf_append_n()
@@ -242,10 +239,9 @@ EAPI Eina_Bool eina_binbuf_append_buffer(Eina_Binbuf *buf, const Eina_Binbuf *da
242 * 239 *
243 * @param buf The string buffer to append to. 240 * @param buf The string buffer to append to.
244 * @param c The char to append. 241 * @param c The char to append.
245 * @return #EINA_TRUE on success, #EINA_FALSE on failure. 242 * @return #EINA_TRUE on success, #EINA_FALSE if @pc could not be inserted.
246 * 243 *
247 * This function inserts @p c to @p buf. If it can not insert it, #EINA_FALSE 244 * This function inserts @p c to @p buf.
248 * is returned, otherwise #EINA_TRUE is returned.
249 */ 245 */
250EAPI Eina_Bool eina_binbuf_append_char(Eina_Binbuf *buf, unsigned char c) EINA_ARG_NONNULL(1); 246EAPI Eina_Bool eina_binbuf_append_char(Eina_Binbuf *buf, unsigned char c) EINA_ARG_NONNULL(1);
251 247
@@ -256,14 +252,12 @@ EAPI Eina_Bool eina_binbuf_append_char(Eina_Binbuf *buf, unsigned char c) EINA_A
256 * @param str The string to insert. 252 * @param str The string to insert.
257 * @param length The exact length to use. 253 * @param length The exact length to use.
258 * @param pos The position to insert the string. 254 * @param pos The position to insert the string.
259 * @return #EINA_TRUE on success, #EINA_FALSE on failure. 255 * @return #EINA_TRUE on success, #EINA_FALSE if @p str could not be inserted.
260 * 256 *
261 * This function inserts @p str to @p buf. @p str must be of size at 257 * This function inserts @p str to @p buf. @p str must be of size at
262 * most @p length. It is slightly faster than eina_binbuf_insert() as 258 * most @p length. It is slightly faster than eina_binbuf_insert() as
263 * it does not compute the size of @p str. It is useful when dealing 259 * it does not compute the size of @p str. It is useful when dealing
264 * with strings of known size, such as eina_stringshare. If @p buf 260 * with strings of known size, such as eina_stringshare.
265 * can't insert it, #EINA_FALSE is returned, otherwise #EINA_TRUE is
266 * returned.
267 * 261 *
268 * @see eina_stringshare_length() 262 * @see eina_stringshare_length()
269 * @see eina_binbuf_insert() 263 * @see eina_binbuf_insert()
@@ -277,11 +271,9 @@ EAPI Eina_Bool eina_binbuf_insert_length(Eina_Binbuf *buf, const unsigned char *
277 * @param buf The string buffer to insert to. 271 * @param buf The string buffer to insert to.
278 * @param slice The slice to insert. 272 * @param slice The slice to insert.
279 * @param pos The position to insert the string. 273 * @param pos The position to insert the string.
280 * @return #EINA_TRUE on success, #EINA_FALSE on failure. 274 * @return #EINA_TRUE on success, #EINA_FALSE if @p slice could not be inserted.
281 * 275 *
282 * This function inserts @p slice to @p buf at position @p pos. If @p 276 * This function inserts @p slice to @p buf at position @p pos.
283 * buf can't insert it, #EINA_FALSE is returned, otherwise #EINA_TRUE
284 * is returned.
285 * 277 *
286 * @since 1.19.0 278 * @since 1.19.0
287 */ 279 */
@@ -294,11 +286,9 @@ EAPI Eina_Bool eina_binbuf_insert_slice(Eina_Binbuf *buf, const Eina_Slice slice
294 * @param buf The string buffer to insert to. 286 * @param buf The string buffer to insert to.
295 * @param c The char to insert. 287 * @param c The char to insert.
296 * @param pos The position to insert the char. 288 * @param pos The position to insert the char.
297 * @return #EINA_TRUE on success, #EINA_FALSE on failure. 289 * @return #EINA_TRUE on success, #EINA_FALSE if @p c could not be inserted.
298 * 290 *
299 * This function inserts @p c to @p buf at position @p pos. If @p buf 291 * This function inserts @p c to @p buf at position @p pos.
300 * can't append it, #EINA_FALSE is returned, otherwise #EINA_TRUE is
301 * returned.
302 */ 292 */
303EAPI Eina_Bool eina_binbuf_insert_char(Eina_Binbuf *buf, unsigned char c, size_t pos) EINA_ARG_NONNULL(1); 293EAPI Eina_Bool eina_binbuf_insert_char(Eina_Binbuf *buf, unsigned char c, size_t pos) EINA_ARG_NONNULL(1);
304 294
@@ -314,7 +304,7 @@ EAPI Eina_Bool eina_binbuf_insert_char(Eina_Binbuf *buf, unsigned char c, size_t
314 * 304 *
315 * This function removes a slice of @p buf, starting at @p start 305 * This function removes a slice of @p buf, starting at @p start
316 * (inclusive) and ending at @p end (non-inclusive). Both values are 306 * (inclusive) and ending at @p end (non-inclusive). Both values are
317 * in bytes. It returns #EINA_FALSE on failure, #EINA_TRUE otherwise. 307 * in bytes.
318 */ 308 */
319 309
320EAPI Eina_Bool eina_binbuf_remove(Eina_Binbuf *buf, size_t start, size_t end) EINA_ARG_NONNULL(1); 310EAPI Eina_Bool eina_binbuf_remove(Eina_Binbuf *buf, size_t start, size_t end) EINA_ARG_NONNULL(1);
@@ -323,12 +313,12 @@ EAPI Eina_Bool eina_binbuf_remove(Eina_Binbuf *buf, size_t start, size_t end) EI
323 * @brief Retrieves a pointer to the contents of a string buffer. 313 * @brief Retrieves a pointer to the contents of a string buffer.
324 * 314 *
325 * @param buf The string buffer. 315 * @param buf The string buffer.
326 * @return The current string in the string buffer. 316 * @return The string that is contained in @p buf.
327 * 317 *
328 * This function returns the string contained in @p buf. The returned 318 * This function returns the string contained in @p buf. The returned
329 * value must not be modified and will no longer be valid if @p buf is 319 * value must not be modified and will no longer be valid if @p buf is
330 * modified. In other words, any eina_binbuf_append() or similar will 320 * modified. In other words, any eina_binbuf_append() or similar will
331 * make that pointer invalid. 321 * make the pointer invalid.
332 * 322 *
333 * @see eina_binbuf_string_steal() 323 * @see eina_binbuf_string_steal()
334 */ 324 */
@@ -337,8 +327,8 @@ EAPI const unsigned char *eina_binbuf_string_get(const Eina_Binbuf *buf) EINA_AR
337/** 327/**
338 * @brief Steals the contents of a string buffer. 328 * @brief Steals the contents of a string buffer.
339 * 329 *
340 * @param buf The string buffer to steal. 330 * @param buf The string buffer.
341 * @return The current string in the string buffer. 331 * @return The string that was contained in @p buf.
342 * 332 *
343 * This function returns the string contained in @p buf. @p buf is 333 * This function returns the string contained in @p buf. @p buf is
344 * then initialized and does not own the returned string anymore. The 334 * then initialized and does not own the returned string anymore. The
@@ -393,12 +383,15 @@ EAPI Eina_Slice eina_binbuf_slice_get(const Eina_Binbuf *buf) EINA_WARN_UNUSED_R
393 * @since 1.19 383 * @since 1.19
394 */ 384 */
395EAPI Eina_Rw_Slice eina_binbuf_rw_slice_get(const Eina_Binbuf *buf) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); 385EAPI Eina_Rw_Slice eina_binbuf_rw_slice_get(const Eina_Binbuf *buf) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
386
396/** 387/**
397 * @brief Gets the content of the buffer and free the buffer. 388 * @brief Gets the content of the buffer and frees the buffer.
398 * 389 *
399 * @param buf the buffer to get the content from and which will be freed 390 * @param buf the buffer to get the content from and which will be freed
400 * 391 *
401 * @return The content contained by buf. The caller must release the memory of the returned content by calling 392 * @return The content contained by buf.
393 *
394 * The caller must release the memory of the returned content by calling
402 * free(). 395 * free().
403 * 396 *
404 * @since 1.19 397 * @since 1.19