Index: trunk/lib/MP3/Find/DB.pm
===================================================================
--- trunk/lib/MP3/Find/DB.pm	(revision 33)
+++ trunk/lib/MP3/Find/DB.pm	(revision 34)
@@ -72,8 +72,17 @@
     
     # create another database
-    $finder->create_db('my_mp3s.db');
-    
-    # update the database from the filesystem
-    $finder->update_db('my_mp3s.db', ['/home/peter/mp3', '/home/peter/cds']);
+    $finder->create({ db_file => 'my_mp3s.db' });
+    
+    # update the database by searching the filesystem
+    $finder->update({
+	db_file => 'my_mp3s.db',
+	dirs => ['/home/peter/mp3', '/home/peter/cds'],
+    });
+
+    # or just update specific mp3s
+    $finder->update({
+	db_file => 'my_mp3s.db',
+	files => \@filenames,
+    });
     
     # and then blow it away
@@ -86,19 +95,10 @@
 =head1 DESCRIPTION
 
-This is the SQLite database backend for L<MP3::Find>.
-
-B<Note:> I'm still working out some kinks in here, so this backend
-is currently not as stable as the Filesystem backend.
-
-=head2 Special Options
-
-=over
-
-=item C<db_file>
-
-The name of the SQLite database file to use. Defaults to F<~/mp3.db>.
-
-The database should have at least one table named C<mp3> with the
-following schema:
+This is the database backend for L<MP3::Find>. The easiest way to
+use it is with a SQLite database, but you can also pass in your own
+DSN or database handle.
+
+The database you use should have at least one table named C<mp3> with 
+the following schema:
 
     CREATE TABLE mp3 (
@@ -133,11 +133,45 @@
     );
 
+B<Note:> I'm still working out some kinks in here, so this backend
+is currently not as stable as the Filesystem backend. Expect API
+fluctuations for now.
+
+B<Deprecated Methods:> C<create_db>, C<update_db>, and C<sync_db>
+have been deprectaed in this release, and will be removed in a future
+release. PLease switch to the new methods C<create>, C<update>, and
+C<sync>.
+
+=head2 Special Options
+
+When using this backend, provide one of the following additional options
+to the C<search> method:
+
+=over
+
+=item C<dsn>, C<username>, C<password>
+
+A custom DSN and (optional) username and password. This gets passed
+to the C<connect> method of L<DBI>.
+
+=item C<dbh>
+
+An already created L<DBI> database handle object.
+
+=item C<db_file>
+
+The name of the SQLite database file to use.
+
 =back
 
 =cut
 
+# get a database handle from named arguments
 sub _get_dbh {
     my $args = shift;
+
+    # we got an explicit $dbh object
     return $args->{dbh} if defined $args->{dbh};
+
+    # or a custom DSN
     if (defined $args->{dsn}) {
     	my $dbh = DBI->connect(
@@ -149,4 +183,5 @@
 	return $dbh;
     }
+    
     # default to a SQLite database
     if (defined $args->{db_file}) {
@@ -159,4 +194,5 @@
 	return $dbh;
     }
+
     return;
 }
@@ -182,6 +218,6 @@
 
 The C<status_callback> gets called each time an entry in the
-database is added, updated, or deleted by the C<update_db> and
-C<sync_db> methods. The arguments passed to the callback are
+database is added, updated, or deleted by the C<update> and
+C<sync> methods. The arguments passed to the callback are
 a status code (A, U, or D) and the filename for that entry.
 The default callback just prints these to C<STDERR>:
@@ -224,5 +260,5 @@
     $finder->create_db($db_filename);
 
-Creates a SQLite database in the file named c<$db_filename>.
+Creates a SQLite database in the file named C<$db_filename>.
 
 =cut
@@ -530,9 +566,7 @@
 =head1 TODO
 
-Database maintanence routines (e.g. clear out old entries)
-
-Allow the passing of a DSN or an already created C<$dbh> instead
-of a SQLite database filename; or write driver classes to handle
-database dependent tasks (create_db/destroy_db).
+Store/search ID3v2 tags
+
+Driver classes to handle database dependent tasks?
 
 =head1 SEE ALSO