On Mi, 2010-09-15 at 10:35 +0100, Julian Foad wrote:
> Hyrum K. Wright wrote:
> > I've been thinking about ways that our API documentation could be made
> > a bit cleaner.
...
> > Thoughts?
> >
> > -Hyrum
>
> +1.
>
> You know what, I've been a bit skeptical of the list-of-params style of
> documentation, as sometimes I've seen "documentation" that says "@param
> revision - the revision number; @param path - the path", without saying
> the path of what, what kind of path, relative to what.
>
> But your mock-up is very good. I particularly like that it refers to
> the canonical definitions of depth, client_ctx (saying which parts of
> that are relevant) and operative/peg revisions, instead of trying to
> explain them yet again in yet another way.
Indeed, I find it very good and it adds a lot of value by referencing
important concepts and giving a concise list of return values.
This style also feels a lot easier to handle, in my opinion, if I refer
to the documentation in order to use other language bindings. Could be
due to fewer uses of C syntax and marking parameters as in/out. I don't
feel burdened with the task to read everything and can quickly check a
single parameter or return value's description.
> This style won't fit all functions - for example, I don't think it would
> be useful to rewrite the doc string of svn_client_checkout2() which is
> currently:
>
> "Similar to svn_client_checkout3() but with allow_unver_obstructions
> always set to FALSE, and depth set according to recurse: if recurse is
> TRUE, depth is svn_depth_infinity, if recurse is FALSE, depth is
> svn_depth_files."
I think that is true. It would fit many of the current version functions
but describing differences to older versions, for example, may be easier
done with a descriptive text.
Cheers,
Uwe
Received on 2010-09-15 16:39:26 CEST