From cac9b01d2e8c4d36517dbcab6614ba1078fc1953 Mon Sep 17 00:00:00 2001
From: Relm-Arrowny <raymond.fan@diamond.ac.uk>
Date: Thu, 18 Apr 2024 11:09:16 +0000
Subject: [PATCH] fixing all the docstrings

---
 src/ophyd_async/core/signal.py | 53 ++++++++++++++++++++++------------
 1 file changed, 35 insertions(+), 18 deletions(-)

diff --git a/src/ophyd_async/core/signal.py b/src/ophyd_async/core/signal.py
index 45cf0400cf..72c884127a 100644
--- a/src/ophyd_async/core/signal.py
+++ b/src/ophyd_async/core/signal.py
@@ -262,20 +262,27 @@ async def _verify_readings(
     expectation: Mapping[str, Reading],
 ) -> None:
     """Take a read/read_configuration function that return a dictionary and
-      compare it with the expected result (expectation)
+        compare it with the expected result (expectation)
 
     Parameters
     ----------
     func:
-        read/read_configuration function, call at the start
-        and results is validate with the expectation.
+        read/read_configuration function.
+
     expectation:
         The expected value from the readable/Configurable.
 
     Notes
     -----
     Example usage::
-        await assert_reading(signal, value)
+        await _verify_readings(readable.read, reading)
+    Or::
+        await _verify_readings(configurable.read_configuration, configuration)
+    Future::
+        func will only be Waitable in the future and the if loop can be removed:
+
+        result = func()
+
     """
     if asyncio.iscoroutinefunction(func):
         result = await func()
@@ -287,34 +294,31 @@ async def _verify_readings(
 
 
 async def assert_value(signal: SignalR[T], value: T) -> None:
-    """Assert a signal value
+    """Assert a signal's value and compare it an expected signal.
 
     Parameters
     ----------
     signal:
-        Call signal.get_value and compare it with expected value.
+        signal with get_value.
     value:
         The expected value from the signal.
 
     Notes
     -----
     Example usage::
-        await _verify_readings(readable.read, reading)
-    Or::
-        await _verify_readings(configurable.read_configuration, configuration)
-
+        await assert_value(signal, value)
 
     """
     assert await signal.get_value() == value
 
 
 async def assert_reading(readable: Readable, reading: Dict[str, Reading]) -> None:
-    """Assert readable by calling_verify_readings
+    """Assert readings from readable.
 
     Parameters
     ----------
     readable:
-        Call readable.read and compare it with expected reading.
+        Callable with readable.read function that generate readings.
 
     reading:
         The expected readings from the readable.
@@ -332,17 +336,15 @@ async def assert_configuration(
     configurable: Configurable,
     configuration: Mapping[str, Reading],
 ) -> None:
-    """
-    Assert configurable generated by configurable.read_configuration by
-    using _verify_readings
+    """Assert readings from Configurable.
 
     Parameters
     ----------
     configurable:
-        Call configurable.read_configuration and compare it with expected configuration.
+        Configurable with Configurable.read function that generate readings.
 
     configuration:
-        The expected readings from the configurable.
+        The expected readings from configurable.
 
     Notes
     -----
@@ -354,7 +356,22 @@ async def assert_configuration(
 
 
 def assert_emitted(docs: Mapping[str, list[DocumentType]], **numbers: int):
-    """Assert emitted"""
+    """Assert emitted document generated by running a Bluesky plan
+
+    Parameters
+    ----------
+    Doc:
+        A dictionary
+
+    numbers:
+        expected emission in kwarg from
+
+    Notes
+    -----
+    Example usage::
+        assert_emitted(docs, start=1, descriptor=1,
+        resource=1, datum=1, event=1, stop=1)
+    """
     assert list(docs) == list(numbers)
     assert {name: len(d) for name, d in docs.items()} == numbers