[erlang-bugs] Doc inconsistency for public_key:pem_entry_decode/2

[Kostis Sagonas]

On 03/06/2015 11:51 AM, Roberto Aloi wrote:
> Hi,
>
> according to the doc, the function expects Password::string() as the
> second argument:
>
> http://www.erlang.org/documentation/doc-5.9.3/lib/public_key-0.17/doc/html/public_key.html#pem_entry_decode-2
>
> The spec for the function expects a list of strings:
>
> https://github.com/erlang/otp/blob/801b09af301a872170e44c215e274425c46f8d24/lib/public_key/src/public_key.erl#L113
>
> This makes dialyzer sad.

... and specs like the one in the link make me even sadder.

The spec there reads:

   -spec pem_entry_decode(pem_entry(), [string()]) -> term().

This spec also has the problem that this function clearly does not 
return any term(), but something more specific than that.  Why not 
document that in the spec so that the callers of this function know what 
to expect?  (If hiding this information is intentional, simply declare 
this data type as opaque.)

More importantly, is there (still) any good reason why discrepancies 
between the specs and the published documentation differ, instead of 
having the documentation generated directly from the specs?

Kostis