From 882fe74222b6f8c06cab1b1937419bfbb8cda23e Mon Sep 17 00:00:00 2001
From: Akim Demaille <akim.demaille@gmail.com>
Date: Sat, 6 Apr 2019 09:59:49 +0200
Subject: [PATCH] doc: document -Wstyle

* doc/bison.texi, src/getargs.c, NEWS: here.
---
 NEWS           | 25 +++++++++++++++++++++++++
 doc/bison.texi | 36 ++++++++++++++++++++++++++++++++++++
 src/getargs.c  |  1 +
 3 files changed, 62 insertions(+)

diff --git a/NEWS b/NEWS
index 8a423fdf8..29bf557b3 100644
--- a/NEWS
+++ b/NEWS
@@ -43,6 +43,31 @@ GNU Bison NEWS
   When given -fsyntax-only, the diagnostics are reported, but no output is
   generated.
 
+*** Diagnostics for stylistic issues: -Wstyle
+
+  A new warning category is introduced: 'style'.  Currently it reports
+  useless explicit actions.  For instance on the following grammar:
+
+    %type <int> "number" expr term
+    %%
+    expr: expr "+" term { $$ = $1 + $3; }
+        | term          { $$ = $1; }
+    term: "(" expr ")"  { $$ = $2; }
+        | "number"      { $$ = $1; }
+
+  bison diagnoses:
+
+    $ bison -Wstyle foo.y
+    foo.y:4.21-32: warning: useless explicit action [-Wstyle]
+         | term          { $$ = $1; }
+                         ^~~~~~~~~~~~
+    foo.y:6.21-32: warning: useless explicit action [-Wstyle]
+         | "number"      { $$ = $1; }
+                         ^~~~~~~~~~~~
+    foo.y: warning: fix-its can be applied.  Rerun with option '--update'. [-Wother]
+
+  Running 'bison -Wstyle --update foo.y' would remove these actions.
+
 *** Include the generated header (yacc.c)
 
   Before, when --defines is used, bison generated a header, and pasted an
diff --git a/doc/bison.texi b/doc/bison.texi
index 45bd4ccd0..4888d38e9 100644
--- a/doc/bison.texi
+++ b/doc/bison.texi
@@ -10448,6 +10448,42 @@ One would get the exact same parser with the following directives instead:
 @end group
 @end example
 
+@item style
+Stylistic issues, i.e., valid input that should be written in a different
+way.  Useless explicit actions (@samp{@{ $$ = $1; @}}) are reported.  For
+instance on the following grammar:
+
+@example
+@group
+$ @kbd{cat foo.y}
+%type <int> "number" expr term
+%%
+expr: expr "+" term @{ $$ = $1 + $3; @}
+    | term          @{ $$ = $1; @}
+term: "(" expr ")"  @{ $$ = $2; @}
+    | "number"      @{ $$ = $1; @}
+@end group
+@end example
+
+@noindent
+@command{bison} diagnoses:
+
+@example
+$ @kbd{bison -Wstyle foo.y}
+foo.y:4.21-32: warning: useless explicit action [-Wstyle]
+     | term          @{ $$ = $1; @}
+                     ^~~~~~~~~~~~
+foo.y:6.21-32: warning: useless explicit action [-Wstyle]
+     | "number"      @{ $$ = $1; @}
+                     ^~~~~~~~~~~~
+foo.y: warning: fix-its can be applied.  Rerun with option '--update'. [-Wother]
+@end example
+
+Running @kbd{bison -Wstyle --update foo.y} would remove these actions.
+
+Actions with named references (e.g., @samp{@{ $expr = $term; @}}) are not
+reported.  To disable the warning locally, write @samp{@{ $$ = ($1); @}}.
+
 @item yacc
 Incompatibilities with POSIX Yacc.
 
diff --git a/src/getargs.c b/src/getargs.c
index 161ae40f5..2579ded0a 100644
--- a/src/getargs.c
+++ b/src/getargs.c
@@ -339,6 +339,7 @@ Warning categories include:\n\
   'empty-rule'        empty rules without %empty\n\
   'midrule-values'    unset or unused midrule values\n\
   'precedence'        useless precedence and associativity\n\
+  'style'             stylistic issues\n\
   'yacc'              incompatibilities with POSIX Yacc\n\
   'other'             all other warnings (enabled by default)\n\
   'all'               all the warnings except 'yacc'\n\