diff options
Diffstat (limited to 'lib/edoc')
35 files changed, 1907 insertions, 339 deletions
diff --git a/lib/edoc/Makefile b/lib/edoc/Makefile index e512e390e3..1add669398 100644 --- a/lib/edoc/Makefile +++ b/lib/edoc/Makefile @@ -13,8 +13,6 @@ # Portions created by Ericsson are Copyright 1999, Ericsson Utvecklings # AB. All Rights Reserved.'' # -# $Id$ -# include $(ERL_TOP)/make/target.mk include $(ERL_TOP)/make/$(TARGET)/otp.mk diff --git a/lib/edoc/doc/Makefile b/lib/edoc/doc/Makefile index a0f6484382..c5f68b25d0 100644 --- a/lib/edoc/doc/Makefile +++ b/lib/edoc/doc/Makefile @@ -13,8 +13,6 @@ # Portions created by Ericsson are Copyright 1999, Ericsson Utvecklings # AB. All Rights Reserved.'' # -# $Id: Makefile,v 1.1.1.1 2004/10/04 13:53:33 richardc Exp $ -# include $(ERL_TOP)/make/target.mk include $(ERL_TOP)/make/$(TARGET)/otp.mk diff --git a/lib/edoc/doc/overview.edoc b/lib/edoc/doc/overview.edoc index 9b25c17b1f..2af425272e 100644 --- a/lib/edoc/doc/overview.edoc +++ b/lib/edoc/doc/overview.edoc @@ -3,7 +3,7 @@ EDoc overview page -@author Richard Carlsson <[email protected]> +@author Richard Carlsson <[email protected]> @copyright 2003-2006 Richard Carlsson @version {@version} @title Welcome to 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> @@ -273,12 +277,12 @@ The following tags can be used before a module declaration: Examples: ```%% @author Richard Carlsson''' -```%% @author Richard Carlsson <[email protected]> +```%% @author Richard Carlsson <[email protected]> %% [http://user.it.uu.se/~richardc/]''' -```%% @author <[email protected]>''' +```%% @author <[email protected]>''' -```%% @author [email protected] [http://user.it.uu.se/~richardc/]''' +```%% @author [email protected] [http://user.it.uu.se/~richardc/]''' </dd> <dt><a name="mtag-copyright">`@copyright'</a></dt> @@ -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>"<<>>" + <br/>| "<<" BaseType ">>" + <br/>| "<<" UnitType ">>" + <br/>| "<<" BaseType "," UnitType ">>"</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,12 +1082,13 @@ 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> + <li>`char()' is the subset of `integer()' representing + Unicode character codes: hex 000000-10FFFF.</li> <li>`tuple()' is the set of all tuples `{...}'.</li> - <li>`list(T)' is just an alias for `[T]'.</li> + <li>`list(T)' is just an alias for `[T]'; list() is an alias + for `list(any())', i.e., `[any()]'.</li> <li>`nil()' is an alias for the empty list `[]'.</li> <li>`cons(H,T)' is the list constructor. This is usually not used directly. It is possible to recursively define `list(T) diff --git a/lib/edoc/doc/src/Makefile b/lib/edoc/doc/src/Makefile index 748691d173..b933094464 100644 --- a/lib/edoc/doc/src/Makefile +++ b/lib/edoc/doc/src/Makefile @@ -13,8 +13,6 @@ # Portions created by Ericsson are Copyright 1999, Ericsson Utvecklings # AB. All Rights Reserved.'' # -# $Id$ -# include $(ERL_TOP)/make/target.mk include $(ERL_TOP)/make/$(TARGET)/otp.mk @@ -105,7 +103,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/notes.xml b/lib/edoc/doc/src/notes.xml index 74fa2d3ab6..b220067bbe 100644 --- a/lib/edoc/doc/src/notes.xml +++ b/lib/edoc/doc/src/notes.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2007</year><year>2010</year> + <year>2007</year><year>2011</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -31,6 +31,176 @@ <p>This document describes the changes made to the EDoc application.</p> +<section><title>Edoc 0.7.9</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p><c>no_return</c> is a new built-in type. </p> + <p> + Own Id: OTP-9350</p> + </item> + <item> + <p> + synchronized with edoc development version</p> + <p> + forgot to ensure that xmerl is found in path for + include_lib to work</p> + <p> + fix -spec declaration that doesn't work in R13B04</p> + <p> + eliminate warnings about unused imports</p> + <p> + removed CVS-keywords from source files (Thanks to Richard + Carlsson )</p> + <p> + Own Id: OTP-9463</p> + </item> + <item> + <p> + Add a proplist() type</p> + <p> + Recently I was adding specs to an API and found that + there is no canonical proplist() type defined. (Thanks to + Ryan Zezeski)</p> + <p> + Own Id: OTP-9499</p> + </item> + <item> + <p> + Removed some never-matching clauses reported by dialyzer + Fix macro expansion in comments following Erlang types + URI-escape bytes as two hex digits always (reported by + Alfonso De Gregorio) Updated author e-mail Recognize some + more URI schemas in wiki text, in particular https + (Thanks to Richard Carlsson)</p> + <p> + Own Id: OTP-9590</p> + </item> + </list> + </section> + +</section> + +<section><title>Edoc 0.7.8</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fix infinite loop for malformed edoc input</p> + <p> + When processing an edoc comment with ``` in it, if the + comment ends without a matching ''' then an infinite loop + occurs in the function edoc_wiki:strip_empty_lines/2. + This change fixes that by adding a clause to return from + the function upon the end of the comment input. This + allows an error to be thrown to indicate the problem, + which is the same behaviour as leaving either `` or ` + unmatched. (Thanks to Taylor Venable)</p> + <p> + Own Id: OTP-9165</p> + </item> + <item> + <p> Bugs concerning the option + <c>report_missing_types</c> that was added in EDoc-0.7.7 + have been corrected: the option was misspelled in the + source, and local definitions as well as the function + tags <c>@private</c> and <c>@hidden</c> were not handled + correctly. (Thanks to Manolis Papadakis.) </p> + <p> + Own Id: OTP-9301</p> + </item> + </list> + </section> + +</section> + +<section><title>Edoc 0.7.7</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> Add encoding when parsing Wiki text. EDoc used to + fail on strings such as "���". (Thanks to Richard + Carlsson.) </p> + <p> + Own Id: OTP-9109</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> It is now possible to use Erlang specifications and + types in EDoc documentation. Erlang specifications and + types will be used unless there is also a function + specification (<c>@spec</c>) or a type alias + (<c>@type</c>) with the same name. In the current + implementation the placement of <c>-spec</c> matters: it + should be placed where the <c>@spec</c> would otherwise + have been placed. </p> + <p>Not all Erlang types are included in the + documentation, but only those exported by some + <c>export_type</c> declaration or used by some documented + Erlang specification (<c>-spec</c>). </p> + <p> There is currently no support for overloaded Erlang + specifications. </p> + <p> The syntax definitions of EDoc have been augmented to + cope with most of the Erlang types. (But we recommend + that Erlang types should be used instead.) </p> + <p> <c>edoc:read_source()</c> takes one new option, + <c>report_missing_types</c>. <c>edoc_layout:module()</c> + takes one new option, <c>pretty_printer</c>. </p> + <p> + Own Id: OTP-8525</p> + </item> + <item> + <p> The <c>edoc_lib</c> module is meant to be private, + but since it is referred to from other man pages it has + been included in the OTP documentation. The modifications + introduced in this ticket make all functions private + except those referred to from other pages. </p> + <p> + Own Id: OTP-9110</p> + </item> + </list> + </section> + +</section> + +<section><title>Edoc 0.7.6.8</title> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Compiler warnings were eliminated.</p> + <p> + Own Id: OTP-8855</p> + </item> + </list> + </section> + +</section> + +<section><title>Edoc 0.7.6.7</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p>Edoc now uses the new API functions to <c>inets</c> + instead of the deprecated ones.</p> + <p> + Own Id: OTP-8749</p> + </item> + </list> + </section> + +</section> + <section><title>Edoc 0.7.6.6</title> <section><title>Improvements and New Features</title> 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/include/Makefile b/lib/edoc/include/Makefile index 0533c27567..5b2ad38c9d 100644 --- a/lib/edoc/include/Makefile +++ b/lib/edoc/include/Makefile @@ -13,8 +13,6 @@ # Portions created by Ericsson are Copyright 1999, Ericsson Utvecklings # AB. All Rights Reserved.'' # -# $Id$ -# include $(ERL_TOP)/make/target.mk include $(ERL_TOP)/make/$(TARGET)/otp.mk diff --git a/lib/edoc/include/edoc_doclet.hrl b/lib/edoc/include/edoc_doclet.hrl index a99ff1fbab..60ec7f44e4 100644 --- a/lib/edoc/include/edoc_doclet.hrl +++ b/lib/edoc/include/edoc_doclet.hrl @@ -18,7 +18,7 @@ %% Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 %% USA %% -%% Author contact: [email protected] +%% Author contact: [email protected] %% ===================================================================== -define(NO_APP, []). diff --git a/lib/edoc/priv/edoc_generate.src b/lib/edoc/priv/edoc_generate.src index e87fdbc902..7ec89207b0 100644 --- a/lib/edoc/priv/edoc_generate.src +++ b/lib/edoc/priv/edoc_generate.src @@ -14,9 +14,6 @@ # Portions created by Ericsson are Copyright 1999-2000, Ericsson # Utvecklings AB. All Rights Reserved.'' # -# $Id$ -# -# #EDOC_DIR=/clearcase/otp/internal_tools/edoc EDOC_DIR=/home/otp/sgml/edoc-%EDOC_VSN% diff --git a/lib/edoc/src/Makefile b/lib/edoc/src/Makefile index ca95c4cdad..fcb0b61292 100644 --- a/lib/edoc/src/Makefile +++ b/lib/edoc/src/Makefile @@ -23,13 +23,14 @@ RELSYSDIR = $(RELEASE_PATH)/lib/edoc-$(VSN) EBIN = ../ebin XMERL = ../../xmerl -ERL_COMPILE_FLAGS += -I../include -I$(XMERL)/include +warn_unused_vars +nowarn_shadow_vars +warn_unused_import +warn_deprecated_guard +ERL_COMPILE_FLAGS += -pa $(XMERL) -I../include -I$(XMERL)/include +warn_unused_vars +nowarn_shadow_vars +warn_unused_import +warn_deprecated_guard 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 ec452a5929..544465b14a 100644 --- a/lib/edoc/src/edoc.erl +++ b/lib/edoc/src/edoc.erl @@ -14,10 +14,8 @@ %% Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 %% USA %% -%% $Id$ -%% %% @copyright 2001-2007 Richard Carlsson -%% @author Richard Carlsson <[email protected]> +%% @author Richard Carlsson <[email protected]> %% @version {@version} %% @end %% ===================================================================== @@ -58,7 +56,7 @@ read_comments/1, read_comments/2, read_source/1, read_source/2]). --import(edoc_report, [report/2, report/3, error/1, error/3]). +-compile({no_auto_import,[error/1]}). -include("edoc.hrl"). @@ -177,8 +175,8 @@ application(App, Options) when is_atom(App) -> Dir when is_list(Dir) -> application(App, Dir, Options); _ -> - report("cannot find application directory for '~s'.", - [App]), + edoc_report:report("cannot find application directory for '~s'.", + [App]), exit(error) end. @@ -256,6 +254,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()], @@ -308,13 +307,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 @@ -340,7 +339,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 @@ -576,6 +575,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) -> @@ -583,12 +588,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 @@ -614,7 +613,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'. @@ -640,6 +639,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 @@ -653,8 +659,8 @@ read_source(Name, Opts0) -> check_forms(Forms, Name), Forms; {error, R} -> - error({"error reading file '~s'.", - [edoc_lib:filename(Name)]}), + edoc_report:error({"error reading file '~s'.", + [edoc_lib:filename(Name)]}), exit({error, R}) end. @@ -678,11 +684,10 @@ check_forms(Fs, Name) -> error_marker -> case erl_syntax:error_marker_info(F) of {L, M, D} -> - error(L, Name, {format_error, M, D}); - + edoc_report:error(L, Name, {format_error, M, D}); Other -> - report(Name, "unknown error in " - "source code: ~w.", [Other]) + edoc_report:report(Name, "unknown error in " + "source code: ~w.", [Other]) end, exit(error); _ -> @@ -722,17 +727,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..98debba4ab 100644 --- a/lib/edoc/src/edoc.hrl +++ b/lib/edoc/src/edoc.hrl @@ -18,7 +18,7 @@ %% Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 %% USA %% -%% Author contact: [email protected] +%% Author contact: [email protected] %% ===================================================================== %% Note: Documentation in this file is included by edoc_extract.erl @@ -37,6 +37,7 @@ -define(SOURCE_DIR, "src"). -define(EBIN_DIR, "ebin"). -define(EDOC_DIR, "doc"). +-define(REPORT_MISSING_TYPES, 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..aad0b14371 100644 --- a/lib/edoc/src/edoc_data.erl +++ b/lib/edoc/src/edoc_data.erl @@ -14,13 +14,11 @@ %% Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 %% USA %% -%% $Id$ -%% %% @private %% @copyright 2003 Richard Carlsson -%% @author Richard Carlsson <[email protected]> +%% @author Richard Carlsson <[email protected]> %% @see edoc -%% @end +%% @end %% ===================================================================== %% @doc Building the EDoc external data structure. See the file @@ -30,9 +28,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 +138,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 +306,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..385d20e9ae 100644 --- a/lib/edoc/src/edoc_doclet.erl +++ b/lib/edoc/src/edoc_doclet.erl @@ -14,10 +14,8 @@ %% Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 %% USA %% -%% $Id$ -%% %% @copyright 2003-2006 Richard Carlsson -%% @author Richard Carlsson <[email protected]> +%% @author Richard Carlsson <[email protected]> %% @see edoc %% @end %% ===================================================================== @@ -52,7 +50,7 @@ -define(IMAGE, "erlang.png"). -define(NL, "\n"). --include("xmerl.hrl"). +-include_lib("xmerl/include/xmerl.hrl"). %% Sources is the list of inputs in the order they were found. Packages %% and Modules are sorted lists of atoms without duplicates. (They @@ -76,7 +74,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 +84,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..5a79e127f6 100644 --- a/lib/edoc/src/edoc_extract.erl +++ b/lib/edoc/src/edoc_extract.erl @@ -14,10 +14,8 @@ %% Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 %% USA %% -%% $Id$ -%% %% @copyright 2001-2003 Richard Carlsson -%% @author Richard Carlsson <[email protected]> +%% @author Richard Carlsson <[email protected]> %% @see edoc %% @end %% ===================================================================== @@ -34,10 +32,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 +53,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 +75,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, Env, File), + 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 +111,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, [], Env, File0), + 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 +126,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 +149,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 +197,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 +216,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 @@ -236,8 +236,8 @@ file(File, Context, Env, Opts) -> case file:read_file(File) of {ok, Bin} -> {ok, text(binary_to_list(Bin), Context, Env, Opts, File)}; - {error, _R} = Error -> - Error + {error, _} = Error -> + Error end. @@ -276,7 +276,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. @@ -296,8 +296,8 @@ get_module_info(Forms, File) -> {Name, Vars} = case lists:keyfind(module, 1, L) of {module, N} when is_atom(N) -> {N, none}; - {module, {N, _Vs} = NVs} when is_atom(N) -> - NVs; + {module, {N, _}=Mod} when is_atom(N) -> + Mod; _ -> report(File, "module name missing.", []), exit(error) @@ -351,6 +351,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 +369,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 +495,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 +542,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 +552,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 +598,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 +624,28 @@ 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, Env, File) -> + Tree = erl_recomment:recomment_forms(Forms0, Comments), + Forms = preprocess_forms(Tree), + Env1 = add_macro_defs(edoc_macros:std_macros(Env), [], Env), + F = fun(C, Line) -> find_fun(C, Line, Env1, File) end, + edoc_specs:docs(Forms, F). + +find_fun(C0, Line, Env, File) -> + C1 = comment_text(C0), + Text = lists:append([C#comment.text || C <- C1]), + Comm = #comment{line = Line, text = Text}, + [Tag | _] = scan_tags([Comm]), + [Tag1] = edoc_macros:expand_tags([Tag], Env, File), + Tag1. diff --git a/lib/edoc/src/edoc_layout.erl b/lib/edoc/src/edoc_layout.erl index 900f0b3040..951cec121c 100644 --- a/lib/edoc/src/edoc_layout.erl +++ b/lib/edoc/src/edoc_layout.erl @@ -14,9 +14,7 @@ %% Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 %% USA %% -%% $Id$ -%% -%% @author Richard Carlsson <[email protected]> +%% @author Richard Carlsson <[email protected]> %% @copyright 2001-2006 Richard Carlsson %% @see edoc %% @end @@ -33,7 +31,7 @@ -import(edoc_report, [report/2]). --include("xmerl.hrl"). +-include_lib("xmerl/include/xmerl.hrl"). -define(HTML_EXPORT, xmerl_html). -define(DEFAULT_XML_EXPORT, ?HTML_EXPORT). @@ -49,7 +47,6 @@ -define(FUNCTIONS_TITLE, "Function Details"). -define(FUNCTIONS_LABEL, "functions"). - %% @doc The layout function. %% %% Options to the standard layout: @@ -59,13 +56,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 +100,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 +122,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 +202,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 +228,7 @@ timestamp() -> edoc_lib:timestr(time())]) ]}]}, ?NL]. - + stylesheet(Opts) -> case Opts#opts.stylesheet of undefined -> @@ -335,8 +345,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 +354,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 +362,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 +377,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 +412,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 +442,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(Es, Opts) -> + local_defs(Es, [], Opts). -local_defs([]) -> []; -local_defs(Es) -> +local_defs([], _, _Opts) -> []; +local_defs(Es0, Last, Opts) -> + [E | Es] = lists:reverse(Es0), [?NL, {ul, [{class, "definitions"}], - lists:concat([[{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 +814,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 +848,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 +876,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), [")"])). @@ -812,12 +957,16 @@ local_label(R) -> xhtml(Title, CSS, Body) -> [{html, [?NL, - {head, [?NL, - {title, Title}, - ?NL] ++ CSS}, - ?NL, - {body, [{bgcolor, "white"}], Body}, - ?NL] + {head, [?NL, + {meta, [{'http-equiv',"Content-Type"}, + {content, "text/html; charset=ISO-8859-1"}], + []}, + ?NL, + {title, Title}, + ?NL] ++ CSS}, + ?NL, + {body, [{bgcolor, "white"}], Body}, + ?NL] }, ?NL]. @@ -827,7 +976,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 +1023,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 47e61f7932..7fd8358add 100644 --- a/lib/edoc/src/edoc_lib.erl +++ b/lib/edoc/src/edoc_lib.erl @@ -14,11 +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]> +%% @author Richard Carlsson <[email protected]> %% @see edoc %% @end %% ===================================================================== @@ -41,7 +38,7 @@ -import(edoc_report, [report/2, warning/2]). -include("edoc.hrl"). --include("xmerl.hrl"). +-include_lib("xmerl/include/xmerl.hrl"). -define(FILE_BASE, "/"). @@ -49,14 +46,17 @@ %% --------------------------------------------------------------------- %% List and string utilities +%% @private timestr({H,M,Sec}) -> lists:flatten(io_lib:fwrite("~2.2.0w:~2.2.0w:~2.2.0w",[H,M,Sec])). +%% @private datestr({Y,M,D}) -> Ms = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"], lists:flatten(io_lib:fwrite("~s ~w ~w",[lists:nth(M, Ms),D,Y])). +%% @private count(X, Xs) -> count(X, Xs, 0). @@ -67,6 +67,7 @@ count(X, [_ | Xs], N) -> count(_X, [], N) -> N. +%% @private lines(Cs) -> lines(Cs, [], []). @@ -77,6 +78,7 @@ lines([C | Cs], As, Ls) -> lines([], As, Ls) -> lists:reverse([lists:reverse(As) | Ls]). +%% @private split_at(Cs, K) -> split_at(Cs, K, []). @@ -87,6 +89,7 @@ split_at([C | Cs], K, As) -> split_at([], _K, As) -> {lists:reverse(As), []}. +%% @private split_at_stop(Cs) -> split_at_stop(Cs, []). @@ -103,6 +106,7 @@ split_at_stop([C | Cs], As) -> split_at_stop([], As) -> {lists:reverse(As), []}. +%% @private split_at_space(Cs) -> split_at_space(Cs, []). @@ -117,17 +121,20 @@ split_at_space([C | Cs], As) -> split_at_space([], As) -> {lists:reverse(As), []}. +%% @private is_space([$\s | Cs]) -> is_space(Cs); is_space([$\t | Cs]) -> is_space(Cs); is_space([$\n | Cs]) -> is_space(Cs); is_space([_C | _Cs]) -> false; is_space([]) -> true. +%% @private strip_space([$\s | Cs]) -> strip_space(Cs); strip_space([$\t | Cs]) -> strip_space(Cs); strip_space([$\n | Cs]) -> strip_space(Cs); strip_space(Cs) -> Cs. +%% @private segment(Es, N) -> segment(Es, [], [], 0, N). @@ -140,6 +147,7 @@ segment([], [], Cs, _N, _M) -> segment([], As, Cs, _N, _M) -> lists:reverse([lists:reverse(As) | Cs]). +%% @private transpose([]) -> []; transpose([[] | Xss]) -> transpose(Xss); transpose([[X | Xs] | Xss]) -> @@ -151,6 +159,7 @@ transpose([[X | Xs] | Xss]) -> %% end of the summary sentence only if it is also the last segment in %% the list, or is followed by a 'p' or 'br' ("whitespace") element. +%% @private get_first_sentence([#xmlElement{name = p, content = Es} | _]) -> %% Descend into initial paragraph. get_first_sentence_1(Es); @@ -230,6 +239,7 @@ end_of_sentence_1(_, false, _) -> %% Names must begin with a lowercase letter and contain only %% alphanumerics and underscores. +%% @private is_name([C | Cs]) when C >= $a, C =< $z -> is_name_1(Cs); is_name([C | Cs]) when C >= $\337, C =< $\377, C =/= $\367 -> @@ -252,6 +262,7 @@ is_name_1(_) -> false. to_atom(A) when is_atom(A) -> A; to_atom(S) when is_list(S) -> list_to_atom(S). +%% @private unique([X | Xs]) -> [X | unique(Xs, X)]; unique([]) -> []. @@ -267,6 +278,7 @@ unique([], _) -> []. %% content of <a href="overview-summary.html#ftag-equiv">`@equiv'</a> %% tags, and strings denoting file names, e.g. in @headerfile. Also used %% by {@link edoc_run}. +%% @private parse_expr(S, L) -> case erl_scan:string(S ++ ".", L) of @@ -287,12 +299,15 @@ parse_expr(S, L) -> %% @doc EDoc "contact information" parsing. This is the type of the %% content in e.g. %% <a href="overview-summary.html#mtag-author">`@author'</a> tags. +%% @private -%% @type info() = #info{name = string(), -%% mail = string(), -%% uri = string()} +%% % @type info() = #info{name = string(), +%% % email = string(), +%% % uri = string()} --record(info, {name = "", email = "", uri = ""}). +-record(info, {name = "" :: string(), + email = "" :: string(), + uri = "" :: string()}). parse_contact(S, L) -> I = scan_name(S, L, #info{}, []), @@ -365,6 +380,7 @@ strip_and_reverse(As) -> %% %% TODO: general utf-8 encoding for all of Unicode (0-16#10ffff) +%% @private escape_uri([C | Cs]) when C >= $a, C =< $z -> [C | escape_uri(Cs)]; escape_uri([C | Cs]) when C >= $A, C =< $Z -> @@ -387,8 +403,13 @@ escape_uri([C | Cs]) -> escape_uri([]) -> []. -escape_byte(C) -> - "%" ++ hex_octet(C). +escape_byte(C) when C >= 0, C =< 255 -> + [$%, hex_digit(C bsr 4), hex_digit(C band 15)]. + +hex_digit(N) when N >= 0, N =< 9 -> + N + $0; +hex_digit(N) when N > 9, N =< 15 -> + N + $a - 10. % utf8([C | Cs]) when C > 16#7f -> % [((C band 16#c0) bsr 6) + 16#c0, C band 16#3f ++ 16#80 | utf8(Cs)]; @@ -397,16 +418,10 @@ escape_byte(C) -> % utf8([]) -> % []. -hex_octet(N) when N =< 9 -> - [$0 + N]; -hex_octet(N) when N > 15 -> - hex_octet(N bsr 4) ++ hex_octet(N band 15); -hex_octet(N) -> - [N - 10 + $a]. - %% Please note that URI are *not* file names. Don't use the stdlib %% 'filename' module for operations on (any parts of) URI. +%% @private join_uri(Base, "") -> Base; join_uri("", Path) -> @@ -416,6 +431,7 @@ join_uri(Base, Path) -> %% Check for relative URI; "network paths" ("//...") not included! +%% @private is_relative_uri([$: | _]) -> false; is_relative_uri([$/, $/ | _]) -> @@ -431,6 +447,7 @@ is_relative_uri([_ | Cs]) -> is_relative_uri([]) -> true. +%% @private uri_get("file:///" ++ Path) -> uri_get_file(Path); uri_get("file://localhost/" ++ Path) -> @@ -472,8 +489,8 @@ uri_get_file(File0) -> uri_get_http(URI) -> %% Try using option full_result=false - case catch {ok, http:request(get, {URI,[]}, [], - [{full_result, false}])} of + case catch {ok, httpc:request(get, {URI,[]}, [], + [{full_result, false}])} of {'EXIT', _} -> uri_get_http_r10(URI); Result -> @@ -482,7 +499,7 @@ uri_get_http(URI) -> uri_get_http_r10(URI) -> %% Try most general form of request - Result = (catch {ok, http:request(get, {URI,[]}, [], [])}), + Result = (catch {ok, httpc:request(get, {URI,[]}, [], [])}), uri_get_http_1(Result, URI). uri_get_http_1(Result, URI) -> @@ -530,6 +547,7 @@ uri_get_ftp(URI) -> Msg = io_lib:format("cannot access ftp scheme yet: '~s'.", [URI]), {error, Msg}. +%% @private to_label([$\s | Cs]) -> to_label(Cs); to_label([$\t | Cs]) -> @@ -562,6 +580,7 @@ to_label_2(Cs) -> %% --------------------------------------------------------------------- %% Files +%% @private filename([C | T]) when is_integer(C), C > 0 -> [C | filename(T)]; filename([H|T]) -> @@ -574,6 +593,7 @@ filename(N) -> report("bad filename: `~P'.", [N, 25]), exit(error). +%% @private copy_file(From, To) -> case file:copy(From, To) of {ok, _} -> ok; @@ -598,6 +618,7 @@ list_dir(Dir, Error) -> F("could not read directory '~s': ~s.", [filename(Dir), R1]) end. +%% @private simplify_path(P) -> case filename:basename(P) of "." -> @@ -634,6 +655,7 @@ simplify_path(P) -> %% exit(error) %% end. +%% @private try_subdir(Dir, Subdir) -> D = filename:join(Dir, Subdir), case filelib:is_dir(D) of @@ -646,6 +668,7 @@ try_subdir(Dir, Subdir) -> %% %% @doc Write the given `Text' to the file named by `Name' in directory %% `Dir'. If the target directory does not exist, it will be created. +%% @private write_file(Text, Dir, Name) -> write_file(Text, Dir, Name, ''). @@ -655,6 +678,7 @@ write_file(Text, Dir, Name) -> %% Name::edoc:filename(), Package::atom()|string()) -> ok %% @doc Like {@link write_file/3}, but adds path components to the target %% directory corresponding to the specified package. +%% @private write_file(Text, Dir, Name, Package) -> Dir1 = filename:join([Dir | packages:split(Package)]), @@ -670,6 +694,7 @@ write_file(Text, Dir, Name, Package) -> exit(error) end. +%% @private write_info_file(App, Packages, Modules, Dir) -> Ts = [{packages, Packages}, {modules, Modules}], @@ -701,6 +726,7 @@ info_file_data(Ts) -> %% Local file access - don't complain if file does not exist. +%% @private read_info_file(Dir) -> File = filename:join(Dir, ?INFO_FILE), case filelib:is_file(File) of @@ -767,11 +793,13 @@ parse_terms_1([], _As, _Vs) -> %% --------------------------------------------------------------------- %% Source files and packages +%% @private find_sources(Path, Opts) -> find_sources(Path, "", Opts). %% @doc See {@link edoc:run/3} for a description of the options %% `subpackages', `source_suffix' and `exclude_packages'. +%% @private %% NEW-OPTIONS: subpackages, source_suffix, exclude_packages %% DEFER-OPTIONS: edoc:run/3 @@ -825,6 +853,7 @@ is_package_dir(Name, Dir) -> is_name(filename:rootname(filename:basename(Name))) andalso filelib:is_dir(filename:join(Dir, Name)). +%% @private find_file([P | Ps], Pkg, Name) -> Dir = filename:join(P, filename:join(packages:split(Pkg))), File = filename:join(Dir, Name), @@ -837,6 +866,7 @@ find_file([P | Ps], Pkg, Name) -> find_file([], _Pkg, _Name) -> "". +%% @private find_doc_dirs() -> find_doc_dirs(code:get_path()). @@ -902,6 +932,7 @@ add_new(K, V, D) -> %% @spec (Options::proplist()) -> edoc_env() %% @equiv get_doc_env([], [], [], Opts) +%% @private get_doc_env(Opts) -> get_doc_env([], [], [], Opts). @@ -912,6 +943,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. %% @@ -950,6 +982,7 @@ get_doc_env(App, Packages, Modules, Opts) -> %% NEW-OPTIONS: doclet %% DEFER-OPTIONS: edoc:run/3 +%% @private run_doclet(Fun, Opts) -> run_plugin(doclet, ?DEFAULT_DOCLET, Fun, Opts). @@ -959,6 +992,7 @@ run_doclet(Fun, Opts) -> %% NEW-OPTIONS: layout %% DEFER-OPTIONS: edoc:layout/2 +%% @private run_layout(Fun, Opts) -> run_plugin(layout, ?DEFAULT_LAYOUT, Fun, Opts). @@ -988,6 +1022,14 @@ get_plugin(Key, Default, Opts) -> %% --------------------------------------------------------------------- %% Error handling +-type line() :: erl_scan:line(). +-type err() :: 'eof' + | {'missing', char()} + | {line(), atom(), string()} + | string(). + +-spec throw_error(err(), line()) -> no_return(). + throw_error({missing, C}, L) -> throw_error({"missing '~c'.", [C]}, L); throw_error(eof, L) -> diff --git a/lib/edoc/src/edoc_macros.erl b/lib/edoc/src/edoc_macros.erl index 2874e2940c..70fb38bf0a 100644 --- a/lib/edoc/src/edoc_macros.erl +++ b/lib/edoc/src/edoc_macros.erl @@ -14,11 +14,9 @@ %% Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 %% USA %% -%% $Id$ -%% %% @private %% @copyright 2001-2005 Richard Carlsson -%% @author Richard Carlsson <[email protected]> +%% @author Richard Carlsson <[email protected]> %% @see edoc %% @end %% ===================================================================== @@ -317,6 +315,14 @@ macro_content([C | Cs], As, L, N) -> macro_content([], _As, _L, _N) -> throw('end'). +-type line() :: erl_scan:line(). +-type err() :: 'unterminated_macro' + | 'macro_name' + | {'macro_name', string()} + | {string(), [string()]}. + +-spec throw_error(line(), err()) -> no_return(). + throw_error(L, unterminated_macro) -> throw_error(L, {"unexpected end of macro.", []}); throw_error(L, macro_name) -> diff --git a/lib/edoc/src/edoc_parser.yrl b/lib/edoc/src/edoc_parser.yrl index 0eea8ae66f..4d6428f75b 100644 --- a/lib/edoc/src/edoc_parser.yrl +++ b/lib/edoc/src/edoc_parser.yrl @@ -22,23 +22,21 @@ %% Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 %% USA %% -%% Author contact: [email protected] -%% -%% $Id$ -%% +%% Author contact: [email protected] %% ===================================================================== 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 +50,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 +64,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 +90,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 +116,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 +163,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 +187,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 +229,7 @@ etype -> utype: '$1'. throws -> etype where_defs: #t_throws{type = '$1', - defs = lists:reverse('$2')}. + defs = '$2'}. %% (commented out for now) %% Header @@ -221,7 +255,7 @@ throws -> etype where_defs: %% "%% USA" %% "%%" %% "%% @private" -%% "%% @author Richard Carlsson <[email protected]>" +%% "%% @author Richard Carlsson <[email protected]>" %% "%% ====================================================================" %% . @@ -297,7 +331,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 @@ -310,10 +359,10 @@ parse_spec(S, L) -> {ok, Spec} -> Spec; {error, E} -> - throw_error(E, L) + throw_error({parse_spec, E}, L) end; {error, E, _} -> - throw_error(E, L) + throw_error({parse_spec, E}, L) end. %% --------------------------------------------------------------------- @@ -379,7 +428,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. @@ -404,8 +453,8 @@ parse_throws(S, L) -> %% --------------------------------------------------------------------- -throw_error({L, M, D}, _L0) -> - throw({error,L,{format_error,M,D}}); +-spec throw_error(term(), erl_scan:line()) -> no_return(). + throw_error({parse_spec, E}, L) -> throw_error({"specification", E}, L); throw_error({parse_typedef, E}, L) -> @@ -417,7 +466,4 @@ throw_error({parse_throws, E}, L) -> throw_error(parse_param, L) -> throw({error, L, "missing parameter name"}); throw_error({Where, E}, L) when is_list(Where) -> - throw({error,L,{"unknown error parsing ~s: ~P.",[Where,E,15]}}); -throw_error(E, L) -> - %% Just in case. - throw({error,L,{"unknown parse error: ~P.",[E,15]}}). + throw({error,L,{"unknown error parsing ~s: ~P.",[Where,E,15]}}). diff --git a/lib/edoc/src/edoc_refs.erl b/lib/edoc/src/edoc_refs.erl index c2146bbe02..1f578a3b83 100644 --- a/lib/edoc/src/edoc_refs.erl +++ b/lib/edoc/src/edoc_refs.erl @@ -14,14 +14,12 @@ %% Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 %% USA %% -%% $Id$ -%% %% @private %% @copyright 2003 Richard Carlsson -%% @author Richard Carlsson <[email protected]> +%% @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_report.erl b/lib/edoc/src/edoc_report.erl index b87c58dde3..9bec08ab97 100644 --- a/lib/edoc/src/edoc_report.erl +++ b/lib/edoc/src/edoc_report.erl @@ -14,11 +14,9 @@ %% Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 %% USA %% -%% $Id$ -%% %% @private %% @copyright 2001-2003 Richard Carlsson -%% @author Richard Carlsson <[email protected]> +%% @author Richard Carlsson <[email protected]> %% @see edoc %% @end %% ===================================================================== @@ -27,6 +25,8 @@ -module(edoc_report). +%% Avoid warning for local function error/2 clashing with autoimported BIF. +-compile({no_auto_import,[error/2]}). -export([error/1, error/2, error/3, diff --git a/lib/edoc/src/edoc_run.erl b/lib/edoc/src/edoc_run.erl index 37025d6621..48b6137ac1 100644 --- a/lib/edoc/src/edoc_run.erl +++ b/lib/edoc/src/edoc_run.erl @@ -14,10 +14,8 @@ %% Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 %% USA %% -%% $Id$ -%% %% @copyright 2003 Richard Carlsson -%% @author Richard Carlsson <[email protected]> +%% @author Richard Carlsson <[email protected]> %% @see edoc %% @end %% ===================================================================== @@ -42,6 +40,8 @@ -export([file/1, application/1, packages/1, files/1, toc/1]). +-compile({no_auto_import,[error/1]}). + -import(edoc_report, [report/2, error/1]). diff --git a/lib/edoc/src/edoc_scanner.erl b/lib/edoc/src/edoc_scanner.erl index d3dff64682..754fcef643 100644 --- a/lib/edoc/src/edoc_scanner.erl +++ b/lib/edoc/src/edoc_scanner.erl @@ -3,24 +3,22 @@ %% 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$ -%% %% @private %% @copyright Richard Carlsson 2001-2003. Portions created by Ericsson %% are Copyright 1999, Ericsson Utvecklings AB. All Rights Reserved. -%% @author Richard Carlsson <[email protected]> +%% @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 +137,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 +164,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 +324,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..5acf8ac0d5 --- /dev/null +++ b/lib/edoc/src/edoc_specs.erl @@ -0,0 +1,601 @@ +%% +%% %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 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 :: fun( ([syntaxTree()], Line :: term()) -> #tag{} )) + -> dict(). + +%% @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::proplists: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({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_types, Opts, + ?REPORT_MISSING_TYPES) =:= 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 1f2cb99c75..2d986988c2 100644 --- a/lib/edoc/src/edoc_tags.erl +++ b/lib/edoc/src/edoc_tags.erl @@ -14,11 +14,9 @@ %% Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 %% USA %% -%% $Id$ -%% %% @private %% @copyright 2001-2003 Richard Carlsson -%% @author Richard Carlsson <[email protected]> +%% @author Richard Carlsson <[email protected]> %% @see edoc %% @end %% ===================================================================== @@ -31,7 +29,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 +200,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 +213,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,16 +323,32 @@ 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. +-type line() :: erl_scan:line(). + +-spec parse_file(_, line(), _, _) -> no_return(). + parse_file(Data, Line, Env, _Where) -> case edoc_lib:parse_expr(Data, Line) of {string, _, File0} -> @@ -344,6 +363,8 @@ parse_file(Data, Line, Env, _Where) -> throw_error(Line, file_not_string) end. +-spec parse_header(_, line(), _, _) -> no_return(). + parse_header(Data, Line, Env, {Where, _}) -> parse_header(Data, Line, Env, Where); parse_header(Data, Line, Env, Where) when is_list(Where) -> @@ -362,6 +383,13 @@ parse_header(Data, Line, Env, Where) when is_list(Where) -> throw_error(Line, file_not_string) end. +-type err() :: 'file_not_string' + | {'file_not_found', file:filename()} + | {'read_file', file:filename(), term()} + | string(). + +-spec throw_error(line(), err()) -> no_return(). + throw_error(L, {read_file, File, R}) -> throw_error(L, {"error reading file '~s': ~w", [edoc_lib:filename(File), R]}); @@ -371,3 +399,115 @@ 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(Entries, Opts, File) -> + Tags = edoc_data:get_all_tags(Entries), + TypeTags = [Tag || #tag{data = {#t_typedef{},_}}=Tag <- Tags], + Entries2 = edoc_data:hidden_filter(Entries, Opts), + Tags2 = edoc_data:get_all_tags(Entries2), + SpecTags = [Tag || #tag{data = #t_spec{}}=Tag <- Tags2], + DT = ets:new(types, [bag]), + _ = [add_type(DT, Name, As, File, Line) || + #tag{line = Line, + data = {#t_typedef{name = Name, args = As},_}} <- TypeTags], + Warn = proplists:get_value(report_missing_types, Opts, + ?REPORT_MISSING_TYPES) =:= true, + P = #parms{tab = DT, warn = Warn, file = File, line = 0}, + try check_types3(TypeTags++SpecTags, 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_types3([], _P, _Ls)-> + ok; +check_types3([Tag | Tags], P, Ls) -> + check_type(Tag, P, Ls, Tags). + +check_type(#tag{line = L, data = Data}, P0, Ls, Ts) -> + P = P0#parms{line = L}, + case Data of + {#t_typedef{type = Type, defs = Defs},_} -> + check_type(Type, P, Ls, Defs++Ts); + #t_spec{type = Type, defs = Defs} -> + LocalTypes = + [{N,length(Args)} || + #t_def{name = #t_type{name = N, args = Args}} <- Defs], + check_type(Type, P, LocalTypes, Defs), + check_types3(Ts, P, Ls); + _-> + check_types3(Ts, P0, Ls) + end; +check_type(#t_def{type = Type}, P, Ls, Ts) -> + check_type(Type, P, Ls, Ts); +check_type(#t_type{name = Name, args = Args}, P, Ls, Ts) -> + check_used_type(Name, Args, P, Ls), + check_types3(Args++Ts, P, Ls); +check_type(#t_var{}, P, Ls, Ts) -> + check_types3(Ts, P, Ls); +check_type(#t_fun{args = Args, range = Range}, P, Ls, Ts) -> + check_type(Range, P, Ls, Args++Ts); +check_type(#t_tuple{types = Types}, P, Ls, Ts) -> + check_types3(Types ++Ts, P, Ls); +check_type(#t_list{type = Type}, P, Ls, Ts) -> + check_type(Type, P, Ls, Ts); +check_type(#t_nil{}, P, Ls, Ts) -> + check_types3(Ts, P, Ls); +check_type(#t_paren{type = Type}, P, Ls, Ts) -> + check_type(Type, P, Ls, Ts); +check_type(#t_nonempty_list{type = Type}, P, Ls, Ts) -> + check_type(Type, P, Ls, Ts); +check_type(#t_atom{}, P, Ls, Ts) -> + check_types3(Ts, P, Ls); +check_type(#t_integer{}, P, Ls, Ts) -> + check_types3(Ts, P, Ls); +check_type(#t_integer_range{}, P, Ls, Ts) -> + check_types3(Ts, P, Ls); +check_type(#t_binary{}, P, Ls, Ts) -> + check_types3(Ts, P, Ls); +check_type(#t_float{}, P, Ls, Ts) -> + check_types3(Ts, P, Ls); +check_type(#t_union{types = Types}, P, Ls, Ts) -> + check_types3(Types++Ts, P, Ls); +check_type(#t_record{fields = Fields}, P, Ls, Ts) -> + check_types3(Fields++Ts, P, Ls); +check_type(#t_field{type = Type}, P, Ls, Ts) -> + check_type(Type, P, Ls, Ts); +check_type(undefined, P, Ls, Ts) -> + check_types3(Ts, P, Ls). + +check_used_type(#t_name{name = N, module = Mod}=Name, Args, P, LocalTypes) -> + 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) + orelse lists:member(TypeName, LocalTypes) + 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 85c9ee6f2a..60c6cecb97 100644 --- a/lib/edoc/src/edoc_types.erl +++ b/lib/edoc/src/edoc_types.erl @@ -14,11 +14,9 @@ %% Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 %% USA %% -%% $Id$ -%% %% @private %% @copyright 2001-2003 Richard Carlsson -%% @author Richard Carlsson <[email protected]> +%% @author Richard Carlsson <[email protected]> %% @see edoc %% @end %% ===================================================================== @@ -27,36 +25,74 @@ -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" -include("edoc_types.hrl"). --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. +-include_lib("xmerl/include/xmerl.hrl"). + + +is_predefined(any, 0) -> true; +is_predefined(atom, 0) -> true; +is_predefined(binary, 0) -> true; +is_predefined(bool, 0) -> true; % kept for backwards compatibility +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(no_return, 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); @@ -91,7 +127,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, @@ -109,14 +147,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..05c61d70ff 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 @@ -18,7 +18,7 @@ %% Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 %% USA %% -%% Author contact: [email protected] +%% Author contact: [email protected] %% ===================================================================== %% Type specification data structures @@ -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 diff --git a/lib/edoc/src/edoc_wiki.erl b/lib/edoc/src/edoc_wiki.erl index e4a3d74734..5c71658af5 100644 --- a/lib/edoc/src/edoc_wiki.erl +++ b/lib/edoc/src/edoc_wiki.erl @@ -14,11 +14,9 @@ %% Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 %% USA %% -%% $Id$ -%% %% @private %% @copyright 2001-2003 Richard Carlsson -%% @author Richard Carlsson <[email protected]> +%% @author Richard Carlsson <[email protected]> %% @see edoc %% @end %% ===================================================================== @@ -70,7 +68,7 @@ -export([parse_xml/2, expand_text/2]). -include("edoc.hrl"). --include("xmerl.hrl"). +-include_lib("xmerl/include/xmerl.hrl"). -define(BASE_HEADING, 3). @@ -82,7 +80,8 @@ parse_xml(Data, Line) -> parse_xml_1(Text, Line) -> Text1 = "<doc>" ++ Text ++ "</doc>", - case catch {ok, xmerl_scan:string(Text1, [{line, Line}])} of + Opts = [{line, Line}, {encoding, 'iso-8859-1'}], + case catch {ok, xmerl_scan:string(Text1, Opts)} of {ok, {E, _}} -> E#xmlElement.content; {'EXIT', {fatal, {Reason, L, _C}}} -> @@ -250,10 +249,20 @@ expand_triple([], L, _, L0) -> expand_uri("http:/" ++ Cs, L, As) -> expand_uri(Cs, L, "/:ptth", As); +expand_uri("https:/" ++ Cs, L, As) -> + expand_uri(Cs, L, "/:sptth", As); expand_uri("ftp:/" ++ Cs, L, As) -> expand_uri(Cs, L, "/:ptf", As); expand_uri("file:/" ++ Cs, L, As) -> expand_uri(Cs, L, "/:elif", As); +expand_uri("mailto:/" ++ Cs, L, As) -> + expand_uri(Cs, L, "/:otliam", As); +expand_uri("nfs:/" ++ Cs, L, As) -> + expand_uri(Cs, L, "/:sfn", As); +expand_uri("shttp:/" ++ Cs, L, As) -> + expand_uri(Cs, L, "/:ptths", As); +expand_uri("xmpp:/" ++ Cs, L, As) -> + expand_uri(Cs, L, "/:ppmx", As); expand_uri(Cs, L, As) -> expand(Cs, L, [$[ | As]). @@ -295,6 +304,8 @@ push_uri(Us, Ss, As) -> strip_empty_lines(Cs) -> strip_empty_lines(Cs, 0). +strip_empty_lines([], N) -> + {[], N}; % reached the end of input strip_empty_lines(Cs, N) -> {Cs1, Cs2} = edoc_lib:split_at(Cs, $\n), case edoc_lib:is_space(Cs1) of @@ -357,10 +368,7 @@ par_text(Cs, As, Bs, E, Es) -> [] -> Bs; _ -> [#xmlElement{name = p, content = Es1} | Bs] end, - Bs1 = case Ss of - [] -> Bs0; - _ -> [#xmlText{value = Ss} | Bs0] - end, + Bs1 = [#xmlText{value = Ss} | Bs0], case Cs2 of [] -> par(Es, [], Bs1); diff --git a/lib/edoc/src/otpsgml_layout.erl b/lib/edoc/src/otpsgml_layout.erl index 45f74b299e..2c4cd919bb 100644 --- a/lib/edoc/src/otpsgml_layout.erl +++ b/lib/edoc/src/otpsgml_layout.erl @@ -14,9 +14,7 @@ %% Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 %% USA %% -%% $Id$ -%% -%% @author Richard Carlsson <[email protected]> +%% @author Richard Carlsson <[email protected]> %% @author Kenneth Lundin <[email protected]> %% @copyright 2001-2004 Richard Carlsson %% @see edoc_layout @@ -34,7 +32,7 @@ -import(edoc_report, [report/2]). --include("xmerl.hrl"). +-include_lib("xmerl/include/xmerl.hrl"). -define(SGML_EXPORT, xmerl_otpsgml). -define(DEFAULT_XML_EXPORT, ?SGML_EXPORT). diff --git a/lib/edoc/test/Makefile b/lib/edoc/test/Makefile index 4ce9799f6d..2dbdb77eff 100644 --- a/lib/edoc/test/Makefile +++ b/lib/edoc/test/Makefile @@ -59,8 +59,8 @@ release_spec: opt release_tests_spec: make_emakefile $(INSTALL_DIR) $(RELSYSDIR) $(INSTALL_DATA) $(EMAKEFILE) $(ERL_FILES) $(RELSYSDIR) - $(INSTALL_DATA) edoc.spec $(RELSYSDIR) - chmod -f -R u+w $(RELSYSDIR) + $(INSTALL_DATA) edoc.spec edoc.cover $(RELSYSDIR) + chmod -R u+w $(RELSYSDIR) @tar cf - *_SUITE_data | (cd $(RELSYSDIR); tar xf -) release_docs_spec: diff --git a/lib/edoc/test/edoc.cover b/lib/edoc/test/edoc.cover new file mode 100644 index 0000000000..50140fafde --- /dev/null +++ b/lib/edoc/test/edoc.cover @@ -0,0 +1,2 @@ +{incl_app,edoc,details}. + diff --git a/lib/edoc/test/edoc.spec b/lib/edoc/test/edoc.spec index 8443a28028..8371427270 100644 --- a/lib/edoc/test/edoc.spec +++ b/lib/edoc/test/edoc.spec @@ -1 +1 @@ -{topcase, {dir, "../edoc_test"}}. +{suites,"../edoc_test",all}. diff --git a/lib/edoc/test/edoc_SUITE.erl b/lib/edoc/test/edoc_SUITE.erl index ea833f89b2..5b95c35756 100644 --- a/lib/edoc/test/edoc_SUITE.erl +++ b/lib/edoc/test/edoc_SUITE.erl @@ -13,21 +13,38 @@ %% Portions created by Ericsson are Copyright 1999, Ericsson Utvecklings %% AB. All Rights Reserved.'' %% -%% $Id$ -%% -module(edoc_SUITE). --include("test_server.hrl"). +-include_lib("test_server/include/test_server.hrl"). %% Test server specific exports --export([all/1]). +-export([all/0, suite/0,groups/0,init_per_suite/1, end_per_suite/1, + init_per_group/2,end_per_group/2]). %% Test cases -export([build_std/1]). -all(suite) -> +suite() -> [{ct_hooks,[ts_install_cth]}]. + +all() -> [build_std]. +groups() -> + []. + +init_per_suite(Config) -> + Config. + +end_per_suite(_Config) -> + ok. + +init_per_group(_GroupName, Config) -> + Config. + +end_per_group(_GroupName, Config) -> + Config. + + build_std(suite) -> []; build_std(doc) -> diff --git a/lib/edoc/vsn.mk b/lib/edoc/vsn.mk index 2de2641b4a..22f225dd9b 100644 --- a/lib/edoc/vsn.mk +++ b/lib/edoc/vsn.mk @@ -1 +1 @@ -EDOC_VSN = 0.7.6.6 +EDOC_VSN = 0.7.9 |