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
MIME-Version: 1.0
Content-Type: text/plain; charset="UTF-8"
X-Mailer: MIME-tools 5.427 (Entity 5.427)
Content-Disposition: inline
Content-Transfer-Encoding: binary
X-RT-Original-Encoding: utf-8
X-RT-Encrypt: 0
X-RT-Sign: 0
Content-Length: 1695
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.
MIME-Version: 1.0
X-Mailer: MIME-tools 5.427 (Entity 5.427)
Content-Disposition: inline
Content-Type: text/plain; charset="UTF-8"
Message-ID: <rt-3.8.HEAD-16522-1363201899-138.83767-0-0 [...] rt.cpan.org>
Content-Transfer-Encoding: binary
X-RT-Original-Encoding: utf-8
Content-Length: 266
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.
MIME-Version: 1.0
In-Reply-To: <rt-3.8.HEAD-16522-1363201899-138.83767-0-0 [...] rt.cpan.org>
X-Mailer: MIME-tools 5.427 (Entity 5.427)
Content-Disposition: inline
References: <rt-3.8.HEAD-16522-1363201899-138.83767-0-0 [...] rt.cpan.org>
Content-Type: text/plain; charset="UTF-8"
Message-ID: <rt-3.8.HEAD-26854-1363261016-1256.83767-0-0 [...] rt.cpan.org>
Content-Transfer-Encoding: binary
X-RT-Original-Encoding: utf-8
Content-Length: 223
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. :)
From rabbit [...] rabbit.us Thu Mar 14 07: 55:21 2013
MIME-Version: 1.0
X-Spam-Status: No, score=-6.9 tagged_above=-99.9 required=10 tests=[BAYES_00=-1.9, RCVD_IN_DNSWL_HI=-5] autolearn=ham
In-Reply-To: <rt-3.8.HEAD-26854-1363261017-694.83767-5-0 [...] rt.cpan.org>
Content-Disposition: inline
X-Spam-Flag: NO
References: <RT-Ticket-83767 [...] rt.cpan.org> <rt-3.8.HEAD-16522-1363201899-138.83767-5-0 [...] rt.cpan.org> <rt-3.8.HEAD-26854-1363261017-694.83767-5-0 [...] rt.cpan.org>
X-Virus-Scanned: Debian amavisd-new at bestpractical.com
Message-ID: <20130314115503.GA14726 [...] rabbit.us>
Content-Type: text/plain; charset="utf-8"
X-RT-Original-Encoding: utf-8
X-Spam-Score: -6.9
Received: from localhost (localhost [127.0.0.1]) by hipster.bestpractical.com (Postfix) with ESMTP id BDA462406BF for <cpan-bug+DBIx-Class [...] hipster.bestpractical.com>; Thu, 14 Mar 2013 07:55:21 -0400 (EDT)
Received: from hipster.bestpractical.com ([127.0.0.1]) by localhost (hipster.bestpractical.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id 3qxmVeMb9Qap for <cpan-bug+DBIx-Class [...] hipster.bestpractical.com>; Thu, 14 Mar 2013 07:55:16 -0400 (EDT)
Received: from la.mx.develooper.com (x1.develooper.com [207.171.7.70]) by hipster.bestpractical.com (Postfix) with SMTP id D29D324055E for <bug-DBIx-Class [...] rt.cpan.org>; Thu, 14 Mar 2013 07:55:14 -0400 (EDT)
Received: (qmail 16194 invoked by uid 103); 14 Mar 2013 11:55:14 -0000
Received: from x16.dev (10.0.100.26) by x1.dev with QMQP; 14 Mar 2013 11:55:14 -0000
Received: from mujunyku.leporine.io (HELO mujunyku.leporine.io) (113.212.96.195) by 16.mx.develooper.com (qpsmtpd/0.84/v0.84-167-g4ed6cab) with ESMTP; Thu, 14 Mar 2013 04:55:08 -0700
Received: by mujunyku.leporine.io (Postfix, from userid 1000) id 917DC228160; Thu, 14 Mar 2013 22:55:03 +1100 (EST)
Delivered-To: cpan-bug+DBIx-Class [...] hipster.bestpractical.com
Subject: Re: [rt.cpan.org #83767] confusing bits in DBIx::Class::Manual::Intro
User-Agent: Mutt/1.5.20 (2009-06-14)
Return-Path: <rabbit [...] rabbit.us>
X-Spam-Check-BY: 16.mx.develooper.com
X-Original-To: cpan-bug+DBIx-Class [...] hipster.bestpractical.com
X-RT-Mail-Extension: dbix-class
Date: Thu, 14 Mar 2013 22:55:03 +1100
X-Spam-Level:
To: Christian Walde via RT <bug-DBIx-Class [...] rt.cpan.org>
From: Peter Rabbitson <ribasushi [...] cpan.org>
RT-Message-ID: <rt-3.8.HEAD-29420-1363262122-905.83767-0-0 [...] rt.cpan.org>
Content-Length: 774
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.