Document model items

src/backend/models/model_item.py

@@ -4,6 +4,19 @@ from ..utils import serialize_value_for_qml
 
 
 class ModelItem:
+    """Base class for items stored inside a `Model`.
+
+    This class must be subclassed and not used directly.
+    All subclasses must be dataclasses.
+
+    Subclasses are also expected to implement `__lt__()`,
+    to provide support for comparisons with the `<`, `>`, `<=`, `=>` operators
+    and thus allow a `Model` to sort its `ModelItem`s.
+
+    They may also implement a `filter_string` property, that will be used
+    for filtering from the UI.
+    """
+
     def __new__(cls, *_args, **_kwargs) -> "ModelItem":
         from .model import Model
         cls.parent_model: Optional[Model] = None
@@ -11,6 +24,8 @@ class ModelItem:
 
 
     def __setattr__(self, name: str, value) -> None:
+        """If this item is in a `Model`, alert it of attribute changes."""
+
         super().__setattr__(name, value)
 
         if name != "parent_model" and self.parent_model is not None:
@@ -24,6 +39,8 @@ class ModelItem:
 
     @property
     def serialized(self) -> Dict[str, Any]:
+        """Return this item as a dict ready to be passed to QML."""
+
         return {
             name: serialize_value_for_qml(getattr(self, name))
             for name in dir(self)