On Thu, Sep 16, 2010 at 12:04 PM, Bert Huijben <[email protected]> wrote: > > >> -----Original Message----- >> From: [email protected] [mailto:[email protected]] >> Sent: donderdag 16 september 2010 10:24 >> To: [email protected] >> 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
