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

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).

> 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.

Regards,
Malcolm

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Fri Mar 10 15:58:50 2006