On Thu, Mar 18, 2010 at 19:54, Julian Foad <[email protected]> wrote: > On Thu, 2010-03-18, Greg Stein wrote: >> On Thu, Mar 18, 2010 at 07:34, <[email protected]> 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.
Conceptually, it is still an output parameter. You are saying "put the result HERE." That's an output parameter. Sure, it takes a while to get the value; you have to drive the editor. But that's just timing. The concept is still an OUT param. I certainly have no problem with a redesign of the dataflow, but for now... I see it as an OUT parameter. (note that we have some similar-style params with some checksum-computing functions, too) Cheers, -g
