java: beware not to alias the locations of the various symbols

* examples/java/calc/Calc.y, tests/calc.at, tests/local.at
(getStartPos, getEndPos): Always return a new object.
* doc/bison.texi: Clarify this.

doc/bison.texi

@@ -12889,9 +12889,12 @@ Default is @code{java.io.IOException}.
 
 @deftypemethod {Lexer} {Position} getStartPos ()
 @deftypemethodx {Lexer} {Position} getEndPos ()
-Return respectively the first position of the last token that
+Return respectively the first position of the last token that @code{yylex}
-@code{yylex} returned, and the first position beyond it.  These
+returned, and the first position beyond it.  These methods are not needed
-methods are not needed unless location tracking is active.
+unless location tracking is active.
+
+They should return new objects for each call, to avoid that all the symbol
+share the same Position boundaries.
 
 The return type can be changed using @code{%define api.position.type
 @{@var{class-name}@}}.

examples/java/calc/Calc.y

@@ -99,11 +99,11 @@ class CalcLexer implements Calc.Lexer {
   Position end = new Position (1, 0);
 
   public Position getStartPos () {
-    return start;
+    return new Position (start);
   }
 
   public Position getEndPos () {
-    return end;
+    return new Position (end);
   }
 
   public void yyreportSyntaxError (Calc.Context ctx)
@@ -175,6 +175,12 @@ class Position {
     column = t;
   }
 
+  public Position (Position p)
+  {
+    line = p.line;
+    column = p.column;
+  }
+
   public void set (Position p)
   {
     line = p.line;

tests/calc.at

@@ -352,11 +352,11 @@ m4_define([AT_CALC_YYLEX(java)],
   Position end = new Position (1, 0);
 
   public Position getStartPos () {
-    return start;
+    return new Position (start);
   }
 
   public Position getEndPos () {
-    return end;
+    return new Position (end);
   }
 
 ]])[

tests/local.at

@@ -847,6 +847,12 @@ m4_define([AT_JAVA_POSITION_DEFINE],
     column = t;
   }
 
+  public Position (Position p)
+  {
+    line = p.line;
+    column = p.column;
+  }
+
   public void set (Position p)
   {
     line = p.line;