Re: [PATCH]: notification progress improvement/fixes (issue #901)

David Anderson wrote:

> Peter N. Lundblad wrote:
>
>> Not all of our API users know our revving policy. I think it is a bit
>> nice
>> to be a little verbose here and give the reason. But if you change
>> it, it
>> should be changed everywhere.
>
>
> API Users need not know about the revving policies in such detail.
> They simply need to know that they have to go through the constructor.

This is exactly my point. In my experience, telling people more than is
necessary will only confuse them. :)

> Perhaps the implementation of the constructor could have a comment to
> the effect of recalling the revving policy, but I'm not sure that
> documenting it in the public API would bring anything but extra clutter.

Our compatibility rules and API revving rules are already documented.
Sowing extra comments all over the docstrings isn't only effor
duplication, it's also a maintenance nightmare. What if we change our
compatibility policy come 2.0 (we can)?

-- Brane

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Wed Aug 31 21:06:10 2005