[Doc-SIG] Documenting Asyncore

[Guido van Rossum]

> 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.

> 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" ???).

--Guido van Rossum (home page: http://www.python.org/~guido/)