Branko Čibej wrote on Tue, 05 Sep 2017 15:56 +0200: > On 05.09.2017 15:45, Daniel Shahaf wrote: > > [email protected] wrote on Tue, 05 Sep 2017 07:45 +0000: > >> Author: brane > >> Date: Tue Sep 5 07:45:49 2017 > >> New Revision: 1807319 > >> > >> URL: http://svn.apache.org/viewvc?rev=1807319&view=rev > >> Log: > >> Introduce the concept of a target format for working copy upgrades > >> into the client library. > >> +++ subversion/branches/better-pristines/subversion/include/svn_client.h > >> Tue Sep 5 07:45:49 2017 > >> @@ -4201,13 +4201,34 @@ svn_client_cleanup(const char *dir, > >> * @{ > >> */ > >> > >> -/** Recursively upgrade a working copy from any older format to the > >> current > >> - * WC metadata storage format. @a wcroot_dir is the path to the WC root. > >> +/** > >> + * Recursively upgrade a working copy from any older format to the > >> + * given WC metadata storage format. @a wcroot_dir is the path to the > >> + * WC root. > >> + * > > Suggest to clarify that "Recursively" means into nested working copies > > (externals), not into subdirs. > > Ack. Note that this is just a slightly modified copy of the original > docstring. >
Haven't noticed this, but the point is valid anyway :-). > >> + * @a wc_format_version is version number of the Subversion client > >> + * that supports a given WC metadata format; @c NULL means the newest > >> + * supported format. Any other value must be a string representing a > >> + * version number, e.g., "1.8" or "1.9.3". The earliest supported > >> + * version is defined by #SVN_VERSION_SUPPORTED_WC_FORMAT. > >> * > > When might 1.A.3 and 1.A.4 have different formats? > > They might not. However, there's no reason to forbid putting the patch > version in here. The format of this parameter is analogous to the value > of the --compatible-version option to svnadmin. Also, using SVN_VERSION > here should be valid. I intend the parser to just extract the first two > dot-separated integers and ignore everything else; there's no reason to > be too strict. > +1; that's exactly what I was thinking, too. > >> * Use @a scratch_pool for any temporary allocations. > >> * > >> + * @since New in 1.10. > >> + */ > >> +svn_error_t * > >> +svn_client_upgrade2(const char *wcroot_dir, > >> + const char* wc_format_version, > >> + svn_client_ctx_t *ctx, > >> + apr_pool_t *scratch_pool); > >> + > >> +/** > >> + * Like svn_client_upgrade2(), but always upgrades to the newest > >> + * supported format. > >> + * > >> - * @since New in 1.7. > >> + * @deprecated Provided for backward compatibility with the 1.7 API. > > Why drop @since? We don't usually remove @since tags when deprecating. > > (Both here and in svn_wc_upgrade()) > > Yes we do. I looked around and didn't find @since and @deprecated used > together. Counter-examples: svn_cmdline_prompt_baton_t, svn_cmdline_create_auth_baton(), svn_txdelta_to_svndiff2(). Functions that have @deprecated but not @since are, the way we've usually managed deprecations, supposed to be functions that were present in 1.0. (Example: svn_txdelta_to_svndiff()) > The deprecation reason gives the original API version anyway. > This is just a coincidence. We could very well have "@since New in 1.1" together with "@deprecated ... for ... the 1.9 API." if we deprecate some old function. Cheers, Daniel
