Fix docstrings for collect (#235)

Author: dbrattli

.pre-commit-config.yaml

@@ -14,5 +14,5 @@ repos:
         language: node
         pass_filenames: false
         types: [python]
-        additional_dependencies: ["[email protected].386"]
+        additional_dependencies: ["[email protected].391"]
     repo: local

expression/collections/block.py

@@ -113,6 +113,19 @@ def mapper(x: _TSource) -> Block[_TResult]:
         return self.collect(mapper)
 
     def collect(self, mapping: Callable[[_TSource], Block[_TResult]]) -> Block[_TResult]:
+        """Collect items from the list.
+
+        Applies the given function to each element of the list and concatenates all the
+        resulting sequences. This function is known as `bind` or `flat_map` in other
+        languages.
+
+        Args:
+            mapping: The function to generate sequences from the elements.
+
+        Returns:
+            A list comprising the concatenated values from the mapping
+            function.
+        """
         mapped = builtins.map(mapping, self._value)
         xs = (y for x in mapped for y in x)
         return Block(xs)
@@ -556,19 +569,19 @@ def choose(source: Block[_TSource], chooser: Callable[[_TSource], Option[_TResul
 
 @curry_flip(1)
 def collect(source: Block[_TSource], mapping: Callable[[_TSource], Block[_TResult]]) -> Block[_TResult]:
-    """Collect block.
+    """Collect items from the list.
 
-    For each element of the list, applies the given function.
-    Concatenates all the results and return the combined list.
+    Applies the given function to each element of the list and
+    concatenates all the resulting sequences. This function is known as
+    `bind` or `flat_map` in other languages.
 
     Args:
         source: The input list (curried flipped).
-        mapping: The function to transform each input element into
-        a sublist to be concatenated.
+        mapping: The function to generate sequences from the elements.
 
     Returns:
-        A partially applied collect function that takes the source
-        list and returns the concatenation of the transformed sublists.
+        A sequence comprising the concatenated values from the mapping
+        function.
     """
     return source.collect(mapping)
 

expression/collections/seq.py

@@ -110,6 +110,19 @@ def choose(self, chooser: Callable[[_TSource], Option[_TResult]]) -> Seq[_TResul
         return Seq(xs)
 
     def collect(self, mapping: Callable[[_TSource], Seq[_TResult]]) -> Seq[_TResult]:
+        """Collect items from the sequence.
+
+        Applies the given function to each element of the list and
+        concatenates all the resulting sequences. This function is known
+        as `bind` or `flat_map` in other languages.
+
+        Args:
+            mapping: The function to generate sequences from the elements.
+
+        Returns:
+            A sequence comprising the concatenated values from the mapping
+            function.
+        """
         xs = pipe(self, collect(mapping))
         return Seq(xs)
 
@@ -429,6 +442,21 @@ def collect(
     source: Iterable[_TSource],
     mapping: Callable[[_TSource], Iterable[_TResult]],
 ) -> Iterable[_TResult]:
+    """Collect items from the sequence.
+
+    Applies the given function to each element of the list and
+    concatenates all the resulting sequences. This function is known as
+    `bind` or `flat_map` in other languages.
+
+    Args:
+        source: The input sequence to to collect from.
+        mapping: The function to generate sequences from the elements.
+
+    Returns:
+        A sequence comprising the concatenated values from the mapping
+        function.
+    """
+
     def gen() -> Iterator[_TResult]:
         for xs in source:
             yield from mapping(xs)

expression/core/builder.py

@@ -42,7 +42,7 @@ def delay(self, fn: Callable[[], _TOuter]) -> _TOuter:
         return fn()
 
     def run(self, xs: _TOuter) -> _TOuter:
-        """Default implementation assumes the result is already evalutated."""
+        """Default implementation assumes the result is already evaluated."""
         return xs
 
     def _send(