[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

Re: svn commit: r1803143 - in /subversion/trunk/subversion: include/ libsvn_delta/ libsvn_ra_serf/ mod_dav_svn/

From: Daniel Shahaf <d.s_at_daniel.shahaf.name>
Date: Tue, 05 Sep 2017 17:45:57 +0000

> > - * @note Don't try to allocate one of these yourself. Instead, always
> > - * use svn_delta_default_editor() or some other constructor, to ensure
> > - * that unused slots are filled in with no-op functions.
> > + * @note Fields may be added to the end of this structure in future
> > + * versions. Therefore, users shouldn't allocate structures of this
> > + * type, to preserve binary compatibility.
> > + *
> > + * @note It is recommended to use svn_delta_default_editor() or some other
> > + * constructor, to ensure that unused slots are filled in with no-op functions.
>
> --- subversion/include/svn_delta.h (revision 1806549)
> +++ subversion/include/svn_delta.h (working copy)
> @@ -694,8 +694,10 @@ svn_txdelta_skip_svndiff_window(apr_file_t *file,
> * as it produces the delta.
> *
> * @note Don't try to allocate one of these yourself. Instead, always
> - * use svn_delta_default_editor() or some other constructor, to ensure
> - * that unused slots are filled in with no-op functions.
> + * use svn_delta_default_editor() or some other constructor, to avoid
> + * backwards compatibility problems if the structure is extended in
> + * future releases and to ensure that unused slots are filled in with
> + * no-op functions.

+1, but note that the "shouldn't" language in current HEAD, which this
patch [once rebased to HEAD] will remove, was copied from some other
docstring. I made no note of which one specifically, because I think
that "shouldn't" language is our standard formula for docstrings of
non-opaque struct types.

Let's also backport this docs patch to 1.9.8. (As a docs patch it needs
just one vote)

Cheers,

Daniel

P.S. I still think a release notes entry would be warranted, but not
strongly enough to reopen that angle.
Received on 2017-09-05 19:46:04 CEST

This is an archived mail posted to the Subversion Dev mailing list.