Add documentation

Signed-off-by: Florian Pritz <bluewind@xinu.at>

3 files changed, 144 insertions, 31 deletions

diff --git a/lib/App/ArchLinux/PackagerTools.pm b/lib/App/ArchLinux/PackagerTools.pm
index d8cb89d..0a45bb8 100644
--- a/lib/App/ArchLinux/PackagerTools.pm
+++ b/lib/App/ArchLinux/PackagerTools.pm
@@ -49,10 +49,35 @@ method new_no_defaults($class: $deps = {}) {
 	return $self;
 }
 
+=head3 get_distributions_in_repo
+
+ my $dists = $app->get_distributions_in_repo();
+
+Return an arrayref of hashrefs with CPAN distribution information. See
+L<App::ArchLinux::PackagerTools::Pacman/"get_perl_distributions">.
+
+=cut
+
 method get_distributions_in_repo() {
 	return $self->{deps}->{pacman}->get_perl_distributions();
 }
 
+=head3 get_updateable_packages
+
+ my $distribution_names = ['App::ArchLinux::PackagerTools', 'DBI'];
+ my $packages = $app->get_updateable_packages($distribution_names);
+ print $packages[0]->{dist_name};
+ print $packages[0]->{pkgname};
+ print $packages[0]->{repo_version};
+ print $packages[0]->{cpan_version};
+
+Accepts a list of package names and returns a list of packages that can be
+updated. The returned packages contain the name of the distribution, the name
+of the pacman package, and the versions of each, the pacman package (which is
+older) and the CPAN distribution.
+
+=cut
+
 method get_updateable_packages($distribution_names) {
 	my @packages;
 	for my $dist_name ($distribution_names->@*) {
diff --git a/lib/App/ArchLinux/PackagerTools/CPAN.pm b/lib/App/ArchLinux/PackagerTools/CPAN.pm
index 175e218..c2dcf4a 100644
--- a/lib/App/ArchLinux/PackagerTools/CPAN.pm
+++ b/lib/App/ArchLinux/PackagerTools/CPAN.pm
@@ -17,19 +17,21 @@ App::ArchLinux::PackagerTools::CPAN - Methods to interact with CPAN
 
 =head1 SYNOPSIS
 
-use App::ArchLinux::PackagerTools::CPAN;
+ use App::ArchLinux::PackagerTools::CPAN;
 
-# synopsis...
+ my $cpan = App::ArchLinux::PackagerTools::CPAN->new();
 
 =head1 DESCRIPTION
 
-# longer description...
+Utility methods to search for distributions in CPAN. Maintains an internal
+database that allows to perform case-insensitive searches for distribution
+names.
 
 =head1 METHODS
 
 =head2 new
 
- App::ArchLinux::PackagerTools::CPAN->new();
+ my $cpan = App::ArchLinux::PackagerTools::CPAN->new();
 
 Returns a new instance.
 
@@ -54,6 +56,8 @@ method new_no_defaults($class: $deps = {}) {
 
 =head3 is_newer_version_available
 
+ if ($cpan->is_newer_version_available($dist_name, $version)) {...}
+
 Return 1 if a newer version of the distribution is available, 0 otherwise.
 
 =cut
@@ -69,6 +73,66 @@ method is_newer_version_available($dist_name, $version) {
 	}
 }
 
+=head3 search_dist
+
+ my $name = "App::ArchLinux::PackagerTools";
+ my $dist = $cpan->search_dist($name);
+
+Search for a distribution that matches the supplied, case-insensitive name.
+Either returns a hash that contains the dist_name and version of the found
+distribution or undef if none is found.
+
+Note that it searches for a distribution only, not for a module.
+
+=cut
+
+method search_dist($name) {
+	$name =~ s/::/-/g;
+	$log->tracef("Searching for CPAN distribution matching '%s'", $name);
+
+	my $index_name = $self->{dist_lc_map}->{lc($name)};
+	if (defined $index_name) {
+		return $self->{dists}->{$index_name};
+	}
+
+	return;
+}
+
+=head3 get_dist
+
+ my $name = "App::ArchLinux::PackagerTools";
+ my $dist = $cpan->get_dist($name);
+
+Return a distribution that matches the supplied, case-insensitive name.
+Returns a hash that contains the dist_name and version of the found
+distribution or raises an exception if no distribution is found.
+
+Note that it searches for a distribution only, not for a module.
+
+=cut
+
+method get_dist($dist_name) {
+	$dist_name =~ s/::/-/g;
+	$log->tracef("Getting CPAN data for distribution '%s'", $dist_name);
+
+	my $index_name = $self->{dist_lc_map}->{lc($dist_name)};
+	if (defined $index_name) {
+		return $self->{dists}->{$index_name};
+	}
+
+	croak $log->errorf("Failed to find distribution with name %s", $dist_name);
+}
+
+=head2 Private Methods
+
+=head3 _build_dist_index
+
+ $self->_build_dist_index();
+
+Set up the internal index of CPAN distributions
+
+=cut
+
 method _build_dist_index() {
 	$self->{deps}->{cpanplus_backend}->reload_indices();
 	# TODO download pacakges list ourselves instead of using cpanplus for it? We may need cpanplus for other features later so keeping it is probably also fine.
@@ -125,30 +189,6 @@ method _build_dist_index() {
 	}
 }
 
-method search_dist($name) {
-	$name =~ s/::/-/g;
-	$log->tracef("Searching for CPAN distribution matching '%s'", $name);
-
-	my $index_name = $self->{dist_lc_map}->{lc($name)};
-	if (defined $index_name) {
-		return $self->{dists}->{$index_name};
-	}
-
-	return;
-}
-
-method get_dist($dist_name) {
-	$dist_name =~ s/::/-/g;
-	$log->tracef("Getting CPAN data for distribution '%s'", $dist_name);
-
-	my $index_name = $self->{dist_lc_map}->{lc($dist_name)};
-	if (defined $index_name) {
-		return $self->{dists}->{$index_name};
-	}
-
-	croak $log->errorf("Failed to find distribution with name %s", $dist_name);
-}
-
 1;
 
 __END__
diff --git a/lib/App/ArchLinux/PackagerTools/Pacman.pm b/lib/App/ArchLinux/PackagerTools/Pacman.pm
index 765746e..8a26407 100644
--- a/lib/App/ArchLinux/PackagerTools/Pacman.pm
+++ b/lib/App/ArchLinux/PackagerTools/Pacman.pm
@@ -18,8 +18,7 @@ App::ArchLinux::PackagerTools::Pacman - Methods to interact with pacman
 =head1 DESCRIPTION
 
 This module allows to query pacman for a list of packages in the repository and
-extract a list of perl distributions that are part of the repository.
-
+extract a list of CPAN distributions that are part of the repository.
 
 =head1 METHODS
 
@@ -27,7 +26,7 @@ extract a list of perl distributions that are part of the repository.
 
 =head3 new
 
- App::ArchLinux::PackagerTools::Pacman->new();
+ my $pacman = App::ArchLinux::PackagerTools::Pacman->new();
 
 Returns a new instance.
 
@@ -55,6 +54,8 @@ method new_no_defaults($class: $deps = {}) {
 
 =head3 get_packages
 
+ my $packages = $pacman->get_packages();
+
 Returns an arrayref of package hashes. Each package hash contains at least the
 pkgname and pkgver keys.
 
@@ -72,12 +73,30 @@ method get_packages() {
 	return \@packages;
 }
 
+=head3 get_perl_packages
+
+ my $packages = $pacman->get_perl_packages();
+
+Similar to get_packages(), but returns a list filtered to perl packages.
+
+=cut
+
 method get_perl_packages() {
 	my @packages = grep {$_->{pkgname} =~ /^perl-/} $self->get_packages->@*;
 	$log->debugf("Found %d perl packages", scalar(@packages));
 	return \@packages;
 }
 
+=head3 get_perl_distributions
+
+ my $dists = $pacman->get_perl_distributions();
+
+Returns a list of CPAN distributions that are in the pacman repo. Returns an
+arrayref of hashrefs that contain dist_name and version keys.
+
+=cut
+
+
 method get_perl_distributions() {
 	my @distributions;
 
@@ -95,6 +114,14 @@ method get_perl_distributions() {
 	return \@distributions;
 }
 
+=head3 get_package_version
+
+ my $version = $pacman->get_package_version($pkgname);
+
+Return the version of a package in the pacman package repositories.
+
+=cut
+
 method get_package_version($pkgname) {
 	# TODO do not fork expac for each package here! works for now, but it's sloooow
 	my $version = `expac -S -1 '%v' -- '$pkgname'`;
@@ -102,13 +129,34 @@ method get_package_version($pkgname) {
 	return $version;
 }
 
+=head3 get_perl_pkgname
+
+ my $pkgname = $pacman->get_perl_pkgname($dist_name);
+
+Return the pacman package name for a CPAN distribution. In most cases, this
+prefixes the distribution with "perl-" and replaces "::" with "-", but it may
+also return other names if they are mapped differently.
+
+=cut
+
 method get_perl_pkgname($dist_name) {
+	# TODO implement mapping
 	my $pkgname = lc($dist_name);
 	$pkgname =~ s/::/-/g;
 	$pkgname = "perl-$pkgname";
 	return $pkgname;
 }
 
+=head3 get_perl_distribution_version
+
+ my $version = $pacman->get_perl_distribution_version($dist_name);
+
+Return the version of a CPAN distribution's pacman package. This removes
+pacman-specific information from the pacman's package version.
+
+=cut
+
+
 method get_perl_distribution_version($dist_name) {
 	my $pkgname = $self->get_perl_pkgname($dist_name);
 	my $version = $self->get_package_version($pkgname);