This is one reason why scaladoc is not documentation. You know, reliability and all that important stuff.

scaladoc.md

1. Look at the scaladoc for Option#zip.

   (Option[A])([B]GenIterable[B] => Option[(A, B)]

2. Look at the Option.scala source.

   > grep zip | wc -l

   0

3. WTF?

4. Expand the arrow on the Option#zip scaladoc.

"This member is added by an implicit conversion from Option[A] to Iterable[A] performed by method option2Iterable in scala.Option. "

5. Well uh ... so er scaladoc invokes implicit functions at documentation time? YOLO I guess.

6. Look at the scaladoc for IterableLike#zip.

(IterableLike[A])([B]GenIterable[B] => Iterable[(A, B)])

7. So zip returns Iterable[(A, B)] but ummm Option#zip scaladoc says it returns Option[(A, B)]. Which is it?

scala> Some(7) zip Some('a') 
res0: Iterable[(Int, Char)] = List((7,a))

9. OK so it returns a List with an Iterable reference.

10. MAKES SENSE.