Update type definitions and edoc comments

doc/jsone.md

@@ -17,6 +17,20 @@ JSON decoding/encoding module.
 
 
 
+### <a name="type-encode_option">encode_option()</a> ###
+
+
+
+<pre><code>
+encode_option() = native_utf8
+</code></pre>
+
+
+
+  native_utf8: Encodes UTF-8 characters as a human-readable(non-escaped) string
+
+
+
 ### <a name="type-json_array">json_array()</a> ###
 
 
@@ -103,7 +117,7 @@ json_value() = <a href="#type-json_number">json_number()</a> | <a href="#type-js
 ## Function Index ##
 
 
-<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#decode-1">decode/1</a></td><td>Decodes an erlang term from json text (a utf8 encoded binary).</td></tr><tr><td valign="top"><a href="#encode-1">encode/1</a></td><td>Encodes an erlang term into json text (a utf8 encoded binary).</td></tr><tr><td valign="top"><a href="#try_decode-1">try_decode/1</a></td><td>Decodes an erlang term from json text (a utf8 encoded binary).</td></tr><tr><td valign="top"><a href="#try_encode-1">try_encode/1</a></td><td>Encodes an erlang term into json text (a utf8 encoded binary).</td></tr></table>
+<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#decode-1">decode/1</a></td><td>Decodes an erlang term from json text (a utf8 encoded binary).</td></tr><tr><td valign="top"><a href="#encode-1">encode/1</a></td><td>Equivalent to <a href="#encode-2"><tt>encode(JsonValue, [])</tt></a>.</td></tr><tr><td valign="top"><a href="#encode-2">encode/2</a></td><td>Encodes an erlang term into json text (a utf8 encoded binary).</td></tr><tr><td valign="top"><a href="#try_decode-1">try_decode/1</a></td><td>Decodes an erlang term from json text (a utf8 encoded binary).</td></tr><tr><td valign="top"><a href="#try_encode-1">try_encode/1</a></td><td>Equivalent to <a href="#try_encode-2"><tt>try_encode(JsonValue, [])</tt></a>.</td></tr><tr><td valign="top"><a href="#try_encode-2">try_encode/2</a></td><td>Encodes an erlang term into json text (a utf8 encoded binary).</td></tr></table>
 
 
 <a name="functions"></a>
@@ -153,6 +167,19 @@ encode(JsonValue::<a href="#type-json_value">json_value()</a>) -&gt; binary()
 <br></br>
 
 
