Add doc to Option on pattern matches

Author: ashawley

library/src/scala/Option.scala

@@ -135,14 +135,38 @@ sealed abstract class Option[+A] extends Product with Serializable {
  self =>
 
  /** Returns true if the option is $none, false otherwise.
+ *
+ * This is equivalent to:
+ * {{{
+ * option match {
+ * case Some(_) => false
+ * case None => true
+ * }
+ * }}}
  */
  def isEmpty: Boolean
 
  /** Returns true if the option is an instance of $some, false otherwise.
+ *
+ * This is equivalent to:
+ * {{{
+ * option match {
+ * case Some(_) => true
+ * case None => false
+ * }
+ * }}}
  */
  def isDefined: Boolean = !isEmpty
 
  /** Returns the option's value.
+ *
+ * This is equivalent to:
+ * {{{
+ * option match {
+ * case Some(x) => x
+ * case None => throw new Exception
+ * }
+ * }}}
  * @note The option must be nonempty.
  * @throws java.util.NoSuchElementException if the option is empty.
  */
@@ -151,15 +175,32 @@ sealed abstract class Option[+A] extends Product with Serializable {
  /** Returns the option's value if the option is nonempty, otherwise
  * return the result of evaluating `default`.
  *
+ * This is equivalent to:
+ * {{{
+ * option match {
+ * case Some(x) => x
+ * case None => default
+ * }
+ * }}}
+ *
  * @param default the default expression.
  */
  @inline final def getOrElse[B >: A](default: => B): B =
  if (isEmpty) default else this.get
 
  /** Returns the option's value if it is nonempty,
  * or `null` if it is empty.
+ *
  * Although the use of null is discouraged, code written to use
  * $option must often interface with code that expects and returns nulls.
+ *
+ * This is equivalent to:
+ * {{{
+ * option match {
+ * case Some(x) => x
+ * case None => null
+ * }
+ * }}}
  * @example {{{
  * val initialText: Option[String] = getInitialText
  * val textField = new JComponent(initialText.orNull,20)
@@ -171,6 +212,13 @@ sealed abstract class Option[+A] extends Product with Serializable {
  * value if this $option is nonempty.
  * Otherwise return $none.
  *
+ * This is equivalent to:
+ * {{{
+ * option match {
+ * case Some(x) => Some(f(x))
+ * case None => None
+ * }
+ * }}}
  * @note This is similar to `flatMap` except here,
  * $f does not need to wrap its result in an $option.
  *
@@ -185,8 +233,17 @@ sealed abstract class Option[+A] extends Product with Serializable {
  * value if the $option is nonempty. Otherwise, evaluates
  * expression `ifEmpty`.
  *
- * @note This is equivalent to `$option map f getOrElse ifEmpty`.
- *
+ * This is equivalent to:
+ * {{{
+ * option match {
+ * case Some(x) => f(x)
+ * case None => ifEmpty
+ * }
+ * }}}
+ * This is also equivalent to:
+ * {{{
+ * option map f getOrElse ifEmpty
+ * }}}
  * @param ifEmpty the expression to evaluate if empty.
  * @param f the function to apply if nonempty.
  */
@@ -199,6 +256,13 @@ sealed abstract class Option[+A] extends Product with Serializable {
  * Slightly different from `map` in that $f is expected to
  * return an $option (which could be $none).
  *
+ * This is equivalent to:
+ * {{{
+ * option match {
+ * case Some(x) => f(x)
+ * case None => None
+ * }
+ * }}}
  * @param f the function to apply
  * @see map
  * @see foreach
@@ -212,6 +276,13 @@ sealed abstract class Option[+A] extends Product with Serializable {
  /** Returns this $option if it is nonempty '''and''' applying the predicate $p to
  * this $option's value returns true. Otherwise, return $none.
  *
+ * This is equivalent to:
+ * {{{
+ * option match {
+ * case Some(x) if p(x) => Some(x)
+ * case _ => None
+ * }
+ * }}}
  * @param p the predicate used for testing.
  */
  @inline final def filter(p: A => Boolean): Option[A] =
@@ -220,12 +291,27 @@ sealed abstract class Option[+A] extends Product with Serializable {
  /** Returns this $option if it is nonempty '''and''' applying the predicate $p to
  * this $option's value returns false. Otherwise, return $none.
  *
+ * This is equivalent to:
+ * {{{
+ * option match {
+ * case Some(x) if !p(x) => Some(x)
+ * case _ => None
+ * }
+ * }}}
  * @param p the predicate used for testing.
  */
  @inline final def filterNot(p: A => Boolean): Option[A] =
  if (isEmpty || !p(this.get)) this else None
 
  /** Returns false if the option is $none, true otherwise.
+ *
+ * This is equivalent to:
+ * {{{
+ * option match {
+ * case Some(_) => true
+ * case None => false
+ * }
+ * }}}
  * @note Implemented here to avoid the implicit conversion to Iterable.
  */
  final def nonEmpty = isDefined
@@ -248,6 +334,13 @@ sealed abstract class Option[+A] extends Product with Serializable {
 
  /** Tests whether the option contains a given value as an element.
  *
+ * This is equivalent to:
+ * {{{
+ * option match {
+ * case Some(x) => x == elem
+ * case None => false
+ * }
+ * }}}
  * @example {{{
  * // Returns true because Some instance contains string "something" which equals "something".
  * Some("something") contains "something"
@@ -270,6 +363,13 @@ sealed abstract class Option[+A] extends Product with Serializable {
  * $p returns true when applied to this $option's value.
  * Otherwise, returns false.
  *
+ * This is equivalent to:
+ * {{{
+ * option match {
+ * case Some(x) => p(x)
+ * case None => false
+ * }
+ * }}}
  * @param p the predicate to test
  */
  @inline final def exists(p: A => Boolean): Boolean =
@@ -278,13 +378,27 @@ sealed abstract class Option[+A] extends Product with Serializable {
  /** Returns true if this option is empty '''or''' the predicate
  * $p returns true when applied to this $option's value.
  *
+ * This is equivalent to:
+ * {{{
+ * option match {
+ * case Some(x) => p(x)
+ * case None => true
+ * }
+ * }}}
  * @param p the predicate to test
  */
  @inline final def forall(p: A => Boolean): Boolean = isEmpty || p(this.get)
 
  /** Apply the given procedure $f to the option's value,
  * if it is nonempty. Otherwise, do nothing.
  *
+ * This is equivalent to:
+ * {{{
+ * option match {
+ * case Some(x) => f(x)
+ * case None => ()
+ * }
+ * }}}
  * @param f the procedure to apply.
  * @see map
  * @see flatMap
@@ -319,6 +433,14 @@ sealed abstract class Option[+A] extends Product with Serializable {
 
  /** Returns this $option if it is nonempty,
  * otherwise return the result of evaluating `alternative`.
+ *
+ * This is equivalent to:
+ * {{{
+ * option match {
+ * case Some(x) => Some(x)
+ * case None => alternative
+ * }
+ * }}}
  * @param alternative the alternative expression.
  */
  @inline final def orElse[B >: A](alternative: => Option[B]): Option[B] =
@@ -332,6 +454,14 @@ sealed abstract class Option[+A] extends Product with Serializable {
 
  /** Returns a singleton list containing the $option's value
  * if it is nonempty, or the empty list if the $option is empty.
+ *
+ * This is equivalent to:
+ * {{{
+ * option match {
+ * case Some(x) => List(x)
+ * case None => Nil
+ * }
+ * }}}
  */
  def toList: List[A] =
  if (isEmpty) List() else new ::(this.get, Nil)
@@ -341,6 +471,13 @@ sealed abstract class Option[+A] extends Product with Serializable {
  * a [[scala.util.Right]] containing this $option's value if
  * this is nonempty.
  *
+ * This is equivalent to:
+ * {{{
+ * option match {
+ * case Some(x) => Right(x)
+ * case None => Left(left)
+ * }
+ * }}}
  * @param left the expression to evaluate and return if this is empty
  * @see toLeft
  */
@@ -352,6 +489,13 @@ sealed abstract class Option[+A] extends Product with Serializable {
  * a [[scala.util.Left]] containing this $option's value
  * if this $option is nonempty.
  *
+ * This is equivalent to:
+ * {{{
+ * option match {
+ * case Some(x) => Left(x)
+ * case None => Right(right)
+ * }
+ * }}}
  * @param right the expression to evaluate and return if this is empty
  * @see toRight
  */