[Doc-SIG] Documenting Asyncore

[Christopher G. Petrilli]

On Wed, Feb 24, 1999 at 12:09:11PM -0500, Guido van Rossum wrote:
> > OK, so I talked with Sam about this, and he's written some pretty good
> > introductory material... but here's the thing... USING asyncore and
> > asynchat requires a brain adjustment for most people, which seems to be
> > outside the realm of the reference manual, so how to deal with this?
> > Should I just document the class and ignore the issue of ideology?  I
> > know, this is a great topic for a HOWTO, and I'm meaning to reformat
> > Sam's introduction into one, but... that doesn't fix the library manual.
> 
> I'm not sure why it wouldn't fit in the library manual.  For example
> the profiler and debugger chapters have some tutorial style material
> in them, and there are some others.

My fear was that while the profiler/debuggers have "tutorials", the
async programming idea requires more like 10-15 pages of stuff to
really get it across to people in a sane way they can understand... it's
just too different for most people's mindset. 

Anyway, what I'm thinkin is just document it a'la a regular library with
a 1-2 paragraph introduction as to WHAT async sockets are meant to
provide, and then say 2 examples of small size which show it being used
(probably Sam's proxy example being one).  a HOWTO could then delve into
it more deeply.

> > Also, I was thinking... perhaps there should be a way to note that
> > there's something in the source code INTENTIONALLY undocumented that
> > might be of trivial use to someone maybe oneday?  DOn't know... there's
> > some things in asyncore like that, you might be interested, but... 
> 
> I'm not sure what you are talking about here -- to indicate that
> something is not intended to be documented a comment in the source
> should be sufficient.  Documenting seems to be an oximoron ("there's
> this really nify undocumented printindex() method in this class that
> you're not supposed to use but could nevertheless be real handy one
> day" ???).

Ignore that, i"m not sure what I was talking about :-)  I think I was
reffering to there being some aspects of libraries that shouldn't be
twiddled with without a deep understanding of the working code.  My
later comment about "dangerous" things might fit in better with that.
Looking back, I must have been suffering from some drug (legal) induced
stupor!

Chris
-- 
| Christopher Petrilli                      ``Television is bubble-gum for
| petrilli@amber.org                          the mind.''-Frank Lloyd Wright