fix: update docstring

Author: lepture

src/joserfc/_rfc7517/models.py

@@ -216,7 +216,7 @@ def check_use(self, use: str) -> None:
         requires its presence.
 
         :param use: this key is used for, e.g. "sig", "enc"
-        :raise: UnsupportedKeyUseError
+        :raise UnsupportedKeyUseError: if this key is not designed for the given use
         """
         designed_use = self.get("use")
         if designed_use and designed_use != use:
@@ -226,7 +226,7 @@ def check_alg(self, alg: str) -> None:
         """Check if this key supports the given "alg".
 
         :param alg: the algorithm this key is intended to be used, e.g. "HS256", "ECDH-EC"
-        :raise: UnsupportedKeyAlgorithmError
+        :raise UnsupportedKeyAlgorithmError: if this key is not designed for the given algorithm
         """
         designed_alg = self.get("alg")
         if designed_alg and designed_alg != alg:
@@ -236,7 +236,7 @@ def check_key_op(self, operation: str) -> None:
         """Check if the given key_op is supported by this key.
 
         :param operation: key operation value, such as "sign", "encrypt".
-        :raise: UnsupportedKeyOperationError
+        :raise UnsupportedKeyOperationError: if the operation is not supported by this key.
         """
         key_ops = self.get("key_ops")
         if key_ops is not None and operation not in key_ops:

src/joserfc/_rfc7519/security.py

@@ -22,7 +22,13 @@
 
 
 def check_sensitive_data(claims: dict[str, Any]) -> None:
-    """Check if claims contains sensitive information."""
+    """
+    Checks for sensitive data within a dictionary of claims and raises an
+    error if any sensitive names or values are detected.
+
+    :param claims: JWT claims to check for sensitive data
+    :raises InsecureClaimError: if any sensitive names or values are detected
+    """
     for k in claims:
         # check claims key name
         if k in SENSITIVE_NAMES:

src/joserfc/_rfc7797/compact.py

@@ -36,7 +36,7 @@ def extract_rfc7515_compact(
     :param value: JWS in bytes
     :param payload: optional payload, required with detached content
     :param registry: optional JWSRegistry instance
-    :raise: DecodeError
+    :raise DecodeError: when decoding fails
     """
     parts = value.split(b".")
     if len(parts) != 3:

src/joserfc/jws.py

@@ -178,7 +178,8 @@ def deserialize_compact(
     :param algorithms: a list of allowed algorithms
     :param registry: a JWSRegistry to use
     :param payload: optional payload, required with detached content
-    :return: object of the ``CompactSignature``
+    :raises BadSignatureError: when signature verification fails
+    :return: object of the CompactSignature
     """
     obj = extract_compact(to_bytes(value), payload, registry)
     if not validate_compact(obj, public_key, algorithms, registry):
@@ -286,8 +287,8 @@ def deserialize_json(
     :param public_key: a flexible public key to verify the signature
     :param algorithms: a list of allowed algorithms
     :param registry: a JWSRegistry to use
-    :return: object of the SignatureData
-    :raise: ValueError or BadSignatureError
+    :return: object of GeneralJSONSignature or FlattenedJSONSignature
+    :raises BadSignatureError: when signature verification fails
     """
     if registry is None:
         registry = construct_registry(algorithms)

src/joserfc/jwt.py

@@ -99,7 +99,8 @@ def decode(
     :param algorithms: a list of allowed algorithms
     :param registry: a ``JWSRegistry`` or ``JWERegistry`` to use
     :param decoder_cls: A JSONDecoder subclass to use
-    :raise: BadSignatureError
+    :raise BadSignatureError: when signature verification fails
+    :raise InvalidPayloadError: when payload is not a valid JSON object
     """
     _value = to_bytes(value)
     header: Header