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.
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."
So +1 on starting to use this style and on committing your
svn_client_checkout3() doc string to start the ball rolling.
- Julian
Received on 2010-09-15 11:36:30 CEST