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")

In reply to (tye)Re: Why are you struggling with Modules by tye
in thread Struggling with Modules by c

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post, it's "PerlMonks-approved HTML":


  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.