Use autofocus for all module documentation/docstrings (#737)

* Use autodoc for OpenSSL.crypto

* Use autodoc for the SSL.Context class

* Use autodoc for SSL.Connection

4 files changed, 282 insertions, 881 deletions

diff --git a/doc/api/crypto.rst b/doc/api/crypto.rst
index 7b21d4f..5cd7fd9 100644
--- a/doc/api/crypto.rst
+++ b/doc/api/crypto.rst
@@ -16,27 +16,9 @@
 Elliptic curves
 ---------------
 
-.. py:function:: get_elliptic_curves
-
-    Return a set of objects representing the elliptic curves supported in the
-    OpenSSL build in use.
-
-    The curve objects have a :py:class:`unicode` ``name`` attribute by which
-    they identify themselves.
-
-    The curve objects are useful as values for the argument accepted by
-    :py:meth:`Context.set_tmp_ecdh` to specify which elliptical curve should be
-    used for ECDHE key exchange.
-
-
-.. py:function:: get_elliptic_curve(name)
-
-    Return a single curve object selected by *name*.
-
-    See :py:func:`get_elliptic_curves` for information about curve objects.
-
-    If the named curve is not supported then :py:class:`ValueError` is raised.
+.. autofunction:: get_elliptic_curves
 
+.. autofunction:: get_elliptic_curve
 
 Serialization and deserialization
 ---------------------------------
@@ -54,42 +36,23 @@ The following serialization functions take one of these constants to determine t
 Certificates
 ~~~~~~~~~~~~
 
-.. py:function:: dump_certificate(type, cert)
-
-    Dump the certificate *cert* into a buffer string encoded with the type
-    *type*.
-
-.. py:function:: load_certificate(type, buffer)
+.. autofunction:: dump_certificate
 
-    Load a certificate (X509) from the string *buffer* encoded with the
-    type *type*.
+.. autofunction:: load_certificate
 
 Certificate signing requests
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. py:function:: dump_certificate_request(type, req)
+.. autofunction:: dump_certificate_request
 
-    Dump the certificate request *req* into a buffer string encoded with the
-    type *type*.
-
-.. py:function:: load_certificate_request(type, buffer)
-
-    Load a certificate request (X509Req) from the string *buffer* encoded with
-    the type *type*.
+.. autofunction:: load_certificate_request
 
 Private keys
 ~~~~~~~~~~~~
 
 .. autofunction:: dump_privatekey
 
-.. py:function:: load_privatekey(type, buffer[, passphrase])
-
-    Load a private key (PKey) from the string *buffer* encoded with the type
-    *type* (must be one of :py:const:`FILETYPE_PEM` and
-    :py:const:`FILETYPE_ASN1`).
-
-    *passphrase* must be either a string or a callback for providing the pass
-    phrase.
+.. autofunction:: load_privatekey
 
 Public keys
 ~~~~~~~~~~~
@@ -103,53 +66,18 @@ Certificate revocation lists
 
 .. autofunction:: dump_crl
 
-.. py:function:: load_crl(type, buffer)
-
-    Load Certificate Revocation List (CRL) data from a string *buffer*.
-    *buffer* encoded with the type *type*.  The type *type* must either
-    :py:const:`FILETYPE_PEM` or :py:const:`FILETYPE_ASN1`).
-
-
-.. py:function:: load_pkcs7_data(type, buffer)
-
-    Load pkcs7 data from the string *buffer* encoded with the type
-    *type*. The type *type* must either :py:const:`FILETYPE_PEM` or
-    :py:const:`FILETYPE_ASN1`).
-
+.. autofunction:: load_crl
 
-.. py:function:: load_pkcs12(buffer[, passphrase])
+.. autofunction:: load_pkcs7_data
 
-    Load pkcs12 data from the string *buffer*. If the pkcs12 structure is
-    encrypted, a *passphrase* must be included.  The MAC is always
-    checked and thus required.
-
-    See also the man page for the C function :py:func:`PKCS12_parse`.
+.. autofunction:: load_pkcs12
 
 Signing and verifying signatures
 --------------------------------
 
-.. py:function:: sign(key, data, digest)
-
-    Sign a data string using the given key and message digest.
-
-    *key* is a :py:class:`PKey` instance.  *data* is a ``str`` instance.
-    *digest* is a ``str`` naming a supported message digest type, for example
-    :py:const:`b"sha256"`.
-
-    .. versionadded:: 0.11
-
+.. autofunction:: sign
 
