pgindent: improve formatting of multiline comments.

Enforce this standard formatting of multiline comments that start
in column 1:

/*
 * line 1
 * line 2
 */

Unlike indented comments, we don't reconsider line breaks, except
for forcing the initial /* and trailing */ onto their own lines.
We do make each line start with " *", with some whitespace following.

We preserve pgindent's existing behavior of not touching comments
that begin with /**... or /*-...  Also, if the first line looks like
/* === or /* ---, we don't split that line; similarly for the last
line.

The vast majority of multiline comments in our tree already look
like this, but this change will clean up some stragglers.

Author: Aleksander Alekseev <aleksander@tigerdata.com>
Reported-by: Michael Paquier <michael@paquier.xyz>
Reviewed-by: Arseniy Mukhin <arseniy.mukhin.dev@gmail.com>
Reviewed-by: Nathan Bossart <nathandbossart@gmail.com>
Reviewed-by: Tom Lane <tgl@sss.pgh.pa.us>
Discussion: https://postgr.es/m/CAJ7c6TPQ0kkHQG-AqeAJ3PV_YtmDzcc7s%2B_V4%3Dt%2BxgSnZm1cFw%40mail.gmail.com
Discussion: https://postgr.es/m/EB0141C5-ACC2-4F0B-85EA-0E3AFBCE322F@umbc.edu

diff --git a/src/tools/pgindent/pgindent b/src/tools/pgindent/pgindent
index d035b53699bfd8fcd0a625a389f8c15cc0ef95f1..004b8fcab00277840562dc024bf96495ecf6e8eb 100755 (executable)
--- a/src/tools/pgindent/pgindent
+++ b/src/tools/pgindent/pgindent
@@ -285,6 +285,9 @@ sub post_indent
        # Fix run-together comments to have a tab between them
        $source =~ s!\*/(/\*.*\*/)$!*/\t$1!gm;
 
+       # Postprocess multiline comments except for /**... and /*-... ones
+       $source =~ s!^(/\*[^\*\-].*?\*/)!postprocess_multiline_comment($1)!mgse;
+
        ## Functions
 
        # Use a single space before '*' in function return types
@@ -293,6 +296,48 @@ sub post_indent
        return $source;
 }
 
+sub postprocess_multiline_comment
+{
+       my $source = shift;
+       my @lines = split "\n", $source;
+
+       # Only reformat comments that actually span more than one line
+       if (scalar @lines < 2)
+       {
+               return $source;
+       }
+
+       # Split any text on the first line onto a separate line,
+       # but keep /* === and /* --- lines as is
+       if ($lines[0] !~ m!^/\*\s+[=-]+$!)
+       {
+               $lines[0] =~ s!/\*\s*(.+)!/\*\n * $1!;
+       }
+
+       # Apply these steps to all lines but the first
+       for my $i (1 .. scalar @lines - 1)
+       {
+               # Insert ' * ' if first non-white-space character is not '*'
+               $lines[$i] =~ s/^\s*/ \* / if $lines[$i] !~ /^\s*\*/;
+               # ... but that might leave us with trailing space
+               $lines[$i] =~ s/\s+$//;
+               # Require exactly one leading '*', and one space before it
+               $lines[$i] =~ s/^\s*\*+/ \*/;
+       }
+
+       # Split trailing "*/" onto its own line if not that already,
+       # but keep === */ and --- */ lines as is
+       if ($lines[-1] !~ m!^\s*[=-]+\s+\*/$!)
+       {
+               # this also removes any trailing whitespace
+               $lines[-1] =~ s!(.+?)\s+\*/!$1\n \*/!;
+       }
+
+       $source = join "\n", @lines;
+
+       return $source;
+}
+
 sub run_indent
 {
        my $source = shift;