Module::CoreList->find_version(): refactor for testability.

In order to address weaknesses in the documentation of find_version() in
CoreList.pod, we first had to address its lack of unit tests.  It was
previously only exercised inside the 'corelist' utility.  Refactored
function a bit to expose all its branches for testing.  Then added tests
for the function with and without arguments.  Corrected documentation
for find_version() in CoreList.pod.

Documentation subsequently clarified per feedback from Steve Parker.

For: RT # 125563 (1st of 2 problems cited in that ticket).

3 files changed, 20 insertions, 5 deletions

diff --git a/dist/Module-CoreList/lib/Module/CoreList.pm b/dist/Module-CoreList/lib/Module/CoreList.pm
index 49b376380e..59316ed3ca 100644
--- a/dist/Module-CoreList/lib/Module/CoreList.pm
+++ b/dist/Module-CoreList/lib/Module/CoreList.pm
@@ -74,9 +74,12 @@ sub find_modules {
 
 sub find_version {
     my $v = shift;
-    $v = shift if eval { $v->isa(__PACKAGE__) };
+    if ($v->isa(__PACKAGE__)) {
+        $v = shift;
+        return if not defined $v;
+    }
     return $version{$v} if defined $version{$v};
-    return undef;
+    return;
 }
 
 sub is_deprecated {
diff --git a/dist/Module-CoreList/lib/Module/CoreList.pod b/dist/Module-CoreList/lib/Module/CoreList.pod
index b32335e353..d8807bf8b4 100644
--- a/dist/Module-CoreList/lib/Module/CoreList.pod
+++ b/dist/Module-CoreList/lib/Module/CoreList.pod
@@ -73,8 +73,11 @@ you may provide a list of perl versions to limit the regex search.
 
 =item C<find_version( PERL_VERSION )>
 
-Takes a perl version as an argument. Returns that perl version if it exists or C<undef>
-otherwise.
+Takes a perl version as an argument. Upon successful completion, returns a
+reference to a hash.  Each element of that hash has a key which is the name of
+a module (I<e.g.,> 'File::Path') shipped with that version of perl and a value
+which is the version number (I<e.g.,> '2.09') of that module which shipped
+with that version of perl .  Returns C<undef> otherwise.
 
 =item C<is_core( MODULE, [ MODULE_VERSION, [ PERL_VERSION ] ] )>
 
diff --git a/dist/Module-CoreList/t/corelist.t b/dist/Module-CoreList/t/corelist.t
index c129584a07..db09f48f4e 100644
--- a/dist/Module-CoreList/t/corelist.t
+++ b/dist/Module-CoreList/t/corelist.t
@@ -1,7 +1,7 @@
 #!perl -w
 use strict;
 use Module::CoreList;
-use Test::More tests => 29;
+use Test::More tests => 32;
 
 BEGIN { require_ok('Module::CoreList'); }
 
@@ -106,3 +106,12 @@ is(Module::CoreList::removed_from('CPANPLUS::inc'), 5.010001,
     cmp_ok($warnings_count, '==', 0,
            "an undefined version does not produce warnings rt#123556");
 }
+
+ok(! defined(Module::CoreList->find_version()),
+    "Lacking an argument, Module::CoreList->find_version() returns undef");
+my $v = 5.022;
+is(ref(Module::CoreList->find_version($v)), 'HASH',
+    "With argument, Module::CoreList->find_version() returns hashref");
+$v = 5.022000;
+is(ref(Module::CoreList->find_version($v)), 'HASH',
+    "With argument, Module::CoreList->find_version() returns hashref");