convert a couple comments to POD

9 files changed, 321 insertions, 87 deletions

diff --git a/urpm/download.pm b/urpm/download.pm
index 9cc6f555..de8abf45 100644
--- a/urpm/download.pm
+++ b/urpm/download.pm
@@ -180,9 +180,14 @@ sub get_proxy_ {
     get_proxy($urpm);
 }
 
-#- reads and loads the proxy.cfg file ;
-#- returns the global proxy settings (without arguments) or the
-#- proxy settings for the specified media (with a media name as argument)
+=item get_proxy($media)
+
+Reads and loads the proxy.cfg file ;
+Returns the global proxy settings (without arguments) or the
+proxy settings for the specified media (with a media name as argument)
+
+=cut
+
 sub get_proxy (;$) {
     my ($o_media) = @_; $o_media ||= '';
     load_proxy_config();
@@ -226,7 +231,12 @@ sub copy_cmd_line_proxy {
     }
 }
 
-#- overrides the config file proxy settings with values passed via command-line
+=item set_cmdline_proxy(%h)
+
+Overrides the config file proxy settings with values passed via command-line
+
+=cut
+
 sub set_cmdline_proxy {
     my (%h) = @_;
     load_proxy_config();
@@ -239,7 +249,12 @@ sub set_cmdline_proxy {
     $proxy_config->{cmd_line}{$_} = $h{$_} foreach keys %h;
 }
 
-#- changes permanently the proxy settings
+=item set_proxy_config($key, $value, $o_media)
+
+Changes permanently the proxy settings
+
+=cut
+
 sub set_proxy_config {
     my ($key, $value, $o_media) = @_;
     $proxy_config->{$o_media || ''}{$key} = $value;
@@ -821,7 +836,12 @@ sub progress_text {
 	 N("        %s%% completed, speed = %s", $percent, $speed)) : '';
 }
 
-#- default logger suitable for sync operation on STDERR only.
+=item sync_logger($mode, $file, $percent, $_total, $_eta, $_speed)
+
+Default logger (callback) suitable for sync operation on STDERR only.
+
+=cut
+
 sub sync_logger {
     my ($mode, $file, $percent, $_total, $_eta, $_speed) = @_;
     if ($mode eq 'start') {
diff --git a/urpm/get_pkgs.pm b/urpm/get_pkgs.pm
index f82b2e41..7f6bcc28 100644
--- a/urpm/get_pkgs.pm
+++ b/urpm/get_pkgs.pm
@@ -178,7 +178,13 @@ sub verify_partial_rpm_and_move {
     "$cachedir/rpms/$filename";
 }
 
-# get the filesize of packages to download from remote media.
+
+=item get_distant_media_filesize(undef, $blists, $sources)
+
+Get the filesize of packages to download from remote media.
+
+=cut
+
 sub get_distant_media_filesize {
     my (undef, $blists, $sources) = @_;
 
@@ -199,10 +205,15 @@ sub get_distant_media_filesize {
     $filesize;
 }
 
-# download packages listed in $blists,
-# and put the result in $sources or $error_sources
-#
-#- options: quiet, callback, 
+=item download_packages_of_distant_media($urpm, $blists, $sources, $error_sources, %options)
+
+Download packages listed in $blists, and put the result in $sources or
+$error_sources
+
+Options: quiet, callback, 
+
+=cut
+
 sub download_packages_of_distant_media {
     my ($urpm, $blists, $sources, $error_sources, %options) = @_;
 
diff --git a/urpm/install.pm b/urpm/install.pm
index 8754fe85..c539af3c 100644
--- a/urpm/install.pm
+++ b/urpm/install.pm
@@ -178,15 +178,17 @@ sub options {
 
 =item install($urpm, $remove, $install, $upgrade, %options)
 
+Install packages according to each hash (remove, install or upgrade).
+
+options: 
+     test, excludepath, nodeps, noorder (unused), delta, 
+     callback_inst, callback_trans, callback_report_uninst,
+     post_clean_cache, verbose
+  (more options for trans->run)
+     excludedocs, nosize, noscripts, oldpackage, repackage, replacepkgs, justdb, ignorearch
+
 =cut
 
-#- install packages according to each hash (remove, install or upgrade).
-#- options: 
-#-      test, excludepath, nodeps, noorder (unused), delta, 
-#-      callback_inst, callback_trans, callback_report_uninst,
-#-      post_clean_cache, verbose
-#-   (more options for trans->run)
-#-      excludedocs, nosize, noscripts, oldpackage, repackage, replacepkgs, justdb, ignorearch
 sub install {
     my ($urpm, $remove, $install, $upgrade, %options) = @_;
     $options{translate_message} = 1;
diff --git a/urpm/lock.pm b/urpm/lock.pm
index 12ab7394..d480b25d 100644
--- a/urpm/lock.pm
+++ b/urpm/lock.pm
@@ -27,16 +27,33 @@ urpm::lock - urpm/rpm DB locking related routines for urpmi
 ################################################################################
 #- class functions
 
-#- lock policy concerning chroot :
-#  - lock rpm db in chroot
-#  - lock urpmi db in /
-# (options: nofatal, wait)
+
+=item rpm_db($urpm, $b_exclusive, %options)
+
+Lock urpmi DB.
+
+Lock policy concerning chroot : lock rpm db in chroot
+
+Options: nofatal, wait
+
+=cut
+
 sub rpm_db {
     my ($urpm, $b_exclusive, %options) = @_;
     my $f = ($urpm->{root} ? "$urpm->{root}/" : '') . "/var/lib/rpm/.RPMLOCK";
     urpm::lock->new($urpm, $f, 'rpm', $b_exclusive, %options);
 }
-# (options: nofatal, wait)
+
+=item urpmi_db($urpm, $b_exclusive, %options)
+
+Lock urpmi DB.
+
+Lock policy concerning chroot : lock urpmi db in /
+
+Options: nofatal, wait
+
+=cut
+
 sub urpmi_db {
     my ($urpm, $b_exclusive, %options) = @_;
     urpm::lock->new($urpm, "$urpm->{statedir}/.LOCK", 'urpmi', $b_exclusive, %options);
diff --git a/urpm/mirrors.pm b/urpm/mirrors.pm
index f3ef162b..3fcf9b13 100644
--- a/urpm/mirrors.pm
+++ b/urpm/mirrors.pm
@@ -18,9 +18,12 @@ urpm::mirrors - Mirrors routines for urpmi
 
 =over
 
-=cut 
+=item try($urpm, $medium, $try)
+
+$medium fields used: mirrorlist, with-dir
+
+=cut
 
-#- $medium fields used: mirrorlist, with-dir
 #- side-effects: $medium->{url}
 #-   + those of _pick_one ($urpm->{mirrors_cache})
 sub try {
@@ -36,10 +39,15 @@ sub try {
     0;
 }
 
-#- similar to try() above, but failure is "normal"
-#- (useful when we lookup a file)
-#-
-#- $medium fields used: mirrorlist, with-dir
+=item try_probe($urpm, $medium, $try)
+
+Similar to try() above, but failure is "normal" (useful when we lookup
+a file)
+
+$medium fields used: mirrorlist, with-dir
+
+=cut
+
 #- side-effects: $medium->{url}
 #-   + those of list_urls ($urpm->{mirrors_cache})
 sub try_probe {
diff --git a/urpm/orphans.pm b/urpm/orphans.pm
index 02c655ea..256470c3 100644
--- a/urpm/orphans.pm
+++ b/urpm/orphans.pm
@@ -203,9 +203,15 @@ sub add_unrequested {
     append_to_file(unrequested_list__file($urpm), join('', map { "$_\t\t$l{$_}\n" } keys %l));
 }
 
-#- we don't want to check orphans on every auto-select,
-#- doing it only after many packages have been added
-#-
+=item check_unrequested_orphans_after_auto_select($urpm)
+
+We don't want to check orphans on every auto-select.
+We do it only after many packages have been added.
+
+Returns whether we should look for orphans depending on a threshold.
+
+=cut
+
 #- side-effects: none
 sub check_unrequested_orphans_after_auto_select {
     my ($urpm) = @_;
@@ -214,13 +220,20 @@ sub check_unrequested_orphans_after_auto_select {
     $nb_added >= $urpm->{options}{'nb-of-new-unrequested-pkgs-between-auto-select-orphans-check'};
 }
 
-#- this function computes wether removing $toremove packages will create
-#- unrequested orphans.
-#-
-#- it does not return the new orphans since "whatsuggests" is not available,
-#- if it detects there are new orphans, _all_unrequested_orphans()
-#- must be used to have the list of the orphans
-#-
+
+=item unrequested_orphans_after_remove($urpm, $toremove)
+
+This function computes wether removing $toremove packages will create
+unrequested orphans.
+
+It does not return the new orphans since "whatsuggests" is not
+available,
+
+If it detects there are new orphans, _all_unrequested_orphans() must
+be used to have the list of the orphans
+
+=cut
+
 #- side-effects: none
 sub unrequested_orphans_after_remove {
     my ($urpm, $toremove) = @_;
diff --git a/urpm/select.pm b/urpm/select.pm
index 8c352ccf..96d5801a 100644
--- a/urpm/select.pm
+++ b/urpm/select.pm
@@ -89,15 +89,32 @@ sub build_listid_ {
     $urpm->build_listid(undef, undef, searchmedia_idlist($urpm));
 }
 
-#- search packages registered by their names by storing their ids into the $packages hash.
-#- Recognized options:
-#-	all
-#-	caseinsensitive
-#-	fuzzy
-#-      no_substring
-#-	src
-#-	use_provides
-#-
+
+=item search_packages($urpm, $packages, $names, %options)
+
+Search packages registered by their names by storing their ids into the $packages hash.
+
+Recognized options:
+
+=over
+
+
+=item * all
+
+=item * caseinsensitive
+
+=item * fuzzy
+
+=item * no_substring
+
+=item * src
+
+=item * use_provides
+
+=back
+
+=cut
+
 #- side-effects: $packages, flag_skip
 sub search_packages {
     my ($urpm, $packages, $names, %options) = @_;
@@ -252,19 +269,48 @@ sub _search_packages_keep_best {
     join('|', map { $_->id } @l);
 }
 
-#- Resolves dependencies between requested packages (and auto selection if any).
-#- handles parallel option if any.
-#- The return value is true if program should be restarted (in order to take
-#- care of important packages being upgraded (priority upgrades)
-#- %options :
-#-	auto_select
-#-	install_src
-#-	priority_upgrade
-#- %options passed to ->resolve_requested:
-#-	callback_choices
-#-	keep
-#-	nodeps
-#-	no_suggests
+
+=item resolve_dependencies($urpm, $state, $requested, %options)
+
+
+Resolves dependencies between requested packages (and auto selection if any).
+Handles parallel option if any.
+
+The return value is true if program should be restarted (in order to take
+care of important packages being upgraded (priority upgrades)
+
+$state->{selected} will contain the selection of packages to be
+installed or upgraded
+
+
+%options :
+
+=over
+
+=item * auto_select
+
+=item * install_src
+
+=item * priority_upgrade
+
+=back
+
+%options passed to ->resolve_requested:
+
+=over
+
+=item * callback_choices
+
+=item * keep
+
+=item * nodeps
+
+=item * no_suggests
+
+=back
+
+=cut
+
 sub resolve_dependencies {
     #- $state->{selected} will contain the selection of packages to be
     #- installed or upgraded
@@ -400,14 +446,31 @@ sub get_preferred {
 
 my $fullname2name_re = qr/^(.*)-[^\-]*-[^\-]*\.[^\.\-]*$/;
 
-#- find packages to remove.
-#- options:
-#-	callback_base
-#-	callback_fuzzy
-#-	callback_notfound
-#-	force
-#-	matches
-#-	test
+
+=item find_packages_to_remove($urpm, $state, $l, %options)
+
+Find packages to remove.
+
+Options:
+
+=over
+
+=item * callback_base
+
+=item * callback_fuzzy
+
+=item * callback_notfound
+
+=item * force
+
+=item * matches
+
+=item * test
+
+=back
+
+=cut 
+
 sub find_packages_to_remove {
     my ($urpm, $state, $l, %options) = @_;
 
@@ -508,13 +571,24 @@ sub _prohibit_packages_that_would_be_removed {
     } intersection(\@to_remove, \@base_fn);
 }
 
-#- misc functions to help finding ask_unselect and ask_remove elements with their reasons translated.
+
+=item unselected_packages(undef, $state)
+
+misc functions to help finding ask_unselect and ask_remove elements with their reasons translated.
+
+=cut
+
 sub unselected_packages {
     my (undef, $state) = @_;
     grep { $state->{rejected}{$_}{backtrack} } keys %{$state->{rejected} || {}};
 }
 
-#- misc functions to help finding ask_unselect and ask_remove elements with their reasons translated.
+=item already_installed($state)
+
+misc functions to help finding ask_unselect and ask_remove elements with their reasons translated.
+
+=cut
+
 sub already_installed {
     my ($state) = @_;
     uniq(map { scalar $_->fullname } values %{$state->{rejected_already_installed} || {}});
diff --git a/urpm/sys.pm b/urpm/sys.pm
index e615b215..64b807f1 100644
--- a/urpm/sys.pm
+++ b/urpm/sys.pm
@@ -23,8 +23,13 @@ urpm::sys - OS-related routines for urpmi
 
 =cut 
 
-#- get the list of packages that should not be upgraded or installed,
-#- typically from the inst.list or skip.list files.
+=item get_packages_list($file, $o_extra)
+
+Get the list of packages that should not be upgraded or installed,
+typically from the inst.list or skip.list files.
+
+=cut
+
 sub get_packages_list {
     my ($file, $o_extra) = @_;
     my @l = split(/,/, $o_extra || '');
@@ -51,6 +56,12 @@ sub _read_fstab_or_mtab {
     @l;
 }
 
+=item find_a_mntpoint($dir)
+
+Find used mount point from a pathname
+
+=cut
+
 sub find_a_mntpoint {
     my ($dir) = @_;
     _find_a_mntpoint($dir, {});
@@ -104,7 +115,12 @@ sub _find_a_mntpoint {
     undef;
 }
 
-#- return the size of the partition and its free space in KiB
+=item df($mntpoint)
+
+Return the size of the partition and its free space in KiB
+
+=cut
+
 sub df {
     my ($mntpoint) = @_;
     require Filesys::Df;
@@ -160,7 +176,13 @@ sub proc_mounts() {
     @l;
 }
 
-#- returns the first unused loop device, or an empty string if none is found.
+
+=item first_free_loopdev()
+
+Returns the first unused loop device, or an empty string if none is found.
+
+=cut
+
 sub first_free_loopdev () {
     my %loopdevs = map { $_ => 1 } grep { ! -d $_ } glob('/dev/loop*');
     foreach (proc_mounts()) {
@@ -181,7 +203,12 @@ sub trim_until_d {
     $dir;
 }
 
-#- checks if the main filesystems are writeable for urpmi to install files in
+=item check_fs_writable()
+
+Checks if the main filesystems are writeable for urpmi to install files in
+
+=cut
+
 sub check_fs_writable () {
     foreach (proc_mounts()) {
 	(undef, our $mountpoint, undef, my $opts) = split ' ';
@@ -288,12 +315,25 @@ sub migrate_back_rpmdb_db_version {
     clean_rpmdb_shared_regions($root);
 }
 
-#- create a plain rpm from an installed rpm and a delta rpm (in the current directory)
-#- returns the new rpm filename in case of success
-#- params :
-#-	$deltarpm : full pathname of the deltarpm
-#-	$o_dir : directory where to put the produced rpm (optional)
-#-	$o_pkg : URPM::Package object corresponding to the deltarpm (optional)
+
+=item apply_delta_rpm($deltarpm, $o_dir, $o_pkg)
+
+Create a plain rpm from an installed rpm and a delta rpm (in the current directory)
+Returns the new rpm filename in case of success.
+Params :
+
+=over
+
+=item * $deltarpm : full pathname of the deltarpm
+
+=item * $o_dir : directory where to put the produced rpm (optional)
+
+=item * $o_pkg : URPM::Package object corresponding to the deltarpm (optional)
+
+=back
+
+=cut
+
 our $APPLYDELTARPM = '/usr/bin/applydeltarpm';
 sub apply_delta_rpm {
     my ($deltarpm, $o_dir, $o_pkg) = @_;
diff --git a/urpm/xml_info_pkg.pm b/urpm/xml_info_pkg.pm
index d75bd2ce..889bfabd 100644
--- a/urpm/xml_info_pkg.pm
+++ b/urpm/xml_info_pkg.pm
@@ -12,9 +12,12 @@ urpm::xml_info_pkg - XML Package data retrieving related routines for urpmi
 
 =over
 
-=cut 
+=item new($class, $hash, $pkg)
 
-# proxy object: returns the xml info if available, otherwise redirects to URPM::Package
+Returns a proxy object
+It enable to get the XML info if available, otherwise redirects to URPM::Package
+
+=cut
 
 sub new {
     my ($class, $hash, $pkg) = @_;
@@ -25,7 +28,23 @@ sub new {
 }
 
 
-# only available in synthesis/hdlist
+=item id($pkg)
+
+=item group($pkg)
+
+=item size($pkg)
+
+=item epoch($pkg)
+
+=item buildhost($pkg)
+
+=item packager($pkg)
+
+=item summary($pkg)
+
+Only available in synthesis/hdlist
+=cut
+
 sub id        { $_[0]{pkg}->id }
 sub group     { $_[0]{pkg}->group }
 sub size      { $_[0]{pkg}->size }
@@ -35,7 +54,22 @@ sub packager  { $_[0]{pkg}->packager }
 sub summary   { $_[0]{pkg}->summary }
 
 
-# can be directly available in xml_info
+=item url($pkg)
+
+=item license($pkg)
+
+=item sourcerpm($pkg)
+
+=item description($pkg)
+
+=item changelogs($pkg)
+
+=item files($pkg)
+
+Can be directly available in xml_info
+
+=cut
+
 sub url         { exists $_[0]{url}         ? $_[0]{url}         : $_[0]{pkg}->url }
 sub license     { exists $_[0]{license}     ? $_[0]{license}     : $_[0]{pkg}->license }
 sub sourcerpm   { exists $_[0]{sourcerpm}   ? $_[0]{sourcerpm}   : $_[0]{pkg}->sourcerpm }
@@ -47,7 +81,22 @@ sub files { exists $_[0]{files} ? split("\n", $_[0]{files}) : $_[0]{pkg}->files
 
 my $fullname_re = qr/^(.*)-([^\-]*)-([^\-]*)\.([^\.\-]*)$/;
 
-# available in both {pkg} and {fn}
+=item name($pkg)
+
+=item version($pkg)
+
+=item release($pkg)
+
+=item arch($pkg)
+
+=item fullname($pkg)
+
+=item filename($pkg)
+
+Available in both {pkg} and {fn}
+
+=cut
+
 sub name      { exists $_[0]{pkg} ? $_[0]{pkg}->name    : $_[0]{fn} =~ $fullname_re && $1 }
 sub version   { exists $_[0]{pkg} ? $_[0]{pkg}->version : $_[0]{fn} =~ $fullname_re && $2 }
 sub release   { exists $_[0]{pkg} ? $_[0]{pkg}->release : $_[0]{fn} =~ $fullname_re && $3 }