Add @specs to the JOSE module

potatosalad · Dec 10, 2023 · bd19f3f · bd19f3f
1 parent bc79e44
commit bd19f3f
Showing 1 changed file with 35 additions and 7 deletions.
diff --git a/lib/jose.ex b/lib/jose.ex
@@ -20,8 +20,11 @@ defmodule JOSE do
   ## Functions
 
   @doc """
-  Gets the current ChaCha20/Poly1305 module used by `jose_chacha20_poly1305`, see `chacha20_poly1305_module/1` for default.
+  Gets the current ChaCha20/Poly1305 module used by `jose_chacha20_poly1305`.
+
+  See `chacha20_poly1305_module/1` for default.
   """
+  @spec chacha20_poly1305_module() :: module()
   defdelegate chacha20_poly1305_module(), to: :jose
 
   @doc """
@@ -35,21 +38,29 @@ defmodule JOSE do
 
   Additional modules that implement the `jose_chacha20_poly1305` behavior may also be used.
   """
+  @spec chacha20_poly1305_module(module()) :: :ok
   defdelegate chacha20_poly1305_module(module), to: :jose
 
   @doc """
-  Gets the current Cryptographic Algorithm Fallback state, defaults to `false`.
+  Gets the current Cryptographic Algorithm Fallback state
+
+  Defaults to `false`.
   """
+  @spec crypto_fallback() :: boolean()
   defdelegate crypto_fallback(), to: :jose
 
   @doc """
   Sets the current Cryptographic Algorithm Fallback state.
   """
+  @spec crypto_fallback(boolean()) :: :ok
   defdelegate crypto_fallback(boolean), to: :jose
 
   @doc """
-  Gets the current Curve25519 module used by `jose_curve25519`, see `curve25519_module/1` for default.
+  Gets the current Curve25519 module used by `jose_curve25519`
+
+  See `curve25519_module/1` for default.
   """
+  @spec curve25519_module() :: module()
   defdelegate curve25519_module(), to: :jose
 
   @doc """
@@ -63,11 +74,15 @@ defmodule JOSE do
 
   Additional modules that implement the `jose_curve25519` behavior may also be used.
   """
+  @spec curve25519_module(module()) :: :ok
   defdelegate curve25519_module(module), to: :jose
 
   @doc """
-  Gets the current Curve448 module used by `jose_curve448`, see `curve448_module/1` for default.
+  Gets the current Curve448 module used by `jose_curve448`
+
+  See `curve448_module/1` for default.
   """
+  @spec curve448_module() :: module()
   defdelegate curve448_module(), to: :jose
 
   @doc """
@@ -80,21 +95,29 @@ defmodule JOSE do
 
   Additional modules that implement the `jose_curve448` behavior may also be used.
   """
+  @spec curve448_module(module()) :: :ok
   defdelegate curve448_module(module), to: :jose
 
   @doc """
-  Decode JSON to a term using the module returned by `json_module/0`.
+  Decodes JSON to a term using the module returned by `json_module/0`.
+
+  Returns the decoded term, or raises if `binary` contains invalid JSON.
   """
+  @spec decode(binary()) :: term()
   defdelegate decode(binary), to: :jose
 
   @doc """
-  Encode a term to JSON using the module returned by `json_module/0`.
+  Encodes a term to JSON using the module returned by `json_module/0`.
+
+  Returns the encoded JSON, or raises if `term` cannot be encoded.
   """
+  @spec encode(term()) :: binary()
   defdelegate encode(term), to: :jose
 
   @doc """
   Gets the current JSON module used by `decode/1` and `encode/1`, see `json_module/1` for default.
   """
+  @spec json_module() :: module()
   defdelegate json_module(), to: :jose
 
   @doc """
@@ -109,13 +132,15 @@ defmodule JOSE do
     * [`jsone`](https://github.com/sile/jsone)
     * [`jsx`](https://github.com/talentdeficit/jsx)
 
-  Additional modules that implement the `jose_json` behavior may also be used.
+  Additional modules that implement the `:jose_json` behavior may also be used.
   """
+  @spec json_module(module()) :: :ok
   defdelegate json_module(module), to: :jose
 
   @doc """
   Gets the current SHA3 module used by `jose_sha3`, see `sha3_module/1` for default.
   """
+  @spec sha3_module() :: module()
   defdelegate sha3_module(), to: :jose
 
   @doc """
@@ -129,11 +154,13 @@ defmodule JOSE do
 
   Additional modules that implement the `jose_sha3` behavior may also be used.
   """
+  @spec sha3_module(module()) :: :ok
   defdelegate sha3_module(module), to: :jose
 
   @doc """
   Gets the current Unsecured Signing state, defaults to `false`.
   """
+  @spec unsecured_signing() :: boolean()
   defdelegate unsecured_signing(), to: :jose
 
   @doc """
@@ -143,5 +170,6 @@ defmodule JOSE do
 
   See [Critical vulnerabilities in JSON Web Token libraries](https://auth0.com/blog/2015/03/31/critical-vulnerabilities-in-json-web-token-libraries/) for more information.
   """
+  @spec unsecured_signing(boolean()) :: :ok
   defdelegate unsecured_signing(boolean), to: :jose
 end