| 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.
Under https://metacpan.org/module/DBIx::Class::Manual::Intro#Tables-become-Result-classes the 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 https://metacpan.org/module/DBIx::Class::Manual::Intro#Its-all-about-the-ResultSet 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.