From 12201461e927af015caefc583a2ab5514c63668b Mon Sep 17 00:00:00 2001
From: Florian Pritz <bluewind@xinu.at>
Date: Mon, 19 Nov 2018 00:03:42 +0100
Subject: Add documentation

Signed-off-by: Florian Pritz <bluewind@xinu.at>
---
 lib/App/ArchLinux/PackagerTools/CPAN.pm | 96 +++++++++++++++++++++++----------
 1 file changed, 68 insertions(+), 28 deletions(-)

(limited to 'lib/App/ArchLinux/PackagerTools/CPAN.pm')

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__
-- 
cgit v1.2.3-24-g4f1b