L2SS-876: Improve docstrings for antennafield

tangostationcontrol/tangostationcontrol/devices/antennafield.py

@@ -397,12 +397,21 @@ class AntennaField(lofar_device):
         return mapped_values
     
     def set_mapped_attribute(self, mapped_point: str, value):
+        """Set the attribute to new value only for controlled points
+
+        :warning: This method is susceptible to a lost update race condition if the
+                  attribute on the RECV device is written to in between `read_attribute`
+                  and `write_attribute`!
+
+        """
         mapped_value = self.__mapper.map_write(mapped_point, value)
 
         for idx, recv_proxy in enumerate(self.recv_proxies):
             new_values = mapped_value[idx]
+
+            # TODO(Corne): Resolve potential lost update race condition
             current_values = recv_proxy.read_attribute(mapped_point)
-            new_values = self.__mapper.merge_write(new_values, current_values)
+            self.__mapper.merge_write(new_values, current_values)
             recv_proxy.write_attribute(mapped_point, new_values)
     
     # --------
@@ -465,7 +474,8 @@ class AntennaToRecvMapper(object):
     def __init__(self, control_to_recv_mapping, power_to_recv_mapping, number_of_receivers):
         number_of_antennas = len(control_to_recv_mapping)
 
-        # Reduce memory footprint of default values by creating single instance of common fields
+        # Reduce memory footprint of default values by creating single instance of
+        # common fields
         value_map_ant_32_int = numpy.zeros([number_of_antennas, 32], dtype=numpy.int64)
         value_map_ant_32_bool = numpy.full((number_of_antennas, 32), False)
         value_map_ant_bool = numpy.full(number_of_antennas, False)
@@ -503,14 +513,14 @@ class AntennaToRecvMapper(object):
             "HBAT_BF_delay_steps_RW": (96, 32),
         }
 
-    def map_read(self, mapped_attribute: str, recv_results: List[any]):
-        """
+    def map_read(self, mapped_attribute: str, recv_results: List[any]) -> List[any]:
+        """Perform a mapped read for the attribute using the recv_results
 
         :param mapped_attribute: attribute identifier as present in
                                  py:attribute:`~_default_value_mapping_read`
         :param recv_results: Results as gathered by appending attributes from RECV
                              devices
-        :return:
+        :return: recv_results as mapped given attribute dimensions and control mapping
         """
 
         default_values = self._default_value_mapping_read[mapped_attribute]
@@ -521,13 +531,13 @@ class AntennaToRecvMapper(object):
         
         return self._mapped_r_values(recv_results, default_values)
         
-    def map_write(self, mapped_attribute: str, set_values):
+    def map_write(self, mapped_attribute: str, set_values: List[any]) -> List[any]:
         """Perform a mapped write for the attribute using the set_values
 
         :param mapped_attribute: attribute identifier as present in
                                  py:attribute:`~_default_value_mapping_write`
-        :param set_values:
-        :return:
+        :param set_values: The values to be set for the specified attribute
+        :return: set_values as mapped given attribute dimensions and control mapping
         """
 
         default_values = self._masked_value_mapping_write[mapped_attribute]
@@ -540,22 +550,26 @@ class AntennaToRecvMapper(object):
 
         return mapped_values
 
-    def merge_write(self, mapped_values, current_values):
+    @staticmethod
+    def merge_write(merge_values: List[any], current_values: List[any]):
         """Merge values as retrieved from :py:func:`~map_write` with current_values
 
+        This method will modify the contents of merge_values.
+
         To be used by the :py:class:`~AntennaField` device to remove None fields
         from mapped_values with recently retrieved current_values from RECV device.
 
-        :param mapped_values:
-        :param current_values:
-        :return:
+        :param merge_values: values as retrieved from :py:func:`~map_write`
+        :param current_values: values retrieved from RECV device on specific attribute
         """
 
-        for idx, value in enumerate(mapped_values):
+        for idx, value in enumerate(merge_values):
             if value is None:
-                mapped_values[idx] = current_values[idx]
+                merge_values[idx] = current_values[idx]
+
+    def _mapped_r_values(self, recv_results: List[any], default_values: List[any]):
+        """Mapping for read using :py:attribute:`~_control_mapping` and shallow copy"""
 
-    def _mapped_r_values(self, recv_results, default_values):
         mapped_values = numpy.array(default_values)
 
         for idx, mapping in enumerate(self._control_mapping):
@@ -566,7 +580,9 @@ class AntennaToRecvMapper(object):
 
         return mapped_values
 
-    def _mapped_rw_values(self, set_values, default_values):
+    def _mapped_rw_values(self, set_values: List[any], default_values: List[any]):
+        """Mapping for write using :py:attribute:`~_control_mapping` and shallow copy"""
+
         mapped_values = []
 
         for _ in range(self._number_of_receivers):
@@ -579,7 +595,6 @@ class AntennaToRecvMapper(object):
             if recv > 0:
                 mapped_values[recv - 1, rcu] = set_values[idx]
 
-        # import pdb; pdb.set_trace()
         return mapped_values
 
 # ----------