Use autodoc for SSL.Connectiondocstrings

2 files changed, 123 insertions, 433 deletions

diff --git a/doc/api/ssl.rst b/doc/api/ssl.rst
index 8a0bd64..c678b28 100644
--- a/doc/api/ssl.rst
+++ b/doc/api/ssl.rst
@@ -236,364 +236,8 @@ Connection objects
 
 Connection objects have the following methods:
 
-.. py:method:: Connection.accept()
-
-    Call the :py:meth:`accept` method of the underlying socket and set up SSL on the
-    returned socket, using the Context object supplied to this Connection object at
-    creation. Returns a pair *(conn, address)*. where *conn* is the new
-    Connection object created, and *address* is as returned by the socket's
-    :py:meth:`accept`.
-
-
-.. py:method:: Connection.bind(address)
-
-    Call the :py:meth:`bind` method of the underlying socket.
-
-
-.. py:method:: Connection.close()
-
-    Call the :py:meth:`close` method of the underlying socket. Note: If you want
-    correct SSL closure, you need to call the :py:meth:`shutdown` method first.
-
-
-.. py:method:: Connection.connect(address)
-
-    Call the :py:meth:`connect` method of the underlying socket and set up SSL on the
-    socket, using the Context object supplied to this Connection object at
-    creation.
-
-
-.. py:method:: Connection.connect_ex(address)
-
-    Call the :py:meth:`connect_ex` method of the underlying socket and set up SSL on
-    the socket, using the Context object supplied to this Connection object at
-    creation. Note that if the :py:meth:`connect_ex` method of the socket doesn't
-    return 0, SSL won't be initialized.
-
-
-.. py:method:: Connection.do_handshake()
-
-    Perform an SSL handshake (usually called after :py:meth:`renegotiate` or one of
-    :py:meth:`set_accept_state` or :py:meth:`set_accept_state`). This can raise the
-    same exceptions as :py:meth:`send` and :py:meth:`recv`.
-
-
-.. py:method:: Connection.fileno()
-
-    Retrieve the file descriptor number for the underlying socket.
-
-
-.. py:method:: Connection.listen(backlog)
-
-    Call the :py:meth:`listen` method of the underlying socket.
-
-
-.. py:method:: Connection.get_app_data()
-
-    Retrieve application data as set by :py:meth:`set_app_data`.
-
-
-.. automethod:: Connection.get_cipher_list
-
-
-.. py:method:: Connection.get_protocol_version()
-
-    Retrieve the version of the SSL or TLS protocol used by the Connection.
-    For example, it will return ``0x769`` for connections made over TLS
-    version 1.
-
-
-.. py:method:: Connection.get_protocol_version_name()
-
-    Retrieve the version of the SSL or TLS protocol used by the Connection as
-    a unicode string. For example, it will return ``TLSv1`` for connections
-    made over TLS version 1, or ``Unknown`` for connections that were not
-    successfully established.
-
-
-.. py:method:: Connection.get_client_ca_list()
-
-    Retrieve the list of preferred client certificate issuers sent by the server
-    as :py:class:`OpenSSL.crypto.X509Name` objects.
-
-    If this is a client :py:class:`Connection`, the list will be empty until the
-    connection with the server is established.
-
-    If this is a server :py:class:`Connection`, return the list of certificate
-    authorities that will be sent or has been sent to the client, as controlled
-    by this :py:class:`Connection`'s :py:class:`Context`.
-
-    .. versionadded:: 0.10
-
-
-.. py:method:: Connection.get_context()
-
-    Retrieve the Context object associated with this Connection.
-
-
-.. py:method:: Connection.set_context(context)
-
-    Specify a replacement Context object for this Connection.
-
-
-.. py:method:: Connection.get_peer_certificate()
-
-    Retrieve the other side's certificate (if any)
-
-
-.. py:method:: Connection.get_peer_cert_chain()
-
-    Retrieve the tuple of the other side's certificate chain (if any)
-
-
-.. py:method:: Connection.getpeername()
-
-    Call the :py:meth:`getpeername` method of the underlying socket.
-
-
-.. py:method:: Connection.getsockname()
-
-    Call the :py:meth:`getsockname` method of the underlying socket.
-
-
-.. py:method:: Connection.getsockopt(level, optname[, buflen])
-
-    Call the :py:meth:`getsockopt` method of the underlying socket.
-
-
-.. py:method:: Connection.pending()
-
-    Retrieve the number of bytes that can be safely read from the SSL buffer
-    (**not** the underlying transport buffer).
-
-
-.. py:method:: Connection.recv(bufsize[, flags])
-
-    Receive data from the Connection. The return value is a string representing the
-    data received. The maximum amount of data to be received at once, is specified
-    by *bufsize*. The only supported flag is ``MSG_PEEK``, all other flags are
-    ignored.
-
-
-.. py:method:: Connection.recv_into(buffer[, nbytes[, flags]])
-
-    Receive data from the Connection and copy it directly into the provided
-    buffer. The return value is the number of bytes read from the connection.
-    The maximum amount of data to be received at once is specified by *nbytes*.
-    The only supported flag is ``MSG_PEEK``, all other flags are ignored.
-
-.. py:method:: Connection.bio_write(bytes)
-
-    If the Connection was created with a memory BIO, this method can be used to add
-    bytes to the read end of that memory BIO.  The Connection can then read the
-    bytes (for example, in response to a call to :py:meth:`recv`).
-
-
-.. automethod:: Connection.renegotiate
-
-.. automethod:: Connection.renegotiate_pending
-
-.. automethod:: Connection.total_renegotiations
-
-.. py:method:: Connection.send(string)
-
-    Send the *string* data to the Connection.
-
-
-.. py:method:: Connection.bio_read(bufsize)
-
-    If the Connection was created with a memory BIO, this method can be used to
-    read bytes from the write end of that memory BIO.  Many Connection methods will
-    add bytes which must be read in this manner or the buffer will eventually fill
-    up and the Connection will be able to take no further actions.
-
-
-.. py:method:: Connection.sendall(string)
-
-    Send all of the *string* data to the Connection. This calls :py:meth:`send`
-    repeatedly until all data is sent. If an error occurs, it's impossible to tell
-    how much data has been sent.
-
-
-.. py:method:: Connection.set_accept_state()
-
-    Set the connection to work in server mode. The handshake will be handled
-    automatically by read/write.
-
-
-.. py:method:: Connection.set_app_data(data)
-
-    Associate *data* with this Connection object. *data* can be retrieved
-    later using the :py:meth:`get_app_data` method.
-
-
-.. py:method:: Connection.set_connect_state()
-
-    Set the connection to work in client mode. The handshake will be handled
-    automatically by read/write.
-
-
-.. py:method:: Connection.setblocking(flag)
-
-    Call the :py:meth:`setblocking` method of the underlying socket.
-
-
-.. py:method:: Connection.setsockopt(level, optname, value)
-
-    Call the :py:meth:`setsockopt` method of the underlying socket.
-
-
-.. py:method:: Connection.shutdown()
-
-    Send the shutdown message to the Connection. Returns true if the shutdown
-    message exchange is completed and false otherwise (in which case you call
-    :py:meth:`recv` or :py:meth:`send` when the connection becomes
-    readable/writeable.
-
-
-.. py:method:: Connection.get_shutdown()
-
-    Get the shutdown state of the Connection.  Returns a bitvector of either or
-    both of *SENT_SHUTDOWN* and *RECEIVED_SHUTDOWN*.
-
-
-.. py:method:: Connection.set_shutdown(state)
-
-    Set the shutdown state of the Connection.  *state* is a bitvector of
-    either or both of *SENT_SHUTDOWN* and *RECEIVED_SHUTDOWN*.
-
-
-.. py:method:: Connection.sock_shutdown(how)
-
-    Call the :py:meth:`shutdown` method of the underlying socket.
-
-
-.. py:method:: Connection.bio_shutdown()
-
-    If the Connection was created with a memory BIO, this method can be used to
-    indicate that *end of file* has been reached on the read end of that memory
-    BIO.
-
-
-.. automethod:: Connection.get_state_string
-
-.. py:method:: Connection.client_random()
-
-    Retrieve the random value used with the client hello message.
-
-
-.. py:method:: Connection.server_random()
-
-    Retrieve the random value used with the server hello message.
-
-
-.. py:method:: Connection.master_key()
-
-    Retrieve the value of the master key for this session.
-
-
-.. py:method:: Connection.want_read()
-
-    Checks if more data has to be read from the transport layer to complete an
-    operation.
-
-
-.. py:method:: Connection.want_write()
-
-    Checks if there is data to write to the transport layer to complete an
-    operation.
-
-
-.. py:method:: Connection.set_tlsext_host_name(name)
-
-    Specify the byte string to send as the server name in the client hello message.
-
-    .. versionadded:: 0.13
-
-
-.. py:method:: Connection.get_servername()
-
-    Get the value of the server name received in the client hello message.
-
-    .. versionadded:: 0.13
-
-
-.. py:method:: Connection.get_session()
-
-    Get a :py:class:`Session` instance representing the SSL session in use by
-    the connection, or :py:obj:`None` if there is no session.
-
-    .. versionadded:: 0.14
-
-
-.. py:method:: Connection.set_session(session)
-
-    Set a new SSL session (using a :py:class:`Session` instance) to be used by
-    the connection.
-
-    .. versionadded:: 0.14
-
-
-.. py:method:: Connection.get_finished()
-
-    Obtain latest TLS Finished message that we sent, or :py:obj:`None` if
-    handshake is not completed.
-
-    .. versionadded:: 0.15
-
-
-.. py:method:: Connection.get_peer_finished()
-
-    Obtain latest TLS Finished message that we expected from peer, or
-    :py:obj:`None` if handshake is not completed.
-
-    .. versionadded:: 0.15
-
-
-.. py:method:: Connection.get_cipher_name()
-
-    Obtain the name of the currently used cipher.
-
-    .. versionadded:: 0.15
-
-
-.. py:method:: Connection.get_cipher_bits()
-
-    Obtain the number of secret bits of the currently used cipher.
-
-    .. versionadded:: 0.15
-
-
-.. py:method:: Connection.get_cipher_version()
-
-    Obtain the protocol name of the currently used cipher.
-
-    .. versionadded:: 0.15
-
-
-.. py:method:: Connection.get_next_proto_negotiated():
-
-    Get the protocol that was negotiated by Next Protocol Negotiation. Returns
-    a bytestring of the protocol name. If no protocol has been negotiated yet,
-    returns an empty string.
-
-    .. versionadded:: 0.15
-
-.. py:method:: Connection.set_alpn_protos(protos)
-
-    Specify the protocols that the client is prepared to speak after the TLS
-    connection has been negotiated using Application Layer Protocol
-    Negotiation.
-
-    *protos* should be a list of protocols that the client is offering, each
-    as a bytestring. For example, ``[b'http/1.1', b'spdy/2']``.
-
-
-.. py:method:: Connection.get_alpn_proto_negotiated()
-
-    Get the protocol that was negotiated by Application Layer Protocol
-    Negotiation. Returns a bytestring of the protocol name. If no protocol has
-    been negotiated yet, returns an empty string.
+.. autoclass:: OpenSSL.SSL.Connection
+               :members:
 
 
 .. Rubric:: Footnotes
diff --git a/src/OpenSSL/SSL.py b/src/OpenSSL/SSL.py
index 9bff583..5def0aa 100644
--- a/src/OpenSSL/SSL.py
+++ b/src/OpenSSL/SSL.py
@@ -759,7 +759,7 @@ class Context(object):
 
         If capath is passed, it must be a directory prepared using the
         ``c_rehash`` tool included with OpenSSL.  Either, but not both, of
-        *pemfile* or *capath* may be :py:data:`None`.
+        *pemfile* or *capath* may be :data:`None`.
 
         :param cafile: In which file we can find the certificates (``bytes`` or
             ``unicode``).
@@ -1169,8 +1169,8 @@ class Context(object):
         Select a curve to use for ECDHE key exchange.
 
         :param curve: A curve object to use as returned by either
-            :py:meth:`OpenSSL.crypto.get_elliptic_curve` or
-            :py:meth:`OpenSSL.crypto.get_elliptic_curves`.
+            :meth:`OpenSSL.crypto.get_elliptic_curve` or
+            :meth:`OpenSSL.crypto.get_elliptic_curves`.
 
         :return: None
         """
@@ -1415,9 +1415,9 @@ class Context(object):
     @_requires_alpn
     def set_alpn_protos(self, protos):
         """
-        Specify the ALPN protocol list of the client.
-
-        These protocols are offered to the server during protocol negotiation.
+        Specify the protocols that the client is prepared to speak after the
+        TLS connection has been negotiated using Application Layer Protocol
+        Negotiation.
 
         :param protos: A list of the protocols to be offered to the server.
             This list should be a Python list of bytestrings representing the
@@ -1624,15 +1624,16 @@ class Connection(object):
 
     def get_context(self):
         """
-        Get session context
+        Retrieve the :class:`Context` object associated with this
+        :class:`Connection`.
         """
         return self._context
 
     def set_context(self, context):
         """
-        Switch this connection to a new session context
+        Switch this connection to a new session context.
 
-        :param context: A :py:class:`Context` instance giving the new session
+        :param context: A :class:`Context` instance giving the new session
             context to use.
         """
         if not isinstance(context, Context):
@@ -1647,7 +1648,9 @@ class Connection(object):
         Retrieve the servername extension value if provided in the client hello
         message, or None if there wasn't one.
 
-        :return: A byte string giving the server name or :py:data:`None`.
+        :return: A byte string giving the server name or :data:`None`.
+
+        .. versionadded:: 0.13
         """
         name = _lib.SSL_get_servername(
             self._ssl, _lib.TLSEXT_NAMETYPE_host_name
@@ -1663,6 +1666,8 @@ class Connection(object):
         Set the value of the servername extension to send in the client hello.
 
         :param name: A byte string giving the name.
+
+        .. versionadded:: 0.13
         """
         if not isinstance(name, bytes):
             raise TypeError("name must be a byte string")
@@ -1674,7 +1679,8 @@ class Connection(object):
 
     def pending(self):
         """
-        Get the number of bytes that can be safely read from the connection
+        Get the number of bytes that can be safely read from the SSL buffer
+        (**not** the underlying transport buffer).
 
         :return: The number of bytes available in the receive buffer.
         """
@@ -1764,8 +1770,8 @@ class Connection(object):
 
     def recv_into(self, buffer, nbytes=None, flags=None):
         """
-        Receive data on the connection and store the data into a buffer rather
-        than creating a new string.
+        Receive data on the connection and copy it directly into the provided
+        buffer, rather than creating a new string.
 
         :param buffer: The buffer to copy into.
         :param nbytes: (optional) The maximum number of bytes to read into the
@@ -1823,8 +1829,11 @@ class Connection(object):
 
     def bio_read(self, bufsiz):
         """
-        When using non-socket connections this function reads the "dirty" data
-        that would have traveled away on the network.
+        If the Connection was created with a memory BIO, this method can be
+        used to read bytes from the write end of that memory BIO.  Many
+        Connection methods will add bytes which must be read in this manner or
+        the buffer will eventually fill up and the Connection will be able to
+        take no further actions.
 
         :param bufsiz: The maximum number of bytes to read
         :return: The string read.
@@ -1844,8 +1853,10 @@ class Connection(object):
 
     def bio_write(self, buf):
         """
-        When using non-socket connections this function sends "dirty" data that
-        would have traveled in on the network.
+        If the Connection was created with a memory BIO, this method can be
+        used to add bytes to the read end of that memory BIO.  The Connection
+        can then read the bytes (for example, in response to a call to
+        :meth:`recv`).
 
         :param buf: The string to put into the memory BIO.
         :return: The number of bytes written
@@ -1874,8 +1885,9 @@ class Connection(object):
 
     def do_handshake(self):
         """
-        Perform an SSL handshake (usually called after renegotiate() or one of
-        set_*_state()). This can raise the same exceptions as send and recv.
+        Perform an SSL handshake (usually called after :meth:`renegotiate` or
+        one of :meth:`set_accept_state` or :meth:`set_accept_state`). This can
+        raise the same exceptions as :meth:`send` and :meth:`recv`.
 
         :return: None.
         """
@@ -1903,7 +1915,9 @@ class Connection(object):
 
     def connect(self, addr):
         """
-        Connect to remote host and set up client-side SSL
+        Call the :meth:`connect` method of the underlying socket and set up SSL
+        on the socket, using the :class:`Context` object supplied to this
+        :class:`Connection` object at creation.
 
         :param addr: A remote address
         :return: What the socket's connect method returns
@@ -1913,8 +1927,10 @@ class Connection(object):
 
     def connect_ex(self, addr):
         """
-        Connect to remote host and set up client-side SSL. Note that if the
-        socket's connect_ex method doesn't return 0, SSL won't be initialized.
+        Call the :meth:`connect_ex` method of the underlying socket and set up
+        SSL on the socket, using the Context object supplied to this Connection
+        object at creation. Note that if the :meth:`connect_ex` method of the
+        socket doesn't return 0, SSL won't be initialized.
 
         :param addr: A remove address
         :return: What the socket's connect_ex method returns
@@ -1925,10 +1941,13 @@ class Connection(object):
 
     def accept(self):
         """
-        Accept incoming connection and set up SSL on it
+        Call the :meth:`accept` method of the underlying socket and set up SSL
+        on the returned socket, using the Context object supplied to this
+        :class:`Connection` object at creation.
 
-        :return: A (conn,addr) pair where conn is a Connection and addr is an
-                 address
+        :return: A *(conn, addr)* pair where *conn* is the new
+            :class:`Connection` object created, and *address* is as returned by
+            the socket's :meth:`accept`.
         """
         client, addr = self._socket.accept()
         conn = Connection(self._context, client)
@@ -1937,8 +1956,9 @@ class Connection(object):
 
     def bio_shutdown(self):
         """
-        When using non-socket connections this function signals end of
-        data on the input for this connection.
+        If the Connection was created with a memory BIO, this method can be
+        used to indicate that *end of file* has been reached on the read end of
+        that memory BIO.
 
         :return: None
         """
@@ -1949,11 +1969,12 @@ class Connection(object):
 
     def shutdown(self):
         """
-        Send closure alert
+        Send the shutdown message to the Connection.
 
         :return: True if the shutdown completed successfully (i.e. both sides
-                 have sent closure alerts), false otherwise (i.e. you have to
-                 wait for a ZeroReturnError on a recv() method call
+                 have sent closure alerts), False otherwise (in which case you
+                 call :meth:`recv` or :meth:`send` when the connection becomes
+                 readable/writeable).
         """
         result = _lib.SSL_shutdown(self._ssl)
         if result < 0:
@@ -1981,12 +2002,14 @@ class Connection(object):
         """
         Get CAs whose certificates are suggested for client authentication.
 
-        :return: If this is a server connection, a list of X509Names
-            representing the acceptable CAs as set by
-            :py:meth:`OpenSSL.SSL.Context.set_client_ca_list` or
-            :py:meth:`OpenSSL.SSL.Context.add_client_ca`.  If this is a client
-            connection, the list of such X509Names sent by the server, or an
-            empty list if that has not yet happened.
+        :return: If this is a server connection, the list of certificate
+            authorities that will be sent or has been sent to the client, as
+            controlled by this :class:`Connection`'s :class:`Context`.
+
+            If this is a client connection, the list will be empty until the
+            connection with the server is established.
+
+        .. versionadded:: 0.10
         """
         ca_names = _lib.SSL_get_client_CA_list(self._ssl)
         if ca_names == _ffi.NULL:
@@ -2016,7 +2039,7 @@ class Connection(object):
 
     def get_app_data(self):
         """
-        Get application data
+        Retrieve application data as set by :meth:`set_app_data`.
 
         :return: The application data
         """
@@ -2026,14 +2049,14 @@ class Connection(object):
         """
         Set application data
 
-        :param data - The application data
+        :param data: The application data
         :return: None
         """
         self._app_data = data
 
     def get_shutdown(self):
         """
-        Get shutdown state
+        Get the shutdown state of the Connection.
 
         :return: The shutdown state, a bitvector of SENT_SHUTDOWN,
             RECEIVED_SHUTDOWN.
@@ -2042,9 +2065,9 @@ class Connection(object):
 
     def set_shutdown(self, state):
         """
-        Set shutdown state
+        Set the shutdown state of the Connection.
 
-        :param state - bitvector of SENT_SHUTDOWN, RECEIVED_SHUTDOWN.
+        :param state: bitvector of SENT_SHUTDOWN, RECEIVED_SHUTDOWN.
         :return: None
         """
         if not isinstance(state, integer_types):
@@ -2063,7 +2086,7 @@ class Connection(object):
 
     def server_random(self):
         """
-        Get a copy of the server hello nonce.
+        Retrieve the random value used with the server hello message.
 
         :return: A string representing the state
         """
@@ -2078,7 +2101,7 @@ class Connection(object):
 
     def client_random(self):
         """
-        Get a copy of the client hello nonce.
+        Retrieve the random value used with the client hello message.
 
         :return: A string representing the state
         """
@@ -2094,7 +2117,7 @@ class Connection(object):
 
     def master_key(self):
         """
-        Get a copy of the master key.
+        Retrieve the value of the master key for this session.
 
         :return: A string representing the state
         """
@@ -2112,10 +2135,10 @@ class Connection(object):
         """
         Obtain keying material for application use.
 
-        :param label - a disambiguating label string as described in RFC 5705
-        :param olen - the length of the exported key material in bytes
-        :param context - a per-association context value
-        :return the exported key material bytes or None
+        :param: label - a disambiguating label string as described in RFC 5705
+        :param: olen - the length of the exported key material in bytes
+        :param: context - a per-association context value
+        :return: the exported key material bytes or None
         """
         outp = _no_zero_allocator("unsigned char[]", olen)
         context_buf = _ffi.NULL
@@ -2134,7 +2157,8 @@ class Connection(object):
 
     def sock_shutdown(self, *args, **kwargs):
         """
-        See shutdown(2)
+        Call the :meth:`shutdown` method of the underlying socket.
+        See :manpage:`shutdown(2)`.
 
         :return: What the socket's shutdown() method returns
         """
@@ -2210,8 +2234,10 @@ class Connection(object):
         """
         Returns the Session currently used.
 
-        @return: An instance of :py:class:`OpenSSL.SSL.Session` or
-            :py:obj:`None` if no session exists.
+        :return: An instance of :class:`OpenSSL.SSL.Session` or
+            :obj:`None` if no session exists.
+
+        .. versionadded:: 0.14
         """
         session = _lib.SSL_get1_session(self._ssl)
         if session == _ffi.NULL:
@@ -2227,6 +2253,8 @@ class Connection(object):
 
         :param session: A Session instance representing the session to use.
         :returns: None
+
+        .. versionadded:: 0.14
         """
         if not isinstance(session, Session):
             raise TypeError("session must be a Session instance")
@@ -2237,15 +2265,15 @@ class Connection(object):
 
     def _get_finished_message(self, function):
         """
-        Helper to implement :py:meth:`get_finished` and
-        :py:meth:`get_peer_finished`.
+        Helper to implement :meth:`get_finished` and
+        :meth:`get_peer_finished`.
 
-        :param function: Either :py:data:`SSL_get_finished`: or
-            :py:data:`SSL_get_peer_finished`.
+        :param function: Either :data:`SSL_get_finished`: or
+            :data:`SSL_get_peer_finished`.
 
-        :return: :py:data:`None` if the desired message has not yet been
+        :return: :data:`None` if the desired message has not yet been
             received, otherwise the contents of the message.
-        :rtype: :py:class:`bytes` or :py:class:`NoneType`
+        :rtype: :class:`bytes` or :class:`NoneType`
         """
         # The OpenSSL documentation says nothing about what might happen if the
         # count argument given is zero.  Specifically, it doesn't say whether
@@ -2271,21 +2299,25 @@ class Connection(object):
 
     def get_finished(self):
         """
-        Obtain the latest `handshake finished` message sent to the peer.
+        Obtain the latest TLS Finished message that we sent.
 
-        :return: The contents of the message or :py:obj:`None` if the TLS
+        :return: The contents of the message or :obj:`None` if the TLS
             handshake has not yet completed.
-        :rtype: :py:class:`bytes` or :py:class:`NoneType`
+        :rtype: :class:`bytes` or :class:`NoneType`
+
+        .. versionadded:: 0.15
         """
         return self._get_finished_message(_lib.SSL_get_finished)
 
     def get_peer_finished(self):
         """
-        Obtain the latest `handshake finished` message received from the peer.
+        Obtain the latest TLS Finished message that we received from the peer.
 
-        :return: The contents of the message or :py:obj:`None` if the TLS
+        :return: The contents of the message or :obj:`None` if the TLS
             handshake has not yet completed.
-        :rtype: :py:class:`bytes` or :py:class:`NoneType`
+        :rtype: :class:`bytes` or :class:`NoneType`
+
+        .. versionadded:: 0.15
         """
         return self._get_finished_message(_lib.SSL_get_peer_finished)
 
@@ -2293,9 +2325,11 @@ class Connection(object):
         """
         Obtain the name of the currently used cipher.
 
-        :returns: The name of the currently used cipher or :py:obj:`None`
+        :returns: The name of the currently used cipher or :obj:`None`
             if no connection has been established.
-        :rtype: :py:class:`unicode` or :py:class:`NoneType`
+        :rtype: :class:`unicode` or :class:`NoneType`
+
+        .. versionadded:: 0.15
         """
         cipher = _lib.SSL_get_current_cipher(self._ssl)
         if cipher == _ffi.NULL:
@@ -2309,8 +2343,10 @@ class Connection(object):
         Obtain the number of secret bits of the currently used cipher.
 
         :returns: The number of secret bits of the currently used cipher
-            or :py:obj:`None` if no connection has been established.
-        :rtype: :py:class:`int` or :py:class:`NoneType`
+            or :obj:`None` if no connection has been established.
+        :rtype: :class:`int` or :class:`NoneType`
+
+        .. versionadded:: 0.15
         """
         cipher = _lib.SSL_get_current_cipher(self._ssl)
         if cipher == _ffi.NULL:
@@ -2323,8 +2359,10 @@ class Connection(object):
         Obtain the protocol version of the currently used cipher.
 
         :returns: The protocol name of the currently used cipher
-            or :py:obj:`None` if no connection has been established.
-        :rtype: :py:class:`unicode` or :py:class:`NoneType`
+            or :obj:`None` if no connection has been established.
+        :rtype: :class:`unicode` or :class:`NoneType`
+
+        .. versionadded:: 0.15
         """
         cipher = _lib.SSL_get_current_cipher(self._ssl)
         if cipher == _ffi.NULL:
@@ -2335,23 +2373,23 @@ class Connection(object):
 
     def get_protocol_version_name(self):
         """
-        Obtain the protocol version of the current connection.
+        Retrieve the protocol version of the current connection.
 
         :returns: The TLS version of the current connection, for example
             the value for TLS 1.2 would be ``TLSv1.2``or ``Unknown``
             for connections that were not successfully established.
-        :rtype: :py:class:`unicode`
+        :rtype: :class:`unicode`
         """
         version = _ffi.string(_lib.SSL_get_version(self._ssl))
         return version.decode("utf-8")
 
     def get_protocol_version(self):
         """
-        Obtain the protocol version of the current connection.
+        Retrieve the SSL or TLS protocol version of the current connection.
 
-        :returns: The TLS version of the current connection, for example
-            the value for TLS 1 would be 0x769.
-        :rtype: :py:class:`int`
+        :returns: The TLS version of the current connection.  For example,
+            it will return ``0x769`` for connections made over TLS version 1.
+        :rtype: :class:`int`
         """
         version = _lib.SSL_version(self._ssl)
         return version
@@ -2360,6 +2398,11 @@ class Connection(object):
     def get_next_proto_negotiated(self):
         """
         Get the protocol that was negotiated by NPN.
+
+        :returns: A bytestring of the protocol name.  If no protocol has been
+            negotiated yet, returns an empty string.
+
+        .. versionadded:: 0.15
         """
         data = _ffi.new("unsigned char **")
         data_len = _ffi.new("unsigned int *")
@@ -2394,6 +2437,9 @@ class Connection(object):
     def get_alpn_proto_negotiated(self):
         """
         Get the protocol that was negotiated by ALPN.
+
+        :returns: A bytestring of the protocol name.  If no protocol has been
+            negotiated yet, returns an empty string.
         """
         data = _ffi.new("unsigned char **")
         data_len = _ffi.new("unsigned int *")