better cross-module linking in ecdsa.keys

1 files changed, 34 insertions, 25 deletions

diff --git a/src/ecdsa/keys.py b/src/ecdsa/keys.py
index 499c5e4..397cf77 100644
--- a/src/ecdsa/keys.py
+++ b/src/ecdsa/keys.py
@@ -636,7 +636,7 @@ class VerifyingKey(object):
         :type signature: sigdecode method dependent
         :param data: data signed by the `signature`, will be hashed using
             `hashfunc`, if specified, or default hash function
-        :type data: bytes like object
+        :type data: :term:`bytes-like object`
         :param hashfunc: The default hash function that will be used for
             verification, needs to implement the same interface as hashlib.sha1
         :type hashfunc: callable
@@ -690,7 +690,7 @@ class VerifyingKey(object):
         :param signature: encoding of the signature
         :type signature: sigdecode method dependent
         :param digest: raw hash value that the signature authenticates.
-        :type digest: bytes like object
+        :type digest: :term:`bytes-like object`
         :param sigdecode: Callable to define the way the signature needs to
             be decoded to an object, needs to handle `signature` as the
             first parameter, the curve order (an int) as the second and return
@@ -879,7 +879,7 @@ class SigningKey(object):
         In Python 3, the expected type is `bytes`.
 
         :param string: the raw encoding of the private key
-        :type string: bytes like object
+        :type string: :term:`bytes-like object`
         :param curve: The curve on which the point needs to reside
         :type curve: ~ecdsa.curves.Curve
         :param hashfunc: The default hash function that will be used for
@@ -1012,7 +1012,7 @@ class SigningKey(object):
         in them will not be detected.
 
         :param string: binary string with DER-encoded private ECDSA key
-        :type string: bytes like object
+        :type string: :term:`bytes-like object`
         :param valid_curve_encodings: list of allowed encoding formats
             for curve parameters. By default (``None``) all are supported:
             ``named_curve`` and ``explicit``.
@@ -1315,7 +1315,7 @@ class SigningKey(object):
         of data is necessary.
 
         :param data: data to be hashed and computed signature over
-        :type data: bytes like object
+        :type data: :term:`bytes-like object`
         :param hashfunc: hash function to use for computing the signature,
             if unspecified, the default hash function selected during
             object initialisation will be used (see
@@ -1334,7 +1334,7 @@ class SigningKey(object):
         :param extra_entropy: additional data that will be fed into the random
             number generator used in the RFC6979 process. Entirely optional.
             Ignored with EdDSA.
-        :type extra_entropy: bytes like object
+        :type extra_entropy: :term:`bytes-like object`
 
         :return: encoded signature over `data`
         :rtype: bytes or sigencode function dependent type
@@ -1374,24 +1374,26 @@ class SigningKey(object):
         hashing of data is necessary.
 
         :param digest: hash of data that will be signed
-        :type digest: bytes like object
+        :type digest: :term:`bytes-like object`
         :param hashfunc: hash function to use for computing the random "k"
             value from RFC6979 process,
             if unspecified, the default hash function selected during
             object initialisation will be used (see
-            `VerifyingKey.default_hashfunc`). The object needs to implement
-            the same interface as hashlib.sha1.
+            :attr:`.VerifyingKey.default_hashfunc`). The object needs to
+            implement
+            the same interface as :func:`~hashlib.sha1` from :py:mod:`hashlib`.
         :type hashfunc: callable
         :param sigencode: function used to encode the signature.
             The function needs to accept three parameters: the two integers
             that are the signature and the order of the curve over which the
             signature was computed. It needs to return an encoded signature.
-            See `ecdsa.util.sigencode_string` and `ecdsa.util.sigencode_der`
+            See :func:`~ecdsa.util.sigencode_string` and
+            :func:`~ecdsa.util.sigencode_der`
             as examples of such functions.
         :type sigencode: callable
         :param extra_entropy: additional data that will be fed into the random
             number generator used in the RFC6979 process. Entirely optional.