-.. py:function:: verify(certificate, signature, data, digest)
-
-    Verify the signature for a data string.
-
-    *certificate* is a :py:class:`X509` instance corresponding to the private
-    key which generated the signature.  *signature* is a *str* instance giving
-    the signature itself.  *data* is a *str* instance giving the data to which
-    the signature applies.  *digest* is a *str* instance naming the message
-    digest type of the signature, for example :py:const:`b"sha256"`.
-
-    .. versionadded:: 0.11
+.. autofunction:: verify
 
 
 .. _openssl-x509:
@@ -243,25 +171,8 @@ PKCS7 objects
 
 PKCS7 objects have the following methods:
 
-.. py:method:: PKCS7.type_is_signed()
-
-    FIXME
-
-.. py:method:: PKCS7.type_is_enveloped()
-
-    FIXME
-
-.. py:method:: PKCS7.type_is_signedAndEnveloped()
-
-    FIXME
-
-.. py:method:: PKCS7.type_is_data()
-
-    FIXME
-
-.. py:method:: PKCS7.get_type_name()
-
-    Get the type name of the PKCS7.
+.. autoclass:: PKCS7
+               :members:
 
 .. _openssl-pkcs12:
 
diff --git a/doc/api/ssl.rst b/doc/api/ssl.rst
index d892dbb..c678b28 100644
--- a/doc/api/ssl.rst
+++ b/doc/api/ssl.rst
@@ -118,11 +118,7 @@ Context, Connection.
     for details.
 
 
-.. py:function:: SSLeay_version(type)
-
-    Retrieve a string describing some aspect of the underlying OpenSSL version.  The
-    type passed in should be one of the :py:const:`SSLEAY_*` constants defined in
-    this module.
+.. autofunction:: SSLeay_version
 
 
 .. py:data:: ContextType
@@ -130,23 +126,9 @@ Context, Connection.
     See :py:class:`Context`.
 
 
-.. py:class:: Context(method)
-
-    A class representing SSL contexts.  Contexts define the parameters of one or
-    more SSL connections.
-
-    *method* should be :py:const:`SSLv2_METHOD`, :py:const:`SSLv3_METHOD`,
-    :py:const:`SSLv23_METHOD`, :py:const:`TLSv1_METHOD`, :py:const:`TLSv1_1_METHOD`,
-    or :py:const:`TLSv1_2_METHOD`.
-
-
-.. py:class:: Session()
+.. autoclass:: Context
 
-    A class representing an SSL session.  A session defines certain connection
-    parameters which may be re-used to speed up the setup of subsequent
-    connections.
-
-    .. versionadded:: 0.14
+.. autoclass:: Session
 
 
 .. py:data:: ConnectionType
@@ -236,283 +218,8 @@ Context objects
 
 Context objects have the following methods:
 
