On Thu, 2010-03-18, Greg Stein wrote:
> On Thu, Mar 18, 2010 at 07:34, <julianfoad_at_apache.org> wrote:
> > Author: julianfoad
> > Date: Thu Mar 18 11:34:45 2010
> > New Revision: 924722
> >
> > URL: http://svn.apache.org/viewvc?rev=924722&view=rev
> > Log:
> > Clean up two revved WC API function signatures: move the wc_ctx parameter
> > before the first of the main input parameters, to keep those together and
> > to minimize the difference from the previous version. Do some doc string
> > clean-ups too.
> >
> > * subversion/include/svn_wc.h
> > (svn_wc_get_status_editor5): Fix a parameter name typo. Note doc string
> > out-of-dateness.
> > (svn_wc_crawl_revisions5): Note doc string out-of-dateness.
> > (svn_wc_get_update_editor4): Swap revision and wc_ctx parameters.
> > (svn_wc_get_switch_editor4): Swap revision and wc_ctx parameters. Refer to
> > svn_wc_get_update_editor4's doc string for most parameters to make it
> > easy for the reader to see that there are no differences.
>
> Why swap these parameters? REVISION (or TARGET_REVISION) is an OUT
> parameter. We always place OUT parameters first, and then the WC_CTX,
> then the other params.
Bert discussed this with me on IRC too. My log message said why, but
actually there's more to it. I hadn't been able to discern a reason why
the rev-number param was moved away (relative to the previous version of
the API) from the other target parameters in the first place. After
this commit, Bert said he'd done it for the reason you state - output
params come before input params. But this parameter isn't an output
from this function, at least not in the usual sense. It's an address
given to this function, an address for this function to store away but
definitely not to read from or write to. A different function will
later retrieve that address and write a revision number to it.
In that sense, the pointer is an input to this function, whereas in
another sense we could call it an "output pointer" meaning it's a
pointer that will only ever be written through (not read from), but it
is neither a classical "input pointer parameter" nor a classical "output
pointer parameter" for this function. Indeed, the code sequence in the
present only caller of svn_wc_get_update_editor4() depends on this
function call NOT overwriting the pointed-to revision number.
I don't know of a precedent or rule for this specific situation so I
feel either way is OK. Bert said he was happy to call it an input
parameter. If you want to declare that this kind of parameter should be
grouped with classical output pointer parameters, I would be fine with
that decision and would happily change it.
- Julian
Received on 2010-03-19 00:55:18 CET