From 1ae7bce8990b09ede1330aebf656df57cc8994d8 Mon Sep 17 00:00:00 2001
From: Michael Behrisch <michael.behrisch@dlr.de>
Date: Fri, 19 Jan 2024 14:31:13 +0100
Subject: [PATCH] improving docs for lanechangestate #2 fix #13981

---
 docs/web/docs/TraCI/Vehicle_Value_Retrieval.md | 2 +-
 tools/traci/_vehicle.py                        | 8 +++++++-
 2 files changed, 8 insertions(+), 2 deletions(-)

diff --git a/docs/web/docs/TraCI/Vehicle_Value_Retrieval.md b/docs/web/docs/TraCI/Vehicle_Value_Retrieval.md
index f9a3464874bb..b1d60325f0be 100644
--- a/docs/web/docs/TraCI/Vehicle_Value_Retrieval.md
+++ b/docs/web/docs/TraCI/Vehicle_Value_Retrieval.md
@@ -586,7 +586,7 @@ Some further messages require additional parameters.
 <td><p>change lane information (0x13)</p></td>
 <td><p>compound , <a href="#change_lane_information_0x13" title="wikilink">see below</a></p></td>
 <td><p>int, int <a href="#change_lane_information_0x13" title="wikilink">see below</a></p></td>
-<td><p>Return whether the vehicle could change lanes in the specified direction (right: -1, left: 1. sublane-change within current lane: 0).<br />
+<td><p>Return whether the vehicle could change lanes in the specified direction in the previous step (right: -1, left: 1. sublane-change within current lane: 0).<br />
 Return the lane change state for the vehicle.</p></td>
 <td><p><a href="https://sumo.dlr.de/pydoc/traci._vehicle.html#VehicleDomain-getLaneChangeState">getLaneChangeState</a> <a href="https://sumo.dlr.de/pydoc/traci._vehicle.html#VehicleDomain-couldChangeLane">couldChangeLane</a> <a href="https://sumo.dlr.de/pydoc/traci._vehicle.html#VehicleDomain-wantsAndCouldChangeLane">wantsAndCouldChangeLane</a></p></td>
 </tr>
diff --git a/tools/traci/_vehicle.py b/tools/traci/_vehicle.py
index 8ee81f29d02e..1e095e19d74d 100644
--- a/tools/traci/_vehicle.py
+++ b/tools/traci/_vehicle.py
@@ -940,7 +940,10 @@ def prettifyBitstring(intval):
 
     def couldChangeLane(self, vehID, direction, state=None):
         """couldChangeLane(string, int) -> bool
-        Return whether the vehicle could change lanes in the specified direction
+        Return whether the vehicle could change lanes in the specified direction.
+        This reflects the state after the last try to change lanes.
+        If you want to execute changeLane as a result of the evaluation of this function
+        it is not guaranteed to work because vehicle movements occur first.
         """
         if state is None:
             state, stateTraCI = self.getLaneChangeState(vehID, direction)
@@ -952,6 +955,9 @@ def couldChangeLane(self, vehID, direction, state=None):
     def wantsAndCouldChangeLane(self, vehID, direction, state=None):
         """wantsAndCouldChangeLane(string, int) -> bool
         Return whether the vehicle wants to and could change lanes in the specified direction
+        This reflects the state after the last try to change lanes.
+        If you want to execute changeLane as a result of the evaluation of this function
+        it is not guaranteed to work because vehicle movements occur first.
         """
         if state is None:
             state, stateTraCI = self.getLaneChangeState(vehID, direction)