doc: refactor docstrings

ophyd_devices/epics/devices/eiger9m_csaxs.py

@@ -94,7 +94,19 @@ class Eiger9MSetup(CustomDetectorMixin):
             )
 
     def update_std_cfg(self, cfg_key: str, value: Any) -> None:
-        """Update std_daq config with new e-account for the current beamtime"""
+        """
+        Update std_daq config
+
+        Checks that the new value matches the type of the former entry.
+
+        Args:
+            cfg_key (str)   : config key of value to be updated
+            value (Any)     : value to be updated for the specified key
+
+        Raises:
+            Raises EigerError if the key was not in the config before and if the new value does not match the type of the old value
+
+        """
 
         # Load config from client and check old value
         cfg = self.std_client.get_config()
@@ -116,7 +128,7 @@ class Eiger9MSetup(CustomDetectorMixin):
         logger.debug(f"Updated std_daq config for key {cfg_key} from {old_value} to {value}")
 
     def stop_detector(self) -> None:
-        """Stop the detector and wait for the proper status message"""
+        """Stop the detector"""
 
         # Stop detector
         self.parent.cam.acquire.put(0)
@@ -154,21 +166,16 @@ class Eiger9MSetup(CustomDetectorMixin):
         self.std_client.stop_writer()
 
     def prepare_detector(self) -> None:
-        """
-        Prepare detector for scan
-
-        Includes checking the detector threshold, setting the acquisition parameters
-        and setting the trigger source
-        """
+        """Prepare detector for scan"""
         self.set_detector_threshold()
         self.set_acquisition_params()
         self.parent.set_trigger(TriggerSource.GATING)
 
     def set_detector_threshold(self) -> None:
         """
-        Set correct detector threshold to 1/2 of the current X-ray energy, allow 5% tolerance
+        Set the detector threshold
 
-        Threshold might be in ev or keV
+        The function sets the detector threshold automatically to 1/2 of the beam energy.
         """
 
         # get current beam energy from device manageer

ophyd_devices/epics/devices/falcon_csaxs.py

@@ -34,11 +34,7 @@ class DetectorState(enum.IntEnum):
 
 
 class TriggerSource(enum.IntEnum):
-    """
-    Trigger source for Falcon detector
-
-    Translates setttings for PV:pixel_advance_mode
-    """
+    """Trigger source for Falcon detector"""
 
     USER = 0
     GATE = 1
@@ -46,11 +42,7 @@ class TriggerSource(enum.IntEnum):
 
 
 class MappingSource(enum.IntEnum):
-    """
-    Mapping source for Falcon detector
-
-    Translates setttings for PV:collect_mode
-    """
+    """Mapping source for Falcon detector"""
 
     SPECTRUM = 0
     MAPPING = 1
@@ -272,16 +264,7 @@ class FalconSetup(CustomDetectorMixin):
         pipe.execute()
 
     def finished(self) -> None:
-        """
-        Check if acquisition is finished.
-
-        In case of the Falcon Sitoro, we check if the number of triggers is equal to the number of written frames.
-
-        In case this is not correct, we would NOT (!) raise an Error at this moment
-        because there is data to reassemble the pixels.
-
-        However, this decision could be revoked and handled differently.
-        """
+        """Check if scan finished succesfully"""
         total_frames = int(
             self.parent.scaninfo.num_points * self.parent.scaninfo.frames_per_trigger
         )
@@ -381,12 +364,7 @@ class FalconcSAXS(PSIDetectorBase):
         self.ignore_gate.put(ignore_gate)
 
     def stage(self) -> List[object]:
-        """
-        Add functionality to stage, and arm the detector
-
-        Additional call to:
-        - custom_prepare.arm_acquisition()
-        """
+        """Stage"""
         rtr = super().stage()
         self.custom_prepare.arm_acquisition()
         return rtr

ophyd_devices/epics/devices/pilatus_csaxs.py

@@ -304,10 +304,11 @@ class PilatusSetup(CustomDetectorMixin):
         return requests.delete(url=url, headers=headers, timeout=5)
 
     def pre_scan(self) -> None:
-        """Pre_scan is an (optional) function that is executed by BEC just before the scan core
+        """
+        Pre_scan function call
 
-        For the pilatus detector, it is used to arm the detector for the acquisition,
-        because the detector times out after ˜7-8 seconds without seeing a trigger.
+        This function is called just before the scan core.
+        Here it is used to arm the detector for the acquisition
 
         """
         self.arm_acquisition()
@@ -355,15 +356,9 @@ class PilatusSetup(CustomDetectorMixin):
         pipe.execute()
 
     def finished(self) -> None:
-        """
-        Check if acquisition is finished.
-
-        Be aware that we check here whether the mcs card is measuring at the moment,
-        we were missing a suitable different signal.
-
-        #TODO remove dependency from the mcs card
-        """
+        """Check if acquisition is finished."""
         # pylint: disable=protected-access
+        # TODO: at the moment this relies on device.mcs.obj._staged attribute
         signal_conditions = [
             (
                 lambda: self.parent.device_manager.devices.mcs.obj._staged,
@@ -429,6 +424,5 @@ class PilatuscSAXS(PSIDetectorBase):
         self.cam.trigger_mode.put(value)
 
 
-# Automatically connect to test environmenr if directly invoked
 if __name__ == "__main__":
     pilatus_2 = PilatuscSAXS(name="pilatus_2", prefix="X12SA-ES-PILATUS300K:", sim_mode=True)

tests/test_falcon_csaxs.py

@@ -103,7 +103,6 @@ def test_init_detector(
     ],
 )
 def test_update_readout_time(mock_det, readout_time, expected_value):
-    # mock_det.scaninfo.readout_time = readout_time
     if readout_time is None:
         mock_det.custom_prepare.update_readout_time()
         assert mock_det.readout_time == expected_value