FYI: lalr1.cc: Doxygen, error signature

[Akim Demaille]

Index: ChangeLog
from  Akim Demaille  <address@hidden>

        * data/lalr1.cc: Extensive Doxygenation.
        (error_): Rename as...
        (error): this, since it is visible to the user.
        Adjust callers.
        (Parser::message): Now an automatic variable from...
        (Parser::yyreport_syntax_error_): here.
        * tests/actions.at, tests/calc.at, tests/regression.at: Adjust to
        Parser::error.
        * tests/input.at: Escape $.

Index: NEWS
===================================================================
RCS file: /cvsroot/bison/bison/NEWS,v
retrieving revision 1.107
diff -u -u -r1.107 NEWS
--- NEWS 11 Dec 2004 06:25:56 -0000 1.107
+++ NEWS 17 Dec 2004 15:23:25 -0000
@@ -1,6 +1,8 @@
 Bison News
 ----------
 
+Changes in version 1.875f:
+
 Changes in version 1.875e, 2004-12-10:
 
 * New directive: %initial-action.
Index: data/lalr1.cc
===================================================================
RCS file: /cvsroot/bison/bison/data/lalr1.cc,v
retrieving revision 1.73
diff -u -u -r1.73 lalr1.cc
--- data/lalr1.cc 16 Dec 2004 20:41:54 -0000 1.73
+++ data/lalr1.cc 17 Dec 2004 15:23:25 -0000
@@ -203,6 +203,7 @@
 
 namespace yy
 {
+  /// A Bison parser.
   class ]b4_parser_class_name[
   {
   public:
@@ -217,10 +218,14 @@
     /// Symbol locations.
     typedef Traits<]b4_parser_class_name[>::LocationType    LocationType;
 
+    /// State stack type.
     typedef Stack<StateType>    StateStack;
+    /// Semantic value stack type.
     typedef Stack<SemanticType> SemanticStack;
+    /// Location stack type.
     typedef Stack<LocationType> LocationStack;
 
+    /// Build a parser object.
     ]b4_parser_class_name[ (]b4_parse_param_decl[) :
       yydebug_ (false),
       yycdebug_ (&std::cerr)]b4_parse_param_cons[
@@ -251,9 +256,15 @@
 
     /// Call the scanner.
     virtual void yylex_ ();
-    virtual void error_ ();
-    /// Generate an error message, and invoke error. */
+
+    /// Report a syntax error.
+    /// \param loc    where the syntax error is found.
+    /// \param msg    a description of the syntax error.
+    virtual void error (const LocationType& loc, const std::string& msg);
+
+    /// Generate an error message, and invoke error.
     virtual void yyreport_syntax_error_ ();
+
 #if YYDEBUG
     /// \brief Report a symbol on the debug stream.
     /// \param yytype       The token type.
@@ -273,19 +284,38 @@
     LocationStack yylocation_stack_;
 
     /* Tables.  */
+    /// For a state, the index in \a yytable_ of its portion.
     static const ]b4_int_type_for([b4_pact])[ yypact_[];
     static const ]b4_int_type(b4_pact_ninf, b4_pact_ninf)[ yypact_ninf_;
+
+    /// For a state, default rule to reduce.
+    /// Unless\a  yytable_ specifies something else to do.
+    /// Zero means the default is an error.
     static const ]b4_int_type_for([b4_defact])[ yydefact_[];
+
     static const ]b4_int_type_for([b4_pgoto])[ yypgoto_[];
     static const ]b4_int_type_for([b4_defgoto])[ yydefgoto_[];
+
+    /// What to do in a state.
+    /// \a yytable_[yypact_[s]]: what to do in state \a s.
+    /// - if positive, shift that token.
+    /// - if negative, reduce the rule which number is the opposite.
+    /// - if zero, do what YYDEFACT says.
     static const ]b4_int_type_for([b4_table])[ yytable_[];
     static const ]b4_int_type(b4_table_ninf, b4_table_ninf)[ yytable_ninf_;
+
     static const ]b4_int_type_for([b4_check])[ yycheck_[];
+
+    /// For a state, its accessing symbol.
     static const ]b4_int_type_for([b4_stos])[ yystos_[];
+
+    /// For a rule, its LHS.
     static const ]b4_int_type_for([b4_r1])[ yyr1_[];
+    /// For a rule, its RHS length.
     static const ]b4_int_type_for([b4_r2])[ yyr2_[];
 
 #if YYDEBUG || YYERROR_VERBOSE
+    /// For a symbol, its name in clear.
     static const char* const yyname_[];
 #endif
 
@@ -298,9 +328,9 @@
     static const ]b4_int_type_for([b4_rline])[ yyrline_[];
     /// For each scanner token number, its symbol number.
     static const ]b4_int_type_for([b4_toknum])[ yytoken_number_[];
-    /// Report on the debug stream that the rule \a yyrule is going to be 
reduced.
-    virtual void yyreduce_print_ (int yyrule);
-/// Print the state stack on the debug stream.
+    /// Report on the debug stream that the rule \a r is going to be reduced.
+    virtual void yyreduce_print_ (int r);
+    /// Print the state stack on the debug stream.
     virtual void yystack_print_ ();
 #endif
 
@@ -350,9 +380,6 @@
     int yylooka_;
     int yyilooka_;
 
-    /* Message.  */
-    std::string message;
-
     /// Semantic value of the look-ahead.
     SemanticType value;
     /// Location of the look-ahead.
@@ -805,7 +832,7 @@
   if (!yyerrstatus_)
     {
       ++yynerrs_;
-
+      std::string message;
 #if YYERROR_VERBOSE
       yyn_ = yypact_[yystate_];
       if (yypact_ninf_ < yyn_ && yyn_ < yylast_)
@@ -838,7 +865,7 @@
       else
 #endif
        message = "syntax error";
-      error_ ();
+      error (location, message);
     }
 }
 
Index: tests/actions.at
===================================================================
RCS file: /cvsroot/bison/bison/tests/actions.at,v
retrieving revision 1.45
diff -u -u -r1.45 actions.at
--- tests/actions.at 16 Dec 2004 14:39:42 -0000 1.45
+++ tests/actions.at 17 Dec 2004 15:23:25 -0000
@@ -311,9 +311,9 @@
 ]AT_LALR1_CC_IF(
 [/* A C++ error reporting function. */
 void
-yy::Parser::error_ ()
+yy::Parser::error (const Location& l, const std::string& m)
 {
-  printf ("%d-%d: %s\n", RANGE (location), message.c_str());
+  printf ("%d-%d: %s\n", RANGE (l), m.c_str());
 }
 
 static bool yydebug;
Index: tests/calc.at
===================================================================
RCS file: /cvsroot/bison/bison/tests/calc.at,v
retrieving revision 1.68
diff -u -u -r1.68 calc.at
--- tests/calc.at 15 Dec 2004 16:18:11 -0000 1.68
+++ tests/calc.at 17 Dec 2004 15:23:25 -0000
@@ -128,9 +128,10 @@
 ]AT_LALR1_CC_IF(
 [/* A C++ error reporting function. */
 void
-yy::Parser::error_ ()
+yy::Parser::error (const Location& l, const std::string& m)
 {
-  std::cerr << AT_LOCATION_IF([location << ": " << ])message << std::endl;
+  (void) l;
+  std::cerr << AT_LOCATION_IF([l << ": " << ])m << std::endl;
 }
 
 int
Index: tests/input.at
===================================================================
RCS file: /cvsroot/bison/bison/tests/input.at,v
retrieving revision 1.29
diff -u -u -r1.29 input.at
--- tests/input.at 11 Oct 2004 09:03:55 -0000 1.29
+++ tests/input.at 17 Dec 2004 15:23:25 -0000
@@ -25,7 +25,7 @@
 ## Invalid $n.  ##
 ## ------------ ##
 
-AT_SETUP([Invalid $n])
+AT_SETUP([Invalid \$n])
 
 AT_DATA([input.y],
 [[%%
Index: tests/regression.at
===================================================================
RCS file: /cvsroot/bison/bison/tests/regression.at,v
retrieving revision 1.85
diff -u -u -r1.85 regression.at
--- tests/regression.at 15 Dec 2004 16:18:12 -0000 1.85
+++ tests/regression.at 17 Dec 2004 15:23:25 -0000
@@ -727,9 +727,9 @@
 AT_LALR1_CC_IF(
 [/* A C++ error reporting function. */
 void
-yy::Parser::error_ ()
+yy::Parser::error (const Location&, const std::string& m)
 {
-  std::cerr << message << std::endl;
+  std::cerr << m << std::endl;
 }
 
 int