launchpad-dev team mailing list archive

[Julian Edwards <julian.edwards@xxxxxxxxxxxxx>]

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