On Tue, Feb 23, 2010 at 5:58 AM, Julian Edwards <[email protected]> wrote: > On Monday 22 February 2010 23:18:04 Martin Pool wrote: >> On 22 February 2010 20:40, Julian Edwards <[email protected]> > 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 _______________________________________________ Mailing list: https://launchpad.net/~launchpad-dev Post to : [email protected] Unsubscribe : https://launchpad.net/~launchpad-dev More help : https://help.launchpad.net/ListHelp
