[erlang-questions] edoc, erlc and dialyser type spec consistency

[Kostis Sagonas]

Joe Armstrong wrote:
> On Thu, Nov 19, 2009 at 1:02 PM, Kenneth Lundin
> <kenneth.lundin@REDACTED> wrote:
>> I agree with Kostis answers and can also inform you that we are working
>> on a solution for a) below.
>>
>> The plan is:
>> Edoc will then parse and use the same -spec and -type as Dialyzer.
>> If a file contains both -spec/-type and edoc comments with @spec and @type
>> you will have to choose which notation to use (as a compatiblity mode) for
>> already existing edoc markup.
> 
> Excellent.
> 
> One more question:
> 
>    - does the dialyzer pick up @specs from edoc comments if there are
> no -spec's in the code?

The short answer is "No".

The long answer is that even if there were some tool that would pick up 
@specs from edoc comments and feed them automatically to dialyzer, you 
probably would not want to use these @specs because quite many of them 
have suffered from code rot and are misleading or just wrong.

See also war story documented in the following paper:

http://www.it.uu.se/research/group/hipe/dialyzer/publications/wrangler.pdf

Highly recommended to anyone who wants to add proper specs to his code.

My advice: if you are about to start documenting your code using specs, 
start using proper -specs and run dialyzer periodically while you do so. 
  Do not worry for that you may not be able to run edoc for a short while.
It's just a matter of time for Edoc to be able to also handle proper -specs.

Kostis