Use autodoc for PKCS12

2 files changed, 46 insertions, 78 deletions

diff --git a/OpenSSL/crypto.py b/OpenSSL/crypto.py
index 34ec98a..fcc89c0 100644
--- a/OpenSSL/crypto.py
+++ b/OpenSSL/crypto.py
@@ -1970,6 +1970,9 @@ PKCS7Type = PKCS7
 
 
 class PKCS12(object):
+    """
+    A PKCS #12 archive.
+    """
     def __init__(self):
         self._pkey = None
         self._cert = None
@@ -1979,19 +1982,21 @@ class PKCS12(object):
 
     def get_certificate(self):
         """
-        Return certificate portion of the PKCS12 structure
+        Get the certificate in the PKCS #12 structure.
 
-        :return: X509 object containing the certificate
+        :return: The certificate, or :py:const:`None` if there is none.
+        :rtype: :py:class:`X509` or :py:const:`None`
         """
         return self._cert
 
 
     def set_certificate(self, cert):
         """
-        Replace the certificate portion of the PKCS12 structure
+        Set the certificate in the PKCS #12 structure.
 
-        :param cert: The new certificate.
+        :param cert: The new certificate, or :py:const:`None` to unset it.
         :type cert: :py:class:`X509` or :py:data:`None`
+
         :return: :py:data:`None`
         """
         if not isinstance(cert, X509):
@@ -2001,19 +2006,21 @@ class PKCS12(object):
 
     def get_privatekey(self):
         """
-        Return private key portion of the PKCS12 structure
+        Get the private key in the PKCS #12 structure.
 
-        :returns: PKey object containing the private key
+        :return: The private key, or :py:const:`None` if there is none.
+        :rtype: :py:class:`PKey`
         """
         return self._pkey
 
 
     def set_privatekey(self, pkey):
         """
-        Replace or set the certificate portion of the PKCS12 structure
+        Set the certificate portion of the PKCS #12 structure.
+
+        :param pkey: The new private key, or :py:const:`None` to unset it.
+        :type pkey: :py:class:`PKey` or :py:const:`None`
 
-        :param pkey: The new private key.
-        :type pkey: :py:class:`PKey`
         :return: :py:data:`None`
         """
         if not isinstance(pkey, PKey):
@@ -2023,10 +2030,11 @@ class PKCS12(object):
 
     def get_ca_certificates(self):
         """
-        Return CA certificates within of the PKCS12 object
+        Get the CA certificates in the PKCS #12 structure.
 
-        :return: A newly created tuple containing the CA certificates in the chain,
-                 if any are present, or None if no CA certificates are present.
+        :return: A tuple with the CA certificates in the chain, or
+            :py:const:`None` if there are none.
+        :rtype: :py:class:`tuple` of :py:class:`X509` or :py:const:`None`
         """
         if self._cacerts is not None:
             return tuple(self._cacerts)
@@ -2034,10 +2042,12 @@ class PKCS12(object):
 
     def set_ca_certificates(self, cacerts):
         """
-        Replace or set the CA certificates withing the PKCS12 object.
+        Set the CA certificates in the PKCS #12 structure.
+
+        :param cacerts: The new CA certificates, or :py:const:`None` to unset
+            them.
+        :type cacerts: An iterable of :py:class:`X509` or :py:data:`None`
 
-        :param cacerts: The new CA certificates.
-        :type cacerts: :py:data:`None` or an iterable of :py:class:`X509`
         :return: :py:data:`None`
         """
         if cacerts is None:
@@ -2052,10 +2062,11 @@ class PKCS12(object):
 
     def set_friendlyname(self, name):
         """
-        Replace or set the certificate portion of the PKCS12 structure
+        Set the friendly name in the PKCS #12 structure.
+
+        :param name: The new friendly name, or :py:const:`None` to unset.
+        :type name: :py:class:`bytes` or :py:data:`None`
 
-        :param name: The new friendly name.
-        :type name: :py:class:`bytes`
         :return: :py:data:`None`
         """
         if name is None:
@@ -2067,27 +2078,33 @@ class PKCS12(object):
 
     def get_friendlyname(self):
         """
-        Return friendly name portion of the PKCS12 structure
+        Get the friendly name in the PKCS# 12 structure.
 
-        :returns: String containing the friendlyname
+        :returns: The friendly name,  or :py:data:`None` if there is none.
+        :rtype: :py:class:`bytes` or :py:data:`None`
         """
         return self._friendlyname
 
 
     def export(self, passphrase=None, iter=2048, maciter=1):
         """
-        Dump a PKCS12 object as a string.  See also "man PKCS12_create".
+        Dump a PKCS12 object as a string.
+
+        For more information, see the :c:func:`PKCS12_create` man page.
 
-        :param passphrase: used to encrypt the PKCS12
+        :param passphrase: The passphrase used to encrypt the structure. Unlike
+            some other passphrase arguments, this *must* be a string, not a
+            callback.
         :type passphrase: :py:data:`bytes`
 
-        :param iter: How many times to repeat the encryption
+        :param iter: Number of times to repeat the encryption step.
         :type iter: :py:data:`int`
 
-        :param maciter: How many times to repeat the MAC
+        :param maciter: Number of times to repeat the MAC step.
         :type maciter: :py:data:`int`
 
-        :return: The string containing the PKCS12
+        :return: The string representation of the PKCS #12 structure.
+        :rtype:
         """
         if self._cacerts is None:
             cacerts = _ffi.NULL
@@ -2127,6 +2144,8 @@ class PKCS12(object):
         _lib.i2d_PKCS12_bio(bio, pkcs12)
         return _bio_to_string(bio)
 
+
+
 PKCS12Type = PKCS12
 
 
diff --git a/doc/api/crypto.rst b/doc/api/crypto.rst
index 6dd6a43..949f9b2 100644
--- a/doc/api/crypto.rst
+++ b/doc/api/crypto.rst
@@ -240,59 +240,8 @@ PKCS7 objects have the following methods:
 PKCS12 objects
 --------------
 
-PKCS12 objects have the following methods:
-
-.. py:method:: PKCS12.export([passphrase=None][, iter=2048][, maciter=1])
-
-    Returns a PKCS12 object as a string.
-
-    The optional *passphrase* must be a string not a callback.
-
-    See also the man page for the C function :py:func:`PKCS12_create`.
-
-
-.. py:method:: PKCS12.get_ca_certificates()
-
-    Return CA certificates within the PKCS12 object as a tuple. Returns
-    :py:const:`None` if no CA certificates are present.
-
-
-.. py:method:: PKCS12.get_certificate()
-
-    Return certificate portion of the PKCS12 structure.
-
-
-.. py:method:: PKCS12.get_friendlyname()
-
-    Return friendlyName portion of the PKCS12 structure.
-
-
-.. py:method:: PKCS12.get_privatekey()
-
-    Return private key portion of the PKCS12 structure
-
-
-.. py:method:: PKCS12.set_ca_certificates(cacerts)
-
-    Replace or set the CA certificates within the PKCS12 object with the sequence *cacerts*.
-
-    Set *cacerts* to :py:const:`None` to remove all CA certificates.
-
-
-.. py:method:: PKCS12.set_certificate(cert)
-
-    Replace or set the certificate portion of the PKCS12 structure.
-
-
-.. py:method:: PKCS12.set_friendlyname(name)
-
-    Replace or set the friendlyName portion of the PKCS12 structure.
-
-
-.. py:method:: PKCS12.set_privatekey(pkey)
-
-    Replace or set private key portion of the PKCS12 structure
-
+.. autoclass:: PKCS12
+               :members:
 
 .. _openssl-509ext: