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
