improve Die.keep() docstring

src/icepool/population/die.py

@@ -853,7 +853,41 @@ def keep(self,
              rolls: int | Sequence[int],
              index: slice | Sequence[int | EllipsisType] | int | None = None,
              /) -> 'Die':
-        """Selects elements after drawing and sorting."""
+        """Selects elements after drawing and sorting and sums them.
+
+        Args:
+            rolls: The number of dice to roll.
+            index: One of the following:
+            * An `int`. This will count only the roll at the specified index.
+            In this case, the result is a `Die` rather than a generator.
+            * A `slice`. The selected dice are counted once each.
+            * A sequence of `int`s with length equal to `rolls`.
+                Each roll is counted that many times, which could be multiple or
+                negative times.
+
+                Up to one `...` (`Ellipsis`) may be used. If no `...` is used,
+                the `rolls` argument may be omitted.
+
+                `...` will be replaced with a number of zero counts in order
+                to make up any missing elements compared to `rolls`.
+                This number may be "negative" if more `int`s are provided than
+                `rolls`. Specifically:
+
+                * If `index` is shorter than `rolls`, `...`
+                    acts as enough zero counts to make up the difference.
+                    E.g. `(1, ..., 1)` on five dice would act as
+                    `(1, 0, 0, 0, 1)`.
+                * If `index` has length equal to `rolls`, `...` has no effect.
+                    E.g. `(1, ..., 1)` on two dice would act as `(1, 1)`.
+                * If `index` is longer than `rolls` and `...` is on one side,
+                    elements will be dropped from `index` on the side with `...`.
+                    E.g. `(..., 1, 2, 3)` on two dice would act as `(2, 3)`.
+                * If `index` is longer than `rolls` and `...`
+                    is in the middle, the counts will be as the sum of two
+                    one-sided `...`.
+                    E.g. `(-1, ..., 1)` acts like `(-1, ...)` plus `(..., 1)`.
+                    If `rolls` was 1 this would have the -1 and 1 cancel each other out.
+        """
         if isinstance(rolls, int):
             if index is None:
                 raise ValueError(