[Doc-SIG] Documenting Asyncore
Christopher G. Petrilli
Wed, 24 Feb 1999 12:13:33 -0500
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
| Christopher Petrilli ``Television is bubble-gum for
| email@example.com the mind.''-Frank Lloyd Wright