asyncio doc: annotate coroutine on coroutine functions and methods

6 files changed, 72 insertions, 42 deletions

diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst
index 4f7fdfe..f2c8945 100644
--- a/Doc/library/asyncio-eventloop.rst
+++ b/Doc/library/asyncio-eventloop.rst
@@ -180,7 +180,7 @@ Coroutines
 Creating connections
 --------------------
 
-.. method:: BaseEventLoop.create_connection(protocol_factory, host=None, port=None, \*, ssl=None, family=0, proto=0, flags=0, sock=None, local_addr=None, server_hostname=None)
+.. coroutinemethod:: BaseEventLoop.create_connection(protocol_factory, host=None, port=None, \*, ssl=None, family=0, proto=0, flags=0, sock=None, local_addr=None, server_hostname=None)
 
    Create a streaming transport connection to a given Internet *host* and
    *port*: socket family :py:data:`~socket.AF_INET` or
@@ -253,7 +253,7 @@ Creating connections
       (:class:`StreamReader`, :class:`StreamWriter`) instead of a protocol.
 
 
-.. method:: BaseEventLoop.create_datagram_endpoint(protocol_factory, local_addr=None, remote_addr=None, \*, family=0, proto=0, flags=0)
+.. coroutinemethod:: BaseEventLoop.create_datagram_endpoint(protocol_factory, local_addr=None, remote_addr=None, \*, family=0, proto=0, flags=0)
 
    Create datagram connection: socket family :py:data:`~socket.AF_INET` or
    :py:data:`~socket.AF_INET6` depending on *host* (or *family* if specified),
@@ -271,7 +271,7 @@ Creating connections
    :ref:`UDP echo server protocol <asyncio-udp-echo-server-protocol>` examples.
 
 
-.. method:: BaseEventLoop.create_unix_connection(protocol_factory, path, \*, ssl=None, sock=None, server_hostname=None)
+.. coroutinemethod:: BaseEventLoop.create_unix_connection(protocol_factory, path, \*, ssl=None, sock=None, server_hostname=None)
 
    Create UNIX connection: socket family :py:data:`~socket.AF_UNIX`, socket
    type :py:data:`~socket.SOCK_STREAM`. The :py:data:`~socket.AF_UNIX` socket
@@ -290,7 +290,7 @@ Creating connections
 Creating listening connections
 ------------------------------
 
-.. method:: BaseEventLoop.create_server(protocol_factory, host=None, port=None, \*, family=socket.AF_UNSPEC, flags=socket.AI_PASSIVE, sock=None, backlog=100, ssl=None, reuse_address=None)
+.. coroutinemethod:: BaseEventLoop.create_server(protocol_factory, host=None, port=None, \*, family=socket.AF_UNSPEC, flags=socket.AI_PASSIVE, sock=None, backlog=100, ssl=None, reuse_address=None)
 
    Create a TCP server (socket type :data:`~socket.SOCK_STREAM`) bound to
    *host* and *port*.
@@ -336,11 +336,13 @@ Creating listening connections
       :class:`StreamWriter`) pair and calls back a function with this pair.
 
 
-.. method:: BaseEventLoop.create_unix_server(protocol_factory, path=None, \*, sock=None, backlog=100, ssl=None)
+.. coroutinemethod:: BaseEventLoop.create_unix_server(protocol_factory, path=None, \*, sock=None, backlog=100, ssl=None)
 
    Similar to :meth:`BaseEventLoop.create_server`, but specific to the
    socket family :py:data:`~socket.AF_UNIX`.
 
+   This method is a :ref:`coroutine <coroutine>`.
+
    Availability: UNIX.
 
 
@@ -384,7 +386,7 @@ the file descriptor of a socket.
 Low-level socket operations
 ---------------------------
 
-.. method:: BaseEventLoop.sock_recv(sock, nbytes)
+.. coroutinemethod:: BaseEventLoop.sock_recv(sock, nbytes)
 
    Receive data from the socket.  The return value is a bytes object
    representing the data received.  The maximum amount of data to be received
@@ -399,7 +401,7 @@ Low-level socket operations
 
       The :meth:`socket.socket.recv` method.
 
