--- PApp-SQL/SQL.pm	2001/12/31 03:01:49	1.18
+++ PApp-SQL/SQL.pm	2002/11/02 03:33:49	1.28
@@ -1,6 +1,6 @@
 =head1 NAME
 
-PApp::SQL - absolutely easy yet fast and powerful sql access
+PApp::SQL - absolutely easy yet fast and powerful sql access.
 
 =head1 SYNOPSIS
 
@@ -15,7 +15,7 @@
  my $a = sql_fetch "select a from ...";
  sql_fetch \my($a, $b), "select a,b ...";
 
- sql_exists "name from table where name like 'a%'"
+ sql_exists "table where name like 'a%'"
     or die "a* required but not existent";
 
  my $db = new PApp::SQL::Database "", "DBI:mysql:test", "user", "pass";
@@ -46,7 +46,7 @@
 BEGIN {
    use base qw(Exporter DynaLoader);
 
-   $VERSION = 0.1241;
+   $VERSION = 0.141;
    @EXPORT = qw(
          sql_exec  sql_fetch  sql_fetchall  sql_exists sql_insertid $sql_exec
          sql_uexec sql_ufetch sql_ufetchall sql_uexists
@@ -71,15 +71,14 @@
 =item $sql_exec
 
 Since the C<sql_exec> family of functions return a statement handle there
-must eb another way to test the return value of the C<execute> call. This
+must be another way to test the return value of the C<execute> call. This
 global variable contains the result of the most recent call to C<execute>
 done by this module.
 
 =item $PApp::SQL::DBH
 
 The default database handle used by this module if no C<$DBH> was
-specified as argument and no C<$DBH> is found in the current package. See
-C<sql_exec> for a discussion.
+specified as argument. See C<sql_exec> for a discussion.
 
 =item $PApp::SQL::Database
 
@@ -113,8 +112,8 @@
 The reason C<$id> is necessary is that you might specify special connect
 arguments or special flags, or you might want to configure your $DBH
 differently than maybe other applications requesting the same database
-connection. If none of this is becessary for your application you can
-leave $id empty (i.e. "").
+connection. If none of this is necessary for your application you can
+leave C<$id> empty (i.e. "").
 
 If specified, C<$connect> is a callback (e.g. a coderef) that will be
 called each time a new connection is being established, with the new
@@ -125,8 +124,8 @@
  # try your luck opening the papp database without access info
  $dbh = connect_cached __FILE__, "DBI:mysql:papp";
 
-Mysql-specific behaviour: The default setting of mysql_client_found_rows
-is TRUE, you can overwrite this, though.
+Mysql-specific behaviour: The default setting of
+C<mysql_client_found_rows> is TRUE, you can overwrite this, though.
 
 =cut
 
@@ -165,12 +164,23 @@
 called only once for each distinct sql call (please keep in mind that the
 returned statement will always be the same, so, if you call C<sql_exec>
 with the same dbh and sql-statement twice (e.g. in a subroutine you
-called), the statement handle for the first call mustn't be used.
+called), the statement handle for the first call mustn't not be in use
+anymore, as the subsequent call will re-use the handle.
 
 The database handle (the first argument) is optional. If it is missing,
-C<sql_exec> first tries to use the variable C<$DBH> in the current (=
-calling) package and, if that fails, it tries to use database handle in
-C<$PApp::SQL::DBH>, which you can set before calling these functions.
+it tries to use database handle in C<$PApp::SQL::DBH>, which you can set
+before calling these functions. NOTICE: future and former versions of
+PApp::SQL might also look up the global variable C<$DBH> in the callers
+package.
+
+=begin comment
+
+If it is missing, C<sql_exec> first tries to use the variable C<$DBH>
+in the current (= calling) package and, if that fails, it tries to use
+database handle in C<$PApp::SQL::DBH>, which you can set before calling
+these functions.
+
+=end comment
 
 The actual return value from the C<$sth->execute> call is stored in the
 package-global (and exported) variable C<$sql_exec>.
@@ -222,7 +232,9 @@
 ... and it's still quite fast unless you fetch large amounts of data.
 
 C<sql_ufetch> is similar to C<sql_fetch> but upgrades all input values to
-utf8 and forces all result values to utf8.
+utf8 and forces all result values to utf8 (this does I<not> include result
+parameters, only return values. Using bind variables in cinjunction with
+sql_u* functions results in undefined behaviour).
 
 =item sql_fetchall <see sql_exec>
 
@@ -249,9 +261,10 @@
  }
 
 C<sql_ufetchall> is similar to C<sql_fetchall> but upgrades all input
-values to utf8 and forces all result values to utf8.
+values to utf8 and forces all result values to utf8 (see the caveats in
+the description of C<sql_ufetch>, though).
 
-=item sql_exists "<table> where ...", args...
+=item sql_exists "<table_references> where <where_condition>...", args...
 
 =item sql_uexists <see sql_exists>
 
@@ -307,7 +320,7 @@
 
 Returns (and possibly changes) the LRU cache size used by C<sql_exec>. The
 default is somewhere around 50 (= the 50 last recently used statements
-will be cached). It shouldn't be too large, since a simple linear listed
+will be cached). It shouldn't be too large, since a simple linear list
 is used for the cache at the moment (which, for small (<100) cache sizes
 is actually quite fast).
 
@@ -405,7 +418,7 @@
 
 =item $db->password
 
-Return the password (emphasizing the fact that the apssword is stored plaintext ;)
+Return the password (emphasizing the fact that the password is stored plaintext ;)
 
 =cut