From 0407acbc595882374febf0a2e471e996131125e6 Mon Sep 17 00:00:00 2001
From: Akim Demaille <akim.demaille@gmail.com>
Date: Thu, 30 Apr 2020 08:34:15 +0200
Subject: [PATCH] java: comment changes

* data/skeletons/lalr1.java, examples/java/calc/Calc.y: here.
---
 data/skeletons/lalr1.java | 17 ++++++++++-------
 examples/java/calc/Calc.y | 25 ++++++++++++++++++++-----
 2 files changed, 30 insertions(+), 12 deletions(-)

diff --git a/data/skeletons/lalr1.java b/data/skeletons/lalr1.java
index e2d4bcad..170be748 100644
--- a/data/skeletons/lalr1.java
+++ b/data/skeletons/lalr1.java
@@ -211,11 +211,10 @@ import java.text.MessageFormat;
     int yylex ()]b4_maybe_throws([b4_lex_throws])[;
 
     /**
-     * Entry point for error reporting.  Emits an error
-     * ]b4_locations_if([referring to the given location ])[in a user-defined way.
+     * Emit an error]b4_locations_if([ referring to the given location])[in a user-defined way.
      *
      *]b4_locations_if([[ @@param loc The location of the element to which the
-     *                error message is related]])[
+     *                error message is related.]])[
      * @@param msg The string for the error message.
      */
      void yyerror (]b4_locations_if([b4_location_type[ loc, ]])[String msg);
@@ -223,9 +222,11 @@ import java.text.MessageFormat;
 ]b4_parse_error_bmatch(
            [custom], [[
     /**
-     * Build and emit a syntax error message.
+     * Build and emit a "syntax error" message in a user-defined way.
+     *
+     * @@param ctx  The context of the error.
      */
-     void reportSyntaxError (][Context yyctx);
+     void reportSyntaxError (][Context ctx);
 ]])[
   }
 
@@ -996,8 +997,10 @@ b4_dollar_popdef[]dnl
   }
 ]])[
 
-/**
-   * Report a syntax error.
+  /**
+   * Build and emit a "syntax error" message in a user-defined way.
+   *
+   * @@param ctx  The context of the error.
    */
   private void yyreportSyntaxError (Context yyctx)
   {]b4_parse_error_bmatch(
diff --git a/examples/java/calc/Calc.y b/examples/java/calc/Calc.y
index d0b507f3..5a5d2048 100644
--- a/examples/java/calc/Calc.y
+++ b/examples/java/calc/Calc.y
@@ -113,6 +113,9 @@ class CalcLexer implements Calc.Lexer {
     return new Position(end);
   }
 
+  /**
+   * Build and emit a syntax error message.
+   */
   public void reportSyntaxError(Calc.Context ctx) {
     System.err.print(ctx.getLocation() + ": syntax error");
     {
@@ -131,11 +134,18 @@ class CalcLexer implements Calc.Lexer {
     System.err.println("");
   }
 
-  public void yyerror(Calc.Location l, String s) {
-    if (l == null)
-      System.err.println(s);
+  /**
+   * Emit an error referring to the given location in a user-defined way.
+   *
+   * @@param loc The location of the element to which the
+   *                error message is related.
+   * @@param msg The string for the error message.
+   */
+  public void yyerror(Calc.Location loc, String msg) {
+    if (loc == null)
+      System.err.println(msg);
     else
-      System.err.println(l + ": " + s);
+      System.err.println(loc + ": " + msg);
   }
 
   Integer yylval;
@@ -185,7 +195,9 @@ class CalcLexer implements Calc.Lexer {
   }
 }
 
-
+/**
+ * A class defining a point in the input.
+ */
 class Position {
   public int line = 1;
   public int column = 1;
@@ -227,6 +239,9 @@ class Position {
   }
 }
 
+/**
+ * A Stream reader that keeps track of the current Position.
+ */
 class PositionReader extends BufferedReader {
 
   private Position position = new Position();