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. _______________________________________________ List: http://lists.rawmode.org/cgi-bin/mailman/listinfo/dbix-class Wiki: http://dbix-class.shadowcatsystems.co.uk/ IRC: irc.perl.org#dbix-class SVN: http://dev.catalyst.perl.org/repos/bast/trunk/DBIx-Class/ Searchable Archive: http://www.mail-archive.com/[email protected]/
