Login
Minor textual cleanup on docs for policies A-M
authorAndy Lester <andy@petdance.com>
Fri, 14 Jul 2006 05:44:25 +0000 (05:44 +0000)
committerAndy Lester <andy@petdance.com>
Fri, 14 Jul 2006 05:44:25 +0000 (05:44 +0000)
17 files changed:
lib/Perl/Critic/Policy/BuiltinFunctions/ProhibitSleepViaSelect.pm
lib/Perl/Critic/Policy/BuiltinFunctions/ProhibitStringyEval.pm
lib/Perl/Critic/Policy/BuiltinFunctions/ProhibitUniversalIsa.pm
lib/Perl/Critic/Policy/BuiltinFunctions/RequireBlockGrep.pm
lib/Perl/Critic/Policy/BuiltinFunctions/RequireBlockMap.pm
lib/Perl/Critic/Policy/BuiltinFunctions/RequireGlobFunction.pm
lib/Perl/Critic/Policy/BuiltinFunctions/RequireSimpleSortBlock.pm
lib/Perl/Critic/Policy/CodeLayout/ProhibitHardTabs.pm
lib/Perl/Critic/Policy/CodeLayout/ProhibitParensWithBuiltins.pm
lib/Perl/Critic/Policy/CodeLayout/ProhibitQuotedWordLists.pm
lib/Perl/Critic/Policy/ControlStructures/ProhibitCascadingIfElse.pm
lib/Perl/Critic/Policy/ControlStructures/ProhibitUnreachableCode.pm
lib/Perl/Critic/Policy/Documentation/RequirePodAtEnd.pm
lib/Perl/Critic/Policy/InputOutput/ProhibitReadlineInForLoop.pm
lib/Perl/Critic/Policy/Modules/ProhibitEvilModules.pm
lib/Perl/Critic/Policy/Modules/RequireExplicitPackage.pm
lib/Perl/Critic/Policy/Modules/RequireVersionVar.pm

index 51ce6a7..152919f 100644 (file)
@@ -57,9 +57,9 @@ Perl::Critic::Policy::BuiltinFunctions::ProhibitSleepViaSelect
 =head1 DESCRIPTION
 
 Conway discourages the use of C<select()> for performing non-integer
-sleeps.  Although its documented in L<perlfunc>, its something that
-generally requires the reader to RTFM to figure out what C<select()>
-is supposed to be doing.  Instead, Conway recommends that you use the
+sleeps.  Although documented in L<perlfunc>, it's something that
+generally requires the reader to read C<perldoc -f select> to figure out what it should be
+doing.  Instead, Conway recommends that you use the
 C<Time::HiRes> module when you want to sleep.
 
   select undef, undef, undef, 0.25;         # not ok
index 716b5b7..60efdbd 100644 (file)
@@ -59,7 +59,7 @@ Perl::Critic::Policy::BuiltinFunctions::ProhibitStringyEval
 
 =head1 DESCRIPTION
 
-The string form of eval is recompiled every time it is executed,
+The string form of C<eval> is recompiled every time it is executed,
 whereas the block form is only compiled once.  Also, the string form
 doesn't give compile-time warnings.
 
index 4182215..c565e99 100644 (file)
@@ -58,7 +58,7 @@ Perl::Critic::Policy::BuiltinFunctions::ProhibitUniversalIsa
   print UNIVERSAL::isa($obj, 'Foo::Bar') ? 'yes' : 'no';  #not ok
   print eval { $obj->isa('Foo::Bar') } ? 'yes' : 'no';    #ok
 
-As of Perl 5.9.3, the use of UNIVERSAL::isa as a function has been
+As of Perl 5.9.3, the use of C<UNIVERSAL::isa> as a function has been
 deprecated and the method form is preferred instead.  Formerly, the
 functional form was recommended because it gave valid results even
 when the object was C<undef> or an unblessed scalar.  However, the
index ef1aea7..0f00740 100644 (file)
@@ -63,7 +63,7 @@ Perl::Critic::Policy::BuiltinFunctions::RequireBlockGrep
 
 =head1 DESCRIPTION
 
-The expression form of C<grep> and C<map> is awkward and hard to read.
+The expression forms of C<grep> and C<map> are awkward and hard to read.
 Use the block forms instead.
 
   @matches = grep  /pattern/,    @list;        #not ok
