[Zope3-dev] Re: Windows eggs

[Marius Gedminas]

On Sun, Jul 15, 2007 at 08:34:43AM -0400, Stephan Richter wrote:
> On Saturday 14 July 2007 04:24, Marius Gedminas wrote:
> > - API documentation: human readability is the primary concern, doctests
> >     are in there just to make sure the documentation stays up to date.
> >     These are .txt files.
> 
> I disagree.

Perhaps not.  ;)

> API reference should be automatically created.

Yes, absolutely, with something like pydoc/epydoc/pydoctor.

I was talking about regular programmer-facing documentation and couldn't
find a good word for it (tutorial?  programmer's guide).  The thing you
read to learn about the package, not the thing you use to look up some
details of some function.

> Text files are 
> there to explain the API to someone who wants to use it. I write text files 
> like I would write a lab report or a book on the subject.
> 
> >   - Short usage examples: sometimes it's simpler to show an example than
> >     to describe the function in words:
> >
> >         def parse_date(date_string):
> >             """Parses an ISO-8601 date.
> >
> >                 >>> parse_date('2007-07-14')
> >                 datetime.date(2007, 7, 14)
> >
> >             """
> 
> I have not done this, because most interesting functions/methods are not that 
> simple.

Yes, these are very rarely applicable in my experience.  Low-level
universal utility functions, mainly, not application business logic.

> Also, I really enjoy not having long documentation strings in the 
> code anymore.

That's great, I completely agree.

> That's a huge win coming from interfaces, in my opinion.

I wish pydoc knew about zope interfaces...

> >   - Unit tests: there are many of those, they're independent (thus a
> >     single .txt for a collection of tests is a Bad Idea), they're short
> >     (so understanding and debugging is easy) and expressive.  I put
> >     those into .py files full with functions that look like
> >
> >         def doctest_FooClass_does_this():
> >             """Test that FooClass is able to ...
> >
> >                 >>> foo = FooClass()
> >                 >>> results = foo.do_this()
> >                 >>> for fruit, score, comments in results:
> >                 ...     print fruit.ljust(10), '|', score.ljust(5), '|',
> > comments Orange     | 9     | Tastes good, a bit sour
> >                 Apple      | 8     | Varies
> >
> >             """
> 
> I never do this anymore. If I have a collection of utility functions, I Still 
> put them in a text file, because text files allow me to concentrate on 
> documentation.

Perhaps I did not get my point clearly accross.  Python modules with
doctests are useful for testing the various corner cases that you did
not test in the corresponding .txt file.

If you put the tests for all your corner cases into the documentation,
it quickly becomes unreadable.

> In you example above, for example, I miss a lot of explanatory 
> text.

I was trying to keep the email short.  I usually have a sentence
explaining each set short sequence of doctest assertions that do
something and then inspect the result.

> When I have utility functions that I want to explain independently, 
> then I simply create one section/chapter per function. 

Right, but test_foo.py is never about documentation, it's about isolated
unit tests.

Marius Gedminas
-- 
I noticed that Open Source proponents using MacOS X have developed highly tuned
excuses, similar to those that smokers have about why cigarettes are good for
you.
        -- Miguel de Icaza,
           http://primates.ximian.com/~miguel/archive/2004/Aug-03.html
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: Digital signature
Url : http://mail.zope.org/pipermail/zope3-dev/attachments/20070715/7e6a5e1a/attachment.bin