Merge pull request #2811 from bplommer/pure-comment

Expand scaladoc for `fs2.Pure`
typelevel · Feb 2, 2022 · cd28087 · cd28087
2 parents e385014 + 96358a7
commit cd28087
Showing 1 changed file with 6 additions and 1 deletion.
diff --git a/core/shared/src/main/scala/fs2/fs2.scala b/core/shared/src/main/scala/fs2/fs2.scala
@@ -36,7 +36,12 @@ package object fs2 {
 
   /** Indicates that a stream evaluates no effects.
     *
-    * A `Stream[Pure,O]` can be safely converted to a `Stream[F,O]` for all `F`.
+    * Because [[Stream]] is covariant, A `Stream[Pure,O]` is also an instance of `Stream[F,O]` for all `F`.
+    *
+    * This should not be confused with [[cats.Id]], which provides an alternative encoding of pure streams,
+    * namely `Stream[Id, O]`. The difference is that `Stream[Id, O]` achieves purity by using an effect type
+    * whose evaluation is a no-op, whereas `Stream[Pure, O]` achieves purity by using an effect type that
+    * has no instances and therefore cannot be instantiated in the first place.
     */
   type Pure[A] <: Nothing