[Zope-dev] Why I dislike narrative doctests

[Kent Tenney]

On Thu, Apr 24, 2008 at 3:07 PM, Jim Fulton <jim at zope.com> wrote:
>
>  On Apr 24, 2008, at 1:12 AM, Christian Theune wrote:
>
>
> > Hi,
> >
> > On Wed, Apr 23, 2008 at 04:47:59PM -0400, Jim Fulton wrote:
> >
> > >
> > > On Apr 23, 2008, at 4:47 PM, Marius Gedminas wrote:
> > > ...
> > >
> > > > The point of my message was not to whine
> > > > about the state of zope.testing, but to present a new argument against
> > > > the current fashion of using plain-text narrative doctests for
> > > > everything.
> > > >
> > >
> > > Except that that is not the current fashion, which has been pointed out
> > > many times in many places.
> > >
> >
> > For my own record (I must have missed this many times in many places), is
> the
> > current fashion something along the lines:
> >
> > "Use the various test styles as reasonable, text-file narrative doctests
> are
> > preferred."
> >
>
>
>  No.  WRT doc tests:
>
>  - If a file is documentation and a test, make sure it is good
> documentation. In that case, documentation comes first. Don't add so many
> tests that it ruins the documentation.
>
>  - Test edge cases in separate tests.  These are typically short-ish strings
> in test modules.
>
>  - A variation is to have a narrative that doesn't try hard to be
> documentation.  The narrative can be convenient, up to a point, even in a
> test.  These should be clearly marked as not being documentation.

However, as Sphinx lowers the barrier to cross-referencing, they will become
important as link destinations from 'real' documentation.


>
>
>  Jim
>
>  --
>  Jim Fulton
>  Zope Corporation
>
>
>  _______________________________________________
>
>  Zope-Dev maillist  -  Zope-Dev at zope.org
>  http://mail.zope.org/mailman/listinfo/zope-dev
>  **  No cross posts or HTML encoding!  **
>  (Related lists -http://mail.zope.org/mailman/listinfo/zope-announce
>  http://mail.zope.org/mailman/listinfo/zope )
>