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

[Peter Rabbitson]

On Thu, Dec 13, 2012 at 01:51:59PM -0500, Brendan Byrd wrote:
> 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.
> 

You hold the "pod-style baton" now - so go with whatever you think fits
best the overall picture.