Merge 'DBIx-Class-current' into 'find_compat'

diff --combined lib/DBIx/Class/ResultSet.pm
index 82382d3,cc0d1ef..b2fa44e
--- 1/lib/DBIx/Class/ResultSet.pm
--- 2/lib/DBIx/Class/ResultSet.pm
+++ b/lib/DBIx/Class/ResultSet.pm
@@@ -6,7 -6,6 +6,7 @@@ use overloa
          '0+'     => \&count,
          'bool'   => sub { 1; },
          fallback => 1;
 +use Carp::Clan qw/^DBIx::Class/;
  use Data::Page;
  use Storable;
  use Data::Dumper;
@@@ -304,8 -303,7 +304,8 @@@ sub find 
      @{$hash}{@cols} = @_;
    }
    elsif (@_) {
 -    # For backwards compatibility
 +    # Compatibility: Allow e.g. find(id => $value)
 +    carp "find by key => value deprecated; please use a hashref instead";
      $hash = {@_};
    }
    else {
@@@ -319,8 -317,9 +319,8 @@@
    my @constraint_names = exists $attrs->{key}
      ? ($attrs->{key})
      : $self->result_source->unique_constraint_names;
 -  $self->throw_exception(
 -    "Can't find unless a primary key or unique constraint is defined"
 -  ) unless @constraint_names;
 +  carp "find now requires a primary key or unique constraint; none is defined on "
 +    . $self->result_source->name unless @constraint_names;
  
    my @unique_queries;
    foreach my $name (@constraint_names) {
@@@ -336,13 -335,6 +336,13 @@@
      push @unique_queries, $unique_query if %$unique_query;
    }
  
 +  # Compatibility: if we didn't get a unique query, take what the user provided
 +  if (%$hash and not @unique_queries) {
 +    carp "find now requires values for the primary key or a unique constraint"
 +      . "; please use the search method instead";
 +    push @unique_queries, $hash;
 +  }
 +
    # Handle cases where the ResultSet already defines the query
    my $query = @unique_queries ? \@unique_queries : undef;
  
@@@ -1523,6 -1515,11 +1523,11 @@@ Which column(s) to order the results by
  through directly to SQL, so you can give e.g. C<year DESC> for a
  descending order on the column `year'.
  
+ Please note that if you have quoting enabled (see 
+ L<DBIx::Class::Storage/quote_char>) you will need to do C<\'year DESC' > to
+ specify an order. (The scalar ref causes it to be passed as raw sql to the DB,
+ so you will need to manually quote things as appropriate.)
+ 
  =head2 columns
  
  =over 4
@@@ -1739,7 -1736,9 +1744,9 @@@ with an accessor type of 'single' or 'f
  
  Makes the resultset paged and specifies the page to retrieve. Effectively
  identical to creating a non-pages resultset and then calling ->page($page)
- on it.
+ on it. 
+ 
+ If L<rows> attribute is not specified it defualts to 10 rows per page.
  
  =head2 rows
  
@@@ -1752,6 -1751,17 +1759,17 @@@
  Specifes the maximum number of rows for direct retrieval or the number of
  rows per page if the page attribute or method is used.
  
+ =head2 offset
+ 
+ =over 4
+ 
+ =item Value: $offset
+ 
+ =back
+ 
+ Specifies the (zero-based) row number for the  first row to be returned, or the
+ of the first row of the first page if paging is used.
+ 
  =head2 group_by
  
  =over 4