Tulip issue 83: document more asyncio functions in docstrings

vstinner · vstinner · commit d143209d7f82 · 2014-06-19T17:11:49.000+02:00
diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst
@@ -311,11 +311,10 @@ 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)
 
-   A :ref:`coroutine <coroutine>` method which creates a TCP server bound to
-   host and port.
+   Create a TCP server bound to host and port. Return an
+   :class:`AbstractServer` object which can be used to stop the service.
 
-   The return value is a :class:`AbstractServer` object which can be used to stop
-   the service.
+   This method is a :ref:`coroutine <coroutine>`.
 
    If *host* is an empty string or None all interfaces are assumed
    and a list of multiple sockets will be returned (most likely
diff --git a/Lib/asyncio/base_events.py b/Lib/asyncio/base_events.py
@@ -320,7 +320,7 @@ def _assert_is_current_event_loop(self):
                 "than the current one")
 
     def call_soon_threadsafe(self, callback, *args):
-        """XXX"""
+        """Like call_soon(), but thread safe."""
         handle = self._call_soon(callback, args, check_loop=False)
         self._write_to_self()
         return handle
@@ -358,7 +358,17 @@ def getnameinfo(self, sockaddr, flags=0):
     def create_connection(self, protocol_factory, host=None, port=None, *,
                           ssl=None, family=0, proto=0, flags=0, sock=None,
                           local_addr=None, server_hostname=None):
-        """XXX"""
+        """Connect to a TCP server.
+
+        Create a streaming transport connection to a given Internet host and
+        port: socket family AF_INET or socket.AF_INET6 depending on host (or
+        family if specified), socket type SOCK_STREAM. protocol_factory must be
+        a callable returning a protocol instance.
+
+        This method is a coroutine which will try to establish the connection
+        in the background.  When successful, the coroutine returns a
+        (transport, protocol) pair.
+        """
         if server_hostname is not None and not ssl:
             raise ValueError('server_hostname is only meaningful with ssl')
 
@@ -557,7 +567,12 @@ def create_server(self, protocol_factory, host=None, port=None,
                       backlog=100,
                       ssl=None,
                       reuse_address=None):
-        """XXX"""
+        """Create a TCP server bound to host and port.
+
+        Return an AbstractServer object which can be used to stop the service.
+
+        This method is a coroutine.
+        """
         if isinstance(ssl, bool):
             raise TypeError('ssl argument must be an SSLContext or None')
         if host is not None or port is not None:
diff --git a/Lib/asyncio/selector_events.py b/Lib/asyncio/selector_events.py
@@ -226,7 +226,14 @@ def remove_writer(self, fd):
                 return False
 
     def sock_recv(self, sock, n):
-        """XXX"""
+        """Receive data from the socket.
+
+        The return value is a bytes object representing the data received.
+        The maximum amount of data to be received at once is specified by
+        nbytes.
+
+        This method is a coroutine.
+        """
         fut = futures.Future(loop=self)
         self._sock_recv(fut, False, sock, n)
         return fut
@@ -253,7 +260,16 @@ def _sock_recv(self, fut, registered, sock, n):
             fut.set_result(data)
 
     def sock_sendall(self, sock, data):
-        """XXX"""
+        """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 been sent or an
+        error occurs. None is returned on success. On error, an exception is
+        raised, and there is no way to determine how much data, if any, was
+        successfully processed by the receiving end of the connection.
+
+        This method is a coroutine.
+        """
         fut = futures.Future(loop=self)
         if data:
             self._sock_sendall(fut, False, sock, data)
@@ -285,7 +301,16 @@ def _sock_sendall(self, fut, registered, sock, data):
             self.add_writer(fd, self._sock_sendall, fut, True, sock, data)
 
     def sock_connect(self, sock, address):
-        """XXX"""
+        """Connect to a remote socket at address.
+
+        The address must be already resolved to avoid the trap of hanging the
+        entire event loop when the address requires doing a DNS lookup. For
+        example, it must be an IP address, not an hostname, for AF_INET and
+        AF_INET6 address families. Use getaddrinfo() to resolve the hostname
+        asynchronously.
+
+        This method is a coroutine.
+        """
         fut = futures.Future(loop=self)
         try:
             base_events._check_resolved_address(sock, address)
@@ -318,7 +343,15 @@ def _sock_connect(self, fut, registered, sock, address):
             fut.set_result(None)
 
     def sock_accept(self, sock):
-        """XXX"""
+        """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 is a new socket
+        object usable to send and receive data on the connection, and address
+        is the address bound to the socket on the other end of the connection.
+
+        This method is a coroutine.
+        """
         fut = futures.Future(loop=self)
         self._sock_accept(fut, False, sock)
         return fut
