document some functions

9 files changed, 193 insertions, 4 deletions

diff --git a/NEWS b/NEWS
index 3cb93a09..68a141af 100644
--- a/NEWS
+++ b/NEWS
@@ -1,4 +1,6 @@
 - fix testsuite
+- library:
+  o enhanced doc
 - security:
   o downgrade missing medium key check question to a warning for virtual media
     without keys when using urpmi --use-distrib
diff --git a/urpm/cdrom.pm b/urpm/cdrom.pm
index 3c6d1f48..32362a9f 100644
--- a/urpm/cdrom.pm
+++ b/urpm/cdrom.pm
@@ -220,6 +220,12 @@ sub _copy_from_cdrom__if_needed {
 	}
 }
 
+
+=item copy_packages_of_removable_media($urpm, $blists, $sources, $o_ask_for_medium)
+
+=cut
+
+
 #- side-effects:
 #-   + those of _may_eject_cdrom ($urpm->{cdrom_mounted}, "hal_umount", "hal_eject")
 #-   + those of _mount_cdrom ($urpm->{cdrom_mounted}, $blists->[_]{medium}{mntpoint}, "hal_mount", "hal_eject")
diff --git a/urpm/download.pm b/urpm/download.pm
index a493bde3..9cc6f555 100644
--- a/urpm/download.pm
+++ b/urpm/download.pm
@@ -35,6 +35,8 @@ urpm::download - download routines for the urpm* tools
 
 =head1 DESCRIPTION
 
+=over
+
 =cut
 
 
@@ -842,6 +844,12 @@ sub sync_logger {
     }
 }
 
