Merge pull request #1453 from twisted/10021-mthuurne-fix-docstrings

Author: mthuurne
Reviewer: twm
Fixes: ticket:10021

Fix incorrect fields in docstrings

src/twisted/_threads/_ithreads.py

@@ -48,7 +48,7 @@ def quit():
         Free any resources associated with this L{IWorker} and cause it to
         reject all future work.
 
-        @raise: L{AlreadyQuit} if this method has already been called.
+        @raise AlreadyQuit: if this method has already been called.
         """
 
 

src/twisted/_threads/_pool.py

@@ -40,9 +40,9 @@ def pool(currentLimit, threadFactory=Thread):
         created.
     @type currentLimit: 0-argument callable returning L{int}
 
-    @param reactor: If passed, the L{IReactorFromThreads} / L{IReactorCore} to
-        be used to coordinate actions on the L{Team} itself.  Otherwise, a
-        L{LockWorker} will be used.
+    @param threadFactory: Factory that, when given a C{target} keyword argument,
+        returns a L{threading.Thread} that will run that target.
+    @type threadFactory: callable returning a L{threading.Thread}
 
     @return: a new L{Team}.
     """

src/twisted/application/reactors.py

@@ -75,7 +75,7 @@ def installReactor(shortName):
 
     @raise NoSuchReactor: If no reactor is found with a matching C{shortName}.
 
-    @raise: anything that the specified reactor can raise when installed.
+    @raise Exception: Anything that the specified reactor can raise when installed.
     """
     for installer in getReactorTypes():
         if installer.shortName == shortName:

src/twisted/conch/endpoints.py

@@ -796,7 +796,7 @@ def _knownHosts(cls):
 
         @return: A L{KnownHostsFile} instance pointed at the user's personal
             I{known hosts} file.
-        @type: L{KnownHostsFile}
+        @rtype: L{KnownHostsFile}
         """
         return KnownHostsFile.fromPath(FilePath(expanduser(cls._KNOWN_HOSTS)))
 

src/twisted/conch/insults/helper.py

