Skip Menu |
 

This queue is for tickets about the DBIx-Class CPAN distribution.

Report information
The Basics
Id: 83767
Status: open
Priority: 0/
Queue: DBIx-Class

People
Owner: Nobody in particular
Requestors: MITHALDU [...] cpan.org
Cc:
AdminCc:

Bug Information
Severity: (no value)
Broken in: (no value)
Fixed in: (no value)



Subject: confusing bits in DBIx::Class::Manual::Intro
Download (untitled) / with headers
text/plain 1.6k
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.
Download (untitled) / with headers
text/plain 266b
Looking at this POD right now. Yeah, it's kinda messy, IMO, and needs at least some refactoring. I think the general structure is okay, but I'm going to audit through this doc to see where it can stand to use some linkbacks, better explanations, and re-wording.
Download (untitled) / with headers
text/plain 223b
Getty informed already that work on the manual is being thought/talked about, but a public answer is much appreciated, especially when it seems to be aimed exactly right. Thank you. I look forward to seeing revisions. :)
Subject: Re: [rt.cpan.org #83767] confusing bits in DBIx::Class::Manual::Intro
Date: Thu, 14 Mar 2013 22:55:03 +1100
To: Christian Walde via RT <bug-DBIx-Class [...] rt.cpan.org>
From: Peter Rabbitson <ribasushi [...] cpan.org>
Download (untitled) / with headers
text/plain 774b
On Thu, Mar 14, 2013 at 07:36:59AM -0400, Christian Walde via RT wrote: Show quoted text
> Queue: DBIx-Class > Ticket <URL: https://rt.cpan.org/Ticket/Display.html?id=83767 > > > Getty informed already that work on the manual is being thought/talked > about, but a public answer is much appreciated, especially when it seems > to be aimed exactly right. Thank you. I look forward to seeing revisions. > :)
When a ticket seems to be stalling - please do speak up to repoke the folks who are supposed to work on it. I myself did not answer because there is nothing I can really say/do about the problem at hand. There are however another 4-5 people that actually can do something much more constructive given they are sufficiently annoyed. Hence continuous poking == good ;)


This service is sponsored and maintained by Best Practical Solutions and runs on Perl.org infrastructure.

Please report any issues with rt.cpan.org to rt-cpan-admin@bestpractical.com.