Revert to allow any term in encodable type.

* Moved the plain JSON types to the top.
* Added type `str` to have a complete set of plain JSON types.
* Refer to options either as encoder or decoder options.
* Renamed some types to include a clarifying enc_/dec_ prefix.

lib/jason.ex

@@ -5,38 +5,47 @@ defmodule Jason do
 
   alias Jason.{Encode, Decoder, DecodeError, EncodeError, Formatter}
 
-  @typedoc "Encoding setting for string escapes."
-  @type escape :: :json | :unicode_safe | :html_safe | :javascript_safe
-  @typedoc "Encoding setting for maps."
-  @type maps :: :naive | :strict
-  @typedoc "Available encoding options."
-  @type encode_opt :: {:escape, escape} | {:maps, maps} | {:pretty, boolean | Formatter.opts()}
+  @typedoc "A plain JSON string."
+  @type str :: String.t()
+  @typedoc "A plain JSON object where keys can only be strings."
+  @type object :: %{optional(str) => value}
+  @typedoc "A plain JSON array with JSON element values."
+  @type array :: [value]
+  @typedoc "A plain JSON value. Meaningful for specs where it's certain that nothing else is contained."
+  @type value :: nil | str | number | boolean | array | object
+
+  @typedoc "Encoder setting for string escapes."
+  @type enc_escape :: :json | :unicode_safe | :html_safe | :javascript_safe
+  @typedoc "Encoder setting for maps."
+  @type enc_maps :: :naive | :strict
+  @typedoc "Available encoder options."
+  @type encode_opt ::
+          {:escape, enc_escape} | {:maps, enc_maps} | {:pretty, boolean | Formatter.opts()}
 
   @typedoc "The type of the value returned by the custom decoder function."
-  @type map_key :: term
+  @type dec_map_key :: term
   @typedoc "Decoding setting for map keys."
-  @type keys :: :atoms | :atoms! | :strings | :copy | (key :: String.t() -> map_key)
+  @type dec_keys :: :atoms | :atoms! | :strings | :copy | (key :: str -> dec_map_key)
   @typedoc "Decoding setting for strings."
-  @type strings :: :reference | :copy
+  @type dec_strings :: :reference | :copy
   @typedoc "Decoding setting for floats."
-  @type floats :: :native | :decimals
+  @type dec_floats :: :native | :decimals
   @typedoc "Decoding setting for objects."
-  @type objects :: :maps | :ordered_objects
+  @type dec_objects :: :maps | :ordered_objects
   @typedoc "Available decoding options."
-  @type decode_opt :: {:keys, keys} | {:strings, strings} | {:floats, floats} | {:objects, objects}
+  @type decode_opt ::
+          {:keys, dec_keys}
+          | {:strings, dec_strings}
+          | {:floats, dec_floats}
+          | {:objects, dec_objects}
 
-  @typedoc "A plain JSON object where keys can only be strings."
-  @type object :: %{String.t() => value}
-  @typedoc "A plain JSON array."
-  @type array :: [value]
-  @typedoc "A plain JSON value."
-  @type value :: nil | String.t() | number | boolean | array | object
   @typedoc "A decoded JSON value where map keys can have any type."
-  @type decoded :: [decoded] | %{map_key => decoded} | value
-  @typedoc "The type of map keys that can be encoded."
-  @type encodable_key :: String.t() | number | atom | [encodable_key]
-  @typedoc "The types that can be encoded. Not included are: `tuple`s, `function`s, `reference`s, `port`s and `pid`s."
-  @type encodable :: String.t() | number | atom | [encodable] | %{encodable_key => encodable}
+  @type decoded :: value | [decoded] | %{optional(dec_map_key) => decoded}
+  @typedoc """
+  The types that can be encoded. In general it will be a JSON `t:value` but
+  it can be any `term` that has the `c:Jason.Encoder` protocol implemented.
+  """
+  @type encodable :: value | term
 
   @doc """
   Parses a JSON value from `input` iodata.
@@ -152,7 +161,7 @@ defmodule Jason do
 
   """
   @spec encode(encodable, [encode_opt]) ::
-          {:ok, String.t()} | {:error, EncodeError.t() | Exception.t()}
+          {:ok, str} | {:error, EncodeError.t() | Exception.t()}
   def encode(input, opts \\ []) do
     case do_encode(input, format_encode_opts(opts)) do
       {:ok, result} -> {:ok, IO.iodata_to_binary(result)}
@@ -175,7 +184,7 @@ defmodule Jason do
       ** (Jason.EncodeError) invalid byte 0xFF in <<255>>
 
   """
-  @spec encode!(encodable, [encode_opt]) :: String.t() | no_return
+  @spec encode!(encodable, [encode_opt]) :: str | no_return
   def encode!(input, opts \\ []) do
     case do_encode(input, format_encode_opts(opts)) do
       {:ok, result} -> IO.iodata_to_binary(result)
@@ -250,10 +259,12 @@ defmodule Jason do
     Encode.encode(input, opts)
   end
 
+  @spec format_encode_opts([encode_opt]) :: %{atom => any}
   defp format_encode_opts(opts) do
     Enum.into(opts, %{escape: :json, maps: :naive})
   end
 
+  @spec format_decode_opts([encode_opt]) :: %{atom => any}
   defp format_decode_opts(opts) do
     Enum.into(opts, %{keys: :strings, strings: :reference, floats: :native, objects: :maps})
   end