Add docstring and fix type hint

AKModel/models.py

@@ -23,7 +23,14 @@ class OptimizerTimeslot:
     idx: int
     constraints: set[str]
 
-    def merge(self, other: "OptimizerTimeslot") -> None:
+    def merge(self, other: "OptimizerTimeslot") -> "OptimizerTimeslot":
+        """Merge with other OptimizerTimeslot.
+
+        Creates a new OptimizerTimeslot object.
+        Its availability is constructed by merging the availabilities of self and other,
+        its constraints by taking the union of both constraint sets.
+        As an index, the index of self is used.
+        """
         avail = self.avail.merge_with(other.avail)
         constraints = self.constraints.union(other.constraints)
         # we simply use the index of result[-1]
@@ -304,6 +311,18 @@ class Event(models.Model):
     def merge_blocks(
         self, blocks: Iterable[TimeslotBlock]
     ) -> Iterable[TimeslotBlock]:
+        """Merge iterable of blocks together.
+
+        The timeslots of all blocks are grouped into maximal blocks.
+        Timeslots with the same start and end are identified with each other
+        and merged (cf `OptimizerTimeslot.merge`).
+        Throws a ValueError if any timeslots are overlapping but do not
+        share the same start and end, i.e. partial overlap is not allowed.
+
+        :param blocks: iterable of blocks to merge.
+        :return: iterable of merged blocks.
+        :rtype: iterable over lists of OptimizerTimeslot objects
+        """
         if not blocks:
             return []
 
@@ -481,6 +500,13 @@ class AKCategory(models.Model):
 
     @staticmethod
     def create_category_constraints(categories: Iterable["AKCategory"]) -> set[str]:
+        """Create a set of constraint strings from an AKCategory iterable.
+
+        :param categories: The iterable of categories to derive the constraint strings from.
+        :return: A set of category constraint strings, i.e. strings of the form
+            'availability-cat-<cat.name>'.
+        :rtype: set of strings.
+        """
         return {
             f"availability-cat-{cat.name}"
             for cat in categories