include/string.h: add comments for public APIs

Change-Id: I56488b61ff000070c430851c9627fa23c164fb18
Signed-off-by: Yanbo Zhou <yanbo.zhou@intel.com>
Reviewed-on: https://review.gerrithub.io/406924
Tested-by: SPDK Automated Test System <sys_sgsw@intel.com>
Reviewed-by: Daniel Verkamp <daniel.verkamp@intel.com>
Reviewed-by: Jim Harris <james.r.harris@intel.com>

include/spdk/string.h

@@ -47,18 +47,25 @@ extern "C" {
 /**
  * sprintf with automatic buffer allocation.
  *
- * The return value is the formatted string,
+ * The return value is the formatted string, which should be passed to free()
- * which should be passed to free() when no longer needed,
+ * when no longer needed.
- * or NULL on failure.
+ *
+ * \param format Format for the string to print.
+ *
+ * \return the formatted string on success, or NULL on failure.
  */
 char *spdk_sprintf_alloc(const char *format, ...) __attribute__((format(printf, 1, 2)));
 
 /**
  * vsprintf with automatic buffer allocation.
  *
- * The return value is the formatted string,
+ * The return value is the formatted string, which should be passed to free()
- * which should be passed to free() when no longer needed,
+ * when no longer needed.
- * or NULL on failure.
+ *
+ * \param format Format for the string to print.
+ * \param args A value that identifies a variable arguments list.
+ *
+ * \return the formatted string on success, or NULL on failure.
  */
 char *spdk_vsprintf_alloc(const char *format, va_list args);
 
@@ -66,19 +73,23 @@ char *spdk_vsprintf_alloc(const char *format, va_list args);
  * Convert string to lowercase in place.
  *
  * \param s String to convert to lowercase.
+ *
+ * \return the converted string.
  */
 char *spdk_strlwr(char *s);
 
 /**
  * Parse a delimited string with quote handling.
  *
- * \param stringp Pointer to starting location in string. *stringp will be updated to point to the
+ * Note that the string will be modified in place to add the string terminator
- * start of the next field, or NULL if the end of the string has been reached.
+ * to each field.
+ *
+ * \param stringp Pointer to starting location in string. *stringp will be updated
+ * to point to the start of the next field, or NULL if the end of the string has
+ * been reached.
  * \param delim Null-terminated string containing the list of accepted delimiters.
  *
- * \return Pointer to beginning of the current field.
+ * \return a pointer to beginning of the current field.
- *
- * Note that the string will be modified in place to add the string terminator to each field.
  */
 char *spdk_strsepq(char **stringp, const char *delim);
 
@@ -86,47 +97,52 @@ char *spdk_strsepq(char **stringp, const char *delim);
  * Trim whitespace from a string in place.
  *
  * \param s String to trim.
+ *
+ * \return the trimmed string.
  */
 char *spdk_str_trim(char *s);
 
 /**
  * Copy the string version of an error into the user supplied buffer
  *
- * \param errnum Error code
+ * \param errnum Error code.
- * \param buf Pointer to a buffer in which to place the error message
+ * \param buf Pointer to a buffer in which to place the error message.
- * \param buflen the size of the buffer in bytes
+ * \param buflen The size of the buffer in bytes.
  */
 void spdk_strerror_r(int errnum, char *buf, size_t buflen);
 
 /**
- * Return the string version of an error from a static, thread-local buffer.
+ * Return the string version of an error from a static, thread-local buffer. This
- * This function is thread safe.
+ * function is thread safe.
  *
- * \param errnum Error code
+ * \param errnum Error code.
  *
- * \return pointer to buffer upon success.
+ * \return a pointer to buffer upon success.
  */
 const char *spdk_strerror(int errnum);
 
 /**
  * Remove trailing newlines from the end of a string in place.
  *
- * Any sequence of trailing \r and \n characters is removed from the end of the string.
+ * Any sequence of trailing \r and \n characters is removed from the end of the
+ * string.
  *
  * \param s String to remove newline from.
- * \return Number of characters removed.
+ *
+ * \return the number of characters removed.
  */
 size_t spdk_str_chomp(char *s);
 
 /**
- * Copy a string into a fixed-size buffer, padding extra bytes with a specific character.
+ * Copy a string into a fixed-size buffer, padding extra bytes with a specific
+ * character.
+ *
+ * If src is longer than size, only size bytes will be copied.
  *
  * \param dst Pointer to destination fixed-size buffer to fill.
  * \param src Pointer to source null-terminated string to copy into dst.
  * \param size Number of bytes to fill in dst.
  * \param pad Character to pad extra space in dst beyond the size of src.
- *
- * If src is longer than size, only size bytes will be copied.
  */
 void spdk_strcpy_pad(void *dst, const char *src, size_t size, int pad);
 
@@ -137,37 +153,39 @@ void spdk_strcpy_pad(void *dst, const char *src, size_t size, int pad);
  * \param size Size of the full string pointed to by str, including padding.
  * \param pad Character that was used to pad str up to size.
  *
- * \return Length of the non-padded portion of str.
+ * \return the length of the non-padded portion of str.
  */
 size_t spdk_strlen_pad(const void *str, size_t size, int pad);
 
 /**
- * Parse an IP address into its hostname and port components.
+ * Parse an IP address into its hostname and port components. This modifies the
- * This modifies the IP address in place.
+ * IP address in place.
  *
- * \param ip A null terminated IP address, including port.
+ * \param ip A null terminated IP address, including port. Both IPv4 and IPv6
- *           Both IPv4 and IPv6 are supported.
+ * are supported.
- * \param host Will point to the start of the hostname within ip.
+ * \param host Will point to the start of the hostname within ip. The string will
- *             The string will be null terminated.
+ * be null terminated.
- * \param port Will point to the start of the port within ip.
+ * \param port Will point to the start of the port within ip. The string will be
- *             The string will be null terminated.
+ * null terminated.
  *
- * \return 0 if successful. -1 on error.
+ * \return 0 on success. -1 on failure.
  */
 int spdk_parse_ip_addr(char *ip, char **host, char **port);
 
 /**
  * Parse a string representing a number possibly followed by a binary prefix.
+ *
  * The string can contain a trailing "B" (KB,MB,GB) but it's not necessary.
  * "128K" = 128 * 1024; "2G" = 2 * 1024 * 1024; "2GB" = 2 * 1024 * 1024;
  * Additionally, lowercase "k", "m", "g" are parsed as well. They are processed
  * the same as their uppercase equivalents.
  *
- * \param cap_str null terminated string
+ * \param cap_str Null terminated string.
- * \param cap pointer where the parsed capacity (in bytes) will be put
+ * \param cap Pointer where the parsed capacity (in bytes) will be put.
- * \param has_prefix pointer to a flag that will be set to describe whether given
+ * \param has_prefix Pointer to a flag that will be set to describe whether given
- * string contains a binary prefix
+ * string contains a binary prefix.
- * \returned 0 on success, negative errno otherwise
+ *
+ * \return 0 on success, or negative errno on failure.
  */
 int spdk_parse_capacity(const char *cap_str, uint64_t *cap, bool *has_prefix);
 
@@ -176,7 +194,9 @@ int spdk_parse_capacity(const char *cap_str, uint64_t *cap, bool *has_prefix);
  *
  * \param data Buffer to check.
  * \param size Size of data in bytes.
- * \return true if data consists entirely of zeroes, or false if any byte in data is not zero.
+ *
+ * \return true if data consists entirely of zeroes, or false if any byte in data
+ * is not zero.
  */
 bool spdk_mem_all_zero(const void *data, size_t size);