[Dbix-class] "the apparent complexity of it all"

[Peter Rabbitson]

On Thu, Apr 04, 2013 at 08:36:53AM +0200, Lars Dɪᴇᴄᴋᴏᴡ 迪拉斯 wrote:
> New patches on top of
> <https://github.com/daxim/dbix-class/commits/master>.
> 
> > I wonder whether this should not mention DBIx::Class::Schema::Loader
> > from the start.
> With 974c7e5, the synopsis then has such a mention.

I meant more of a "this is how you do it in 30 seconds without reading 
on the vagaries of result definitions". Given that this is a quick-start 
guide it kinda seems apt. And by mention I mean simply the CLI dbicdump 
oneliner and a link to SL. Again - just a suggestion, maybe it is out of 
scope.

> > hope we get some feedback
> > from other folk versed in doc-writing
> I got valuable feedback after reminding on irc. I'm sorry, I don't know
> how to work the GH review feature so that it creates a forward link to
> the commit, I hope I have done it right by just reading the info and
> making a new one, backlinking to the review page. The result is
> 3a93a5e1cc. When rebasing onto master, you may fixup/squash this into
> 974c7e53e3.

I will leave it to castaway to comment on this one. The only thing that 
is technically incorrect is that: "The first four arguments are the same 
as for L<DBI/connect>" - the hash takes extra DBIC args directly if one
so wishes. But it probably doesn't matter for a quick-start.

> > Not merged. While I like the idea, I am not sure if mentioning
> > DBIC::Row DBIC::Rel::Base (which is about to go away soon... I
> > hope... I really do) is a good idea. Especially given that we have
> > https://metacpan.org/module/DBIx::Class::Manual::ResultClass#INHERITED-METHODS.
> It's not the problem you think it is. The docs patch does and must
> reflect current reality.

Right... and current reality is that folks look at ::Row, and decide it 
is the base class and never look further on. This was the whole reason 
behind constructing ::Manual::ResultClass - to highlight ::Row is just a 
small part of the entire set. This is something SineSwiper should wheigh 
in on.

> The explicit mention is better because it creates an obvious mode of
> failure: when ::Rel::Base is removed, the author hopefully acks through
> the whole source and sees this needs an update. Even if that is missed
> and the distro ships with that broken link going nowhere, eventually a
> reader notices and reports.

To reiterate - I am not worried about broken doclinks (we have soooo 
many). I am worried about giving the user a skewed perspective on where 
the methods for their Result class come from.

> > Perhaps we should have a separate test-less
> > DBIx::Class::ExtendedManual dist which is a direct dependency of
> > DBIx::Class?
> ++ to that

Well... Daxim, Abraxxa, Castaway, SineSwiper - who wants to tackle that? 
This way we get the reference manual remain in core (and get updated 
with code) and the tutorials etc being maintained separately (which is 
safe given our commitment to backwards comp).

Cheers