We discussed record definitions earlier in the book. In the example of the mobile user database in Chapter 10, you saw a declaration of a record to hold information about a particular user of the mobile phone system:

-record(usr, {msisdn,             %int()
              id,                 %term()
              status = enabled    %atom(), enabled | disabled
              plan,               %atom(), prepay | postpay
              services = []}).    %[atom()], service flag list

The usr record has five fields, and in the comments that follow, each field type is indicated.

You can take that a step further, however, and make these comments a part of the program itself. First, you introduce type declarations defining types for the kind of plan, user status, and service:

-type(plan()     :: prepay | postpay).
-type(status()   :: enabled | disabled).
-type(service()  :: atom()).

The three type declarations define the plan, status, and service types. As with constant functions, they are followed by a set of parentheses, ():

With these definitions in place, you can explicitly give types to the record fields in this record with typed fields:

-record(usr, {msisdn              ::integer(),
              id                  ::integer(),
              status = enabled    ::status(),
              plan                ::plan(),
              services = []       ::[service()]
}).

This more clearly indicates what the elements of the usr record type should be and how they should be used by programs that manipulate them. But most importantly, it provides tools with information that will help you detect type errors in the code. This short example provided you with a taste of the Erlang type notation. Now let’s cover it in more detail.

A number of Erlang types are predefined, and they include the following:

You can find details of other predefined types in the EDoc and Dialyzer documentation. In addition to the aforementioned predefined types, you can define your own types using the following notation:

A function type has the following form:

(Argument_types) -> Result_type

where the argument types may also contain the names of the corresponding parameters.

You use a –spec statement to specify a type (or prototype) for a function in a program.To be clear, -spec is used to specify the type of a function, whereas –type is used to define a type. Revisiting the usr_db example from Chapter 10, you can say:

-spec(create_tables(FileName::string()) -> {ok, ref()} | {error, atom()}).

create_tables(FileName) ->
    ... .

-spec(close_tables() -> ok | {error, atom()}).

close_tables() ->
    ... .

The type of create_tables here indicates that the FileName argument is a string, and that there are two alternatives for the return type:

The use of FileName here is optional. Writing the following would have the same effect:

-spec(create_tables(string()) -> {ok, ref()} | {error, atom()}).

However, including the parameter name—assuming it is chosen to reflect its purpose—improves the documentation.^[44]

TypEr gives an analysis of types in Erlang programs. Dialyzer extends this to perform static analysis on Erlang programs to identify software discrepancies, including redundant tests and unreachable code, as well as obvious type errors.

To speed up its operation, Dialyzer can create a Persistent Lookup Table (PLT), using the --build_plt option. When you include the kernel, standard libraries, and Mnesia, as shown here:

dialyzer --build_plt -r <erl-lib>/kernel-2.12.5/ebin <erl-lib>/
stdlib-1.15.5/ebin <erl-lib>/mnesia-4.4.7/ebin

it takes some minutes to generate the PLT and produce this report:

Creating PLT /Users/simonthompson/.dialyzer_plt ...
re.erl:41: Call to missing or unexported function unicode:characters_to_binary/2
re.erl:134: Call to missing or unexported function unicode:characters_to_list/2
re.erl:200: Call to missing or unexported function re:compile/2
re.erl:226: Call to missing or unexported function unicode:characters_to_binary/2
re.erl:245: Call to missing or unexported function unicode:characters_to_list/2
re.erl:505: Call to missing or unexported function unicode:characters_to_list/2
re.erl:545: Call to missing or unexported function unicode:characters_to_binary/2
Unknown functions:
  compile:file/2
  compile:forms/2
  compile:noenv_forms/2
  compile:output_generated/1
  crypto:des3_cbc_decrypt/5
  crypto:start/0
 done in 16m43.44s
done (warnings were emitted)

Subsequently calling Dialyzer on the files for the running example gives this report (in less than a second):

dialyzer -c usr.erl usr_db.erl
  Checking whether the PLT /Users/simonthompson/.dialyzer_plt is up-to-date... yes
  Proceeding with analysis...
usr.erl:110: The pattern [] can never match the type {'error','instance'}
usr_db.erl:69: Call to missing or unexported function ets:safefixtable/2
 done in 0m0.33s
done (warnings were emitted)

You can find more information about Dialyzer in the online documentation.

EDoc generates documentation from tags of the form @tag text, embedded within comments. Each tag can continue over multiple lines, until the next tag or noncomment line. You can use different kinds of tags in different ways:

We will look at these in turn for the usr_db example.

