From 8052b98f596db048467c0c57cbaac1d3a27687ad Mon Sep 17 00:00:00 2001 From: Hans Bolinder 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/doc/overview.edoc | 103 ++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 97 insertions(+), 6 deletions(-) (limited to 'lib/edoc/doc/overview.edoc') diff --git a/lib/edoc/doc/overview.edoc b/lib/edoc/doc/overview.edoc index 9b25c17b1f..bd603b7a13 100644 --- a/lib/edoc/doc/overview.edoc +++ b/lib/edoc/doc/overview.edoc @@ -205,8 +205,12 @@ The following tags can be used anywhere within a module: the text. See {@section Type specifications} for syntax and examples. All data type descriptions are placed in a separate section of - the documentation, regardless of where the tags occur. + 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. @@ -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. + 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.
`@throws'
Specifies which types of terms may be thrown by the @@ -763,6 +772,17 @@ following escape sequences may be used:
=== Function specifications === +Although the syntax described in the following can still be used +for specifying functions we recommend that Erlang specifications as +described in Types +and Function Specification should be added to the source +code instead. This way the analyses of Dialyzer'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. + + 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,15 +838,50 @@ not as `(atom()) -> (atom() | integer())'.
| Atom
| Integer
| Float +
| Integer ".." Integer
| FunType +
| "fun(" FunType ")" +
| "fun(...)"
| "{" UnionTypes? "}" +
| "#" Atom "{" Fields? "}"
| "[" "]"
| "[" UnionType "]" +
| "[" UnionType "," "..." "]"
| "(" UnionType ")" +
| BinType
| TypeName "(" UnionTypes? ")"
| ModuleName ":" TypeName "(" UnionTypes? ")"
| "//" AppName "/" ModuleName ":" TypeName "(" UnionTypes? ")" + + Fields + ::= + Field +
| Fields "," Fields + + + Field + ::= + Atom "=" UnionList + + + BinType + ::= + "<<>>" +
| "<<" BaseType ">>" +
| "<<" UnitType ">>" +
| "<<" BaseType "," UnitType ">>" + + + BaseType + ::= + "_" ":" Integer + + + UnitType + ::= + "_" ":" "_" "*" Integer + TypeVariable ::= @@ -858,7 +913,7 @@ not as `(atom()) -> (atom() | integer())'. Def ::= - TypeVariable "=" UnionType + TypeVariable "=" UnionList
| TypeName "(" TypeVariables? ")" "=" UnionType @@ -872,6 +927,9 @@ not as `(atom()) -> (atom() | integer())'. Examples: +``` + -spec my_function(X :: integer()) -> integer(). + %% @doc Creates ...''' ``` %% @spec my_function(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 type variables @@ -930,6 +990,13 @@ contain any annotations at all. === Type definitions === +Although the syntax described in the following can still be used +for specifying types we recommend that Erlang types as described in + Types and Function +Specification should be added to the source code instead. +Erlang types will be used unless there is a type alias with the same +name. + The following grammar (see above for auxiliary definitions) describes the form of the definitions that may follow a `@type' tag: @@ -939,13 +1006,18 @@ the form of the definitions that may follow a `@type' tag: Typedef ::= TypeName "(" TypeVariables? ")" DefList? -
| TypeName "(" TypeVariables? ")" "=" UnionType DefList? +
| TypeName "(" TypeVariables? ")" "=" UnionList DefList? (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 ...''' ``` @@ -955,6 +1027,7 @@ definition may be followed by additional local definitions. Examples: %% A = term(). %% A kind of wrapper type thingy.''' +The first two examples show the recommended way of specifying types. === Pre-defined data types === @@ -962,24 +1035,42 @@ The following data types are predefined by EDoc, and may not be redefined: ``` any() + arity() atom() binary() - bool() + bitstring() + bool() (allowed, but use boolean() instead) + boolean() + byte() char() cons() deep_string() float() function() integer() + iodata() + iolist() list() + maybe_improper_list() + mfa() + module() nil() + neg_integer() + node() + non_neg_integer() + nonempty_improper_list() + nonempty_list() + nonempty_maybe_improper_list() + nonempty_string() none() number() pid() port() + pos_integer() reference() string() term() + timeout() tuple() ''' Details: @@ -991,7 +1082,7 @@ Details: `integer()', `pid()', `port()' and `reference()' are primitive data types of the Erlang programming language. -
  • `bool()' is the subset of `atom()' consisting +
  • `boolean()' is the subset of `atom()' consisting of the atoms `true' and `false'.
  • `char()' is a subset of `integer()' representing character codes.
    • -- cgit v1.2.3