address review comments

2 files changed, 36 insertions, 44 deletions

diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst
index 66bb37c9..ab2fe4e5 100644
--- a/docs/hazmat/primitives/asymmetric/rsa.rst
+++ b/docs/hazmat/primitives/asymmetric/rsa.rst
@@ -93,8 +93,9 @@ to serialize the key.
 
     >>> from cryptography.hazmat.primitives import serialization
     >>> pem = private_key.dump(
-    ...    serialization.PKCS8(serialization.Encoding.PEM),
-    ...    serialization.BestAvailable(b'passwordgoeshere')
+    ...    encoding=serialization.Encoding.PEM,
+    ...    fmt=serialization.Format.PKCS8,
+    ...    encryption_type=serialization.BestAvailableEncryption(b'mypassword')
     ... )
     >>> pem.splitlines()[0]
     '-----BEGIN ENCRYPTED PRIVATE KEY-----'
@@ -105,8 +106,9 @@ It is also possible to serialize without encryption using
 .. doctest::
 
     >>> pem = private_key.dump(
-    ...    serialization.TraditionalOpenSSL(serialization.Encoding.PEM),
-    ...    serialization.NoEncryption()
+    ...    encoding=serialization.Encoding.PEM,
+    ...    fmt=serialization.Format.PKCS8,
+    ...    encryption_type=serialization.NoEncryption()
     ... )
     >>> pem.splitlines()[0]
     '-----BEGIN RSA PRIVATE KEY-----'
@@ -532,13 +534,15 @@ Key interfaces
             :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateNumbers`
             instance.
 
-    .. method:: dump(serializer, encryption_type)
+    .. method:: dump(encoding, fmt, encryption_type)
 
         Dump the key to PEM encoded bytes using the serializer provided.
 
-        :param serializer: An instance of
-            :class:`~cryptography.hazmat.primitives.serialization.TraditionalOpenSSL`
-            or :class:`~cryptography.hazmat.primitives.serialization.PKCS8`
+        :param encoding: A value from the
+            :class:`~cryptography.hazmat.primitives.serialization.Encoding` enum.
+
+        :param fmt: A value from the
+            :class:`~cryptography.hazmat.primitives.serialization.Format` enum.
 
         :param encryption_type: An instance of an object conforming to the
             :class:`~cryptography.hazmat.primitives.serialization.KeySerializationEncryption`
diff --git a/docs/hazmat/primitives/asymmetric/serialization.rst b/docs/hazmat/primitives/asymmetric/serialization.rst
index 68eaf021..b429766d 100644
--- a/docs/hazmat/primitives/asymmetric/serialization.rst
+++ b/docs/hazmat/primitives/asymmetric/serialization.rst
@@ -75,12 +75,12 @@ methods.
     .. doctest::
 
         >>> from cryptography.hazmat.backends import default_backend
-        >>> from cryptography.hazmat.primitives.asymmetric import dsa, rsa
+        >>> from cryptography.hazmat.primitives.asymmetric import rsa
         >>> from cryptography.hazmat.primitives.serialization import load_pem_private_key
         >>> key = load_pem_private_key(pem_data, password=None, backend=default_backend())
         >>> if isinstance(key, rsa.RSAPrivateKey):
         ...     signature = sign_with_rsa_key(key, message)
-        ... elif isinstance(key, dsa.DSAPrivateKey):
+        ... elif isinstance(key, interfaces.DSAPrivateKey):
         ...     signature = sign_with_dsa_key(key, message)
         ... else:
         ...     raise TypeError
@@ -283,30 +283,37 @@ DSA keys look almost identical but begin with ``ssh-dss`` rather than
     :raises cryptography.exceptions.UnsupportedAlgorithm: If the serialized
         key is of a type that is not supported.
 
-Serializers
-~~~~~~~~~~~
-
-Instances of these classes can be passed to methods like
-:meth:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKeyWithSerialization.dump`.
+Serialization Formats
+~~~~~~~~~~~~~~~~~~~~~
 
-.. class:: PKCS8(encoding)
+.. class:: Format
 
     .. versionadded:: 0.8
 
-    A serializer for the PKCS #8 format.
+    An enumeration for key formats.
+
+    .. attribute:: TraditionalOpenSSL
+
+        Frequently known as PKCS#1 format.
 
-    :param encoding: A value from the
-        :class:`~cryptography.hazmat.primitives.serialization.Encoding` enum.
+    .. attribute:: PKCS8
 
-.. class:: TraditionalOpenSSL(encoding)
+Serialization Encodings
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. class:: Encoding
 
     .. versionadded:: 0.8
 
-    A serializer for the traditional OpenSSL (sometimes known as PKCS #1)
-    format.
+    An enumeration for encoding types.
+
+    .. attribute:: PEM
 
-    :param encoding: A value from the
-        :class:`~cryptography.hazmat.primitives.serialization.Encoding` enum.
+        For PEM format. This is a base64 format with delimiters.
+
+    .. attribute:: DER
+
+        For DER format. This is a binary format.
 
 
 Serialization Encryption Types
@@ -320,7 +327,7 @@ Serialization Encryption Types
     All other classes in this section represent the available choices for
     encryption and have this interface.
 
-.. class:: BestAvailable
+.. class:: BestAvailableEncryption(password)
 
     Encrypt using the best available encryption for a given key's backend.
     This is a curated encryption choice and the algorithm may change over
@@ -331,22 +338,3 @@ Serialization Encryption Types
 .. class:: NoEncryption
 
     Do not encrypt.
-
-
-Utility Classes
-~~~~~~~~~~~~~~~
-
-.. class:: Encoding
-
-    .. versionadded:: 0.8
-
-    An enumeration for encoding types. Used by :class:`PKCS8` and
-    :class:`TraditionalOpenSSL`.
-
-    .. attribute:: PEM
-
-        For PEM format. This is a base64 format with delimiters.
-
-    .. attribute:: DER
-
-        For DER format. This is a binary format.