[eeps] Commit: r52 - eeps/trunk

raimo+eeps <>
Thu Oct 30 15:20:25 CET 2008


Author: raimo
Date: 2008-10-30 15:20:25 +0100 (Thu, 30 Oct 2008)
New Revision: 52

Modified:
   eeps/trunk/eep-0008.txt
Log:
Update from Kostis


Modified: eeps/trunk/eep-0008.txt
===================================================================
--- eeps/trunk/eep-0008.txt	2008-10-29 14:51:40 UTC (rev 51)
+++ eeps/trunk/eep-0008.txt	2008-10-30 14:20:25 UTC (rev 52)
@@ -27,7 +27,7 @@
 exploited by documentation tools such as Edoc for generating program
 documentation of various forms. It is expected that the type language
 described in this document will supersede and eventually replace the
-purely comment-based type language currently used by Edoc.
+purely comment-based @type and @spec declarations used by Edoc.
 
 
 
@@ -112,8 +112,8 @@
 
 
 Because lists are commonly used, they have shorthand type notations.
-The type ``list(T)`` has the shorthand ``[T]``. The shorthand ``[T,...]`` stands
-for the set of non-empty proper lists whose elements are of type ``T``.
+The type ``list(T)`` has the shorthand ``[T]``. The shorthand ``[T,...]``
+stands for the set of non-empty proper lists whose elements are of type ``T``.
 The only difference between the two shorthands is that ``[T]`` may be an
 empty list but ``[T,...]`` may not.
 
@@ -128,6 +128,7 @@
     ==========================  =====================================
           Built-in type                   Stands for
     ==========================  =====================================
+    ``term()``                  ``any()``
     ``bool()``                  ``'false' | 'true'``
     ``byte()``                  ``0..255``
     ``char()``                  ``0..16#10ffff``
@@ -143,13 +144,18 @@
     ``iolist()``                ``maybe_improper_list(``
                                     ``char() | binary() |``
                                     ``iolist(), binary() | [])``
+    ``module()``                ``atom()``
     ``mfa()``                   ``{atom(),atom(),byte()}``
+    ``node()``                  ``atom()``
+    ``timeout()``               ``'infinity' | non_neg_integer()``
     ``no_return()``             ``none()``
     ==========================  =====================================
 
 Users are not allowed to define types with the same names as the
-predefined or built-in ones.  This is checked by the compiler and its
-violation results in a compilation error.
+predefined or built-in ones. This is checked by the compiler and its
+violation results in a compilation error. (For bootstrapping purposes,
+it can also result to just a warning if this involves a built-in type
+which has just been introduced.)
 
     *NOTE*: The following built-in list types also exist, but they are
     expected to be rarely used. Hence, they have long names:
@@ -184,7 +190,7 @@
 parentheses. New types are declared using ``'type'`` compiler attributes
 as in the following::
 
-    -type(my_type() :: Type).
+    -type my_type() :: Type.
 
 where the type name is an atom (``'my_type'`` in the above) followed by
 parenthesis. Type is a type as defined in the previous section. A
@@ -202,7 +208,7 @@
 variables can - and should - appear on the RHS of the definition.
 A concrete example appears below::
 
-    -type(orddict(Key, Val) :: [{Key, Val}]).
+    -type orddict(Key, Val) :: [{Key, Val}].
 
 
 Type information in record declarations
@@ -260,7 +266,7 @@
 A contract (or specification) for a function is given using the new
 compiler attribute ``'spec'``. The basic format is as follows::
 
-    -spec(Module:Function/N :: (ArgType1, ..., ArgTypeN) -> ReturnType).
+    -spec Module:Function(ArgType1, ..., ArgTypeN) -> ReturnType.
 
 The arity of the function has to match the number of arguments, or
 else a compilation error occurs.
@@ -272,38 +278,38 @@
 
 For most uses within a given module, the following shorthand is allowed::
 
-    -spec(Function/N :: (ArgType1, ..., ArgTypeN) -> ReturnType).
+    -spec Function(ArgType1, ..., ArgTypeN) -> ReturnType.
 
 Also, for documentation purposes, argument names can be given::
 
-    -spec(Function/N :: (ArgName1 :: Type1, ..., ArgNameN :: TypeN) -> RT).
+    -spec Function(ArgName1 :: Type1, ..., ArgNameN :: TypeN) -> RT.
 
 A function specification can be overloaded. That is, it can have
 several types, separated by a semicolon (;)::
 
-    -spec(f/2 :: (T1, T2) -> T3
-               ; (T4, T5) -> T6).
+    -spec foo(T1, T2) -> T3
+           ; (T4, T5) -> T6.
 
 A current restriction, which currently results in a warning (*OBS*: not
 an error) by the compiler, is that the domains of the argument types
 cannot be overlapping. For example, the following specification
 results in a warning::
 
-    -spec(f/1 :: (pos_integer()) -> pos_integer()
-               ; (integer()) -> integer()).
+    -spec foo(pos_integer()) -> pos_integer()
+           ; (integer()) -> integer().
 
 Type variables can be used in specifications to specify relations for
 the input and output arguments of a function. For example, the
 following specification defines the type of a polymorphic identity
 function::
 
-    -spec(id/1 :: (X) -> X).
+    -spec id(X) -> X.
 
 However, note that the above specification does not restrict the input
 and output type in any way. We can constrain these types by guard-like
 subtype constraints::
 
-    -spec(id/1 :: (X) -> X when is_subtype(X, tuple())).
+    -spec id(X) -> X when is_subtype(X, tuple()).
 
 and provide bounded quantification. Currently, the ``is_subtype/2`` guard
 is the only guard which can be used in a ``'spec'`` attribute.
@@ -313,8 +319,8 @@
 that different variables are used in different constituents of an
 overloaded contract as in the example below::
 
-    -spec(f/1 :: ({X, integer()}) -> X when is_subtype(X, atom())
-               ; ([Y]) -> Y when is_subtype(Y, number())).
+    -spec foo({X, integer()}) -> X when is_subtype(X, atom())
+           ; ([Y]) -> Y when is_subtype(Y, number()).
 
 
 Some functions in Erlang are not meant to return; either because they
@@ -326,7 +332,7 @@
 For such functions we recommend the use of the special ``no_return()``
 type for their "return", via a contract of the form::
 
-    -spec(my_error/1 :: (any()) -> no_return()).
+    -spec my_error(term()) -> no_return().
 
 
 Current limitations
@@ -349,4 +355,3 @@
    fill-column: 70
    coding: utf-8
    End:
-




More information about the eeps mailing list