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

Re: [PATCH] [DOCFIX] Fix ambiguous comments for svn_string_isempty()

From: Julian Foad <julianfoad_at_btopenworld.com>
Date: 2006-03-13 02:15:11 CET

Malcolm Rowe wrote:
> On Fri, Mar 10, 2006 at 02:36:05PM +0000, Julian Foad wrote:
>
>>We should change "@c TRUE" to "true" in our API documentation, for both
>>inputs and outputs, both because it avoids assumptions about what exact
>>value is used and whether it should be relied upon, and because it is
>>neater and less distracting to read. May I?
>
> +1 for outputs, -0 for inputs. ("Pass @c TRUE to.." might be easier
> to read than "Pass a true value to..", and "Pass true to.." may be
> considered ambiguous).

I don't necessarily agree about inputs - the wording is often "If @a recurse is
true then ...". I'll leave it for now.

>>It would also be good if we documented somewhere (probably at the
>>definition of svn_boolean_t) that "true" has the meanings I described
>>above. Perhaps:
>>
>>-/** YABT: Yet Another Boolean Type */
>>+/** Our own Boolean type. To provide a value, use TRUE or FALSE if an
>>+ * explicit value is needed, else the non-zero or zero result of an
>>+ * expression. Use the value in an implicit test for truth such as
>>+ * "(... && b)" or "if (! b)", not a comparison such as "(b == TRUE)". */
>> typedef int svn_boolean_t;
>
> That's standard C, isn't it? I'm not sure that might not make things
> more confusing.

Yes, it's pretty much standard, but it does codify some assumptions that not
all programmers make (or have thought about). For instance, I do come across
"= 1" frequently and "== TRUE" from time to time. But I agree that writing
this here without further explanation may just be confusing, so I won't do it.

- Julian

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Mon Mar 13 02:15:28 2006

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

This site is subject to the Apache Privacy Policy and the Apache Public Forum Archive Policy.