edoc, erlc and dialyser type spec consistency
Thu Nov 19 10:55:25 CET 2009
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.
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
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
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*????
What's wrong with bool() - why is the name changed to boolean()?
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
There rules obey certain meta principles:
meta principle 1) "don't wear your fingers out"
- I want to type
foo(X::bool()) -> ok.
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.
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.
More information about the erlang-questions