-        :type extra_entropy: bytes like object
+        :type extra_entropy: :term:`bytes-like object`
         :param bool allow_truncate: if True, the provided digest can have
             bigger bit-size than the order of the curve, the extra bits (at
             the end of the digest) will be truncated. Use it when signing
@@ -1456,28 +1458,35 @@ class SigningKey(object):
         method instead of this one.
 
         :param data: data that will be hashed for signing
-        :type data: bytes like object
-        :param callable entropy: randomness source, os.urandom by default.
-            Ignored with EdDSA.
-        :param hashfunc: hash function to use for hashing the provided `data`.
+        :type data: :term:`bytes-like object`
+        :param callable entropy: randomness source, :func:`os.urandom` by
+            default. Ignored with EdDSA.
+        :param hashfunc: hash function to use for hashing the provided
+            ``data``.
             If unspecified the default hash function selected during
             object initialisation will be used (see
-            `VerifyingKey.default_hashfunc`).
-            Should behave like hashlib.sha1. The output length of the
+            :attr:`.VerifyingKey.default_hashfunc`).
+            Should behave like :func:`~hashlib.sha1` from :py:mod:`hashlib`.
+            The output length of the
             hash (in bytes) must not be longer than the length of the curve
             order (rounded up to the nearest byte), so using SHA256 with
             NIST256p is ok, but SHA256 with NIST192p is not. (In the 2**-96ish
             unlikely event of a hash output larger than the curve order, the
             hash will effectively be wrapped mod n).
-            Use hashfunc=hashlib.sha1 to match openssl's -ecdsa-with-SHA1 mode,
-            or hashfunc=hashlib.sha256 for openssl-1.0.0's -ecdsa-with-SHA256.
+            If you want to explicitly allow use of large hashes with small
+            curves set the ``allow_truncate`` to ``True``.
+            Use ``hashfunc=hashlib.sha1`` to match openssl's
+            ``-ecdsa-with-SHA1`` mode,
+            or ``hashfunc=hashlib.sha256`` for openssl-1.0.0's
+            ``-ecdsa-with-SHA256``.
             Ignored for EdDSA
         :type hashfunc: callable
         :param sigencode: function used to encode the signature.
             The function needs to accept three parameters: the two integers
             that are the signature and the order of the curve over which the
             signature was computed. It needs to return an encoded signature.
-            See `ecdsa.util.sigencode_string` and `ecdsa.util.sigencode_der`
+            See :func:`~ecdsa.util.sigencode_string` and
+            :func:`~ecdsa.util.sigencode_der`
             as examples of such functions.
             Ignored for EdDSA
         :type sigencode: callable
@@ -1485,17 +1494,17 @@ class SigningKey(object):
             In typical use cases, it should be set to None (the default) to
             allow its generation from an entropy source.
             Ignored for EdDSA.
-        :param bool allow_truncate: if True, the provided digest can have
+        :param bool allow_truncate: if ``True``, the provided digest can have
             bigger bit-size than the order of the curve, the extra bits (at
             the end of the digest) will be truncated. Use it when signing
             SHA-384 output using NIST256p or in similar situations. True by
             default.
             Ignored for EdDSA.
 
-        :raises RSZeroError: in the unlikely event when "r" parameter or
-            "s" parameter of the created signature is equal 0, as that would
+        :raises RSZeroError: in the unlikely event when *r* parameter or
+            *s* parameter of the created signature is equal 0, as that would
             leak the key. Caller should try a better entropy source, retry with
-            different 'k', or use the
+            different ``k``, or use the
             :func:`~SigningKey.sign_deterministic` in such case.
 
         :return: encoded signature of the hash of `data`
@@ -1529,7 +1538,7 @@ class SigningKey(object):
         instead of this one.
 
         :param digest: hash value that will be signed
-        :type digest: bytes like object
+        :type digest: :term:`bytes-like object`
         :param callable entropy: randomness source, os.urandom by default
         :param sigencode: function used to encode the signature.
             The function needs to accept three parameters: the two integers