Bug #78984 for MailTools:

Wed Aug 15 11:49:50 2012 stratman [...] gmail.com - Ticket created

Attached doc patch clarifies that open() expects a hash *ref* rather than a hash. This was tripping up a new user, somewhat understandably (even though the SYNOPSIS clearly shows it expects a ref).

Subject:

MailTools.patch

--- MailTools-2.09/lib/Mail/Mailer.pod 2012-02-25 07:47:45.000000000 -0600 +++ MailTools-docfix/lib/Mail/Mailer.pod 2012-08-15 10:44:42.000000000 -0500 @@ -81,9 +81,9 @@ the DESCRIPTION chapter of this manual page. The ARGS are passed to that back-end. -=item $obj-E<gt>B<open>(HASH) +=item $obj-E<gt>B<open>(HASHREF) -The HASH consists of key and value pairs, the key being the name of +The HASHREF consists of key and value pairs, the key being the name of the header field (eg, C<To>), and the value being the corresponding contents of the header field. The value can either be a scalar (eg, C<gnat@frii.com>) or a reference to an array of scalars

Wed Aug 15 14:29:54 2012 Mark [...] Overmeer.net - Correspondence added

Subject:	Re: [rt.cpan.org #78984]
Date:	Wed, 15 Aug 2012 20:29:36 +0200
To:	"Mark A. Stratman via RT" <bug-MailTools [...] rt.cpan.org>
From:	Mark Overmeer <mark [...] overmeer.net>

* Mark A. Stratman via RT (bug-MailTools@rt.cpan.org) [120815 15:49]: Show quoted text

> Wed Aug 15 11:49:50 2012: Request 78984 was acted upon. > Transaction: Ticket created by MSTRAT > Queue: MailTools > > Attached doc patch clarifies that open() expects a hash *ref* rather > than a hash. This was tripping up a new user, somewhat understandably > (even though the SYNOPSIS clearly shows it expects a ref).

I disagree. SCALAR, ARRAY and HASH as parameters are always references. Non-ref parameters to a function are described by their meaning, like "FILENAME". But some docs are sloppy. With f(%a) you do not pass a hash to the function, but a list of all the key-value pairs flattened out. You can only pass a hash as it is via a hash-reference, which is in perl shown as HASH. The same for an array: with f(@a) you pass the elements of the array, not @a itself. See "perldoc -f push", when you need to pass an array as-is, then you have to pass a reference to an array, represented by "ARRAY". In this case, push() itself creates the array reference because it has function prototype push(\@@) I do not agree with you, but do value your contribution -- Regards, MarkOv ------------------------------------------------------------------------ Mark Overmeer MSc MARKOV Solutions Mark@Overmeer.net solutions@overmeer.net http://Mark.Overmeer.net http://solutions.overmeer.net

Wed Aug 15 14:29:55 2012 The RT System itself - Status changed from 'new' to 'open'

Wed Aug 15 14:43:20 2012 stratman [...] gmail.com - Correspondence added

I respect your opinion and whatever decision you come to. But please consider this if you haven't already: It took 2 paragraphs, making an extremely pedantic case, to describe why func(HASH) is "correct." But let's take a step back and consider the more salient question: What will better serve the readers? Given the doc "open(HASH)", will the following programmers think "gee, open(%hash) is not technically passing a hash, but rather a list of key/value pairs, therefore I should pass a ref instead": Beginner - No. Intermediate - probably not Advanced - Maybe. Given the doc "open(HASHREF)" will the following programmers pass a ref: Beginner - Yes Intermediate - Yes. Advanced - Yes. Conversely, Will anyone - even the most advanced users - get tripped up by "open(HASHREF)", because of the argument you've laid out? Just some food for thought. If you still disagree, I can respect that. However, I invite you to focus on "what will best help the reader?" rather than "what is most technically correct?"

Wed Aug 15 15:08:17 2012 Mark [...] Overmeer.net - Correspondence added

Subject:	Re: [rt.cpan.org #78984]
Date:	Wed, 15 Aug 2012 21:08:03 +0200
To:	"Mark A. Stratman via RT" <bug-MailTools [...] rt.cpan.org>
From:	Mark Overmeer <mark [...] overmeer.net>

* Mark A. Stratman via RT (bug-MailTools@rt.cpan.org) [120815 18:43]: Show quoted text

> Queue: MailTools > Ticket <URL: https://rt.cpan.org/Ticket/Display.html?id=78984 > > > It took 2 paragraphs, making an extremely pedantic case, to describe > why func(HASH) is "correct."

I tried to explain to you why 'REF' is not needed to be clear. The documentation of MailTools is about 20 years old, one of the earliest modules on CPAN. I did not use Perl at the time, so other people decided this syntax. Most other modules use it the same syntax, amongst them all documentation in Perl Core. If you get the syntax of all those other modules to change, I may do that as well. Show quoted text

> But let's take a step back and consider the more salient question: > What will better serve the readers?

Legacy and consistency is my counter argument. Show quoted text

> Given the doc "open(HASH)", will the following programmers think "gee, > open(%hash) is not technically passing a hash, but rather a list of > key/value pairs, therefore I should pass a ref instead":

Show quoted text

> Beginner - No. > Intermediate - probably not > Advanced - Maybe.

Wrong. You translate HASH by %hash. Where does this '%' come from? Guessing? Wrong guess, should be \%hash. I do dislike the way Perl5 works sometimes: Larry does not want to decide on things like naming convensions (use of capitals and _ in names), name-spaces (module naming), or documentation structure. Perlpod(1) doesn't tell you which chapter names should be used or how, it doesn't tell you how to document functions or methods. Everyone tries to follow some important modules in style. Tomorrow I go to a two-day Perl5/Perl6 summit in the German city of Perl. Larry and 20 other core developers will be there. I have already on my slide a call (again) for decissions about this (at least for Perl6), because I do like consistency. But it will write-down the way most people do it now to start with. Show quoted text

> Given the doc "open(HASHREF)" will the following programmers pass a ref: > Beginner - Yes > Intermediate - Yes. > Advanced - Yes.

No, HASHREF whould be for me a \\%h, a REF to HASH -- Regards, MarkOv ------------------------------------------------------------------------ Mark Overmeer MSc MARKOV Solutions Mark@Overmeer.net solutions@overmeer.net http://Mark.Overmeer.net http://solutions.overmeer.net

Tue Aug 28 03:20:39 2012 MARKOV [...] cpan.org - Correspondence added

Subject:

HASHREF i.s.o HASH in method call description

Suggested patch does not reflect Perl's general documentation practice. The current syntax does.

Tue Aug 28 03:20:40 2012 MARKOV [...] cpan.org - Status changed from 'open' to 'rejected'