| Subject: | confusing bits in DBIx::Class::Manual::Intro [2] |
Further comments and questions.
"Let's look at how you can set and use your first native DBIx::Class
tree."
I know what this talks about, but a newbie likely won't understand
that. This sentence could use an explanation ahead of it that explains
how a group of tables is taken together and represented in a scheme,
which is defined in a tree of perl modules.
"In this class you load your result_source ("table", "model") classes,
which we will define later, using the load_namespaces() method:"
I don't udnerstand why there is table/model in parens. The whole
sentence reads like it was written by a german. Could be split in two
sentences.
"# load My::Schema::Result::* and their resultset classes"
Would be easier understandable as:
# load My::Schema::Result::* and My::Schema::ResultSet::* classes
"By default this loads all the Result (Row) classes"
It was said earlier that Result classes are tables.
"any resultset classes in the My::Schema::ResultSet:: namespace"
At this point i realized that nothing in the text explained ResultSet
classes separated from the anonymously generated result sets made with
search and friends.
"(if missing, the resultsets are defaulted to be DBIx::Class::ResultSet
objects)"
It's unclear what this is meant to mean. Does it point out that
anonymously generated result sets are DBIx::Class::ResultSet by
default? Could be clarified or removed.
"Next, create each of the classes you want to load as specified above:"
Had to read that twice, maybe replace with: "Next, create each of the
classes you want to the schema specified above to load:"
"Load any additional components"
Said without explaining what a component is. Also, is the ordering of
that section that way because components need to be loaded before the
table name or the columns are defined? If not, it should probably go to
the bottom. I don't think the explanation of what exactly the component
Ordered does is very useful and that it should instead link to the
module itself.
"DBIx::Class doesn't directly use most of this data yet"
"See DBIx::Class::ResultSource for more details of the possible column
attributes."
The former bit should contain a link to https://metacpan.org/module/
DBIx::Class::ResultSource#add_columns because it answer the immediate
question: "Is there a list of what data DBIC cares about?"
"either belongs_to to describe a column which contains an ID of another
Table, or has_many to make a predefined accessor"
Doesn't belongs_to also create an accessor? This paragraph is pretty
good already, but i think it would be improved by being clear about
both belongs_to and has_many creating an accessor which returns results
from the related tables.
"that contain this Table's foreign key:"
I suppose this means "that contain this table's primary key as a
foreign key:"? Why is table capitalized?