[PATCH 4/4] parse.stats: documentation

[Akim Demaille]

* doc/bison.texi (%define Summary): Document parse.stats.
---
 NEWS           |  9 +++++++++
 doc/bison.texi | 43 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 52 insertions(+)

diff --git a/NEWS b/NEWS
index df884905..da9cfeac 100644
--- a/NEWS
+++ b/NEWS
@@ -11,6 +11,15 @@ GNU Bison NEWS
   The Java backend no longer emits code and data for parser tracing if the
   %define variable parse.trace is not defined.
 
+*** Summary of a parser run (yacc.c)
+
+  As an experimental feature, if you specify
+
+    %define parse.stats
+
+  and set yydebug to yydebug_stats, then at the end of the parse, the number
+  of reductions and shifts is printed in the debug stream.
+
 * Noteworthy changes in release 3.4.1 (2019-05-22) [stable]
 
 ** Bug fixes
diff --git a/doc/bison.texi b/doc/bison.texi
index 73c29f65..423ddabd 100644
--- a/doc/bison.texi
+++ b/doc/bison.texi
@@ -6516,6 +6516,49 @@ syntax error handling.  @xref{LAC}.
 @c parse.lac
 
 
+@c ================================================== parse.stats
+@deffn Directive {%define parse.stats} (experimental)
+
+@itemize
+@item Languages(s): C
+
+@item Purpose: Require parser instrumentation for parsing summary.
+@xref{Tracing, ,Tracing Your Parser}.
+
+Provide a means, at the end of the parsing, to print facts about the parsing
+itself: number of shifts and number of reductions.  This is enabled only
+when the @code{%define} variable @code{parse.trace} is set.
+
+Then @code{yydebug} is interpreted via bit masks:
+@table @code
+@item yydebug_none
+Disable all traces.  Equal to 0.
+
+@item yydebug_trace
+Enable parse traces.
+
+@item yydebug_stats
+At the end of the parse, print a count of the parser actions.
+
+@item yydebug_none
+Enable all traces.  Equal to -1.
+@end table
+
+All these identifiers follow @code{api.prefix}.  For instance to enable
+traces and summary when @samp{%define api.prefix @{calc_@}} is specified,
+use @samp{calc_debug = calc_debug_trace | calc_debug_stats}.
+
+@item Accepted Values: Boolean
+
+@item Default Value: @code{false}
+@item History:
+introduced in Bison 3.4 as an experimental feature.
+@end itemize
+@end deffn
+@c parse.stats
+
+
+
 @c ================================================== parse.trace
 @deffn Directive {%define parse.trace}
 
-- 
2.22.0