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 <cmpil...@collab.net> CollabNet <> www.collab.net <> Distributed Development On Demand
signature.asc
Description: OpenPGP digital signature
