build: work around warnings in Flex

[Akim Demaille]

I think I’m done with the problems with Flex now.

commit e1c33f04d1eb50d14b1f9929334650a09869d086
Author: Akim Demaille <address@hidden>
Date:   Sat Sep 8 12:10:06 2018 +0200

    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.

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"
address@hidden
address@hidden example
 
address@hidden
address@hidden file: calc++/scanner.ll
address@hidden
address@hidden
 // 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
 address@hidden
 @end example
address@hidden ignore
 
 @noindent
 Because there is no @code{#include}-like feature we don't need
address@hidden, 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.
address@hidden, 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
address@hidden 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;