update docs

diff --git a/bin/perltidy b/bin/perltidy
index 7fb447b49e4e7dfa80aff526f98c736ded92a538..c57a461b86e042c9f1769faefce649e256a0b1f9 100755 (executable)
--- a/bin/perltidy
+++ b/bin/perltidy
@@ -5571,6 +5571,16 @@ and B<--dump-short-names>, all described below, may all be helpful.
 
 =back
 
+=item B<Skipping a line with an unknown parameter>
+
+Versions of perltidy greater than 20240511 have an option to filter
+unrecognized parameters from a perltidy command file.  If a line in the file
+begins with B<three dashes> followed by a parameter name (rather than one or
+two), then the line will be removed if the parameter is unknown. Otherwise, a
+dash will be removed to make the line valid.  This option was added to allow a
+single command file to be used during the transition to a new version of
+perltidy.
+
 =item B<Creating a new abbreviation>
 
 A special notation is available for use in a F<.perltidyrc> file
@@ -6159,9 +6169,9 @@ B<Notes and Limitations:>
 =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> operations.  It
-will also work for some other common cases, such as direct access to individual
-elements of the @_ array. However if the coding for arg extraction is complex
-then the number of sub args will be considered indeterminate.
+will also work for direct access to specific elements of the @_ array.  However
+if the coding for arg extraction is complex then the number of sub args will be
+considered indeterminate and a count cannot be checked.
 
 =item *
 Sub calls made without parentheses around the args are not checked.

diff --git a/lib/Perl/Tidy.pm b/lib/Perl/Tidy.pm
index cb7d8b3809fe7fbf405a113e2f7a801a70deded5..36a08054c80959527511ae2d754b1e9d821c6227 100644 (file)
--- a/lib/Perl/Tidy.pm
+++ b/lib/Perl/Tidy.pm
@@ -4724,6 +4724,8 @@ EOM
 sub make_grep_alias_string {
     my ($rOpts) = @_;
 
+    # pre-process the --grep-alias-list parameter
+
     # Defaults: list operators in List::Util
     # Possible future additions:  pairfirst pairgrep pairmap
     my $default_string = join SPACE, qw(
@@ -5649,6 +5651,20 @@ sub filter_unknown_options {
 sub read_config_file {
 
     my ( $rconfig_string, $config_file, $rexpansion ) = @_;
+
+    # Read and process the contents of a perltidyrc command file
+
+    # Given:
+    #   $rconfig_string = ref to the file as a string
+    #   $config_file = name of the file, for error reporting
+    #   $rexpansion = ref to hash of abbreviations; if this config file defines
+    #                 any abbreviations they will be added to it
+
+    # Return:
+    #   \@config_list = ref to final parameters and values which will be
+    #     placed in @ARGV for processing by GetOptions
+    #   $death_message = error message returned if a fatal error occurs
+
     my @config_list = ();
 
     # file is bad if non-empty $death_message is returned
@@ -5754,6 +5770,15 @@ sub strip_comment {
 
     # Strip any comment from a command line
     my ( $instr, $config_file, $line_no ) = @_;
+
+    # Given:
+    #   $instr = string with the text of an input line
+    #   $config_file = filename, for error messages
+    #   $line_no = line number, for error messages
+    # Return:
+    #   string with any comment removed
+    #   $msg = any error message
+
     my $msg = EMPTY_STRING;
 
     # check for full-line comment