syntax_tools: Add types and specs for most exported functions

While at it, consistently replace "bool()" with "boolean()"
in the Edoc specs.

1 files changed, 61 insertions, 10 deletions

diff --git a/lib/syntax_tools/src/epp_dodger.erl b/lib/syntax_tools/src/epp_dodger.erl
index 7aef549574..6b0f2034f8 100644
--- a/lib/syntax_tools/src/epp_dodger.erl
+++ b/lib/syntax_tools/src/epp_dodger.erl
@@ -90,6 +90,9 @@
 %% This is a so-called Erlang I/O ErrorInfo structure; see the {@link
 %% //stdlib/io} module for details.
 
+-type errorinfo() :: term(). % {integer(), atom(), term()}.
+
+-type option() :: atom() | {atom(), term()}.
 
 %% =====================================================================
 %% @spec parse_file(File) -> {ok, Forms} | {error, errorinfo()}
@@ -98,6 +101,9 @@
 %% 
 %% @equiv parse_file(File, [])
 
+-spec parse_file(file:filename()) ->
+        {'ok', erl_syntax:forms()} | {'error', errorinfo()}.
+
 parse_file(File) ->
     parse_file(File, []).
 
@@ -109,11 +115,11 @@ parse_file(File) ->
 %% @doc Reads and parses a file. If successful, `{ok, Forms}'
 %% is returned, where `Forms' is a list of abstract syntax
 %% trees representing the "program forms" of the file (cf.
-%% `erl_syntax:is_form/1'). Otherwise, `{error,
-%% errorinfo()}' is returned, typically if the file could not be
-%% opened. Note that parse errors show up as error markers in the
-%% returned list of forms; they do not cause this function to fail or
-%% return `{error,errorinfo()}'.
+%% `erl_syntax:is_form/1'). Otherwise, `{error, errorinfo()}' is
+%% returned, typically if the file could not be opened. Note that
+%% parse errors show up as error markers in the returned list of
+%% forms; they do not cause this function to fail or return
+%% `{error, errorinfo()}'.
 %%
 %% Options:
 %% <dl>
@@ -135,6 +141,9 @@ parse_file(File) ->
 %% @see quick_parse_file/1
 %% @see erl_syntax:is_form/1
 
+-spec parse_file(file:filename(), [option()]) ->
+        {'ok', erl_syntax:forms()} | {'error', errorinfo()}.
+
 parse_file(File, Options) ->
     parse_file(File, fun parse/3, Options).
 
@@ -144,6 +153,9 @@ parse_file(File, Options) ->
 %%
 %% @equiv quick_parse_file(File, [])
 
+-spec quick_parse_file(file:filename()) ->
+        {'ok', erl_syntax:forms()} | {'error', errorinfo()}.
+
 quick_parse_file(File) ->
     quick_parse_file(File, []).
 
@@ -167,6 +179,9 @@ quick_parse_file(File) ->
 %% @see quick_parse/2
 %% @see parse_file/2
 
+-spec quick_parse_file(file:filename(), [option()]) ->
+        {'ok', erl_syntax:forms()} | {'error', errorinfo()}.
+
 quick_parse_file(File, Options) ->
     parse_file(File, fun quick_parse/3, Options ++ [no_fail]).
 
@@ -185,6 +200,8 @@ parse_file(File, Parser, Options) ->
 %% @spec parse(IODevice) -> {ok, Forms} | {error, errorinfo()}
 %% @equiv parse(IODevice, 1)
 
+-spec parse(file:io_device()) -> {'ok', erl_syntax:forms()}.
+
 parse(Dev) ->
     parse(Dev, 1).
 
@@ -196,6 +213,8 @@ parse(Dev) ->
 %% @equiv parse(IODevice, StartLine, [])
 %% @see parse/1
 
+-spec parse(file:io_device(), integer()) -> {'ok', erl_syntax:forms()}.
+
 parse(Dev, L) ->
     parse(Dev, L, []).
 
@@ -216,12 +235,18 @@ parse(Dev, L) ->
 %% @see parse_form/2
 %% @see quick_parse/3
 
+-spec parse(file:io_device(), integer(), [option()]) ->
+        {'ok', erl_syntax:forms()}.
+
 parse(Dev, L0, Options) ->
     parse(Dev, L0, fun parse_form/3, Options).
 
 %% @spec quick_parse(IODevice) -> {ok, Forms} | {error, errorinfo()}
 %% @equiv quick_parse(IODevice, 1)
 
+-spec quick_parse(file:io_device()) ->
+        {'ok', erl_syntax:forms()}.
+
 quick_parse(Dev) ->
     quick_parse(Dev, 1).
 
@@ -234,6 +259,9 @@ quick_parse(Dev) ->
 %% @equiv quick_parse(IODevice, StartLine, [])
 %% @see quick_parse/1
 
+-spec quick_parse(file:io_device(), integer()) ->
+        {'ok', erl_syntax:forms()}.
+
 quick_parse(Dev, L) ->
     quick_parse(Dev, L, []).
 
@@ -252,6 +280,9 @@ quick_parse(Dev, L) ->
 %% @see quick_parse_form/2
 %% @see parse/3
 
+-spec quick_parse(file:io_device(), integer(), [option()]) ->
+        {'ok', erl_syntax:forms()}.
+
 quick_parse(Dev, L0, Options) ->
     parse(Dev, L0, fun quick_parse_form/3, Options).
 
@@ -284,6 +315,10 @@ parse(Dev, L0, Fs, Parser, Options) ->
 %%
 %% @see quick_parse_form/2
 
+-spec parse_form(file:io_device(), integer()) ->
+        {'ok', erl_syntax:forms(), integer()}
+      | {'eof', integer()} | {'error', errorinfo(), integer()}.
+
 parse_form(Dev, L0) ->
     parse_form(Dev, L0, []).
 
@@ -310,6 +345,10 @@ parse_form(Dev, L0) ->
 %% @see parse_form/2
 %% @see quick_parse_form/3
 
+-spec parse_form(file:io_device(), integer(), [option()]) ->
+        {'ok', erl_syntax:forms(), integer()}
+      | {'eof', integer()} | {'error', errorinfo(), integer()}.
+
 parse_form(Dev, L0, Options) ->
     parse_form(Dev, L0, fun normal_parser/2, Options).
 
@@ -326,6 +365,10 @@ parse_form(Dev, L0, Options) ->
 %%
 %% @see parse_form/2
 
+-spec quick_parse_form(file:io_device(), integer()) ->
+        {'ok', erl_syntax:forms(), integer()}
+      | {'eof', integer()} | {'error', errorinfo(), integer()}.
+
 quick_parse_form(Dev, L0) ->
     quick_parse_form(Dev, L0, []).
 
@@ -347,6 +390,10 @@ quick_parse_form(Dev, L0) ->
 %% @see quick_parse_form/2
 %% @see parse_form/3
 
+-spec quick_parse_form(file:io_device(), integer(), [option()]) ->
+        {'ok', erl_syntax:forms(), integer()}
+      | {'eof', integer()} | {'error', errorinfo(), integer()}.
+
 quick_parse_form(Dev, L0, Options) ->
     parse_form(Dev, L0, fun quick_parser/2, Options).
 
@@ -751,11 +798,13 @@ fix_define([{atom, L, ?pp_form}, {'(', _}, {')', _}, {'->', _},
 fix_define(_Ts) ->
     error.
 
-%% @spec (Tokens::[term()]) -> string()
+%% @spec tokens_to_string(Tokens::[term()]) -> string()
 %% 
 %% @doc Generates a string corresponding to the given token sequence.
 %% The string can be re-tokenized to yield the same token list again.
 
+-spec tokens_to_string([term()]) -> string().
+
 tokens_to_string([{atom,_,A} | Ts]) ->
     io_lib:write_atom(A) ++ " " ++ tokens_to_string(Ts);
 tokens_to_string([{string, _, S} | Ts]) ->
@@ -764,21 +813,23 @@ tokens_to_string([{float, _, F} | Ts]) ->
     float_to_list(F) ++ " " ++ tokens_to_string(Ts);
 tokens_to_string([{integer, _, N} | Ts]) ->
     integer_to_list(N) ++ " " ++ tokens_to_string(Ts);
-tokens_to_string([{var,_,A} | Ts]) ->
+tokens_to_string([{var, _, A} | Ts]) ->
     atom_to_list(A) ++ " " ++ tokens_to_string(Ts);
-tokens_to_string([{dot,_} | Ts]) ->
+tokens_to_string([{dot, _} | Ts]) ->
     ".\n" ++ tokens_to_string(Ts);
-tokens_to_string([{A,_} | Ts]) ->
+tokens_to_string([{A, _} | Ts]) ->
     atom_to_list(A) ++ " " ++ tokens_to_string(Ts);
 tokens_to_string([]) ->
     "".
 
 
-%% @spec (Descriptor::term()) -> string()
+%% @spec format_error(Descriptor::term()) -> string()
 %% @hidden
 %% @doc Callback function for formatting error descriptors. Not for
 %% normal use.
 
+-spec format_error(term()) -> string().
+
 format_error(macro_args) ->
     errormsg("macro call missing end parenthesis");
 format_error({unknown, Reason}) ->