On Wed, Dec 9, 2009 at 9:29 PM, Bjorn Tillenius <[email protected]> wrote: > On Mon, Dec 07, 2009 at 09:57:28AM +1100, Jonathan Lange wrote: >> On Thu, Dec 3, 2009 at 10:15 AM, Bjorn Tillenius <[email protected]> wrote: >> > It should be documentation with tests. It would probably be >> > possible to have a normal unittest test, exctract the comments, and >> > produce a suitable document. >> > >> >> It is! See https://launchpad.net/testdoc for a tool that does exactly this. > > Yeah, I knew about that, actually. Do you have an example (preferably in > the LP tree) of where this is used successfully? I.e., where the > comments from a Python unittest test produce a nice and readable > document.
I don't use testdoc in my day to day development, mostly because it's not integrated with our current toolchain, there's no where to put the docs it generates, and no one would read them anyway. But, I grabbed a copy of testdoc, ran it on lp.code.model.test.test_branchcollection. Here's what it generated: http://pastebin.ubuntu.com/339043/ Some thoughts: * It's a very different type of document to a doctest -- more a collection of small specifications than a tutorial. * If testdoc were part of my development process, I know I'd have written some of those comments differently. * There are some actual bugs in the documentation generation. * I'm surprised it worked so well after three years of not actually being used. 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
