Bug #122522 for Module-CheckDep-Version: doc describes purpose incorrectly

In Module-CheckDep-Version-0.05, the doc says of check_deps(): # and either returns or prints to the screen a list of each dependency that # requires a version bump. This is incorrect. The code makes no attempt at all to determine whether a dependency "requires a version bump". All it determines is, as stated in the "description" section, "dependencies that have updated versions". It's determining whether a newer version of the dependency is *available*, not whether it's *required*. The documentation should be accurate about the function's behaviour. In addition to the bit that I quoted above, the clause in the "description" section about "behind in version" should be changed: I can't quite make sense of it, but it seems misleading. The documentation should really go further, and advise caution in how the result of the function is used. Since one side of the comparison being made is module versions that are currently available, one would normally expect the other side of the comparison to be module versions that were available at some earlier time, perhaps a list of module versions that one has audited. One would expect the list of module versions currently available to eventually make its way onto the other side of the comparison, causing the function to yield no results until there's a new release of something. But instead the other side of the comparison is the list of module versions that a module declares as its requirements. This is not a like-for-like comparison. It is totally normal for the minimum required versions of a module's dependencies to be very old versions, typically the version that added a critical feature or fixed a critical bug. It is not routine for this requirement to change at all, let alone to be bumped to the latest available version. So the behaviour of the check_deps() function, even without the documentation, seems to encourage users to repeatedly change the minimum required dependency versions that they declare, in order to get empty output from check_deps(), regardless of the actual requirements of their code. This behaviour would be damaging to the CPAN ecosystem. check_deps() maximises the damage by always encouraging bumping the declared dependency to the latest module version available, which will fairly often be a version that has some portability problem or stringent dependency of its own, which would be a bad thing to import by falsely declaring a dependency. So the documentation for Module::CheckDep::Version ought to warn the user clearly against this type of seductive but dangerous interpretation of check_deps()'s output. It should describe what kind of use can be safely made of the function. -zefram