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
