From 86efe2822260949ee5bfd2512f6aa007901d39f4 Mon Sep 17 00:00:00 2001
From: Akim Demaille <akim.demaille@gmail.com>
Date: Sun, 4 Nov 2018 13:03:43 +0100
Subject: [PATCH] c++: improve the generated documentation

* data/lalr1.cc, data/location.cc: Improve documenting comments.
* tests/c++.at (Doxygen Documentation): Fix AT_BISON_OPTION_PUSHDEFS,
so that the generated yyerror is correct.
* tests/c++.at, tests/headers.at: Prefer %empty.
---
 data/lalr1.cc    | 3 ++-
 data/location.cc | 4 ++--
 tests/c++.at     | 7 ++++---
 tests/headers.at | 4 ++--
 4 files changed, 10 insertions(+), 8 deletions(-)

diff --git a/data/lalr1.cc b/data/lalr1.cc
index 30c6f7b9..936dacd1 100644
--- a/data/lalr1.cc
+++ b/data/lalr1.cc
@@ -272,8 +272,9 @@ m4_define([b4_shared_declarations],
     /// Print the state stack on the debug stream.
     virtual void yystack_print_ ();
 
-    // Debugging.
+    /// Debugging level.
     int yydebug_;
+    /// Debug stream.
     std::ostream* yycdebug_;
 
     /// \brief Display a symbol type, value and location.
diff --git a/data/location.cc b/data/location.cc
index 88106036..906939d4 100644
--- a/data/location.cc
+++ b/data/location.cc
@@ -59,7 +59,7 @@ m4_ifdef([b4_location_file],
 # ------------------
 # Define the position and location classes.
 m4_define([b4_location_define],
-[[  /// Abstract a position.
+[[  /// A point in a source file.
   class position
   {
   public:]m4_ifdef([b4_location_constructors], [[
@@ -178,7 +178,7 @@ m4_define([b4_location_define],
     return ostr << pos.line << '.' << pos.column;
   }
 
-  /// Abstract a location.
+  /// Two points in a source file.
   class location
   {
   public:
diff --git a/tests/c++.at b/tests/c++.at
index c25aca32..b23f761b 100644
--- a/tests/c++.at
+++ b/tests/c++.at
@@ -679,14 +679,15 @@ m4_define([AT_CHECK_DOXYGEN],
          [m4_fatal([invalid argument: $1])])
 AT_SETUP([Doxygen $1 Documentation])
 
-AT_BISON_OPTION_PUSHDEFS([%skeleton "lalr1.cc"])
+AT_BISON_OPTION_PUSHDEFS([%skeleton "lalr1.cc" %locations])
 AT_DATA([input.yy],
-[[%skeleton "lalr1.cc"
+[[%require "3.2"
+%skeleton "lalr1.cc"
 %locations
 %defines
 %debug
 %%
-exp: /* empty */;
+exp: %empty;
 %%
 ]AT_YYERROR_DEFINE[
 ]])
diff --git a/tests/headers.at b/tests/headers.at
index 490cf1d4..637fd81c 100644
--- a/tests/headers.at
+++ b/tests/headers.at
@@ -41,7 +41,7 @@ AT_DATA_GRAMMAR([$1.y],
 ]AT_YYLEX_DECLARE_EXTERN[
 %}
 %%
-dummy: /* empty */;
+dummy: %empty;
 %%
 #include <$1.h>
 ])
@@ -81,7 +81,7 @@ AT_DATA_GRAMMAR([input.y],
 ]AT_YYLEX_DEFINE[
 %}
 %%
-exp: /* empty */;
+exp: %empty;
 ]])
 
 AT_BISON_CHECK([--defines -o input.c input.y])