Bug #41942 for Perl-Critic: Severity levels are wrong in POD

Wed Dec 24 19:41:57 2008 APOCAL [...] cpan.org - Ticket created

Subject:

Severity levels are wrong in POD

Hello, While arguing with a certain "jawnsy" on IRC we realized that we were looking at our configs from the opposite sides. The problem is with severity levels. I was using numbers, and he was using the string equivalents. Looking at the POD, it's contradictory and we were left scratching our heads! "Severity values are integers ranging from 1 (least severe) to 5 (most severe)." "-severity => 'gentle' -severity => 5" "-severity => 'brutal' -severity => 1" Looking at the code in Perl::Critic::Utils shows: Readonly::Hash my %SEVERITY_NUMBER_OF => ( gentle => 5, ... brutal => 1, ); This means the sentence in the POD must be wrong, and would need tweaking to correctly represent the concept of 5 being least severe, and 1 being the most severe. P.S. Thanks again for the excellent module! :) -- ~Apocalypse

Wed Dec 24 21:10:19 2008 perl [...] galumph.com - Correspondence added

Subject:	Re: [rt.cpan.org #41942] Severity levels are wrong in POD
Date:	Wed, 24 Dec 2008 20:09:51 -0600
To:	bug-Perl-Critic [...] rt.cpan.org
From:	Elliot Shank <perl [...] galumph.com>

APOCAL via RT wrote: Show quoted text

> This means the sentence in the POD must be wrong, and would need > tweaking to correctly represent the concept of 5 being least severe, and > 1 being the most severe.

The POD is correct, it's just what thing you're talking about. There's the severity level of an individual policy. So, for example, RequireUseStrict is a 5 (highest), because it's one of the most important things to have in order to avoid bugs. But RequirePodAtEnd is a 1 (lowest) because it doesn't really affect your code, just how you maintain your documentation. Then, there's the severity which you want perlcritic to use. Gentle is 5 (least strict). Brutal is 1 (most strict). You either specify the number itself, or you use the name and that gets translated into the number. Then, the policies are filtered by using only those with a severity greater than or equal to the strictness. So, when you specify --stern, perlcritic goes through the policies and finds those with severity greater than or equal to 4, which means only the severe policies will be applied (4 or 5). Yes, it's confusing. The two scales run in opposite order. There probably should have been some internal reversal of the scales so that the numbers meant the same thing, but it's a case of "it's too late now". Sorry.

Wed Dec 24 21:10:19 2008 The RT System itself - Status changed from 'new' to 'open'

Thu Dec 25 18:06:32 2008 perl [...] 0ne.us - Correspondence added

Subject:	Re: [rt.cpan.org #41942] Severity levels are wrong in POD
Date:	Thu, 25 Dec 2008 18:06:16 -0500
To:	bug-Perl-Critic [...] rt.cpan.org
From:	Apocalypse <perl [...] 0ne.us>

Hello, THANKS for clarifying this, it makes sense to me now! Maybe it would be useful to put what you just told me in the POD to make things more clearer for the next idiot like me who strolls by? :) We can always wish for a time machine to go back and "tidy" up things, but here's to a bright future for Perl::Critic! P.S. You can consider this ticket closed, and thanks again. Elliot Shank via RT wrote: Show quoted text

> <URL: http://rt.cpan.org/Ticket/Display.html?id=41942 > > > APOCAL via RT wrote: >

>> This means the sentence in the POD must be wrong, and would need >> tweaking to correctly represent the concept of 5 being least severe, and >> 1 being the most severe. >>

> > The POD is correct, it's just what thing you're talking about. > > There's the severity level of an individual policy. So, for example, RequireUseStrict is a 5 (highest), because it's one of the most important things to have in order to avoid bugs. But RequirePodAtEnd is a 1 (lowest) because it doesn't really affect your code, just how you maintain your documentation. > > Then, there's the severity which you want perlcritic to use. Gentle is 5 (least strict). Brutal is 1 (most strict). You either specify the number itself, or you use the name and that gets translated into the number. Then, the policies are filtered by using only those with a severity greater than or equal to the strictness. So, when you specify --stern, perlcritic goes through the policies and finds those with severity greater than or equal to 4, which means only the severe policies will be applied (4 or 5). > > Yes, it's confusing. The two scales run in opposite order. There probably should have been some internal reversal of the scales so that the numbers meant the same thing, but it's a case of "it's too late now". Sorry. > >

Thu Jan 15 17:29:35 2009 mgrimes [...] cpan.org - Correspondence added

With some very minor changes to the wording, I think this could be much clearer. Patch attached.

Index: lib/Perl/Critic.pm =================================================================== --- lib/Perl/Critic.pm (revision 2958) +++ lib/Perl/Critic.pm (working copy) @@ -294,12 +294,12 @@ B<-severity> is the minimum severity level. Only Policy modules that have a severity greater than C<$N> will be applied. Severity values -are integers ranging from 1 (least severe) to 5 (most severe). The -default is 5. For a given C<-profile>, decreasing the C<-severity> -will usually reveal more Policy violations. You can set the default -value for this option in your F<.perlcriticrc> file. Users can -redefine the severity level for any Policy in their F<.perlcriticrc> -file. See L<"CONFIGURATION"> for more information. +are integers ranging from 1 (least severe violations) to 5 (most +severe violations). The default is 5. For a given C<-profile>, +decreasing the C<-severity> will usually reveal more Policy violations. +You can set the default value for this option in your F<.perlcriticrc> +file. Users can redefine the severity level for any Policy in their +F<.perlcriticrc> file. See L<"CONFIGURATION"> for more information. If it is difficult for you to remember whether severity "5" is the most or least restrictive level, then you can use one of these named @@ -655,7 +655,7 @@ analyzing test scripts. Conversely, you may wish to enable only a specific subset of Policies when analyzing modules. -The Policies that ship with Perl::Critic are have been broken into the +The Policies that ship with Perl::Critic have been broken into the following themes. This is just our attempt to provide some basic logical groupings. You are free to invent new themes that suit your needs.

Thu Jan 15 22:31:25 2009 perl [...] galumph.com - Correspondence added

Subject:	Re: [rt.cpan.org #41942] Severity levels are wrong in POD
Date:	Thu, 15 Jan 2009 21:12:09 -0600
To:	bug-Perl-Critic [...] rt.cpan.org
From:	Elliot Shank <perl [...] galumph.com>

Mark Grimes via RT wrote: Show quoted text

> With some very minor changes to the wording, I think this could be much > clearer. > > Patch attached.

Thanks. Applied.

Sun Jan 18 21:38:24 2009 thaljef [...] cpan.org - Correspondence added

This has been fixed and released as Perl-Critic-1.095_001 to a CPAN near you. Thanks for reporting this bug. -Jeff

Sun Jan 18 21:38:25 2009 thaljef [...] cpan.org - Status changed from 'open' to 'resolved'

Bug #41942 for Perl-Critic: Severity levels are wrong in POD

Preferred bug tracker