Documenting CPAN::Shell->install etc

Awesome. You know that CPAN.pm migrated to github, right? So you can fork
from http://github.com/andk/cpanpm/tree/master and hack away at
documentation.

I've been meaning to create lib/CPAN/API.pod anyway to start to consolidate
this kind of stuff. I just ran out of bandwidth. If there are bits I can
help with, please let me know (along with your timeframe) and I'll tell you
whether I can commit to it.

When I looked at this for a question on stackoverflow, I concluded that the
thing to do was check $mod->uptodate rather than rely on the return value of
install.

my $mod = CPAN::Shell->expand("Module", "Module::Name::Here");
if ( ! $mod->uptodate ) {
$mod->install;
die "Problems installing" unless $mod->uptodate;
}

As I recall, a lot of things return to shortcut control flow and those
aren't necessarily consistent in returning true/false. Depending on how
they are invoked, I think some of those values just fall through to the end
of install.

I'd prefer to see things either return true/false, but it may be that things
should return an object that can provide context. E.g. "tests passed, but
dependency was missing" -- is that success for "test Foo::Bar" or failure?
If running CPAN::Shell->test(*) then it's success, but when
CPAN::Shell->install calls test() then it's a failure. (That might be a
contrived example, so please don't nit pick me over it.) Many of the
functions in CPAN::Distribution do return CPAN::Distrostatus objects, but I
don't think that works for routines from Shell that might be called against
module names, not distribution names.

-- David

Yes, and that's even in the manpage:

Note that install() gives no meaningful return value. See uptodate().
Given that you can pass an array of arbitrary length to install() but
uptodate() is for one object, I figured that I cannot produce a
meaningful return value. Jos once mentioned that this is more or less
the main reason why he created CPANPLUS.

?! That seems like an overreaction. :-)

If it's an arbitrary length array, what about returning a list of "success
objects"?

Through, really, I'd rather spend my energy on improving the underlying
object API rather than having people use "CPAN::Shell" as the main
interface.

-- David

In article (Andreas J. Koenig)
wrote:
Yes, I know about that part, but there's also all of the possible
messages it might print. I'd like to capture those to see if I can suss
out what went wrong. I'd like to document those diagnotistics to. :)