document callbacks

2 files changed, 29 insertions, 0 deletions

diff --git a/NEWS b/NEWS
index 36a1ec6..6966129 100644
--- a/NEWS
+++ b/NEWS
@@ -1,3 +1,5 @@
+- enhanced doc
+
 Version 4.23 - 20 January 2012
 
 - fix scoring locale packages
diff --git a/URPM.pm b/URPM.pm
index c680435..f980773 100644
--- a/URPM.pm
+++ b/URPM.pm
@@ -334,6 +334,8 @@ where epoch, version and release are RPM-style version numbers.
 This method gets the B<depslist> and the B<provides> from a synthesis file
 and adds them to the URPM object.
 
+Callback signature is callback(C<URPM>, C<URPM::Package>).
+
 The return value is a two-element array containing the first and the last id
 parsed.
 
@@ -346,6 +348,8 @@ file and adds them to the URPM object. Allowed options are
     callback => sub { ... }
     keep_all_tags => 0 / 1
 
+Callback signature is callback(C<URPM>, C<URPM::Package>).
+
 The return value is a two-element array containing the first and the last id
 parsed.
 
@@ -361,6 +365,8 @@ and adds them to the URPM object. Allowed options are
 If C<keep_all_tags> isn't specified, URPM will drop all memory-consuming tags
 (notably changelogs, filelists, scriptlets).
 
+Callback signature is callback(URPM::Package).
+
 =item $urpm->packages_providing($name)
 
 Returns a list of C<URPM::Package> providing <$name>
@@ -393,6 +399,8 @@ $names is a reference to an array, holding the acceptable values of the said
 tag for the searched variables.
 Then, $callback is called for each matching package in the depslist.
 
+Callback signature is callback(URPM::Package).
+
 This is used when faking a URPM::DB: $urpm can be used as-a $db
 
 =item $urpm->traverse_tag_find($tag,$name,$callback)
@@ -401,6 +409,8 @@ Quite similar to C<traverse_tag>, but stops when $callback returns true.
 
 (also note that only one $name is handled)
 
+Callback signature is callback(URPM::Package).
+
 This is used when faking a URPM::DB: $urpm can be used as-a $db
 
 =item URPM::verify_rpm($file, %options)
@@ -470,6 +480,8 @@ $names is a reference to an array, holding the acceptable values of the said
 tag for the searched variables.
 Then, $callback is called for each matching package in the DB.
 
+Callback signature is callback(URPM::Package).
+
 Returns the number of packages seen (all those that matched provided names).
 
 =item $db->traverse_tag_find($tag,$name,$callback)
@@ -478,6 +490,8 @@ Quite similar to C<traverse_tag>, but stops when $callback returns true.
 
 (also note that only one $name is handled)
 
+Callback signature is callback(URPM::Package).
+
 Returns whether callback returned true once.
 
 =item $db->create_transaction()
@@ -760,6 +774,7 @@ list context, returns an array of problems (an empty array indicates success).
 Runs the transaction.
 
 $data is an arbitrary user-provided piece of data to be passed to callbacks.
+It's usually the $urpm object.
 
 Recognized options are:
 
@@ -780,6 +795,18 @@ Recognized options are:
 
 They roughly correspond to command-line options to rpm(1).
 
+'callback_open' signature is (C<$data>, C<$cb_type>, C<$pkg_id>). It _must_ return a file handler for the asked package.
+
+'callback_close' signature is (C<$data>, C<$cb_type>, C<$pkg_id>). It is called just before URPM close the fd for the installed package.
+
+C<$cb_type> is one of 'open' or 'close'.
+
+Other Callbacks signature is callback(C<$data>, C<$cb_type>, C<$pkg_id>, C<$subtype>, C<$amout>, C<$total>)
+
+C<$cb_type> is one of 'inst', 'trans' or 'uninst'. C<$subtype> can be 'start', 'progress' or 'stop'.
+
+The purpose of those callbacks is to report progress (the two last parameters (C<$amount> & C<$total>) enable to compute progress percentage).
+
 =item $trans->traverse($callback)
 
 Executes the specified callback (a code reference) for each package in the