maint: enforce comma style usage

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@redhat.com>

HACKING

@@ -325,6 +325,35 @@ 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 syntax-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. Any sentinel enumerator value with a name ending in _LAST
+is exempt, since you would extend such an enum before the _LAST element.
+Another reason to favor trailing commas is that it requires less effort to
+produce via code generators. Note that the syntax checker is unable to enforce
+a style of trailing commas, so there are counterexamples in existing code
+which do not use it; also, while C99 allows trailing commas, remember that
+JSON and XDR do not.
+
+      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

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;
 }

docs/hacking.html.in

@@ -402,6 +402,43 @@
       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
+      syntax-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.  Any
+      sentinel enumerator value with a name ending in _LAST is exempt,
+      since you would extend such an enum before the _LAST element.
+      Another reason to favor trailing commas is that it requires less
+      effort to produce via code generators.  Note that the syntax
+      checker is unable to enforce a style of trailing commas, so
+      there are counterexamples in existing code which do not use it;
+      also, while C99 allows trailing commas, remember that JSON and
+      XDR do not.
+    </p>
+    <pre>
+      enum {
+          VALUE_ONE,
+          VALUE_TWO // Bad
+      };
+      enum {
+          VALUE_THREE,
+          VALUE_FOUR, // Good
+      };
+</pre>
+
     <h2><a name="semicolon">Semicolons</a></h2>
 
     <p>