launchpad-dev team mailing list archive

[Julian Edwards <julian.edwards@xxxxxxxxxxxxx>]

On Monday 01 March 2010 12:10:43 Jonathan Lange wrote:
> It sounds like you are mostly agreeing with each other.
> 
> Personally, I prefer having big class- and module-level docstrings. I
> don't think that documentation on "how to use a model object" is
> interesting in the general case. I would much rather read a document
> about how to do something interesting. Sometimes this will be about
> using a model object.

I think you're still agreeing with me.

> (Also, what makes model objects so special anyway?)

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.

I think the doc tests should still be about how to drive the object (or "doing 
something useful with it" like you say).

The doc strings should be like a reference where you already know how to drive 
it but need help on a specific function/method.