From bf631ea176b33e85e28bdb36af82048c1e557d73 Mon Sep 17 00:00:00 2001
From: Nicolai Buchwitz <n.buchwitz@kunbus.com>
Date: Tue, 3 Feb 2026 16:13:07 +0100
Subject: [PATCH] docs: add missing docstrings to classes and methods

Added docstrings to:
- Error classes (RevPiModIOError, DeviceNotFoundError)
- ProductType constants class
- GatewayMixin class for piGate module detection
- IO __call__ methods (IOBase, IntIO, StructIO)
- MemIO.get_variantvalue method
- RevPiModIO context manager methods (__enter__, __exit__)
---
 src/revpimodio2/device.py  |  2 ++
 src/revpimodio2/errors.py  |  4 ++++
 src/revpimodio2/io.py      | 28 ++++++++++++++++++++++++++++
 src/revpimodio2/modio.py   | 11 +++++++++++
 src/revpimodio2/pictory.py |  2 ++
 5 files changed, 47 insertions(+)

diff --git a/src/revpimodio2/device.py b/src/revpimodio2/device.py
index 0400650..cad4284 100644
--- a/src/revpimodio2/device.py
+++ b/src/revpimodio2/device.py
@@ -572,6 +572,8 @@ class Base(Device):
 
 
 class GatewayMixin:
+    """Mixin class providing piGate module detection functionality."""
+
     @property
     def leftgate(self) -> bool:
         """
diff --git a/src/revpimodio2/errors.py b/src/revpimodio2/errors.py
index cd456f9..121ab3e 100644
--- a/src/revpimodio2/errors.py
+++ b/src/revpimodio2/errors.py
@@ -6,8 +6,12 @@ __license__ = "LGPLv2"
 
 
 class RevPiModIOError(Exception):
+    """Base exception class for RevPiModIO errors."""
+
     pass
 
 
 class DeviceNotFoundError(RevPiModIOError):
+    """Raised when a requested device cannot be found in the configuration."""
+
     pass
diff --git a/src/revpimodio2/io.py b/src/revpimodio2/io.py
index 5849d83..c155eed 100644
--- a/src/revpimodio2/io.py
+++ b/src/revpimodio2/io.py
@@ -493,6 +493,12 @@ class IOBase(object):
             return any(self._parentdevice._ba_devdata[self._slc_address])
 
     def __call__(self, value=None):
+        """
+        Get or set the IO value using function call syntax.
+
+        :param value: If None, returns current value; otherwise sets the value
+        :return: Current IO value when called without arguments
+        """
         if value is None:
             # Inline get_value()
             if self._bitshift:
@@ -978,6 +984,13 @@ class IntIO(IOBase):
         )
 
     def __call__(self, value=None):
+        """
+        Get or set the integer IO value using function call syntax.
+
+        :param value: If None, returns current integer value; otherwise sets the integer value
+        :return: Current IO value as integer when called without arguments
+        :raises TypeError: If value is not an integer
+        """
         if value is None:
             # Inline get_intvalue()
             return int.from_bytes(
@@ -1447,6 +1460,14 @@ class StructIO(IOBase):
             raise BufferError("registered value does not fit process image scope")
 
     def __call__(self, value=None):
+        """
+        Get or set the structured IO value using function call syntax.
+
+        Handles byte and word order conversion based on configuration.
+
+        :param value: If None, returns current value unpacked using struct format; otherwise packs and sets the value
+        :return: Current IO value unpacked according to struct format when called without arguments
+        """
         if value is None:
             # Inline get_structdefaultvalue()
             if self._bitshift:
@@ -1567,6 +1588,13 @@ class MemIO(IOBase):
     """
 
     def get_variantvalue(self):
+        """
+        Get the default value as either string or integer based on bit length.
+
+        For values > 64 bits, returns as decoded string. Otherwise returns as integer.
+
+        :return: Default value as string (if > 64 bits) or integer
+        """
         val = bytes(self._defaultvalue)
 
         if self._bitlength > 64:
diff --git a/src/revpimodio2/modio.py b/src/revpimodio2/modio.py
index 1fd9c71..ff7fa47 100644
--- a/src/revpimodio2/modio.py
+++ b/src/revpimodio2/modio.py
@@ -208,6 +208,12 @@ class RevPiModIO(object):
                 self._myfh.close()
 
     def __enter__(self):
+        """
+        Context manager entry (deprecated).
+
+        .. deprecated::
+            Use ``with revpi.io:`` or ``with revpi.device.my_device:`` instead.
+        """
         # todo: Remove this context manager in future
         warnings.warn(
             "This context manager is deprecated and will be removed!\n\n"
@@ -231,6 +237,11 @@ class RevPiModIO(object):
         return self
 
     def __exit__(self, exc_type, exc_val, exc_tb):
+        """
+        Context manager exit (deprecated).
+
+        Writes process image and performs cleanup.
+        """
         if not self._monitoring:
             self.writeprocimg()
         self.exit(full=True)
diff --git a/src/revpimodio2/pictory.py b/src/revpimodio2/pictory.py
index fd7c55d..b8d1839 100644
--- a/src/revpimodio2/pictory.py
+++ b/src/revpimodio2/pictory.py
@@ -15,6 +15,8 @@ __license__ = "LGPLv2"
 
 
 class ProductType:
+    """Product type constants for Revolution Pi devices and modules."""
+
     CON_BT = 111
     CON_CAN = 109
     CON_MBUS = 110