string.c: Improve documentation of create_argv().
authorAndre Noll <maan@tuebingen.mpg.de>
Sun, 24 Jul 2016 09:32:43 +0000 (11:32 +0200)
committerAndre Noll <maan@tuebingen.mpg.de>
Sun, 7 Aug 2016 12:03:44 +0000 (14:03 +0200)
Mention that it is OK to pass NULL, and that the returned array is
NULL terminated.

string.c

index 86e7753..6033a00 100644 (file)
--- a/string.c
+++ b/string.c
@@ -803,15 +803,18 @@ err:
  * Split a buffer into words.
  *
  * This parser honors single and double quotes, backslash-escaped characters
- * and special characters like \p \\n. The result contains pointers to copies
- * of the words contained in \a buf and has to be freed by using \ref
- * free_argv().
+ * and special characters like \\n. The result contains pointers to copies of
+ * the words contained in buf and has to be freed by using \ref free_argv().
  *
  * \param buf The buffer to be split.
  * \param delim Each character in this string is treated as a separator.
  * \param result The array of words is returned here.
  *
- * \return Number of words in \a buf, negative on errors.
+ * It's OK to pass NULL as the buffer argument. This is equivalent to passing
+ * the empty string.
+ *
+ * \return Number of words in buf, negative on errors. The array returned
+ * through the result pointer is NULL terminated.
  */
 int create_argv(const char *buf, const char *delim, char ***result)
 {