> > - * @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.
