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
Received on 2010-09-15 10:53:07 CEST