-.. method:: BaseEventLoop.sock_sendall(sock, data)
+.. coroutinemethod:: BaseEventLoop.sock_sendall(sock, data)
 
    Send data to the socket.  The socket must be connected to a remote socket.
    This method continues to send data from *data* until either all data has
@@ -416,7 +418,7 @@ Low-level socket operations
 
       The :meth:`socket.socket.sendall` method.
 
-.. method:: BaseEventLoop.sock_connect(sock, address)
+.. coroutinemethod:: BaseEventLoop.sock_connect(sock, address)
 
    Connect to a remote socket at *address*.
 
@@ -438,7 +440,7 @@ Low-level socket operations
       method.
 
 
-.. method:: BaseEventLoop.sock_accept(sock)
+.. coroutinemethod:: BaseEventLoop.sock_accept(sock)
 
    Accept a connection. The socket must be bound to an address and listening
    for connections. The return value is a pair ``(conn, address)`` where *conn*
@@ -459,12 +461,12 @@ Low-level socket operations
 Resolve host name
 -----------------
 
-.. method:: BaseEventLoop.getaddrinfo(host, port, \*, family=0, type=0, proto=0, flags=0)
+.. coroutinemethod:: BaseEventLoop.getaddrinfo(host, port, \*, family=0, type=0, proto=0, flags=0)
 
    This method is a :ref:`coroutine <coroutine>`, similar to
    :meth:`socket.getaddrinfo` function but non-blocking.
 
-.. method:: BaseEventLoop.getnameinfo(sockaddr, flags=0)
+.. coroutinemethod:: BaseEventLoop.getnameinfo(sockaddr, flags=0)
 
    This method is a :ref:`coroutine <coroutine>`, similar to
    :meth:`socket.getnameinfo` function but non-blocking.
@@ -476,7 +478,7 @@ Connect pipes
 On Windows with :class:`SelectorEventLoop`, these methods are not supported.
 Use :class:`ProactorEventLoop` to support pipes on Windows.
 
-.. method:: BaseEventLoop.connect_read_pipe(protocol_factory, pipe)
+.. coroutinemethod:: BaseEventLoop.connect_read_pipe(protocol_factory, pipe)
 
    Register read pipe in eventloop.
 
@@ -490,7 +492,7 @@ Use :class:`ProactorEventLoop` to support pipes on Windows.
 
    This method is a :ref:`coroutine <coroutine>`.
 
-.. method:: BaseEventLoop.connect_write_pipe(protocol_factory, pipe)
+.. coroutinemethod:: BaseEventLoop.connect_write_pipe(protocol_factory, pipe)
 
    Register write pipe in eventloop.
 
@@ -543,7 +545,7 @@ Call a function in an :class:`~concurrent.futures.Executor` (pool of threads or
 pool of processes). By default, an event loop uses a thread pool executor
 (:class:`~concurrent.futures.ThreadPoolExecutor`).
 
-.. method:: BaseEventLoop.run_in_executor(executor, callback, \*args)
+.. coroutinemethod:: BaseEventLoop.run_in_executor(executor, callback, \*args)
 
    Arrange for a callback to be called in the specified executor.
 
@@ -654,7 +656,7 @@ Server
       The server is closed asynchonously, use the :meth:`wait_closed` coroutine
       to wait until the server is closed.
 
-   .. method:: wait_closed()
+   .. coroutinemethod:: wait_closed()
 
       Wait until the :meth:`close` method completes.
 
diff --git a/Doc/library/asyncio-stream.rst b/Doc/library/asyncio-stream.rst
index 3809d94..22b7341 100644
--- a/Doc/library/asyncio-stream.rst
+++ b/Doc/library/asyncio-stream.rst
@@ -9,7 +9,7 @@ Streams (high-level API)
 Stream functions
 ================
 
-.. function:: open_connection(host=None, port=None, \*, loop=None, limit=None, **kwds)
+.. coroutinefunction:: open_connection(host=None, port=None, \*, loop=None, limit=None, \*\*kwds)
 
    A wrapper for :meth:`~BaseEventLoop.create_connection()` returning a (reader,
    writer) pair.