%% @author Francesco Cesarini <[email protected]>
%% @author Simon Thompson [http://www.cs.kent.ac.uk/~sjt/]
%% @doc Back end for the mobile subscriber database.
%% The module provides an example of using ETS and DETS tables.
%% @reference <a href="http://oreilly.com/catalog/9780596518189/">
  Erlang Programming</a>,
%%  <em> Francesco Cesarini and Simon Thompson</em>,
%%  O'Reilly, 2009.
%% @copyright 2009 Francesco Cesarini and Simon Thompson

%% @doc Create the ETS and DETS tables which implement the database. The
%% argument gives the filename which is used to hold the DETS table.
%% If the table can be created, an 'ok' tuple containing a
%% reference to the created table is returned; if not, it returns an 'error'
%% tuple with an atom describing the error.

%% @spec create_tables(string()) -> {ok, reference()} | {error, atom()}

-spec(create_tables(string()) -> {ok, ref()} | {error, atom()}).

create_tables(FileName) ->
  ets:new(subRam, [named_table, {keypos, #usr.msisdn}]),
  ets:new(subIndex, [named_table]),
  dets:open_file(subDisk, [{file, FileName}, {keypos, #usr.msisdn}]).

%% @doc Close the ETS and DETS tables implementing the database.
%% Returns either 'ok' or an 'error'
%% tuple with the reason for the failure to close the DETS table.

%% @spec close_tables() -> ok | {error, atom()}

-spec(close_tables() -> ok | {error, atom()}).

close_tables() ->
  ets:delete(subRam),
  ets:delete(subIndex),
  dets:close(subDisk).

%% @doc Add a user (of the 'usr' record type) to the database.

%% @spec add_usr(#usr{}) -> ok

-spec(add_usr(#usr{}) -> ok).

add_usr(#usr{msisdn=PhoneNo, id=CustId} = Usr) ->
  ets:insert(subIndex, {CustId, PhoneNo}),
  update_usr(Usr).

The main EDoc functions are in the edoc module. A call to edoc:application/1 will generate the documentation for an application, and a call to edoc:files/1 will generate the documentation for a set of files; these functions use the default EDoc options. Two-argument versions of the functions allow a set of option choices to be passed in the second argument.

Module pages

Figure 18-1 shows the page generated for the usr_db module that results from running edoc:files(["usr_db.erl", "usr.erl"]). This shows the structure of a typical EDoc page for an Erlang module.

Figure 18-1. EDoc page for (a fragment of) usr_db.erl

The page begins with links to its major sections, and is followed by the one-sentence summary of the module and other module tags; the full description of the module follows.

In the function index, functions are listed in alphabetical order, rather than in their order in the file. Each function is hyperlinked to its details, and is given a one-sentence overview: the first sentence of its @doc tag.

Each function has details regarding its type. Note that the information contains not only the types of the arguments and results, but also the names of the arguments that are automatically extracted from the source code. For instance, the @spec for create_tables/1 says the following:

%% @spec create_tables(string()) -> {ok, reference()} | {error, atom()}

Here is the documentation that is produced:

create_tables(FileName::string()) -> {ok, reference()} | {error, atom()}

This gives you the useful extra information that the string argument represents a filename. Without any @spec information, EDoc will still include the names of the parameters in the generated information.

Overview page

For each project, an overview page will be generated, providing an index for the modules in the project. Further information can be provided for this in an overview.edoc file, which should typically appear in a doc subdirectory where the other documentation will be placed.

The overview.edoc file has the same content tags as the header for a module, but it is not necessary to enclose each line in a comment. The results of this for the running example are shown in Figure 18-2, as generated from a file that begins like this:

@author Francesco Cesarini <[email protected]>
@author Simon Thompson [http://www.cs.kent.ac.uk/~sjt/]
@reference <a href="http://oreilly.com/catalog/9780596518189/">Erlang Programming</a>,
  <em> Francesco Cesarini and Simon Thompson</em>,
  O'Reilly, 2009.

Figure 18-2. The EDoc overview page for the database

The usr_db.erl module contains no type definitions, but usr.hrl contains a number of these, and they are referenced in usr.erl. Types are documented like this: the definition is given first, and this can be followed by an optional description:

%% @type plan() = prepay|postpay. The two payment types for mobile subscribers.
%% @type status() = enabled | disabled. The status of a customer can be enabled
%% or disabled.
%% @type service() = atom(). Services are specified by atoms, including
%% (but not limited to) 'data', 'lbs' and 'sms'. 'Data' confirms the user
%% has subscribed to a data plan, 'sms' allows the user to send and receive
%% premium rated smses, while 'lbs' would allow third parties to execute
%% location lookups on this particular user.

This is extracted in the documentation for the usr module, and if a defined type is used in the @spec for a function, this is hyperlinked to its definition. The information about types appears in the documentation after the general description and before the function index. Figure 18-3 shows a fragment of the documentation for usr.erl, with the data type definitions appearing after the module description.

Figure 18-3. A fragment of the web page for usr.erl

If you want to generate comprehensive documentation for applications and other projects, EDoc provides a number of facilities for formatting, cross-referencing, and preprocessing.

EDoc comes with a set of predefined macros, called by enclosing them in braces, thus: {@name} and {@name argument}. These include @date, @time, @module, and @version as well as the {@link reference. description} form. This creates a link to the object identified by the reference; the description gives the text for the anchor of the link.

References include name/arity for functions within the module, and Mod:name/arity for functions in the module Mod. A typename() refers to a type within the same module, and Mod:typename() in another. So, for example, the following link:

{@link set_status/2. 'set_status/2'}

gives a link to the documentation for the set_status/2 function in the same module.

In this example, the link is also labeled set_status/2: you use another EDoc facility for verbatim quotation. The quotation of the text '...' puts the enclosed text into verbatim (code) form, properly escaping any XHTML-significant characters in the text, such as <, =, and >. y shows an example using the @link construct, where the description part of the documentation gives an index for the functions divided according to function, rather than alphabetically.

For author convenience, EDoc supports wiki-style formatting instead of XHTML. Blank lines are taken to delimit paragraphs (i.e., <p> ... </p> elements). Headings can be generated automatically from ==Heading==, and similarly from ===, however, = should not be used. This header markup will automatically generate an anchor (equivalent to <a name="Heading">), which can then be referred to by an EDoc macro, {@section Heading}. For further details on formatting and cross-referencing in EDoc, see the online documentation.