[erlang-questions] [erlang-patches] Fix spec for cpu_sup:util/1

[Andrew Caruth]

Hi Kostis,

Thanks for taking a look at that! I definitely agree that the ideal is the documentation of library functions should ultimately come from the code. Otherwise either the spec/documentation is misleading, or the code is misleading. Also, as you point out, the fact that dialyzer flags an error is a potential warning sign that the module is either incomplete, undergoing some changes, is potentially no longer properly supported, or simply contains bugs.

Though, upon the completion of a release of a particular version of a library, is that not the point at which the functionality is cast in stone as it were? In general the OTP specs and documentation are excellent. 

Thanks,
Andrew

-----Original Message-----
From: erlang-questions-bounces@REDACTED [mailto:erlang-questions-bounces@REDACTED] On Behalf Of Kostis Sagonas
Sent: 04 December 2013 14:57
To: erlang-patches@REDACTED
Cc: Erlang
Subject: Re: [erlang-questions] [erlang-patches] Fix spec for cpu_sup:util/1

On 12/04/2013 03:38 PM, Andrew Caruth wrote:
> Hi OTP devs,
>
> I recently noticed dialyzer was flagging an issue in one of our own modules that was making a call to cpu_sup:util([detailed]). An 'is_list()' guard test was performed on the second element of the tuple returned which dialyzer was reporting as a test that could never succeed. Sample output from a call to cpu_sup:util([detailed]):
>
> {[0],
>   [{soft_irq,0.0},
>    {hard_irq,0.0},
>    {kernel,0.41368935690109065},
>    {nice_user,0.0},
>    {user,0.9402030838661151}],
>   [{steal,0.0},{idle,98.64610755923279},{wait,0.0}],
>   []}
>
> The spec implied {'all' | integer | list, tuple | float, tuple | float, []}, which excludes the above output, so I've updated the spec to allow the second and third elements as lists.
>
> Also, the atoms 'soft_irq', 'hard_irq', and 'steal' were also not part of the spec, so I've also added those.

I do not want to comment on the particular patch, but only to point out that this a more general problem.

Often, there are good reasons for implementations of built-in of library functions to contain *more* functionality than what the fine manual describes (e.g. to have some experimental features or interfaces that are not cast in stone yet).

I think it's a good idea that the specs and the manual always agree with each other.  In fact, I think that the manual of library modules should ideally be produced by what's in their code.

All the above imply that dialyzer, which is based on specs, may be less forgiving than the actual implementation, and there are very good reasons for it to behave so: It warns you that you are relying on some undocumented (and likely to disappear) feature of the current implementation.

Kostis

_______________________________________________
erlang-questions mailing list
erlang-questions@REDACTED
http://erlang.org/mailman/listinfo/erlang-questions