On Wed, Sep 15, 2010 at 11:35 AM, Julian Foad <julian.foad_at_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
Received on 2010-09-15 11:43:49 CEST