@@ -32,7 +32,7 @@ Stream functions
 
    This function is a :ref:`coroutine <coroutine>`.
 
-.. function:: start_server(client_connected_cb, host=None, port=None, \*, loop=None, limit=None, **kwds)
+.. coroutinefunction:: start_server(client_connected_cb, host=None, port=None, \*, loop=None, limit=None, \*\*kwds)
 
    Start a socket server, with a callback for each client connected. The return
    value is the same as :meth:`~BaseEventLoop.create_server()`.
@@ -56,7 +56,7 @@ Stream functions
 
    This function is a :ref:`coroutine <coroutine>`.
 
-.. function:: open_unix_connection(path=None, \*, loop=None, limit=None, **kwds)
+.. coroutinefunction:: open_unix_connection(path=None, \*, loop=None, limit=None, **kwds)
 
    A wrapper for :meth:`~BaseEventLoop.create_unix_connection()` returning
    a (reader, writer) pair.
@@ -68,7 +68,7 @@ Stream functions
 
    Availability: UNIX.
 
-.. function:: start_unix_server(client_connected_cb, path=None, \*, loop=None, limit=None, **kwds)
+.. coroutinefunction:: start_unix_server(client_connected_cb, path=None, \*, loop=None, limit=None, **kwds)
 
    Start a UNIX Domain Socket server, with a callback for each client connected.
 
@@ -106,7 +106,7 @@ StreamReader
 
       Set the transport.
 
-   .. method:: read(n=-1)
+   .. coroutinemethod:: read(n=-1)
 
       Read up to *n* bytes.  If *n* is not provided, or set to ``-1``,
       read until EOF and return all read bytes.
@@ -116,7 +116,7 @@ StreamReader
 
       This method is a :ref:`coroutine <coroutine>`.
 
-   .. method:: readline()
+   .. coroutinemethod:: readline()
 
       Read one line, where "line" is a sequence of bytes ending with ``\n``.
 
@@ -128,7 +128,7 @@ StreamReader
 
       This method is a :ref:`coroutine <coroutine>`.
 
-   .. method:: readexactly(n)
+   .. coroutinemethod:: readexactly(n)
 
       Read exactly *n* bytes. Raise an :exc:`IncompleteReadError` if the end of
       the stream is reached before *n* can be read, the
@@ -168,7 +168,7 @@ StreamWriter
 
       Close the transport: see :meth:`BaseTransport.close`.
 
-   .. method:: drain()
+   .. coroutinemethod:: drain()
 
       Let the write buffer of the underlying transport a chance to be flushed.
 
diff --git a/Doc/library/asyncio-subprocess.rst b/Doc/library/asyncio-subprocess.rst
index 570107e..1334f5b 100644
--- a/Doc/library/asyncio-subprocess.rst
+++ b/Doc/library/asyncio-subprocess.rst
@@ -27,7 +27,7 @@ Example to use it on Windows::
 Create a subprocess: high-level API using Process
 -------------------------------------------------
 
-.. function:: create_subprocess_exec(\*args, stdin=None, stdout=None, stderr=None, loop=None, limit=None, \*\*kwds)
+.. coroutinefunction:: create_subprocess_exec(\*args, stdin=None, stdout=None, stderr=None, loop=None, limit=None, \*\*kwds)
 
    Create a subprocess.
 
@@ -39,7 +39,7 @@ Create a subprocess: high-level API using Process
 
    This function is a :ref:`coroutine <coroutine>`.
 
-.. function:: create_subprocess_shell(cmd, stdin=None, stdout=None, stderr=None, loop=None, limit=None, \*\*kwds)
+.. coroutinefunction:: create_subprocess_shell(cmd, stdin=None, stdout=None, stderr=None, loop=None, limit=None, \*\*kwds)
 
    Run the shell command *cmd*.
 
@@ -67,7 +67,7 @@ Create a subprocess: low-level API using subprocess.Popen
 
 Run subprocesses asynchronously using the :mod:`subprocess` module.
 
