|Subject:||confusing bits in DBIx::Class::Manual::Intro|
I'm reading the docs now and will make tickets with things i notice as i go along. Please view these as questions and suggestions, since my interpretation of the docs might be way off. Underthe document talks about "Result classes" and mentions offhand that "classes are defined by calling methods proxied to DBIx::Class::ResultSource". With my experience i can guess that this means "classes are defined by using setup helper methods inherited from D::C::R", but i'm fairly sure the current wording simply means nothing to quite a few newbies. Additionally the very next section drops the notion of "Result classes" and instead talks about "ResultSources". That seems to be a historical thing and should be normalized. "Now, we want to actually use those definitions to help us translate the queries we need into handy perl objects!" Honestly, i have no idea what this means. "the results of: [...] Would be retrieved by creating a ResultSet object from the album table's ResultSource, likely by using the "search" method." Shouldn't this say "... and calling a result retrieval method on the ResultSet object, like next or all."? "Any time you would reach for a SQL query in DBI, you are creating a DBIx::Class::ResultSet." Wouldn't this be better worded as: "Instead of writing queries manually, you ask a ResultSet object to generate them." "Rows of the search from the database are blessed into Result objects." While that is correct, the bless bit could be removed i think to lower cognitive overhead.