launchpad-dev team mailing list archive

[Jonathan Lange <jml@xxxxxxxxxxxxx>]

On Tue, Feb 23, 2010 at 5:58 AM, Julian Edwards
<julian.edwards@xxxxxxxxxxxxx> wrote:
> On Monday 22 February 2010 23:18:04 Martin Pool wrote:
>> On 22 February 2010 20:40, Julian Edwards <julian.edwards@xxxxxxxxxxxxx>
> wrote:
>> >> imo you are either writing doc tests or you're writing testable
>> >> documentation; they are not the same thing at all and it's hard to
>> >> make one document work for both.
>> >
>> > I have exactly the opposite opinion :)
>> >
>> > I'd like to see an example of why you think it's hard though?
>>
>> A good test suite should exercise every distinct domain of the
>> interface, trying to break it, paying attention to edge cases.  You
>> expect them to all fail at least once so it's good to make them pretty
>> fine grained and perhaps to use validating decorators or something
>> else that will check internals or be faster, and perhaps to use
>> infrastructure to apply the same test in many different situations.
>> Having the output from one test feed into the next is generally poor
>> because you get cascading confusion.
>>
>> Whereas for documentation you want someone to be able to read it from
>> start to end, which means it should have a kind of narrative, show the
>> typical cases, not the obscure ones, and showing the typical way to
>> use the object, not a special setup for testing.
>>
>> At least that's how it seems to me.  If you have an example of a
>> something that works really well for both at once I would be happy to
>> see it.
>>
>
>
> Ah, I am absolutely not advocating that a doc test does both, you're basically
> in agreement with me with your first two paragraphs here.  I think our lines
> got crossed somewhere.
>
> For me, a doctest for a model object tells me how to use it.  The obscure
> corner cases can go in the unit tests.
>

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.

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

jml