[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

Re: [PATCH] Doxygen documentation change for svn_cstring_split() in svn_string.h

From: Daniel Shahaf <danielsh_at_elego.de>
Date: Sat, 27 Apr 2013 23:26:24 +0300

Gabriela Gibson wrote on Sat, Apr 27, 2013 at 21:05:51 +0100:
> Danielsh suggested on IRC that I clarify the API documentation for the
> function svn_cstring_split().
>
> [[[
>
> Clarify the doxygen documentation for the semantics of the @a sep_chars
> parameter.
>
> * subversion/include/svn_string.h
> (svn_cstring_split): Update doxygen comment.
>
> Suggested by: Danielsh

My name is "danielsh" :-)

> ]]]

> Index: subversion/include/svn_string.h
> ===================================================================
> --- subversion/include/svn_string.h (revision 1471133)
> +++ subversion/include/svn_string.h (working copy)
> @@ -407,15 +407,17 @@ svn_string_compare_stringbuf(const svn_string_t *s
> * @{
> */
>
> -/** Divide @a input into substrings along @a sep_chars boundaries, return an
> - * array of copies of those substrings (plain const char*), allocating both
> - * the array and the copies in @a pool.
> +/** Divide @a input into substrings, interpreting any char from @a sep
> + * as a token separator.
> *
> + * Return an array of copies of those substrings (plain const char*),
> + * allocating both the array and the copies in @a pool.
> *

+1 to commit. That said, I note that...

> - * None of the elements added to the array contain any of the
> - * characters in @a sep_chars, and none of the new elements are empty
> - * (thus, it is possible that the returned array will have length
> - * zero).
> + * Because none of the elements added to the resulting array contain
> + * any of the characters in @a sep_chars, and none of the new elements
> + * are empty, it is possible that the returned array will have length
> + * zero.

.. I personally prefer the original form of this paragraph, because it
doesn't hide the new info ("no empty elements") in a clause.

Thanks

Daniel

> + *
> * If @a chop_whitespace is TRUE, then remove leading and trailing
> * whitespace from the returned strings.
> */
Received on 2013-04-27 22:27:00 CEST

This is an archived mail posted to the Subversion Dev mailing list.