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
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.
> I also like the way we can easily check whether the correct set of
> parameters is documented.
C. Michael Pilato <cmpilato_at_collab.net>
CollabNet <> www.collab.net <> Distributed Development On Demand
Received on 2010-09-15 17:20:22 CEST