|Subject:||confusing bits in DBIx::Class::Manual::Intro |
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 toDBIx::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?