From e1c33f04d1eb50d14b1f9929334650a09869d086 Mon Sep 17 00:00:00 2001
From: Akim Demaille <akim.demaille@gmail.com>
Date: Sat, 8 Sep 2018 12:10:06 +0200
Subject: [PATCH] build: work around warnings in Flex

See ea0db44fedc8d5cbdc5c3180bef0285d7ae83803.  We also need to disable
the warning in the examples (but don't want to clutter the
documentation with such details).

* doc/bison.texi (scanner.ll): Disable Clang's -Wdocumentation.
While at it, hide the other kludges.
---
 doc/bison.texi  | 42 ++++++++++++++++++++++++++++++------------
 examples/extexi | 12 ++++++++++++
 2 files changed, 42 insertions(+), 12 deletions(-)

diff --git a/doc/bison.texi b/doc/bison.texi
index 55e2b46f..68b55b23 100644
--- a/doc/bison.texi
+++ b/doc/bison.texi
@@ -11405,8 +11405,8 @@ yy::parser::error (const location_type& l, const std::string& m)
 @node Calc++ Scanner
 @subsubsection Calc++ Scanner
 
-The Flex scanner first includes the driver declaration, then the
-parser's to get the set of defined tokens.
+In addition to standard headers, the Flex scanner includes the driver's,
+then the parser's to get the set of defined tokens.
 
 @comment file: calc++/scanner.ll
 @example
@@ -11417,7 +11417,13 @@ parser's to get the set of defined tokens.
 # include <string>
 # include "driver.hh"
 # include "parser.hh"
+%@}
+@end example
 
+@ignore
+@comment file: calc++/scanner.ll
+@example
+%@{
 // Work around an incompatibility in flex (at least versions
 // 2.5.31 through 2.5.33): it generates code that does
 // not conform to C89.  See Debian bug 333231
@@ -11430,14 +11436,27 @@ parser's to get the set of defined tokens.
 #if defined __GNUC__ && !defined __clang__ && 6 <= __GNUC__
 # pragma GCC diagnostic ignored "-Wnull-dereference"
 #endif
+
+// Old versions of Flex (2.5.35) generate an incomplete documentation comment.
+//
+//  In file included from src/scan-code-c.c:3:
+//  src/scan-code.c:2198:21: error: empty paragraph passed to '@param' command
+//        [-Werror,-Wdocumentation]
+//   * @param line_number
+//     ~~~~~~~~~~~~~~~~~^
+//  1 error generated.
+#if YY_FLEX_MAJOR_VERSION * 1000 + YY_FLEX_MINOR_VERSION <= 2006 && defined __clang__
+# pragma clang diagnostic ignored "-Wdocumentation"
+#endif
 %@}
 @end example
+@end ignore
 
 @noindent
 Because there is no @code{#include}-like feature we don't need
-@code{yywrap}, we don't need @code{unput} either, and we parse an
-actual file, this is not an interactive session with the user.
-Finally, we enable scanner tracing.
+@code{yywrap}, we don't need @code{unput} either, and we parse an actual
+file, this is not an interactive session with the user.  Finally, we enable
+scanner tracing.
 
 @comment file: calc++/scanner.ll
 @example
@@ -11455,13 +11474,12 @@ blank [ \t]
 @end example
 
 @noindent
-The following paragraph suffices to track locations accurately.  Each
-time @code{yylex} is invoked, the begin position is moved onto the end
-position.  Then when a pattern is matched, its width is added to the end
-column.  When matching ends of lines, the end
-cursor is adjusted, and each time blanks are matched, the begin cursor
-is moved onto the end cursor to effectively ignore the blanks
-preceding tokens.  Comments would be treated equally.
+The following paragraph suffices to track locations accurately.  Each time
+@code{yylex} is invoked, the begin position is moved onto the end position.
+Then when a pattern is matched, its width is added to the end column.  When
+matching ends of lines, the end cursor is adjusted, and each time blanks are
+matched, the begin cursor is moved onto the end cursor to effectively ignore
+the blanks preceding tokens.  Comments would be treated equally.
 
 @comment file: calc++/scanner.ll
 @example
diff --git a/examples/extexi b/examples/extexi
index 80d7dd5d..a2b31946 100755
--- a/examples/extexi
+++ b/examples/extexi
@@ -32,6 +32,18 @@
 # output before block 2, even if the latter appears before).  The same
 # number may be used several time, in which case the order of
 # appearance is used.
+#
+# Use @ignore for code to extract that must not be part of the
+# documentation.  For instance:
+#
+#      @ignore
+#      @comment file: calc++/scanner.ll
+#      @example
+#      // Work around an incompatibility in Flex.
+#      # undef yywrap
+#      # define yywrap() 1
+#      @end example
+#      @end ignore
 
 use strict;