[DBIx-Class-Devel] Review request topic/populate_doc (unrelated to Brendan's work)

[Brendan Byrd]

On Thu, Dec 13, 2012 at 8:48 AM, fREW Schmidt <frioux at gmail.com> wrote:
> On Thu, Dec 13, 2012 at 06:21:16PM +1100, Peter Rabbitson wrote:
>>
>> Brendan, this is mostly a question to you: I am not entirely sure how
>> to document the signature. Currently we have:
>>
>> =item Arguments: [ \@column_list, \@row_values+ ] | [ \%col_data+ ]
>>
>> I am not sure if the '+' is descriptive enough. Thoughts?
>
> Here's my idea.  It's wide, but clear:
>
>   =item Arguments: [ \@column_list, \@row_values+ ] | [ \%col_1_data, \%col_2_data, ... ]

or just \%col_data, \%col_data, ...

I've bantered around the idea myself in other things (like
add_to_$rel).  If we use +, we should document that in ::Reading.

However, I'm more in favor of the long form.  Furthermore, I hate
\@col syntax.  Why?  Because the brain has to process more to
translate that form into something that you can actually use in real
Perl code.  Almost nobody writes the arguments in \@ form.  For
example:

[ \@column_list, \@row_values+ ]

or

[ [ @column_list ], [ @row_values ], [ @row_values ], ... ]

Which form is more readable to you?  Which form can I just copy and
paste to plug into real Perl code, with less modification?

Another example:

$rel_name, \%col_data | @pk_values

I actually checked the code to make sure I wasn't reading it wrong.
Very easily mistaken for:

$rel_name, \%col_data | \@pk_values

However:

$rel_name, { %col_data } | @pk_values

Is a lot more clear.

-- 
Brendan Byrd <Perl at ResonatorSoft.org>
Brendan Byrd <BBYRD at CPAN.org>