index f8763dc..ce11290 100644 (file)
@@ -59,7 +59,7 @@ Perl::Critic::Policy::BuiltinFunctions::RequireBlockMap
 
 =head1 DESCRIPTION
 
-The expression form of C<grep> and C<map> is awkward and hard to read.
+The expression forms of C<grep> and C<map> are awkward and hard to read.
 Use the block forms instead.
 
   @matches = grep   /pattern/,   @list;        #not ok
index 417737d..927c751 100644 (file)
@@ -52,8 +52,8 @@ Perl::Critic::Policy::BuiltinFunctions::RequireGlobFunction
 
 =head1 DESCRIPTION
 
-Conway discourages the use of the C<E<lt>..E<gt>> construct for globbing, as
-its heavily associated with I/O in most people's minds.  Instead, he recommends
+Conway discourages the use of the C< <..> > construct for globbing, as it is easily
+confused with the angle bracket file input operator.  Instead, he recommends
 the use of the C<glob()> function as it makes it much more obvious what you're
 attempting to do.
 
index 985dedf..7caf40b 100644 (file)
@@ -63,7 +63,7 @@ Perl::Critic::Policy::BuiltinFunctions::RequireSimpleSortBlock
 
 Conway advises that sort functions should be simple.  Any complicated
 operations on list elements should be computed and cached (perhaps via
-a Schwartzian Transform) before the sort rather than computed inside
+a Schwartzian Transform) before the sort, rather than computed inside
 the sort block, because the sort block is called C<N log N> times
 instead of just C<N> times.
 
index 2413e3b..eb70ba0 100644 (file)
@@ -67,7 +67,7 @@ those tabs are anywhere other than a leading position.  Because
 various applications and devices represent tabs differently, they can
 cause you code to look vastly different to other people.  Any decent
 editor can be configured to expand tabs into spaces.  L<Perl::Tidy>
-also does this for you.  
+also does this for you.
 
 This Policy catches all tabs in your source code, including POD, quotes,
 and HEREDOCS.  However, tabs in a leading position are allowed.  If you want
index 3ee29e1..02db06f 100644 (file)
@@ -154,10 +154,10 @@ Perl::Critic::Policy::CodeLayout::ProhibitParensWithBuiltins
 
 =head1 DESCRIPTION
 
-Conway suggests that all built-in functions should be called without
-parenthesis around the argument list.  This reduces visual clutter and
+Conway suggests that all built-in functions be called without
+parentheses around the argument list.  This reduces visual clutter and
 disambiguates built-in functions from user functions.  Exceptions are
-made for C<my>, C<local>, and C<our> which require parenthesis when
+made for C<my>, C<local>, and C<our> which require parentheses when
 called with multiple arguments.
 
   open($handle, '>', $filename); #not ok
index e29bd1c..f2066bc 100644 (file)
@@ -91,11 +91,10 @@ Perl::Critic::Policy::CodeLayout::ProhibitQuotedWordLists
 
 =head1 DESCRIPTION
 
-Conway doesn't mention this, but I think C<qw()> is an underutilized
+Conway doesn't mention this, but I think C<qw()> is an underused
 feature of Perl.  Whenever you need to declare a list of one-word
-literals, the C<qw()> operator is wonderfully concise and saves you
-lots of keystrokes.  And using C<qw()> makes it easy to add to the
-list in the future.
+literals, the C<qw()> operator is wonderfully concise, and makes
+it easy to add to the list in the future.
 
   @list = ('foo', 'bar', 'baz');  #not ok
   @list = qw(foo bar baz);        #ok
@@ -103,7 +102,7 @@ list in the future.
 =head1 CONSTRUCTOR
 
 This Policy accepts an additional key-value pair in the constructor.
-The key must be 'min_elements' and the value is the minimum number of
+The key must be C<min_elements> and the value is the minimum number of
 elements in the list.  Lists with fewer elements will be overlooked by
 this Policy.  The default is 2.  Users of Perl::Critic can configure
 this in their F<.perlcriticrc> file like this:
index f218a71..364f2a7 100644 (file)
@@ -72,7 +72,7 @@ Perl::Critic::Policy::ControlStructures::ProhibitCascadingIfElse
 
 Long C<if-elsif> chains are hard to digest, especially if they are
 longer than a single page or screen.  If testing for equality, use a
