edoc, erlc and dialyser type spec consistency

[Kostis Sagonas]

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.
I can assure you that Dialyzer uses the same specs as erlc.

> 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
>
> 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 
astonishment here.

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 
called is_boolean/1.

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 
in R13B04.

Kostis