WIP: more docstrings

src/ophyd_async/fastcs/panda/_trigger.py

@@ -9,6 +9,8 @@
 
 
 class SeqTableInfo(BaseModel):
+    """Info for the PandA `SeqTable` for flyscanning."""
+
     sequence_table: SeqTable = Field(strict=True)
     repeats: int = Field(ge=0)
     prescale_as_us: float = Field(default=1, ge=0)  # microseconds
@@ -44,6 +46,8 @@ async def stop(self):
 
 
 class PcompInfo(BaseModel):
+    """Info for the PandA `Pcomp` for flyscanning."""
+
     start_postion: int = Field(description="start position in counts")
     pulse_width: int = Field(description="width of a single pulse in counts", gt=0)
     rising_edge_step: int = Field(

src/ophyd_async/plan_stubs/_ensure_connected.py

@@ -12,6 +12,7 @@ def ensure_connected(
     timeout: float = DEFAULT_TIMEOUT,
     force_reconnect=False,
 ):
+    """Plan stub to ensure devices are connected with a given timeout."""
     device_names = [device.name for device in devices]
     non_unique = {
         device: device.name for device in devices if device_names.count(device.name) > 1

src/ophyd_async/plan_stubs/_nd_attributes.py

@@ -16,6 +16,7 @@
 def setup_ndattributes(
     device: NDArrayBaseIO, ndattributes: Sequence[NDAttributePv | NDAttributeParam]
 ):
+    """Set up attributes on NdArray devices."""
     root = ET.Element("Attributes")
 
     for ndattribute in ndattributes:
@@ -50,6 +51,8 @@ def setup_ndattributes(
 
 
 def setup_ndstats_sum(detector: Device):
+    """Set up nd stats for a detector."""
+
     hdf = getattr(detector, "fileio", None)
     if not isinstance(hdf, NDFileHDFIO):
         msg = (

src/ophyd_async/plan_stubs/_panda.py

@@ -8,6 +8,7 @@
 
 @plan
 def apply_panda_settings(settings: Settings[panda.HDFPanda]) -> MsgGenerator[None]:
+    """Apply given settings to a panda device."""
     units, others = settings.partition(lambda signal: signal.name.endswith("_units"))
     yield from apply_settings(units)
     yield from apply_settings(others)

src/ophyd_async/plan_stubs/_settings.py

@@ -33,6 +33,8 @@ def _get_values_of_signals(
 
 @plan
 def get_current_settings(device: Device) -> MsgGenerator[Settings]:
+    """Get current settings on `Device`."""
+
     signals = walk_rw_signals(device)
     named_values = yield from _get_values_of_signals(signals)
     signal_values = {signals[name]: value for name, value in named_values.items()}

src/ophyd_async/sim/_blob_detector.py

@@ -8,6 +8,8 @@
 
 
 class SimBlobDetector(StandardDetector):
+    """Simulates a detector and writes Blobs to file."""
+
     def __init__(
         self,
         path_provider: PathProvider,

src/ophyd_async/sim/_motor.py

@@ -18,6 +18,8 @@
 
 
 class SimMotor(StandardReadable, Movable, Stoppable):
+    """For usage when simulating a motor."""
+
     def __init__(self, name="", instant=True) -> None:
         """Simulation of a motor, with optional velocity
 

src/ophyd_async/sim/_pattern_generator.py

@@ -71,6 +71,8 @@ def close(self):
 
 
 class PatternGenerator:
+    """Generates pattern images in files."""
+
     def __init__(self):
         self._x = 0.0
         self._y = 0.0

src/ophyd_async/sim/_point_detector.py

@@ -37,6 +37,8 @@ def __init__(self, value_signal: SignalR[int], name=""):
 
 
 class SimPointDetector(StandardReadable):
+    """Simalutes a point detector with multiple channels"""
+
     def __init__(
         self, generator: PatternGenerator, num_channels: int = 3, name: str = ""
     ) -> None:

src/ophyd_async/tango/core/_signal.py

@@ -147,6 +147,8 @@ def tango_signal_x(
 async def infer_python_type(
     trl: str = "", proxy: DeviceProxy | None = None
 ) -> object | npt.NDArray | type[DevState] | IntEnum:
+    """Infers the python type from the TRL."""
+
     # TODO: work out if this is still needed
     device_trl, tr_name = trl.rsplit("/", 1)
     if proxy is None:

src/ophyd_async/tango/core/_tango_transport.py

@@ -46,6 +46,8 @@
 def ensure_proper_executor(
     func: Callable[..., Coroutine[Any, Any, R]],
 ) -> Callable[..., Coroutine[Any, Any, R]]:
+    """Ensures decorated method has a proper asyncio executor."""
+
     @functools.wraps(func)
     async def wrapper(self: Any, *args: Any, **kwargs: Any) -> R:
         current_executor: AsyncioExecutor = get_global_executor()  # type: ignore
@@ -57,6 +59,7 @@ async def wrapper(self: Any, *args: Any, **kwargs: Any) -> R:
 
 
 def get_python_type(tango_type: CmdArgType) -> tuple[bool, object, str]:
+    """For converting between recieved tango types and python primatives."""
     array = is_array(tango_type)
     if is_int(tango_type, True):
         return array, int, "integer"
@@ -138,6 +141,8 @@ def set_polling(
 
 
 class AttributeProxy(TangoProxy):
+    """Used by the tango transport."""
+
     _callback: Callback | None = None
     _eid: int | None = None
     _poll_task: asyncio.Task | None = None
@@ -386,6 +391,8 @@ def set_polling(
 
 
 class CommandProxy(TangoProxy):
+    """Tango proxy for commands."""
+
     _last_reading: Reading = Reading(value=None, timestamp=0, alarm_severity=0)
 
     def subscribe_callback(self, callback: Callback | None) -> None:
@@ -474,6 +481,7 @@ def set_polling(
 
 
 def get_dtype_extended(datatype) -> object | None:
+    """For converting tango types to numpy datatype formats."""
     # DevState tango type does not have numpy equivalents
     dtype = get_dtype(datatype)
     if dtype == np.object_:
@@ -487,6 +495,8 @@ def get_trl_descriptor(
     tango_resource: str,
     tr_configs: dict[str, AttributeInfoEx | CommandInfo],
 ) -> Descriptor:
+    """Creates a descriptor from a tango resource locator."""
+
     tr_dtype = {}
     for tr_name, config in tr_configs.items():
         if isinstance(config, AttributeInfoEx):
@@ -583,6 +593,8 @@ def get_trl_descriptor(
 async def get_tango_trl(
     full_trl: str, device_proxy: DeviceProxy | TangoProxy | None, timeout: float
 ) -> TangoProxy:
+    """Gets the tango resource locator."""
+
     if isinstance(device_proxy, TangoProxy):
         return device_proxy
     device_trl, trl_name = full_trl.rsplit("/", 1)
@@ -618,6 +630,8 @@ async def get_tango_trl(
 
 
 class TangoSignalBackend(SignalBackend[SignalDatatypeT]):
+    """Tango backend to connect signals over tango."""
+
     def __init__(
         self,
         datatype: type[SignalDatatypeT] | None,

src/ophyd_async/tango/demo/_counter.py

@@ -6,6 +6,8 @@
 
 
 class TangoCounter(TangoReadable):
+    """Tango counting device."""
+
     # Enter the name and type of the signals you want to use
     # If the server doesn't support events, the TangoPolling annotation gives
     # the parameters for ophyd to poll instead

src/ophyd_async/tango/demo/_detector.py

@@ -11,6 +11,8 @@
 
 
 class TangoDetector(StandardReadable):
+    """For use with tango detector devices."""
+
     def __init__(self, mover_trl: str, counter_trls: list[str], name=""):
         # A detector device may be composed of tango sub-devices
         self.mover = TangoMover(mover_trl)

src/ophyd_async/tango/demo/_mover.py

@@ -22,6 +22,8 @@
 
 
 class TangoMover(TangoReadable, Movable, Stoppable):
+    """Tango moving device."""
+
     # Enter the name and type of the signals you want to use
     # If the server doesn't support events, the TangoPolling annotation gives
     # the parameters for ophyd to poll instead

src/ophyd_async/tango/demo/_tango/_servers.py

@@ -8,6 +8,8 @@
 
 
 class DemoMover(Device):
+    """Demo tango moving device."""
+
     green_mode = GreenMode.Asyncio
     _position = 0.0
     _setpoint = 0.0
@@ -65,6 +67,8 @@ async def _move(self, new_position):
 
 
 class DemoCounter(Device):
+    """Demo tango counting device."""
+
     green_mode = GreenMode.Asyncio
     _counts = 0
     _sample_time = 1.0

src/ophyd_async/testing/_assert.py

@@ -22,6 +22,7 @@
 
 
 def approx_value(value: Any):
+    """For appoximating values on signals. `Table`s cant use `pytest.approx`"""
     return ApproxTable(value) if isinstance(value, Table) else pytest.approx(value)
 
 
@@ -82,6 +83,8 @@ async def assert_configuration(
 
 
 async def assert_describe_signal(signal: SignalR, /, **metadata):
+    """Asserts the describe of a signal matches the expected metadata."""
+
     actual_describe = await signal.describe()
     assert list(actual_describe) == [signal.name]
     (actual_datakey,) = actual_describe.values()
@@ -114,6 +117,11 @@ def assert_emitted(docs: dict[str, list[dict]], **numbers: int):
 
 
 class ApproxTable:
+    """
+    For approximating two tables are equivalent, up to
+    some relative or absolute difference.
+    """
+
     def __init__(self, expected: Table, rel=None, abs=None, nan_ok: bool = False):
         self.expected = expected
         self.rel = rel

src/ophyd_async/testing/_one_of_everything.py

@@ -19,6 +19,8 @@
 
 
 class ExampleEnum(StrictEnum):
+    """Example of a strict Enum datatype."""
+
     A = "Aaa"
     B = "Bbb"
     C = "Ccc"
@@ -61,6 +63,8 @@ def float_array_signal(
 
 
 class OneOfEverythingDevice(StandardReadable):
+    """A device with one of every datatype allowed on signals."""
+
     # make a detector to test assert_configuration
     def __init__(self, name=""):
         # add all signals to configuration
@@ -112,6 +116,8 @@ async def _get_signal_values(child: Device) -> dict[SignalRW, Any]:
 
 
 class ParentOfEverythingDevice(Device):
+    """Device containing subdevices with one of every datatype allowed on signals."""
+
     def __init__(self, name=""):
         self.child = OneOfEverythingDevice()
         self.vector = DeviceVector(

tests/tango/test_tango_signals.py

@@ -266,6 +266,8 @@ async def make_backend(
     connect: bool = True,
     allow_events: bool | None = True,
 ) -> TangoSignalBackend:
+    """Wrapper for making the tango signal backend."""
+
     backend = TangoSignalBackend(typ, pv, pv)
     backend.allow_events(allow_events)
     if connect:
@@ -281,6 +283,8 @@ async def prepare_device(echo_device: str, pv: str, put_value: T) -> None:
 
 # --------------------------------------------------------------------
 class MonitorQueue:
+    """For monitoring updates in tests."""
+
     def __init__(self, backend: SignalBackend):
         self.updates: asyncio.Queue[Reading] = asyncio.Queue()
         self.backend = backend