[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

Public API documentation

From: Hyrum K. Wright <hyrum_wright_at_mail.utexas.edu>
Date: Wed, 15 Sep 2010 10:52:23 +0200

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

This is an archived mail posted to the Subversion Dev mailing list.