-.. :py:class:: OpenSSL.SSL.Context
-
-.. py:method:: Context.check_privatekey()
-
-    Check if the private key (loaded with :py:meth:`use_privatekey`) matches the
-    certificate (loaded with :py:meth:`use_certificate`).  Returns
-    :py:data:`None` if they match, raises :py:exc:`Error` otherwise.
-
-
-.. py:method:: Context.get_app_data()
-
-    Retrieve application data as set by :py:meth:`set_app_data`.
-
-
-.. py:method:: Context.get_cert_store()
-
-    Retrieve the certificate store (a X509Store object) that the context uses.
-    This can be used to add "trusted" certificates without using the
-    :py:meth:`load_verify_locations` method.
-
-
-.. py:method:: Context.get_timeout()
-
-    Retrieve session timeout, as set by :py:meth:`set_timeout`. The default is 300
-    seconds.
-
-
-.. py:method:: Context.get_verify_depth()
-
-    Retrieve the Context object's verify depth, as set by
-    :py:meth:`set_verify_depth`.
-
-
-.. py:method:: Context.get_verify_mode()
-
-    Retrieve the Context object's verify mode, as set by :py:meth:`set_verify`.
-
-
-.. automethod:: Context.load_client_ca
-
-
-.. py:method:: Context.set_client_ca_list(certificate_authorities)
-
-    Replace the current list of preferred certificate signers that would be
-    sent to the client when requesting a client certificate with the
-    *certificate_authorities* sequence of :py:class:`OpenSSL.crypto.X509Name`'s.
-
-    .. versionadded:: 0.10
-
-
-.. py:method:: Context.add_client_ca(certificate_authority)
-
-    Extract a :py:class:`OpenSSL.crypto.X509Name` from the *certificate_authority*
-    :py:class:`OpenSSL.crypto.X509` certificate and add it to the list of preferred
-    certificate signers sent to the client when requesting a client certificate.
-
-    .. versionadded:: 0.10
-
-
-.. py:method:: Context.load_verify_locations(pemfile, capath)
-
-    Specify where CA certificates for verification purposes are located. These
-    are trusted certificates. Note that the certificates have to be in PEM
-    format.  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`.
-
-
-.. py:method:: Context.set_default_verify_paths()
-
-    Specify that the platform provided CA certificates are to be used for verification purposes.
-    This method has some caveats related to the binary wheels that cryptography (pyOpenSSL's primary dependency) ships:
-
-    * macOS will only load certificates using this method if the user has the ``openssl@1.1`` `Homebrew <https://brew.sh>`_ formula installed in the default location.
-    * Windows will not work.
-    * manylinux1 cryptography wheels will work on most common Linux distributions in pyOpenSSL 17.1.0 and above.
-      pyOpenSSL detects the manylinux1 wheel and attempts to load roots via a fallback path.
-
-
-.. py:method:: Context.load_tmp_dh(dhfile)
-
-    Load parameters for Ephemeral Diffie-Hellman from *dhfile*.
-
-
-.. py:method:: Context.set_tmp_ecdh(curve)
-
-   Select a curve to use for ECDHE key exchange.
-
-   The valid values of *curve* are the objects returned by
-   :py:func:`OpenSSL.crypto.get_elliptic_curves` or
-   :py:func:`OpenSSL.crypto.get_elliptic_curve`.
-
-
-.. py:method:: Context.set_app_data(data)
-
-    Associate *data* with this Context object. *data* can be retrieved
-    later using the :py:meth:`get_app_data` method.
-
-
-.. automethod:: Context.set_cipher_list
-
-.. py:method:: Context.set_info_callback(callback)
-
-    Set the information callback to *callback*. This function will be called
-    from time to time during SSL handshakes.
-
-    *callback* should take three arguments: a Connection object and two integers.
-    The first integer specifies where in the SSL handshake the function was
-    called, and the other the return code from a (possibly failed) internal
-    function call.
-
-
-.. py:method:: Context.set_options(options)
-
-    Add SSL options. Options you have set before are not cleared!
-    This method should be used with the :py:const:`OP_*` constants.
-
-
-.. py:method:: Context.set_mode(mode)
-
-   Add SSL mode. Modes you have set before are not cleared!  This method should
-   be used with the :py:const:`MODE_*` constants.
-
-
-.. py:method:: Context.set_passwd_cb(callback[, userdata])
-
-    Set the passphrase callback to *callback*. This function will be called
-    when a private key with a passphrase is loaded. *callback* must accept
-    three positional arguments.  First, an integer giving the maximum length of
-    the passphrase it may return.  If the returned passphrase is longer than
-    this, it will be truncated.  Second, a boolean value which will be true if
-    the user should be prompted for the passphrase twice and the callback should
-    verify that the two values supplied are equal. Third, the value given as the
-    *userdata* parameter to :py:meth:`set_passwd_cb`.  The *callback* must return
-    a byte string. If an error occurs, *callback* should return a false value
-    (e.g. an empty string).
-
-
-.. py:method:: Context.set_session_cache_mode(mode)
-
-    Set the behavior of the session cache used by all connections using this
-    Context.  The previously set mode is returned.  See :py:const:`SESS_CACHE_*`
-    for details about particular modes.
-
-    .. versionadded:: 0.14
-
-
-.. py:method:: Context.get_session_cache_mode()
-
-    Get the current session cache mode.
-
-    .. versionadded:: 0.14
-
-
-.. automethod:: Context.set_session_id
-
-
-.. py:method:: Context.set_timeout(timeout)
-
-    Set the timeout for newly created sessions for this Context object to
-    *timeout*. *timeout* must be given in (whole) seconds. The default
-    value is 300 seconds. See the OpenSSL manual for more information (e.g.
-    :manpage:`SSL_CTX_set_timeout(3)`).
-
-
-.. py:method:: Context.set_verify(mode, callback)
-
-    Set the verification flags for this Context object to *mode* and specify
-    that *callback* should be used for verification callbacks. *mode* should be
-    one of :py:const:`VERIFY_NONE` and :py:const:`VERIFY_PEER`. If
-    :py:const:`VERIFY_PEER` is used, *mode* can be OR:ed with
-    :py:const:`VERIFY_FAIL_IF_NO_PEER_CERT` and :py:const:`VERIFY_CLIENT_ONCE`
-    to further control the behaviour.
-
-    *callback* should take five arguments: A Connection object, an X509 object,
-    and three integer variables, which are in turn potential error number, error
-    depth and return code. *callback* should return true if verification passes
-    and false otherwise.
-
-
-.. py:method:: Context.set_verify_depth(depth)
-
-    Set the maximum depth for the certificate chain verification that shall be
-    allowed for this Context object.
-
-
-.. py:method:: Context.use_certificate(cert)
-
-    Use the certificate *cert* which has to be a X509 object.
-
-
-.. py:method:: Context.add_extra_chain_cert(cert)
-
-    Adds the certificate *cert*, which has to be a X509 object, to the
-    certificate chain presented together with the certificate.
-
-
-.. py:method:: Context.use_certificate_chain_file(file)
-
-    Load a certificate chain from *file* which must be PEM encoded.
-
-
-.. py:method:: Context.use_privatekey(pkey)
-
-    Use the private key *pkey* which has to be a PKey object.
-
-
-.. py:method:: Context.use_certificate_file(file[, format])
-
-    Load the first certificate found in *file*. The certificate must be in the
-    format specified by *format*, which is either :py:const:`FILETYPE_PEM` or
-    :py:const:`FILETYPE_ASN1`. The default is :py:const:`FILETYPE_PEM`.
-
-
-.. py:method:: Context.use_privatekey_file(file[, format])
-
-    Load the first private key found in *file*. The private key must be in the
-    format specified by *format*, which is either :py:const:`FILETYPE_PEM` or
-    :py:const:`FILETYPE_ASN1`. The default is :py:const:`FILETYPE_PEM`.
-
-
-.. py:method:: Context.set_tlsext_servername_callback(callback)
-
-    Specify a one-argument callable to use as the TLS extension server name
-    callback.  When a connection using the server name extension is made using
-    this context, the callback will be invoked with the :py:class:`Connection`
-    instance.
-
-    .. versionadded:: 0.13
-
-
-.. py:method:: Context.set_npn_advertise_callback(callback)
-
-    Specify a callback function that will be called when offering `Next
-    Protocol Negotiation
-    <https://tools.ietf.org/html/draft-agl-tls-nextprotoneg-03>`_ as a server.
-
-    *callback* should be the callback function.  It will be invoked with one
-    argument, the :py:class:`Connection` instance.  It should return a list of
-    bytestrings representing the advertised protocols, like
-    ``[b'http/1.1', b'spdy/2']``.
-
-    .. versionadded:: 0.15
-
-
-.. py:method:: Context.set_npn_select_callback(callback):
-
-    Specify a callback function that will be called when a server offers Next
-    Protocol Negotiation options.
-
-    *callback* should be the callback function.  It will be invoked with two
-    arguments: the :py:class:`Connection`, and a list of offered protocols as
-    bytestrings, e.g. ``[b'http/1.1', b'spdy/2']``.  It should return one of
-    those bytestrings, the chosen protocol.
-
-    .. versionadded:: 0.15
-
-.. py:method:: Context.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:: Context.set_alpn_select_callback(callback)
-
-    Specify a callback function that will be called on the server when a client
-    offers protocols using Application Layer Protocol Negotiation.
-
-    *callback* should be the callback function. It will be invoked with two
-    arguments: the :py:class:`Connection` and a list of offered protocols as
-    bytestrings, e.g. ``[b'http/1.1', b'spdy/2']``. It should return one of
-    these bytestrings, the chosen protocol.
-
+.. autoclass:: OpenSSL.SSL.Context
+               :members:
 
 .. _openssl-session:
 
