aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
Diffstat
-rw-r--r--lib/edoc/doc/overview.edoc103
-rw-r--r--lib/edoc/doc/src/Makefile2
-rw-r--r--lib/edoc/doc/src/ref_man.xml2
-rw-r--r--lib/edoc/src/Makefile3
-rw-r--r--lib/edoc/src/edoc.app.src1
-rw-r--r--lib/edoc/src/edoc.erl34
-rw-r--r--lib/edoc/src/edoc.hrl11
-rw-r--r--lib/edoc/src/edoc_data.erl16
-rw-r--r--lib/edoc/src/edoc_doclet.erl4
-rw-r--r--lib/edoc/src/edoc_extract.erl154
-rw-r--r--lib/edoc/src/edoc_layout.erl395
-rw-r--r--lib/edoc/src/edoc_lib.erl1
-rw-r--r--lib/edoc/src/edoc_parser.yrl106
-rw-r--r--lib/edoc/src/edoc_refs.erl2
-rw-r--r--lib/edoc/src/edoc_scanner.erl22
-rw-r--r--lib/edoc/src/edoc_specs.erl603
-rw-r--r--lib/edoc/src/edoc_tags.erl133
-rw-r--r--lib/edoc/src/edoc_types.erl107
-rw-r--r--lib/edoc/src/edoc_types.hrl45
19 files changed, 1540 insertions, 204 deletions
diff --git a/lib/edoc/doc/overview.edoc b/lib/edoc/doc/overview.edoc
index 9b25c17b1f..bd603b7a13 100644
--- a/lib/edoc/doc/overview.edoc
+++ b/lib/edoc/doc/overview.edoc
@@ -205,8 +205,12 @@ The following tags can be used anywhere within a module:
the text. See {@section Type specifications} for syntax and
examples.
All data type descriptions are placed in a separate section of
- the documentation, regardless of where the tags occur.</dd>
+ the documentation, regardless of where the tags occur.
+ Instead of specifying the complete type alias in an EDoc
+ documentation comment, type definitions from the actual
+ Erlang code can be re-used for documentation.
+ See {@section Type specifications} for examples.</dd>
</dl>
@@ -405,7 +409,12 @@ The following tags can be used before a function definition:
included in the specification, it must match the name in the
actual code. When parameter names are not given in the
specification, suitable names will be taken from the source
- code if possible, and otherwise synthesized.</dd>
+ code if possible, and otherwise synthesized.
+
+ Instead of specifying the complete function type in an EDoc
+ documentation comment, specifications from the actual
+ Erlang code can be re-used for documentation.
+ See {@section Type specifications} for examples.</dd>
<dt><a name="ftag-throws">`@throws'</a></dt>
<dd>Specifies which types of terms may be thrown by the
@@ -763,6 +772,17 @@ following escape sequences may be used: <dl>
=== Function specifications ===
+<note>Although the syntax described in the following can still be used
+for specifying functions we recommend that Erlang specifications as
+described in <seealso marker="doc/reference_manual:typespec"> Types
+and Function Specification</seealso> should be added to the source
+code instead. This way the analyses of <seealso
+marker="dialyzer:dialyzer">Dialyzer</seealso>'s can be utilized in the
+process of keeping the documentation consistent and up-to-date.
+Erlang specifications will be used unless there is also a function
+specification (a `@spec' tag followed by a type) with the same name.
+</note>
+
The following grammar describes the form of the specifications following
a `@spec' tag. A '`?'' suffix implies that the element is optional.
Function types have higher precedence than union types; e.g., "`(atom())
@@ -818,16 +838,51 @@ not as `(atom()) -> (atom() | integer())'.
<br/>| Atom
<br/>| Integer
<br/>| Float
+ <br/>| Integer ".." Integer
<br/>| FunType
+ <br/>| "fun(" FunType ")"
+ <br/>| "fun(...)"
<br/>| "{" UnionTypes? "}"
+ <br/>| "#" Atom "{" Fields? "}"
<br/>| "[" "]"
<br/>| "[" UnionType "]"
+ <br/>| "[" UnionType "," "..." "]"
<br/>| "(" UnionType ")"
+ <br/>| BinType
<br/>| TypeName "(" UnionTypes? ")"
<br/>| ModuleName ":" TypeName "(" UnionTypes? ")"
<br/>| "//" AppName "/" ModuleName ":" TypeName "(" UnionTypes? ")"</code></td>
</tr>
<tr>
+ <td><code>Fields</code></td>
+ <td>::=</td>
+ <td><code>Field
+ <br/>| Fields "," Fields</code></td>
+ </tr>
+ <tr>
+ <td><code>Field</code></td>
+ <td>::=</td>
+ <td><code>Atom "=" UnionList</code></td>
+ </tr>
+ <tr>
+ <td><code>BinType</code></td>
+ <td>::=</td>
+ <td><code>"&lt;&lt;&gt;&gt;"
+ <br/>| "&lt;&lt;" BaseType "&gt;&gt;"
+ <br/>| "&lt;&lt;" UnitType "&gt;&gt;"
+ <br/>| "&lt;&lt;" BaseType "," UnitType "&gt;&gt;"</code></td>
+ </tr>
+ <tr>
+ <td><code>BaseType</code></td>
+ <td>::=</td>
+ <td><code>"_" ":" Integer</code></td>
+ </tr>
+ <tr>
+ <td><code>UnitType</code></td>
+ <td>::=</td>
+ <td><code>"_" ":" "_" "*" Integer</code></td>
+ </tr>
+ <tr>
<td><code>TypeVariable</code></td>
<td>::=</td>
<td><code>Variable</code></td>
@@ -858,7 +913,7 @@ not as `(atom()) -> (atom() | integer())'.
<tr>
<td><code>Def</code></td>
<td>::=</td>
- <td><code>TypeVariable "=" UnionType
+ <td><code>TypeVariable "=" UnionList
<br/>| TypeName "(" TypeVariables? ")" "=" UnionType</code></td>
</tr>
<tr>
@@ -873,6 +928,9 @@ not as `(atom()) -> (atom() | integer())'.
Examples:
```
+ -spec my_function(X :: integer()) -> integer().
+ %% @doc Creates ...'''
+```
%% @spec my_function(X::integer()) -> integer()'''
```
%% @spec (X::integer()) -> integer()'''
@@ -895,6 +953,8 @@ Examples:
```
%% @spec close(graphics:window()) -> ok'''
+The first example shows the recommended way of specifying functions.
+
In the above examples, `X', `A', `B',
and `File' are parameter names, used for referring to the
parameters from the documentation text. The <em>type variables</em>
@@ -930,6 +990,13 @@ contain any annotations at all.
=== Type definitions ===
+<note>Although the syntax described in the following can still be used
+for specifying types we recommend that Erlang types as described in
+<seealso marker="doc/reference_manual:typespec"> Types and Function
+Specification</seealso> should be added to the source code instead.
+Erlang types will be used unless there is a type alias with the same
+name.</note>
+
The following grammar (see above for auxiliary definitions) describes
the form of the definitions that may follow a `@type' tag:
@@ -939,7 +1006,7 @@ the form of the definitions that may follow a `@type' tag:
<td><code>Typedef</code></td>
<td>::=</td>
<td><code>TypeName "(" TypeVariables? ")" DefList?
- <br/>| TypeName "(" TypeVariables? ")" "=" UnionType DefList?</code></td>
+ <br/>| TypeName "(" TypeVariables? ")" "=" UnionList DefList?</code></td>
</tr>
</tbody>
</table>
@@ -947,6 +1014,11 @@ the form of the definitions that may follow a `@type' tag:
(For a truly abstract data type, no equivalence is specified.) The main
definition may be followed by additional local definitions. Examples:
```
+ -type my_list(X) :: [X]. %% A special kind of lists ...'''
+```
+ -opaque another_list(X) :: [X].
+ %% another_list() is a kind of list...'''
+```
%% @type myList(X). A special kind of lists ...'''
```
%% @type filename() = string(). Atoms not allowed!'''
@@ -955,6 +1027,7 @@ definition may be followed by additional local definitions. Examples:
%% A = term().
%% A kind of wrapper type thingy.'''
+The first two examples show the recommended way of specifying types.
=== Pre-defined data types ===
@@ -962,24 +1035,42 @@ The following data types are predefined by EDoc, and may not be
redefined:
```
any()
+ arity()
atom()
binary()
- bool()
+ bitstring()
+ bool() (allowed, but use boolean() instead)
+ boolean()
+ byte()
char()
cons()
deep_string()
float()
function()
integer()
+ iodata()
+ iolist()
list()
+ maybe_improper_list()
+ mfa()
+ module()
nil()
+ neg_integer()
+ node()
+ non_neg_integer()
+ nonempty_improper_list()
+ nonempty_list()
+ nonempty_maybe_improper_list()
+ nonempty_string()
none()
number()
pid()
port()
+ pos_integer()
reference()
string()
term()
+ timeout()
tuple()
'''
Details:
@@ -991,7 +1082,7 @@ Details:
`integer()', `pid()', `port()'
and `reference()' are primitive data types of
the Erlang programming language.</li>
- <li>`bool()' is the subset of `atom()' consisting
+ <li>`boolean()' is the subset of `atom()' consisting
of the atoms `true' and `false'.</li>
<li>`char()' is a subset of
`integer()' representing character codes.</li>
diff --git a/lib/edoc/doc/src/Makefile b/lib/edoc/doc/src/Makefile
index 748691d173..5ee0096f0f 100644
--- a/lib/edoc/doc/src/Makefile
+++ b/lib/edoc/doc/src/Makefile
@@ -105,7 +105,7 @@ man: $(MAN3_FILES)
$(XML_REF3_FILES):
escript $(DOCGEN)/priv/bin/xml_from_edoc.escript -def vsn $(EDOC_VSN) -i $(ERL_TOP)/lib/edoc/include $(SRC_DIR)/$(@:%.xml=%.erl)
-$(XML_CHAPTER_FILES):
+$(XML_CHAPTER_FILES): ../overview.edoc
escript $(DOCGEN)/priv/bin/xml_from_edoc.escript -def vsn $(EDOC_VSN) -chapter ../overview.edoc
gifs: $(GIF_FILES:%=$(HTMLDIR)/%)
diff --git a/lib/edoc/doc/src/ref_man.xml b/lib/edoc/doc/src/ref_man.xml
index 619fbaa7ca..a9af8740b9 100644
--- a/lib/edoc/doc/src/ref_man.xml
+++ b/lib/edoc/doc/src/ref_man.xml
@@ -4,7 +4,7 @@
<application xmlns:xi="http://www.w3.org/2001/XInclude">
<header>
<copyright>
- <year>2006</year><year>2009</year>
+ <year>2006</year><year>2011</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
diff --git a/lib/edoc/src/Makefile b/lib/edoc/src/Makefile
index ca95c4cdad..9c5a9d30d1 100644
--- a/lib/edoc/src/Makefile
+++ b/lib/edoc/src/Makefile
@@ -29,7 +29,8 @@ SOURCES= \
edoc.erl edoc_data.erl edoc_doclet.erl edoc_extract.erl \
edoc_layout.erl edoc_lib.erl edoc_macros.erl edoc_parser.erl \
edoc_refs.erl edoc_report.erl edoc_run.erl edoc_scanner.erl \
- edoc_tags.erl edoc_types.erl edoc_wiki.erl otpsgml_layout.erl
+ edoc_specs.erl edoc_tags.erl edoc_types.erl edoc_wiki.erl \
+ otpsgml_layout.erl
OBJECTS=$(SOURCES:%.erl=$(EBIN)/%.$(EMULATOR)) $(APP_TARGET) $(APPUP_TARGET)
diff --git a/lib/edoc/src/edoc.app.src b/lib/edoc/src/edoc.app.src
index 2177533441..0c8d5b85f8 100644
--- a/lib/edoc/src/edoc.app.src
+++ b/lib/edoc/src/edoc.app.src
@@ -15,6 +15,7 @@
edoc_report,
edoc_run,
edoc_scanner,
+ edoc_specs,
edoc_tags,
edoc_types,
edoc_wiki,
diff --git a/lib/edoc/src/edoc.erl b/lib/edoc/src/edoc.erl
index 75b3bb451a..360f2dbc9e 100644
--- a/lib/edoc/src/edoc.erl
+++ b/lib/edoc/src/edoc.erl
@@ -258,6 +258,7 @@ opt_defaults() ->
opt_negations() ->
[{no_preprocess, preprocess},
{no_subpackages, subpackages},
+ {no_report_missing_types, report_missing_types},
{no_packages, packages}].
%% @spec run(Packages::[package()],
@@ -310,13 +311,13 @@ opt_negations() ->
%% <dd>Specifies the suffix used for output files. The default value is
%% `".html"'. Note that this also affects generated references.
%% </dd>
-%% <dt>{@type {new, bool()@}}
+%% <dt>{@type {new, boolean()@}}
%% </dt>
%% <dd>If the value is `true', any existing `edoc-info' file in the
%% target directory will be ignored and overwritten. The default
%% value is `false'.
%% </dd>
-%% <dt>{@type {packages, bool()@}}
+%% <dt>{@type {packages, boolean()@}}
%% </dt>
%% <dd>If the value is `true', it it assumed that packages (module
%% namespaces) are being used, and that the source code directory
@@ -342,7 +343,7 @@ opt_negations() ->
%% <dd>Specifies the expected suffix of input files. The default
%% value is `".erl"'.
%% </dd>
-%% <dt>{@type {subpackages, bool()@}}
+%% <dt>{@type {subpackages, boolean()@}}
%% </dt>
%% <dd>If the value is `true', all subpackages of specified packages
%% will also be included in the documentation. The default value is
@@ -578,6 +579,12 @@ layout(Doc, Opts) ->
%% @spec (File) -> [comment()]
+%% @type comment() = {Line, Column, Indentation, Text}
+%% where
+%% Line = integer(),
+%% Column = integer(),
+%% Indentation = integer(),
+%% Text = [string()]
%% @equiv read_comments(File, [])
read_comments(File) ->
@@ -585,12 +592,6 @@ read_comments(File) ->
%% @spec read_comments(File::filename(), Options::proplist()) ->
%% [comment()]
-%% where
-%% comment() = {Line, Column, Indentation, Text},
-%% Line = integer(),
-%% Column = integer(),
-%% Indentation = integer(),
-%% Text = [string()]
%%
%% @doc Extracts comments from an Erlang source code file. See the
%% module {@link //syntax_tools/erl_comment_scan} for details on the
@@ -616,7 +617,7 @@ read_source(Name) ->
%%
%% Options:
%% <dl>
-%% <dt>{@type {preprocess, bool()@}}
+%% <dt>{@type {preprocess, boolean()@}}
%% </dt>
%% <dd>If the value is `true', the source file will be read via the
%% Erlang preprocessor (`epp'). The default value is `false'.
@@ -642,6 +643,13 @@ read_source(Name) ->
%% macro definitions, used if the `preprocess' option is turned on.
%% The default value is the empty list.</dd>
%% </dl>
+%% <dt>{@type {report_missing_types, boolean()@}}
+%% </dt>
+%% <dd>If the value is `true', warnings are issued for missing types.
+%% The default value is `false'.
+%% `no_report_missing_types' is an alias for
+%% `{report_missing_types, false}'.
+%% </dd>
%%
%% @see get_doc/2
%% @see //syntax_tools/erl_syntax
@@ -724,17 +732,17 @@ get_doc(File) ->
%% <a href="overview-summary.html#Macro_expansion">Inline macro expansion</a>
%% for details.
%% </dd>
-%% <dt>{@type {hidden, bool()@}}
+%% <dt>{@type {hidden, boolean()@}}
%% </dt>
%% <dd>If the value is `true', documentation of hidden functions will
%% also be included. The default value is `false'.
%% </dd>
-%% <dt>{@type {private, bool()@}}
+%% <dt>{@type {private, boolean()@}}
%% </dt>
%% <dd>If the value is `true', documentation of private functions will
%% also be included. The default value is `false'.
%% </dd>
-%% <dt>{@type {todo, bool()@}}
+%% <dt>{@type {todo, boolean()@}}
%% </dt>
%% <dd>If the value is `true', To-Do notes written using `@todo' or
%% `@TODO' tags will be included in the documentation. The default
diff --git a/lib/edoc/src/edoc.hrl b/lib/edoc/src/edoc.hrl
index 71cc1a52b9..43657b3b8f 100644
--- a/lib/edoc/src/edoc.hrl
+++ b/lib/edoc/src/edoc.hrl
@@ -37,6 +37,7 @@
-define(SOURCE_DIR, "src").
-define(EBIN_DIR, "ebin").
-define(EDOC_DIR, "doc").
+-define(REPORT_MISSING_TYPE, false).
-include("edoc_doclet.hrl").
@@ -83,10 +84,11 @@
%% Module Entries (one per function, plus module header and footer)
-%% @type entry() = #entry{name = atom(),
-%% args = [string()],
+%% @type entry() = #entry{{atom(), integer()} % function
+%% | name = atom(), % other
+%% args = [atom()],
%% line = integer(),
-%% export = bool(),
+%% export = boolean(),
%% data = term()}
-record(entry, {name, args = [], line = 0, export, data}).
@@ -95,6 +97,7 @@
%% @type tag() = #tag{name = atom(),
%% line = integer(),
+%% origin = comment | code,
%% data = term()}
--record(tag, {name, line = 0, data}).
+-record(tag, {name, line = 0, origin = comment, data}).
diff --git a/lib/edoc/src/edoc_data.erl b/lib/edoc/src/edoc_data.erl
index 124f8eb9a1..27f43dca5a 100644
--- a/lib/edoc/src/edoc_data.erl
+++ b/lib/edoc/src/edoc_data.erl
@@ -20,7 +20,7 @@
%% @copyright 2003 Richard Carlsson
%% @author Richard Carlsson <[email protected]>
%% @see edoc
-%% @end
+%% @end
%% =====================================================================
%% @doc Building the EDoc external data structure. See the file
@@ -30,9 +30,10 @@
-export([module/4, package/4, overview/4, type/2]).
+-export([hidden_filter/2, get_all_tags/1]).
+
-include("edoc.hrl").
-%% TODO: report multiple definitions of the same type in the same module.
%% TODO: check that variables in @equiv are found in the signature
%% TODO: copy types from target (if missing) when using @equiv
@@ -139,6 +140,15 @@ functions(Es, Env, Opts) ->
|| #entry{name = {_,_}=N, args = As, export = Export, data = Ts}
<- Es].
+hidden_filter(Es, Opts) ->
+ Private = proplists:get_bool(private, Opts),
+ Hidden = proplists:get_bool(hidden, Opts),
+ [E || E <- Es,
+ case E#entry.name of
+ {_, _} -> function_filter(E, Private, Hidden);
+ _ -> true
+ end].
+
function_filter(Es, Opts) ->
Private = proplists:get_bool(private, Opts),
Hidden = proplists:get_bool(hidden, Opts),
@@ -298,7 +308,7 @@ get_deprecated(Ts, F, A, Env) ->
case otp_internal:obsolete(M, F, A) of
{Tag, Text} when Tag =:= deprecated; Tag =:= removed ->
deprecated([Text]);
- {Tag, Repl, _Rel} when Tag =:= deprecated; Tag =:= removed ->
+ {Tag, Repl, _Rel} when Tag =:= deprecated; Tag =:= removed ->
deprecated(Repl, Env);
_ ->
[]
diff --git a/lib/edoc/src/edoc_doclet.erl b/lib/edoc/src/edoc_doclet.erl
index f1d876d593..30eef3e63a 100644
--- a/lib/edoc/src/edoc_doclet.erl
+++ b/lib/edoc/src/edoc_doclet.erl
@@ -76,7 +76,7 @@
%% <dd>Specifies the suffix used for output files. The default value is
%% `".html"'.
%% </dd>
-%% <dt>{@type {hidden, bool()@}}
+%% <dt>{@type {hidden, boolean()@}}
%% </dt>
%% <dd>If the value is `true', documentation of hidden modules and
%% functions will also be included. The default value is `false'.
@@ -86,7 +86,7 @@
%% <dd>Specifies the name of the overview-file. By default, this doclet
%% looks for a file `"overview.edoc"' in the target directory.
%% </dd>
-%% <dt>{@type {private, bool()@}}
+%% <dt>{@type {private, boolean()@}}
%% </dt>
%% <dd>If the value is `true', documentation of private modules and
%% functions will also be included. The default value is `false'.
diff --git a/lib/edoc/src/edoc_extract.erl b/lib/edoc/src/edoc_extract.erl
index ea2755f7aa..5e28762c53 100644
--- a/lib/edoc/src/edoc_extract.erl
+++ b/lib/edoc/src/edoc_extract.erl
@@ -14,7 +14,7 @@
%% Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
%% USA
%%
-%% $Id$
+%% $Id: $
%%
%% @copyright 2001-2003 Richard Carlsson
%% @author Richard Carlsson <[email protected]>
@@ -34,10 +34,12 @@
%% %% @headerfile "edoc.hrl" (disabled until it can be made private)
-include("edoc.hrl").
-%% @type filename() = file:filename()
+%% @type filename() = file:filename().
+%% @type proplist() = proplists:property().
+%% @type syntaxTree() = erl_syntax:syntaxTree().
%% @spec source(File::filename(), Env::edoc_env(), Options::proplist())
-%% -> {ModuleName, edoc_module()}
+%% -> {ModuleName, edoc:edoc_module()}
%% ModuleName = atom()
%% proplist() = [term()]
%%
@@ -53,16 +55,11 @@ source(File, Env, Opts) ->
Comments = edoc:read_comments(File, Opts),
source(Forms, Comments, File, Env, Opts).
-%% @spec source(Forms, Comments::[comment()], File::filename(),
+%% @spec source(Forms, Comments::[edoc:comment()], File::filename(),
%% Env::edoc_env(), Options::proplist()) ->
-%% {ModuleName, edoc_module()}
+%% {ModuleName, edoc:edoc_module()}
%%
%% Forms = syntaxTree() | [syntaxTree()]
-%% comment() = {Line, Column, Indentation, Text}
-%% Line = integer()
-%% Column = integer()
-%% Indentation = integer()
-%% Text = [string()]
%% ModuleName = atom()
%%
%% @doc Like {@link source/4}, but first inserts the given comments in
@@ -80,15 +77,15 @@ source(Forms, Comments, File, Env, Opts) when is_list(Forms) ->
source(Forms1, Comments, File, Env, Opts);
source(Forms, Comments, File, Env, Opts) ->
Tree = erl_recomment:quick_recomment_forms(Forms, Comments),
- source(Tree, File, Env, Opts).
+ TypeDocs = find_type_docs(Forms, Comments),
+ source1(Tree, File, Env, Opts, TypeDocs).
%% @spec source(Forms, File::filename(), Env::edoc_env(),
%% Options::proplist()) ->
-%% {ModuleName, edoc_module()}
+%% {ModuleName, edoc:edoc_module()}
%%
%% Forms = syntaxTree() | [syntaxTree()]
%% ModuleName = atom()
-%% edoc_module() = edoc:edoc_module()
%% @type edoc_env() = edoc_lib:edoc_env()
%%
%% @doc Extracts EDoc documentation from commented source code syntax
@@ -116,6 +113,11 @@ source(Forms, Comments, File, Env, Opts) ->
source(Forms, File, Env, Opts) when is_list(Forms) ->
source(erl_syntax:form_list(Forms), File, Env, Opts);
source(Tree, File0, Env, Opts) ->
+ TypeDocs = find_type_docs(Tree, []),
+ source1(Tree, File0, Env, Opts, TypeDocs).
+
+%% Forms0 and Comments is used for extracting Erlang type documentation.
+source1(Tree, File0, Env, Opts, TypeDocs) ->
Forms = preprocess_forms(Tree),
File = edoc_lib:filename(File0),
Module = get_module_info(Tree, File),
@@ -126,11 +128,12 @@ source(Tree, File0, Env, Opts) ->
package = Package,
root = edoc_refs:relative_package_path('', Package)},
Env2 = add_macro_defs(module_macros(Env1), Opts, Env1),
- Entries1 = get_tags([Header, Footer | Entries], Env2, File),
- Data = edoc_data:module(Module, Entries1, Env2, Opts),
+ Entries1 = get_tags([Header, Footer | Entries], Env2, File, TypeDocs),
+ Entries2 = edoc_specs:add_data(Entries1, Opts, File, Module),
+ edoc_tags:check_types(Entries2, Opts, File),
+ Data = edoc_data:module(Module, Entries2, Env2, Opts),
{Name, Data}.
-
%% @spec header(File::filename(), Env::edoc_env(), Options::proplist())
%% -> {ok, Tags} | {error, Reason}
%% Tags = [term()]
@@ -148,7 +151,7 @@ header(File, Env, Opts) ->
Comments = edoc:read_comments(File),
header(Forms, Comments, File, Env, Opts).
-%% @spec header(Forms, Comments::[comment()], File::filename(),
+%% @spec header(Forms, Comments::[edoc:comment()], File::filename(),
%% Env::edoc_env(), Options::proplist()) ->
%% {ok, Tags} | {error, Reason}
%% Forms = syntaxTree() | [syntaxTree()]
@@ -196,7 +199,7 @@ header(Tree, File0, Env, _Opts) ->
%% kill all the information above it up to that point. Then we call
%% this the 'header' to make error reports make better sense.
{Header, Footer, Entries} = collect(Forms, Module),
- if Header#entry.data /= [] ->
+ if Header#entry.data /= {[],[],[]} ->
warning(File, "documentation before module declaration is ignored by @headerfile", []);
true -> ok
end,
@@ -215,7 +218,6 @@ add_macro_defs(Defs0, Opts, Env) ->
edoc_macros:check_defs(Defs),
Env#env{macros = Defs ++ Defs0 ++ Env#env.macros}.
-
%% @spec file(File::filename(), Context, Env::edoc_env(),
%% Options::proplist()) -> {ok, Tags} | {error, Reason}
%% Context = overview | package
@@ -276,7 +278,7 @@ text(Text, Context, Env, Opts, Where) ->
end.
-%% @spec (Forms::[syntaxTree()], File::filename()) -> moduleInfo()
+%% @spec (Forms::[syntaxTree()], File::filename()) -> module()
%% @doc Initialises a module-info record with data about the module
%% represented by the list of forms. Exports are guaranteed to exist in
%% the set of defined names.
@@ -351,6 +353,13 @@ preprocess_forms_2(F, Fs) ->
[F | preprocess_forms_1(Fs)];
text ->
[F | preprocess_forms_1(Fs)];
+ {attribute, {N, _}} ->
+ case edoc_specs:is_tag(N) of
+ true ->
+ [F | preprocess_forms_1(Fs)];
+ false ->
+ preprocess_forms_1(Fs)
+ end;
_ ->
preprocess_forms_1(Fs)
end.
@@ -362,42 +371,55 @@ preprocess_forms_2(F, Fs) ->
%% in the list.
collect(Fs, Mod) ->
- collect(Fs, [], [], undefined, Mod).
+ collect(Fs, [], [], [], [], undefined, Mod).
-collect([F | Fs], Cs, As, Header, Mod) ->
+collect([F | Fs], Cs, Ss, Ts, As, Header, Mod) ->
case erl_syntax_lib:analyze_form(F) of
comment ->
- collect(Fs, [F | Cs], As, Header, Mod);
+ collect(Fs, [F | Cs], Ss, Ts, As, Header, Mod);
{function, Name} ->
L = erl_syntax:get_pos(F),
Export = ordsets:is_element(Name, Mod#module.exports),
Args = parameters(erl_syntax:function_clauses(F)),
- collect(Fs, [], [#entry{name = Name, args = Args, line = L,
- export = Export,
- data = comment_text(Cs)} | As],
+ collect(Fs, [], [], [],
+ [#entry{name = Name, args = Args, line = L,
+ export = Export,
+ data = {comment_text(Cs),Ss,Ts}} | As],
Header, Mod);
{rule, Name} ->
L = erl_syntax:get_pos(F),
Export = ordsets:is_element(Name, Mod#module.exports),
Args = parameters(erl_syntax:rule_clauses(F)),
- collect(Fs, [], [#entry{name = Name, args = Args, line = L,
- export = Export,
- data = comment_text(Cs)} | As],
+ collect(Fs, [], [], [],
+ [#entry{name = Name, args = Args, line = L,
+ export = Export,
+ data = {comment_text(Cs),Ss,Ts}} | As],
Header, Mod);
{attribute, {module, _}} when Header =:= undefined ->
L = erl_syntax:get_pos(F),
- collect(Fs, [], As, #entry{name = module, line = L,
- data = comment_text(Cs)},
+ collect(Fs, [], [], [], As,
+ #entry{name = module, line = L,
+ data = {comment_text(Cs),Ss,Ts}},
Mod);
+ {attribute, {N, _}} ->
+ case edoc_specs:tag(N) of
+ spec ->
+ collect(Fs, Cs, [F | Ss], Ts, As, Header, Mod);
+ type ->
+ collect(Fs, Cs, Ss, [F | Ts], As, Header, Mod);
+ unknown ->
+ %% Drop current seen comments.
+ collect(Fs, [], [], [], As, Header, Mod)
+ end;
_ ->
%% Drop current seen comments.
- collect(Fs, [], As, Header, Mod)
+ collect(Fs, [], [], [], As, Header, Mod)
end;
-collect([], Cs, As, Header, _Mod) ->
- Footer = #entry{name = footer, data = comment_text(Cs)},
+collect([], Cs, Ss, Ts, As, Header, _Mod) ->
+ Footer = #entry{name = footer, data = {comment_text(Cs),Ss,Ts}},
As1 = lists:reverse(As),
if Header =:= undefined ->
- {#entry{name = module, data = []}, Footer, As1};
+ {#entry{name = module, data = {[],[],[]}}, Footer, As1};
true ->
{Header, Footer, As1}
end.
@@ -475,7 +497,7 @@ select_names([Ns | Ls], As, S) ->
select_names([], As, _) ->
lists:reverse(As).
-select_name([A | Ns], S) ->
+select_name([A | Ns], S) ->
case sets:is_element(A, S) of
true ->
select_name(Ns, S);
@@ -522,6 +544,9 @@ capitalize(Cs) -> Cs.
-record(tags, {names,single,module,function,footer}).
get_tags(Es, Env, File) ->
+ get_tags(Es, Env, File, dict:new()).
+
+get_tags(Es, Env, File, TypeDocs) ->
%% Cache this stuff for quick lookups.
Tags = #tags{names = sets:from_list(edoc_tags:tag_names()),
single = sets:from_list(edoc_tags:tags(single)),
@@ -529,17 +554,20 @@ get_tags(Es, Env, File) ->
footer = sets:from_list(edoc_tags:tags(footer)),
function = sets:from_list(edoc_tags:tags(function))},
How = dict:from_list(edoc_tags:tag_parsers()),
- get_tags(Es, Tags, Env, How, File).
+ get_tags(Es, Tags, Env, How, File, TypeDocs).
-get_tags([#entry{name = Name, data = Cs} = E | Es], Tags, Env,
- How, File) ->
+get_tags([#entry{name = Name, data = {Cs,Specs,Types}} = E | Es], Tags, Env,
+ How, File, TypeDocs) ->
Where = {File, Name},
Ts0 = scan_tags(Cs),
- Ts1 = check_tags(Ts0, Tags, Where),
- Ts2 = edoc_macros:expand_tags(Ts1, Env, Where),
- Ts = edoc_tags:parse_tags(Ts2, How, Env, Where),
- [E#entry{data = Ts} | get_tags(Es, Tags, Env, How, File)];
-get_tags([], _, _, _, _) ->
+ {Ts1,Specs1} = select_spec(Ts0, Where, Specs),
+ Ts2 = check_tags(Ts1, Tags, Where),
+ Ts3 = edoc_macros:expand_tags(Ts2, Env, Where),
+ Ts4 = edoc_tags:parse_tags(Ts3, How, Env, Where),
+ Ts = selected_specs(Specs1, Ts4),
+ ETypes = [edoc_specs:type(Type, TypeDocs) || Type <- Types],
+ [E#entry{data = Ts++ETypes} | get_tags(Es, Tags, Env, How, File, TypeDocs)];
+get_tags([], _, _, _, _, _) ->
[].
%% Scanning a list of separate comments for tags.
@@ -572,6 +600,22 @@ check_tags_1(Ts, Tags, Where) ->
Single = Tags#tags.single,
edoc_tags:check_tags(Ts, Allow, Single, Where).
+select_spec(Ts, {_, {_F, _A}}, Specs) ->
+ case edoc_tags:filter_tags(Ts, sets:from_list([spec])) of
+ [] ->
+ %% Just a dummy to get us through check_tags()
+ {[edoc_specs:dummy_spec(S) || S <- Specs] ++ Ts, Specs};
+ _ ->
+ {Ts,[]}
+ end;
+select_spec(Ts, _Where, _Specs) ->
+ {Ts,[]}.
+
+selected_specs([], Ts) ->
+ Ts;
+selected_specs([F], [_ | Ts]) ->
+ [edoc_specs:spec(F, _Clause=1) | Ts].
+
%% Macros for modules
module_macros(Env) ->
@@ -582,3 +626,25 @@ module_macros(Env) ->
file_macros(_Context, Env) ->
edoc_macros:std_macros(Env).
+
+%% @doc Extracts what will be documentation of Erlang types.
+%% Returns a dict of {Name, Doc} where Name is {TypeName, Arity}.
+%%
+%% 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.
+%% The same thing using -type:
+%% -type t() :: t1(). % Some docs of t/0;
+%% Further docs of t/0.
+find_type_docs(Forms0, Comments) ->
+ Tree = erl_recomment:recomment_forms(Forms0, Comments),
+ Forms = preprocess_forms(Tree),
+ edoc_specs:docs(Forms, fun find_fun/2).
+
+find_fun(C0, Line) ->
+ C1 = comment_text(C0),
+ Text = lists:append([C#comment.text || C <- C1]),
+ Comm = #comment{line = Line, text = Text},
+ [Tag | _] = scan_tags([Comm]),
+ Tag.
diff --git a/lib/edoc/src/edoc_layout.erl b/lib/edoc/src/edoc_layout.erl
index 6cc2f5cd9b..3ec87b7060 100644
--- a/lib/edoc/src/edoc_layout.erl
+++ b/lib/edoc/src/edoc_layout.erl
@@ -14,7 +14,7 @@
%% Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
%% USA
%%
-%% $Id$
+%% $Id: $
%%
%% @author Richard Carlsson <[email protected]>
%% @copyright 2001-2006 Richard Carlsson
@@ -49,7 +49,6 @@
-define(FUNCTIONS_TITLE, "Function Details").
-define(FUNCTIONS_LABEL, "functions").
-
%% @doc The layout function.
%%
%% Options to the standard layout:
@@ -59,13 +58,20 @@
%% <dd>Specifies the number of column pairs used for the function
%% index tables. The default value is 1.
%% </dd>
+%% <dt>{@type {pretty_printer, atom()@}}
+%% </dt>
+%% <dd>Specifies how types and specifications are pretty printed.
+%% If the value `erl_pp' is specified the Erlang pretty printer
+%% (the module `erl_pp') will be used. The default is to do
+%% no pretty printing which implies that lines can be very long.
+%% </dd>
%% <dt>{@type {stylesheet, string()@}}
%% </dt>
%% <dd>Specifies the URI used for referencing the stylesheet. The
%% default value is `"stylesheet.css"'. If an empty string is
%% specified, no stylesheet reference will be generated.
%% </dd>
-%% <dt>{@type {sort_functions, bool()@}}
+%% <dt>{@type {sort_functions, boolean()@}}
%% </dt>
%% <dd>If `true', the detailed function descriptions are listed by
%% name, otherwise they are listed in the order of occurrence in
@@ -96,14 +102,20 @@ module(Element, Options) ->
%% % stylesheet = string(),
%% % index_columns = integer()}
--record(opts, {root, stylesheet, index_columns, sort_functions}).
+-record(opts, {root,
+ stylesheet,
+ index_columns,
+ sort_functions,
+ pretty_printer}).
init_opts(Element, Options) ->
R = #opts{root = get_attrval(root, Element),
index_columns = proplists:get_value(index_columns,
Options, 1),
sort_functions = proplists:get_value(sort_functions,
- Options, true)
+ Options, true),
+ pretty_printer = proplists:get_value(pretty_printer,
+ Options, '')
},
case proplists:get_value(stylesheet, Options) of
undefined ->
@@ -112,7 +124,7 @@ init_opts(Element, Options) ->
"" ->
R; % don't use any stylesheet
S when is_list(S) ->
- R#opts{stylesheet = S};
+ R#opts{stylesheet = S};
_ ->
report("bad value for option `stylesheet'.", []),
exit(error)
@@ -192,10 +204,10 @@ layout_module(#xmlElement{name = module, content = Es}=E, Opts) ->
["Description"]}]}
| FullDesc]
end
- ++ types(lists:sort(Types))
+ ++ types(lists:sort(Types), Opts)
++ function_index(SortedFs, Opts#opts.index_columns)
- ++ if Opts#opts.sort_functions -> functions(SortedFs);
- true -> functions(Functions)
+ ++ if Opts#opts.sort_functions -> functions(SortedFs, Opts);
+ true -> functions(Functions, Opts)
end
++ [hr, ?NL]
++ navigation("bottom")
@@ -218,7 +230,7 @@ timestamp() ->
edoc_lib:timestr(time())])
]}]},
?NL].
-
+
stylesheet(Opts) ->
case Opts#opts.stylesheet of
undefined ->
@@ -335,8 +347,8 @@ label_href(Content, F) ->
%% <!ELEMENT equiv (expr, see?)>
%% <!ELEMENT expr (#PCDATA)>
-functions(Fs) ->
- Es = lists:flatmap(fun ({Name, E}) -> function(Name, E) end, Fs),
+functions(Fs, Opts) ->
+ Es = lists:flatmap(fun ({Name, E}) -> function(Name, E, Opts) end, Fs),
if Es == [] -> [];
true ->
[?NL,
@@ -344,7 +356,7 @@ functions(Fs) ->
?NL | Es]
end.
-function(Name, E=#xmlElement{content = Es}) ->
+function(Name, E=#xmlElement{content = Es}, Opts) ->
([?NL,
{h3, [{class, "function"}],
label_anchor(function_header(Name, E, " *"), E)},
@@ -352,7 +364,7 @@ function(Name, E=#xmlElement{content = Es}) ->
++ [{'div', [{class, "spec"}],
[?NL,
{p,
- case typespec(get_content(typespec, Es)) of
+ case typespec(get_content(typespec, Es), Opts) of
[] ->
signature(get_content(args, Es),
get_attrval(name, E));
@@ -367,7 +379,7 @@ function(Name, E=#xmlElement{content = Es}) ->
[] -> [];
Rs -> [{p, Rs}, ?NL]
end}]
- ++ throws(Es)
+ ++ throws(Es, Opts)
++ equiv_p(Es)
++ deprecated(Es, "function")
++ fulldesc(Es)
@@ -402,7 +414,7 @@ label_anchor(Content, E) ->
%% This is currently only done for functions without type spec.
-signature(Es, Name) ->
+signature(Es, Name) ->
[{tt, [Name, "("] ++ seq(fun arg/1, Es) ++ [") -> any()"]}].
arg(#xmlElement{content = Es}) ->
@@ -432,66 +444,168 @@ returns(Es) ->
%% <!ELEMENT throws (type, localdef*)>
-throws(Es) ->
+throws(Es, Opts) ->
case get_content(throws, Es) of
[] -> [];
Es1 ->
+ %% Doesn't use format_type; keep it short!
[{p, (["throws ", {tt, t_utype(get_elem(type, Es1))}]
- ++ local_defs(get_elem(localdef, Es1)))},
+ ++ local_defs(get_elem(localdef, Es1), Opts))},
?NL]
end.
%% <!ELEMENT typespec (erlangName, type, localdef*)>
-typespec([]) -> [];
-typespec(Es) ->
- [{tt, ([t_name(get_elem(erlangName, Es))]
- ++ t_utype(get_elem(type, Es)))}]
- ++ local_defs(get_elem(localdef, Es)).
+typespec([], _Opts) -> [];
+typespec(Es, Opts) ->
+ Name = t_name(get_elem(erlangName, Es)),
+ Defs = get_elem(localdef, Es),
+ [Type] = get_elem(type, Es),
+ format_spec(Name, Type, Defs, Opts) ++ local_defs(Defs, Opts).
%% <!ELEMENT typedecl (typedef, description?)>
%% <!ELEMENT typedef (erlangName, argtypes, type?, localdef*)>
-types([]) -> [];
-types(Ts) ->
- Es = lists:flatmap(fun ({Name, E}) -> typedecl(Name, E) end, Ts),
+types([], _Opts) -> [];
+types(Ts, Opts) ->
+ Es = lists:flatmap(fun ({Name, E}) -> typedecl(Name, E, Opts) end, Ts),
[?NL,
{h2, [{a, [{name, ?DATA_TYPES_LABEL}],
[?DATA_TYPES_TITLE]}]},
?NL | Es].
-typedecl(Name, E=#xmlElement{content = Es}) ->
+typedecl(Name, E=#xmlElement{content = Es}, Opts) ->
([?NL, {h3, [{class, "typedecl"}], label_anchor([Name, "()"], E)}, ?NL]
- ++ [{p, typedef(get_content(typedef, Es))}, ?NL]
+ ++ [{p, typedef(get_content(typedef, Es), Opts)}, ?NL]
++ fulldesc(Es)).
type_name(#xmlElement{content = Es}) ->
t_name(get_elem(erlangName, get_content(typedef, Es))).
-typedef(Es) ->
+typedef(Es, Opts) ->
Name = ([t_name(get_elem(erlangName, Es)), "("]
- ++ seq(fun t_utype_elem/1, get_content(argtypes, Es), [")"])),
+ ++ seq(fun t_utype_elem/1, get_content(argtypes, Es), [")"])),
(case get_elem(type, Es) of
[] -> [{b, ["abstract datatype"]}, ": ", {tt, Name}];
- Type ->
- [{tt, Name ++ [" = "] ++ t_utype(Type)}]
+ Type -> format_type(Name, Name, Type, [], Opts)
end
- ++ local_defs(get_elem(localdef, Es))).
+ ++ local_defs(get_elem(localdef, Es), Opts)).
-local_defs([]) -> [];
-local_defs(Es) ->
+local_defs(Es, Opts) ->
+ local_defs(Es, [], Opts).
+
+local_defs([], _, _Opts) -> [];
+local_defs(Es0, Last, Opts) ->
+ [E | Es] = lists:reverse(Es0),
[?NL,
{ul, [{class, "definitions"}],
- lists:append([[{li, [{tt, localdef(E)}]}, ?NL] || E <- Es])}].
-
-localdef(E = #xmlElement{content = Es}) ->
- (case get_elem(typevar, Es) of
- [] ->
- label_anchor(t_abstype(get_content(abstype, Es)), E);
- [V] ->
- t_var(V)
- end
- ++ [" = "] ++ t_utype(get_elem(type, Es))).
+ lists:reverse(lists:append([localdef(E1, [], Opts) || E1 <- Es]),
+ localdef(E, Last, Opts))}].
+
+localdef(E = #xmlElement{content = Es}, Last, Opts) ->
+ Name = case get_elem(typevar, Es) of
+ [] ->
+ label_anchor(N0 = t_abstype(get_content(abstype, Es)), E);
+ [V] ->
+ N0 = t_var(V)
+ end,
+ [{li, format_type(Name, N0, get_elem(type, Es), Last, Opts)}].
+
+%% Use the default formatting of EDoc, which creates references, and
+%% then insert newlines and indentation according to erl_pp (the
+%% (fast) Erlang pretty printer).
+format_spec(Name, Type, Defs, #opts{pretty_printer = erl_pp}=Opts) ->
+ try
+ L = t_clause(Name, Type),
+ O = pp_clause(Name, Type),
+ {R, ".\n"} = etypef(L, O),
+ [{pre, R}]
+ catch _:_ ->
+ %% Example: "@spec ... -> record(a)"
+ format_spec(Name, Type, Defs, Opts#opts{pretty_printer=''})
+ end;
+format_spec(Sep, Type, Defs, _Opts) ->
+ %% Very limited formatting.
+ Br = if Defs =:= [] -> br; true -> [] end,
+ [{tt, t_clause(Sep, Type)}, Br].
+
+t_clause(Name, Type) ->
+ #xmlElement{content = [#xmlElement{name = 'fun', content = C}]} = Type,
+ [Name] ++ t_fun(C).
+
+pp_clause(Pre, Type) ->
+ Types = ot_utype([Type]),
+ Atom = lists:duplicate(iolist_size(Pre), $a),
+ L1 = erl_pp:attribute({attribute,0,spec,{{list_to_atom(Atom),0},[Types]}}),
+ "-spec " ++ L2 = lists:flatten(L1),
+ L3 = Pre ++ lists:nthtail(length(Atom), L2),
+ re:replace(L3, "\n ", "\n", [{return,list},global]).
+
+format_type(Prefix, Name, Type, Last, #opts{pretty_printer = erl_pp}=Opts) ->
+ try
+ L = t_utype(Type),
+ O = pp_type(Name, Type),
+ {R, ".\n"} = etypef(L, O),
+ [{pre, Prefix ++ [" = "] ++ R ++ Last}]
+ catch _:_ ->
+ %% Example: "t() = record(a)."
+ format_type(Prefix, Name, Type, Last, Opts#opts{pretty_printer =''})
+ end;
+format_type(Prefix, _Name, Type, Last, _Opts) ->
+ [{tt, Prefix ++ [" = "] ++ t_utype(Type) ++ Last}].
+
+pp_type(Prefix, Type) ->
+ Atom = list_to_atom(lists:duplicate(iolist_size(Prefix), $a)),
+ L1 = erl_pp:attribute({attribute,0,type,{Atom,ot_utype(Type),[]}}),
+ {L2,N} = case lists:dropwhile(fun(C) -> C =/= $: end, lists:flatten(L1)) of
+ ":: " ++ L3 -> {L3,9}; % compensation for extra "()" and ":"
+ "::\n" ++ L3 -> {"\n"++L3,6}
+ end,
+ Ss = lists:duplicate(N, $\s),
+ re:replace(L2, "\n"++Ss, "\n", [{return,list},global]).
+
+etypef(L, O0) ->
+ {R, O} = etypef(L, [], O0, []),
+ {lists:reverse(R), O}.
+
+etypef([C | L], St, [C | O], R) ->
+ etypef(L, St, O, [[C] | R]);
+etypef(" "++L, St, O, R) ->
+ etypef(L, St, O, R);
+etypef("", [Cs | St], O, R) ->
+ etypef(Cs, St, O, R);
+etypef("", [], O, R) ->
+ {R, O};
+etypef(L, St, " "++O, R) ->
+ etypef(L, St, O, [" " | R]);
+etypef(L, St, "\n"++O, R) ->
+ Ss = lists:takewhile(fun(C) -> C =:= $\s end, O),
+ etypef(L, St, lists:nthtail(length(Ss), O), ["\n"++Ss | R]);
+etypef([{a, HRef, S0} | L], St, O0, R) ->
+ {S, O} = etypef(S0, app_fix(O0)),
+ etypef(L, St, O, [{a, HRef, S} | R]);
+etypef("="++L, St, "::"++O, R) ->
+ %% EDoc uses "=" for record field types; Erlang types use "::".
+ %% Maybe there should be an option for this, possibly affecting
+ %% other similar discrepancies.
+ etypef(L, St, O, ["=" | R]);
+etypef([Cs | L], St, O, R) ->
+ etypef(Cs, [L | St], O, R).
+
+app_fix(L) ->
+ try
+ {"//" ++ R1,L2} = app_fix(L, 1),
+ [App, Mod] = string:tokens(R1, "/"),
+ "//" ++ atom(App) ++ "/" ++ atom(Mod) ++ L2
+ catch _:_ -> L
+ end.
+
+app_fix(L, I) -> % a bit slow
+ {L1, L2} = lists:split(I, L),
+ case erl_scan:tokens([], L1 ++ ". ", 1) of
+ {done, {ok,[{atom,_,Atom}|_],_}, _} -> {atom_to_list(Atom), L2};
+ _ -> app_fix(L, I+1)
+ end.
fulldesc(Es) ->
case get_content(fullDescription, get_content(description, Es)) of
@@ -702,21 +816,28 @@ t_type([E=#xmlElement{name = atom}]) ->
t_atom(E);
t_type([E=#xmlElement{name = integer}]) ->
t_integer(E);
+t_type([E=#xmlElement{name = range}]) ->
+ t_range(E);
+t_type([E=#xmlElement{name = binary}]) ->
+ t_binary(E);
t_type([E=#xmlElement{name = float}]) ->
t_float(E);
t_type([#xmlElement{name = nil}]) ->
t_nil();
+t_type([#xmlElement{name = paren, content = Es}]) ->
+ t_paren(Es);
t_type([#xmlElement{name = list, content = Es}]) ->
t_list(Es);
+t_type([#xmlElement{name = nonempty_list, content = Es}]) ->
+ t_nonempty_list(Es);
t_type([#xmlElement{name = tuple, content = Es}]) ->
t_tuple(Es);
t_type([#xmlElement{name = 'fun', content = Es}]) ->
- t_fun(Es);
-t_type([#xmlElement{name = record, content = Es}]) ->
- t_record(Es);
+ ["fun("] ++ t_fun(Es) ++ [")"];
+t_type([E = #xmlElement{name = record, content = Es}]) ->
+ t_record(E, Es);
t_type([E = #xmlElement{name = abstype, content = Es}]) ->
- T = t_abstype(Es),
- see(E, T);
+ t_abstype(E, Es);
t_type([#xmlElement{name = union, content = Es}]) ->
t_union(Es).
@@ -729,15 +850,27 @@ t_atom(E) ->
t_integer(E) ->
[get_attrval(value, E)].
+t_range(E) ->
+ [get_attrval(value, E)].
+
+t_binary(E) ->
+ [get_attrval(value, E)].
+
t_float(E) ->
[get_attrval(value, E)].
t_nil() ->
["[]"].
+t_paren(Es) ->
+ ["("] ++ t_utype(get_elem(type, Es)) ++ [")"].
+
t_list(Es) ->
["["] ++ t_utype(get_elem(type, Es)) ++ ["]"].
+t_nonempty_list(Es) ->
+ ["["] ++ t_utype(get_elem(type, Es)) ++ [", ...]"].
+
t_tuple(Es) ->
["{"] ++ seq(fun t_utype_elem/1, Es, ["}"]).
@@ -745,13 +878,27 @@ t_fun(Es) ->
["("] ++ seq(fun t_utype_elem/1, get_content(argtypes, Es),
[") -> "] ++ t_utype(get_elem(type, Es))).
-t_record(Es) ->
- ["#"] ++ t_type(get_elem(atom, Es)) ++ ["{"]
- ++ seq(fun t_field/1, get_elem(field, Es), ["}"]).
+t_record(E, Es) ->
+ Name = ["#"] ++ t_type(get_elem(atom, Es)),
+ case get_elem(field, Es) of
+ [] ->
+ see(E, [Name, "{}"]);
+ Fs ->
+ see(E, Name) ++ ["{"] ++ seq(fun t_field/1, Fs, ["}"])
+ end.
t_field(#xmlElement{content = Es}) ->
t_type(get_elem(atom, Es)) ++ [" = "] ++ t_utype(get_elem(type, Es)).
+t_abstype(E, Es) ->
+ Name = t_name(get_elem(erlangName, Es)),
+ case get_elem(type, Es) of
+ [] ->
+ see(E, [Name, "()"]);
+ Ts ->
+ see(E, [Name]) ++ ["("] ++ seq(fun t_utype_elem/1, Ts, [")"])
+ end.
+
t_abstype(Es) ->
([t_name(get_elem(erlangName, Es)), "("]
++ seq(fun t_utype_elem/1, get_elem(type, Es), [")"])).
@@ -827,7 +974,8 @@ type(E) ->
type(E, []).
type(E, Ds) ->
- xmerl:export_simple_content(t_utype_elem(E) ++ local_defs(Ds),
+ Opts = [],
+ xmerl:export_simple_content(t_utype_elem(E) ++ local_defs(Ds, Opts),
?HTML_EXPORT).
package(E=#xmlElement{name = package, content = Es}, Options) ->
@@ -873,3 +1021,142 @@ overview(E=#xmlElement{name = overview, content = Es}, Options) ->
++ timestamp()),
XML = xhtml(Title, stylesheet(Opts), Body),
xmerl:export_simple(XML, ?HTML_EXPORT, []).
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% NYTT
+
+ot_utype([E]) ->
+ ot_utype_elem(E).
+
+ot_utype_elem(E=#xmlElement{content = Es}) ->
+ case get_attrval(name, E) of
+ "" -> ot_type(Es);
+ N ->
+ Name = {var,0,list_to_atom(N)},
+ T = ot_type(Es),
+ case T of
+ Name -> T;
+ T -> {ann_type,0,[Name, T]}
+ end
+ end.
+
+ot_type([E=#xmlElement{name = typevar}]) ->
+ ot_var(E);
+ot_type([E=#xmlElement{name = atom}]) ->
+ ot_atom(E);
+ot_type([E=#xmlElement{name = integer}]) ->
+ ot_integer(E);
+ot_type([E=#xmlElement{name = range}]) ->
+ ot_range(E);
+ot_type([E=#xmlElement{name = binary}]) ->
+ ot_binary(E);
+ot_type([E=#xmlElement{name = float}]) ->
+ ot_float(E);
+ot_type([#xmlElement{name = nil}]) ->
+ ot_nil();
+ot_type([#xmlElement{name = paren, content = Es}]) ->
+ ot_paren(Es);
+ot_type([#xmlElement{name = list, content = Es}]) ->
+ ot_list(Es);
+ot_type([#xmlElement{name = nonempty_list, content = Es}]) ->
+ ot_nonempty_list(Es);
+ot_type([#xmlElement{name = tuple, content = Es}]) ->
+ ot_tuple(Es);
+ot_type([#xmlElement{name = 'fun', content = Es}]) ->
+ ot_fun(Es);
+ot_type([#xmlElement{name = record, content = Es}]) ->
+ ot_record(Es);
+ot_type([#xmlElement{name = abstype, content = Es}]) ->
+ ot_abstype(Es);
+ot_type([#xmlElement{name = union, content = Es}]) ->
+ ot_union(Es).
+
+ot_var(E) ->
+ {var,0,list_to_atom(get_attrval(name, E))}.
+
+ot_atom(E) ->
+ {ok, [Atom], _} = erl_scan:string(get_attrval(value, E), 0),
+ Atom.
+
+ot_integer(E) ->
+ {integer,0,list_to_integer(get_attrval(value, E))}.
+
+ot_range(E) ->
+ [I1, I2] = string:tokens(get_attrval(value, E), "."),
+ {type,0,range,[{integer,0,list_to_integer(I1)},
+ {integer,0,list_to_integer(I2)}]}.
+
+ot_binary(E) ->
+ {Base, Unit} =
+ case string:tokens(get_attrval(value, E), ",:*><") of
+ [] ->
+ {0, 0};
+ ["_",B] ->
+ {list_to_integer(B), 0};
+ ["_","_",U] ->
+ {0, list_to_integer(U)};
+ ["_",B,_,"_",U] ->
+ {list_to_integer(B), list_to_integer(U)}
+ end,
+ {type,0,binary,[{integer,0,Base},{integer,0,Unit}]}.
+
+ot_float(E) ->
+ {float,0,list_to_float(get_attrval(value, E))}.
+
+ot_nil() ->
+ {nil,0}.
+
+ot_paren(Es) ->
+ {paren_type,0,[ot_utype(get_elem(type, Es))]}.
+
+ot_list(Es) ->
+ {type,0,list,[ot_utype(get_elem(type, Es))]}.
+
+ot_nonempty_list(Es) ->
+ {type,0,nonempty_list,[ot_utype(get_elem(type, Es))]}.
+
+ot_tuple(Es) ->
+ {type,0,tuple,[ot_utype_elem(E) || E <- Es]}.
+
+ot_fun(Es) ->
+ Range = ot_utype(get_elem(type, Es)),
+ Args = [ot_utype_elem(A) || A <- get_content(argtypes, Es)],
+ {type,0,'fun',[{type,0,product,Args},Range]}.
+
+ot_record(Es) ->
+ {type,0,record,[ot_type(get_elem(atom, Es)) |
+ [ot_field(F) || F <- get_elem(field, Es)]]}.
+
+ot_field(#xmlElement{content = Es}) ->
+ {type,0,field_type,
+ [ot_type(get_elem(atom, Es)), ot_utype(get_elem(type, Es))]}.
+
+ot_abstype(Es) ->
+ ot_name(get_elem(erlangName, Es),
+ [ot_utype_elem(Elem) || Elem <- get_elem(type, Es)]).
+
+ot_union(Es) ->
+ {type,0,union,[ot_utype_elem(E) || E <- Es]}.
+
+ot_name(Es, T) ->
+ case ot_name(Es) of
+ [Mod, ":", Atom] ->
+ {remote_type,0,[{atom,0,list_to_atom(Mod)},
+ {atom,0,list_to_atom(Atom)},T]};
+ "tuple" when T =:= [] ->
+ {type,0,tuple,any};
+ Atom ->
+ {type,0,list_to_atom(Atom),T}
+ end.
+
+ot_name([E]) ->
+ Atom = get_attrval(name, E),
+ case get_attrval(module, E) of
+ "" -> Atom;
+ M ->
+ case get_attrval(app, E) of
+ "" ->
+ [M, ":", Atom];
+ A ->
+ ["//"++A++"/" ++ M, ":", Atom] % EDoc only!
+ end
+ end.
diff --git a/lib/edoc/src/edoc_lib.erl b/lib/edoc/src/edoc_lib.erl
index 6705ccd356..585e30a2d2 100644
--- a/lib/edoc/src/edoc_lib.erl
+++ b/lib/edoc/src/edoc_lib.erl
@@ -947,6 +947,7 @@ get_doc_env(Opts) ->
%% Modules = [atom()]
%% proplist() = [term()]
%%
+%% @type proplist() = proplists:property().
%% @type edoc_env(). Environment information needed by EDoc for
%% generating references. The data representation is not documented.
%%
diff --git a/lib/edoc/src/edoc_parser.yrl b/lib/edoc/src/edoc_parser.yrl
index 91ee5a1b2b..6943f1bdb8 100644
--- a/lib/edoc/src/edoc_parser.yrl
+++ b/lib/edoc/src/edoc_parser.yrl
@@ -24,21 +24,22 @@
%%
%% Author contact: [email protected]
%%
-%% $Id$
+%% $Id $
%%
%% =====================================================================
Nonterminals
start spec func_type utype_list utype_tuple utypes utype ptypes ptype
-nutype function_name where_defs defs def typedef etype throws qname ref
-aref mref lref pref var_list vars fields field.
+nutype function_name where_defs defs defs2 def typedef etype
+throws qname ref aref mref lref pref var_list vars fields field
+futype_list bin_base_type bin_unit_type.
Terminals
-atom float integer var string start_spec start_typedef start_throws
+atom float integer var an_var string start_spec start_typedef start_throws
start_ref
'(' ')' ',' '.' '->' '{' '}' '[' ']' '|' '+' ':' '::' '=' '/' '//' '*'
-'#' 'where'.
+'#' 'where' '<<' '>>' '..' '...'.
Rootsymbol start.
@@ -52,9 +53,9 @@ qname -> atom: [tok_val('$1')].
qname -> qname '.' atom: [tok_val('$3') | '$1'].
spec -> func_type where_defs:
- #t_spec{type = '$1', defs = lists:reverse('$2')}.
+ #t_spec{type = '$1', defs = '$2'}.
spec -> function_name func_type where_defs:
- #t_spec{name = '$1', type = '$2', defs = lists:reverse('$3')}.
+ #t_spec{name = '$1', type = '$2', defs = '$3'}.
where_defs -> 'where' defs: '$2'.
where_defs -> defs: '$1'.
@@ -66,13 +67,15 @@ func_type -> utype_list '->' utype:
%% Paired with line number, for later error reporting
-utype_list -> '(' ')' : {[], tok_line('$1')}.
utype_list -> '(' utypes ')' : {lists:reverse('$2'), tok_line('$1')}.
-utype_tuple -> '{' '}' : [].
+futype_list -> utype_list : '$1'.
+futype_list -> '(' '...' ')' : {[#t_var{name = '...'}], tok_line('$1')}.
+
utype_tuple -> '{' utypes '}' : lists:reverse('$2').
%% Produced in reverse order.
+utypes -> '$empty' : [].
utypes -> utype : ['$1'].
utypes -> utypes ',' utype : ['$3' | '$1'].
@@ -90,20 +93,25 @@ ptypes -> ptypes '|' ptype : ['$3' | '$1'].
ptype -> var : #t_var{name = tok_val('$1')}.
ptype -> atom : #t_atom{val = tok_val('$1')}.
ptype -> integer: #t_integer{val = tok_val('$1')}.
+ptype -> integer '..' integer: #t_integer_range{from = tok_val('$1'),
+ to = tok_val('$3')}.
ptype -> float: #t_float{val = tok_val('$1')}.
ptype -> utype_tuple : #t_tuple{types = '$1'}.
ptype -> '[' ']' : #t_nil{}.
ptype -> '[' utype ']' : #t_list{type = '$2'}.
+ptype -> '[' utype ',' '...' ']' : #t_nonempty_list{type = '$2'}.
ptype -> utype_list:
- if length(element(1, '$1')) == 1 ->
+ if length(element(1, '$1')) == 1 ->
%% there must be exactly one utype in the list
hd(element(1, '$1'));
+ %% Replace last line when releasing next major release:
+ %% #t_paren{type = hd(element(1, '$1'))};
length(element(1, '$1')) == 0 ->
return_error(element(2, '$1'), "syntax error before: ')'");
true ->
return_error(element(2, '$1'), "syntax error before: ','")
end.
-ptype -> utype_list '->' ptype:
+ptype -> futype_list '->' ptype:
#t_fun{args = element(1, '$1'), range = '$3'}.
ptype -> '#' atom '{' '}' :
#t_record{name = #t_atom{val = tok_val('$2')}}.
@@ -111,17 +119,45 @@ ptype -> '#' atom '{' fields '}' :
#t_record{name = #t_atom{val = tok_val('$2')},
fields = lists:reverse('$4')}.
ptype -> atom utype_list:
- #t_type{name = #t_name{name = tok_val('$1')},
- args = element(1, '$2')}.
-ptype -> qname ':' atom utype_list :
+ case {tok_val('$1'), element(1, '$2')} of
+ {nil, []} ->
+ %% Prefer '[]' before 'nil(). Due to
+ %% compatibility with Erlang types, which do not
+ %% separate '[]' from 'nil()'.
+ #t_nil{};
+ {list, [T]} ->
+ %% Prefer '[T]' before 'list(T). Due to
+ %% compatibility with Erlang types, which do not
+ %% separate '[T]' from 'list(T)'.
+ #t_list{type = T};
+ {'fun', [#t_fun{}=Fun]} ->
+ %% An incompatible change as compared to EDOc 0.7.6.6.
+ %% Due to compatibility with Erlang types.
+ Fun;
+ {'fun', []} ->
+ #t_type{name = #t_name{name = function}};
+ {Name, Args} ->
+ #t_type{name = #t_name{name = Name},
+ args = Args}
+ end.
+ptype -> qname ':' atom utype_list :
#t_type{name = #t_name{module = qname('$1'),
name = tok_val('$3')},
args = element(1, '$4')}.
-ptype -> '//' atom '/' qname ':' atom utype_list :
+ptype -> '//' atom '/' qname ':' atom utype_list :
#t_type{name = #t_name{app = tok_val('$2'),
module = qname('$4'),
name = tok_val('$6')},
args = element(1, '$7')}.
+ptype -> '<<' '>>' : #t_binary{}.
+ptype -> '<<' bin_base_type '>>' : #t_binary{base_size = '$2'}.
+ptype -> '<<' bin_unit_type '>>' : #t_binary{unit_size = '$2'}.
+ptype -> '<<' bin_base_type ',' bin_unit_type '>>' :
+ #t_binary{base_size = '$2', unit_size = '$4'}.
+
+bin_base_type -> an_var ':' integer: tok_val('$3').
+
+bin_unit_type -> an_var ':' an_var '*' integer : tok_val('$5').
%% Produced in reverse order.
fields -> field : ['$1'].
@@ -130,18 +166,19 @@ fields -> fields ',' field : ['$3' | '$1'].
field -> atom '=' utype :
#t_field{name = #t_atom{val = tok_val('$1')}, type = '$3'}.
-%% Produced in reverse order.
defs -> '$empty' : [].
-defs -> defs def : ['$2' | '$1'].
-defs -> defs ',' def : ['$3' | '$1'].
+defs -> def defs2 : ['$1' | lists:reverse('$2')].
+
+%% Produced in reverse order.
+defs2 -> '$empty' : [].
+defs2 -> defs2 def : ['$2' | '$1'].
+defs2 -> defs2 ',' def : ['$3' | '$1'].
def -> var '=' utype:
#t_def{name = #t_var{name = tok_val('$1')},
type = '$3'}.
-def -> atom var_list '=' utype:
- #t_def{name = #t_type{name = #t_name{name = tok_val('$1')},
- args = '$2'},
- type = '$4'}.
+def -> atom '(' utypes ')' '=' utype:
+ build_def(tok_val('$1'), '$2', '$3', '$6').
var_list -> '(' ')' : [].
var_list -> '(' vars ')' : lists:reverse('$2').
@@ -153,12 +190,12 @@ vars -> vars ',' var : [#t_var{name = tok_val('$3')} | '$1'].
typedef -> atom var_list where_defs:
#t_typedef{name = #t_name{name = tok_val('$1')},
args = '$2',
- defs = lists:reverse('$3')}.
+ defs = '$3'}.
typedef -> atom var_list '=' utype where_defs:
#t_typedef{name = #t_name{name = tok_val('$1')},
args = '$2',
type = '$4',
- defs = lists:reverse('$5')}.
+ defs = '$5'}.
%% References
@@ -195,7 +232,7 @@ etype -> utype: '$1'.
throws -> etype where_defs:
#t_throws{type = '$1',
- defs = lists:reverse('$2')}.
+ defs = '$2'}.
%% (commented out for now)
%% Header
@@ -297,7 +334,22 @@ union(Ts) ->
end.
annotate(T, A) -> ?add_t_ann(T, A).
-
+
+build_def(S, P, As, T) ->
+ case all_vars(As) of
+ true ->
+ #t_def{name = #t_type{name = #t_name{name = S},
+ args = lists:reverse(As)},
+ type = T};
+ false ->
+ return_error(element(2, P), "variable expected after '('")
+ end.
+
+all_vars([#t_var{} | As]) ->
+ all_vars(As);
+all_vars(As) ->
+ As =:= [].
+
%% ---------------------------------------------------------------------
%% @doc EDoc type specification parsing. Parses the content of
@@ -379,7 +431,7 @@ parse_param(S, L) ->
{S1, S2} = edoc_lib:split_at_space(edoc_lib:strip_space(S)),
case edoc_lib:strip_space(S1) of
"" -> throw_error(parse_param, L);
- Name ->
+ Name ->
Text = edoc_lib:strip_space(S2),
{list_to_atom(Name), edoc_wiki:parse_xml(Text, L)}
end.
diff --git a/lib/edoc/src/edoc_refs.erl b/lib/edoc/src/edoc_refs.erl
index edc30674c0..b974cf77c1 100644
--- a/lib/edoc/src/edoc_refs.erl
+++ b/lib/edoc/src/edoc_refs.erl
@@ -19,7 +19,7 @@
%% @author Richard Carlsson <[email protected]>
%% @see edoc
%% @see edoc_parse_ref
-%% @end
+%% @end
%% =====================================================================
%% @doc Representation and handling of EDoc object references. See
diff --git a/lib/edoc/src/edoc_scanner.erl b/lib/edoc/src/edoc_scanner.erl
index d3dff64682..9d2e6f3aed 100644
--- a/lib/edoc/src/edoc_scanner.erl
+++ b/lib/edoc/src/edoc_scanner.erl
@@ -3,24 +3,24 @@
%% compliance with the License. You should have received a copy of the
%% Erlang Public License along with this software. If not, it can be
%% retrieved via the world wide web at http://www.erlang.org/.
-%%
+%%
%% Software distributed under the License is distributed on an "AS IS"
%% basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
%% the License for the specific language governing rights and
%% limitations under the License.
-%%
+%%
%% The Initial Developer of the Original Code is Ericsson Utvecklings
%% AB. Portions created by Ericsson are Copyright 1999, Ericsson
%% Utvecklings AB. All Rights Reserved.''
%%
-%% $Id$
+%% $Id: $
%%
%% @private
%% @copyright Richard Carlsson 2001-2003. Portions created by Ericsson
%% are Copyright 1999, Ericsson Utvecklings AB. All Rights Reserved.
%% @author Richard Carlsson <[email protected]>
%% @see edoc
-%% @end
+%% @end
%% @doc Tokeniser for EDoc. Based on the Erlang standard library module
%% {@link //stdlib/erl_scan}.
@@ -139,13 +139,21 @@ scan1([$"|Cs0], Toks, Pos) -> % String
scan_error({illegal, string}, Pos)
end;
%% Punctuation characters and operators, first recognise multiples.
+scan1([$<,$<|Cs], Toks, Pos) ->
+ scan1(Cs, [{'<<',Pos}|Toks], Pos);
+scan1([$>,$>|Cs], Toks, Pos) ->
+ scan1(Cs, [{'>>',Pos}|Toks], Pos);
scan1([$-,$>|Cs], Toks, Pos) ->
scan1(Cs, [{'->',Pos}|Toks], Pos);
scan1([$:,$:|Cs], Toks, Pos) ->
scan1(Cs, [{'::',Pos}|Toks], Pos);
scan1([$/,$/|Cs], Toks, Pos) ->
scan1(Cs, [{'//',Pos}|Toks], Pos);
-scan1([C|Cs], Toks, Pos) -> % Punctuation character
+scan1([$.,$.,$.|Cs], Toks, Pos) ->
+ scan1(Cs, [{'...',Pos}|Toks], Pos);
+scan1([$.,$.|Cs], Toks, Pos) ->
+ scan1(Cs, [{'..',Pos}|Toks], Pos);
+scan1([C|Cs], Toks, Pos) -> % Punctuation character
P = list_to_atom([C]),
scan1(Cs, [{P,Pos}|Toks], Pos);
scan1([], Toks0, _Pos) ->
@@ -158,7 +166,7 @@ scan_variable(C, Cs, Toks, Pos) ->
W = [C|reverse(Wcs)],
case W of
"_" ->
- scan_error({illegal,token}, Pos);
+ scan1(Cs1, [{an_var,Pos,'_'}|Toks], Pos);
_ ->
case catch list_to_atom(W) of
A when is_atom(A) ->
@@ -318,7 +326,7 @@ scan_integer(Cs, Stack, Pos) ->
scan_after_int([$.,C|Cs0], Ncs0, Toks, SPos, CPos) when C >= $0, C =< $9 ->
{Ncs,Cs,CPos1} = scan_integer(Cs0, [C,$.|Ncs0], CPos),
- scan_after_fraction(Cs, Ncs, Toks, SPos, CPos1);
+ scan_after_fraction(Cs, Ncs, Toks, SPos, CPos1);
scan_after_int(Cs, Ncs, Toks, SPos, CPos) ->
N = list_to_integer(reverse(Ncs)),
scan1(Cs, [{integer,SPos,N}|Toks], CPos).
diff --git a/lib/edoc/src/edoc_specs.erl b/lib/edoc/src/edoc_specs.erl
new file mode 100644
index 0000000000..45016ef85a
--- /dev/null
+++ b/lib/edoc/src/edoc_specs.erl
@@ -0,0 +1,603 @@
+%
+%% %CopyrightBegin%
+%%
+%% Copyright Ericsson AB 1996-2011. All Rights Reserved.
+%%
+%% The contents of this file are subject to the Erlang Public License,
+%% Version 1.1, (the "License"); you may not use this file except in
+%% compliance with the License. You should have received a copy of the
+%% Erlang Public License along with this software. If not, it can be
+%% retrieved online at http://www.erlang.org/.
+%%
+%% Software distributed under the License is distributed on an "AS IS"
+%% basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+%% the License for the specific language governing rights and limitations
+%% under the License.
+%%
+%% %CopyrightEnd%
+
+%% @doc EDoc interface to Erlang specifications and types.
+
+-module(edoc_specs).
+
+-export([type/2, spec/2, dummy_spec/1, docs/2]).
+
+-export([add_data/4, tag/1, is_tag/1]).
+
+-include("edoc.hrl").
+-include("edoc_types.hrl").
+
+-type proplist() :: [proplists:property()].
+-type syntaxTree() :: erl_syntax:syntaxTree().
+
+-define(TOP_TYPE, term).
+
+%%
+%% Exported functions
+%%
+
+-spec type(Form::syntaxTree(), TypeDocs::dict()) -> #tag{}.
+
+%% @doc Convert an Erlang type to EDoc representation.
+%% TypeDocs is a dict of {Name, Doc}.
+%% Note: #t_typedef.name is set to {record, R} for record types.
+type(Form, TypeDocs) ->
+ {Name, Data0} = erl_syntax_lib:analyze_wild_attribute(Form),
+ type = tag(Name),
+ {TypeName, Type, Args, Doc} =
+ case Data0 of
+ {{record, R}, Fs, []} ->
+ L = erl_syntax:get_pos(Form),
+ {{record, R}, {type, L, record, [{atom,L,R} | Fs]}, [], ""};
+ {N,T,As} ->
+ Doc0 =
+ case dict:find({N, length(As)}, TypeDocs) of
+ {ok, Doc1} ->
+ Doc1;
+ error ->
+ ""
+ end,
+ {#t_name{name = N}, T, As, Doc0}
+ end,
+ #tag{name = type, line = element(2, Type),
+ origin = code,
+ data = {#t_typedef{name = TypeName,
+ args = d2e(Args),
+ type = d2e(opaque2abstr(Name, Type))},
+ Doc}}.
+
+-spec spec(Form::syntaxTree(), ClauseN::pos_integer()) -> #tag{}.
+
+%% @doc Convert an Erlang spec to EDoc representation.
+spec(Form, Clause) ->
+ {Name, _Arity, TypeSpecs} = get_spec(Form),
+ TypeSpec = lists:nth(Clause, TypeSpecs),
+ #tag{name = spec, line = element(2, TypeSpec),
+ origin = code,
+ data = aspec(d2e(TypeSpec), Name)}.
+
+-spec dummy_spec(Form::syntaxTree()) -> #tag{}.
+
+%% @doc Create a #tag{} record where data is a string with the name of
+%% the given Erlang spec and an empty list of arguments.
+dummy_spec(Form) ->
+ {#t_name{name = Name}, Arity, TypeSpecs} = get_spec(Form),
+ As = string:join(lists:duplicate(Arity, "_X"), ","),
+ S = lists:flatten(io_lib:format("~p(~s) -> true\n", [Name, As])),
+ #tag{name = spec, line = element(2, hd(TypeSpecs)),
+ origin = code, data = S}.
+
+-spec docs(Forms::[syntaxTree()], CommentFun) -> dict() when
+ CommentFun :: fun(([syntaxTree()], Line :: term()) -> #tag{}).
+
+%% @doc Find comments after -type/-opaque declarations.
+%% Postcomments "inside" the type are skipped.
+docs(Forms, CommentFun) ->
+ find_type_docs(Forms, [], CommentFun).
+
+-type entry() :: #entry{}.
+-type module_info() :: #module{}.
+-type entries() :: [entry()].
+-spec add_data(Entries::entries(), Options::proplist(),
+ File::file:filename(), Module::module_info()) -> entries().
+
+%% @doc Create tags a la EDoc for Erlang specifications and types.
+%% Exported types and types used (indirectly) by Erlang specs are
+%% added to the entries.
+add_data(Entries, Opts, File, Module) ->
+ TypeDefs0 = espec_types(Entries),
+ TypeTable = ets:new(etypes, [ordered_set]),
+ Es1 = expand_records(Entries, TypeDefs0, TypeTable, Opts, File, Module),
+ Es = [use_tags(E, TypeTable) || E <- Es1],
+ true = ets:delete(TypeTable),
+ Es.
+
+%%
+%% Local functions
+%%
+
+aspec(#t_spec{}=Spec, Name) ->
+ Spec#t_spec{name = Name};
+aspec(Type, Name) ->
+ #t_spec{name = Name, type = Type}.
+
+get_spec(Form) ->
+ {spec, Data0} = erl_syntax_lib:analyze_wild_attribute(Form),
+ case Data0 of
+ {{F,A}, D} ->
+ {#t_name{name = F}, A, D};
+ {{M,F,A}, D} ->
+ {#t_name{module = M, name = F}, A, D}
+ end.
+
+find_type_docs([], Cs, _Fun) ->
+ dict:from_list(Cs);
+find_type_docs([F | Fs], Cs, Fun) ->
+ try get_name_and_last_line(F) of
+ {Name, LastTypeLine} ->
+ C0 = erl_syntax:comment(["% @type f(). "]),
+ C1 = erl_syntax:set_pos(C0, LastTypeLine),
+ %% Postcomments before the dot after the typespec are ignored.
+ C2 = [C1 | [C ||
+ C <- erl_syntax:get_postcomments(F),
+ get_line(erl_syntax:get_pos(C)) >= LastTypeLine]],
+ C3 = collect_comments(Fs, LastTypeLine),
+ #tag{data = Doc0} = Fun(lists:reverse(C2 ++ C3), LastTypeLine),
+ case strip(Doc0) of % Strip away "f(). \n"
+ "" ->
+ find_type_docs(Fs, Cs, Fun);
+ Doc ->
+ W = edoc_wiki:parse_xml(Doc, LastTypeLine),
+ find_type_docs(Fs, [{Name, W}|Cs], Fun)
+ end
+ catch _:_ ->
+ find_type_docs(Fs, Cs, Fun)
+ end.
+
+collect_comments([], _Line) ->
+ [];
+collect_comments([F | Fs], Line) ->
+ L1 = get_line(erl_syntax:get_pos(F)),
+ if
+ L1 =:= Line + 1;
+ L1 =:= Line -> % a separate postcomment
+ case is_comment(F) of
+ true ->
+ [F | collect_comments(Fs, L1)];
+ false ->
+ []
+ end;
+ true ->
+ []
+ end.
+%% Note: there is a creepy bug concerning an include file terminated
+%% by a -type attribute and the include statement is followed by a
+%% comment (which is not meant to be documentation of the type).
+
+is_comment(F) ->
+ erl_syntax_lib:analyze_form(F) =:= comment.
+
+strip("") ->
+ "";
+strip([$\n | S]) ->
+ S;
+strip([_ | S]) ->
+ strip(S).
+
+%% Find the type name and the greatest line number of a type spec.
+%% Should use syntax_tools but this has to do for now.
+get_name_and_last_line(F) ->
+ {Name, Data} = erl_syntax_lib:analyze_wild_attribute(F),
+ type = edoc_specs:tag(Name),
+ Attr = {attribute, erl_syntax:get_pos(F), Name, Data},
+ Ref = make_ref(),
+ Fun = fun(L) -> {Ref, get_line(L)} end,
+ TypeName = case Data of
+ {N, _T, As} when is_atom(N) -> % skip records
+ {N, length(As)}
+ end,
+ Line = gll(erl_lint:modify_line(Attr, Fun), Ref),
+ {TypeName, Line}.
+
+gll({Ref, Line}, Ref) ->
+ Line;
+gll([], _Ref) ->
+ 0;
+gll(List, Ref) when is_list(List) ->
+ lists:max([gll(E, Ref) || E <- List]);
+gll(Tuple, Ref) when is_tuple(Tuple) ->
+ gll(tuple_to_list(Tuple), Ref);
+gll(_, _) ->
+ 0.
+
+get_line(Pos) ->
+ {line, Line} = erl_scan:attributes_info(Pos, line),
+ Line.
+
+%% Collect all Erlang types. Types in comments (@type) shadow Erlang
+%% types (-spec/-opaque).
+espec_types(Entries) ->
+ Tags = get_all_tags(Entries),
+ CommTs = [type_name(T) ||
+ #tag{name = type, origin = comment}=T <- Tags],
+ CT = sets:from_list(CommTs),
+ [T || #tag{name = Name, origin = code}=T <- Tags,
+ tag(Name) =:= type,
+ not sets:is_element(type_name(T), CT)].
+
+get_all_tags(Es) ->
+ lists:flatmap(fun (#entry{data = Ts}) -> Ts end, Es).
+
+%% Turns an opaque type into an abstract datatype.
+%% Note: top level annotation is ignored.
+opaque2abstr(opaque, _T) -> undefined;
+opaque2abstr(type, T) -> T.
+
+%% Replaces the parameters extracted from the source (by
+%% edoc_extract:parameters/1) by annotations and variable names, using
+%% the source parameters as default values
+%% Selects seen types (exported types, types used by specs),
+%% skips records and unused types.
+use_tags(#entry{data = Ts}=E, TypeTable) ->
+ use_tags(Ts, E, TypeTable, []).
+
+use_tags([], E, _TypeTable, NTs) ->
+ E#entry{data = lists:reverse(NTs)};
+use_tags([#tag{origin = code}=T | Ts], E, TypeTable, NTs) ->
+ case tag(T#tag.name) of
+ spec ->
+ Args = params(T, E#entry.args),
+ use_tags(Ts, E#entry{args = Args}, TypeTable, [T | NTs]);
+ type ->
+ TypeName = type_name(T),
+ case ets:lookup(TypeTable, TypeName) of
+ [{{{record,_},_},_,_}] ->
+ use_tags(Ts, E, TypeTable, NTs);
+ [{_,_,not_seen}] ->
+ use_tags(Ts, E, TypeTable, NTs);
+ [] ->
+ use_tags(Ts, E, TypeTable, NTs);
+ [{TypeName, Tag, seen}] ->
+ use_tags(Ts, E, TypeTable, [Tag | NTs])
+ end
+ end;
+use_tags([T | Ts], E, TypeTable, NTs) ->
+ use_tags(Ts, E, TypeTable, [T | NTs]).
+
+params(#tag{name = spec, data=#t_spec{type = #t_fun{args = As}}}, Default) ->
+ parms(As, Default).
+
+parms([], []) ->
+ [];
+parms([A | As], [D | Ds]) ->
+ [param(A, D) | parms(As, Ds)].
+
+param(#t_list{type = Type}, Default) ->
+ param(Type, Default);
+param(#t_paren{type = Type}, Default) ->
+ param(Type, Default);
+param(#t_nonempty_list{type = Type}, Default) ->
+ param(Type, Default);
+param(#t_record{name = #t_atom{val = Name}}, _Default) ->
+ list_to_atom(capitalize(atom_to_list(Name)));
+param(T, Default) ->
+ arg_name(?t_ann(T), Default).
+
+capitalize([C | Cs]) when C >= $a, C =< $z -> [C - 32 | Cs];
+capitalize(Cs) -> Cs.
+
+%% Like edoc_types:arg_name/1
+arg_name([], Default) ->
+ Default;
+arg_name([A | As], Default) ->
+ case is_name(A) of
+ true -> A;
+ false -> arg_name(As, Default)
+ end.
+
+is_name(A) ->
+ is_atom(A).
+
+d2e({ann_type,_,[V, T0]}) ->
+ %% Note: the -spec/-type syntax allows annotations everywhere, but
+ %% EDoc does not. The fact that the annotation is added to the
+ %% type here does not necessarily mean that it will be used by the
+ %% layout module.
+ T = d2e(T0),
+ ?add_t_ann(T, element(3, V));
+d2e({type,_,no_return,[]}) ->
+ #t_type{name = #t_name{name = none}};
+d2e({remote_type,_,[{atom,_,M},{atom,_,F},Ts0]}) ->
+ Ts = d2e(Ts0),
+ typevar_anno(#t_type{name = #t_name{module = M, name = F}, args = Ts}, Ts);
+d2e({type,_,'fun',[{type,_,product,As0},Ran0]}) ->
+ Ts = [Ran|As] = d2e([Ran0|As0]),
+ %% Assume that the linter has checked type variables.
+ typevar_anno(#t_fun{args = As, range = Ran}, Ts);
+d2e({type,_,'fun',[A0={type,_,any},Ran0]}) ->
+ Ts = [A, Ran] = d2e([A0, Ran0]),
+ typevar_anno(#t_fun{args = [A], range = Ran}, Ts);
+d2e({type,_,'fun',[]}) ->
+ #t_type{name = #t_name{name = function}, args = []};
+d2e({type,_,any}) ->
+ #t_var{name = '...'}; % Kludge... not a type variable!
+d2e({type,_,nil,[]}) ->
+ #t_nil{};
+d2e({paren_type,_,[T]}) ->
+ #t_paren{type = d2e(T)};
+d2e({type,_,list,[T0]}) ->
+ T = d2e(T0),
+ typevar_anno(#t_list{type = T}, [T]);
+d2e({type,_,nonempty_list,[T0]}) ->
+ T = d2e(T0),
+ typevar_anno(#t_nonempty_list{type = T}, [T]);
+d2e({type,_,bounded_fun,[T,Gs]}) ->
+ [F0|Defs] = d2e([T|Gs]),
+ F = ?set_t_ann(F0, lists:keydelete(type_variables, 1, ?t_ann(F0))),
+ %% Assume that the linter has checked type variables.
+ #t_spec{type = typevar_anno(F, [F0]), defs = Defs};
+d2e({type,_,range,[V1,V2]}) ->
+ {integer,_,I1} = erl_eval:partial_eval(V1),
+ {integer,_,I2} = erl_eval:partial_eval(V2),
+ #t_integer_range{from = I1, to = I2};
+d2e({type,_,constraint,[Sub,Ts0]}) ->
+ case {Sub,Ts0} of
+ {{atom,_,is_subtype},[{var,_,N},T0]} ->
+ Ts = [T] = d2e([T0]),
+ #t_def{name = #t_var{name = N}, type = typevar_anno(T, Ts)};
+ {{atom,_,is_subtype},[ST0,T0]} ->
+ %% Should not happen.
+ Ts = [ST,T] = d2e([ST0,T0]),
+ #t_def{name = ST, type = typevar_anno(T, Ts)};
+ _ ->
+ throw_error(element(2, Sub), "cannot handle guard", [])
+ end;
+d2e({type,_,union,Ts0}) ->
+ Ts = d2e(Ts0),
+ typevar_anno(#t_union{types = Ts}, Ts);
+d2e({type,_,tuple,any}) ->
+ #t_type{name = #t_name{name = tuple}, args = []};
+d2e({type,_,binary,[Base,Unit]}) ->
+ #t_binary{base_size = element(3, Base),
+ unit_size = element(3, Unit)};
+d2e({type,_,tuple,Ts0}) ->
+ Ts = d2e(Ts0),
+ typevar_anno(#t_tuple{types = Ts}, Ts);
+d2e({type,_,record,[Name|Fs0]}) ->
+ Atom = #t_atom{val = element(3, Name)},
+ Fs = d2e(Fs0),
+ typevar_anno(#t_record{name = Atom, fields = Fs}, Fs);
+d2e({type,_,field_type,[Name,Type0]}) ->
+ Type = d2e(Type0),
+ typevar_anno(#t_field{name = #t_atom{val = element(3, Name)}, type = Type},
+ [Type]);
+d2e({typed_record_field,{record_field,L,Name},Type}) ->
+ d2e({type,L,field_type,[Name,Type]});
+d2e({typed_record_field,{record_field,L,Name,_E},Type}) ->
+ d2e({type,L,field_type,[Name,Type]});
+d2e({record_field,L,_Name,_E}=F) ->
+ d2e({typed_record_field,F,{type,L,any,[]}}); % Maybe skip...
+d2e({record_field,L,_Name}=F) ->
+ d2e({typed_record_field,F,{type,L,any,[]}}); % Maybe skip...
+d2e({type,_,Name,Types0}) ->
+ Types = d2e(Types0),
+ typevar_anno(#t_type{name = #t_name{name = Name}, args = Types}, Types);
+d2e({var,_,'_'}) ->
+ #t_type{name = #t_name{name = ?TOP_TYPE}};
+d2e({var,_,TypeName}) ->
+ TypeVar = ordsets:from_list([TypeName]),
+ T = #t_var{name = TypeName},
+ %% Annotate type variables with the name of the variable.
+ %% Doing so will stop edoc_layout (and possibly other layout modules)
+ %% from using the argument name from the source or to invent a new name.
+ T1 = ?add_t_ann(T, {type_variables, TypeVar}),
+ ?add_t_ann(T1, TypeName);
+d2e(L) when is_list(L) ->
+ [d2e(T) || T <- L];
+d2e({atom,_,A}) ->
+ #t_atom{val = A};
+d2e(undefined = U) -> % opaque
+ U;
+d2e(Expr) ->
+ {integer,_,I} = erl_eval:partial_eval(Expr),
+ #t_integer{val = I}.
+
+%% A type annotation (a tuple; neither an atom nor a list).
+typevar_anno(Type, Ts) ->
+ Vs = typevars(Ts),
+ case ordsets:to_list(Vs) of
+ [] -> Type;
+ _ -> ?add_t_ann(Type, {type_variables, Vs})
+ end.
+
+typevars(Ts) ->
+ ordsets:union(get_typevars(Ts)).
+
+get_typevars(Ts) ->
+ [Vs || T <- Ts, T =/= undefined, {type_variables, Vs} <- ?t_ann(T)].
+
+-record(parms, {tab, warn, file, line}).
+
+%% Expands record references. Explicitly given record fields are kept,
+%% but otherwise the fields from the record definition are substituted
+%% for the reference. The reason is that there are no record types.
+%% It is recommended to introduce types like "r() :: r{}" and then use
+%% r() everywhere. The right hand side, r{}, is expanded in order to
+%% show all fields.
+%% Returns updated types in the ETS table DT.
+expand_records(Entries, TypeDefs, DT, Opts, File, Module) ->
+ TypeList = [{type_name(T), T, not_seen} || T <- TypeDefs],
+ true = ets:insert(DT, TypeList),
+ Warn = proplists:get_value(report_missing_type, Opts,
+ ?REPORT_MISSING_TYPE) =:= true,
+ P = #parms{tab = DT, warn = Warn, file = File, line = 0},
+ ExportedTypes = [Name ||
+ {export_type,Ts} <- Module#module.attributes,
+ is_list(Ts),
+ {N,I} <- Ts,
+ ets:member(DT, Name = {#t_name{name = N}, I})],
+ _ = lists:foreach(fun({N,A}) -> true = seen_type(N, A, P)
+ end, ExportedTypes),
+ entries(Entries, P, Opts).
+
+entries([E0 | Es], P, Opts) ->
+ E = case edoc_data:hidden_filter([E0], Opts) of
+ [] ->
+ E0;
+ [_] ->
+ E0#entry{data = specs(E0#entry.data, P)}
+ end,
+ [E | entries(Es, P, Opts)];
+entries([], _P, _Opts) ->
+ [].
+
+specs([#tag{line = L, name = spec, origin = code, data = Spec}=Tag0 | Tags],
+ P0) ->
+ #t_spec{type = Type0, defs = Defs0} = Spec,
+ P = P0#parms{line = L},
+ Type = xrecs(Type0, P),
+ Defs = xrecs(Defs0, P),
+ Tag = Tag0#tag{data = Spec#t_spec{type = Type, defs = Defs}},
+ [Tag | specs(Tags, P)];
+specs([Tag | Tags], P) ->
+ [Tag | specs(Tags, P)];
+specs([], _P) ->
+ [].
+
+xrecs(#t_def{type = Type0}=T, P) ->
+ Type = xrecs(Type0, P),
+ T#t_def{type = Type};
+xrecs(#t_type{name = Name, args = Args0}=T, P) ->
+ Args = xrecs(Args0, P),
+ NArgs = length(Args),
+ true = seen_type(Name, NArgs, P),
+ T#t_type{args = Args};
+xrecs(#t_var{}=T, _P) ->
+ T;
+xrecs(#t_fun{args = Args0, range = Range0}=T, P) ->
+ Args = xrecs(Args0, P),
+ Range = xrecs(Range0, P),
+ T#t_fun{args = Args, range = Range};
+xrecs(#t_tuple{types = Types0}=T, P) ->
+ Types = xrecs(Types0, P),
+ T#t_tuple{types = Types};
+xrecs(#t_list{type = Type0}=T, P) ->
+ Type = xrecs(Type0, P),
+ T#t_list{type = Type};
+xrecs(#t_nil{}=T, _P) ->
+ T;
+xrecs(#t_paren{type = Type0}=T, P) ->
+ Type = xrecs(Type0, P),
+ T#t_paren{type = Type};
+xrecs(#t_nonempty_list{type = Type0}=T, P) ->
+ Type = xrecs(Type0, P),
+ T#t_nonempty_list{type = Type};
+xrecs(#t_atom{}=T, _P) ->
+ T;
+xrecs(#t_integer{}=T, _P) ->
+ T;
+xrecs(#t_integer_range{}=T, _P) ->
+ T;
+xrecs(#t_binary{}=T, _P) ->
+ T;
+xrecs(#t_float{}=T, _P) ->
+ T;
+xrecs(#t_union{types = Types0}=T, P) ->
+ Types = xrecs(Types0, P),
+ T#t_union{types = Types};
+xrecs(#t_record{fields = Fields0}=T, P) ->
+ Fields1 = xrecs(Fields0, P),
+ #t_record{name = #t_atom{val = Name}} = T,
+ RName = {record, Name},
+ true = seen_type(RName, 0, P),
+ Fields = select_fields(Fields1, RName, P#parms.tab),
+ T#t_record{fields = Fields};
+xrecs(#t_field{type = Type0}=T, P) ->
+ Type = xrecs(Type0, P),
+ T#t_field{type = Type};
+xrecs(undefined=T, _P) -> % opaque
+ T;
+xrecs([]=T, _P) ->
+ T;
+xrecs([E0 | Es0], P) ->
+ [xrecs(E0, P) | xrecs(Es0, P)].
+
+seen_type(N, NArgs, P) ->
+ TypeName = {N, NArgs},
+ #parms{tab = DT} = P,
+ case {ets:lookup(DT, TypeName), N} of
+ {[{TypeName, _, seen}], _} ->
+ true;
+ {[{TypeName, TagType, not_seen}], _} when N#t_name.module =:= [] ->
+ expand_datatype(TagType, proper_type, DT, P);
+ {[{TypeName, TagType, not_seen}], {record, _}} ->
+ expand_datatype(TagType, record_type, DT, P);
+ {[], {record, R}} ->
+ #parms{warn = W, line = L, file = File} = P,
+ [edoc_report:warning(L, File, "reference to untyped record ~w",
+ [R]) || W],
+ ets:insert(DT, {TypeName, fake, seen});
+ {[], _} -> % External type or missing type.
+ true
+ end.
+
+expand_datatype(Tag0, Kind, DT, P0) ->
+ #tag{line = L, data = {T0, Doc}} = Tag0,
+ #t_typedef{type = Type0, defs = []} = T0,
+ TypeName = type_name(Tag0),
+ true = ets:update_element(DT, TypeName, {3, seen}),
+ P = P0#parms{line = L},
+ Type = case Kind of
+ record_type ->
+ #t_record{fields = Fields0} = Type0,
+ Fields = xrecs(Fields0, P),
+ Type0#t_record{fields = Fields};
+ proper_type ->
+ xrecs(Type0, P)
+ end,
+ Tag = Tag0#tag{data={T0#t_typedef{type=Type}, Doc}},
+ ets:insert(DT, {TypeName, Tag, seen}).
+
+select_fields(Fields, Name, DT) ->
+ RecordName = {Name, 0},
+ case ets:lookup(DT, RecordName) of
+ [{RecordName, fake, seen}] ->
+ Fields;
+ [{RecordName, #tag{data = {T, _Doc}}, seen}] ->
+ #t_typedef{args = [], type = #t_record{fields = Fs}, defs = []}=T,
+ [find_field(F, Fields) || F <- Fs]
+ end.
+
+find_field(F, Fs) ->
+ case lists:keyfind(F#t_field.name, #t_field.name, Fs) of
+ false -> F;
+ NF -> NF
+ end.
+
+type_name(#tag{name = type,
+ data = {#t_typedef{name = Name, args = As},_}}) ->
+ {Name, length(As)}.
+
+%% @doc Return `true' if `Tag' is one of the specification and type
+%% attribute tags recognized by the Erlang compiler.
+
+-spec is_tag(Tag::atom()) -> boolean().
+
+is_tag(opaque) -> true;
+is_tag(spec) -> true;
+is_tag(type) -> true;
+is_tag(_) -> false.
+
+%% @doc Return the kind of the attribute tag.
+
+-type tag_kind() :: 'type' | 'spec' | 'unknown'.
+-spec tag(Tag::atom()) -> tag_kind().
+
+tag(opaque) -> type;
+tag(spec) -> spec;
+tag(type) -> type;
+tag(_) -> unknown.
+
+throw_error(Line, S, A) ->
+ edoc_report:error(Line, "", io_lib:format(S, A)),
+ throw(error).
diff --git a/lib/edoc/src/edoc_tags.erl b/lib/edoc/src/edoc_tags.erl
index c0b861e08a..def39ee34c 100644
--- a/lib/edoc/src/edoc_tags.erl
+++ b/lib/edoc/src/edoc_tags.erl
@@ -31,7 +31,8 @@
-module(edoc_tags).
-export([tags/0, tags/1, tag_names/0, tag_parsers/0, scan_lines/2,
- filter_tags/3, check_tags/4, parse_tags/4]).
+ filter_tags/2, filter_tags/3, check_tags/4, parse_tags/4,
+ check_types/3]).
-import(edoc_report, [report/4, warning/4, error/3]).
@@ -201,6 +202,9 @@ append_lines([]) -> [].
%% Filtering out unknown tags.
+filter_tags(Ts, Tags) ->
+ filter_tags(Ts, Tags, no).
+
filter_tags(Ts, Tags, Where) ->
filter_tags(Ts, Tags, Where, []).
@@ -211,7 +215,8 @@ filter_tags([#tag{name = N, line = L} = T | Ts], Tags, Where, Ts1) ->
true ->
filter_tags(Ts, Tags, Where, [T | Ts1]);
false ->
- warning(L, Where, "tag @~s not recognized.", [N]),
+ [warning(L, Where, "tag @~s not recognized.", [N]) ||
+ Where =/= no],
filter_tags(Ts, Tags, Where, Ts1)
end;
filter_tags([], _, _, Ts) ->
@@ -320,12 +325,24 @@ parse_contact(Data, Line, _Env, _Where) ->
Info
end.
-parse_typedef(Data, Line, _Env, _Where) ->
+parse_typedef(Data, Line, _Env, Where) ->
Def = edoc_parser:parse_typedef(Data, Line),
- {#t_typedef{name = #t_name{name = T}}, _} = Def,
- case edoc_types:is_predefined(T) of
+ {#t_typedef{name = #t_name{name = T}, args = As}, _} = Def,
+ NAs = length(As),
+ case edoc_types:is_predefined(T, NAs) of
true ->
- throw_error(Line, {"redefining built-in type '~w'.", [T]});
+ case
+ edoc_types:is_new_predefined(T, NAs)
+ orelse edoc_types:is_predefined_otp_type(T, NAs)
+ of
+ false ->
+ throw_error(Line, {"redefining built-in type '~w'.",
+ [T]});
+ true ->
+ warning(Line, Where, "redefining built-in type '~w'.",
+ [T]),
+ Def
+ end;
false ->
Def
end.
@@ -384,3 +401,107 @@ throw_error(L, file_not_string) ->
throw_error(L, "expected file name as a string");
throw_error(L, D) ->
throw({error, L, D}).
+
+%% Checks local types.
+
+-record(parms, {tab, warn, file, line}).
+
+check_types(Entries0, Opts, File) ->
+ Entries = edoc_data:hidden_filter(Entries0, Opts),
+ Tags = edoc_data:get_all_tags(Entries),
+ DT = ets:new(types, [bag]),
+ _ = [add_type(DT, Name, As, File, Line) ||
+ #tag{line = Line,
+ data = {#t_typedef{name = Name, args = As},_}} <- Tags],
+ Warn = proplists:get_value(report_missing_type, Opts,
+ ?REPORT_MISSING_TYPE) =:= true,
+ P = #parms{tab = DT, warn = Warn, file = File, line = 0},
+ try check_types(Tags, P)
+ after true = ets:delete(DT)
+ end.
+
+add_type(DT, Name, Args, File, Line) ->
+ NArgs = length(Args),
+ TypeName = {Name, NArgs},
+ case lists:member(TypeName, ets:lookup(DT, Name)) of
+ true ->
+ #t_name{name = N} = Name,
+ type_warning(Line, File, "duplicated type", N, NArgs);
+ false ->
+ ets:insert(DT, {Name, NArgs})
+ end.
+
+check_types([], _P)->
+ ok;
+check_types([Tag | Tags], P) ->
+ check_type(Tag, P, Tags).
+
+check_type(#tag{line = L, data = Data}, P0, Ts) ->
+ P = P0#parms{line = L},
+ case Data of
+ {#t_typedef{type = Type, defs = Defs},_} ->
+ check_type(Type, P, Defs++Ts);
+ #t_spec{type = Type, defs = Defs} ->
+ check_type(Type, P, Defs++Ts);
+ _->
+ check_types(Ts, P0)
+ end;
+check_type(#t_def{type = Type}, P, Ts) ->
+ check_type(Type, P, Ts);
+check_type(#t_type{name = Name, args = Args}, P, Ts) ->
+ check_used_type(Name, Args, P),
+ check_types(Args++Ts, P);
+check_type(#t_var{}, P, Ts) ->
+ check_types(Ts, P);
+check_type(#t_fun{args = Args, range = Range}, P, Ts) ->
+ check_type(Range, P, Args++Ts);
+check_type(#t_tuple{types = Types}, P, Ts) ->
+ check_types(Types ++Ts, P);
+check_type(#t_list{type = Type}, P, Ts) ->
+ check_type(Type, P, Ts);
+check_type(#t_nil{}, P, Ts) ->
+ check_types(Ts, P);
+check_type(#t_paren{type = Type}, P, Ts) ->
+ check_type(Type, P, Ts);
+check_type(#t_nonempty_list{type = Type}, P, Ts) ->
+ check_type(Type, P, Ts);
+check_type(#t_atom{}, P, Ts) ->
+ check_types(Ts, P);
+check_type(#t_integer{}, P, Ts) ->
+ check_types(Ts, P);
+check_type(#t_integer_range{}, P, Ts) ->
+ check_types(Ts, P);
+check_type(#t_binary{}, P, Ts) ->
+ check_types(Ts, P);
+check_type(#t_float{}, P, Ts) ->
+ check_types(Ts, P);
+check_type(#t_union{types = Types}, P, Ts) ->
+ check_types(Types++Ts, P);
+check_type(#t_record{fields = Fields}, P, Ts) ->
+ check_types(Fields++Ts, P);
+check_type(#t_field{type = Type}, P, Ts) ->
+ check_type(Type, P, Ts);
+check_type(undefined, P, Ts) ->
+ check_types(Ts, P).
+
+check_used_type(#t_name{name = N, module = Mod}=Name, Args, P) ->
+ NArgs = length(Args),
+ TypeName = {Name, NArgs},
+ DT = P#parms.tab,
+ case
+ Mod =/= []
+ orelse lists:member(TypeName, ets:lookup(DT, Name))
+ orelse edoc_types:is_predefined(N, NArgs)
+ orelse edoc_types:is_predefined_otp_type(N, NArgs)
+ of
+ true ->
+ ok;
+ false ->
+ #parms{warn = W, line = L, file = File} = P,
+ %% true = ets:insert(DT, TypeName),
+ [type_warning(L, File, "missing type", N, NArgs) || W]
+ end.
+
+type_warning(Line, File, S, N, NArgs) ->
+ AS = ["/"++integer_to_list(NArgs) || NArgs > 0],
+ warning(Line, File, S++" ~w~s", [N, AS]).
diff --git a/lib/edoc/src/edoc_types.erl b/lib/edoc/src/edoc_types.erl
index b0255f793d..1ded63dffe 100644
--- a/lib/edoc/src/edoc_types.erl
+++ b/lib/edoc/src/edoc_types.erl
@@ -14,6 +14,8 @@
%% Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
%% USA
%%
+%% $Id$
+%%
%% @private
%% @copyright 2001-2003 Richard Carlsson
%% @author Richard Carlsson <[email protected]>
@@ -25,8 +27,9 @@
-module(edoc_types).
--export([is_predefined/1, to_ref/1, to_xml/2, to_label/1, arg_names/1,
- set_arg_names/2, arg_descs/1, range_desc/1]).
+-export([is_predefined/2, is_new_predefined/2, is_predefined_otp_type/2,
+ to_ref/1, to_xml/2, to_label/1, arg_names/1, set_arg_names/2,
+ arg_descs/1, range_desc/1]).
%% @headerfile "edoc_types.hrl"
@@ -34,27 +37,63 @@
-include("xmerl.hrl").
-is_predefined(any) -> true;
-is_predefined(atom) -> true;
-is_predefined(binary) -> true;
-is_predefined(bool) -> true;
-is_predefined(char) -> true;
-is_predefined(cons) -> true;
-is_predefined(deep_string) -> true;
-is_predefined(float) -> true;
-is_predefined(function) -> true;
-is_predefined(integer) -> true;
-is_predefined(list) -> true;
-is_predefined(nil) -> true;
-is_predefined(none) -> true;
-is_predefined(number) -> true;
-is_predefined(pid) -> true;
-is_predefined(port) -> true;
-is_predefined(reference) -> true;
-is_predefined(string) -> true;
-is_predefined(term) -> true;
-is_predefined(tuple) -> true;
-is_predefined(_) -> false.
+is_predefined(any, 0) -> true;
+is_predefined(atom, 0) -> true;
+is_predefined(binary, 0) -> true;
+is_predefined(bool, 0) -> true;
+is_predefined(char, 0) -> true;
+is_predefined(cons, 2) -> true;
+is_predefined(deep_string, 0) -> true;
+is_predefined(float, 0) -> true;
+is_predefined(function, 0) -> true;
+is_predefined(integer, 0) -> true;
+is_predefined(list, 0) -> true;
+is_predefined(list, 1) -> true;
+is_predefined(nil, 0) -> true;
+is_predefined(none, 0) -> true;
+is_predefined(number, 0) -> true;
+is_predefined(pid, 0) -> true;
+is_predefined(port, 0) -> true;
+is_predefined(reference, 0) -> true;
+is_predefined(string, 0) -> true;
+is_predefined(term, 0) -> true;
+is_predefined(tuple, 0) -> true;
+is_predefined(F, A) -> is_new_predefined(F, A).
+
+%% Should eventually be coalesced with is_predefined/2.
+is_new_predefined(arity, 0) -> true;
+is_new_predefined(bitstring, 0) -> true;
+is_new_predefined(boolean, 0) -> true;
+is_new_predefined(byte, 0) -> true;
+is_new_predefined(iodata, 0) -> true;
+is_new_predefined(iolist, 0) -> true;
+is_new_predefined(maybe_improper_list, 0) -> true;
+is_new_predefined(maybe_improper_list, 2) -> true;
+is_new_predefined(mfa, 0) -> true;
+is_new_predefined(module, 0) -> true;
+is_new_predefined(neg_integer, 0) -> true;
+is_new_predefined(node, 0) -> true;
+is_new_predefined(non_neg_integer, 0) -> true;
+is_new_predefined(nonempty_improper_list, 2) -> true;
+is_new_predefined(nonempty_list, 0) -> true;
+is_new_predefined(nonempty_list, 1) -> true;
+is_new_predefined(nonempty_maybe_improper_list, 0) -> true;
+is_new_predefined(nonempty_maybe_improper_list, 2) -> true;
+is_new_predefined(nonempty_string, 0) -> true;
+is_new_predefined(pos_integer, 0) -> true;
+is_new_predefined(timeout, 0) -> true;
+is_new_predefined(_, _) -> false.
+
+%% The following types will be removed later, but they are currently
+%% kind of built-in.
+is_predefined_otp_type(array, 0) -> true;
+is_predefined_otp_type(dict, 0) -> true;
+is_predefined_otp_type(digraph, 0) -> true;
+is_predefined_otp_type(gb_set, 0) -> true;
+is_predefined_otp_type(gb_tree, 0) -> true;
+is_predefined_otp_type(queue, 0) -> true;
+is_predefined_otp_type(set, 0) -> true;
+is_predefined_otp_type(_, _) -> false.
to_ref(#t_typedef{name = N}) ->
to_ref(N);
@@ -89,7 +128,9 @@ to_xml(#t_name{app = A, module = M, name = N}, _Env) ->
to_xml(#t_type{name = N, args = As}, Env) ->
Predef = case N of
#t_name{module = [], name = T} ->
- is_predefined(T);
+ NArgs = length(As),
+ (is_predefined(T, NArgs)
+ orelse is_predefined_otp_type(T, NArgs));
_ ->
false
end,
@@ -107,14 +148,30 @@ to_xml(#t_list{type = T}, Env) ->
{list, [wrap_utype(T, Env)]};
to_xml(#t_nil{}, _Env) ->
nil;
+to_xml(#t_paren{type = T}, Env) ->
+ {paren, [wrap_utype(T, Env)]};
+to_xml(#t_nonempty_list{type = T}, Env) ->
+ {nonempty_list, [wrap_utype(T, Env)]};
to_xml(#t_atom{val = V}, _Env) ->
{atom, [{value, io_lib:write(V)}], []};
to_xml(#t_integer{val = V}, _Env) ->
{integer, [{value, integer_to_list(V)}], []};
+to_xml(#t_integer_range{from = From, to = To}, _Env) ->
+ {range, [{value, integer_to_list(From)++".."++integer_to_list(To)}], []};
+to_xml(#t_binary{base_size = 0, unit_size = 0}, _Ens) ->
+ {binary, [{value, "<<>>"}], []};
+to_xml(#t_binary{base_size = B, unit_size = 0}, _Ens) ->
+ {binary, [{value, io_lib:fwrite("<<_:~w>>", [B])}], []};
+%to_xml(#t_binary{base_size = 0, unit_size = 8}, _Ens) ->
+% {binary, [{value, "binary()"}], []};
+to_xml(#t_binary{base_size = 0, unit_size = U}, _Ens) ->
+ {binary, [{value, io_lib:fwrite("<<_:_*~w>>", [U])}], []};
+to_xml(#t_binary{base_size = B, unit_size = U}, _Ens) ->
+ {binary, [{value, io_lib:fwrite("<<_:~w, _:_*~w>>", [B, U])}], []};
to_xml(#t_float{val = V}, _Env) ->
{float, [{value, io_lib:write(V)}], []};
to_xml(#t_union{types = Ts}, Env) ->
- {union, map(fun wrap_type/2, Ts, Env)};
+ {union, map(fun wrap_utype/2, Ts, Env)};
to_xml(#t_record{name = N = #t_atom{}, fields = Fs}, Env) ->
{record, [to_xml(N, Env) | map(fun to_xml/2, Fs, Env)]};
to_xml(#t_field{name = N = #t_atom{}, type = T}, Env) ->
diff --git a/lib/edoc/src/edoc_types.hrl b/lib/edoc/src/edoc_types.hrl
index 1dcbdd9493..1353bfb93a 100644
--- a/lib/edoc/src/edoc_types.hrl
+++ b/lib/edoc/src/edoc_types.hrl
@@ -1,6 +1,6 @@
%% =====================================================================
%% Header file for EDoc Type Representations
-%%
+%%
%% Copyright (C) 2001-2005 Richard Carlsson
%%
%% This library is free software; you can redistribute it and/or modify
@@ -29,13 +29,15 @@
-record(t_spec, {name, type, defs=[]}). % function specification
-%% @type type() = t_atom() | t_fun() | t_integer() | t_list() | t_nil()
-%% | t_tuple() | t_type() | t_union() | t_var()
+%% @type type() = t_atom() | t_binary() | t_float() | t_fun() | t_integer()
+%% | t_integer_range() | t_list() | t_nil()| t_nonempty_list()
+%% | t_record() | t_tuple() | t_type() | t_union() | t_var()
+%% | t_paren()
%% @type t_typedef() = #t_typedef{name = t_name(),
%% args = [type()],
-%% type = type(),
-%% defs = [t_def()]}
+%% type = type() | undefined,
+%% defs = [t_def()]}.
-record(t_typedef, {name, args, type,
defs=[]}). % type declaration/definition
@@ -45,7 +47,7 @@
-record(t_throws, {type, defs=[]}). % exception declaration
-%% @type t_def() = #t_def{name = t_name(),
+%% @type t_def() = #t_def{name = t_type() | t_var(),
%% type = type()}
-record(t_def, {name, type}). % local definition 'name = type'
@@ -75,7 +77,9 @@
%% name = t_name(),
%% args = [type()]}
--record(t_type, {a=[], name, args = []}). % abstract type 'name(...)'
+-record(t_type, {a=[], % abstract type 'name(...)'
+ name,
+ args = []}).
%% @type t_union() = #t_union{a = list(),
%% types = [type()]}
@@ -102,6 +106,11 @@
-record(t_nil, {a=[]}). % empty-list constant '[]'
+%% @type t_nonempty_list() = #t_nonempty_list{a = list(),
+%% type = type()}
+
+-record(t_nonempty_list, {a=[], type}). % list type '[type, ...]'
+
%% @type t_atom() = #t_atom{a = list(),
%% val = atom()}
@@ -112,19 +121,37 @@
-record(t_integer, {a=[], val}). % integer constant
+%% @type t_integer_range() = #t_integer_range{a = list(),
+%% from = integer(),
+%% to = integer()}
+
+-record(t_integer_range, {a=[], from, to}).
+
+%% @type t_binary() = #t_binary{a = list(),
+%% base_size = integer(),
+%% unit_size = integer()}
+
+-record(t_binary, {a=[], base_size = 0, unit_size = 0}).
+
%% @type t_float() = #t_float{a = list(),
%% val = float()}
-record(t_float, {a=[], val}). % floating-point constant
%% @type t_record() = #t_list{a = list(),
-%% name = type(),
+%% name = t_atom(),
%% fields = [field()]}
--record(t_record, {a=[], name, fields = []}). % record type '#r{f1,...,fN}'
+-record(t_record, {a=[], % record "type" '#r{f1,...,fN}'
+ name,
+ fields = []}).
%% @type t_field() = #t_field{a = list(),
%% name = type(),
%% type = type()}
-record(t_field, {a=[], name, type}). % named field 'n1=t1'
+
+%% @type t_paren() = #t_paren{a = list(), type = type()}
+
+-record(t_paren, {a=[], type}). % parentheses
generated by cgit v1.2.3 (git 2.25.1) at 2024-11-09 18:46:08 +0000