From: Steve Hancock Date: Thu, 23 Nov 2023 14:57:02 +0000 (-0800) Subject: add note to docs about word-wrapping comments (see git#127) X-Git-Tag: 20230912.06~19 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=2ede5e32906671b995606b62a0b3660037aa2a9b;p=perltidy.git add note to docs about word-wrapping comments (see git#127) --- diff --git a/bin/perltidy b/bin/perltidy index 64a14833..9dacaf67 100755 --- a/bin/perltidy +++ b/bin/perltidy @@ -1756,6 +1756,12 @@ and side comments. The term B here refers to a full-line comment, whereas B will refer to a comment which appears on a line to the right of some code. +Perltidy does not do any word wrapping of commented text to match a selected +maximum line length. This is because there is no way to determine if this is +appropriate for the given content. However, an interactive program named +B is available in the B folder of the perltidy +distribution which can assist in doing this. + =over 4 =item B<-ibc>, B<--indent-block-comments> diff --git a/examples/perlcomment.pl b/examples/perlcomment.pl index c6143c76..6c0343e5 100755 --- a/examples/perlcomment.pl +++ b/examples/perlcomment.pl @@ -1,6 +1,6 @@ #!/usr/bin/perl -w # -# Walk through a perl script and reformat perl comments +# Walk through a perl script and reformat perl comments # using Text::Autoformat. # # usage: @@ -13,21 +13,30 @@ # # This file demonstrates using Perl::Tidy to walk through a perl file # and find all of its comments. It offers to reformat each group of -# consecutive full-line comments with Text::Autoformat. +# consecutive full-line comments with Text::Autoformat. # # This may or may not be useful, depending on your coding style. # Change it to suit your own purposes; see sub get_line(). # -# Uses: Text::Autoformat +# Uses: Text::Autoformat # Perl::Tidy # # Steve Hancock, March 2003 # Based on a suggestion by Tim Maher +# Also discussed in git#127 # +# Note that the indentation which is assumed for blocks of comments is whatever +# the indentation is in the input file. A potential problem is that if the +# input file has very long comments which have been out-dented, this may not +# give the desired result. This problem can be avoided by doing a preliminary +# formatting pass with perltidy which includes the parameter +# --nooutdent-long-comments (-nolc). + # TODO: (just ideas that probably won't get done) # -Handle lines of stars, dashes, etc better # -Need flag to limit changes to lines greater than some minimum length # -reformat side and hanging side comments + use strict; use Getopt::Std; use Text::Autoformat; @@ -40,7 +49,7 @@ my $usage = <new($line_length); - my $err=perltidy( - 'formatter' => $formatter, # callback object + my $err = perltidy( + 'formatter' => $formatter, # callback object 'source' => $fh, - 'argv' => "-npro -se", # dont need .perltidyrc - # errors to STDOUT + 'argv' => "-npro -se", # dont need .perltidyrc + # errors to STDOUT ); if ($err) { die "Error calling perltidy\n"; @@ -100,16 +109,16 @@ sub write_line { # Other lines go to stdout immediately my $self = shift; my $line_of_tokens = shift; - my $line_type = $line_of_tokens->{_line_type}; - ## my $input_line_number = $line_of_tokens->{_line_number}; + my $line_type = $line_of_tokens->{_line_type}; + ## my $input_line_number = $line_of_tokens->{_line_number}; my $input_line = $line_of_tokens->{_line_text}; # the original line my $rtoken_type = $line_of_tokens->{_rtoken_type}; # type of tokens my $rtokens = $line_of_tokens->{_rtokens}; # text of tokens # Just print non-code, non-comment lines if ( - $line_type ne 'CODE' # if it's not code, - || !@$rtokens # or is a blank line + $line_type ne 'CODE' # if it's not code, + || !@$rtokens # or is a blank line || $$rtoken_type[-1] ne '#' # or the last token isn't a comment ) { @@ -123,7 +132,7 @@ sub write_line { # - a full line comment (@$rtokens==1) # Output a line with a side comment, but remember it - if (@$rtokens > 1) { + if ( @$rtokens > 1 ) { $self->print($input_line); $self->{_in_hanging_side_comment} = 1; return; @@ -132,7 +141,7 @@ sub write_line { # A hanging side comment is a full-line comment immediately # following a side comment or another hanging side comment. # Output a hanging side comment directly - if ($self->{_in_hanging_side_comment}) { + if ( $self->{_in_hanging_side_comment} ) { $self->print($input_line); return; } @@ -163,11 +172,11 @@ sub print { sub append_comment { my ( $self, $input_line ) = @_; - my $rcomment_block = $self->{_rcomment_block}; + my $rcomment_block = $self->{_rcomment_block}; my $maximum_comment_length = $self->{_maximum_comment_length}; $$rcomment_block .= $input_line; - if (length($input_line) > $maximum_comment_length) { - $self->{_maximum_comment_length}=length($input_line); + if ( length($input_line) > $maximum_comment_length ) { + $self->{_maximum_comment_length} = length($input_line); } } @@ -182,12 +191,12 @@ sub append_comment { sub flush_comments { - my ($self) = @_; - my $rcomment_block = $self->{_rcomment_block}; - my $line_length = $self->{_line_length}; + my ($self) = @_; + my $rcomment_block = $self->{_rcomment_block}; + my $line_length = $self->{_line_length}; my $maximum_comment_length = $self->{_maximum_comment_length}; if ($$rcomment_block) { - my $comments = $$rcomment_block; + my $comments = $$rcomment_block; # we will just reformat lines longer than the desired length for now # TODO: this can be changed @@ -209,7 +218,7 @@ sub append_comment { } print $comments; $$rcomment_block = ""; - $self->{_maximum_comment_length}=0; + $self->{_maximum_comment_length} = 0; } } } @@ -229,7 +238,7 @@ sub queryu { sub ifyes { my $count = 0; ASK: - my $ans = queryu(@_); + my $ans = queryu(@_); if ( $ans =~ /^Y/ ) { return 1 } elsif ( $ans =~ /^N/ ) { return 0 } else {