@@ -529,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 b664254..5def0aa 100644
--- a/src/OpenSSL/SSL.py
+++ b/src/OpenSSL/SSL.py
@@ -632,7 +632,7 @@ def SSLeay_version(type):
     """
     Return a string describing the version of OpenSSL in use.
 
-    :param type: One of the SSLEAY_ constants defined in this module.
+    :param type: One of the :const:`SSLEAY_` constants defined in this module.
     """
     return _ffi.string(_lib.SSLeay_version(type))
 
@@ -675,6 +675,13 @@ _requires_sni = _make_requires(
 
 
 class Session(object):
+    """
+    A class representing an SSL session.  A session defines certain connection
+    parameters which may be re-used to speed up the setup of subsequent
+    connections.
+
+    .. versionadded:: 0.14
+    """
     pass
 
 
@@ -682,6 +689,9 @@ class Context(object):
     """
     :class:`OpenSSL.SSL.Context` instances define the parameters for setting
     up new SSL connections.
+
+    :param method: One of SSLv2_METHOD, SSLv3_METHOD, SSLv23_METHOD, or
+        TLSv1_METHOD.
     """
     _methods = {
         SSLv2_METHOD: "SSLv2_method",
@@ -697,10 +707,6 @@ class Context(object):
         if getattr(_lib, name, None) is not None)
 
     def __init__(self, method):
-        """
-        :param method: One of SSLv2_METHOD, SSLv3_METHOD, SSLv23_METHOD, or
-            TLSv1_METHOD.
-        """
         if not isinstance(method, integer_types):
             raise TypeError("method must be an integer")
 
@@ -749,7 +755,11 @@ class Context(object):
     def load_verify_locations(self, cafile, capath=None):
         """
         Let SSL know where we can find trusted certificates for the certificate
-        chain
+        chain.  Note that the certificates have to be in PEM format.
+
+        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 :data:`None`.
 
         :param cafile: In which file we can find the certificates (``bytes`` or
             ``unicode``).
@@ -783,9 +793,19 @@ class Context(object):
 
     def set_passwd_cb(self, callback, userdata=None):
         """
-        Set the passphrase callback
-
-        :param callback: The Python callback to use; must return a byte string
+        Set the passphrase callback.  This function will be called
+        when a private key with a passphrase is loaded.
+
+        :param callback: The Python callback to use.  This must accept three
+            positional arguments.  First, an integer giving the maximum length
+            of the passphrase it may return.  If the returned passphrase is
+            longer than this, it will be truncated.  Second, a boolean value
+            which will be true if the user should be prompted for the
+            passphrase twice and the callback should verify that the two values
+            supplied are equal. Third, the value given as the *userdata*
+            parameter to :meth:`set_passwd_cb`.  The *callback* must return
+            a byte string. If an error occurs, *callback* should return a false
+            value (e.g. an empty string).
         :param userdata: (optional) A Python object which will be given as
                          argument to the callback
         :return: None
@@ -801,7 +821,17 @@ class Context(object):
 
     def set_default_verify_paths(self):
         """
-        Use the platform-specific CA certificate locations
+        Specify that the platform provided CA certificates are to be used for
+        verification purposes. This method has some caveats related to the
+        binary wheels that cryptography (pyOpenSSL's primary dependency) ships:
+
+        *   macOS will only load certificates using this method if the user has
+            the ``openssl@1.1`` `Homebrew <https://brew.sh>`_ formula installed
+            in the default location.
+        *   Windows will not work.
+        *   manylinux1 cryptography wheels will work on most common Linux
+            distributions in pyOpenSSL 17.1.0 and above.  pyOpenSSL detects the
+            manylinux1 wheel and attempts to load roots via a fallback path.
 
         :return: None
         """
@@ -871,10 +901,10 @@ class Context(object):
 
     def use_certificate_chain_file(self, certfile):
         """
-        Load a certificate chain from a file
+        Load a certificate chain from a file.
 
         :param certfile: The name of the certificate chain file (``bytes`` or
-            ``unicode``).
+            ``unicode``).  Must be PEM encoded.
 
         :return: None
         """
@@ -892,7 +922,9 @@ class Context(object):
 
         :param certfile: The name of the certificate file (``bytes`` or
             ``unicode``).
-        :param filetype: (optional) The encoding of the file, default is PEM
+        :param filetype: (optional) The encoding of the file, which is either
+            :const:`FILETYPE_PEM` or :const:`FILETYPE_ASN1`.  The default is
+            :const:`FILETYPE_PEM`.
 
         :return: None
         """
@@ -948,7 +980,9 @@ class Context(object):
         Load a private key from a file
 
         :param keyfile: The name of the key file (``bytes`` or ``unicode``)
-        :param filetype: (optional) The encoding of the file, default is PEM
+        :param filetype: (optional) The encoding of the file, which is either
+            :const:`FILETYPE_PEM` or :const:`FILETYPE_ASN1`.  The default is
+            :const:`FILETYPE_PEM`.
 
         :return: None
         """
@@ -980,9 +1014,10 @@ class Context(object):
 
     def check_privatekey(self):
         """
-        Check that the private key and certificate match up
+        Check if the private key (loaded with :meth:`use_privatekey`) matches
+        the certificate (loaded with :meth:`use_certificate`)
 
-        :return: None (raises an exception if something's wrong)
+        :return: :data:`None` (raises :exc:`Error` if something's wrong)
         """
         if not _lib.SSL_CTX_check_private_key(self._context):
             _raise_current_error()
@@ -1024,11 +1059,15 @@ class Context(object):
 
     def set_session_cache_mode(self, mode):
         """
-        Enable/disable session caching and specify the mode used.
+        Set the behavior of the session cache used by all connections using
+        this Context.  The previously set mode is returned.  See
+        :const:`SESS_CACHE_*` for details about particular modes.
 
         :param mode: One or more of the SESS_CACHE_* flags (combine using
             bitwise or)
         :returns: The previously set caching mode.
+
+        .. versionadded:: 0.14
         """
         if not isinstance(mode, integer_types):
             raise TypeError("mode must be an integer")
@@ -1037,17 +1076,29 @@ class Context(object):
 
     def get_session_cache_mode(self):
         """
+        Get the current session cache mode.
+
         :returns: The currently used cache mode.
+
+        .. versionadded:: 0.14
         """
         return _lib.SSL_CTX_get_session_cache_mode(self._context)
 
     def set_verify(self, mode, callback):
         """
-        Set the verify mode and verify callback
-
-        :param mode: The verify mode, this is either VERIFY_NONE or
-                     VERIFY_PEER combined with possible other flags
-        :param callback: The Python callback to use
+        et the verification flags for this Context object to *mode* and specify
+        that *callback* should be used for verification callbacks.
+
+        :param mode: The verify mode, this should be one of
+            :const:`VERIFY_NONE` and :const:`VERIFY_PEER`. If
+            :const:`VERIFY_PEER` is used, *mode* can be OR:ed with
+            :const:`VERIFY_FAIL_IF_NO_PEER_CERT` and
+            :const:`VERIFY_CLIENT_ONCE` to further control the behaviour.
+        :param callback: The Python callback to use.  This should take five
+            arguments: A Connection object, an X509 object, and three integer
+            variables, which are in turn potential error number, error depth
+            and return code. *callback* should return True if verification
+            passes and False otherwise.
         :return: None
 
         See SSL_CTX_set_verify(3SSL) for further details.
@@ -1064,7 +1115,8 @@ class Context(object):
 
     def set_verify_depth(self, depth):
         """
-        Set the verify depth
+        Set the maximum depth for the certificate chain verification that shall
+        be allowed for this Context object.
 
         :param depth: An integer specifying the verify depth
         :return: None
@@ -1076,7 +1128,8 @@ class Context(object):
 
     def get_verify_mode(self):
         """
-        Get the verify mode
+        Retrieve the Context object's verify mode, as set by
+        :meth:`set_verify`.
 
         :return: The verify mode
         """
@@ -1084,7 +1137,8 @@ class Context(object):
 
     def get_verify_depth(self):
         """
-        Get the verify depth
+        Retrieve the Context object's verify depth, as set by
+        :meth:`set_verify_depth`.
 
         :return: The verify depth
         """
@@ -1115,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
         """
@@ -1151,6 +1205,8 @@ class Context(object):
 
         :param certificate_authorities: a sequence of X509Names.
         :return: None
+
+        .. versionadded:: 0.10
         """
         name_stack = _lib.sk_X509_NAME_new_null()
         _openssl_assert(name_stack != _ffi.NULL)
@@ -1186,6 +1242,8 @@ class Context(object):
 
         :param certificate_authority: certificate authority's X509 certificate.
         :return: None
+
+        .. versionadded:: 0.10
         """
         if not isinstance(certificate_authority, X509):
             raise TypeError("certificate_authority must be an X509 instance")
@@ -1196,9 +1254,11 @@ class Context(object):
 
     def set_timeout(self, timeout):
         """
-        Set session timeout
+        Set the timeout for newly created sessions for this Context object to
+        *timeout*.  The default value is 300 seconds. See the OpenSSL manual
+        for more information (e.g. :manpage:`SSL_CTX_set_timeout(3)`).
 
-        :param timeout: The timeout in seconds
+        :param timeout: The timeout in (whole) seconds
         :return: The previous session timeout
         """
         if not isinstance(timeout, integer_types):
@@ -1208,7 +1268,8 @@ class Context(object):
 
     def get_timeout(self):
         """
-        Get the session timeout
+        Retrieve session timeout, as set by :meth:`set_timeout`. The default
+        is 300 seconds.
 
         :return: The session timeout
         """
@@ -1216,9 +1277,14 @@ class Context(object):
 
     def set_info_callback(self, callback):
         """
-        Set the info callback
+        Set the information callback to *callback*. This function will be
+        called from time to time during SSL handshakes.
 
-        :param callback: The Python callback to use
+        :param callback: The Python callback to use.  This should take three
+            arguments: a Connection object and two integers.  The first integer
+            specifies where in the SSL handshake the function was called, and
+            the other the return code from a (possibly failed) internal
+            function call.
         :return: None
         """
         @wraps(callback)
@@ -1230,7 +1296,7 @@ class Context(object):
 
     def get_app_data(self):
         """
-        Get the application data (supplied via set_app_data())
+        Get the application data (supplied via :meth:`set_app_data()`)
 
         :return: The application data
         """
@@ -1247,7 +1313,9 @@ class Context(object):
 
     def get_cert_store(self):
         """
-        Get the certificate store for the context.
+        Get the certificate store for the context.  This can be used to add
+        "trusted" certificates without using the
+        :meth:`load_verify_locations` method.
 
         :return: A X509Store object or None if it does not have one.
         """
@@ -1263,6 +1331,7 @@ class Context(object):
     def set_options(self, options):
         """
         Add options. Options set before are not cleared!
+        This method should be used with the :const:`OP_*` constants.
 
         :param options: The options to add.
         :return: The new option bitmask.
@@ -1274,7 +1343,8 @@ class Context(object):
 
     def set_mode(self, mode):
         """
-        Add modes via bitmask. Modes set before are not cleared!
+        Add modes via bitmask. Modes set before are not cleared!  This method
+        should be used with the :const:`MODE_*` constants.
 
         :param mode: The mode to add.
         :return: The new mode bitmask.
@@ -1292,6 +1362,8 @@ class Context(object):
 
         :param callback: The callback function.  It will be invoked with one
             argument, the Connection instance.
+
+        .. versionadded:: 0.13
         """
         @wraps(callback)
         def wrapper(ssl, alert, arg):
@@ -1311,9 +1383,11 @@ class Context(object):
         <https://technotes.googlecode.com/git/nextprotoneg.html>`_ as a server.
 
         :param callback: The callback function.  It will be invoked with one
-            argument, the Connection instance.  It should return a list of
-            bytestrings representing the advertised protocols, like
+            argument, the :class:`Connection` instance.  It should return a
+            list of bytestrings representing the advertised protocols, like
             ``[b'http/1.1', b'spdy/2']``.
+
+        .. versionadded:: 0.15
         """
         self._npn_advertise_helper = _NpnAdvertiseHelper(callback)
         self._npn_advertise_callback = self._npn_advertise_helper.callback
@@ -1330,6 +1404,8 @@ class Context(object):
             arguments: the Connection, and a list of offered protocols as
             bytestrings, e.g. ``[b'http/1.1', b'spdy/2']``.  It should return
             one of those bytestrings, the chosen protocol.
+
+        .. versionadded:: 0.15
         """
         self._npn_select_helper = _NpnSelectHelper(callback)
         self._npn_select_callback = self._npn_select_helper.callback
@@ -1339,9 +1415,9 @@ class Context(object):
     @_requires_alpn
     def set_alpn_protos(self, protos):
         """
-        Specify the clients ALPN protocol list.
-
-        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
@@ -1361,7 +1437,8 @@ class Context(object):
     @_requires_alpn
     def set_alpn_select_callback(self, callback):
         """
-        Set the callback to handle ALPN protocol choice.
+        Specify a callback function that will be called on the server when a
+        client offers protocols using ALPN.
 
         :param callback: The callback function.  It will be invoked with two
             arguments: the Connection, and a list of offered protocols as
@@ -1547,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):
@@ -1570,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
@@ -1586,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")
@@ -1597,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.
         """
@@ -1687,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
@@ -1746,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.
@@ -1767,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
@@ -1797,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.
         """
