On Wed, Sep 15, 2010 at 11:35 AM, Julian Foad <julian.f...@wandisco.com> wrote: > Hyrum K. Wright wrote: >> I've been thinking about ways that our API documentation could be made >> a bit cleaner. >> >> Currently, we use a lot of prose to describe APIs, their parameters, >> and other nuances. I find this approach rather unique, and in some >> ways obfuscating. We have great documentation in that we cover a lot >> of ground, but I wonder if we can be more consistent and clear. >> >> For instance, look at the description of svn_client_checkout3(): >> http://people.apache.org/~hwright/svn/doc/api/trunk/group__clnt__wc__checkout.html#ga31e87d0db53bf1158eaceb6552c63bae >> >> It's is really difficult to determine what each parameter does or what >> possible errors are returned, without reading the entire docstring. >> Maybe that's intended, but perhaps a strategy which enumerates the >> parameters would be a bit better. I've mocked up with this may look >> like: >> http://people.apache.org/~hwright/svn/doc/api/temp/group__clnt__wc__checkout.html#ga31e87d0db53bf1158eaceb6552c63bae >> >> You'll note that there isn't a complex discussion of client contexts, >> depth, or peg revisions, but rather links to a common location where >> such concepts can be discussed in-depth. I've also tried to detect >> the various errors which may be returned, and enumerate them >> specifically, rather than buried in the prose description of the API. >> I think this strategy will lead to more consistent and maintainable >> documentation across the project (and easier identifiable deviations >> from standard behavior). >> >> 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. > > I also like the way we can easily check whether the correct set of > parameters is documented. In the past we have often changed function > parameters (when revving the function, or just renaming existing params) > and have failed to notice that the doc string no longer refers to the > real params.
And we get the added benefit of allowing doxygen to help us by identifying undocumented or documented-but-not-existent parameters. > 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." Agreed. That is essentially "inherit the docstring for checkout3(), but with the following delta". > So +1 on starting to use this style and on committing your > svn_client_checkout3() doc string to start the ball rolling. Thanks. Though I'll probably wait a day or two, to let any dissenters make themselves known. :) -Hyrum