[PATCH v9 13/21] dts: port and virtual device docstring update

["Juraj Linkeš" <juraj.linkes@pantheon.tech>]

Format according to the Google format and PEP257, with slight
deviations.

Signed-off-by: Juraj Linkeš <juraj.linkes@pantheon.tech>
---
 dts/framework/testbed_model/__init__.py       | 17 ++++--
 dts/framework/testbed_model/port.py           | 53 +++++++++++++++----
 dts/framework/testbed_model/virtual_device.py | 17 +++++-
 3 files changed, 72 insertions(+), 15 deletions(-)

diff --git a/dts/framework/testbed_model/__init__.py b/dts/framework/testbed_model/__init__.py
index 8ced05653b..6086512ca2 100644
--- a/dts/framework/testbed_model/__init__.py
+++ b/dts/framework/testbed_model/__init__.py
@@ -2,9 +2,20 @@
 # Copyright(c) 2022-2023 University of New Hampshire
 # Copyright(c) 2023 PANTHEON.tech s.r.o.
 
-"""
-This package contains the classes used to model the physical traffic generator,
-system under test and any other components that need to be interacted with.
+"""Testbed modelling.
+
+This package defines the testbed elements DTS works with:
+
+    * A system under test node: :class:`~.sut_node.SutNode`,
+    * A traffic generator node: :class:`~.tg_node.TGNode`,
+    * The ports of network interface cards (NICs) present on nodes: :class:`~.port.Port`,
+    * The logical cores of CPUs present on nodes: :class:`~.cpu.LogicalCore`,
+    * The virtual devices that can be created on nodes: :class:`~.virtual_device.VirtualDevice`,
+    * The operating systems running on nodes: :class:`~.linux_session.LinuxSession`
+      and :class:`~.posix_session.PosixSession`.
+
+DTS needs to be able to connect to nodes and understand some of the hardware present on these nodes
+to properly build and test DPDK.
 """
 
 # pylama:ignore=W0611
diff --git a/dts/framework/testbed_model/port.py b/dts/framework/testbed_model/port.py
index 680c29bfe3..817405bea4 100644
--- a/dts/framework/testbed_model/port.py
+++ b/dts/framework/testbed_model/port.py
@@ -2,6 +2,13 @@
 # Copyright(c) 2022 University of New Hampshire
 # Copyright(c) 2023 PANTHEON.tech s.r.o.
 
+"""NIC port model.
+
+Basic port information, such as location (the port are identified by their PCI address on a node),
+drivers and address.
+"""
+
+
 from dataclasses import dataclass
 
 from framework.config import PortConfig
@@ -9,24 +16,35 @@
 
 @dataclass(slots=True, frozen=True)
 class PortIdentifier:
+    """The port identifier.
+
+    Attributes:
+        node: The node where the port resides.
+        pci: The PCI address of the port on `node`.
+    """
+
     node: str
     pci: str
 
 
 @dataclass(slots=True)
 class Port:
-    """
-    identifier: The PCI address of the port on a node.
-
-    os_driver: The driver used by this port when the OS is controlling it.
-        Example: i40e
-    os_driver_for_dpdk: The driver the device must be bound to for DPDK to use it,
-        Example: vfio-pci.
+    """Physical port on a node.
 
-    Note: os_driver and os_driver_for_dpdk may be the same thing.
-        Example: mlx5_core
+    The ports are identified by the node they're on and their PCI addresses. The port on the other
+    side of the connection is also captured here.
+    Each port is serviced by a driver, which may be different for the operating system (`os_driver`)
+    and for DPDK (`os_driver_for_dpdk`). For some devices, they are the same, e.g.: ``mlx5_core``.
 
-    peer: The identifier of a port this port is connected with.
+    Attributes:
+        identifier: The PCI address of the port on a node.
+        os_driver: The operating system driver name when the operating system controls the port,
+            e.g.: ``i40e``.
+        os_driver_for_dpdk: The operating system driver name for use with DPDK, e.g.: ``vfio-pci``.
+        peer: The identifier of a port this port is connected with.
+            The `peer` is on a different node.
+        mac_address: The MAC address of the port.
+        logical_name: The logical name of the port. Must be discovered.
     """
 
     identifier: PortIdentifier
@@ -37,6 +55,12 @@ class Port:
     logical_name: str = ""
 
     def __init__(self, node_name: str, config: PortConfig):
+        """Initialize the port from `node_name` and `config`.
+
+        Args:
+            node_name: The name of the port's node.
+            config: The test run configuration of the port.
+        """
         self.identifier = PortIdentifier(
             node=node_name,
             pci=config.pci,
@@ -47,14 +71,23 @@ def __init__(self, node_name: str, config: PortConfig):
 
     @property
     def node(self) -> str:
+        """The node where the port resides."""
         return self.identifier.node
 
     @property
     def pci(self) -> str:
+        """The PCI address of the port."""
         return self.identifier.pci
 
 
 @dataclass(slots=True, frozen=True)
 class PortLink:
+    """The physical, cabled connection between the ports.
+
+    Attributes:
+        sut_port: The port on the SUT node connected to `tg_port`.
+        tg_port: The port on the TG node connected to `sut_port`.
+    """
+
     sut_port: Port
     tg_port: Port
diff --git a/dts/framework/testbed_model/virtual_device.py b/dts/framework/testbed_model/virtual_device.py
index eb664d9f17..e9b5e9c3be 100644
--- a/dts/framework/testbed_model/virtual_device.py
+++ b/dts/framework/testbed_model/virtual_device.py
@@ -1,16 +1,29 @@
 # SPDX-License-Identifier: BSD-3-Clause
 # Copyright(c) 2023 PANTHEON.tech s.r.o.
 
+"""Virtual devices model.
+
+Alongside support for physical hardware, DPDK can create various virtual devices.
+"""
+
 
 class VirtualDevice(object):
-    """
-    Base class for virtual devices used by DPDK.
+    """Base class for virtual devices used by DPDK.
+
+    Attributes:
+        name: The name of the virtual device.
     """
 
     name: str
 
     def __init__(self, name: str):
+        """Initialize the virtual device.
+
+        Args:
+            name: The name of the virtual device.
+        """
         self.name = name
 
     def __str__(self) -> str:
+        """This corresponds to the name used for DPDK devices."""
         return self.name
-- 
2.34.1