IMAP examples

[Donn Cave]

In article <3F187ED4.6179CDDD at engcorp.com>,
 Peter Hansen <peter at engcorp.com> wrote:

> "James T. Dennis" wrote:
> > 
> > Sean 'Shaleh' Perry <shalehperry at comcast.net> wrote:
> > 
> > >> If my english was better I would love to help improve the python
> > >> documentation, most modules in the standard libraries lack good
> > >> examples how to *use* them with just a simple description.  And a
> > >> short motivation for the design of a module if possible like "just
> > >> copied the C API" or "Because of efficiency ..." or "We use a class
> > >> framework here because ...".  A gigantic task.  The PSL book by effbot
> > >> is great but it's a book.  And it needs a new version.
> > 
> > > part of the reason why the docs are not but so great is that most of the
> > > library is Python code which means any questions can be answered by 
> > > reading
> > > the source.  I find myself doing this quite often.
> > 
> >  <flame>That's BS!</flame>
> > 
> >  As a dabbler in programming I have to say that poor documentation is not
> >  excused by the availability of sources.  
> 
> True, but poor documentation *is* excused quite nicely by the LACK
> of availability of _re_sources, specifically the human resources and time
> required to make them better.
> 
> Or was your flame an indirect offer to assist with improving the 
> documentation of Python?  If so, thank you!

Well, he did offer some suggestions, which is about all most of
us do around here.  But I don't think I'd go along with the premise
as easily as you did - I mean, ``poor documentation is not excused
by the availability of source'' is true as far as it goes, but in
some cases I think ``source is good documentation'' can be true, too.

And in this specific case.  IMAP4 support is a can of worms.  Big
feature set here, baroque might be the word.  Not trivial to parse.
The imaplib solution is minimal.  It does a reasonable job setting
up an imap service connection and conducting a client/server dialogue,
but it doesn't get into the structure or significance of the data.
If you want to use IMAP, the documentation you need to read is the
RFC, unfortunately but it is a reasonable discussion of the protocol.

imaplib.__doc__ points to imaplib.IMAP4;  imaplib.IMAP4.__doc__ is
30 or 40 lines of concise information about the API.  I don't think
this is a crisis situation.

   Donn Cave, donn at u.washington.edu