[DBIx-Class-Devel] doc fixes

[Peter Rabbitson]

On Fri, Dec 07, 2012 at 03:28:00PM -0500, Brendan Byrd wrote:
> On Tue, Dec 4, 2012 at 4:49 AM, Peter Rabbitson <rabbit+dbic at rabbit.us> wrote:
> > On Tue, Dec 04, 2012 at 12:11:05AM -0500, Brendan Byrd wrote:
> >>
> >> It's not.  I specifically split rs_doc_fix2 into these two separate
> >> topics because the
> >> response I got from that former topic was something to the effect of "omg, too
> >> much stuff here".
> >
> > It... is. The bulk of 383211ab7 is contained in 03bf20842a. In
> > particular Relationship::Base/$relationship_accessor and the NOTE on top
> > of ::Row are in both commits, with minor differences. Please double
> > check.
> 
> I see those.  I'll use doc_fixes as the source for those and remove it
> on the other
> side.  I think this was caused by rebasing on the current master for
> both, and since
> the change doesn't exist on master, it ends up adding the para to
> both.  I'll just
> rebase the PI branch with doc_fixes, since that'll be the logical flow, anyway.
> 
> BTW, Castaway's issue with that INHERITED METHODS reference is only on the
> PI branch.
> 
> Riba, you good with merging doc_fixes into master now?
> 

No :) I merged the authorship update d77f6ff82[1], but 383211ab7 has a
bunch of problems without its other sibling:

- lib/DBIx/Class/Core.pm refers to a not-yet existing class
- You were going to clarify the blurb about why one should prefer
  $column_accessor with mst and/or abraxxa (see last section of [2]). 
  The way it is worded   currently makes no sense. Also "this will not
  store the data" is better written as "commit to storage" or something
  like that - it does store the data in the object obv.
- The id() documentation is removed from Row before the PI stuff is available
  This is a rather "hot" method, I rather we not have releases where it is
  hard to find its docs

So I left this commit out - either update it individually for merge, or fold
it into your PI work.

There are also some inconsistencies in the =head1 NOTE, especuially the
"should inherit from Core" part. Here is a version that feels more factually
correct to me - incorporate whatever you deem useful.

======================

=head2 Note on class contents

All "Row objects" derived from a Schema-attached L<DBIx::Class::ResultSet>
object (such as a typical C<< L<search|DBIx::Class::ResultSet/search
>->L<next|DBIx::Class::ResultSet/next> >> call) are actually Result
instances, based on your application's
L<Result class|DBIx::Class::Manual::Glossary/Result_class>.
  
L<DBIx::Class::Row> implements most of the row-based communication with the
underlying storage, but a Result class B<should not inherit from it directly>.
Usually Result classes inherit from L<DBIx::Class::Core>, which in turn
combines the methods from several classes, one of them being
L<DBIx::Class::Row>. Therefore, while many of the methods available to a
L<DBIx::Class::Core>-derived Result class are described in the following
documentation, it does not detail all of the methods available to Result
objects. Refer to L<DBIx::Class::Core> for more info.

=======================

Cheers

[1] I wasn't sure if you cleared this change with mst or not (after all 
it is his copyright you are removing, but Getty told me he took care of 
that.

[2] http://lists.scsys.co.uk/cgi-bin/mailman/private/dbix-class-devel/2012-December/000130.html