Tweak specs for better docs visualization (#88)

williamthome · Aug 6, 2024 · 7daca0c · 7daca0c
1 parent 62e88c5
commit 7daca0c
Show file tree

Hide file tree

Showing 4 changed files with 46 additions and 21 deletions.
diff --git a/src/euneus.erl b/src/euneus.erl
@@ -42,7 +42,8 @@
 %% API functions
 %% --------------------------------------------------------------------
 
--spec encode(term()) -> binary().
+-spec encode(Term) -> binary() when
+    Term :: term().
 %% @doc Encodes a term into a binary JSON.
 %%
 %% <em>Example:</em>
@@ -54,7 +55,9 @@
 encode(Term) ->
     encode(Term, #{}).
 
--spec encode(term(), euneus_encoder:options()) -> binary().
+-spec encode(Term, Options) -> binary() when
+    Term :: term(),
+    Options :: euneus_encoder:options().
 %% @doc Encodes a term into a binary JSON.
 %%
 %% <em>Example:</em>
@@ -66,7 +69,8 @@ encode(Term) ->
 encode(Term, Opts) ->
     iolist_to_binary(euneus_encoder:encode(Term, Opts)).
 
--spec encode_to_iodata(term()) -> iodata().
+-spec encode_to_iodata(Term) -> iodata() when
+    Term :: term().
 %% @doc Encodes a term into an iodata JSON.
 %%
 %% <em>Example:</em>
@@ -78,7 +82,9 @@ encode(Term, Opts) ->
 encode_to_iodata(Term) ->
     encode_to_iodata(Term, #{}).
 
--spec encode_to_iodata(term(), euneus_encoder:options()) -> iodata().
+-spec encode_to_iodata(Term, Options) -> iodata() when
+    Term :: term(),
+    Options :: euneus_encoder:options().
 %% @doc Encodes a term into an iodata JSON.
 %%
 %% <em>Example:</em>
@@ -90,7 +96,8 @@ encode_to_iodata(Term) ->
 encode_to_iodata(Term, Opts) ->
     euneus_encoder:encode(Term, Opts).
 
--spec decode(binary()) -> term().
+-spec decode(JSON) -> term() when
+    JSON :: binary().
 %% @doc Decodes a binary JSON into a term.
 %%
 %% <em>Example:</em>
@@ -102,7 +109,9 @@ encode_to_iodata(Term, Opts) ->
 decode(JSON) ->
     decode(JSON, #{}).
 
--spec decode(binary(), euneus_decoder:options()) -> term().
+-spec decode(JSON, Options) -> term() when
+    JSON :: binary(),
+    Options :: euneus_decoder:options().
 %% @doc Decodes a binary JSON into a term.
 %%
 %% <em>Example:</em>
@@ -114,7 +123,8 @@ decode(JSON) ->
 decode(JSON, Opts) ->
     euneus_decoder:decode(JSON, Opts).
 
--spec decode_iodata(iodata()) -> term().
+-spec decode_iodata(JSON) -> term() when
+    JSON :: iodata().
 %% @doc Decodes an iodata JSON into a term.
 %%
 %% <em>Example:</em>
@@ -126,7 +136,9 @@ decode(JSON, Opts) ->
 decode_iodata(JSON) ->
     decode_iodata(JSON, #{}).
 
--spec decode_iodata(iodata(), euneus_decoder:options()) -> term().
+-spec decode_iodata(JSON, Options) -> term() when
+    JSON :: iodata(),
+    Options :: euneus_decoder:options().
 %% @doc Decodes an iodata JSON into a term.
 %%
 %% <em>Example:</em>
@@ -138,7 +150,8 @@ decode_iodata(JSON) ->
 decode_iodata(JSON, Opts) ->
     euneus_decoder:decode(iolist_to_binary(JSON), Opts).
 
--spec minify(binary()) -> binary().
+-spec minify(JSON) -> binary() when
+    JSON :: binary().
 %% @doc Minifies a binary JSON.
 %%
 %% <em>Example:</em>
@@ -155,7 +168,9 @@ minify(JSON) ->
         crlf => none
     }).
 
--spec format(binary(), euneus_formatter:options()) -> binary().
+-spec format(JSON, Options) -> binary() when
+    JSON :: binary(),
+    Options :: euneus_formatter:options().
 %% @doc Formats a binary JSON.
 %%
 %% <em>Example:</em>

diff --git a/src/euneus_decoder.erl b/src/euneus_decoder.erl
@@ -87,7 +87,9 @@
 %% API functions
 %% --------------------------------------------------------------------
 
--spec decode(binary(), options()) -> term().
+-spec decode(JSON, Options) -> term() when
+    JSON :: binary(),
+    Options :: options().
 %% @doc Decodes a binary JSON into a term.
 %%
 %% <em>Example:</em>

diff --git a/src/euneus_encoder.erl b/src/euneus_encoder.erl
@@ -156,7 +156,9 @@
 %% API functions
 %% --------------------------------------------------------------------
 
--spec encode(term(), options()) -> iodata().
+-spec encode(Term, Options) -> iodata() when
+    Term :: term(),
+    Options :: options().
 %% @doc Encode a term into an iodata JSON.
 %%
 %% <em>Example:</em>
@@ -402,10 +404,12 @@
 %%     Default is `encode_term/2', which raises `unsupported_term' error.
 %%   </li>
 %% </ul>
-encode(Input, Opts) ->
-    json:encode(Input, encoder(new_state(Opts))).
+encode(Term, Opts) ->
+    json:encode(Term, encoder(new_state(Opts))).
 
--spec continue(term(), state()) -> iodata().
+-spec continue(Term, State) -> iodata() when
+    Term :: term(),
+    State :: state().
 %% @doc Used by encoders to continue encoding.
 %%
 %% <em>Example:</em>
@@ -446,7 +450,9 @@ continue(Ref, State) when is_reference(Ref) ->
 continue(Term, State) ->
     (State#state.encode_term)(Term, State).
 
--spec codec_callback(codec(), tuple()) -> codec_result().
+-spec codec_callback(Codec, Tuple) -> codec_result() when
+    Codec :: codec(),
+    Tuple :: tuple().
 codec_callback(timestamp, Tuple) ->
     timestamp_codec_callback(Tuple);
 codec_callback(datetime, Tuple) ->
@@ -472,12 +478,12 @@ key_to_binary(Int) when is_integer(Int) ->
     integer_to_binary(Int, 10).
 
 -spec escape(binary()) -> iodata().
-escape(Bin) ->
-    json:encode_binary(Bin).
+escape(Binary) ->
+    json:encode_binary(Binary).
 
 -spec encode_integer(integer(), state()) -> iodata().
-encode_integer(Int, _State) ->
-    erlang:integer_to_binary(Int, 10).
+encode_integer(Integer, _State) ->
+    erlang:integer_to_binary(Integer, 10).
 
 -spec encode_float(float(), state()) -> iodata().
 -if(?OTP_RELEASE >= 25).

diff --git a/src/euneus_formatter.erl b/src/euneus_formatter.erl
@@ -36,7 +36,9 @@
 %% API functions
 %% --------------------------------------------------------------------
 
--spec format(binary(), options()) -> iodata().
+-spec format(JSON, Options) -> iodata() when
+    JSON :: binary(),
+    Options :: options().
 %% @doc Formats a binary JSON.
 %%
 %% Option details: