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

[Peter Rabbitson]

On Tue, Dec 04, 2012 at 06:12:51AM -0500, Brendan Byrd wrote:
> On Tue, Dec 4, 2012 at 4:29 AM, Peter Rabbitson <rabbit+dbic at rabbit.us> wrote:
> > On Tue, Dec 04, 2012 at 12:05:59AM -0500, Brendan Byrd wrote:
> >
> > Oh I should have executed it to see what exactly it does. Right - then this
> > point splits into several problems:
> >
> > - In this case (number of files) we definitely can not do it in the workdir,
> > sorry. There is no easy way to declutter things (make realclean does not touch
> > them), and files will linger forever in a repo even if the underlying .pm is
> > gone/renamed. Here is a scetch of a functional workaround, will need however
> > get to CPAN as a devrel for render-testing:
> > https://github.com/dbsrgits/dbix-class/commit/38a597851
> 
> As long as the PODs install in the right directories for both user
> install and distro creation, I'm fine with that.  I was putting these
> in blib, but I ran into other issues.

Yes for install, no for distcreation. Basically this instructs EUMM to 
combine the contents of both dirs on `make install`. This is also why I 
said we need to test it on s.c.o/metacpan, since in the tarball the .pod 
will still be in maint. I am pretty sure things will be picked up, but 
not 100%. There is no harm in you uploading a DBIx-Class-0.08204_01 
right away, before even merging things to master. The policy for devrels 
is that we delete them once they served their test purpose, so all is 
good.

> > - PI needs a way to parse the target POD and exclude methods which are
> > undocumented at their origin. And yes, there is a number of "public"
> > (non _ed) methods which are in fact undocumented. Maybe they are utility
> > (e.g. STORABLE_freeze) or maybe they are deprecated warning-emitting
> > methods, which are nevertheless still there (and will be there for a
> > while). I am not that concerned over dead links, I am much more
> > concerned about re-exposure of hidden stuff.
> 
> Hmmm, I might need to cut a release for P:I for that.  We have
> skip_underscored for "private" methods and skip_inherits for entire
> classes, but nothing to exclude specific methods.  Should be an easy
> enough feature to implement, though.

I was actually going further - the skips should happen automatically, 
based solely on lack of POD on the other side. Think of it as 
"no_dead_links => 1" sort of thing. As an example see 
ResultSource::pk_depends_on(). Instead of fishing these out one by one, 
something like a Pod::Tree walk can populate a %seen and prune them 
automatically.

> >> Errr, hmmmm, I might need a code example to work from.  Is @bind_values
> >> an array of hashrefs?  I think I can handle the tech writing if I have enough
> >> information.
> >
> > Array of tuple-arrays. Look at any test changed by the commit I
> > mentioned above - they all follow the same principle. I was really under
> > the impression the commit message was rather exhaustive from an
> > explanation POV. In any case - ask as many questions as you need - we
> > have not had this documented for 2 years now, it's time.
>
> Well, I guess my confusion is from the commit message describing a hash:
>
> "To fix this all up and provide more flexibility the standard [ $col
> => $val ] was replaced with [ \%args => $val ]. The format of \%args
> is currently:"
>
> So, there would be a collection of these array/hash pairs?  Like ( [
> \%args => $val ], [ \%args => $val ], ... ) ?

Precisely. Here is an example:
https://github.com/dbsrgits/dbix-class/blob/master/t/sqlmaker/bind_transport.t#L47
Note all of these args are "advisory", i.e. a [ {} => $value ] will also 
work, it just won't do anything fancy.

> 
> " ( pending in the next patch: [ $val ] === [ {}, $val ] ) "
>  
> Was this already implemented?
> 

Sadly no, I ran out of tuits and never came back to it :( I *think* it is
a little amount of code, but honestly I have not looked since.

> > See discussion of 'result' above. Also yes, having the rest say
> > ResultSet Object won't be a bad idea imo. But this is even more work, we
> > better first agree on a path forward.
> 
> Well, playing Devil's Advocate, the term "Result" is ambiguous, but
> things like ResultSet or ResultSource are most definitely implied as
> objects. I think I'm okay with that direction: renaming just Result.

Perhaps bring it up tonight in front of a wider audience - I am not a 
native english speaker, I may have a perception bias here.

> > We should probably start that if not too difficult. Will reduce the amount
> > of "holy shit where do I start", and will clearly delineate the ::Dev::
> > namespace.
> 
> That's fine, though I think I may split some of these changes into
> another topic (doc_fix2?) to get the approved changes out of the way
> quicker.  These poor branches have been lingering too long.
> 

Sure, ping the list when you push the reshuffled stuff, whatever patches 
seem ok as-is I will merge directly.

Cheers