From: Steve Hancock <perltidy@users.sourceforge.net>
Date: Fri, 26 Apr 2024 05:12:32 +0000 (-0700)
Subject: clean up -wma documentation
X-Git-Tag: 20240511~16
X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=e3c95156311c225c14d321423f423236898a4aa6;p=perltidy.git

clean up -wma documentation
---

diff --git a/bin/perltidy b/bin/perltidy
index bac9c505..fd6f0d18 100755
--- a/bin/perltidy
+++ b/bin/perltidy
@@ -6100,9 +6100,9 @@ and
 This may or may not be an error, but it is worth checking. It might become an
 error in the future if sub C<Fault> starts to access C<$self>.
 
-=item B<o:> (B<overcount): the number of call args exceeds the expected number.
+=item B<o:> (B<overcount>): the number of call args exceeds the expected number.
 
-=item B<u:> (B<undercount): the number of call args is less than the expected number.
+=item B<u:> (B<undercount>): the number of call args is less than the expected number.
 
 For example
 
@@ -6123,10 +6123,14 @@ possibility, but it is worth checking.  The simple static processing done by per
 
 =back
 
-B<Some Limitations:>
+B<Notes and Limitations:>
 
 =over 4
 
+=item *
+When prototypes or signatures are given, they are used to determine the
+expected number of sub arguments. Otherwise, the sub text is scanned.
+
 =item *
 This option works best for subs which unpack call args in an orderly
 manner near the beginning of the sub from C<@_> and/or with C<shift>
@@ -6175,19 +6179,20 @@ string of space- or comma-separated names. All subs with those names will be
 skipped, regardless of package.
 
 =item *
-B<--warn-mismatched-arg-undercount-cutoff=n>, or
-B<-wmauc=n>, can be used to avoid undercount warnings when the number of
-args expected is B<n> or less.  Please note that this number B<n> is the number
-of args from the point of view of the sub definition, so an object like
-C<$self> passed with an arrow operator counts as one arg.
-
-The default value is B<n=3>. This has been found to allow most programs to pass
-without warnings, but it should be reduced if possible for better error
+B<--warn-mismatched-arg-undercount-cutoff=n>, or B<-wmauc=n>, can be used to
+avoid undercount warnings when the number of args expected is B<n> or less.
+Please note that this number B<n> is the number of args from the point of
+view of the sub definition, so an object like C<$self> passed with an arrow
+operator counts as one arg.
+
+The default value is B<n=3>. This has been found to allow most programs to
+pass without warnings, but it should be reduced if possible for better error
 checking.  The minimum possible value of B<n> needed to avoid triggering an
-error for a program can be determined by running with B<-wmauc=0>, or by
-running with B<--dump-mismatched-args>. The output shows, for each mismatch,
-the number of args expected by a sub plus the range of the number of args
-actually passed to it.
+error for a program can be determined by running with B<-wma -wmauc=0>.  If
+there are undercount errors, a note at the bottom of the error output
+indicates the value of B<n> required to avoid reporting them.
+
+=back
 
 To illustrate these controls,
 
@@ -6199,8 +6204,6 @@ and only warn of undercounts for subs expecting more than 2 args.
 
 =back
 
-=back
-
 =head2 B<Working with MakeMaker, AutoLoader and SelfLoader>
 
 The first $VERSION line of a file which might be eval'd by MakeMaker
diff --git a/lib/Perl/Tidy/Formatter.pm b/lib/Perl/Tidy/Formatter.pm
index 1146309e..0dbc2e75 100644
--- a/lib/Perl/Tidy/Formatter.pm
+++ b/lib/Perl/Tidy/Formatter.pm
@@ -9481,7 +9481,7 @@ sub dump_unusual_variables {
 
     # output for multiple types
     my $output_string = <<EOM;
-Issues abbreviations  u=unused  r=reused  s=multi-sigil  p=package crossing
+Issue abbreviations  u=unused  r=reused  s=multi-sigil  p=package crossing
 Line:Issue: Var: note
 EOM
     foreach my $item ( @{$rlines} ) {
@@ -14630,6 +14630,8 @@ sub cross_check_call_args {
     # Now look for issues
     #--------------------
     my @warnings;
+    my $max_shift_count_with_undercount = 0;
+    my $number_of_undercount_warnings   = 0;
 
     # Look at each key:
     foreach my $key ( keys %common_hash ) {
@@ -14757,6 +14759,10 @@ sub cross_check_call_args {
             # issue 'u': undercount
             if ($num_under_count) {
 
+                if ( $shift_count_min > $max_shift_count_with_undercount ) {
+                    $max_shift_count_with_undercount = $shift_count_min;
+                }
+
                 # Skip the warning for small lists with undercount
                 if (   $ris_mismatched_call_type->{'u'}
                     && $shift_count_min > $mismatched_arg_undercount_cutoff )
@@ -14768,6 +14774,7 @@ sub cross_check_call_args {
                     $note =
 "missing args at $num_under_count of $total calls($lines_under_count)";
 
+                    $number_of_undercount_warnings++;
                     push @warnings,
                       {
                         line_number     => $lno,
@@ -14791,7 +14798,13 @@ sub cross_check_call_args {
         } @warnings;
     }
 
-    return \@warnings;
+    my $hint = EMPTY_STRING;
+    if ($number_of_undercount_warnings) {
+        $hint = <<EOM;
+Note: use -wmauc=$max_shift_count_with_undercount or greater to prevent undercount warnings in this file
+EOM
+    }
+    return ( \@warnings, $hint );
 } ## end sub cross_check_call_args
 
 sub stringify_line_range {
@@ -14935,13 +14948,14 @@ sub warn_mismatched_args {
     # - warn-mismatched-arg-exclusion-list
     # - warn-mismatched-arg-undercount-cutoff
 
-    my $rwarnings = $self->cross_check_call_args(1);
+    my ( $rwarnings, $hint ) = $self->cross_check_call_args(1);
     return unless ( $rwarnings && @{$rwarnings} );
 
     my $wma_key       = 'warn-mismatched-args';
     my $output_string = "Begin scan for --$wma_key\n";
     $output_string .= <<EOM;
-Line:Mismatch:Name:#args:Min:Max: note
+Issue abbreviations a=arrow mismatch u=undercount o=overcount
+Line:Issue:Name:#args:Min:Max: note
 EOM
 
     # output the results, ignoring any excluded names
@@ -14961,6 +14975,7 @@ EOM
         $output_string .=
 "$lno:$letter:$name:$shift_count:$min_arg_count:$max_arg_count: $note\n";
     }
+    if ($hint) { $output_string .= $hint }
     $output_string .= "End scan for --$wma_key\n";
     warning($output_string);
 
@@ -14972,10 +14987,11 @@ sub dump_mismatched_args {
 
     # process a --dump-mismatched-args command
 
-    my $rwarnings = $self->cross_check_call_args(0);
+    my ( $rwarnings, $hint ) = $self->cross_check_call_args(0);
     return unless ( $rwarnings && @{$rwarnings} );
     my $output_string = <<EOM;
-Line:Mismatch:Name:#args:Min:Max: note
+Issue abbreviations a=arrow mismatch u=undercount o=overcount i=indeterminate
+Line:Issue:Name:#args:Min:Max: note
 EOM
     foreach my $item ( @{$rwarnings} ) {
         my $lno             = $item->{line_number};