doc the relationship between PrivateKey and PrivateKeyWithSerialization (#3721)

* doc the relationship between PrivateKey and PrivateKeyWithSerialization

Or at least do it better.

* let's talk about opaque keys

4 files changed, 25 insertions, 8 deletions

diff --git a/docs/hazmat/primitives/asymmetric/dh.rst b/docs/hazmat/primitives/asymmetric/dh.rst
index f97a328b..c52ee4d1 100644
--- a/docs/hazmat/primitives/asymmetric/dh.rst
+++ b/docs/hazmat/primitives/asymmetric/dh.rst
@@ -142,6 +142,9 @@ Key interfaces
 
     .. versionadded:: 0.9
 
+    A DH private key that is not an :term:`opaque key` also implements
+    :class:`DHPrivateKeyWithSerialization` to provide serialization methods.
+
     .. attribute:: key_size
 
         The bit length of the prime modulus.
@@ -172,8 +175,9 @@ Key interfaces
 
     .. versionadded:: 0.9
 
-    Inherits from
-    :class:`~cryptography.hazmat.primitives.asymmetric.dh.DHPrivateKey`.
+    This interface contains additional methods relating to serialization.
+    Any object with this interface also has all the methods from
+    :class:`DHPrivateKey`.
 
     .. method:: private_numbers()
 
diff --git a/docs/hazmat/primitives/asymmetric/dsa.rst b/docs/hazmat/primitives/asymmetric/dsa.rst
index 13cd0412..a6088190 100644
--- a/docs/hazmat/primitives/asymmetric/dsa.rst
+++ b/docs/hazmat/primitives/asymmetric/dsa.rst
@@ -278,7 +278,9 @@ Key interfaces
 
     .. versionadded:: 0.3
 
-    A `DSA`_ private key.
+    A `DSA`_ private key. A DSA private key that is not an
+    :term:`opaque key` also implements :class:`DSAPrivateKeyWithSerialization`
+    to provide serialization methods.
 
     .. method:: public_key()
 
@@ -322,7 +324,9 @@ Key interfaces
 
     .. versionadded:: 0.8
 
-    Extends :class:`DSAPrivateKey`.
+    This interface contains additional methods relating to serialization.
+    Any object with this interface also has all the methods from
+    :class:`DSAPrivateKey`.
 
     .. method:: private_numbers()
 
diff --git a/docs/hazmat/primitives/asymmetric/ec.rst b/docs/hazmat/primitives/asymmetric/ec.rst
index 614d7a32..710c11ca 100644
--- a/docs/hazmat/primitives/asymmetric/ec.rst
+++ b/docs/hazmat/primitives/asymmetric/ec.rst
@@ -441,7 +441,10 @@ Key Interfaces
     .. versionadded:: 0.5
 
     An elliptic curve private key for use with an algorithm such as `ECDSA`_ or
-    `EdDSA`_.
+    `EdDSA`_. An elliptic curve private key that is not an
+    :term:`opaque key` also implements
+    :class:`EllipticCurvePrivateKeyWithSerialization` to provide serialization
+    methods.
 
     .. method:: exchange(algorithm, peer_public_key)
 
@@ -495,7 +498,9 @@ Key Interfaces
 
     .. versionadded:: 0.8
 
-    Extends :class:`EllipticCurvePrivateKey`.
+    This interface contains additional methods relating to serialization.
+    Any object with this interface also has all the methods from
+    :class:`EllipticCurvePrivateKey`.
 
     .. method:: private_numbers()
 
diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst
index 152e5ed8..97f68c3a 100644
--- a/docs/hazmat/primitives/asymmetric/rsa.rst
+++ b/docs/hazmat/primitives/asymmetric/rsa.rst
@@ -530,7 +530,9 @@ Key interfaces
 
     .. versionadded:: 0.2
 
-    An `RSA`_ private key.
+    An `RSA`_ private key. An RSA private key that is not an
+    :term:`opaque key` also implements :class:`RSAPrivateKeyWithSerialization`
+    to provide serialization methods.
 
     .. method:: decrypt(ciphertext, padding)
 
@@ -584,7 +586,9 @@ Key interfaces
 
     .. versionadded:: 0.8
 
-    Extends :class:`RSAPrivateKey`.
+    This interface contains additional methods relating to serialization.
+    Any object with this interface also has all the methods from
+    :class:`RSAPrivateKey`.
 
     .. method:: private_numbers()