Merge branch 'hasse/erl_docgen/generated_type_links/ERL-120/OTP-13720' into maint

* hasse/erl_docgen/generated_type_links/ERL-120/OTP-13720:
  wx: Prepare for using Erlang types and specs
  syntax_tools: Improve types
  syntax_tools: Improve seealso:s referring to types
  erl_docgen: Allow 'seealso' in 'name'
  erl_docgen: Generate type links in callback module creating erlref
  erl_docgen: Correct callback module for creating erlref
  erl_docgen: Improve callback module for creating erlref
  edoc: Correct types

18 files changed, 409 insertions, 71 deletions

diff --git a/lib/edoc/src/edoc_extract.erl b/lib/edoc/src/edoc_extract.erl
index e7a4c36ca4..2d6cb04a6d 100644
--- a/lib/edoc/src/edoc_extract.erl
+++ b/lib/edoc/src/edoc_extract.erl
@@ -32,9 +32,9 @@
 %% %% @headerfile "edoc.hrl" (disabled until it can be made private)
 -include("edoc.hrl").
 
-%% @type filename() = file:filename().
-%% @type proplist() = proplists:property().
-%% @type syntaxTree() = erl_syntax:syntaxTree().
+%% @type filename() = //kernel/file:filename().
+%% @type proplist() = //stdlib/proplists:property().
+%% @type syntaxTree() = //syntax_tools/erl_syntax:syntaxTree().
 
 %% @spec source(File::filename(), Env::edoc_env(), Options::proplist())
 %%             -> {ModuleName, edoc:edoc_module()}
@@ -639,11 +639,11 @@ file_macros(_Context, Env) ->
 %%
 %% The idea is to mimic how the @type tag works.
 %% Using @type:
