Guide to writing specs in Erlang

Question

In open source projects I see the following two ways of writing specs:

Specs in comments

@spec start_link() -> {ok, pid()}

Specs in source code

-spec start_link() -> {ok, pid()}

What's the difference? Is one preferred over the other?

Answer 1

The comment (@spec) version predates the source code (-spec) version. The latter is preferable.

according to EDoc documentation:

Note: 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.