c++: locations: complete the API and fix comments

There are no support for += between locations, and some comments are wrong.
Reported by Alexandre Duret-Lutz.

* data/location.cc: Fix.
* doc/bison.texi: Document.
* tests/c++.at: Check.

data/location.cc

@@ -83,7 +83,7 @@ m4_define([b4_position_define],
     }
   };
 
-  /// Add and assign a position.
+  /// Add \a width columns, in place.
   inline position&
   operator+= (position& res, int width)
   {
@@ -91,21 +91,21 @@ m4_define([b4_position_define],
     return res;
   }
 
-  /// Add two position objects.
+  /// Add \a width columns.
   inline position
   operator+ (position res, int width)
   {
     return res += width;
   }
 
-  /// Add and assign a position.
+  /// Subtract \a width columns, in place.
   inline position&
   operator-= (position& res, int width)
   {
     return res += -width;
   }
 
-  /// Add two position objects.
+  /// Subtract \a width columns.
   inline position
   operator- (position res, int width)
   {
@@ -216,36 +216,42 @@ m4_define([b4_location_define],
     position end;
   };
 
-  /// Join two location objects to create a location.
+  /// Join two locations, in place.
-  inline location operator+ (location res, const location& end)
+  inline location& operator+= (location& res, const location& end)
   {
     res.end = end.end;
     return res;
   }
 
-  /// Change end position in place.
+  /// Join two locations.
+  inline location operator+ (location res, const location& end)
+  {
+    return res += end;
+  }
+
+  /// Add \a width columns to the end position, in place.
   inline location& operator+= (location& res, int width)
   {
     res.columns (width);
     return res;
   }
 
-  /// Change end position.
+  /// Add \a width columns to the end position.
   inline location operator+ (location res, int width)
   {
     return res += width;
   }
 
-  /// Change end position in place.
+  /// Subtract \a width columns to the end position, in place.
   inline location& operator-= (location& res, int width)
   {
     return res += -width;
   }
 
-  /// Change end position.
+  /// Subtract \a width columns to the end position.
-  inline location operator- (const location& begin, int width)
+  inline location operator- (location res, int width)
   {
-    return begin + -width;
+    return res -= width;
   }
 ]b4_percent_define_flag_if([[define_location_comparison]], [[
   /// Compare two location objects.

doc/bison.texi

@@ -10686,12 +10686,17 @@ The first, inclusive, position of the range, and the first beyond.
 Forwarded to the @code{end} position.
 @end deftypemethod
 
-@deftypemethod {location} {location} operator+ (const location& @var{end})
+@deftypemethod  {location} {location} operator+  (int @var{width})
-@deftypemethodx {location} {location} operator+ (int @var{width})
 @deftypemethodx {location} {location} operator+= (int @var{width})
-@deftypemethodx {location} {location} operator- (int @var{width})
+@deftypemethodx {location} {location} operator-  (int @var{width})
 @deftypemethodx {location} {location} operator-= (int @var{width})
-Various forms of syntactic sugar.
+Various forms of syntactic sugar for @code{columns}.
+@end deftypemethod
+
+@deftypemethod {location} {location} operator+ (const location& @var{end})
+@deftypemethodx {location} {location} operator+= (const location& @var{end})
+Join two locations: starts at the position of the first one, and ends at the
+position of the second.
 @end deftypemethod
 
 @deftypemethod {location} {void} step ()

tests/c++.at

@@ -60,8 +60,10 @@ main (void)
 {
   int fail = 0;
   ]AT_YYLTYPE[ loc;  fail += check (loc, "1.1");
+                     fail += check (loc + 10, "1.1-10");
   loc += 10;         fail += check (loc, "1.1-10");
   loc += -5;         fail += check (loc, "1.1-5");
+                     fail += check (loc - 5, "1.1");
   loc -= 5;          fail += check (loc, "1.1");
   // Check that we don't go below.
   // http://lists.gnu.org/archive/html/bug-bison/2013-02/msg00000.html
@@ -70,6 +72,11 @@ main (void)
   loc.columns (10); loc.lines (10); fail += check (loc, "1.1-11.0");
   loc.lines (-2);                   fail += check (loc, "1.1-9.0");
   loc.lines (-10);                  fail += check (loc, "1.1");
+
+  ]AT_YYLTYPE[ loc2 (YY_NULLPTR, 5, 10);
+                   fail += check (loc2, "5.10");
+                   fail += check (loc + loc2, "1.1-5.9");
+  loc += loc2;     fail += check (loc, "1.1-5.9");
   return !fail;
 }
 ]])