@@ -1826,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
@@ -1836,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
@@ -1848,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)
@@ -1860,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
         """
@@ -1872,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:
@@ -1904,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:
@@ -1939,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
         """
@@ -1949,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.
@@ -1965,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):
@@ -1986,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
         """
@@ -2001,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
         """
@@ -2017,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
         """
@@ -2035,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
@@ -2057,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
         """
@@ -2133,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:
@@ -2150,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")
@@ -2160,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
@@ -2194,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)
 
@@ -2216,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:
@@ -2232,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:
@@ -2246,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:
@@ -2258,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
@@ -2283,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 *")
@@ -2317,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 *")
diff --git a/src/OpenSSL/crypto.py b/src/OpenSSL/crypto.py
index 12b4db0..adf03b4 100644
--- a/src/OpenSSL/crypto.py
+++ b/src/OpenSSL/crypto.py
@@ -1799,7 +1799,8 @@ class X509StoreContext(object):
 
 def load_certificate(type, buffer):
     """
-    Load a certificate from a buffer
+    Load a certificate (X509) from the string *buffer* encoded with the
+    type *type*.
 
     :param type: The file type (one of FILETYPE_PEM, FILETYPE_ASN1)
 
@@ -1828,7 +1829,8 @@ def load_certificate(type, buffer):
 
 def dump_certificate(type, cert):
     """
