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

[Kostis Sagonas]

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