doc updates and bump version for new release

Changes

@@ -1,5 +1,10 @@
 Revision history for Perl extension DBIx::DataModel.
 
+v2.09 21.01.2012
+  - error message when wrong call to $schema->Table(..)
+  - error message when wrong call to ->do_transaction(sub {...})
+  - update() accepts refs to refs or scalars for verbatim SQL
+
 v2.08 18.12.2011
   - forgot to declare use POSIX qw/LONG_MAX/ -- buggy on Perl 5.8
 

MANIFEST

@@ -42,3 +42,4 @@ t/v1_ParentClasses.t
 t/v1_Storable.t
 t/v2_multischema.t
 t/v2_paths.t
+t/v2_update.t

lib/DBIx/DataModel.pm

@@ -8,7 +8,7 @@ use warnings;
 use strict;
 use MRO::Compat  (); # don't want to call MRO::Compat::import()
 
-our $VERSION = '2.08';
+our $VERSION = '2.09';
 
 # compatibility setting : see import(); for the moment, automatic compat 1.0
 our $COMPATIBILITY = 1.0;
@@ -449,6 +449,33 @@ into an array (they must be used immediately) :
   }
 
 
+=head3 Update
+
+  # update on a set of fields, primary key included
+  my $table = $schema->table($table_name);
+  $table->update({pk_field => $pk, field1 => $val1, field2 => $val2, ...});
+
+  # update on a set of fields, primary key passed separately
+  $table->update(@primary_key, {field1 => $val1, field2 => $val2, ...});
+
+  # bulk update
+  $table->update(-set   => {field1 => $val1, field2 => $val2, ...}
+                 -where => \%condition);
+
+  # invoking instances instead of table classes
+  $obj->update({field1 => $val1, ...}); # updates specified fields
+  $obj->update;                         # updates all fields stored in memory
+
+
+=head3 Delete
+
+  # invoking a table class
+  my $table = $schema->table($table_name);
+  $table->delete(@primary_key);
+
+  # invoking an instance
+  $obj->delete;
+
 
 =head1 DESCRIPTION
 

lib/DBIx/DataModel/Doc/Design.pod

@@ -1476,7 +1476,6 @@ Here is a list of points to improve in future versions C<DBIx::DataModel> :
   - declare RT bug for Params::Validate : doc is confused about
     validate_with / validation_options
 
-
   - savepoints
 
   - various policies for guessing foreign keys : e.g proc.id = attr.proc_id

lib/DBIx/DataModel/Doc/Reference.pod

@@ -1493,12 +1493,14 @@ is raw data that did not transit through Perl objects.
 
 =item * 
 
-the second syntax is used for updating a single
-record. A C<-where> clause will be automatically generated
-by extracting the primary key column(s) from the record;
-then the remaining columns are treated as the columns to update.
-Before calling the database, the C<to_DB> handlers are applied, 
-and the C<no_update> columns are removed.
+the second syntax is used for updating a single record, passed as a
+hashref; it does not matter if this hashref is blessed or not, because
+a copy will be blessed into the class of the invocant. 
+A C<-where> clause will be automatically generated by extracting the
+primary key column(s) from the record; then the remaining columns are
+treated as the columns to update.  Before calling the database, the
+C<to_DB> handlers are applied, and the C<no_update> columns are
+removed.
 
 =item * 
 
@@ -2477,18 +2479,34 @@ distinguish between an invalid existent column and a missing column.
 =head3 Table::update()
 
   $source_class->update(@update_args);
+  $source_instance->update({field1 => $val1, ...});
   $source_instance->update();
 
-Both a class and an instance method, that 
+
+This is both a class and an instance method, that 
 implicitly creates a a connected source from  the source's schema
 and meta-source, and then calls the C<update()> method on that 
-statement. 
+connected source. 
+
+When used as a class method, the argument syntax is exactly like
+for L<Connected_source::update()|update>.
+
+When used as an instance method with arguments, this is equivalent to 
+
+  $connected_source->update($source_instance->primary_key,
+                            {field1 => $val1, ...});
+
+in other words, the invocant is only used for taking
+its primary key, and the updated fields are passed
+as an argument hashref.
+
+
+When used as an instance method without arguments, this is equivalent to
 
-When used as an instance method, passes the object itself
-as argument to update(), so that the database will be updated
-from the column values stored in memory within the object
-(ignoring all non-scalar values). 
+  $connected_source->update($source_instance);
 
+in other words, the updated fields are all column values stored 
+in memory within the object (ignoring all non-scalar values). 
 
 
 =head2 Table::delete()