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. >> > [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? Would these need yet another struct? -Hyrum