From 8052b98f596db048467c0c57cbaac1d3a27687ad Mon Sep 17 00:00:00 2001
From: Hans Bolinder <hasse@erlang.org>
Date: Tue, 22 Jun 2010 09:42:44 +0200
Subject: Make Erlang specifications and types available in EDoc

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 (@spec) or a type alias (@type)
with the same name. In the current implementation the placement of
-spec matters: it should be placed where the @spec would otherwise
have been placed.

Not all Erlang types are included in the documentation, but only those
exported by some export_type declaration or used by some documented
Erlang specification (-spec).

There is currently no support for overloaded Erlang specifications.

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.)

edoc:read_source() takes one new option, report_missing_types.
edoc_layout:module() takes one new option, pretty_printer.
---
 lib/edoc/src/edoc.erl | 34 +++++++++++++++++++++-------------
 1 file changed, 21 insertions(+), 13 deletions(-)

(limited to 'lib/edoc/src/edoc.erl')

diff --git a/lib/edoc/src/edoc.erl b/lib/edoc/src/edoc.erl
index 75b3bb451a..360f2dbc9e 100644
--- a/lib/edoc/src/edoc.erl
+++ b/lib/edoc/src/edoc.erl
@@ -258,6 +258,7 @@ opt_defaults() ->
 opt_negations() ->
     [{no_preprocess, preprocess},
      {no_subpackages, subpackages},
+     {no_report_missing_types, report_missing_types},
      {no_packages, packages}].
 
 %% @spec run(Packages::[package()],
@@ -310,13 +311,13 @@ opt_negations() ->
 %%  <dd>Specifies the suffix used for output files. The default value is
 %%      `".html"'. Note that this also affects generated references.
 %%  </dd>
-%%  <dt>{@type {new, bool()@}}
+%%  <dt>{@type {new, boolean()@}}
 %%  </dt>
 %%  <dd>If the value is `true', any existing `edoc-info' file in the
 %%      target directory will be ignored and overwritten. The default
 %%      value is `false'.
 %%  </dd>
-%%  <dt>{@type {packages, bool()@}}
+%%  <dt>{@type {packages, boolean()@}}
 %%  </dt>
 %%  <dd>If the value is `true', it it assumed that packages (module
 %%      namespaces) are being used, and that the source code directory
@@ -342,7 +343,7 @@ opt_negations() ->
 %%  <dd>Specifies the expected suffix of input files. The default
 %%      value is `".erl"'.
 %%  </dd>
-%%  <dt>{@type {subpackages, bool()@}}
+%%  <dt>{@type {subpackages, boolean()@}}
 %%  </dt>
 %%  <dd>If the value is `true', all subpackages of specified packages
 %%      will also be included in the documentation. The default value is
@@ -578,6 +579,12 @@ layout(Doc, Opts) ->
 
 
 %% @spec (File) ->  [comment()]
+%% @type comment() = {Line, Column, Indentation, Text}
+%% where
+%%   Line = integer(),
+%%   Column = integer(),
+%%   Indentation = integer(),
+%%   Text = [string()]
 %% @equiv read_comments(File, [])
 
 read_comments(File) ->
@@ -585,12 +592,6 @@ read_comments(File) ->
 
 %% @spec read_comments(File::filename(), Options::proplist()) ->
 %%           [comment()]
-%% where
-%%   comment() = {Line, Column, Indentation, Text},
-%%   Line = integer(),
-%%   Column = integer(),
-%%   Indentation = integer(),
-%%   Text = [string()]
 %%
 %% @doc Extracts comments from an Erlang source code file. See the
 %% module {@link //syntax_tools/erl_comment_scan} for details on the
@@ -616,7 +617,7 @@ read_source(Name) ->
 %%
 %% Options:
 %% <dl>
-%%  <dt>{@type {preprocess, bool()@}}
+%%  <dt>{@type {preprocess, boolean()@}}
 %%  </dt>
 %%  <dd>If the value is `true', the source file will be read via the
 %%      Erlang preprocessor (`epp'). The default value is `false'.
@@ -642,6 +643,13 @@ read_source(Name) ->
 %%      macro definitions, used if the `preprocess' option is turned on.
 %%      The default value is the empty list.</dd>
 %% </dl>
+%%  <dt>{@type {report_missing_types, boolean()@}}
+%%  </dt>
+%%  <dd>If the value is `true', warnings are issued for missing types.
+%%      The default value is `false'.
+%%      `no_report_missing_types' is an alias for
+%%      `{report_missing_types, false}'.
+%%  </dd>
 %%
 %% @see get_doc/2
 %% @see //syntax_tools/erl_syntax
@@ -724,17 +732,17 @@ get_doc(File) ->
 %%    <a href="overview-summary.html#Macro_expansion">Inline macro expansion</a>
 %%    for details.
 %%  </dd>
-%%  <dt>{@type {hidden, bool()@}}
+%%  <dt>{@type {hidden, boolean()@}}
 %%  </dt>
 %%  <dd>If the value is `true', documentation of hidden functions will
 %%      also be included. The default value is `false'.
 %%  </dd>
-%%  <dt>{@type {private, bool()@}}
+%%  <dt>{@type {private, boolean()@}}
 %%  </dt>
 %%  <dd>If the value is `true', documentation of private functions will
 %%      also be included. The default value is `false'.
 %%  </dd>
-%%  <dt>{@type {todo, bool()@}}
+%%  <dt>{@type {todo, boolean()@}}
 %%  </dt>
 %%  <dd>If the value is `true', To-Do notes written using `@todo' or
 %%  `@TODO' tags will be included in the documentation. The default
-- 
cgit v1.2.3