[Catalyst] Catalyst-Devel Patch

J. Shirley jshirley at gmail.com
Mon Jul 21 04:38:42 BST 2008


On Sun, Jul 20, 2008 at 7:49 PM, Todd Rinaldo <toddr at null.net> wrote:
> Hi,
>
> I still think something should go in the manual explaining how this
> works. I spent quite a bit of time trying to figure out how
> Catalyst::Helper did it's magic. If a code reference shouldn't go in,
> then could I recommend a link to the FAQ. I think allot of people get
> their start with DBIC using Catalyst::Helper and so it's the natural
> place they would look first.
>
> [snip]

The main point is that Catalyst::Helper is specific to Catalyst, and
has absolutely zero relevance to DBIx::Class.

If you want something in the Catalyst::Helper space, something
specific to DBIC would be the right place.

As an example, Catalyst::Model::DBIC::Schema:
http://search.cpan.org/~blblack/Catalyst-Model-DBIC-Schema-0.20/lib/Catalyst/Model/DBIC/Schema.pm

But, again, the question you are asking is already answered in the
Catalyst::Helper::Model::DBIC::Schema documents:
http://search.cpan.org/~blblack/Catalyst-Model-DBIC-Schema-0.20/lib/Catalyst/Helper/Model/DBIC/Schema.pm

The relevant excerpt:
create=static instructs this Helper to generate the named Schema class
for you, using DBIx::Class::Schema::Loader in "one shot" mode to
create a standard, manually-defined DBIx::Class::Schema setup, based
on what the Loader sees in your database at this moment. A
Schema/Model pair generated this way will not require
DBIx::Class::Schema::Loader at runtime, and will not automatically
adapt itself to changes in your database structure. You can edit the
generated classes by hand to refine them.

So, what we have is documentation to use
Catalyst::Helper::Model::DBIC::Schema or to use DBIx::Class directly
and the make_schema_at method.

If you'll note, Catalyst::Helper's pod, almost in entirety, is focused
on people writing generic model, view and controller classes - and not
for end users.  In fact, even in Catalyst::Manual::Cookbook the only
reference to DBIC is a link to Catalyst::Model::DBIC::Schema.  Further
reading of that page, in the description section, it hints at your
question:
"This is a Catalyst Model for DBIx::Class::Schema-based Models. See
the documentation for Catalyst::Helper::Model::DBIC::Schema for
information on generating these Models via Helper scripts."

The link there finally answers the specifics of the question on how to
generate DBIC classes from an existing database, and in very specific
detail.

It's unreasonable to expect Catalyst core documentation to reference
any specific model that may or may not be used.  Simply because
Catalyst and DBIC are most commonly used together does not mean that
the Catalyst community endorses DBIC as the only ORM.  If you ask our
advice, we will recommend it (more in the way of, if you don't know
why you should use it over others, you should use it).

Now, please note I'm not saying that search.cpan.org or Pod in its
current form is the best solution for documentation.  I think it could
use work, and that would help increase findability.  As always,
patches welcome and all that.  I just think that your patch is a
misguided attempt to help because you failed to read other relevant
documentation.  I don't want to discourage you from helping just
because I'm saying no, because there are other ways to address your
very valid issue of not finding the right information.

If you agree with me in my feelings that finding this information is
the issue, and not the location (and increasing where the information
is found is not a solution), perhaps the right solution is to submit
this on the wiki, or start a blog, or if you have one use a catalyst,
perl or dbic tag, write an article and then submit your blog to be
included on planet.catalystframework.org.  This is always preferable
than adding in more, and potentially irrelevant, documentation in an
area where it doesn't belong.

On the wiki, there is already a DBIC FAQ that would be the perfect location:
http://dev.catalystframework.org/dbicfaq

Thanks and I hope to see your contributions on the wiki,
-J



More information about the Catalyst mailing list