[Qemu-devel] [PATCH v2] scripts: add script to convert multiline comments into 4-line format

[Qemu-devel] [PATCH v2] scripts: add script to convert multiline comments into 4-line format

[Paolo Bonzini]

Since we're adding checkpatch rules to enforce 4-line multiline comment
format, i.e. with lone /* and */, this script can be run on existing
code so that the comment style does not become inconsistent within a
file.

The alternative to awk-in-a-shell-script could be Perl, which also
supports -i directly, but a2p seems to have bitrotten and I didn't quite
feel like writing this twice...

Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
---
        v1->v2: fix handling of multiline doc comments without lone /**
---
 scripts/fix-multiline-comments.sh | 62 +++++++++++++++++++++++++++++++
 1 file changed, 62 insertions(+)
 create mode 100755 scripts/fix-multiline-comments.sh

diff --git a/scripts/fix-multiline-comments.sh b/scripts/fix-multiline-comments.sh
new file mode 100755
index 0000000000..93f9b10669
--- /dev/null
+++ b/scripts/fix-multiline-comments.sh
@@ -0,0 +1,62 @@
+#! /bin/sh
+#
+# Fix multiline comments to match CODING_STYLE
+#
+# Copyright (C) 2018 Red Hat, Inc.
+#
+# Author: Paolo Bonzini
+#
+# Usage: scripts/fix-multiline-comments.sh [-i] FILE...
+#
+# -i edits the file in place (requires gawk 4.1.0).
+#
+# Set the AWK environment variable to choose the awk interpreter to use
+# (default 'awk')
+
+if test "$1" = -i; then
+  # gawk extension
+  inplace="-i inplace"
+  shift
+fi
+${AWK-awk} $inplace 'BEGIN { indent = -1 }
+{
+    line = $0
+    # apply a star to the indent on lines after the first
+    if (indent != -1) {
+        if (line == "") {
+            line = sp " *"
+        } else if (substr(line, 1, indent + 2) == sp "  ") {
+            line = sp " *" substr(line, indent + 3)
+        }
+    }
+
+    is_lead = (line ~ /^[ \t]*\/\*/)
+    is_trail = (line ~ /\*\//)
+    if (is_lead && !is_trail) {
+        # grab the indent at the start of a comment, but not for
+        # single-line comments
+        match(line, /^[ \t]*\/\*/)
+        indent = RLENGTH - 2
+        sp = substr(line, 1, indent)
+    }
+
+    # the regular expression filters out lone /*, /**, or */
+    if (indent != -1 && !(line ~ /^[ \t]*(\/\*+|\*\/)[ \t]*$/)) {
+        if (is_lead) {
+            # split the leading /* or /** on a separate line
+            match(line, /^[ \t]*\/\*+/)
+            lead = substr(line, 1, RLENGTH)
+            match(line, /^[ \t]*\/\*+[ \t]*/)
+            line = lead "\n" sp " *" substr(line, RLENGTH)
+        }
+        if (is_trail) {
+            # split the trailing */ on a separate line
+            match(line, /[ \t]*\*\//)
+            line = substr(line, 1, RSTART - 1) "\n" sp " */"
+        }
+    }
+    if (is_trail) {
+        indent = -1
+    }
+    print line
+}' "$@"
-- 
2.19.2

Re: [Qemu-devel] [PATCH v2] scripts: add script to convert multiline comments into 4-line format

[Wainer dos Santos Moschetta]

On 12/14/2018 07:48 AM, Paolo Bonzini wrote:
> Since we're adding checkpatch rules to enforce 4-line multiline comment
> format, i.e. with lone /* and */, this script can be run on existing
> code so that the comment style does not become inconsistent within a
> file.
>
> The alternative to awk-in-a-shell-script could be Perl, which also
> supports -i directly, but a2p seems to have bitrotten and I didn't quite
> feel like writing this twice...
>
> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
> ---
>          v1->v2: fix handling of multiline doc comments without lone /**
> ---
>   scripts/fix-multiline-comments.sh | 62 +++++++++++++++++++++++++++++++
>   1 file changed, 62 insertions(+)
>   create mode 100755 scripts/fix-multiline-comments.sh
>
> diff --git a/scripts/fix-multiline-comments.sh b/scripts/fix-multiline-comments.sh
> new file mode 100755
> index 0000000000..93f9b10669
> --- /dev/null
> +++ b/scripts/fix-multiline-comments.sh
> @@ -0,0 +1,62 @@
> +#! /bin/sh
> +#
> +# Fix multiline comments to match CODING_STYLE
> +#
> +# Copyright (C) 2018 Red Hat, Inc.
> +#
> +# Author: Paolo Bonzini
> +#
> +# Usage: scripts/fix-multiline-comments.sh [-i] FILE...
> +#
> +# -i edits the file in place (requires gawk 4.1.0).
> +#
> +# Set the AWK environment variable to choose the awk interpreter to use
> +# (default 'awk')
> +
> +if test "$1" = -i; then
> +  # gawk extension
> +  inplace="-i inplace"
> +  shift
> +fi
> +${AWK-awk} $inplace 'BEGIN { indent = -1 }
> +{
> +    line = $0
> +    # apply a star to the indent on lines after the first
> +    if (indent != -1) {
> +        if (line == "") {
> +            line = sp " *"
> +        } else if (substr(line, 1, indent + 2) == sp "  ") {
> +            line = sp " *" substr(line, indent + 3)
> +        }
> +    }

IIUC above block handles the lines between lead and trail. So it would 
fix (but it doesn't) this:

# cat foo
/*
  comment 1
  comment 2
  */

# scripts/fix-multiline-comments.sh foo
/*
  comment 1
  comment 2
  */

- Wainer

> +
> +    is_lead = (line ~ /^[ \t]*\/\*/)
> +    is_trail = (line ~ /\*\//)
> +    if (is_lead && !is_trail) {
> +        # grab the indent at the start of a comment, but not for
> +        # single-line comments
> +        match(line, /^[ \t]*\/\*/)
> +        indent = RLENGTH - 2
> +        sp = substr(line, 1, indent)
> +    }
> +
> +    # the regular expression filters out lone /*, /**, or */
> +    if (indent != -1 && !(line ~ /^[ \t]*(\/\*+|\*\/)[ \t]*$/)) {
> +        if (is_lead) {
> +            # split the leading /* or /** on a separate line
> +            match(line, /^[ \t]*\/\*+/)
> +            lead = substr(line, 1, RLENGTH)
> +            match(line, /^[ \t]*\/\*+[ \t]*/)
> +            line = lead "\n" sp " *" substr(line, RLENGTH)
> +        }
> +        if (is_trail) {
> +            # split the trailing */ on a separate line
> +            match(line, /[ \t]*\*\//)
> +            line = substr(line, 1, RSTART - 1) "\n" sp " */"
> +        }
> +    }
> +    if (is_trail) {
> +        indent = -1
> +    }
> +    print line
> +}' "$@"

Re: [Qemu-devel] [PATCH v2] scripts: add script to convert multiline comments into 4-line format

[Paolo Bonzini]

On 14/12/18 19:06, Wainer dos Santos Moschetta wrote:
> 
> IIUC above block handles the lines between lead and trail. So it would
> fix (but it doesn't) this:
> 
> # cat foo
> /*
>  comment 1
>  comment 2
>  */
> 
> # scripts/fix-multiline-comments.sh foo
> /*
>  comment 1
>  comment 2
>  */

Not enough spaces :)  It would fix

 /*
    comment 1
    comment 2
  */

or what is actually found in QEMU:

   /* comment 1
      comment 2 */

Thanks,

Paolo

Re: [Qemu-devel] [PATCH v2] scripts: add script to convert multiline comments into 4-line format

[Wainer dos Santos Moschetta]

On 12/14/2018 04:15 PM, Paolo Bonzini wrote:
> On 14/12/18 19:06, Wainer dos Santos Moschetta wrote:
>> IIUC above block handles the lines between lead and trail. So it would
>> fix (but it doesn't) this:
>>
>> # cat foo
>> /*
>>   comment 1
>>   comment 2
>>   */
>>
>> # scripts/fix-multiline-comments.sh foo
>> /*
>>   comment 1
>>   comment 2
>>   */
> Not enough spaces :)  It would fix
>
>   /*
>      comment 1
>      comment 2
>    */
>
> or what is actually found in QEMU:
>
>     /* comment 1
>        comment 2 */

I tried hard but I failed to find problems. :)

Thus,

Reviewed-by: Wainer dos Santos Moschetta <wainersm@redhat.com>


>
> Thanks,
>
> Paolo