Eina: improve eina_str documentation.

SVN revision: 60757

legacy/eina/src/include/eina_str.h

@@ -55,7 +55,13 @@
 /**
  * @addtogroup Eina_String_Group String
  *
- * @brief These functions provide useful C string management.
+ * @brief Provide useful functions for C string manipulation.
+ *
+ * This group of functions allow you to more easily manipulate strings, they
+ * provide functionality not available through string.h.
+ *
+ * @warning Since these functions modify the strings they can't be used with
+ * shared strings(eina_stringshare).
  *
  * @{
  */
@@ -89,6 +95,10 @@
  * (unless @p siz is equal to 0). The returned value is the length of
  * @p src. If the returned value is greater than @p siz, truncation
  * occurred.
+ *
+ * @note The main difference between eina_strlcpy and strncpy is that this
+ * ensures @p dst is NULL terminated even if no NULL byte is found in the first
+ * @p siz bytes of src.
  */
 EAPI size_t          eina_strlcpy(char *dst, const char *src, size_t siz) EINA_ARG_NONNULL(1, 2);
 
@@ -143,8 +153,8 @@ EAPI Eina_Bool       eina_str_has_suffix(const char *str, const char *suffix) EI
  * @param ext The  extension to check for.
  * @return #EINA_TRUE if the string has the given extension, #EINA_FALSE otherwise.
  *
- * This function does the same like eina_str_has_suffix(), but with a
- * case insensitive compare.
+ * This function does the same as eina_str_has_suffix(), except it's case
+ * insensitive.
  */
 EAPI Eina_Bool       eina_str_has_extension(const char *str, const char *ext) EINA_PURE EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT;
 
@@ -166,6 +176,9 @@ EAPI Eina_Bool       eina_str_has_extension(const char *str, const char *ext) EI
  * newly allocated NULL-terminated array of strings or NULL if it fails to
  * allocate the array. To free it, free the first element of the array and the
  * array itself.
+ *
+ * @note If you need the number of elements in the returned array see
+ * eina_str_split_full().
  */
 EAPI char          **eina_str_split(const char *string, const char *delimiter, int max_tokens) EINA_ARG_NONNULL(1, 2) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
 
@@ -242,14 +255,15 @@ EAPI char           *eina_str_convert(const char *enc_from, const char *enc_to,
 
 
 /**
- * @brief Put a \ before and Space( ), \ or ' in a string.
+ * @brief Escape slashes, spaces and apostrophes in strings.
  *
  * @param str The string to escape.
  * @return The escaped string.
  *
- * This function returns a newly allocated escaped string on success,
- * @c NULL on failure. When not used anymore, the returned value must
- * be freed.
+ * Escaping is done by adding a slash "\" before any occurrence of slashes "\",
+ * spaces " " or apostrophes "'". This function returns a newly allocated
+ * escaped string on success, @c NULL on failure. When not used anymore, the
+ * returned value must be freed.
  */
 EAPI char           *eina_str_escape(const char *str) EINA_WARN_UNUSED_RESULT EINA_MALLOC EINA_ARG_NONNULL(1);