9 files changed, 30 insertions, 47 deletions

diff --git a/pyecsca/sca/target/ISO7816.py b/pyecsca/sca/target/ISO7816.py
index 896cb62..8da06f8 100644
--- a/pyecsca/sca/target/ISO7816.py
+++ b/pyecsca/sca/target/ISO7816.py
@@ -1,6 +1,4 @@
-"""
-This module provides classes for working with ISO7816-4 APDUs and an abstract base class for an ISO7816-4 based target.
-"""
+"""This module provides classes for working with ISO7816-4 APDUs and an abstract base class for an ISO7816-4 based target."""
 from abc import abstractmethod, ABC
 from dataclasses import dataclass
 from typing import Optional
@@ -13,7 +11,7 @@ from .base import Target
 @public
 @dataclass
 class CommandAPDU(object):  # pragma: no cover
-    """A command APDU that can be sent to an ISO7816-4 target."""
+    """Command APDU that can be sent to an ISO7816-4 target."""
 
     cls: int
     ins: int
@@ -82,7 +80,7 @@ class CommandAPDU(object):  # pragma: no cover
 @public
 @dataclass
 class ResponseAPDU(object):
-    """A response APDU that can be received from an ISO7816-4 target."""
+    """Response APDU that can be received from an ISO7816-4 target."""
 
     data: bytes
     sw: int
@@ -90,18 +88,18 @@ class ResponseAPDU(object):
 
 @public
 class ISO7816Target(Target, ABC):
-    """An ISO7816-4 target."""
+    """ISO7816-4 target."""
 
     @property
     @abstractmethod
     def atr(self) -> bytes:
-        """The ATR (Answer To Reset) of the target."""
+        """Return the ATR (Answer To Reset) of the target."""
         raise NotImplementedError
 
     @abstractmethod
     def select(self, aid: bytes) -> bool:
         """
-        Select an applet with `aid`.
+        Select an applet with :paramref:`~.select.aid`.
 
         :param aid: The AID of the applet to select.
         :return: Whether the selection was successful.
@@ -121,7 +119,7 @@ class ISO7816Target(Target, ABC):
 
 @public
 class ISO7816:
-    """A bunch of ISO7816-4 constants (status words)."""
+    """Bunch of ISO7816-4 constants (status words)."""
 
     SW_FILE_FULL = 0x6A84
     SW_UNKNOWN = 0x6F00
diff --git a/pyecsca/sca/target/PCSC.py b/pyecsca/sca/target/PCSC.py
index 4b2620c..ca77d12 100644
--- a/pyecsca/sca/target/PCSC.py
+++ b/pyecsca/sca/target/PCSC.py
@@ -1,6 +1,4 @@
-"""
-This module provides a smartcard target communicating via PC/SC (Personal Computer/Smart Card).
-"""
+"""This module provides a smartcard target communicating via PC/SC (Personal Computer/Smart Card)."""
 from typing import Union
 
 from public import public
@@ -14,7 +12,7 @@ from .ISO7816 import ISO7816Target, CommandAPDU, ResponseAPDU, ISO7816
 
 @public
 class PCSCTarget(ISO7816Target):  # pragma: no cover
-    """A smartcard target communicating via PCSC."""
+    """Smartcard target communicating via PCSC."""
 
     def __init__(self, reader: Union[str, PCSCReader]):
         if isinstance(reader, str):
diff --git a/pyecsca/sca/target/base.py b/pyecsca/sca/target/base.py
index 6e1758d..0c24f8d 100644
--- a/pyecsca/sca/target/base.py
+++ b/pyecsca/sca/target/base.py
@@ -1,6 +1,4 @@
-"""
-This module provides an abstract base class for targets.
-"""
+"""This module provides an abstract base class for targets."""
 from abc import ABC, abstractmethod
 
 from public import public
diff --git a/pyecsca/sca/target/binary.py b/pyecsca/sca/target/binary.py
index d4c402e..291f8bc 100644
--- a/pyecsca/sca/target/binary.py
+++ b/pyecsca/sca/target/binary.py
@@ -1,6 +1,4 @@
-"""
-This module provides a binary target class which represents a target that is a runnable binary on the host.
-"""
+"""This module provides a binary target class which represents a target that is a runnable binary on the host."""
 import subprocess
 from subprocess import Popen
 from typing import Optional, Union, List
@@ -12,7 +10,7 @@ from .serial import SerialTarget
 
 @public
 class BinaryTarget(SerialTarget):
-    """A binary target that is runnable on the host and communicates using the stdin/stdout streams."""
+    """Binary target that is runnable on the host and communicates using the stdin/stdout streams."""
 
     binary: List[str]
     process: Optional[Popen] = None
diff --git a/pyecsca/sca/target/chipwhisperer.py b/pyecsca/sca/target/chipwhisperer.py
index 4037f12..c9380cc 100644
--- a/pyecsca/sca/target/chipwhisperer.py
+++ b/pyecsca/sca/target/chipwhisperer.py
@@ -1,5 +1,6 @@
 """
 This module provides a `ChipWhisperer <https://github.com/newaetech/chipwhisperer/>`_ target class.
+
 ChipWhisperer is a side-channel analysis tool and framework. A ChipWhisperer target is one
 that uses the ChipWhisperer's SimpleSerial communication protocol and is communicated with
 using ChipWhisperer-Lite or Pro.
@@ -17,10 +18,7 @@ from .simpleserial import SimpleSerialTarget
 
 @public
 class ChipWhispererTarget(Flashable, SimpleSerialTarget):  # pragma: no cover