+=item requested_ftp_http_downloader($urpm, $medium)
+
+Return the downloader program to use (whether it pas provided on the
+command line or in the config file).
+
+=cut
 
 sub requested_ftp_http_downloader {
     my ($urpm, $medium) = @_;
@@ -917,6 +925,12 @@ sub sync_rel_one {
     $files->[0];
 }
 
+=item sync_url($urpm, $url, %options)
+
+Retrieve a file from the network and return the local cached file path.
+
+=cut
+
 sub sync_url {
     my ($urpm, $url, %options) = @_;
     sync_rel_one($urpm, { url => dirname($url), disable_metalink => $options{disable_metalink} }, basename($url), %options);
@@ -945,6 +959,13 @@ sub sync {
     1;
 }
 
+
+=item get_content($urpm, $url, %o_options)
+
+Retrieve a file and return its content.
+
+=cut
+
 sub get_content {
     my ($urpm, $url, %o_options) = @_;
 
@@ -1069,6 +1090,8 @@ sub _create_metalink_ {
 
 __END__
 
+=back
+
 =head1 COPYRIGHT
 
 Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005 MandrakeSoft SA
diff --git a/urpm/install.pm b/urpm/install.pm
index 741f9ee3..8754fe85 100644
--- a/urpm/install.pm
+++ b/urpm/install.pm
@@ -39,6 +39,11 @@ sub _hash_intersect_list {
     \%h;
 }
 
+=item prepare_transaction($set, $blists, $sources)
+
+=cut
+
+
 sub prepare_transaction {
     my ($set, $blists, $sources) = @_;
 
@@ -79,6 +84,12 @@ sub transaction_set_to_string {
     } @$set;
 }
 
+=item install_logger($urpm, $type, $id, $subtype, $amount, $total)
+
+Standard logger for transactions
+
+=cut
+
 # install logger callback
 sub install_logger {
     my ($urpm, $type, $id, $subtype, $amount, $total) = @_;
@@ -116,6 +127,10 @@ sub install_logger {
     }
 }
 
+=item get_README_files($urpm, $trans, $pkg)
+
+=cut
+
 sub get_README_files {
     my ($urpm, $trans, $pkg) = @_;
 
@@ -161,6 +176,10 @@ sub options {
     );
 }
 
+=item install($urpm, $remove, $install, $upgrade, %options)
+
+=cut
+
 #- install packages according to each hash (remove, install or upgrade).
 #- options: 
 #-      test, excludepath, nodeps, noorder (unused), delta, 
diff --git a/urpm/ldap.pm b/urpm/ldap.pm
index 50c95962..164e9fa1 100644
--- a/urpm/ldap.pm
+++ b/urpm/ldap.pm
@@ -109,6 +109,8 @@ sub clean_ldap_cache($) {
 
 =item get_ldap_config()
 
+parse the system LDAP configuration file and return its config values
+
 =cut
 
 sub get_ldap_config() {
@@ -117,6 +119,8 @@ sub get_ldap_config() {
 
 =item get_ldap_config_file($file)
 
+parse a given LDAP configuration file and return its config values
+
 =cut
 
 sub get_ldap_config_file {
diff --git a/urpm/main_loop.pm b/urpm/main_loop.pm
index e8bae71c..52525da1 100644
--- a/urpm/main_loop.pm
+++ b/urpm/main_loop.pm
@@ -309,7 +309,45 @@ sub _run_transaction {
     !$fatal;
 }
 
-# locking is left to callers
+=item run($urpm, $state, $something_was_to_be_done, $ask_unselect, $_requested, $callbacks)
+
+Run the main urpm loop:
+
+=over
+
+=item * mount removable media if needed
+
+=item * split the work in smaller transactions
+
+=item * for each transaction:
+
+=over
+
+=item * prepare the transaction
+
+=item * download packages needed for this small transaction
+
+=item * verify packages
+
+=item * split package that should be installed instead of upgraded,
+
+=item * install source package only (whatever the user is root or not, but use rpm for that)
+
+=item * install/remove other packages
+
+=back
+
+=item * migrate the chrooted rpmdb if needed
+
+=item * display the final success/error message(s)
+
+=back
+
+Warning: locking is left to callers...
+
+=cut
+
+
 sub run {
     my ($urpm, $state, $something_was_to_be_done, $ask_unselect, $_requested, $callbacks) = @_;
 
diff --git a/urpm/md5sum.pm b/urpm/md5sum.pm
index 8c1b7389..62a21512 100644
--- a/urpm/md5sum.pm
+++ b/urpm/md5sum.pm
@@ -17,6 +17,14 @@ urpm::md5sum - Meta-data checking routines for urpmi
 
 =cut 
 
+
+=item parse($md5sum_file)
+
+Parse a MD5SUM file.
+Returns a hash of file => md5sum 
+
+=cut
+
 sub parse {
     my ($md5sum_file) = @_;
 
@@ -28,6 +36,14 @@ sub parse {
     \%h;
 }
 
+
+=item parse($md5sum_file)
+
+Check size and parse a MD5SUM file.
+Returns a hash of file => md5sum 
+
+=cut
+
 sub check_file {
     my ($md5sum_file) = @_;
 
@@ -40,6 +56,13 @@ sub from_MD5SUM__or_warn {
     $md5sums->{$basename};
 }
 
+
+=item versioned_media_info_file($urpm, $medium, $basename)
+
+Returns the latest versionated file name for $basename
+
+=cut
+
 sub versioned_media_info_file {
     my ($urpm, $medium, $basename) = @_;
     my $md5sums = $medium->{parsed_md5sum} or $urpm->{log}("$medium->{name} has no md5sum"), return;
@@ -54,6 +77,12 @@ sub versioned_media_info_file {
     $l[0];
 }
 
+=item compute($file)
+
+Return the MD5SUM control sum of $file
+
+=cut
+
 sub compute {
     my ($file) = @_;
     eval { require Digest::MD5 };
diff --git a/urpm/orphans.pm b/urpm/orphans.pm
index c8e68b9e..02c655ea 100644
--- a/urpm/orphans.pm
+++ b/urpm/orphans.pm
@@ -36,6 +36,13 @@ sub installed_packages_packed {
     \@l;
 }
 
+
+=item unrequested_list__file($urpm)
+
+Return the path of the unrequested list file.
+
+=cut
+
 #- side-effects: none
 sub unrequested_list__file {
     my ($urpm) = @_;
@@ -52,6 +59,13 @@ sub unrequested_list {
     } cat_(unrequested_list__file($urpm)) };
 }
 
+=item mark_as_requested($urpm, $state, $test)
+
+Mark some packages as explicitely requested (usually because
+they were manually installed).
+
+=cut
+
 #- side-effects: those of _write_unrequested_list__file
 sub mark_as_requested {
     my ($urpm, $state, $test) = @_;
@@ -418,6 +432,12 @@ sub _all_unrequested_orphans {
     [ values %l ];
 }
 
+=item compute_future_unrequested_orphans($urpm, $state)
+
+Compute the list of packages that will be unrequested and
+could potently be removed.
+
+=cut
 
 #- side-effects: $state->{orphans_to_remove}
 #-   + those of _installed_and_unrequested_lists (<root>/var/lib/rpm/installed-through-deps.list)
@@ -441,8 +461,16 @@ sub compute_future_unrequested_orphans {
     # nb: $state->{orphans_to_remove} is used when computing ->selected_size
 }
 
-#- it is quite fast. the slow part is the creation of $installed_packages_packed
-#- (using installed_packages_packed())
+
+=item get_orphans($urpm)
+
+Returns the list of unrequested packages (aka orphans).
+
+It is quite fast. the slow part is the creation of
+$installed_packages_packed (using installed_packages_packed())
+
+=cut
+
 #
 #- side-effects:
 #-   + those of _installed_req_and_unreq (<root>/var/lib/rpm/installed-through-deps.list)
@@ -464,6 +492,15 @@ sub _get_now_orphans_raw_msg {
     (scalar(@orphans), add_leading_spaces(join("\n", sort @orphans)));
 }
 
+=item get_now_orphans_gui_msg($urpm)
+
+Like get_now_orphans_msg() but more suited for GUIes, it return
+message about orphan packages.
+
+Used by rpmdrake.
+
+=cut
+
 sub get_now_orphans_gui_msg {
     my ($urpm) = @_;
 
@@ -477,6 +514,14 @@ sub get_now_orphans_gui_msg {
     );
 }
 
+
+=item get_now_orphans_msg($urpm)
+
+Similar to get_now_orphans_gui_msg() but more suited for CLI, it
+return message about orphan packages.
+
+=cut
+
 sub get_now_orphans_msg {
     my ($urpm) = @_;
 
@@ -487,6 +532,12 @@ sub get_now_orphans_msg {
 }
 
 
+=item add_leading_spaces($string)
+
+Add leading spaces to the string and return it.
+
+=cut
+
 #- side-effects: none
 sub add_leading_spaces {
     my ($s) = @_;
diff --git a/urpm/signature.pm b/urpm/signature.pm
index 931a95c2..b873a06d 100644
--- a/urpm/signature.pm
+++ b/urpm/signature.pm
@@ -18,9 +18,26 @@ urpm::signature - Package signature routines for urpmi
 
 =over
 
+=item check($urpm, $sources_install, $sources, %options)
+
+Checks a package signature, return a list of error messages
+
+Options:
+
+=over
+
+=item * basename
+
+whether to show full file paths or only file names in messages (used by rpmdrake)
+
+=item * callback
+
+A callback called on package verification (used by rpmdrake in order to update its progressbar)
+
+=back
+
 =cut
 
-#- options: callback, basename
 sub check {
     my ($urpm, $sources_install, $sources, %options) = @_;
     sort(_check($urpm, $sources_install, %options),