I agree that making a perfectly executable synopsis is problematic for some modules, so you have to use judgement. I also agree that language extension modules are different. I didn't think of Exporter::VA as a language extension like strict. If it really is a language extension, then my preferences for the synopsis do not apply.

Perhaps my favorite synopsis is the one in CGI.

The idea of tearing off the shrink-wrap is to think about the initial user experience with a module. I don't know if you remember your first experience with use strict;, but I remember that mine was rough! It introduced a whole new way of coding for me. If Exporter::VA is to change the way that I code and become a 'way of life' module, the documentation needs to be especially clearly written. The strict perldoc is quite good, for example. Even with this documentation, I really had to read a detailed article about the requirements and benefits of strict before I was successful with it.

For ordinary modules that just do something clever, I like to try them out quickly. I typically evaluate five to ten modules a week, so speed is important to me.

Here is what I did to try out File::Slurp, which I think has a synopsis that is slightly more complex than my ideal, but it is actually fine how it is.

$ cpan
> install File::Slurp
> quit

$ mkdir fileslurp
$ cd fileslurp
$ perldoc File::Slurp
# This next bit is cut and paste:
$ cat > t.pl
               use File::Slurp;

               $all_of_it = read_file($filename);
               @all_lines = read_file($filename);

               write_file($filename, @contents)

               overwrite_file($filename, @new_contnts);

               append_file($filename, @additional_contents);

               @files = read_dir($directory);


$ vi t.pl

[download]
After pulling in my perl test-program template and a bit of editing I have this: 
<P>
#!/home/toma/perl58i/bin/perl
#!/home/toma/perl58i/bin/perl -d:ptkdb
#
# Tom Anderson
# Sat Jan 11 12:31:00 PST 2003
#
# Program to try out File::Slurp
#
#

my $VERSION=".01";

use strict;
use warnings;
use diagnostics;

use File::Slurp;

my $filename = "/etc/passwd";
my $all_of_it = read_file($filename);

print $all_of_it;

[download]

With very few keystrokes and very little time I have evaluated File::Slurp and my first impression is that it is a very good module. I understand what it does, although I have only scratched the surface. I think that the author of File::Slurp has done me a great favor by uploading this module to CPAN, because I got to experience it working perfectly the first time!

It should work perfectly the first time! - toma

In reply to Re: Re: Re: My module - my latest step by toma
in thread My module - my latest step by John M. Dlugosz

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.