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

Lars Dɪᴇᴄᴋᴏᴡ 迪拉斯 daxim at cpan.org
Thu Apr 4 06:36:53 GMT 2013


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.

> 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 decided to not include the alternative way to update and delete via
row object accessors/methods because I feel that's too much for the
scope - I want a newcomer to be able to have a first feeling of success
after a very short time, and balance every side-step against the risk
of not achieving the goal. It does say "minimum amount of code" in the
intro. The row object alternatives are still explained in the main
docs, in ::Tutorial, in ::SQLHackers, in the book for the approach of
structured learning that comes afterwards, when the newcomer is on the
proverbial hook.

> 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. Worry about changing that when the time
actually comes. Of course, one could reword it to indirectly refer to
e.g. "the first two classes in the inherited methods list" or somesuch,
but that can silently/unnoticably become a dangling link
when ::Manual::ResultClass gets reorganised.

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.

> Also I would recommend changing L<SQL::Abstract> to
> L<SQL::Abstract|SQL::Abstract/WHERE CLAUSES>.
Done in 7923f7c1b5. When rebasing onto master, you may fixup/squash
this into cc3ad5941e.

> Perhaps we should have a separate test-less
> DBIx::Class::ExtendedManual dist which is a direct dependency of
> DBIx::Class?
++ to that
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 836 bytes
Desc: not available
Url : http://lists.scsys.co.uk/pipermail/dbix-class/attachments/20130404/e9c82558/signature.pgp


More information about the DBIx-Class mailing list