| Subject: | Better documentation would be nice... |
| Date: | Sun, 14 Jul 2013 12:42:55 -0700 |
| To: | bug-Email-Simple [...] rt.cpan.org |
| From: | "Ronald F. Guilmette" <rfg [...] tristatelogic.com> |
On the following page:
http://search.cpan.org/~rjbs/Email-Simple-2.201/lib/Email/Simple/Header.pm
two methods are incompletely described, i.e. "header_names" and also
"header_pairs".
Specifically, there is no indication what kinds of things are returned
by these methods.
Because the nature of the return values for these two methos are not
documented, a reader who is not familiar with this specific Perl package
is forced to make educated guesses about what the return values will be.
Specifically, I assume that the return value of "header_names" is a
simple array, but would it kill you guys to just say that, you know,
on the man page?
Likewise, my first guess would be that the return value of "header_pairs"
would be a hash, where the keys are the initial tokens of the various
header lines (e.g. "Subject", "Message-ID", etc.) but then I realize
that that wouldn't work because for some header types (e.g. "Received")
there could be more than one in the header of a single message. So
obviously, the return value of header_pairs must be an array object
but what are the elements of this array? Is each element a reference
to another array which itself consists of just two values, i.e. name &
value? That would make the most sense, but since the documentation
doesn't give the reader any guidance I guess I'll have to just play
around with it until I figure out the relevant facts that should have
been in the man page.
Note please: The questions about are retorical only. Please DO NOT
just tell me about the nature of the return values of the methods I've
mentioned. Instead, please DOCUMENT that in the man page, so that everyone
can see it. Thanks.