| Subject: | Mail::DKIM::Signer - The documentation for the headers() method is very confusing. |
Mail::DKIM version 0.52 downloaded from CPAN 21 January 2018.
The documentation for Mail::DKIM::Signer reads:
[QUOTE]
headers()
Determine which headers to put in signature.
my $headers = $dkim->headers;
This is a string containing the names of the header fields that will be
signed, separated by colons.
[/QUOTE]
This leads one to suppose that the methods offers some control over what headers are signed.
In my experience the method merely returns the headers which have signed after a message has been signed (by some call to a signing method); it croaks if it is given an argument, and if called without an argument before the message has been signed it returns nothing.
Perhaps the documentation should be rewritten along the lines of
[DOC]
headers()
Show which headers were signed after the signature has been generated.
my $headers = $dkim->headers;
This is a string containing the colon-separated names of the header fields which have been
signed by this instance of Mail::DKIM::Signer.
If no signature has yet been generated, this method returns an empty string.
[/DOC]
However I see that the headers() method now calls process_headers_hash(), which version 0.40 in the current Debian distribution at least does not. I have not investigated, but it seems to me that under some circumstances this could lead to a violation of the principle of least surprise. :)