-    Dump a certificate to a buffer
+    Dump the certificate *cert* into a buffer string encoded with the type
+    *type*.
 
     :param type: The file type (one of FILETYPE_PEM, FILETYPE_ASN1, or
         FILETYPE_TEXT)
@@ -2766,7 +2768,8 @@ def load_publickey(type, buffer):
 
 def load_privatekey(type, buffer, passphrase=None):
     """
-    Load a private key from a buffer
+    Load a private key (PKey) from the string *buffer* encoded with the type
+    *type*.
 
     :param type: The file type (one of FILETYPE_PEM, FILETYPE_ASN1)
     :param buffer: The buffer the key is stored in
@@ -2801,7 +2804,8 @@ def load_privatekey(type, buffer, passphrase=None):
 
 def dump_certificate_request(type, req):
     """
-    Dump a certificate request to a buffer
+    Dump the certificate request *req* into a buffer string encoded with the
+    type *type*.
 
     :param type: The file type (one of FILETYPE_PEM, FILETYPE_ASN1)
     :param req: The certificate request to dump
@@ -2828,7 +2832,8 @@ def dump_certificate_request(type, req):
 
 def load_certificate_request(type, buffer):
     """
-    Load a certificate request from a buffer
+    Load a certificate request (X509Req) from the string *buffer* encoded with
+    the type *type*.
 
     :param type: The file type (one of FILETYPE_PEM, FILETYPE_ASN1)
     :param buffer: The buffer the certificate request is stored in
@@ -2855,12 +2860,14 @@ def load_certificate_request(type, buffer):
 
 def sign(pkey, data, digest):
     """
