Generally the docs that come with a specific module are the best place to get info about the module. A couple of the most useful modules (CGI and DBI) have books dedicated to them.

Perhaps you're looking for help at a higher level tho'? Documentation about which modules are available and what they are for. It's sometimes difficult to answer questions like "Which modules would be useful for this project?" Often the best solution to this is to go to search.cpan.org and just search for likely looking names.

A few years ago, O'Reilly released the Perl Resource Kit which was a number of new Perl books together with a CD containing a snapshot of CPAN (among other things). This included a 2 volume printed copy of various CPAN modules' documentation. Another, far more useful, book in the set was called "Programming With Perl Modules" and it was an introduction to which modules could be used for various tasks. The PRK itself didn't sell particularly well, but I've often thought that the "Programming With Perl modules" book would sell well if sold separately.

Your question is somewhat unclear to me.

I assume that you are looking for documentation for the Perl modules you get from CPAN or somewhere else. Perl modules normally include their documentation right in the source code in the POD (Plain Old Documentation) format, and different outputs are generated when you install the module. Under UNIX, perldoc modulename will show you the documentation and with ActiveState Perl under Windows, the documentation will be included with the HTML documentation for ActiveState Perl itself.

If you look for documentation beyond what's included and / or automatically generated, there are not many possibilities. Some of the Books about Perl discuss several important modules like CGI.pm, at other times, the module author might be of assistance, but in general, Perl modules lack good documentation, as it is the case with most open source stuff. Of course, the Open Source Apology for not providing documentation also holds here, you can still look at the module source code to figure out how it works :).

A special case is the Image::Magick module, where the documentation is not included with the Perl modules (but only a meagre page telling us it has more bugs than the imagemagick program suite alone), but the Perl documentation comes with the ImageMagick program suite itself (for reasons unknown to me).

Of course, if you have any specific questions or are in search of examples, a question here will most likely turn up many useful answers.

...but in general, Perl modules lack good documentation...

I have to disagree, because IMHO, Perl Modules come with a rather good documentation, as you mentioned the perldoc. This is sufficient in most cases, if you just want to use the module. Of course, if you want to write and/or _understand_ a module, you have to look elsewhere.

Hmmm - after desperately searching for a module in the standard distribution of Perl, I have to admit that I can't come up with an example of bad documentation. I only remember that the documentation for HTML::Parser was really bad, as they documented that one could "use either the version 2 compatible interface" (which was nowhere documented but maybe in the obsolete version of this module that was no more around) or the new (and completely different) version 3 interface, but the documentation completely lacked any example. Maybe that's because the documentation for this module is supposed to be in some book, I don't know.

But nonetheless, I have to admit, Perl module documentation is not bad in general, it was only my perception of the documentation (you seldom notice good documentation :).

#!/usr/bin/perl -w
use strict;
my ($module)=@ARGV or die "Usage: $0 <absolute path to module>\n";
open (MODULE, $module) or die "Can't open $module: $!\n";
while (<MODULE>) {
  print if /^#/;
}
[download]