-.. method:: BaseEventLoop.subprocess_exec(protocol_factory, \*args, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, \*\*kwargs)
+.. coroutinemethod:: BaseEventLoop.subprocess_exec(protocol_factory, \*args, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, \*\*kwargs)
 
    Create a subprocess from one or more string arguments (character strings or
    bytes strings encoded to the :ref:`filesystem encoding
@@ -116,7 +116,7 @@ Run subprocesses asynchronously using the :mod:`subprocess` module.
 
    See the constructor of the :class:`subprocess.Popen` class for parameters.
 
-.. method:: BaseEventLoop.subprocess_shell(protocol_factory, cmd, \*, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, \*\*kwargs)
+.. coroutinemethod:: BaseEventLoop.subprocess_shell(protocol_factory, cmd, \*, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, \*\*kwargs)
 
    Create a subprocess from *cmd*, which is a character string or a bytes
    string encoded to the :ref:`filesystem encoding <filesystem-encoding>`,
@@ -193,7 +193,7 @@ Process
      :meth:`~subprocess.Popen.wait` method of the :class:`~subprocess.Popen`
      class is implemented as a busy loop.
 
-   .. method:: wait()
+   .. coroutinemethod:: wait()
 
       Wait for child process to terminate.  Set and return :attr:`returncode`
       attribute.
@@ -207,7 +207,7 @@ Process
          blocks waiting for the OS pipe buffer to accept more data. Use the
          :meth:`communicate` method when using pipes to avoid that.
 
-   .. method:: communicate(input=None)
+   .. coroutinemethod:: communicate(input=None)
 
       Interact with process: Send data to stdin.  Read data from stdout and
       stderr, until end-of-file is reached.  Wait for process to terminate.
diff --git a/Doc/library/asyncio-sync.rst b/Doc/library/asyncio-sync.rst
index 80974d9..f036bc8 100644
--- a/Doc/library/asyncio-sync.rst
+++ b/Doc/library/asyncio-sync.rst
@@ -89,7 +89,7 @@ Lock
 
       Return ``True`` if the lock is acquired.
 
-   .. method:: acquire()
+   .. coroutinemethod:: acquire()
 
       Acquire a lock.
 
@@ -139,7 +139,7 @@ Event
       true are awakened. Coroutine that call :meth:`wait` once the flag is true
       will not block at all.
 
-   .. method:: wait()
+   .. coroutinemethod:: wait()
 
       Block until the internal flag is true.
 
@@ -166,7 +166,7 @@ Condition
    object, and it is used as the underlying lock.  Otherwise,
    a new :class:`Lock` object is created and used as the underlying lock.
 
-   .. method:: acquire()
+   .. coroutinemethod:: acquire()
 
       Acquire the underlying lock.
 
@@ -213,7 +213,7 @@ Condition
 
       There is no return value.
 
-   .. method:: wait()
+   .. coroutinemethod:: wait()
 
       Wait until notified.
 
@@ -227,7 +227,7 @@ Condition
 
       This method is a :ref:`coroutine <coroutine>`.
 
-   .. method:: wait_for(predicate)
+   .. coroutinemethod:: wait_for(predicate)
 
       Wait until a predicate becomes true.
 
@@ -258,7 +258,7 @@ Semaphore
    defaults to ``1``. If the value given is less than ``0``, :exc:`ValueError`
    is raised.
 
-   .. method:: acquire()
+   .. coroutinemethod:: acquire()
 
       Acquire a semaphore.
 
@@ -273,7 +273,7 @@ Semaphore
 
       Returns ``True`` if semaphore can not be acquired immediately.
 
-   .. method:: release()
+   .. coroutinemethod:: release()
 
       Release a semaphore, incrementing the internal counter by one. When it
       was zero on entry and another coroutine is waiting for it to become
@@ -323,7 +323,7 @@ Queue
          If the Queue was initialized with ``maxsize=0`` (the default), then
          :meth:`full()` is never ``True``.
 
-   .. method:: get()
+   .. coroutinemethod:: get()
 
       Remove and return an item from the queue. If queue is empty, wait until
       an item is available.
@@ -341,7 +341,7 @@ Queue
       Return an item if one is immediately available, else raise
       :exc:`QueueEmpty`.
 
-   .. method:: put(item)
+   .. coroutinemethod:: put(item)
 
       Put an item into the queue. If the queue is full, wait until a free slot
       is available before adding item.
@@ -395,7 +395,7 @@ JoinableQueue
    A subclass of :class:`Queue` with :meth:`task_done` and :meth:`join`
    methods.
 
-   .. method:: join()
+   .. coroutinemethod:: join()
 
       Block until all items in the queue have been gotten and processed.
 
diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst
index 3008c86..edc05c3 100644
--- a/Doc/library/asyncio-task.rst
+++ b/Doc/library/asyncio-task.rst
@@ -545,7 +545,7 @@ Task functions
    Return ``True`` if *func* is a decorated :ref:`coroutine function
    <coroutine>`.
 
-.. function:: sleep(delay, result=None, \*, loop=None)
+.. coroutinefunction:: sleep(delay, result=None, \*, loop=None)
 
    Create a :ref:`coroutine <coroutine>` that completes after a given
    time (in seconds).  If *result* is provided, it is produced to the caller
@@ -554,6 +554,8 @@ Task functions
    The resolution of the sleep depends on the :ref:`granularity of the event
    loop <asyncio-delayed-calls>`.
 
+   This function is a :ref:`coroutine <coroutine>`.
+
 .. function:: shield(arg, \*, loop=None)
 
    Wait for a future, shielding it from cancellation.
@@ -581,7 +583,7 @@ Task functions
        except CancelledError:
            res = None
 
-.. function:: wait(futures, \*, loop=None, timeout=None, return_when=ALL_COMPLETED)
+.. coroutinefunction:: wait(futures, \*, loop=None, timeout=None, return_when=ALL_COMPLETED)
 
    Wait for the Futures and coroutine objects given by the sequence *futures*
    to complete.  Coroutines will be wrapped in Tasks. Returns two sets of
@@ -626,7 +628,7 @@ Task functions
       when the timeout occurs are returned in the second set.
 
 
-.. function:: wait_for(fut, timeout, \*, loop=None)
+.. coroutinefunction:: wait_for(fut, timeout, \*, loop=None)
 
    Wait for the single :class:`Future` or :ref:`coroutine object <coroutine>`
    to complete with timeout. If *timeout* is ``None``, block until the future
diff --git a/Doc/tools/extensions/pyspecific.py b/Doc/tools/extensions/pyspecific.py
index 7baacc4..17b3c82 100644
--- a/Doc/tools/extensions/pyspecific.py
+++ b/Doc/tools/extensions/pyspecific.py
@@ -145,6 +145,30 @@ class PyDecoratorMethod(PyDecoratorMixin, PyClassmember):
         return PyClassmember.run(self)
 
 
+class PyCoroutineMixin(object):
+    def handle_signature(self, sig, signode):
+        ret = super(PyCoroutineMixin, self).handle_signature(sig, signode)
+#        signode.insert(0, addnodes.desc_addname('coroutine ', 'coroutine '))
+        signode.insert(0, addnodes.desc_annotation('coroutine ', 'coroutine '))
+        return ret
+
+    def needs_arglist(self):
+        return False
+
+
+class PyCoroutineFunction(PyCoroutineMixin, PyModulelevel):
+    def run(self):
+        # a decorator function is a function after all
+        self.name = 'py:function'
+        return PyModulelevel.run(self)
+
+
+class PyCoroutineMethod(PyCoroutineMixin, PyClassmember):
+    def run(self):
+        self.name = 'py:method'
+        return PyClassmember.run(self)
+
+
 # Support for documenting version of removal in deprecations
 
 class DeprecatedRemoved(Directive):
@@ -347,5 +371,7 @@ def setup(app):
     app.add_description_unit('2to3fixer', '2to3fixer', '%s (2to3 fixer)')
     app.add_directive_to_domain('py', 'decorator', PyDecoratorFunction)
     app.add_directive_to_domain('py', 'decoratormethod', PyDecoratorMethod)
+    app.add_directive_to_domain('py', 'coroutinefunction', PyCoroutineFunction)
+    app.add_directive_to_domain('py', 'coroutinemethod', PyCoroutineMethod)
     app.add_directive('miscnews', MiscNews)
     return {'version': '1.0', 'parallel_read_safe': True}