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

[fREW Schmidt]

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.

I disagree and use \%foo and \@bar all the time.  Additionally []
apparently means optional in our pod, so how do you make it clear
what's an arrayref of arrayrefs (as in popuplate) or an optional list
of arrayrefs?

Note that I think this is stupid and that [] as optional only makes
sense for commandline help, but I don't care enough to change minds :)

--
fREW Schmidt
http://blog.afoolishmanifesto.com
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 836 bytes
Desc: not available
Url : http://lists.scsys.co.uk/pipermail/dbix-class-devel/attachments/20121213/d90826a9/attachment.pgp