--- BDB/BDB.pm	2008/07/08 08:35:12	1.40
+++ BDB/BDB.pm	2008/07/09 12:15:36	1.41
@@ -162,15 +162,37 @@
 C<U32> is an unsigned 32 bit integer, C<int> is some integer, C<NV> is a
 floating point value.
 
-The C<SV *> types are generic perl scalars (for input and output of data
-values), and the C<SV *callback> is the optional callback function to call
-when the request is completed.
+Most C<SV *> types are generic perl scalars (for input and output of data
+values).
 
 The various C<DB_ENV> etc. arguments are handles return by
 C<db_env_create>, C<db_create>, C<txn_begin> and so on. If they have an
 appended C<_ornull> this means they are optional and you can pass C<undef>
 for them, resulting a NULL pointer on the C level.
 
+The C<SV *callback> is the optional callback function to call when the
+request is completed. This last callback argument is special: the callback
+is simply the last argument passed. If there are "optional" arguments
+before the callback they can be left out. The callback itself can be left
+out or specified as C<undef>, in which case the function will be executed
+synchronously.
+
+For example, C<db_env_txn_checkpoint> usually is called with all integer
+arguments zero. These can be left out, so all of these specify a call
+to C<< DB_ENV->txn_checkpoint >>, to be executed asynchronously with a
+callback to be called:
+
+   db_env_txn_checkpoint $db_env, 0, 0, 0, sub { };
+   db_env_txn_checkpoint $db_env, 0, 0, sub { };
+   db_env_txn_checkpoint $db_env, sub { };
+
+While these all specify a call to C<< DB_ENV->txn_checkpoint >> to be
+executed synchronously:
+
+   db_env_txn_checkpoint $db_env, 0, 0, 0, undef;
+   db_env_txn_checkpoint $db_env, 0, 0, 0;
+   db_env_txn_checkpoint $db_env, 0;
+
 =head3 BDB functions
 
 Functions in the BDB namespace, exported by default: