andrew-twisted at puzzling.org
Mon Dec 9 23:59:55 EST 2002
On Mon, Dec 09, 2002 at 11:16:10PM -0500, Steve Waterbury wrote:
> Andrew Bennetts wrote:
> > I probably should update the "Introduction to Twisted Enterprise" doc to
> > make this clearer :)
> Actually, you might want to start with the doc string for
> operationDone, which says:
> """Default callback for database operation success."""
> I'd suggest something like:
> """Template for [or "example of"] callback indicating
> operation success -- subclass as desired."""
I've decided to go with:
"""Example callback for database operation success.
Override this, and/or define your own callbacks.
That's now in CVS.
> I think I would have got the idea if it had said that.
> (It isn't really what I would call a default because it isn't
> called by default ... one has to explicitly call it, which,
> as you point out, isn't the intent ... kind of a nit, but
> enough to confuse a literalist such as myself ... ;^)
Yeah, it was confusing, and needed to be fixed.
> I try to adhere as closely as possible to what I think is
> the design intent of the Twisted developers (since it tends to
> make life easier in the long run ;^), so doc string hints about
> subclassing, etc., are much appreciated -- as are the Twisted
> docs, of course, which are continuously improving -- thanks!
The docs should always try to encourage "best practice" use of the code;
which means using the appropriate idioms in examples, and so on.
Let us know if you find any other problems like this :)
> BTW, has anyone here checked out Leo? ... seems interesting
> and might be integrable with lore ... so many documentation
> technologies, so little time ...
Leo is on my list of "things I'll look at when I have some spare time" ;)
More information about the Twisted-Python