Opened 4 years ago

Last modified 18 months ago

#4622 enhancement new

Better docstring for ClientCreator.__init__

Reported by: lvh Owned by:
Priority: lowest Milestone:
Component: core Keywords: documentation
Cc: thijs Branch:
Author: Launchpad Bug:

Description

ClientCreator.__init__ currently does not have a docstring. People have told me this is annoying, and it took them longer than eps to figure out how it worked. Specifically, *a, **kw in __init__'s signature was confusing (even though the class docstring technically documents it).

To remedy this, I propose the following docstring:

"""
Initializes a ClientCreator.

@param reactor: The reactor clients created by this object will use to connect.
@type reactor: The appropriate L{t.i.interfaces.IReactor*} (implementing the reactor methods you intend to use).
@param protocolClass: The protocol class that will be instantiated upon connection. 
@type protocolClass: class implementing L{IProtocol}
@param *protocolArgs: The arguments that will be passed to the protocol class upon instantiation at connection.
@param **protocolKwargs: The keyword arguments that will be passed to the protocol class upon instantiation at connection.
"""

I also propose we change the *a, **kw signature to *protocolArgs, **protocolKwargs, for descriptiveness. (This change is already reflected in the above docstring.)

The @type reactor is a bit superfluous and probably adds more confusing than it clarifies. It could be thrown out. Same with @type protocolClass, really.

Change History (3)

comment:1 Changed 4 years ago by exarkun

Should strongly recommend using endpoints instead.

comment:2 Changed 3 years ago by <automation>

  • Owner glyph deleted

comment:3 Changed 18 months ago by thijs

  • Cc thijs added
Note: See TracTickets for help on using tickets.