[Twisted-Python] Documentation Question

[Moshe Zadka]

On Mon, 10 Nov 2003, Steven Bauer <bauer at mit.edu> wrote:

> Being new to twisted I may be lacking a clue, but finding the
> proper arguments to twisted.application.internet.UDPServer()
> was a major pain in the butt.  
> 
> Only by looking at the code could I find all the valid arguments and
> that took a lot of tracing because the valid arguments are determined by
> listenudp() it seems.

Did you try using help(internet.UDPServer) from the interactive interpreter?
Here's what I got:

class UDPServer(_AbstractServer)
 |  Serve UDP clients
 |
 |  Call listenUDP when the service starts, with the
 |  arguments given to the constructor. When the service stops,
 |  stop listening.

I checked in a fix to make it say "reactor.listenUDP" -- I guess it was
just a blindspot of me, I knew what listenUDP means :)
Anyway, this should not have required any "looking at the code".
Hopefully with my fix you'll be able to know you should do
help(reactor.listenUDP) to get the information you're after:

>>> help(reactor.listenUDP)
Help on method listenUDP in module twisted.internet.default:

listenUDP(self, port, protocol, interface='', maxPacketSize=8192) method of twis
ted.internet.default.SelectReactor instance
    Connects a given L{DatagramProtocol} to the given numeric UDP port.

I realize that the indirection is a pain, but it'd be somewhat annoying
(not impossible, though) to lose it, and I would prefer not to do it
unless it's a real deal breaker for someone.

In general, I highly recommend using help() from the interactive interpreter
to read the docstrings of stuff, and see how to call it. If this strategy
does not give you information for a specific method/class, you should
file a documentation bug in http://twistedmatrix.com/bugs -- while
ideally everything should have a docstring, the developers have so much
time, so prioritizing by stuff people need is a necessity.