[libvirt] [PATCH 11/11] maint: enforce comma style usage

[Eric Blake]

Enforce and document the style set up by the previous patches.

* build-aux/bracket-spacing.pl: Add comma checks.
* docs/hacking.html.in: Document the rules.
* HACKING: Regenerate.

Signed-off-by: Eric Blake <eblake at redhat.com>
---
 HACKING                      | 25 +++++++++++++++++++++++++
 build-aux/bracket-spacing.pl | 15 +++++++++++----
 docs/hacking.html.in         | 31 +++++++++++++++++++++++++++++++
 3 files changed, 67 insertions(+), 4 deletions(-)

diff --git a/HACKING b/HACKING
index f8797cc..357a4bd 100644
--- a/HACKING
+++ b/HACKING
@@ -325,6 +325,31 @@ immediately prior to any closing bracket. E.g.
       int foo(int wizz);    // Good


+Commas
+======
+Commas should always be followed by a space or end of line, and never have
+leading space; this is enforced during 'make check'.
+
+      call(a,b ,c);// Bad
+      call(a, b, c); // Good
+
+When declaring an enum or using a struct initializer that occupies more than
+one line, use a trailing comma. That way, future edits to extend the list only
+have to add a line, rather than modify an existing line to add the
+intermediate comma. However, this is harder to enforce, so you will find
+counterexamples in existing code. Additionally, any sentinel enumerator value
+with a name ending in _LAST is exempt.
+
+      enum {
+          VALUE_ONE,
+          VALUE_TWO // Bad
+      };
+      enum {
+          VALUE_THREE,
+          VALUE_FOUR, // Good
+      };
+
+
 Semicolons
 ==========
 Semicolons should never have a space beforehand. Inside the condition of a
diff --git a/build-aux/bracket-spacing.pl b/build-aux/bracket-spacing.pl
index 4c19968..802a640 100755
--- a/build-aux/bracket-spacing.pl
+++ b/build-aux/bracket-spacing.pl
@@ -32,8 +32,8 @@ foreach my $file (@ARGV) {
     while (defined (my $line = <FILE>)) {
         my $data = $line;

-        # Kill any quoted ; or "
-        $data =~ s,'[";]','X',g;
+        # Kill any quoted , ; or "
+        $data =~ s/'[";,]'/'X'/g;

         # Kill any quoted strings
         $data =~ s,"([^\\\"]|\\.)*","XXX",g;
@@ -114,7 +114,7 @@ foreach my $file (@ARGV) {
             last;
         }

-        # Forbid whitespace before ";". Things like below are allowed:
+        # Forbid whitespace before ";" or ",". Things like below are allowed:
         #
         # 1) The expression is empty for "for" loop. E.g.
         #   for (i = 0; ; i++)
@@ -124,7 +124,7 @@ foreach my $file (@ARGV) {
         #          errno == EINTR)
         #       ;
         #
-        while ($data =~ /[^;\s]\s+;/) {
+        while ($data =~ /[^;\s]\s+[;,]/) {
             print "$file:$.: $line";
             $ret = 1;
             last;
@@ -137,6 +137,13 @@ foreach my $file (@ARGV) {
             $ret = 1;
             last;
         }
+
+        # Require EOL, space, or enum/struct end after comma.
+        while ($data =~ /,[^ \\\n)}]/) {
+            print "$file:$.: $line";
+            $ret = 1;
+            last;
+        }
     }
     close FILE;
 }
diff --git a/docs/hacking.html.in b/docs/hacking.html.in
index 7f31abf..cc76997 100644
--- a/docs/hacking.html.in
+++ b/docs/hacking.html.in
@@ -402,6 +402,37 @@
       int foo(int wizz);    // Good
 </pre>

+    <h2><a name="comma">Commas</a></h2>
+
+    <p>
+      Commas should always be followed by a space or end of line, and
+      never have leading space; this is enforced during 'make check'.
+    </p>
+    <pre>
+      call(a,b ,c);// Bad
+      call(a, b, c); // Good
+</pre>
+
+    <p>
+      When declaring an enum or using a struct initializer that
+      occupies more than one line, use a trailing comma.  That way,
+      future edits to extend the list only have to add a line, rather
+      than modify an existing line to add the intermediate comma.
+      However, this is harder to enforce, so you will find
+      counterexamples in existing code.  Additionally, any sentinel
+      enumerator value with a name ending in _LAST is exempt.
+    </p>
+    <pre>
+      enum {
+          VALUE_ONE,
+          VALUE_TWO // Bad
+      };
+      enum {
+          VALUE_THREE,
+          VALUE_FOUR, // Good
+      };
+</pre>
+
     <h2><a name="semicolon">Semicolons</a></h2>

     <p>
-- 
1.8.3.1