-hash-lookup instead.  See L<Switch> for another approach.
+hash lookup instead.  See L<Switch> for another approach.
 
   if ($condition1) {         #ok
       $foo = 1;
@@ -93,7 +93,7 @@ hash-lookup instead.  See L<Switch> for another approach.
 =head1 CONSTRUCTOR
 
 This policy accepts an additional key-value pair in the C<new> method.
-The key should be 'max_elsif' and the value should be an integer
+The key should be C<max_elsif> and the value should be an integer
 indicating the maximum number of C<elsif> alternatives to allow.  The
 default is 2.  When using the L<Perl::Critic> engine, these can be
 configured in the F<.perlcriticrc> file like this:
index d5c62ff..f6764b0 100755 (executable)
@@ -104,11 +104,17 @@ L<Carp> are also included.
 
 Code is reachable if any of the following conditions are true:
 
-  * Flow-altering statement has a conditional attached to it
-  * Statement is on the right side of an operator C<&&>, C<||>, C<and>, or C<or>.
-  * Code is prefixed with a label (can potentially be reached via C<goto>)
-  * Code is a subroutine
-  *
+=over 4
+
+=item * Flow-altering statement has a conditional attached to it
+
+=item * Statement is on the right side of an operator C<&&>, C<||>, C<and>, or C<or>.
+
+=item * Code is prefixed with a label (can potentially be reached via C<goto>)
+
+=item * Code is a subroutine
+
+=back
 
 =head1 EXAMPLES
 
index 194d56d..3285906 100644 (file)
@@ -68,7 +68,7 @@ Perl::Critic::Policy::Documentation::RequirePodAtEnd
 =head1 DESCRIPTION
 
 Perl stops processing code when it sees an C<__END__> statement.  So,
-to save processor cycles, it's more efficient to store all
+to save processing time, it's faster to put
 documentation after the C<__END__>.  Also, writing all the POD in one
 place usually leads to a more cohesive document, rather than being
 forced to follow the layout of your code.  This policy issues
index 16e2522..b79349e 100644 (file)
@@ -54,7 +54,7 @@ Perl::Critic::Policy::InputOutput::ProhibitReadlineInForLoop
 =head1 DESCRIPTION
 
 Using the readline operator in a C<for> or C<foreach> loop is very
-inefficient.  The iteration list of the loop creates a list context,
+slow.  The iteration list of the loop creates a list context,
 which causes the readline operator to read the entire input stream
 before iteration even starts.  Instead, just use a C<while> loop,
 which only reads one line at a time.
index dab0e30..63dc779 100644 (file)
@@ -103,9 +103,9 @@ C<m/$module_name/> will be forbidden.  For example:
 would cause all modules that match C<m/Acme::/> to be forbidden.  You
 can add any of the C<imxs> switches to the end of the pattern, but
 beware that your pattern should not contain spaces, lest the parser
-will get confused.
+get confused.
 
-By default, there aren't any prohibited modules (although I can think
+By default, there are no prohibited modules (although I can think
 of a few that should be).
 
 =head1 NOTES
index c007806..3d57fee 100644 (file)
@@ -109,8 +109,7 @@ Perl::Critic::Policy::Modules::RequireExplicitPackage
 
 =head1 DESCRIPTION
 
-Conway doesn't specifically mention this, but I've come across it in
-my own work.  In general, the first statement of any Perl module or
+In general, the first statement of any Perl module or
 library should be a C<package> statement.  Otherwise, all the code
 that comes before the C<package> statement is getting executed in the
 caller's package, and you have no idea who that is.  Good
@@ -119,8 +118,8 @@ innards to itself.
 
 As for scripts, most people understand that the default package is
 C<main>, so this Policy doesn't apply to files that begin with a perl
-shebang.  But it you want to require an explicit C<package>
-declaration in all files, including scripts, then add the following to
+shebang.  If you want to require an explicit C<package>
+declaration in all files, including programs, then add the following to
 your F<.perlcriticrc> file
 
   [Modules::RequireExplicitPackage]
index fb6906a..5207409 100644 (file)
@@ -84,7 +84,7 @@ Perl::Critic::Policy::Modules::RequireVersionVar
 
 =head1 DESCRIPTION
 
-Every Perl file (modules, libraries, and scripts) should have a
+Every Perl file (modules, libraries, and programs) should have a
 C<$VERSION> variable.  The C<$VERSION> allows clients to insist on a
 particular revision of your file like this: