[SciPy-dev] Doc-ing classes and data attributes

[Ralf Gommers]

On Tue, Jun 23, 2009 at 3:18 PM, Pauli Virtanen <pav at iki.fi> wrote:

> On 2009-06-23, Ralf Gommers <ralf.gommers at googlemail.com> wrote:
> [clip]
> > It looks like these doctests have not worked in a long time. There is
> also
> > a conceptual problem, do you really want everyone who signs up in the doc
> > editor to be able to produce test failures because they wrote an example
> > that doctest does not like?
> [clip]
>
> Yeah, it's quite likely that several of the doctests/examples
> there currently fail. But I think that in many cases a failure to
> doctest indicates also that the example is somehow wrong, and
> someone trying to follow it would run into the same problem.
>
> The doctests are not run by default, and are not included in the
> test suite. The features that allow running them are mostly meant
> to make it easier to ensure that all of the examples actually
> work. (Though AFAIK nobody has vetted them through :)


That makes sense.

I updated the patch attached to #1146, changes are:

   - added note on 75 character per line limit
   - documented the correct way to run doctests, and that this is meant to
   check if the examples work
   - documenting private methods in classes (not sure if there is full
   agreement on this)
   - documenting class instances
   - documenting constants

Ralf
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20090623/b493bb77/attachment.html>