[Zope-dev] Why I dislike narrative doctests

[Kent Tenney]

On Fri, Apr 25, 2008 at 9:39 AM, Jim Fulton <jim at zope.com> wrote:
>
>  On Apr 25, 2008, at 10:20 AM, Kent Tenney wrote:
>
> > However, as Sphinx lowers the barrier to cross-referencing,
> >
>
>  Sounds like I need to check that out. :)
>
>
>
> > they will become
> > important as link destinations from 'real' documentation.
> >
>
>
>  Maaaybe.  I like doctests for readability even if they aren't
> documentation.  I'd be hesitant to link to d=non-documentation from
> documentation.

I think even non-documentation doctests are documentation since they
demonstrate correct usage. They need to be explained in the linking
document, but they are invaluable as examples.

Seems like a natural separation of concerns.

>
>
>
>  Jim
>
>  --
>  Jim Fulton
>  Zope Corporation
>
>
>