update doc

components/i_feed/devices/traffic_light.py

@@ -39,6 +39,14 @@ class TrafficLight:
                  tlid: str,
                  switching_time: int = SWITCHING_TIME,
                  starting_color: TrafficLightColor = TrafficLightColor.RED):
+        """
+        Init a new Traffic Light client. This will already initialize its message queue.
+        Start it with self.start().
+
+        :param tlid: ID of the traffic light
+        :param switching_time: time in seconds to switch between states (TrafficLightColor.RED and .GREEN)
+        :param starting_color: TrafficLightColor to start with
+        """
         self.tlid = tlid
         self.switching_time = switching_time
         self._starting_color = starting_color

components/i_feed/devices/vehicle.py

@@ -70,6 +70,19 @@ class Vehicle:
                  vin: str,
                  starting_point: geopy.Point = STARTING_POINT,
                  starting_velocity: float = STARTING_VELOCITY):
+        """
+        Initialize a new vehicle client. Already initializes the corresponding sending and receiving message queue.
+        A vehicle sends every UPDATE_INTERVAL seconds its current DAF to the orchestrator. It receives as response the
+        new TargetVelocity to achieve a possible green wave. After a fixed amount of kilometers, the NCE event is
+        happening. The car then stands still for TIME_TO_RECOVER seconds. Afterwards, it starts driving with the last
+        known velocity. While it is recovering, it ignores the target velocity responses from the orchestrator.
+        A vehicle drives a full route between start and end. After reaching the end, it restores the internal state and
+        starts again from the beginning.
+
+        :param vin: Vehicle Identification Number
+        :param starting_point: point on globe to start at
+        :param starting_velocity: velocity to start driving with
+        """
         self.vin = vin
         self._starting_point = starting_point
         self._gps_location = starting_point
@@ -85,6 +98,10 @@ class Vehicle:
     def nce(self):
         """
         On accessing this property, it is calculated if the NCE shall happen. NCE only happens up to once per route.
+        If the NCE happens, the car stopps driving (velocity = 0) for TIME_TO_RECOVER seconds. In this time,
+        responses from the orchestrator are ignored. After recovery, the vehicle starts driving again with the last
+        known velocity.z
+
         :return: True if NCE invoked, otherwise False
         """
         if self._nce_possible and not self._nce_happened:
@@ -115,7 +132,10 @@ class Vehicle:
     @property
     def daf(self):
         """
-        :return: "Datenaufzeichnung für automatisiertes Fahren" (DAF) object
+        Return the DAF object of the vehicle. The properties are always evaluated on calling. That guarantees accurate
+        values.
+
+        :return: current "Datenaufzeichnung für automatisiertes Fahren" (DAF) object
         """
 
         # ATTENTION: ORDER MANDATORY
@@ -133,10 +153,10 @@ class Vehicle:
     @property
     def gps_location(self):
         """
-        Update self.gps_location with given speed in km/h and the driven time in seconds
-        :param velocity: in km/h
-        :param time: in seconds
-        :param bearing: direction in degrees: 0=N, 90=E, 180=S, 270=W
+        An accurate current position of the vehicle at the moment the property is called is retunred.
+        The gps location is derived from the last position this property was called at and the
+        time the vehicle was driving since then. Therefore, it is not necessary to call this function exactly at a given
+        time span, because it calculates the driven kms relative to the calling time.
         """
         # Define starting point.
         start = self._gps_location
@@ -165,6 +185,9 @@ class Vehicle:
 
     @property
     def driven_kms(self):
+        """
+        :returns: a string representation of the driven kms
+        """
         return '{}km'.format(round(self._driven_kms, 2))
 
     def start_driving(self):
@@ -211,12 +234,16 @@ class Vehicle:
 
     @circuit(failure_threshold=10, expected_exception=AMQPConnectionError)
     def send_status_update(self):
+        """
+        Sends the current DAF to the orchestrator. The orchestrator will then respond asynchronously on the response
+        queue.
+        """
         print(self.driven_kms, '\t', self.daf)
         self._daf_mb.send(pickle.dumps(self.daf))
 
     def new_velocity(self, response: bytes):
         """
-        Will be invoked if new target velocity message received
+        Will be invoked if new target velocity message received from orchestrator.
         :param response: pickled TargetVelocity object
         """
         response: TargetVelocity = pickle.loads(response)