-    """
-    A ChipWhisperer-based target, using the SimpleSerial protocol and communicating
-    using ChipWhisperer-Lite/Pro.
-    """
+    """ChipWhisperer-based target, using the SimpleSerial protocol and communicating using ChipWhisperer-Lite/Pro."""
 
     def __init__(
         self, target: SimpleSerial, scope: ScopeTemplate, programmer, **kwargs
diff --git a/pyecsca/sca/target/ectester.py b/pyecsca/sca/target/ectester.py
index 08c0e02..4057e61 100644
--- a/pyecsca/sca/target/ectester.py
+++ b/pyecsca/sca/target/ectester.py
@@ -1,6 +1,4 @@
-"""
-This module provides an `ECTester <https://github.com/crocs-muni/ECTester/>`_ target class.
-"""
+"""This module provides an `ECTester <https://github.com/crocs-muni/ECTester/>`_ target class."""
 from abc import ABC
 from binascii import hexlify
 from enum import IntEnum, IntFlag
@@ -511,10 +509,7 @@ class InfoResponse(Response):  # pragma: no cover
 
 @public
 class ECTesterTarget(PCSCTarget):  # pragma: no cover
-    """
-    A smartcard target which communicates with the `ECTester <https://github.com/crocs-muni/ECTester>`_
-    applet on smartcards of the JavaCard platform using PCSC.
-    """
+    """Smartcard target which communicates with the `ECTester <https://github.com/crocs-muni/ECTester>`_ sapplet on smartcards of the JavaCard platform using PCSC."""
 
     CLA_ECTESTER = 0xB0
     AID_PREFIX = bytes([0x45, 0x43, 0x54, 0x65, 0x73, 0x74, 0x65, 0x72])
diff --git a/pyecsca/sca/target/flash.py b/pyecsca/sca/target/flash.py
index cc70a9c..b644c27 100644
--- a/pyecsca/sca/target/flash.py
+++ b/pyecsca/sca/target/flash.py
@@ -1,6 +1,4 @@
-"""
-This module provides a mix-in class of a flashable target (e.g. one where the code gets flashed to it before running).
-"""
+"""This module provides a mix-in class of a flashable target (e.g. one where the code gets flashed to it before running)."""
 from public import public
 from abc import ABC, abstractmethod
 
diff --git a/pyecsca/sca/target/serial.py b/pyecsca/sca/target/serial.py
index a435ca0..fba5d69 100644
--- a/pyecsca/sca/target/serial.py
+++ b/pyecsca/sca/target/serial.py
@@ -1,6 +1,4 @@
-"""
-This module provides an abstract serial target, that communicates by writing and reading a stream of bytes.
-"""
+"""This module provides an abstract serial target, that communicates by writing and reading a stream of bytes."""
 from abc import abstractmethod
 
 from public import public
@@ -10,12 +8,12 @@ from .base import Target
 
 @public
 class SerialTarget(Target):
-    """A serial target."""
+    """Serial target."""
 
     @abstractmethod
     def write(self, data: bytes) -> None:
         """
-        Write the `data` bytes to the target's serial input.
+        Write the :paramref:`~.write.data` bytes to the target's serial input.
 
         :param data: The data to write.
         """
@@ -24,9 +22,9 @@ class SerialTarget(Target):
     @abstractmethod
     def read(self, num: int = 0, timeout: int = 0) -> bytes:
         """
-        Read upto `num` bytes or until `timeout` milliseconds from the target's serial output.
+        Read upto :paramref:`~.read.num` bytes or until :paramref:`~.read.timeout` milliseconds from the target's serial output.
 
-        :param num: The number of bytes to read, `0` for all available.
+        :param num: The number of bytes to read, ``0`` for all available.
         :param timeout: The timeout in milliseconds.
         :return: The bytes read.
         """
diff --git a/pyecsca/sca/target/simpleserial.py b/pyecsca/sca/target/simpleserial.py
index 03cb9cf..a28672e 100644
--- a/pyecsca/sca/target/simpleserial.py
+++ b/pyecsca/sca/target/simpleserial.py
@@ -1,7 +1,4 @@
-"""
-This module provides an abstract target class communicating using the
-`ChipWhisperer's <https://github.com/newaetech/chipwhisperer/>`_ SimpleSerial protocol.
-"""
+"""This module provides an abstract target class communicating using the `ChipWhisperer's <https://github.com/newaetech/chipwhisperer/>`_ SimpleSerial protocol."""
 from time import time_ns, sleep
 from typing import Mapping, Union
 
@@ -42,6 +39,12 @@ class SimpleSerialTarget(SerialTarget):
     """A SimpleSerial target, sends and receives SimpleSerial messages over a serial link."""
 
     def recv_msgs(self, timeout: int) -> Mapping[str, SimpleSerialMessage]:
+        """
+        Receive :py:class:`SimpleSerialMessage` messages, while waiting upto :paramref:`~.recv_msgs.timeout` seconds.
+
+        :param timeout: How long to wait.
+        :return: The received messages with their char.
+        """
         start = time_ns() // 1000000
         buffer = bytes()
         while not buffer.endswith(b"z00\n"):
@@ -65,8 +68,7 @@ class SimpleSerialTarget(SerialTarget):
         self, cmd: SimpleSerialMessage, timeout: int
     ) -> Mapping[str, SimpleSerialMessage]:
         """
-        Send a :py:class:`SimpleSerialMessage` and receive the response messages that the command produces,
-        within a `timeout`.
+        Send a :py:class:`SimpleSerialMessage` and receive the response messages that the command produces, within a :paramref:`~.send_cmd.timeout`.
 
         :param cmd: The command message to send.
         :param timeout: The timeout value to wait for the responses.