launchpad-dev team mailing list archive

[Julian Edwards <julian.edwards@xxxxxxxxxxxxx>]

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?