Add doc strings for some key classes

src/fastcs/attributes.py

@@ -7,19 +7,25 @@
 
 
 class AttrMode(Enum):
+    """Access mode of an `Attribute`."""
+
     READ = 1
     WRITE = 2
     READ_WRITE = 3
 
 
 @runtime_checkable
 class Sender(Protocol):
+    """Protocol for setting the value of an `Attribute`."""
+
     async def put(self, controller: Any, attr: AttrW, value: Any) -> None:
         pass
 
 
 @runtime_checkable
 class Updater(Protocol):
+    """Protocol for updating the cached readback value of an `Attribute`."""
+
     update_period: float
 
     async def update(self, controller: Any, attr: AttrR) -> None:
@@ -28,10 +34,22 @@ async def update(self, controller: Any, attr: AttrR) -> None:
 
 @runtime_checkable
 class Handler(Sender, Updater, Protocol):
+    """Protocol encapsulating both `Sender` and `Updater`."""
+
     pass
 
 
 class Attribute(Generic[T]):
+    """Base FastCS attribute.
+
+    Instances of this class added to a `Controller` will be exposed to the backend.
+
+    Args:
+        datatype: Type of attribute
+        access_mode: Access mode of attribute
+        group: Group to include attribute in on generated UI
+    """
+
     def __init__(
         self, datatype: DataType[T], access_mode: AttrMode, handler: Any = None
     ) -> None:
@@ -55,6 +73,8 @@ def access_mode(self) -> AttrMode:
 
 
 class AttrR(Attribute[T]):
+    """A read-only `Attribute`."""
+
     def __init__(
         self,
         datatype: DataType[T],
@@ -84,6 +104,8 @@ def updater(self) -> Updater | None:
 
 
 class AttrW(Attribute[T]):
+    """A write-only `Attribute`."""
+
     def __init__(
         self,
         datatype: DataType[T],
@@ -120,6 +142,8 @@ def sender(self) -> Sender | None:
 
 
 class AttrRW(AttrW[T], AttrR[T]):
+    """A read-write `Attribute`."""
+
     def __init__(
         self,
         datatype: DataType[T],

src/fastcs/controller.py

@@ -23,6 +23,12 @@ def _bind_attrs(self) -> None:
 
 
 class Controller(BaseController):
+    """Top-level controller for a device.
+
+    This is the primary class for implementing device support in FastCS. Instances of
+    this class can be loaded into a backend to expose its Attributes.
+    """
+
     def __init__(self) -> None:
         super().__init__()
         self.__sub_controllers: list[SubController] = []
@@ -38,5 +44,11 @@ def get_sub_controllers(self) -> list[SubController]:
 
 
 class SubController(BaseController):
+    """A subordinate to a `Controller` for managing a subset of a device.
+
+    An instance of this class can be registered with a parent `Controller` to include it
+    as part of a larger device.
+    """
+
     def __init__(self, path: str) -> None:
         super().__init__(path)

src/fastcs/datatypes.py

@@ -12,6 +12,8 @@
 
 
 class DataType(Generic[T]):
+    """Generic datatype mapping to a python builtin type, with additional metadata."""
+
     @property
     @abstractmethod
     def dtype(self) -> type[T]:  # Using property due to lack of Generic ClassVars
@@ -20,13 +22,17 @@ def dtype(self) -> type[T]:  # Using property due to lack of Generic ClassVars
 
 @dataclass(frozen=True)
 class Int(DataType[int]):
+    """DataType mapping to builtin `int`."""
+
     @property
     def dtype(self) -> type[int]:
         return int
 
 
 @dataclass(frozen=True)
 class Float(DataType[float]):
+    """DataType mapping to builtin `float`."""
+
     prec: int = 2
 
     @property
@@ -36,6 +42,8 @@ def dtype(self) -> type[float]:
 
 @dataclass(frozen=True)
 class Bool(DataType[bool]):
+    """DataType mapping to builtin `bool`."""
+
     znam: str = "OFF"
     onam: str = "ON"
 
@@ -46,6 +54,8 @@ def dtype(self) -> type[bool]:
 
 @dataclass(frozen=True)
 class String(DataType[str]):
+    """DataType mapping to builtin `str`."""
+
     @property
     def dtype(self) -> type[str]:
         return str