From bd19f3fbaf85be5be1cb463f9594dd20291dcf00 Mon Sep 17 00:00:00 2001
From: Andrea Leopardi <an.leopardi@gmail.com>
Date: Sun, 10 Dec 2023 12:43:19 +0100
Subject: [PATCH] Add @specs to the JOSE module

---
 lib/jose.ex | 42 +++++++++++++++++++++++++++++++++++-------
 1 file changed, 35 insertions(+), 7 deletions(-)

diff --git a/lib/jose.ex b/lib/jose.ex
index b8db021..8ecac46 100644
--- 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