+Equivalent to [`encode(JsonValue, [])`](#encode-2).
+<a name="encode-2"></a>
+
+### encode/2 ###
+
+
+<pre><code>
+encode(JsonValue::<a href="#type-json_value">json_value()</a>, Options::[<a href="#type-encode_option">encode_option()</a>]) -&gt; binary()
+</code></pre>
+
+<br></br>
+
+
 
 Encodes an erlang term into json text (a utf8 encoded binary)
 
@@ -210,6 +237,19 @@ try_encode(JsonValue::<a href="#type-json_value">json_value()</a>) -&gt; {ok, bi
 <br></br>
 
 
+Equivalent to [`try_encode(JsonValue, [])`](#try_encode-2).
+<a name="try_encode-2"></a>
+
+### try_encode/2 ###
+
+
+<pre><code>
+try_encode(JsonValue::<a href="#type-json_value">json_value()</a>, Options::[<a href="#type-encode_option">encode_option()</a>]) -&gt; {ok, binary()} | {error, {Reason::term(), [<a href="erlang.md#type-stack_item">erlang:stack_item()</a>]}}
+</code></pre>
+
+<br></br>
+
+
 
 Encodes an erlang term into json text (a utf8 encoded binary)
 

src/jsone.erl

@@ -42,11 +42,13 @@
               json_array/0,
               json_object/0,
               json_object_members/0,
-              json_boolean/0
+              json_boolean/0,
+
+              encode_option/0
              ]).
 
 %%--------------------------------------------------------------------------------
-%% Types
+%% Types & Macros
 %%--------------------------------------------------------------------------------
 -type json_value()          :: json_number() | json_string() | json_array() | json_object() | json_boolean() | null.
 -type json_boolean()        :: boolean().
@@ -56,10 +58,10 @@
 -type json_object()         :: {json_object_members()}.
 -type json_object_members() :: [{json_string(), json_value()}].
 
--type option()              :: {atom(), atom()|boolean()}.
--export_type([option/0]).
+-type encode_option() :: native_utf8.
+%% native_utf8: Encodes UTF-8 characters as a human-readable(non-escaped) string
 
--define(DEFAULT_OPTIONS, []).
+-define(DEFAULT_ENCODE_OPTIONS, []).
 
 %%--------------------------------------------------------------------------------
 %% Exported Functions
@@ -71,7 +73,7 @@
 %% ```
 %% > jsone:decode(<<"1">>).
 %% 1
-%% 
+%%
 %% > jsone:decode(<<"wrong json">>).
 %% ** exception error: bad argument
 %%     in function  jsone_decode:number_integer_part/4
@@ -93,7 +95,7 @@ decode(Json) ->
 %% ```
 %% > jsone:try_decode(<<"[1,2,3] \"next value\"">>).
 %% {ok,[1,2,3],<<" \"next value\"">>}
-%%  
+%%
 %% > jsone:try_decode(<<"wrong json">>).
 %% {error,{badarg,[{jsone_decode,number_integer_part,
 %%                               [<<"wrong json">>,1,[],<<>>],
@@ -103,6 +105,11 @@ decode(Json) ->
 try_decode(Json) ->
     jsone_decode:decode(Json).
 
+%% @equiv encode(JsonValue, [])
+-spec encode(json_value()) -> binary().
+encode(JsonValue) ->
+    encode(JsonValue, ?DEFAULT_ENCODE_OPTIONS).
+
 %% @doc Encodes an erlang term into json text (a utf8 encoded binary)
 %%
 %% Raises an error exception if input is not an instance of type `json_value()'
@@ -110,18 +117,14 @@ try_decode(Json) ->
 %% ```
 %% > jsone:encode([1, null, 2]).
 %% <<"[1,null,2]">>
-%%  
+%%
 %% > jsone:encode([1, hoge, 2]).  % 'hoge' atom is not a json value
 %% ** exception error: bad argument
 %%      in function  jsone_encode:value/3
 %%         called as jsone_encode:value(hoge,[{array_values,[2]}],<<"[1,">>)
 %%      in call from jsone:encode/1 (src/jsone.erl, line 97)
 %% '''
--spec encode(json_value()) -> binary().
-encode(JsonValue) ->
-    encode(JsonValue, ?DEFAULT_OPTIONS).
-
--spec encode(json_value(), [option()]) -> binary().
+-spec encode(json_value(), [encode_option()]) -> binary().
 encode(JsonValue, Options) ->
     try
         {ok, Binary} = try_encode(JsonValue, Options),
@@ -131,21 +134,22 @@ encode(JsonValue, Options) ->
             erlang:raise(error, Reason, [StackItem | erlang:get_stacktrace()])
     end.
 
+%% @equiv try_encode(JsonValue, [])
+-spec try_encode(json_value()) -> {ok, binary()} | {error, {Reason::term(), [erlang:stack_item()]}}.
+try_encode(JsonValue) ->
+    jsone_encode:encode(JsonValue, ?DEFAULT_ENCODE_OPTIONS).
+
 %% @doc Encodes an erlang term into json text (a utf8 encoded binary)
 %%
 %% ```
 %% > jsone:try_encode([1, null, 2]).
 %% {ok,<<"[1,null,2]">>}
-%%  
+%%
 %% > jsone:try_encode([1, hoge, 2]).  % 'hoge' atom is not a json value
 %% {error,{badarg,[{jsone_encode,value,
 %%                               [hoge,[{array_values,[2]}],<<"[1,">>],
 %%                               [{line,86}]}]}}
 %% '''
--spec try_encode(json_value()) -> {ok, binary()} | {error, {Reason::term(), [erlang:stack_item()]}}.
-try_encode(JsonValue) ->
-    jsone_encode:encode(JsonValue, ?DEFAULT_OPTIONS).
-
--spec try_encode(json_value(), [option()]) -> {ok, binary()} | {error, {Reason::term(), [erlang:stack_item()]}}.
+-spec try_encode(json_value(), [encode_option()]) -> {ok, binary()} | {error, {Reason::term(), [erlang:stack_item()]}}.
 try_encode(JsonValue, Options) ->
     jsone_encode:encode(JsonValue, Options).

src/jsone_encode.erl

@@ -57,7 +57,7 @@
 encode(Value) ->
     jsone:try_encode(Value).
 
--spec encode(jsone:json_value(), [jsone:option()]) -> encode_result().
+-spec encode(jsone:json_value(), [jsone:encode_option()]) -> encode_result().
 encode(Value, Options) ->
     Opt = parse_options(Options),
     value(Value, [], <<"">>, Opt).
@@ -169,7 +169,7 @@ object_value(Value, Members, Nexts, Buf, Opt) ->
     value(Value, [{object_members, Members} | Nexts], <<Buf/binary, $:>>, Opt).
 
 
--spec parse_options([jsone:option()]) -> encode_opt().
+-spec parse_options([jsone:encode_option()]) -> encode_opt().
 parse_options(Options) ->
     parse_option(Options, ?ENCODE_OPT{}).