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