On 07/04/2007 6.57, David James wrote:
>> > Should we write some code to edit lower-level API functions and
>> > upgrade them so that they throw exceptions instead of returning error
>> > codes? I think that this is a good idea, as long as this difference is
>> > carefully documented.
>>
>> Of course. IMO, it is fine for the lower layer to provide an API which is
>> slightly modified from the C API, as long as the modifications are
>> general and
>> automatic, and thus can be remembered by users without having to look
>> at a
>> reference guide. Basically, you want your modifications *not* to
>> require a
>> specific Python reference documentation: the C reference documentation
>> ought
>> to be enough. Thus, the rules must be simple and general. For instance:
>>
>> - All functions returning an error through a svn_error_t
>> automatically raise
>> a SubversionException() instead.
>> - All functions returning multiple return values through the usual
>> C-language "pattern" of passing pointers to variables are modified to
>> return
>> tuples of values instead.
>>
>> These are good general rules which are easy to remember and can be
>> unconditionally applied to all functions. When somebody has read them
>> in the
>> documentation, she can go ahead and use the API just by looking at the C
>> reference.
>
> I like the first rule, because it's simple, but I don't think the
> second rule is as simple as it looks. It's not easy for users (or for
> us) to figure out which parameters are output parameters.
After having read your rationale and looked at your example
(svn_stream_checksummed) I agree with you. Thanks!
--
Giovanni Bajo
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Tue Apr 10 13:14:44 2007