[svn:dbi] r14093 - dbi/trunk

Author: timbo
Date: Wed Jun  2 02:14:57 2010
New Revision: 14093

Modified:
   dbi/trunk/Changes
   dbi/trunk/DBI.pm

Log:
Updated and clarified documentation for finish method.
Reordered Changes to approximately my Fixed/Changed/Added/Docs sequence style.


Modified: dbi/trunk/Changes
==============================================================================
--- dbi/trunk/Changes	(original)
+++ dbi/trunk/Changes	Wed Jun  2 02:14:57 2010
@@ -9,27 +9,30 @@
 =head2 Changes in DBI 1.612 (svn r14075) 28th May 2010
 
   Fixed DBD::DBM breakage with SQL::Statement (Jens Rehsack)
-  Fixed DBD::File leaks file handles (Jens Rehsack)
+  Fixed DBD::File file handle leak (Jens Rehsack)
+  Fixed problems in 50dbm.t when running tests with multiple
+    dbms (Martin J. Evans)
+  Fixed DBD::DBM bugs found during tests (Jens Rehsack)
 
+  Changed Makefile.PL to modernize with CONFLICTS, recommended dependencies
+    and resources (Jens Rehsack)
   Changed DBI::ProfileDumper to rename any existing profile file by
     appending .prev, instead of overwriting it.
   Changed DBI::ProfileDumper::Apache to work in more configurations
     including vhosts using PerlOptions +Parent.
-  Fixed problems in 50dbm.t when running tests with multiple
-    dbms (Martin J. Evans)
+
   Added more tests to 50dbm_simple.t to prove optimizations in
     DBI::SQL::Nano and SQL::Statement (Jens Rehsack)
   Updated tests to cover optional installed SQL::Statement (Jens Rehsack)
   Synchronize between SQL::Statement and DBI::SQL::Nano (Jens Rehsack)
   Added basic test for DBD::File (H. Merijn Brand)
-  Modernize Makefile.PL with CONFLICTS, recommended dependencies and
-    resources (Jens Rehsack)
+
+  Updated and clarified documentation for finish method (Tim Bunce).
   Changes to DBD::File for better English and hopefully better
     explanation (Martin J. Evans)
   Update documentation of DBD::DBM to cover current implementation,
     tried to explain some things better and changes most examples to
     preferred style of Merijn and myself (Jens Rehsack)
-  DBD::DBM fixes found during tests (Jens Rehsack)
 
 =head2 Changes in DBI 1.611 (svn r13935) 29th April 2010
 

Modified: dbi/trunk/DBI.pm
==============================================================================
--- dbi/trunk/DBI.pm	(original)
+++ dbi/trunk/DBI.pm	Wed Jun  2 02:14:57 2010
@@ -6381,28 +6381,27 @@
   $rc  = $sth->finish;
 
 Indicate that no more data will be fetched from this statement handle
-before it is either executed again or destroyed.  The C<finish> method
-is rarely needed, and frequently overused, but can sometimes be
-helpful in a few very specific situations to allow the server to free
-up resources (such as sort buffers).
-
-When all the data has been fetched from a C<SELECT> statement, the
-driver should automatically call C<finish> for you. So you should
-I<not> normally need to call it explicitly I<except> when you know
-that you've not fetched all the data from a statement handle.
-The most common example is when you only want to fetch one row,
-but in that case the C<selectrow_*> methods are usually better anyway.
-Adding calls to C<finish> after each fetch loop is a common mistake,
+before it is either executed again or destroyed.  You almost certainly
+do I<not> need to call this method.
+
+Adding calls to C<finish> after loop that fetches all rows is a common mistake,
 don't do it, it can mask genuine problems like uncaught fetch errors.
 
+When all the data has been fetched from a C<SELECT> statement, the driver will
+automatically call C<finish> for you. So you should I<not> call it explicitly
+I<except> when you know that you've not fetched all the data from a statement
+handle I<and> the handle won't be destroyed soon.
+
+The most common example is when you only want to fetch just one row,
+but in that case the C<selectrow_*> methods are usually better anyway.
+
 Consider a query like:
 
-  SELECT foo FROM table WHERE bar=? ORDER BY foo
+  SELECT foo FROM table WHERE bar=? ORDER BY baz
 
-where you want to select just the first (smallest) "foo" value from a
-very large table. When executed, the database server will have to use
+on a very large table. When executed, the database server will have to use
 temporary buffer space to store the sorted rows. If, after executing
-the handle and selecting one row, the handle won't be re-executed for
+the handle and selecting just a few rows, the handle won't be re-executed for
 some time and won't be destroyed, the C<finish> method can be used to tell
 the server that the buffer space can be freed.