edoc, erlc and dialyser type spec consistency
Thu Nov 19 11:22:47 CET 2009
Joe Armstrong wrote:
> I'm trying to document my new library - *beautifully* - so
> I want to use edoc, the dialyzer etc. and anything I can throw at it
> to improve the code, but I'm confused about type specifications.
> The type specifications in edoc and erlc violate the principle of
> least astonishment, I haven't checked with the dialyzer.
You do not have to check this. dialyzer uses the same spec language as
> Question 1)
> Should type specifications end with DOT Whitespace?
> erlc says YES, edoc says NO
> -spec foo(In::string()) -> Out::string(). is legal in erlc
> %% @spec foo(In::string()) -> Out::string(). gives an error in edoc
> Question 2)
> Are type specifications without a function name symbol legal?
> The Edoc manual says the function name is optional.
> %% @spec (In::string()) -> Out::string()
> foo(X) -> Y.
> is *legal* in edoc and the function name is picked up from the
> *next* definition. But:
> -spec (In::string()) -> Out::string().
> is *illegal* in erlc
By the way, this happens because -specs can appear /anywhere/ in the
file, while Edoc @specs *must* appear immediately before the
corresponding function definitions, so it's easy for Edoc to fill in the
missing function name.
> Question 3)
> What's up with atoms?
> A quick grep though stdlib shows that all atoms in type specifications
> are quoted - why is thi? Why is the convention for *atoms in code*
> different to *atoms in type specifications*????
As you point out, quoting atoms in specs is optional. It's equally
optional in code, so I do not see any discrepancy or reason for
I've personally adopted a habit to quote atoms in specs, because I've
been bitten one too many from wanting to write e.g. atom() but written
atom. Perhaps other users are more careful and disciplined than I am,
so they do not need this. But it does not hurt to express intention
that I want the 'ok' atom here and the ok() type there.
> Question 4)
> What's wrong with bool() - why is the name changed to boolean()?
This was a conscious decision to have all base types match the
corresponding type tests/guards. There is no is_bool/1 test, the BIF is
Similarly, quite long ago ref() was renamed to reference().
> My suggestion:
> a) There should be ONE type/spec parser as part of the OTP distribution
> everybody should use this one and not their own
> b) Specs and types must finish with DOT WHITESPACE.
> c) Quoting atoms in type specs is illegal.
> d) Function names are required (ie not optional as in edoc)
> e) Short form of type names are legal
> bool(), int().
I very much agree with (a), (b) and (d).
I strongly disagree with (c) because the corresponding action in code is
legal. Why should it be illegal in specs?
As for (e), it's currently very simple for the user to include type
alias definitions as in:
-type int() :: integer().
But if there is a strong demand, we can add hard-coded such declarations
More information about the erlang-questions