[DBIx-Class-Devel] Pull Request: topic/docs-pod-inherit

[Brendan Byrd]

On Tue, Dec 11, 2012 at 11:27 AM, Peter Rabbitson <rabbit+dbic at rabbit.us> wrote:
>
> Somewhat - it is all for your consideratin only - perhaps things can
> stay as-is.

Maybe for now, but we should put in a full example later on.  (Or just
bulk up the SYNOPSIS.)

> Look at 14f8d7dbc - it has two sections (well three if you count the one
> from above):
>
> =head1 INITIALIZATION METHODS
>
> =head1 RESULTSOURCE METADATA METHODS
>
> =head1 DATA INSTANCE MANIPULATION METHODS
>
> What I meant was - perhaps it is possible to separate the bunch of
> inherited methods into separate =head's. Same caveat as above applies -
> it is just a "nice to have"

Yeah, we'll have to tackle this later, since that would be a different
Pod::Inherit change.  (Combined with multiple PI calls and Pod
manipulation in gen_pod_inherit.)

> Well not quite - key is a *special* attribute, and as such is not documented
> in Resultset. Perhaps something like:
> { key => $unique_constraint_name, %attrs(+link) }?

Why shouldn't we just document this one in ATTRIBUTES?  If it only
applies to relationship methods, we can just document that in the
beginning.

> Honestly I would just write a new test for this based on one of the existing
> ones.

Yeah, I think I'll do that.  Though it looks like it might need to be
a TODO test until we can put that into SQLA.

>> I'm also in favor of expanding resultset_attributes to fix whatever
>> issues might arise from it.  Like deep nested hash combining, if a
>> second option is given.
>
> I don't follow - what do you mean by "nested hash combining"?

Just some preliminary ideas I thought of.  rs_attr could have a second
param that indicates how defaults are merged with existing attributes:

0 = whatever we are doing right now (ie: no change from existing behavior)
1 = no combining (ie: any %attr will turn off the default)
2 = simple combining (ie: if prefetch is in both, the default gets
clobbered, but the rest will merge)
3 = deep nested combining (ie: clobber as little as possible)

>> Or some sort of attribute that would force no defaults.
>
> That would be a solution while looking for a problem :) result_attributes
> was badly thought through in the first place, and parts of it don't even
> work properly (and are a massive bitch to fix). See RT#63709 for example.
> The less the docs and existing machinery encourage their use - the better.

I don't quite follow why they don't work.  Is this a case of defaults
being inserted and manipulated too late or too early while other
processes (like relationship mapping) mess with the %attr hash?  Is
there a way to implement it "properly" and deprecate the existing
design?

> +1. The more the better. There is also a maint/gen_pod_index which has
> not been touched/used by anyone since 2006 (55a55d31). Perhaps it can
> be brought back in service?

Ahhh, wondered what that was, but with so many methods everywhere, it
might be needed.

However, it can be implemented in a different fashion using P:I.  P:I
can be forced to write to a POD (like ResultClass) and it can be
mapped to basically every module we have.  Then, we can have something
like Pod::POM edit the header to something else besides "INHERITED
METHODS".  There would still be a grouping of methods together by
module, but at least every method would be on one page, easily enough
for a Ctrl+F.

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