-    Sign data with a digest
+    Sign a data string using the given key and message digest.
 
-    :param pkey: Pkey to sign with
+    :param pkey: PKey to sign with
     :param data: data to be signed
     :param digest: message digest to use
     :return: signature
+
+    .. versionadded:: 0.11
     """
     data = _text_to_bytes_and_warn("data", data)
 
@@ -2887,13 +2894,16 @@ def sign(pkey, data, digest):
 
 def verify(cert, signature, data, digest):
     """
-    Verify a signature.
+    Verify the signature for a data string.
 
-    :param cert: signing certificate (X509 object)
+    :param cert: signing certificate (X509 object) corresponding to the
+        private key which generated the signature.
     :param signature: signature returned by sign function
     :param data: data to be verified
     :param digest: message digest to use
     :return: ``None`` if the signature is correct, raise exception otherwise.
+
+    .. versionadded:: 0.11
     """
     data = _text_to_bytes_and_warn("data", data)
 
@@ -2948,7 +2958,8 @@ def dump_crl(type, crl):
 
 def load_crl(type, buffer):
     """
-    Load a certificate revocation list from a buffer
+    Load Certificate Revocation List (CRL) data from a string *buffer*.
+    *buffer* encoded with the type *type*.
 
     :param type: The file type (one of FILETYPE_PEM, FILETYPE_ASN1)
     :param buffer: The buffer the CRL is stored in
@@ -2977,7 +2988,8 @@ def load_crl(type, buffer):
 
 def load_pkcs7_data(type, buffer):
     """
-    Load pkcs7 data from a buffer
+    Load pkcs7 data from the string *buffer* encoded with the type
+    *type*.
 
     :param type: The file type (one of FILETYPE_PEM or FILETYPE_ASN1)
     :param buffer: The buffer with the pkcs7 data.
@@ -3005,7 +3017,11 @@ def load_pkcs7_data(type, buffer):
 
 def load_pkcs12(buffer, passphrase=None):
     """
-    Load a PKCS12 object from a buffer
+    Load pkcs12 data from the string *buffer*. If the pkcs12 structure is
+    encrypted, a *passphrase* must be included.  The MAC is always
+    checked and thus required.
+
+    See also the man page for the C function :py:func:`PKCS12_parse`.
 
     :param buffer: The buffer the certificate is stored in
     :param passphrase: (Optional) The password to decrypt the PKCS12 lump