doc: clean up the C++ section

[Akim Demaille]

It is well known that this section needs love.  I’m sure it would
appreciate spontaneous contributions…


commit 2d079403257dee8a90be0a2bed03cde0063c7209
Author: Akim Demaille <address@hidden>
Date:   Wed Sep 26 06:36:11 2018 +0200

    doc: clean up the C++ section
    
    * doc/bison.texi: Minor fixes in typography.
    It is no longer require to pass --defines for C++ (it was addressed
    long ago).
    No longer refer to the `variant` define variable, it was replaced by
    `api.value.type variant`.
    Prefer nullptr to 0 for the null pointer.
    Use deftypeop for constructors.
    (Complete Symbols): Give the expected signature of yylex.
    Don't document the symbol_type constructors, as we want users to focus
    on make_TOKEN.
    Also show the case without locations.

diff --git a/doc/bison.texi b/doc/bison.texi
index e0364b7e..e2baf0ff 100644
--- a/doc/bison.texi
+++ b/doc/bison.texi
@@ -5727,7 +5727,7 @@ delimiters) denote finite choice (e.g., a variation of a 
feature).  String
 values denote remaining cases (e.g., a file name).
 
 It is an error if a @var{variable} is defined by @code{%define} multiple
-times, but see @ref{Bison Options,,-D @address@hidden
+times, but see @ref{Bison Options,,@option{-D @address@hidden
 @end deffn
 
 The rest of this section summarizes variables and values that
@@ -10572,17 +10572,13 @@ An auxiliary class @code{stack} used by the parser.
 @item @var{file}.hh
 @itemx @var{file}.cc
 (Assuming the extension of the grammar file was @samp{.yy}.)  The
-declaration and implementation of the C++ parser class.  The basename
-and extension of these two files follow the same rules as with regular C
-parsers (@pxref{Invocation}).
-
-The header is @emph{mandatory}; you must either pass
address@hidden/@option{--defines} to @command{bison}, or use the
address@hidden directive.
+declaration and implementation of the C++ parser class.  The basename and
+extension of these two files follow the same rules as with regular C parsers
+(@pxref{Invocation}).
 @end table
 
-All these files are documented using Doxygen; run @command{doxygen}
-for a complete and accurate documentation.
+All these files are documented using Doxygen; run @command{doxygen} for a
+complete and accurate documentation.
 
 @node C++ Semantic Values
 @subsection C++ Semantic Values
@@ -10629,10 +10625,11 @@ Bison provides a @emph{variant} based implementation 
of semantic values for
 C++.  This alleviates all the limitations reported in the previous section,
 and in particular, object types can be used without pointers.
 
-To enable variant-based semantic values, set @code{%define} variable
address@hidden (@pxref{%define Summary,, variant}).  Once this defined,
address@hidden is ignored, and instead of using the name of the fields of the
address@hidden to ``type'' the symbols, use genuine types.
+To enable variant-based semantic values, set the @code{%define} variable
address@hidden to @code{variant} (@pxref{%define Summary,,
address@hidden).  Then @code{%union} is ignored; instead of using
+the name of the fields of the @code{%union} to ``type'' the symbols, use
+genuine types.
 
 For instance, instead of:
 
@@ -10737,21 +10734,21 @@ classes will not be generated, and the user defined 
type will be used.
 @node C++ position
 @subsubsection C++ @code{position}
 
address@hidden {Constructor} {position} {} position (std::string* @var{file} = 
0, unsigned @var{line} = 1, unsigned @var{col} = 1)
address@hidden {Constructor} {position} {} position (std::string* @var{file} = 
nullptr, unsigned @var{line} = 1, unsigned @var{col} = 1)
 Create a @code{position} denoting a given point.  Note that @code{file} is
 not reclaimed when the @code{position} is destroyed: memory managed must be
 handled elsewhere.
 @end deftypeop
 
address@hidden {position} {void} initialize (std::string* @var{file} = 0, 
unsigned @var{line} = 1, unsigned @var{col} = 1)
address@hidden {position} {void} initialize (std::string* @var{file} = nullptr, 
unsigned @var{line} = 1, unsigned @var{col} = 1)
 Reset the position to the given values.
 @end deftypemethod
 
 @deftypeivar {position} {std::string*} file
-The name of the file.  It will always be handled as a pointer, the
-parser will never duplicate nor deallocate it.  As an experimental
-feature you may change it to @address@hidden using @samp{%define
-filename_type "@var{type}"}.
+The name of the file.  It will always be handled as a pointer, the parser
+will never duplicate nor deallocate it.  As an experimental feature you may
+change it to @address@hidden using @samp{%define filename_type
+"@var{type}"}.
 @end deftypeivar
 
 @deftypeivar {position} {unsigned} line
@@ -10802,7 +10799,7 @@ Create a @code{Location} from the endpoints of the 
range.
 Create a @code{Location} denoting an empty range located at a given point.
 @end deftypeop
 
address@hidden {location} {void} initialize (std::string* @var{file} = 0, 
unsigned @var{line} = 1, unsigned @var{col} = 1)
address@hidden {location} {void} initialize (std::string* @var{file} = nullptr, 
unsigned @var{line} = 1, unsigned @var{col} = 1)
 Reset the location to an empty range at the given values.
 @end deftypemethod
 
@@ -10940,15 +10937,16 @@ invoked from user actions (i.e., written in the 
action itself), the
 exception can be thrown from function invoked from the user action.
 @end defcv
 
address@hidden {parser} {} parser (@var{type1} @var{arg1}, ...)
-Build a new parser object.  There are no arguments by default, unless
address@hidden {Constructor} {parser} {} parser ()
address@hidden {Constructor} {parser} {} parser (@var{type1} @var{arg1}, ...)
+Build a new parser object.  There are no arguments, unless
 @samp{%parse-param @address@hidden @address@hidden was used.
address@hidden deftypemethod
address@hidden deftypeop
 
address@hidden {syntax_error} {} syntax_error (const location_type& @var{l}, 
const std::string& @var{m})
address@hidden {syntax_error} {} syntax_error (const std::string& @var{m})
address@hidden {Constructor} {syntax_error} {} syntax_error (const 
location_type& @var{l}, const std::string& @var{m})
address@hidden {Constructor}  {syntax_error} {} syntax_error (const 
std::string& @var{m})
 Instantiate a syntax-error exception.
address@hidden deftypemethod
address@hidden deftypeop
 
 @deftypemethod {parser} {int} parse ()
 Run the syntactic analysis, and return 0 on success, 1 otherwise.
@@ -10977,10 +10975,9 @@ or nonzero, full tracing.
 
 @deftypemethod {parser} {void} error (const location_type& @var{l}, const 
std::string& @var{m})
 @deftypemethodx {parser} {void} error (const std::string& @var{m})
-The definition for this member function must be supplied by the user:
-the parser uses it to report a parser error occurring at @var{l},
-described by @var{m}.  If location tracking is not enabled, the second
-signature is used.
+The definition for this member function must be supplied by the user: the
+parser uses it to report a parser error occurring at @var{l}, described by
address@hidden  If location tracking is not abled, the second signature is used.
 @end deftypemethod
 
 
@@ -11003,14 +11000,14 @@ depends whether you use unions, or variants.
 @node Split Symbols
 @subsubsection Split Symbols
 
-The interface is as follows.
+The generated parser expects @code{yylex} to have the following prototype.
 
address@hidden {parser} {int} yylex (semantic_type* @var{yylval}, 
location_type* @var{yylloc}, @var{type1} @var{arg1}, ...)
address@hidden {parser} {int} yylex (semantic_type* @var{yylval}, @var{type1} 
@var{arg1}, ...)
address@hidden {int} yylex (semantic_type* @var{yylval}, location_type* 
@var{yylloc}, @var{type1} @var{arg1}, ...)
address@hidden {int} yylex (semantic_type* @var{yylval}, @var{type1} 
@var{arg1}, ...)
 Return the next token.  Its type is the return value, its semantic value and
 location (if enabled) being @var{yylval} and @var{yylloc}.  Invocations of
 @samp{%lex-param @address@hidden @address@hidden yield additional arguments.
address@hidden deftypemethod
address@hidden deftypefun
 
 Note that when using variants, the interface for @code{yylex} is the same,
 but @code{yylval} is handled differently.
@@ -11060,32 +11057,28 @@ or
 @node Complete Symbols
 @subsubsection Complete Symbols
 
-If you specified both @code{%define api.value.type variant} and
address@hidden api.token.constructor},
-the @code{parser} class also defines the class @code{parser::symbol_type}
-which defines a @emph{complete} symbol, aggregating its type (i.e., the
-traditional value returned by @code{yylex}), its semantic value (i.e., the
-value passed in @code{yylval}, and possibly its location (@code{yylloc}).
-
address@hidden {symbol_type} {} symbol_type (token_type @var{type},  const 
semantic_type& @var{value}, const location_type& @var{location})
-Build a complete terminal symbol which token type is @var{type}, and which
-semantic value is @var{value}.  If location tracking is enabled, also pass
-the @var{location}.
address@hidden deftypemethod
+With both @code{%define api.value.type variant} and @code{%define
+api.token.constructor}, the parser defines the type @code{symbol_type}, and
+expects @code{yylex} to have the following prototype.
 
-This interface is low-level and should not be used for two reasons.  First,
-it is inconvenient, as you still have to build the semantic value, which is
-a variant, and second, because consistency is not enforced: as with unions,
-it is still possible to give an integer as semantic value for a string.
address@hidden {parser::symbol_type} yylex ()
address@hidden {parser::symbol_type} yylex (var{type1} @var{arg1}, ...)
+Return a @emph{complete} symbol, aggregating its type (i.e., the traditional
+value returned by @code{yylex}), its semantic value, and possibly its
+location.  Invocations of @samp{%lex-param @address@hidden @address@hidden 
yield
+additional arguments.
address@hidden deftypefun
 
-So for each token type, Bison generates named constructors as follows.
+For each token type, Bison generates named constructors as follows.
 
address@hidden {symbol_type} {} address@hidden (const @var{value_type}& 
@var{value}, const location_type& @var{location})
address@hidden {symbol_type} {} address@hidden (const location_type& 
@var{location})
address@hidden {parser} {symbol_type} address@hidden (const @var{value_type}& 
@var{value}, const location_type& @var{location})
address@hidden {parser} {symbol_type} address@hidden (const location_type& 
@var{location})
address@hidden {parser} {symbol_type} address@hidden (const @var{value_type}& 
@var{value})
address@hidden {parser} {symbol_type} address@hidden ()
 Build a complete terminal symbol for the token type @var{token} (not
-including the @code{api.token.prefix}) whose possible semantic value is
address@hidden of adequate @var{value_type}.  If location tracking is enabled,
-also pass the @var{location}.
+including the @code{api.token.prefix}), whose semantic value, if it has one,
+is @var{value} of adequate @var{value_type}.  Pass the @var{location} iff
+location tracking is enabled.
 @end deftypemethod
 
 For instance, given the following declarations:
@@ -11098,7 +11091,7 @@ For instance, given the following declarations:
 @end example
 
 @noindent
-Bison generates the following functions:
+Bison generates:
 
 @example
 symbol_type make_IDENTIFIER (const std::string&, const location_type&);
@@ -11118,6 +11111,7 @@ which should be used in a Lex-scanner as follows.
 Tokens that do not have an identifier are not accessible: you cannot simply
 use characters such as @code{':'}, they must be declared with @code{%token}.
 
+
 @node A Complete C++ Example
 @subsection A Complete C++ Example