perlcritic man page

Discussion in 'Perl' started by John Dollar, Apr 20, 2007.

  1. John Dollar

    John Dollar Guest

    Is it just me, or is the man page for perlcritic messed up?

    I ask because it's very confusing when it comes to severity.

    First, it states for the "-severity N" option:

    Severity values are integers ranging from 1 (least severe) to 5 (most
    severe). The default is 5.

    (which makes you figure it defaults to the MOST SEVERE.)

    Then later on, for "-severity NAME":

    SEVERITY NAME ...is equivalent to... SEVERITY NUMBER
    --------------------------------------------------------
    -severity gentle -severity 5
    -severity stern -severity 4
    -severity harsh -severity 3
    -severity cruel -severity 2
    -severity brutal -severity 1

    Which is 100% the opposite.

    Then for the "-gentle | -stern | -harsh | -cruel | -brutal" options:

    These are named shortcuts for setting the "-severity" option. For
    example, "-cruel" is equivalent to "-severity 4".

    Umm...no...according to the table above, 4 is "-stern", not "-cruel".

    And, of course, the real answer is that the table for "-severity NAME" is the
    *ONLY* place that it is correct. However, it DOES default to 5, which is the
    LEAST severe.

    So, either this is written in some new version of the English language I've
    never seen where words change their meanings paragraph to paragraph, or it's
    completely confusing/wrong/needs fixing/etc./etc.
    John Dollar, Apr 20, 2007
    #1
    1. Advertising

  2. John Dollar

    thaljef

    Joined:
    Apr 27, 2007
    Messages:
    1
    Severity levels in perlcritic

    In the early versions, perlcritic only supported the numeric severity levels. But many people said it was hard to remember if "1" was the most critical or least critical setting. So I added the named severity levels to make it a little easier. I didn't realize it at the time, but I had overloaded the meaning of "severity". I agree that it still isn't intuitive, so please allow me to try and explain...

    Each violation has a numeric severity level assigned to it (ranging from 1 to 5). Violations with larger numbers are considered more important than those with smaller numbers.

    Now when you use a numeric argument with the -severity option, think of it as the minimum level of importance. So "-severity 5" reports only the most important violations.

    But when you use a named argument with the -severity option, think of it as the intensity of criticism. So "-severity gentle" also reports only the most important violations.

    Essentially, the named and numeric severity levels have an inverse effect. The stronger names equate to smaller numbers, and weaker names equate to larger numbers. But most folks associate greater size with greater strength, so this arrangement can definitely be confusing.

    You are absolutely correct about the error in the docs. It should read:

    "-cruel" is equivalent to "-severity 2"​

    Thaks for spotting that. I'll fix it in the next release.

    So let me know if that helps clear things up, and I'll try to beef up the documentation as well. If you have suggestions on how to improve the interface, you're totally welcome to send your ideas to the perlcritic team at "dev at perlcritic dot tigris dot org". And thanks for your helpful feedback.

    Cheers.

    -Jeff
    Last edited: Apr 27, 2007
    thaljef, Apr 27, 2007
    #2
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. march
    Replies:
    9
    Views:
    252
    James Mills
    Jul 23, 2010
  2. Andrea Fazzi

    man page from rdoc source

    Andrea Fazzi, Dec 8, 2007, in forum: Ruby
    Replies:
    1
    Views:
    127
    Andrea Fazzi
    Dec 9, 2007
  3. Jaap Karssenberg

    conflict between man perlipc and man perlfunc !?

    Jaap Karssenberg, Jan 9, 2004, in forum: Perl Misc
    Replies:
    0
    Views:
    138
    Jaap Karssenberg
    Jan 9, 2004
  4. Vincent Lefevre

    CPAN and man page installation

    Vincent Lefevre, Feb 24, 2008, in forum: Perl Misc
    Replies:
    3
    Views:
    86
    Vincent Lefevre
    Feb 27, 2008
  5. Peng Yu
    Replies:
    1
    Views:
    157
    Rainer Weikusat
    Sep 8, 2011
Loading...

Share This Page