Podify more

3 files changed, 162 insertions, 36 deletions

diff --git a/urpm/lock.pm b/urpm/lock.pm
index 2b7855a8..358b63a1 100644
--- a/urpm/lock.pm
+++ b/urpm/lock.pm
@@ -18,14 +18,9 @@ urpm::lock - urpm/rpm DB locking related routines for urpmi
 
 =head1 DESCRIPTION
 
-=over
-
-=cut 
-
-
-################################################################################
-#- class functions
+=head1 CLASS FUNCTIONS
 
+=over
 
 =item rpm_db($urpm, $b_exclusive, %options)
 
@@ -58,11 +53,29 @@ sub urpmi_db {
     urpm::lock->new($urpm, "$urpm->{statedir}/.LOCK", 'urpmi', $b_exclusive, %options);
 }
 
+=back
+
+=head1 METHODS
+
+=over
+
+=item new($_class, $urpm, $file, $db_name, $b_exclusive, %options)
+
+Create a new lock.
+You don't want to use it directly. Either use urpmi_db() or rpm_db().
+
+Options:
 
-################################################################################
-#- methods
+=over 4
+
+=item * nofatal
+
+=item * wait
+
+=back
+
+=cut
 
-# (options: nofatal, wait)
 sub new {
     my ($_class, $urpm, $file, $db_name, $b_exclusive, %options) = @_;
     
@@ -121,6 +134,14 @@ sub _lock {
     $lock->{exclusive} = $b_exclusive;
 }
 
+
+=item unlock($lock)
+
+Free a lock.
+
+=cut
+
+
 sub unlock {
     my ($lock) = @_;
     $lock->{fh} or warn "lock $lock->{db_name} already released\n", return;
diff --git a/urpm/msg.pm b/urpm/msg.pm
index a79e59b8..6efe681c 100644
--- a/urpm/msg.pm
+++ b/urpm/msg.pm
@@ -7,6 +7,20 @@ use Exporter;
 use URPM;
 use urpm::util 'append_to_file';
 
+=head1 NAME
+
+urpm::msg - routines to prompt messages from the urpm* tools
+
+=head1 SYNOPSIS
+
+=head1 DESCRIPTION
+
+=head1 METHODS
+
+=over
+
+=cut
+
 my $encoding;
 BEGIN {
     eval { require encoding; $encoding = encoding::_get_locale_encoding() };
@@ -40,6 +54,13 @@ sub from_locale_encoding {
     } || $s;
 }
 
+
+=item translate($s, $o_plural, $o_nb)
+
+Actually translate a string using gettext.
+
+=cut
+
 sub translate {
     my ($s, $o_plural, $o_nb) = @_;
     my $res;
@@ -60,15 +81,36 @@ sub translate {
     }
 }
 
+=item P($s_singular, $s_plural, $nb, @para)
+
+Like N(), translate a string but with different singular/plural strings according to $nb
+
+=cut
+
 sub P {
     my ($s_singular, $s_plural, $nb, @para) = @_; 
     sprintf(translate($s_singular, $s_plural, $nb), @para);
 }
 
+=item N($format, @params)
+
+Translate the $format string (a la printf using @params)
+
+=cut
+
 sub N {
     my ($format, @params) = @_;
     sprintf(translate($format), @params);
 }
+
+=item N_($string)
+
+Unlike N(), it doesn't actually translate $string but serves to tag a string as translatable for extracting into pod catalog.
+
+The string will actually be translated later using translate().
+
+=cut
+
 sub N_ { $_[0] }
 
 my $noexpr = N("Nn");
@@ -88,9 +130,20 @@ eval {
     END { defined &closelog and closelog() }
 };
 
+=item sys_log(...)
+
+Log through syslog if Sys::Syslog is installed.
+
+=cut
+
 sub sys_log { defined &syslog and eval { syslog("info", @_) } }
 
-#- writes only to logfile, not to screen
+=item bug_log(...)
+
+Writes only to logfile, not to screen
+
+=cut
+
 sub bug_log {
     append_to_file($::logfile, @_) if $::logfile;
 }
@@ -131,6 +184,13 @@ sub _message_input {
     return $input;
 }
 
+
+=item toMb($nb)
+
+Convert a number of bytes into Mb
+
+=cut
+
 sub toMb {
     my $nb = $_[0] / 1024 / 1024;
     int $nb + 0.5;
@@ -185,7 +245,22 @@ sub _format_line_selected_packages {
      map { sprintf($format_line_format, @$_) } @l);
 }
 
-# duplicated from svn+ssh://svn.mandriva.com/svn/soft/drakx/trunk/perl-install/common.pm
+
+=item formatXiB($number [, $o_newbase])
+
+Returns a nicely human size. eg:
+
+  2097152 => "2MB"
+
+The optional parameter enables to provide the unit size (default is one).
+eg for a 2000 512 sized sectors:
+
+  formatXiB(2000, 512)
+
+Duplicated from L<common> (drakx/perl-install/common.pm)
+
+=cut
+
 sub formatXiB {
     my ($newnb, $o_newbase) = @_;
     my $newbase = $o_newbase || 1;
@@ -211,14 +286,7 @@ sub localtime2changelog { scalar(localtime($_[0])) =~ /(.*) \S+ (\d{4})$/ && "$1
 
 1;
 
-
-=head1 NAME
-
-urpm::msg - routines to prompt messages from the urpm* tools
-
-=head1 SYNOPSIS
-
-=head1 DESCRIPTION
+=back
 
 =head1 COPYRIGHT
 
diff --git a/urpm/util.pm b/urpm/util.pm
index 60a449d8..a8c89363 100644
--- a/urpm/util.pm
+++ b/urpm/util.pm
@@ -37,10 +37,36 @@ our @EXPORT = qw(add2hash_
     wc_l
 );
 
+
+=head1 NAME
+
+urpm::util - Misc. utilities subs for urpmi
+
+Mostly a subset of L<MDK::Common>
+
+See C<perldoc MDK::Common> for more documentation
+
+=head1 SYNOPSIS
+
+=head1 DESCRIPTION
+
+=head1 FUNCTIONS
+
+=over
+
+=cut
+
 sub min  { my $n = shift; $_ < $n and $n = $_ foreach @_; $n }
 sub max  { my $n = shift; $_ > $n and $n = $_ foreach @_; $n }
 
-#- quoting/unquoting a string that may be containing space chars.
+=item quotespace($str)
+
+=item unquotespace($str)
+
+Quoting/unquoting a string that may be containing space chars.
+
+=cut
+
 sub quotespace		 { my $x = $_[0] || ''; $x =~ s/(\s)/\\$1/g; $x }
 sub unquotespace	 { my $x = $_[0] || ''; $x =~ s/\\(\s)/$1/g; $x }
 
@@ -57,7 +83,12 @@ sub file2absolute_file {
     $f;
 }
 
-#- reduce pathname by removing <something>/.. each time it appears (or . too).
+=item reduce_pathname($url)
+
+Reduce pathname by removing <something>/.. each time it appears (or . too).
+
+=cut
+
 sub reduce_pathname {
     my ($url) = @_;
 
@@ -92,8 +123,13 @@ sub reduce_pathname {
     $host . $dir;
 }
 
-#- offset pathname by returning the right things to add to a relative directory
-#- to make no change. url is needed to resolve going before to top base.
+=item offset_pathname($url, $offset)
+
+Offset pathname by returning the right things to add to a relative directory
+to make no change. url is needed to resolve going before to top base.
+
+=cut
+
 sub offset_pathname {
     my ($url, $offset) = map { reduce_pathname($_) } @_;
 
@@ -134,7 +170,12 @@ sub move {
     rename($file, $dest) || !system("/bin/mv", "-f", $file, $dest);
 }
 
-#- file_size is useful to write file_size(...) > 32 without having warnings if file doesn't exist
+=item file_size($file)
+
+It is useful to write file_size(...) > 32 without having warnings if file doesn't exist
+
+=cut
+
 sub file_size {
     my ($file) = @_;
     -s $file || 0;
@@ -227,7 +268,12 @@ sub append_to_file {
     1;
 }
 
-#- return the UEFI machine type short name
+=item uefi_type()
+
+Return the UEFI machine type short name
+
+=cut
+
 sub uefi_type() {
     if (-e '/sys/firmware/efi/fw_platform_size') {
         # No support for ARM yet
@@ -239,16 +285,7 @@ sub uefi_type() {
 
 1;
 
-
-=head1 NAME
-
-urpm::util - Misc. utilities subs for urpmi
-
-Mostly a subset of L<MDK::Common>
-
-=head1 SYNOPSIS
-
-=head1 DESCRIPTION
+=back
 
 =head1 COPYRIGHT