-%%   @type t() = t1(). Some docs of t/0;
-%%   Further docs of t/0.
+%%```@type t() = t1(). Some docs of t/0;
+%%   Further docs of t/0.'''
 %% The same thing using -type:
-%%   -type t() :: t1(). % Some docs of t/0;
-%%   Further docs of t/0.
+%%```-type t() :: t1(). % Some docs of t/0;
+%%   Further docs of t/0.'''
 find_type_docs(Forms0, Comments, Env, File) ->
     Tree = erl_recomment:recomment_forms(Forms0, Comments),
     Forms = preprocess_forms(Tree),
diff --git a/lib/edoc/src/edoc_lib.erl b/lib/edoc/src/edoc_lib.erl
index dcc239f6b4..cc0a8d0b94 100644
--- a/lib/edoc/src/edoc_lib.erl
+++ b/lib/edoc/src/edoc_lib.erl
@@ -935,7 +935,7 @@ get_doc_env(Opts) ->
 %%     Modules = [atom()]
 %%     proplist() = [term()]
 %%
-%% @type proplist() = proplists:property().
+%% @type proplist() = //stdlib/proplists:property().
 %% @type edoc_env(). Environment information needed by EDoc for
 %% generating references. The data representation is not documented.
 %%
diff --git a/lib/erl_docgen/priv/bin/xref_mod_app.escript b/lib/erl_docgen/priv/bin/xref_mod_app.escript
index ac4278bf22..4a418fe144 100755
--- a/lib/erl_docgen/priv/bin/xref_mod_app.escript
+++ b/lib/erl_docgen/priv/bin/xref_mod_app.escript
@@ -84,7 +84,7 @@ preloaded(TopDir) ->
 %% It's OK if too much data is generated as long as all applications
 %% and all modules are mentioned.
 appmods(D) ->
-    ErlFiles = filelib:wildcard(filename:join([D,"src","*.erl"])),
+    ErlFiles = filelib:wildcard(filename:join([D,"src","**","*.erl"])),
     AppV = filename:basename(D),
     App = case string:rstr(AppV, "-") of
               0 -> AppV;
diff --git a/lib/erl_docgen/priv/dtd/erlref.dtd b/lib/erl_docgen/priv/dtd/erlref.dtd
index 835407520a..615b88b61a 100644
--- a/lib/erl_docgen/priv/dtd/erlref.dtd
+++ b/lib/erl_docgen/priv/dtd/erlref.dtd
@@ -29,7 +29,7 @@
 
 <!-- `name' is used in common.refs.dtd and must therefore 
       be defined in each *ref. dtd -->
-<!ELEMENT name                (#PCDATA) >
+<!ELEMENT name                (#PCDATA|seealso)* >
 <!ATTLIST name                 name CDATA #IMPLIED
                                arity CDATA #IMPLIED
 	                       clause_i CDATA #IMPLIED
diff --git a/lib/erl_docgen/priv/xsl/db_html.xsl b/lib/erl_docgen/priv/xsl/db_html.xsl
index fe6c7d3c28..edab8e1c7e 100644
--- a/lib/erl_docgen/priv/xsl/db_html.xsl
+++ b/lib/erl_docgen/priv/xsl/db_html.xsl
@@ -2007,10 +2007,10 @@
         </xsl:variable>
 	<xsl:choose>
 	  <xsl:when test="ancestor::datatype">
-            <a name="type-{$fname}"><span class="bold_code"><xsl:value-of select="."/></span></a><br/>
+            <a name="type-{$fname}"></a><span class="bold_code"><xsl:apply-templates/></span><br/>
 	  </xsl:when>
           <xsl:otherwise>
-            <a name="{$fname}-{$arity}"><span class="bold_code"><xsl:value-of select="."/></span></a><br/>
+            <a name="{$fname}-{$arity}"></a><span class="bold_code"><xsl:apply-templates/></span><br/>
           </xsl:otherwise>
 	</xsl:choose>
       </xsl:when>
diff --git a/lib/erl_docgen/src/docgen_edoc_xml_cb.erl b/lib/erl_docgen/src/docgen_edoc_xml_cb.erl
index 0ac7985a48..4f3af1f767 100644
--- a/lib/erl_docgen/src/docgen_edoc_xml_cb.erl
+++ b/lib/erl_docgen/src/docgen_edoc_xml_cb.erl
@@ -1,7 +1,7 @@
 %%
 %% %CopyrightBegin%
 %%
-%% Copyright Ericsson AB 2001-2015. All Rights Reserved.
+%% Copyright Ericsson AB 2001-2016. All Rights Reserved.
 %%
 %% Licensed under the Apache License, Version 2.0 (the "License");
 %% you may not use this file except in compliance with the License.
@@ -563,7 +563,14 @@ otp_xmlify_a_fileref(FileRef1, AppS) ->
 			 true ->
 			     case split(Marker0, "-") of
 				 [Func,Arity] ->
-				     Func++"/"++Arity;
+                                     try list_to_integer(Arity) of
+                                         _ ->
+                                             Func++"/"++Arity
+                                     catch
+                                         _:_ ->
+                                             %% This is "type-"<a-type>.
+                                             Marker0
+                                     end;
 				 _ ->
 				     Marker0
 			     end
@@ -831,19 +838,49 @@ local_types([]) -> [];
 local_types(Es) ->
     local_defs2(get_elem(localdef, Es)).
 
+-define(LOCAL_TYPES, edoc_local_defs).
+
 local_defs2([]) -> [];
 local_defs2(Es) ->
+    case collect_local_types(Es) of
+        [] -> local_defs3(Es);
+        LocalTypes ->
+            ?LOCAL_TYPES = ets:new(?LOCAL_TYPES, [named_table]),
+            true = ets:insert(?LOCAL_TYPES, LocalTypes),
+            try
+                local_defs3(Es)
+            after
+                ets:delete(?LOCAL_TYPES)
+            end
+    end.
+
+local_defs3(Es) ->
     {type,[?NL | [{v, localdef2(E)} || E <- Es]]}.
 
+%% Does not work well for parametrized types.
+collect_local_types(Es) ->
+    lists:append([collect_local_type(E) || E <- Es]).
+
+collect_local_type(#xmlElement{content = Es}) ->
+    case get_elem(typevar, Es) of
+        [] ->
+            [{t_abstype(get_content(abstype, Es))}];
+        [_] ->
+            []
+    end.
+
 %% Like localdef/1, but does not use label_anchor/2 -- we don't want any
 %% markers or em tags in <v> tag, plain text only!
+%% When used stand-alone, EDoc generates links to local types. An ETS
+%% table holds local types, to avoid generating links to them.
 localdef2(#xmlElement{content = Es}) ->
-    case get_elem(typevar, Es) of
-	[] -> 
-	    t_utype(get_elem(type, Es));
-	[V] ->
-	    t_var(V) ++ [" = "] ++ t_utype(get_elem(type, Es))
-    end.
+    Var = case get_elem(typevar, Es) of
+              [] ->
+		  [t_abstype(get_content(abstype, Es))];
+              [V] ->
+                  t_var(V)
+          end,
+    Var ++ [" = "] ++ t_utype(get_elem(type, Es)).
 
 type_name(#xmlElement{content = Es}) ->
     t_name(get_elem(erlangName, get_content(typedef, Es))).
@@ -855,10 +892,9 @@ types(Ts) ->
 typedecl(Name, #xmlElement{content = Es}) ->
     TypedefEs = get_content(typedef, Es),
     Id = "type-"++Name,
-    [{tag, typedef(TypedefEs)},
+    [{tag, [{marker,[{id,Id}],[]}] ++ typedef(TypedefEs)},
      ?NL,
-     {item, [{marker,[{id,Id}],[]} |
-	     local_defs(get_elem(localdef, TypedefEs)) ++ fulldesc(Es)]},
+     {item, local_defs(get_elem(localdef, TypedefEs)) ++ fulldesc(Es)},
      ?NL].
 
 typedef(Es) ->
@@ -866,14 +902,14 @@ typedef(Es) ->
   	    ++ seq(fun t_utype_elem/1, get_content(argtypes, Es), [")"])),
     case get_elem(type, Es) of
  	 [] ->
-	    [{tt, Name}];
+	    Name;
  	 Type ->
-	    [{tt, Name ++ [" = "] ++ t_utype(Type)}]
+	    Name ++ [" = "] ++ t_utype(Type)
     end.
 
-local_defs([]) -> [];
+local_defs([]) -> [{p,[]}];
 local_defs(Es) ->
-    [?NL, {ul, [{li, [{tt, localdef(E)}]} || E <- Es]}].
+    [?NL, {ul, [{li, [{p, localdef(E)}]} || E <- Es]}].
 
 localdef(E = #xmlElement{content = Es}) ->
     Var = case get_elem(typevar, Es) of
@@ -917,6 +953,7 @@ seealso_module(Es) ->
 	Es1 ->
 	    {section,[{title,["See also"]},{p,seq(fun see/1, Es1, [])}]}
     end.
+
 seealso_function(Es) ->
     case get_elem(see, Es) of
 	[] -> [];
@@ -988,7 +1025,14 @@ t_name([E]) ->
     end.
 
 t_utype([E]) ->
-    t_utype_elem(E).
+    flatten_type(t_utype_elem(E)).
+
+%% Make sure see also are top elements of lists.
+flatten_type(T) ->
+    [case is_integer(E) of
+         true -> [E];
+         false -> E
+     end || E <- lists:flatten(T)].
 
 t_utype_elem(E=#xmlElement{content = Es}) ->
     case get_attrval(name, E) of
@@ -1021,16 +1065,14 @@ t_type([#xmlElement{name = tuple, content = Es}]) ->
     t_tuple(Es);
 t_type([#xmlElement{name = 'fun', content = Es}]) ->
     t_fun(Es);
-t_type([#xmlElement{name = abstype, content = Es}]) ->
-    t_abstype(Es);
+t_type([E = #xmlElement{name = abstype, content = Es}]) ->
+    t_abstype(E, Es);
 t_type([#xmlElement{name = union, content = Es}]) ->
     t_union(Es);
 t_type([#xmlElement{name = record, content = Es}]) ->
     t_record(Es);
 t_type([#xmlElement{name = map, content = Es}]) ->
-    t_map(Es);
-t_type([#xmlElement{name = map_field, content = Es}]) ->
-    t_map_field(Es).
+    t_map(Es).
 
 t_var(E) ->
     [get_attrval(name, E)].
@@ -1065,35 +1107,53 @@ t_fun(Es) ->
 
 t_record([E|Es]) ->
     ["#", get_attrval(value, E), "{"++ seq(fun t_field/1, Es) ++"}"].
+
 t_field(#xmlElement{name=field, content=[Atom,Type]}) ->
     [get_attrval(value, Atom), "="] ++ t_utype_elem(Type).
 
 t_map(Es) ->
-    ["#{"] ++ seq(fun t_utype_elem/1, Es, ["}"]).
+    ["#{"] ++ seq(fun t_map_field/1, Es, ["}"]).
+
+t_map_field(E = #xmlElement{name = map_field, content = [K,V]}) ->
+    KElem = t_utype_elem(K),
+    VElem = t_utype_elem(V),
+    AS = case get_attrval(assoc_type, E) of
+             "assoc" -> " => ";
+             "exact" -> " := "
+         end,
+    [KElem ++ AS ++ VElem].
 
-t_map_field([K,V]) ->
-    [t_utype_elem(K) ++ " => " ++ t_utype_elem(V)].
+t_abstype(E, Es) ->
+    see_type(E, t_abstype(Es)).
 
 t_abstype(Es) ->
-    case split_at_colon(t_name(get_elem(erlangName, Es)),[]) of
-	{Mod,Type} -> 
-	    [Type, "("] ++ 
-		seq(fun t_utype_elem/1, get_elem(type, Es), [")"]) ++ 
-		[" (see module ", Mod, ")"];
-	Type ->
-	    [Type, "("] ++ 
-		seq(fun t_utype_elem/1, get_elem(type, Es), [")"])
+    Name = t_name(get_elem(erlangName, Es)),
+    [Name, "("] ++ seq(fun t_utype_elem/1, get_elem(type, Es), [")"]).
+
+see_type(E, Es0) ->
+    case get_attrval(href, E) of
+        [] -> Es0;
+        Href0 ->
+            try
+                false = is_local_type(Es0),
+                %% Fails for parametrized types:
+                Text = #xmlText{value = lists:append(Es0)},
+                {Href, Es} = otp_xmlify_a_href(Href0, [Text]),
+                [{seealso, [{marker, Href}], Es}]
+            catch
+                _:_ ->
+                    Es0
+            end
     end.
 
-%% Split at one colon, but not at two (or more)
-split_at_colon([$:,$:|_]=Rest,Acc) ->
-    lists:reverse(Acc)++Rest;
-split_at_colon([$:|Type],Acc) ->
-    {lists:reverse(Acc),Type};
-split_at_colon([Char|Rest],Acc) ->
-    split_at_colon(Rest,[Char|Acc]);
-split_at_colon([],Acc) ->
-    lists:reverse(Acc).
+is_local_type(Es) ->
+    try
+        [_] = ets:lookup(?LOCAL_TYPES, Es),
+        true
+    catch
+        _:_->
+            false
+    end.
 
 t_union(Es) ->
     seq(fun t_utype_elem/1, Es, " | ", []).
diff --git a/lib/syntax_tools/doc/specs/.gitignore b/lib/syntax_tools/doc/specs/.gitignore
new file mode 100644
index 0000000000..322eebcb06
--- /dev/null
+++ b/lib/syntax_tools/doc/specs/.gitignore
@@ -0,0 +1 @@
+specs_*.xml
diff --git a/lib/syntax_tools/doc/src/Makefile b/lib/syntax_tools/doc/src/Makefile
index ff4f3f78ff..e55222e59c 100644
--- a/lib/syntax_tools/doc/src/Makefile
+++ b/lib/syntax_tools/doc/src/Makefile
@@ -81,10 +81,15 @@ HTML_REF_MAN_FILE = $(HTMLDIR)/index.html
 
 TOP_PDF_FILE = $(PDFDIR)/$(APPLICATION)-$(VSN).pdf
 
+SPECS_FILES = $(XML_REF3_FILES:%.xml=$(SPECDIR)/specs_%.xml)
+
+TOP_SPECS_FILE = specs.xml
+
 # ----------------------------------------------------
 # FLAGS 
 # ----------------------------------------------------
 XML_FLAGS += 
+SPECS_FLAGS = -I../../include
 DVIPS_FLAGS += 
 
 # ----------------------------------------------------
@@ -93,7 +98,7 @@ DVIPS_FLAGS +=
 $(HTMLDIR)/%.gif: %.gif
 	$(INSTALL_DATA) $< $@
 
-docs: pdf html man
+docs: man pdf html
 
 $(TOP_PDF_FILE): $(XML_FILES)
 
@@ -120,6 +125,7 @@ clean clean_docs:
 	rm -f $(MAN3DIR)/*
 	rm -f $(XML_REF3_FILES) $(XML_CHAPTER_FILES) *.html
 	rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo)
+	rm -f $(SPECDIR)/*
 	rm -f errs core *~ 
 
 # ----------------------------------------------------
diff --git a/lib/syntax_tools/doc/src/specs.xml b/lib/syntax_tools/doc/src/specs.xml
new file mode 100644
index 0000000000..04c3a494e7
--- /dev/null
+++ b/lib/syntax_tools/doc/src/specs.xml
@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<specs xmlns:xi="http://www.w3.org/2001/XInclude">
+  <xi:include href="../specs/specs_epp_dodger.xml"/>
+  <xi:include href="../specs/specs_erl_comment_scan.xml"/>
+  <xi:include href="../specs/specs_erl_prettypr.xml"/>
+  <xi:include href="../specs/specs_erl_recomment.xml"/>
+  <xi:include href="../specs/specs_erl_syntax.xml"/>
+  <xi:include href="../specs/specs_erl_syntax_lib.xml"/>
+  <xi:include href="../specs/specs_erl_tidy.xml"/>
+  <xi:include href="../specs/specs_igor.xml"/>
+  <xi:include href="../specs/specs_merl.xml"/>
+  <xi:include href="../specs/specs_merl_transform.xml"/>
+  <xi:include href="../specs/specs_prettypr.xml"/>
+</specs>
diff --git a/lib/syntax_tools/src/erl_comment_scan.erl b/lib/syntax_tools/src/erl_comment_scan.erl
index 03429d4d42..b5ac564146 100644
--- a/lib/syntax_tools/src/erl_comment_scan.erl
+++ b/lib/syntax_tools/src/erl_comment_scan.erl
@@ -30,8 +30,14 @@
 
 %% =====================================================================
 
--type comment()     :: {integer(), integer(), integer(), [string()]}.
--type commentLine() :: {integer(), integer(), integer(), string()}.
+-type comment()     :: {Line:: integer(),
+                        Column:: integer(),
+                        Indentation :: integer(),
+                        Text :: [string()]}.
+-type commentLine() :: {Line :: integer(),
+                        Column :: integer(),
+                        Indent :: integer(),
+                        Text :: string()}.
 
 %% =====================================================================
 %% @spec file(FileName::file:filename()) -> [Comment]
diff --git a/lib/syntax_tools/src/erl_prettypr.erl b/lib/syntax_tools/src/erl_prettypr.erl
index f1615b2610..df0d78031c 100644
--- a/lib/syntax_tools/src/erl_prettypr.erl
+++ b/lib/syntax_tools/src/erl_prettypr.erl
@@ -195,10 +195,16 @@ format(Node) ->
 
 %% =====================================================================
 %% @spec format(Tree::syntaxTree(), Options::[term()]) -> string()
-%%           syntaxTree() = erl_syntax:syntaxTree()
 %%
-%% @type hook() = (syntaxTree(), context(), Continuation) -> document()
-%%	    Continuation = (syntaxTree(), context()) -> document().
+%% @type syntaxTree() = erl_syntax:syntaxTree().
+%%
+%% An abstract syntax tree. See the {@link erl_syntax} module for
+%% details.
+%%
+%% @type hook() = (syntaxTree(), context(), Continuation) ->
+%%                            prettypr:document()
+%%	    Continuation = (syntaxTree(), context()) ->
+%%                            prettypr:document().
 %%
 %% A call-back function for user-controlled formatting. See {@link
 %% format/2}.
@@ -277,7 +283,7 @@ format(Node, Options) ->
 
 
 %% =====================================================================
-%% @spec best(Tree::syntaxTree()) -> empty | document()
+%% @spec best(Tree::syntaxTree()) -> empty | prettypr:document()
 %% @equiv best(Tree, [])
 
 -spec best(erl_syntax:syntaxTree()) -> 'empty' | prettypr:document().
@@ -288,7 +294,7 @@ best(Node) ->
 
 %% =====================================================================
 %% @spec best(Tree::syntaxTree(), Options::[term()]) ->
-%%           empty | document()
+%%           empty | prettypr:document()
 %%
 %% @doc Creates a fixed "best" abstract layout for a syntax tree. This
 %% is similar to the `layout/2' function, except that here, the final
@@ -310,7 +316,7 @@ best(Node, Options) ->
 
 
 %% =====================================================================
-%% @spec layout(Tree::syntaxTree()) -> document()
+%% @spec layout(Tree::syntaxTree()) -> prettypr:document()
 %% @equiv layout(Tree, [])
 
 -spec layout(erl_syntax:syntaxTree()) -> prettypr:document().
@@ -320,8 +326,7 @@ layout(Node) ->
 
 
 %% =====================================================================
-%% @spec layout(Tree::syntaxTree(), Options::[term()]) -> document()
-%%	    document() = prettypr:document()
+%% @spec layout(Tree::syntaxTree(), Options::[term()]) -> prettypr:document()
 %%
 %% @doc Creates an abstract document layout for a syntax tree. The
 %% result represents a set of possible layouts (cf. module `prettypr').
diff --git a/lib/syntax_tools/src/erl_recomment.erl b/lib/syntax_tools/src/erl_recomment.erl
index c1141b2bc6..1d23034991 100644
--- a/lib/syntax_tools/src/erl_recomment.erl
+++ b/lib/syntax_tools/src/erl_recomment.erl
@@ -30,6 +30,9 @@
 -export([recomment_forms/2, quick_recomment_forms/2, recomment_tree/2]).
 
 
+%% @type syntaxTree() = erl_syntax:syntaxTree(). An abstract syntax
+%% tree. See the {@link erl_syntax} module for details.
+
 %% =====================================================================
 %% @spec quick_recomment_forms(Forms, Comments::[Comment]) ->
 %%           syntaxTree()
@@ -55,7 +58,6 @@ quick_recomment_forms(Tree, Cs) ->
 %% =====================================================================
 %% @spec recomment_forms(Forms, Comments::[Comment]) -> syntaxTree()
 %%
-%%	    syntaxTree() = erl_syntax:syntaxTree()
 %%	    Forms = syntaxTree() | [syntaxTree()]
 %%	    Comment = {Line, Column, Indentation, Text}
 %%	    Line = integer()
diff --git a/lib/syntax_tools/src/erl_syntax_lib.erl b/lib/syntax_tools/src/erl_syntax_lib.erl
index 9815559779..5aecf5d774 100644
--- a/lib/syntax_tools/src/erl_syntax_lib.erl
+++ b/lib/syntax_tools/src/erl_syntax_lib.erl
@@ -280,7 +280,7 @@ mapfoldl(_, S, []) ->
 %% =====================================================================
 %% @spec variables(syntaxTree()) -> set(atom())
 %%
-%%        set(T) = //stdlib/sets:set(T)
+%% @type set(T) = //stdlib/sets:set(T)
 %%
 %% @doc Returns the names of variables occurring in a syntax tree, The
 %% result is a set of variable names represented by atoms. Macro names
@@ -1955,7 +1955,7 @@ analyze_application(Node) ->
 
 
 %% =====================================================================
-%% @spec analyze_type_application(Node::syntaxTree()) -> typeName()
+%% @spec analyze_type_application(Node::syntaxTree()) -> TypeName
 %%
 %%          TypeName = {atom(), integer()}
 %%                   | {ModuleName, {atom(), integer()}}
diff --git a/lib/syntax_tools/src/erl_tidy.erl b/lib/syntax_tools/src/erl_tidy.erl
index 3a37ca43bd..5d3fc6f062 100644
--- a/lib/syntax_tools/src/erl_tidy.erl
+++ b/lib/syntax_tools/src/erl_tidy.erl
@@ -36,6 +36,11 @@
 %% been reasonably well tested, but the possibility of errors remains.
 %% Keep backups of your original code safely stored, until you feel
 %% confident that the new, modified code can be trusted.
+%%
+%% @type syntaxTree() = erl_syntax:syntaxTree(). An abstract syntax
+%% tree. See the {@link erl_syntax} module for details.
+%%
+%% @type filename() = file:filename().
 
 -module(erl_tidy).
 
@@ -79,7 +84,6 @@ dir(Dir) ->
 
 %% =====================================================================
 %% @spec dir(Directory::filename(), Options::[term()]) -> ok
-%%           filename() = file:filename()
 %%
 %% @doc Tidies Erlang source files in a directory and its
 %% subdirectories.
@@ -513,7 +517,6 @@ module(Forms) ->
 %% @spec module(Forms, Options::[term()]) -> syntaxTree()
 %%
 %%          Forms = syntaxTree() | [syntaxTree()]
-%%          syntaxTree() = erl_syntax:syntaxTree()
 %%
 %% @doc Tidies a syntax tree representation of a module
 %% definition. The given `Forms' may be either a single
diff --git a/lib/syntax_tools/src/igor.erl b/lib/syntax_tools/src/igor.erl
index 1d14bd7c3a..943250e5cd 100644
--- a/lib/syntax_tools/src/igor.erl
+++ b/lib/syntax_tools/src/igor.erl
@@ -151,7 +151,8 @@ default_printer(Tree, Options) ->
 %% @spec parse_transform(Forms::[syntaxTree()], Options::[term()]) ->
 %%           [syntaxTree()]
 %%
-%%         syntaxTree() = erl_syntax:syntaxTree()
+%% @type syntaxTree() = erl_syntax:syntaxTree(). An abstract syntax
+%% tree. See the {@link erl_syntax} module for details.
 %%
 %% @doc Allows Igor to work as a component of the Erlang compiler.
 %% Including the term `{parse_transform, igor}' in the
@@ -212,7 +213,7 @@ merge(Name, Files) ->
 %% @spec merge(Name::atom(), Files::[filename()], Options::[term()]) ->
 %%           [filename()]
 %%
-%%	    filename() = file:filename()
+%% @type filename() = file:filename()
 %%
 %% @doc Merges source code files to a single file. `Name'
 %% specifies the name of the resulting module - not the name of the
@@ -367,6 +368,7 @@ merge_files(Name, Files, Options) ->
 %% @spec merge_files(Name::atom(), Sources::[Forms],
 %%                   Files::[filename()], Options::[term()]) ->
 %%           {syntaxTree(), [stubDescriptor()]}
+%%
 %%     Forms = syntaxTree() | [syntaxTree()]
 %%
 %% @doc Merges source code files and syntax trees to a single syntax
diff --git a/lib/wx/doc/specs/.gitignore b/lib/wx/doc/specs/.gitignore
new file mode 100644
index 0000000000..322eebcb06
--- /dev/null
+++ b/lib/wx/doc/specs/.gitignore
@@ -0,0 +1 @@
+specs_*.xml
diff --git a/lib/wx/doc/src/Makefile b/lib/wx/doc/src/Makefile
index cae2f9fe4e..23890f47f0 100644
--- a/lib/wx/doc/src/Makefile
+++ b/lib/wx/doc/src/Makefile
@@ -63,10 +63,15 @@ HTML_REF_MAN_FILE = $(HTMLDIR)/index.html
 
 TOP_PDF_FILE = $(PDFDIR)/$(APPLICATION)-$(VSN).pdf
 
+SPECS_FILES = $(XML_REF3_FILES:%.xml=$(SPECDIR)/specs_%.xml)
+
+TOP_SPECS_FILE = specs.xml
+
 # ----------------------------------------------------
 # FLAGS
 # ----------------------------------------------------
 XML_FLAGS +=
+SPECS_FLAGS = -I../../include -I../../src
 DVIPS_FLAGS +=
 
 # ----------------------------------------------------
@@ -111,6 +116,7 @@ clean clean_docs:
 	rm -rf  $(HTMLDIR)/*
 	rm -f $(MAN3DIR)/*
 	rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo)
+	rm -f $(SPECDIR)/*
 	rm -f errs core *~ ../html/edoc-info
 	rm -f $(XML_REF3_FILES) $(XML_CHAPTER_FILES) *.html
 
diff --git a/lib/wx/doc/src/specs.xml b/lib/wx/doc/src/specs.xml
new file mode 100644
index 0000000000..2e19baafc4
--- /dev/null
+++ b/lib/wx/doc/src/specs.xml
@@ -0,0 +1,232 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<specs xmlns:xi="http://www.w3.org/2001/XInclude">
+  <xi:include href="../specs/specs_wx.xml"/>
+  <xi:include href="../specs/specs_wx_object.xml"/>
+  <xi:include href="../specs/specs_wxAcceleratorEntry.xml"/>
+  <xi:include href="../specs/specs_wxAcceleratorTable.xml"/>
+  <xi:include href="../specs/specs_wxActivateEvent.xml"/>
+  <xi:include href="../specs/specs_wxArtProvider.xml"/>
+  <xi:include href="../specs/specs_wxAuiDockArt.xml"/>
+  <xi:include href="../specs/specs_wxAuiManager.xml"/>
+  <xi:include href="../specs/specs_wxAuiManagerEvent.xml"/>
+  <xi:include href="../specs/specs_wxAuiNotebook.xml"/>
+  <xi:include href="../specs/specs_wxAuiNotebookEvent.xml"/>
+  <xi:include href="../specs/specs_wxAuiPaneInfo.xml"/>
+  <xi:include href="../specs/specs_wxAuiSimpleTabArt.xml"/>
+  <xi:include href="../specs/specs_wxAuiTabArt.xml"/>
+  <xi:include href="../specs/specs_wxBitmapButton.xml"/>
+  <xi:include href="../specs/specs_wxBitmapDataObject.xml"/>
+  <xi:include href="../specs/specs_wxBitmap.xml"/>
+  <xi:include href="../specs/specs_wxBoxSizer.xml"/>
+  <xi:include href="../specs/specs_wxBrush.xml"/>
+  <xi:include href="../specs/specs_wxBufferedDC.xml"/>
+  <xi:include href="../specs/specs_wxBufferedPaintDC.xml"/>
+  <xi:include href="../specs/specs_wxButton.xml"/>
+  <xi:include href="../specs/specs_wxCalendarCtrl.xml"/>
+  <xi:include href="../specs/specs_wxCalendarDateAttr.xml"/>
+  <xi:include href="../specs/specs_wxCalendarEvent.xml"/>
+  <xi:include href="../specs/specs_wxCaret.xml"/>
+  <xi:include href="../specs/specs_wxCheckBox.xml"/>
+  <xi:include href="../specs/specs_wxCheckListBox.xml"/>
+  <xi:include href="../specs/specs_wxChildFocusEvent.xml"/>
+  <xi:include href="../specs/specs_wxChoicebook.xml"/>
+  <xi:include href="../specs/specs_wxChoice.xml"/>
+  <xi:include href="../specs/specs_wxClientDC.xml"/>
+  <xi:include href="../specs/specs_wxClipboard.xml"/>
+  <xi:include href="../specs/specs_wxClipboardTextEvent.xml"/>
+  <xi:include href="../specs/specs_wxCloseEvent.xml"/>
+  <xi:include href="../specs/specs_wxColourData.xml"/>
+  <xi:include href="../specs/specs_wxColourDialog.xml"/>
+  <xi:include href="../specs/specs_wxColourPickerCtrl.xml"/>
+  <xi:include href="../specs/specs_wxColourPickerEvent.xml"/>
+  <xi:include href="../specs/specs_wxComboBox.xml"/>
+  <xi:include href="../specs/specs_wxCommandEvent.xml"/>
+  <xi:include href="../specs/specs_wxContextMenuEvent.xml"/>
+  <xi:include href="../specs/specs_wxControl.xml"/>
+  <xi:include href="../specs/specs_wxControlWithItems.xml"/>
+  <xi:include href="../specs/specs_wxCursor.xml"/>
+  <xi:include href="../specs/specs_wxDataObject.xml"/>
+  <xi:include href="../specs/specs_wxDateEvent.xml"/>
+  <xi:include href="../specs/specs_wxDatePickerCtrl.xml"/>
+  <xi:include href="../specs/specs_wxDC.xml"/>
+  <xi:include href="../specs/specs_wxDCOverlay.xml"/>
+  <xi:include href="../specs/specs_wxDialog.xml"/>
+  <xi:include href="../specs/specs_wxDirDialog.xml"/>
+  <xi:include href="../specs/specs_wxDirPickerCtrl.xml"/>
+  <xi:include href="../specs/specs_wxDisplayChangedEvent.xml"/>
+  <xi:include href="../specs/specs_wxEraseEvent.xml"/>
+  <xi:include href="../specs/specs_wxEvent.xml"/>
+  <xi:include href="../specs/specs_wxEvtHandler.xml"/>
+  <xi:include href="../specs/specs_wxFileDataObject.xml"/>
+  <xi:include href="../specs/specs_wxFileDialog.xml"/>
+  <xi:include href="../specs/specs_wxFileDirPickerEvent.xml"/>
+  <xi:include href="../specs/specs_wxFilePickerCtrl.xml"/>
+  <xi:include href="../specs/specs_wxFindReplaceData.xml"/>
+  <xi:include href="../specs/specs_wxFindReplaceDialog.xml"/>
+  <xi:include href="../specs/specs_wxFlexGridSizer.xml"/>
+  <xi:include href="../specs/specs_wxFocusEvent.xml"/>
+  <xi:include href="../specs/specs_wxFontData.xml"/>
+  <xi:include href="../specs/specs_wxFontDialog.xml"/>
+  <xi:include href="../specs/specs_wxFont.xml"/>
+  <xi:include href="../specs/specs_wxFontPickerCtrl.xml"/>
+  <xi:include href="../specs/specs_wxFontPickerEvent.xml"/>
+  <xi:include href="../specs/specs_wxFrame.xml"/>
+  <xi:include href="../specs/specs_wxGauge.xml"/>
+  <xi:include href="../specs/specs_wxGBSizerItem.xml"/>
+  <xi:include href="../specs/specs_wxGenericDirCtrl.xml"/>
+  <xi:include href="../specs/specs_wxGLCanvas.xml"/>
+  <xi:include href="../specs/specs_wxGraphicsBrush.xml"/>
+  <xi:include href="../specs/specs_wxGraphicsContext.xml"/>
+  <xi:include href="../specs/specs_wxGraphicsFont.xml"/>
+  <xi:include href="../specs/specs_wxGraphicsMatrix.xml"/>
+  <xi:include href="../specs/specs_wxGraphicsObject.xml"/>
+  <xi:include href="../specs/specs_wxGraphicsPath.xml"/>
+  <xi:include href="../specs/specs_wxGraphicsPen.xml"/>
+  <xi:include href="../specs/specs_wxGraphicsRenderer.xml"/>
+  <xi:include href="../specs/specs_wxGridBagSizer.xml"/>
+  <xi:include href="../specs/specs_wxGridCellAttr.xml"/>
+  <xi:include href="../specs/specs_wxGridCellBoolEditor.xml"/>
+  <xi:include href="../specs/specs_wxGridCellBoolRenderer.xml"/>
+  <xi:include href="../specs/specs_wxGridCellChoiceEditor.xml"/>
+  <xi:include href="../specs/specs_wxGridCellEditor.xml"/>
+  <xi:include href="../specs/specs_wxGridCellFloatEditor.xml"/>
+  <xi:include href="../specs/specs_wxGridCellFloatRenderer.xml"/>
+  <xi:include href="../specs/specs_wxGridCellNumberEditor.xml"/>
+  <xi:include href="../specs/specs_wxGridCellNumberRenderer.xml"/>
+  <xi:include href="../specs/specs_wxGridCellRenderer.xml"/>
+  <xi:include href="../specs/specs_wxGridCellStringRenderer.xml"/>
+  <xi:include href="../specs/specs_wxGridCellTextEditor.xml"/>
+  <xi:include href="../specs/specs_wxGrid.xml"/>
+  <xi:include href="../specs/specs_wxGridEvent.xml"/>
+  <xi:include href="../specs/specs_wxGridSizer.xml"/>
+  <xi:include href="../specs/specs_wxHelpEvent.xml"/>
+  <xi:include href="../specs/specs_wxHtmlEasyPrinting.xml"/>
+  <xi:include href="../specs/specs_wxHtmlLinkEvent.xml"/>
+  <xi:include href="../specs/specs_wxHtmlWindow.xml"/>
+  <xi:include href="../specs/specs_wxIconBundle.xml"/>
+  <xi:include href="../specs/specs_wxIcon.xml"/>
+  <xi:include href="../specs/specs_wxIconizeEvent.xml"/>
+  <xi:include href="../specs/specs_wxIdleEvent.xml"/>
+  <xi:include href="../specs/specs_wxImage.xml"/>
+  <xi:include href="../specs/specs_wxImageList.xml"/>
+  <xi:include href="../specs/specs_wxInitDialogEvent.xml"/>
+  <xi:include href="../specs/specs_wxJoystickEvent.xml"/>
+  <xi:include href="../specs/specs_wxKeyEvent.xml"/>
+  <xi:include href="../specs/specs_wxLayoutAlgorithm.xml"/>
+  <xi:include href="../specs/specs_wxListbook.xml"/>
+  <xi:include href="../specs/specs_wxListBox.xml"/>
+  <xi:include href="../specs/specs_wxListCtrl.xml"/>
+  <xi:include href="../specs/specs_wxListEvent.xml"/>
+  <xi:include href="../specs/specs_wxListItemAttr.xml"/>
+  <xi:include href="../specs/specs_wxListItem.xml"/>
+  <xi:include href="../specs/specs_wxListView.xml"/>
+  <xi:include href="../specs/specs_wxLocale.xml"/>
+  <xi:include href="../specs/specs_wxLogNull.xml"/>
+  <xi:include href="../specs/specs_wxMask.xml"/>
+  <xi:include href="../specs/specs_wxMaximizeEvent.xml"/>
+  <xi:include href="../specs/specs_wxMDIChildFrame.xml"/>
+  <xi:include href="../specs/specs_wxMDIClientWindow.xml"/>
+  <xi:include href="../specs/specs_wxMDIParentFrame.xml"/>
+  <xi:include href="../specs/specs_wxMemoryDC.xml"/>
+  <xi:include href="../specs/specs_wxMenuBar.xml"/>
+  <xi:include href="../specs/specs_wxMenu.xml"/>
+  <xi:include href="../specs/specs_wxMenuEvent.xml"/>
+  <xi:include href="../specs/specs_wxMenuItem.xml"/>
+  <xi:include href="../specs/specs_wxMessageDialog.xml"/>
+  <xi:include href="../specs/specs_wxMiniFrame.xml"/>
+  <xi:include href="../specs/specs_wxMirrorDC.xml"/>
+  <xi:include href="../specs/specs_wxMouseCaptureChangedEvent.xml"/>
+  <xi:include href="../specs/specs_wxMouseCaptureLostEvent.xml"/>
+  <xi:include href="../specs/specs_wxMouseEvent.xml"/>
+  <xi:include href="../specs/specs_wxMoveEvent.xml"/>
+  <xi:include href="../specs/specs_wxMultiChoiceDialog.xml"/>
+  <xi:include href="../specs/specs_wxNavigationKeyEvent.xml"/>
+  <xi:include href="../specs/specs_wxNotebook.xml"/>
+  <xi:include href="../specs/specs_wxNotebookEvent.xml"/>
+  <xi:include href="../specs/specs_wxNotifyEvent.xml"/>
+  <xi:include href="../specs/specs_wxOverlay.xml"/>
+  <xi:include href="../specs/specs_wxPageSetupDialogData.xml"/>
+  <xi:include href="../specs/specs_wxPageSetupDialog.xml"/>
+  <xi:include href="../specs/specs_wxPaintDC.xml"/>
+  <xi:include href="../specs/specs_wxPaintEvent.xml"/>
+  <xi:include href="../specs/specs_wxPaletteChangedEvent.xml"/>
+  <xi:include href="../specs/specs_wxPalette.xml"/>
+  <xi:include href="../specs/specs_wxPanel.xml"/>
+  <xi:include href="../specs/specs_wxPasswordEntryDialog.xml"/>
+  <xi:include href="../specs/specs_wxPen.xml"/>
+  <xi:include href="../specs/specs_wxPickerBase.xml"/>
+  <xi:include href="../specs/specs_wxPopupTransientWindow.xml"/>
+  <xi:include href="../specs/specs_wxPopupWindow.xml"/>
+  <xi:include href="../specs/specs_wxPostScriptDC.xml"/>
+  <xi:include href="../specs/specs_wxPreviewCanvas.xml"/>
+  <xi:include href="../specs/specs_wxPreviewControlBar.xml"/>
+  <xi:include href="../specs/specs_wxPreviewFrame.xml"/>
+  <xi:include href="../specs/specs_wxPrintData.xml"/>
+  <xi:include href="../specs/specs_wxPrintDialogData.xml"/>
+  <xi:include href="../specs/specs_wxPrintDialog.xml"/>
+  <xi:include href="../specs/specs_wxPrinter.xml"/>
+  <xi:include href="../specs/specs_wxPrintout.xml"/>
+  <xi:include href="../specs/specs_wxPrintPreview.xml"/>
+  <xi:include href="../specs/specs_wxProgressDialog.xml"/>
+  <xi:include href="../specs/specs_wxQueryNewPaletteEvent.xml"/>
+  <xi:include href="../specs/specs_wxRadioBox.xml"/>
+  <xi:include href="../specs/specs_wxRadioButton.xml"/>
+  <xi:include href="../specs/specs_wxRegion.xml"/>
+  <xi:include href="../specs/specs_wxSashEvent.xml"/>
+  <xi:include href="../specs/specs_wxSashLayoutWindow.xml"/>
+  <xi:include href="../specs/specs_wxSashWindow.xml"/>
+  <xi:include href="../specs/specs_wxScreenDC.xml"/>
+  <xi:include href="../specs/specs_wxScrollBar.xml"/>
+  <xi:include href="../specs/specs_wxScrolledWindow.xml"/>
+  <xi:include href="../specs/specs_wxScrollEvent.xml"/>
+  <xi:include href="../specs/specs_wxScrollWinEvent.xml"/>
+  <xi:include href="../specs/specs_wxSetCursorEvent.xml"/>
+  <xi:include href="../specs/specs_wxShowEvent.xml"/>
+  <xi:include href="../specs/specs_wxSingleChoiceDialog.xml"/>
+  <xi:include href="../specs/specs_wxSizeEvent.xml"/>
+  <xi:include href="../specs/specs_wxSizer.xml"/>
+  <xi:include href="../specs/specs_wxSizerFlags.xml"/>
+  <xi:include href="../specs/specs_wxSizerItem.xml"/>
+  <xi:include href="../specs/specs_wxSlider.xml"/>
+  <xi:include href="../specs/specs_wxSpinButton.xml"/>
+  <xi:include href="../specs/specs_wxSpinCtrl.xml"/>
+  <xi:include href="../specs/specs_wxSpinEvent.xml"/>
+  <xi:include href="../specs/specs_wxSplashScreen.xml"/>
+  <xi:include href="../specs/specs_wxSplitterEvent.xml"/>
+  <xi:include href="../specs/specs_wxSplitterWindow.xml"/>
+  <xi:include href="../specs/specs_wxStaticBitmap.xml"/>
+  <xi:include href="../specs/specs_wxStaticBox.xml"/>
+  <xi:include href="../specs/specs_wxStaticBoxSizer.xml"/>
+  <xi:include href="../specs/specs_wxStaticLine.xml"/>
+  <xi:include href="../specs/specs_wxStaticText.xml"/>
+  <xi:include href="../specs/specs_wxStatusBar.xml"/>
+  <xi:include href="../specs/specs_wxStdDialogButtonSizer.xml"/>
+  <xi:include href="../specs/specs_wxStyledTextCtrl.xml"/>
+  <xi:include href="../specs/specs_wxStyledTextEvent.xml"/>
+  <xi:include href="../specs/specs_wxSysColourChangedEvent.xml"/>
+  <xi:include href="../specs/specs_wxSystemOptions.xml"/>
+  <xi:include href="../specs/specs_wxSystemSettings.xml"/>
+  <xi:include href="../specs/specs_wxTaskBarIcon.xml"/>
+  <xi:include href="../specs/specs_wxTaskBarIconEvent.xml"/>
+  <xi:include href="../specs/specs_wxTextAttr.xml"/>
+  <xi:include href="../specs/specs_wxTextCtrl.xml"/>
+  <xi:include href="../specs/specs_wxTextDataObject.xml"/>
+  <xi:include href="../specs/specs_wxTextEntryDialog.xml"/>
+  <xi:include href="../specs/specs_wxToggleButton.xml"/>
+  <xi:include href="../specs/specs_wxToolBar.xml"/>
+  <xi:include href="../specs/specs_wxToolbook.xml"/>
+  <xi:include href="../specs/specs_wxToolTip.xml"/>
+  <xi:include href="../specs/specs_wxTopLevelWindow.xml"/>
+  <xi:include href="../specs/specs_wxTreebook.xml"/>
+  <xi:include href="../specs/specs_wxTreeCtrl.xml"/>
+  <xi:include href="../specs/specs_wxTreeEvent.xml"/>
+  <xi:include href="../specs/specs_wxUpdateUIEvent.xml"/>
+  <xi:include href="../specs/specs_wxWindowCreateEvent.xml"/>
+  <xi:include href="../specs/specs_wxWindowDC.xml"/>
+  <xi:include href="../specs/specs_wxWindowDestroyEvent.xml"/>
+  <xi:include href="../specs/specs_wxWindow.xml"/>
+  <xi:include href="../specs/specs_wxXmlResource.xml"/>
+  <xi:include href="../specs/specs_wx_misc.xml"/>
+  <xi:include href="../specs/specs_glu.xml"/>
+  <xi:include href="../specs/specs_gl.xml"/>
+</specs>