On Monday 01 March 2010 16:28:06 Gary Poster wrote: > On Mar 1, 2010, at 10:57 AM, Julian Edwards wrote: > > On Monday 01 March 2010 15:40:25 Aaron Bentley wrote: > >> Julian Edwards wrote: > >>> Precedent. Pretty much most of our model objects already have this. > >>> Our doc strings are mostly awful and where they are not awful they are > >>> mediocre. > >> > >> Our classes which implement interfaces have deliberately content-free > >> docstrings, and I really wish they didn't. Having the documentation of > >> lp.code.model.Branch just saying "See `IBranch`." over and over is not > >> useful. > >> > >> It is very useful to have the documentation and the implementation in > >> the same place, so that the documentation can serve as a guide to > >> understanding the implementation. It also makes it easier to spot and > >> fix errors in the documentation. > >> > >> Aaron > > > > Huge +1. > > > > I've always hated that we document the interface and not the model. Does > > anyone remember why we do it that way? > > Zope pattern. > > The pattern makes more sense IMO when you are designing shared systems, > libraries, or framework. Less sense when you are writing application > code. The Grok pattern is to forego interfaces in favor of classes in > application code--code that is hooking things or plugging things together, > rather than providing plug-points. > > I'd be in favor of that.
We seem to be doing both of these things at the same time - the webservice and our own application code. And I just remembered that the webservice inspects the interface doc strings to produce the apidoc... _______________________________________________ Mailing list: https://launchpad.net/~launchpad-dev Post to : [email protected] Unsubscribe : https://launchpad.net/~launchpad-dev More help : https://help.launchpad.net/ListHelp
