Re: [PATCH] Tweak doxygen markups in subversion/include/svn_client.h

On Wed, 10 May 2006, Peter N. Lundblad wrote:

> C. Michael Pilato writes:
> > Peter N. Lundblad wrote:
> > > Madan U Sreenivasan writes:
> > > >
> > > > Hi,
> > > >
> > > > Pl. find attached a patch containing tweaks to doxygen
> > > > markups. Kinda follow-up to r19589.
> > > >
> > > > [[[
> > > > Tweak doxygen markups.
> > > >
> > > > * subversion/include/svn_client.h
> > > > (svn_client_add3, svn_client_import2, svn_client_blame3,
> > > > svn_client_blame2, svn_client_export3,
> > > > svn_client_lock): Markup boolean values with @c.
> > >
> > > The problem with this is that it somewhat implies that the values must be
> > > these particular values (which is nearly always not the case for true values).
> > > I think we should go in the other direction, only talking about true
> > > and false values in lowercase and without markup. So, "if @a b is
> > > true..." implies not the exact value TRUE.
> >
> > If that's the case, then I'd suggest we use the terminology "set" and
> > "unset" (instead of "true" and "false", which might be confused with the
> > preprocessor definitions TRUE and FALSE).
> >
>
> Nah, I don't think that makes it clearer. Talking about "true values" and
> "false values", however makes sense. I think it is clear that we
> aren't talking about the "literals". But I can live with "@c TRUE and
> "@c FALSE" as well, I just think it is a minro read/writability
> issue.

I do find Mike's suggestion more clear, but also suggest "evaluates to
true" and "evaluates to false", which implies the condition without
explicitly stating that we're talking about the constants TRUE and
FALSE.

-- 
Daniel Rall