Hyrum Wright wrote on Wed, Sep 22, 2010 at 21:07:10 +0100:
> On Wed, Sep 22, 2010 at 8:40 PM, Daniel Shahaf <d...@daniel.shahaf.name>
> wrote:
> > Hyrum Wright wrote on Wed, Sep 22, 2010 at 12:08:41 +0100:
> >> On Wed, Sep 22, 2010 at 11:33 AM, Daniel Shahaf <d...@daniel.shahaf.name>
> >> wrote:
> >> > [1] For the [out] parameter, can we have @param[out,optional] and
> >> > @param[out,mandatory] notations, or do we have to say "may be NULL"
> >> > in the prose?)
> >>
> >> @param[out] is part of the doxygen markup (not just some arbitrary
> >> notation). I don't know what it would do in the face of extra values
> >> (see http://www.stack.nl/~dimitri/doxygen/commands.html#cmdparam)
> >>
> >
> > Well, the [mandatory] and [optional] could be a nice extension to that
> > syntax.
>
> Agreed, though I'm not sure the doxygen parser would handle it.
>
I didn't mean we should invent doxygen syntax, I meant it would be nice
if doxygen supported that syntax (and once it does --- not before that
--- we can use it).
> >> > [2] How about introducing:
> >> >
> >> > struct svn_ra_node_t {
> >> > const char *repos_relpath;
> >> > svn_revnum_t peg;
> >> > };
> >> >
> >> > struct svn_client_node_t {
> >> > const char *path_or_URL;
> >> > svn_opt_revision_t *peg;
> >> > };
> >> >
> >> > (that will also help make the docstrings clearer)
> >>
> >> You'd probably want to the revision in there too, much like we do for
> >> svn_client_copy_source_t. Both the peg revision and the operative
> >> revision are used to specify a node (though in the absence of one, the
> >> default is generally the other, I think).
> >>
> >
> > Yeah, I can argue to have those structs both with/without the operative
> > revision in them.
> >
> > Either way, what I had in mind was using these structs in APIs instead
> > of having separate 'path' and 'peg_revision' arguments. This will
> > simplify docstrings (we can say "the node" instead of "the path as it
> > existed at the peg revision"), and it's logically correct too (represent
> > logical tuples as structs: the 'node', as one unit, is the target of the
> > operation).
>
> Quick thought: are there APIs which take an array of target
> paths/urls, but only a single peg/operative revision pair?
Examples:
* 'svn cp' (takes array of copy_source_t)
* syntax (2) of 'svn log' (takes a single peg)
* svn_ra_get_mergeinfo() (I'm not sure what pegs it uses)
> Would these need yet another struct?
>
No, they can take an array of strings instead of array of node_t's.
> -Hyrum
