Branko Čibej wrote on Tue, 05 Sep 2017 15:56 +0200:
> On 05.09.2017 15:45, Daniel Shahaf wrote:
> > brane_at_apache.org 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
Received on 2017-09-05 16:06:09 CEST