edoc, erlc and dialyser type spec consistency

[Joe Armstrong]

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.

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*????

Question 4)

    What's wrong with bool() - why is the name changed to boolean()?

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().

There rules obey certain meta principles:

    meta principle 1) "don't wear your fingers out"

   - I want to type

        foo(X::bool()) -> ok.

    and not

        foo(X::boolean()) -> 'ok'

    meta principle 2) "optional is bad"

        ie DOT whitespace is not optional - dropping the function
        symbol and inferring it from the next function is bad.

        (aside: the optional ';' in Javascript totally screwed up
                the parser and is responsible for lager numbers
                or really weird errors)

    meta principle 3) "make type specs etc look like Erlang"

    Similar syntax if possible, similar conventions. The sudden appearance
    of quotes, optional '.' violates the principle of least astonishment.


/Joe