Re: Public API documentation

On 09/15/2010 05:35 AM, Julian Foad wrote:
> Hyrum K. Wright wrote:
>> I've been thinking about ways that our API documentation could be made
>> a bit cleaner.

[...]

>> 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

I would suggest that yes, it is intended that folks read the entire
docstring for a function before using it. But I "get" that sometimes it
might be nice to more quickly lookup a particular parameter's general
meaning without swimming through tons of context.

Julian Foad wrote:
> 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.

+1

> I also like the way we can easily check whether the correct set of
> parameters is documented.

Yup.

-- 
C. Michael Pilato <cmpilato_at_collab.net>
CollabNet   <>   www.collab.net   <>   Distributed Development On Demand