[Dbix-class] some suggestions about the DBIx::Class documentation

[Marc Espie]

I've been slowly learning to use DBIx::Class, with a lot of issues...

One big problem I've had is that the documentation is trying to be
everything at once, and is poorly organized in my opinion.

Please take the following comments as  positive criticism. I'm very
happy to have DBIx::Class around as compared to `raw' DBI stuff.


If I start with the DBIx::Class manpage, I will see a generic synopsis,
and then tendrils all over the place to all kinds of pages, which
(more or less) all mix reference documentation, examples, AND tendrils
to other stuff like C3::Class or SQL::Abstract.

If you haven't worked with any of this stuff, even if you know basic
perl really good, it's a bit hard to `jump in'.

I believe that the documentation could be improved by being a bit more
segregated, with reference on one side, and examples on the other.

Personally, I have a lot of trouble finding some of the information. I've
had to experiment, read the whole documentation, and look at the source
to find some specific examples...

- it would be cool to have a reference page to all DBIx::Class objects.
A thingy which explains DBIx::Class::ResultSet, ResultSource, Schema,
Relationship, and all the things I'm missing.

- the types of things are not sufficiently explained. For instance, if
I look into DBIx::Class::ResultSet, I can't figure out what the create
method returns. If returns an object, but of what type ?
Is this a class I'm going to find in my Schema ? If so, what are the
applicable methods ?

- I'd like a summary of callable methods with corresponding homes. Unless
you know the documentation fairly well, figuring out from load_components
what  is provided by Core is not really easy.  Especially since this
includes both object methods (the Row stuff), and class methods (Relationship
and friends).

Okay, reading the documentation again while writing this thing, I've figured
out that $object is a DBIx::Class::Row, among other things.  So, that should
probably be in the documentation (possibly as a DBIx::Class::Object manpage).

One thing which is a bit confusing is that database classes contain both
row_object definitions and schema meta-data stuff.  Maybe there is a
non-obvious benefit from it, but it looks to me like there should be
two separate class hierarchies with correspondences... A row object and a
relationship are not the same thing to me. As far as I'm concerned, this
adds to the confusion.

I'm also not quite clear about the storage stuff.

I understand that there are several layers to DBIx::Class, that's just fine
for people who need the control. On the other hand, I believe the current
class organization, and the documentation exposes too many details from all
layers for every user.


I expect that, as I get more proficient with DBIx::Class, a lot of these
details will become natural.   But I wanted to write this from the
perspective of a relative newcomer... I think the learning curve is fairly
steep and could be a little better.