@@ -73,7 +73,7 @@ def wantOne(self, **kw):
         """
         Add a character attribute to a copy of this formatting state.
 
-        @param **kw: An optional attribute name and value can be provided with
+        @param kw: An optional attribute name and value can be provided with
             a keyword argument.
 
         @return: A formatting state instance with the new attribute.

src/twisted/conch/ssh/connection.py

@@ -411,7 +411,7 @@ def sendGlobalRequest(self, request, data, wantReply=0):
         @type request:      L{bytes}
         @type data:         L{bytes}
         @type wantReply:    L{bool}
-        @rtype              C{Deferred}/L{None}
+        @rtype:             C{Deferred}/L{None}
         """
         self.transport.sendPacket(
             MSG_GLOBAL_REQUEST,
@@ -458,7 +458,7 @@ def sendRequest(self, channel, requestType, data, wantReply=0):
         @type requestType:  L{bytes}
         @type data:         L{bytes}
         @type wantReply:    L{bool}
-        @rtype              C{Deferred}/L{None}
+        @rtype:             C{Deferred}/L{None}
         """
         if channel.localClosed:
             return

src/twisted/conch/ssh/filetransfer.py

@@ -856,7 +856,7 @@ def gotServerVersion(self, serverVersion, extData):
         """
         Called when the client sends their version info.
 
-        @param otherVersion: an integer representing the version of the SFTP
+        @param serverVersion: an integer representing the version of the SFTP
         protocol they are claiming.
         @param extData: a dictionary of extended_name : extended_data items.
         These items are sent by the client to indicate additional features.

src/twisted/conch/ssh/keys.py

@@ -1570,13 +1570,19 @@ def _toPrivateOpenSSH_PEM(self, passphrase=None):
     def _toString_OPENSSH(self, subtype=None, comment=None, passphrase=None):
         """
         Return a public or private OpenSSH string.  See
-        _fromString_PUBLIC_OPENSSH and _fromPrivateOpenSSH_PEM for the
-        string formats.  If extra is present, it represents a comment for a
-        public key, or a passphrase for a private key.
+        L{_fromString_PUBLIC_OPENSSH} and L{_fromPrivateOpenSSH_PEM} for the
+        string formats.
 
-        @param extra: Comment for a public key or passphrase for a
-            private key
-        @type extra: L{bytes}
+        @param subtype: A subtype to emit.  Only supported for private keys,
+            for which the currently supported subtypes are C{'PEM'} and C{'v1'}.
+            If not given, an appropriate default is used.
+        @type subtype: L{str} or L{None}
+
+        @param comment: Comment for a public key.
+        @type comment: L{bytes}
+
+        @param passphrase: Passphrase for a private key.
+        @type passphrase: L{bytes}
 
         @rtype: L{bytes}
         """

src/twisted/cred/_digest.py

@@ -85,7 +85,7 @@ def calcHA2(algo, pszMethod, pszDigestUri, pszQop, pszHEntity):
     """
     Compute H(A2) from RFC 2617.
 
-    @param pszAlg: The name of the algorithm to use to calculate the digest.
+    @param algo: The name of the algorithm to use to calculate the digest.
         Currently supported are md5, md5-sess, and sha.
     @param pszMethod: The request method.
     @param pszDigestUri: The request URI.

src/twisted/enterprise/adbapi.py

@@ -173,27 +173,27 @@ def __init__(self, dbapiName, *connargs, **connkw):
         @param dbapiName: an import string to use to obtain a DB-API compatible
             module (e.g. C{'pyPgSQL.PgSQL'})
 
-        @param cp_min: the minimum number of connections in pool (default 3)
+        @keyword cp_min: the minimum number of connections in pool (default 3)
 
-        @param cp_max: the maximum number of connections in pool (default 5)
+        @keyword cp_max: the maximum number of connections in pool (default 5)
 
-        @param cp_noisy: generate informational log messages during operation
+        @keyword cp_noisy: generate informational log messages during operation
             (default C{False})
 
-        @param cp_openfun: a callback invoked after every C{connect()} on the
+        @keyword cp_openfun: a callback invoked after every C{connect()} on the
             underlying DB-API object. The callback is passed a new DB-API
             connection object. This callback can setup per-connection state
             such as charset, timezone, etc.
 
-        @param cp_reconnect: detect connections which have failed and reconnect
+        @keyword cp_reconnect: detect connections which have failed and reconnect
             (default C{False}). Failed connections may result in
             L{ConnectionLost} exceptions, which indicate the query may need to
             be re-sent.
 
-        @param cp_good_sql: an sql query which should always succeed and change
+        @keyword cp_good_sql: an sql query which should always succeed and change
             no state (default C{'select 1'})
 
-        @param cp_reactor: use this reactor instead of the global reactor
+        @keyword cp_reactor: use this reactor instead of the global reactor
             (added in Twisted 10.2).
         @type cp_reactor: L{IReactorCore} provider
         """
@@ -266,9 +266,9 @@ def runWithConnection(self, func, *args, **kw):
             B{Note} that this function is B{not} run in the main thread: it
             must be threadsafe.
 
-        @param *args: positional arguments to be passed to func
+        @param args: positional arguments to be passed to func
 
-        @param **kw: keyword arguments to be passed to func
+        @param kw: keyword arguments to be passed to func
 
         @return: a L{Deferred} which will fire the return value of
             C{func(Transaction(...), *args, **kw)}, or a
@@ -311,10 +311,10 @@ def runInteraction(self, interaction, *args, **kw):
         @param interaction: a callable object whose first argument is an
             L{adbapi.Transaction}.
 
-        @param *args: additional positional arguments to be passed to
+        @param args: additional positional arguments to be passed to
             interaction
 
-        @param **kw: keyword arguments to be passed to interaction
+        @param kw: keyword arguments to be passed to interaction
 
         @return: a Deferred which will fire the return value of
             C{interaction(Transaction(...), *args, **kw)}, or a

src/twisted/internet/_glibbase.py

@@ -36,7 +36,7 @@ def ensureNotImported(moduleNames, errorMessage, preventImports=[]):
     @param errorMessage: Message to use when raising an C{ImportError}.
     @type errorMessage: C{str}
 
-    @raises: C{ImportError} with given error message if a given module name
+    @raise ImportError: with given error message if a given module name
         has already been imported.
     """
     for name in moduleNames:

src/twisted/internet/_sslverify.py

@@ -477,7 +477,7 @@ def peerFromTransport(Class, transport):
 
         @rtype: C{Class}
 
-        @raise: L{CertificateError}, if the given transport does not have a peer
+        @raise CertificateError: if the given transport does not have a peer
             certificate.
         """
         return _handleattrhelper(Class, transport, "peer")
@@ -491,7 +491,7 @@ def hostFromTransport(Class, transport):
 
         @rtype: C{Class}
 
-        @raise: L{CertificateError}, if the given transport does not have a host
+        @raise CertificateError: if the given transport does not have a host
             certificate.
         """
         return _handleattrhelper(Class, transport, "host")
@@ -1218,7 +1218,7 @@ def optionsForClientTLS(
         the list are preferred over those later in the list.
     @type acceptableProtocols: L{list} of L{bytes}
 
-    @param extraCertificateOptions: keyword-only argument; this is a dictionary
+    @keyword extraCertificateOptions: keyword-only argument; this is a dictionary
         of additional keyword arguments to be presented to
         L{CertificateOptions}. Please avoid using this unless you absolutely
         need to; any time you need to pass an option here that is a bug in this

src/twisted/internet/base.py

@@ -422,8 +422,8 @@ def addTrigger(
         @param phase: One of C{'before'}, C{'during'}, or C{'after'}.
 
         @param callable: An object to be called when this event is triggered.
-        @param *args: Positional arguments to pass to C{callable}.
-        @param **kwargs: Keyword arguments to pass to C{callable}.
+        @param args: Positional arguments to pass to C{callable}.
+        @param kwargs: Keyword arguments to pass to C{callable}.
 
         @return: An opaque handle which may be passed to L{removeTrigger} to
             reverse the effects of calling this method.
@@ -727,7 +727,8 @@ def sigInt(self, number: int, frame: Optional[FrameType] = None) -> None:
         """
         Handle a SIGINT interrupt.
 
-        @param args: See handler specification in L{signal.signal}
+        @param number: See handler specification in L{signal.signal}
+        @param frame: See handler specification in L{signal.signal}
         """
         log.msg("Received SIGINT, shutting down.")
         self.callFromThread(self.stop)
@@ -737,7 +738,8 @@ def sigBreak(self, number: int, frame: Optional[FrameType] = None) -> None:
         """
         Handle a SIGBREAK interrupt.
 
-        @param args: See handler specification in L{signal.signal}
+        @param number: See handler specification in L{signal.signal}
+        @param frame: See handler specification in L{signal.signal}
         """
         log.msg("Received SIGBREAK, shutting down.")
         self.callFromThread(self.stop)
@@ -747,7 +749,8 @@ def sigTerm(self, number: int, frame: Optional[FrameType] = None) -> None:
         """
         Handle a SIGTERM interrupt.
 
-        @param args: See handler specification in L{signal.signal}
+        @param number: See handler specification in L{signal.signal}
+        @param frame: See handler specification in L{signal.signal}
         """
         log.msg("Received SIGTERM, shutting down.")
         self.callFromThread(self.stop)

src/twisted/internet/defer.py

@@ -768,7 +768,7 @@ def send(self, value=None):
 
     def asFuture(self, loop):
         """
-        Adapt a L{Deferred} into a L{asyncio.Future} which is bound to C{loop}.
+        Adapt this L{Deferred} into a L{asyncio.Future} which is bound to C{loop}.
 
         @note: converting a L{Deferred} to an L{asyncio.Future} consumes both
             its result and its errors, so this method implicitly converts
@@ -780,9 +780,6 @@ def asFuture(self, loop):
         @param loop: The asyncio event loop to bind the L{asyncio.Future} to.
         @type loop: L{asyncio.AbstractEventLoop} or similar
 
-        @param deferred: The Deferred to adapt.
-        @type deferred: L{Deferred}
-
         @return: A Future which will fire when the Deferred fires.
         @rtype: L{asyncio.Future}
         """
@@ -920,7 +917,9 @@ def _cancelledToTimedOutError(value, timeout):
     @type timeout: L{int}
 
     @rtype: C{value}
-    @raise: L{TimeoutError}
+    @raise TimeoutError: If C{value} is a L{Failure} that is a L{CancelledError}.
+    @raise Exception: If C{value} is a L{Failure} that is not a L{CancelledError},
+        it is re-raised.
 
     @since: 16.5
     """

src/twisted/internet/endpoints.py

@@ -1985,15 +1985,14 @@ def _parseClientSSL(*args, **kwargs):
 
     Valid positional arguments to this function are host and port.
 
-    @param caCertsDir: The one parameter which is not part of
+    @keyword caCertsDir: The one parameter which is not part of
         L{IReactorSSL.connectSSL}'s signature, this is a path name used to
         construct a list of certificate authority certificates.  The directory
         will be scanned for files ending in C{.pem}, all of which will be
         considered valid certificate authorities for this connection.
-
     @type caCertsDir: L{str}
 
-    @param hostname: The hostname to use for validating the server's
+    @keyword hostname: The hostname to use for validating the server's
         certificate.
     @type hostname: L{unicode}
 

src/twisted/internet/interfaces.py

@@ -1588,9 +1588,6 @@ class IFileDescriptor(ILoggingContext):
 
     def fileno() -> object:
         """
-        @raise: If the descriptor no longer has a valid file descriptor
-            number associated with it.
-
         @return: The platform-specified representation of a file descriptor
             number.  Or C{-1} if the descriptor no longer has a valid file
             descriptor number associated with it.  As long as the descriptor

src/twisted/internet/iocpreactor/interfaces.py

@@ -15,8 +15,8 @@ def readFromHandle(bufflist, evt):
         """
         Read into the given buffers from this handle.
 
-        @param buff: the buffers to read into
-        @type buff: list of objects implementing the read/write buffer protocol
+        @param bufflist: the buffers to read into
+        @type bufflist: list of objects implementing the read/write buffer protocol
 
         @param evt: an IOCP Event object
 

src/twisted/internet/protocol.py

@@ -255,10 +255,10 @@ def _connect(self, method, *args, **kwargs):
         @param method: A callable which will actually start the connection
             attempt.  For example, C{reactor.connectTCP}.
 
-        @param *args: Positional arguments to pass to C{method}, excluding the
+        @param args: Positional arguments to pass to C{method}, excluding the
             factory.
 
-        @param **kwargs: Keyword arguments to pass to C{method}.
+        @param kwargs: Keyword arguments to pass to C{method}.
 
         @return: A L{Deferred} which fires with an instance of the protocol
             class passed to this L{ClientCreator}'s initializer or fails if the

src/twisted/internet/task.py

@@ -822,9 +822,9 @@ def deferLater(clock, delay, callable=None, *args, **kw):
 
     @param callable: The object to call after the delay.
 
-    @param *args: The positional arguments to pass to C{callable}.
+    @param args: The positional arguments to pass to C{callable}.
 
-    @param **kw: The keyword arguments to pass to C{callable}.
+    @param kw: The keyword arguments to pass to C{callable}.
 
     @rtype: L{defer.Deferred}
 

src/twisted/internet/tcp.py

@@ -913,8 +913,8 @@ def reserve():
         because of C{EMFILE}, internal state is reset so that another
         reservation attempt can be made.
 
-        @raises: Any exception except an L{OSError} or L{IOError}
-            whose errno is L{EMFILE}.
+        @raises Exception: Any exception except an L{OSError} whose
+            errno is L{EMFILE}.
         """
 
     def __enter__():

src/twisted/internet/threads.py

@@ -29,8 +29,8 @@ def deferToThreadPool(reactor, threadpool, f, *args, **kwargs):
         method of C{twisted.python.threadpool.ThreadPool}.
 
     @param f: The function to call.
-    @param *args: positional arguments to pass to f.
-    @param **kwargs: keyword arguments to pass to f.
+    @param args: positional arguments to pass to f.
+    @param kwargs: keyword arguments to pass to f.
 
     @return: A Deferred which fires a callback with the result of f, or an
         errback with a L{twisted.python.failure.Failure} if f throws an
@@ -54,8 +54,8 @@ def deferToThread(f, *args, **kwargs):
     Run a function in a thread and return the result as a Deferred.
 
     @param f: The function to call.
-    @param *args: positional arguments to pass to f.
-    @param **kwargs: keyword arguments to pass to f.
+    @param args: positional arguments to pass to f.
+    @param kwargs: keyword arguments to pass to f.
 
     @return: A Deferred which fires a callback with the result of f,
     or an errback with a L{twisted.python.failure.Failure} if f throws
@@ -101,7 +101,7 @@ def blockingCallFromThread(reactor, f, *a, **kw):
     @return: the result of the L{Deferred} returned by C{f}, or the result
         of C{f} if it returns anything other than a L{Deferred}.
 
-    @raise: If C{f} raises a synchronous exception,
+    @raise Exception: If C{f} raises a synchronous exception,
         C{blockingCallFromThread} will raise that exception.  If C{f}
         returns a L{Deferred} which fires with a L{Failure},
         C{blockingCallFromThread} will raise that failure's exception (see

src/twisted/logger/_legacy.py

@@ -22,7 +22,7 @@
 @implementer(ILogObserver)
 class LegacyLogObserverWrapper:
     """
-    L{ILogObserver} that wraps a L{twisted.python.log.ILegacyLogObserver}.
+    L{ILogObserver} that wraps a L{twisted.python.log.ILogObserver}.
 
     Received (new-style) events are modified prior to forwarding to
     the legacy observer to ensure compatibility with observers that