On Thu, Sep 16, 2010 at 12:04 PM, Bert Huijben <bert_at_qqmail.nl> wrote:
>
>
>> -----Original Message-----
>> From: hwright_at_apache.org [mailto:hwright_at_apache.org]
>> Sent: donderdag 16 september 2010 10:24
>> To: commits_at_subversion.apache.org
>> Subject: svn commit: r997639 -
>> /subversion/trunk/subversion/include/svn_client.h
>>
>> Author: hwright
>> Date: Thu Sep 16 08:23:54 2010
>> New Revision: 997639
>>
>
>
>> + * than a directory; <br>
>> + * #SVN_ERR_RA_ILLEGAL_URL if @a URL does not exist; <br>
>> + * #SVN_ERR_CLIENT_BAD_REVISION if @a revision is not one of
>> + * #svn_opt_revision_number, #svn_opt_revision_head, or
>> + * #svn_opt_revision_date; <br>
>> + * #SVN_NO_ERROR otherwise.
>
> And after reading this as just an API user, how would you expect authorization, network, filesystem and/or other errors to be reported?
>
> The old documentation documented a few specific errors and left the rest open. This new documentation would tell me that we never report other errors then this short (incomplete) list, while just checking out over an existing working copy from a different repository will give an error that is not in this list.
>
> And this function returns an svn_error_t* which (when not NULL) can contain those error codes, or can be NULL/SVN_NO_ERROR. SVN_NO_ERROR and the specific error codes should not be in the same list without some separation.
All good points. Are you suggesting that the newer format is worse
than, or simply maintains the status quo from the older format? The
user would have been equally surprised with the prior docstring, or
maybe this just highlights how poorly we do at documenting potential
error conditions.
What would you suggest to improve this documentation? (And of course,
feel free to edit it directly.)
-Hyrum
Received on 2010-09-16 12:22:13 CEST