improve docstrings

README.md

@@ -125,7 +125,7 @@ assert list(pokemon_names) == ['bulbasaur', 'ivysaur', 'venusaur']
 
 > Preserves the upstream order by default (FIFO), but you can set `ordered=False` for *First Done First Out*.
 
-> `concurrency` is also the size of the buffer containing not-yet-yielded results. **If the buffer is full, the iteration over the upstream is stopped** until some results are yielded out of the buffer.
+> `concurrency` is also the size of the buffer containing not-yet-yielded results. **If the buffer is full, the iteration over the upstream is stopped** until a result is yielded from the buffer.
 
 
 ### process-based concurrency

streamable/stream.py

@@ -59,7 +59,7 @@ def __init__(self, source: Union[Iterable[T], Callable[[], Iterable[T]]]) -> Non
         A `Stream[T]` decorates an `Iterable[T]` with a **fluent interface** enabling the chaining of lazy operations.
 
         Args:
-            source (Union[Iterable[T], Callable[[], Iterable[T]]]): The iterable to decorate. Can be provided via a function that will be called each time an iteration is started over the stream.
+            source (Union[Iterable[T], Callable[[], Iterable[T]]]): The iterable to decorate. Can be specified via a function that will be called each time an iteration is started over the stream.
         """
         self._source = source
         self._upstream: "Optional[Stream]" = None
@@ -257,7 +257,7 @@ def foreach(
 
         Args:
             effect (Callable[[T], Any]): The function to be applied to each element as a side effect.
-            concurrency (int): Represents both the number of threads used to concurrently apply the `effect` and the size of the buffer containing not-yet-yielded elements. If the buffer is full, the iteration over the upstream is stopped until some elements are yielded out of the buffer. (default is 1, meaning no multithreading).
+            concurrency (int): Represents both the number of threads used to concurrently apply the `effect` and the size of the buffer containing not-yet-yielded elements. If the buffer is full, the iteration over the upstream is stopped until an element is yielded from the buffer. (default is 1, meaning no multithreading).
             ordered (bool): If `concurrency` > 1, whether to preserve the order of upstream elements or to yield them as soon as they are processed (default preserves order).
             via ("thread" or "process"): If `concurrency` > 1, whether to apply `transformation` using processes or threads (default via threads).
         Returns:
@@ -279,7 +279,7 @@ def aforeach(
 
         Args:
             effect (Callable[[T], Any]): The asynchronous function to be applied to each element as a side effect.
-            concurrency (int): Represents both the number of async tasks concurrently applying the `effect` and the size of the buffer containing not-yet-yielded elements. If the buffer is full, the iteration over the upstream is stopped until some elements are yielded out of the buffer.
+            concurrency (int): Represents both the number of async tasks concurrently applying the `effect` and the size of the buffer containing not-yet-yielded elements. If the buffer is full, the iteration over the upstream is stopped until an element is yielded from the buffer.
             ordered (bool): If `concurrency` > 1, whether to preserve the order of upstream elements or to yield them as soon as they are processed (default preserves order).
         Returns:
             Stream[T]: A stream of upstream elements, unchanged.
@@ -324,7 +324,7 @@ def map(
 
         Args:
             transformation (Callable[[T], R]): The function to be applied to each element.
-            concurrency (int): Represents both the number of threads used to concurrently apply `transformation` and the size of the buffer containing not-yet-yielded results. If the buffer is full, the iteration over the upstream is stopped until some results are yielded out of the buffer. (default is 1, meaning no multithreading).
+            concurrency (int): Represents both the number of threads used to concurrently apply `transformation` and the size of the buffer containing not-yet-yielded results. If the buffer is full, the iteration over the upstream is stopped until a result is yielded from the buffer. (default is 1, meaning no multithreading).
             ordered (bool): If `concurrency` > 1, whether to preserve the order of upstream elements or to yield them as soon as they are processed (default preserves order).
             via ("thread" or "process"): If `concurrency` > 1, whether to apply `transformation` using processes or threads (default via threads).
         Returns:
@@ -345,7 +345,7 @@ def amap(
 
         Args:
             transformation (Callable[[T], Coroutine[Any, Any, U]]): The asynchronous function to be applied to each element.
-            concurrency (int): Represents both the number of async tasks concurrently applying `transformation` and the size of the buffer containing not-yet-yielded results. If the buffer is full, the iteration over the upstream is stopped until some results are yielded out of the buffer.
+            concurrency (int): Represents both the number of async tasks concurrently applying `transformation` and the size of the buffer containing not-yet-yielded results. If the buffer is full, the iteration over the upstream is stopped until a result is yielded from the buffer.
             ordered (bool): If `concurrency` > 1, whether to preserve the order of upstream elements or to yield them as soon as they are processed (default preserves order).
         Returns:
             Stream[R]: A stream of transformed elements.
@@ -393,7 +393,7 @@ def throttle(
             interval (datetime.timedelta, optional): Minimum span of time between yields (no limit by default).
 
         Returns:
-            Stream[T]: A stream yielding upstream elements under the provided rate constraints.
+            Stream[T]: A stream yielding upstream elements according to the specified rate constraints.
         """
         validate_throttle_per_period("per_second", per_second)
         validate_throttle_per_period("per_minute", per_minute)

tests/test_stream.py

@@ -1207,7 +1207,7 @@ def f(i):
         self.assertListEqual(
             list(stream.catch()),
             list(map(f, safe_src)),
-            msg="If the predicate is not provided, then all exceptions should be catched.",
+            msg="If the predicate is not specified, then all exceptions should be catched.",
         )
 
         with self.assertRaises(