Yes, the documentation for File::Find would be improved a great deal if it were to actually mention (or even, *gasp*, explain) the basic concept of what the module does. ;)

It never says, for example:

For each directory you specify, File::Find calls a function that you provide (&wanted) for each file and directory found in that directory, every subdirectory, every subsubdirectory, etc., allowing you to "do something" for each file/directory within an entire directory tree. To use File::Find, you have to write a function that, each time it gets called, will decide what should be done with a specific file [for example, based on whether it is an ordinary file (-f $_) or if the file name matches some pattern (/\.html?$/i)] and then perform those operation(s). [...]

It mearly says that "it traverses a directory tree" and that you pass it a "wanted" function and talks about various details. It never actually says that "wanted" is called once for each file, much less explain the concept.

This is rather sad as File::Find is part of the base distribution. Many modules don't enjoy this level of attention and so are often just the ramblings of a lone hacker trying to offer something useful to the community. The lone hacker may not have great language skills (especially in English which might be "a second language") or have other reasons why the documentation doesn't really shine.

So modules are a very mixed bag. If you find one that has documentation that gives you a hard time, the best thing that you can do is to get the documentation updated. The most important step in that process is finding someone motivated enough to actually produce and submit a patch to the module maintainer and then follow-up if needed. I suggest you look to yourself for that.

Then you need to get someone to write some decent documentation. Perhaps just asking about the module here and requesting specific suggestions for documentation updates could get you the raw material for producing a patch.

        - tye (but my friends call me "Tye")