refactor(Stream/raceAll): improve documentation

.changeset/stream-race-all.md

@@ -2,4 +2,27 @@
 "effect": minor
 ---
 
-feat(Stream): raceAll
+feat(Stream): implement "raceAll" operator, which returns a stream that mirrors the first source stream to emit an item.
+
+
+```ts
+import { Stream, Schedule, Console, Effect } from "effect" 
+
+const stream = Stream.raceAll(
+ Stream.fromSchedule(Schedule.spaced('1 millis')),
+ Stream.fromSchedule(Schedule.spaced('2 millis')),
+ Stream.fromSchedule(Schedule.spaced('4 millis'))
+).pipe(
+ Stream.take(6), 
+ Stream.tap(Console.log)
+)
+
+Effect.runPromise(Stream.runDrain(stream))
+// Output only from the first stream, the rest streams are interrupted
+// 0 
+// 1 
+// 2 
+// 3 
+// 4 
+// 5
+```

packages/effect/src/Stream.ts

@@ -2695,7 +2695,11 @@ export const provideSomeLayer: {
 } = internal.provideSomeLayer
 
 /**
- * Returns a stream that mirrors the first source stream to emit an item.
+ * Returns a stream that mirrors the first upstream to emit an item.
+ * As soon as one of the upstream emits a first value, all the others are being interrupted.
+ * The resulting stream will forward all items from the "winning" source stream.
+ * Any upstream failures will cause the returned stream to fail.
+ *
  * @example
  * import { Stream, Schedule, Console, Effect } from "effect"
  *