Merge pull request scala#4089 from gourlaysama/wip/t6626-scaladoc-throws-links

SI-6626 make @throws tags create links to exceptions

Author: Vlad Ureche

src/library/scala/Option.scala

@@ -107,7 +107,7 @@ sealed abstract class Option[+A] extends Product with Serializable {
 
   /** Returns the option's value.
    *  @note The option must be nonEmpty.
-   *  @throws Predef.NoSuchElementException if the option is empty.
+   *  @throws java.util.NoSuchElementException if the option is empty.
    */
   def get: A
 

src/library/scala/Predef.scala

@@ -220,7 +220,7 @@ object Predef extends LowPriorityImplicits with DeprecatedPredef {
   }
 
   /** `???` can be used for marking methods that remain to be implemented.
-   *  @throws  A `NotImplementedError`
+   *  @throws NotImplementedError
    */
   def ??? : Nothing = throw new NotImplementedError
 

src/library/scala/Product.scala

@@ -22,7 +22,7 @@ trait Product extends Any with Equals {
    *  product `A(x,,1,,, ..., x,,k,,)`, returns `x,,(n+1),,` where `0 < n < k`.
    *
    *  @param    n   the index of the element to return
-   *  @throws       `IndexOutOfBoundsException`
+   *  @throws       IndexOutOfBoundsException
    *  @return       the element `n` elements after the first element
    */
   def productElement(n: Int): Any

src/library/scala/StringContext.scala

@@ -58,7 +58,7 @@ case class StringContext(parts: String*) {
   /** Checks that the length of the given argument `args` is one less than the number
    *  of `parts` supplied to the enclosing `StringContext`.
    *  @param `args` The arguments to be checked.
-   *  @throws An `IllegalArgumentException` if this is not the case.
+   *  @throws IllegalArgumentException  if this is not the case.
    */
   def checkLengths(args: Seq[Any]): Unit =
     if (parts.length != args.length + 1)
@@ -85,10 +85,11 @@ case class StringContext(parts: String*) {
    *  will print the string `1 + 1 = 2`.
    *
    *  @param `args` The arguments to be inserted into the resulting string.
-   *  @throws An `IllegalArgumentException`
+   *  @throws IllegalArgumentException
    *          if the number of `parts` in the enclosing `StringContext` does not exceed
    *          the number of arguments `arg` by exactly 1.
-   *  @throws A `StringContext.InvalidEscapeException` if a `parts` string contains a backslash (`\`) character
+   *  @throws StringContext.InvalidEscapeException
+   *          if a `parts` string contains a backslash (`\`) character
    *          that does not start a valid escape sequence.
    */
   def s(args: Any*): String = standardInterpolator(treatEscapes, args)
@@ -109,7 +110,7 @@ case class StringContext(parts: String*) {
    *  }}}
    *
    *  @param `args` The arguments to be inserted into the resulting string.
-   *  @throws An `IllegalArgumentException`
+   *  @throws IllegalArgumentException
    *          if the number of `parts` in the enclosing `StringContext` does not exceed
    *          the number of arguments `arg` by exactly 1.
    */
@@ -144,10 +145,11 @@ case class StringContext(parts: String*) {
    *  }}}
    *
    *  @param `args` The arguments to be inserted into the resulting string.
-   *  @throws An `IllegalArgumentException`
+   *  @throws IllegalArgumentException
    *          if the number of `parts` in the enclosing `StringContext` does not exceed
    *          the number of arguments `arg` by exactly 1.
-   *  @throws A `StringContext.InvalidEscapeException` if a `parts` string contains a backslash (`\`) character
+   *  @throws StringContext.InvalidEscapeException
+   *          if a `parts` string contains a backslash (`\`) character
    *          that does not start a valid escape sequence.
    *
    *  Note: The `f` method works by assembling a format string from all the `parts` strings and using

src/library/scala/collection/GenSeqLike.scala

@@ -47,7 +47,7 @@ trait GenSeqLike[+A, +Repr] extends Any with GenIterableLike[A, Repr] with Equal
    *
    *  @param  idx  The index to select.
    *  @return the element of this $coll at index `idx`, where `0` indicates the first element.
-   *  @throws `IndexOutOfBoundsException` if `idx` does not satisfy `0 <= idx < length`.
+   *  @throws IndexOutOfBoundsException if `idx` does not satisfy `0 <= idx < length`.
    */
   def apply(idx: Int): A
 

src/library/scala/collection/GenTraversableLike.scala

@@ -63,7 +63,7 @@ trait GenTraversableLike[+A, +Repr] extends Any with GenTraversableOnce[A] with
   /** Selects the first element of this $coll.
    *  $orderDependent
    *  @return  the first element of this $coll.
-   *  @throws `NoSuchElementException` if the $coll is empty.
+   *  @throws NoSuchElementException if the $coll is empty.
    */
   def head: A
 
@@ -83,7 +83,7 @@ trait GenTraversableLike[+A, +Repr] extends Any with GenTraversableOnce[A] with
    *  $orderDependent
    *  @return  a $coll consisting of all elements of this $coll
    *           except the first one.
-   *  @throws `UnsupportedOperationException` if the $coll is empty.
+   *  @throws UnsupportedOperationException if the $coll is empty.
    */
   def tail: Repr
 
@@ -105,7 +105,7 @@ trait GenTraversableLike[+A, +Repr] extends Any with GenTraversableOnce[A] with
    *  $orderDependent
    *  @return  a $coll consisting of all elements of this $coll
    *           except the last one.
-   *  @throws `UnsupportedOperationException` if the $coll is empty.
+   *  @throws UnsupportedOperationException if the $coll is empty.
    */
   def init: Repr
 

src/library/scala/collection/GenTraversableOnce.scala

@@ -268,7 +268,7 @@ trait GenTraversableOnce[+A] extends Any {
    *             op(x_1, op(x_2, ..., op(x_{n-1}, x_n)...))
    *           }}}
    *           where `x,,1,,, ..., x,,n,,` are the elements of this $coll.
-   *  @throws `UnsupportedOperationException` if this $coll is empty.
+   *  @throws UnsupportedOperationException if this $coll is empty.
    */
   def reduceRight[B >: A](op: (A, B) => B): B
 

src/library/scala/collection/LinearSeqOptimized.scala

@@ -44,7 +44,7 @@ trait LinearSeqOptimized[+A, +Repr <: LinearSeqOptimized[A, Repr]] extends Linea
 
   /** Selects an element by its index in the $coll.
    *  Note: the execution of `apply` may take time proportial to the index value.
-   *  @throws `IndexOutOfBoundsException` if `idx` does not satisfy `0 <= idx < length`.
+   *  @throws IndexOutOfBoundsException if `idx` does not satisfy `0 <= idx < length`.
    */
   def apply(n: Int): A = {
     val rest = drop(n)

src/library/scala/collection/MapLike.scala

@@ -222,7 +222,7 @@ self =>
    *  but it might be overridden in subclasses.
    *
    *  @param key the given key value for which a binding is missing.
-   *  @throws `NoSuchElementException`
+   *  @throws NoSuchElementException
    */
   def default(key: A): B =
     throw new NoSuchElementException("key not found: " + key)

src/library/scala/collection/TraversableLike.scala

@@ -419,7 +419,7 @@ trait TraversableLike[+A, +Repr] extends Any
   /** Selects the first element of this $coll.
    *  $orderDependent
    *  @return  the first element of this $coll.
-   *  @throws `NoSuchElementException` if the $coll is empty.
+   *  @throws NoSuchElementException if the $coll is empty.
    */
   def head: A = {
     var result: () => A = () => throw new NoSuchElementException
@@ -473,7 +473,7 @@ trait TraversableLike[+A, +Repr] extends Any
    *  $orderDependent
    *  @return  a $coll consisting of all elements of this $coll
    *           except the last one.
-   *  @throws `UnsupportedOperationException` if the $coll is empty.
+   *  @throws UnsupportedOperationException if the $coll is empty.
    */
   def init: Repr = {
     if (isEmpty) throw new UnsupportedOperationException("empty.init")

src/library/scala/collection/TraversableOnce.scala

@@ -159,7 +159,7 @@ trait TraversableOnce[+A] extends Any with GenTraversableOnce[A] {
    *             op( op( ... op(x_1, x_2) ..., x_{n-1}), x_n)
    *           }}}
    *           where `x,,1,,, ..., x,,n,,` are the elements of this $coll.
-   *  @throws `UnsupportedOperationException` if this $coll is empty.   */
+   *  @throws UnsupportedOperationException if this $coll is empty.   */
   def reduceLeft[B >: A](op: (B, A) => B): B = {
     if (isEmpty)
       throw new UnsupportedOperationException("empty.reduceLeft")

src/library/scala/collection/generic/GenericTraversableTemplate.scala

@@ -45,7 +45,7 @@ trait GenericTraversableTemplate[+A, +CC[X] <: GenTraversable[X]] extends HasNew
   /** Selects the first element of this $coll.
    *
    *  @return  the first element of this $coll.
-   *  @throws `NoSuchElementException` if the $coll is empty.
+   *  @throws NoSuchElementException if the $coll is empty.
    */
   def head: A
 
@@ -202,7 +202,7 @@ trait GenericTraversableTemplate[+A, +CC[X] <: GenTraversable[X]] extends HasNew
    *          element type of this $coll is a `Traversable`.
    *  @return a two-dimensional $coll of ${coll}s which has as ''n''th row
    *          the ''n''th column of this $coll.
-   *  @throws `IllegalArgumentException` if all collections in this $coll
+   *  @throws IllegalArgumentException if all collections in this $coll
    *          are not of the same size.
    */
   @migration("`transpose` throws an `IllegalArgumentException` if collections are not uniformly sized.", "2.9.0")

src/library/scala/collection/immutable/ListSet.scala

@@ -111,7 +111,7 @@ class ListSet[A] extends AbstractSet[A]
 
   /** Creates a new iterator over all elements contained in this set.
    *
-   *  @throws Predef.NoSuchElementException
+   *  @throws java.util.NoSuchElementException
    *  @return the new iterator
    */
   def iterator: Iterator[A] = new AbstractIterator[A] {
@@ -127,12 +127,12 @@ class ListSet[A] extends AbstractSet[A]
   }
 
   /**
-   *  @throws Predef.NoSuchElementException
+   *  @throws java.util.NoSuchElementException
    */
   override def head: A = throw new NoSuchElementException("Set has no elements")
 
   /**
-   *  @throws Predef.NoSuchElementException
+   *  @throws java.util.NoSuchElementException
    */
   override def tail: ListSet[A] = throw new NoSuchElementException("Next of an empty set")
 

src/library/scala/collection/immutable/Queue.scala

@@ -53,7 +53,7 @@ class Queue[+A] protected(protected val in: List[A], protected val out: List[A])
    *
    *  @param  n index of the element to return
    *  @return   the element at position `n` in this queue.
-   *  @throws Predef.NoSuchElementException if the queue is too short.
+   *  @throws java.util.NoSuchElementException if the queue is too short.
    */
   override def apply(n: Int): A = {
     val len = out.length
@@ -120,7 +120,7 @@ class Queue[+A] protected(protected val in: List[A], protected val out: List[A])
   /** Returns a tuple with the first element in the queue,
    *  and a new queue with this element removed.
    *
-   *  @throws Predef.NoSuchElementException
+   *  @throws java.util.NoSuchElementException
    *  @return the first element of the queue.
    */
   def dequeue: (A, Queue[A]) = out match {
@@ -139,7 +139,7 @@ class Queue[+A] protected(protected val in: List[A], protected val out: List[A])
   /** Returns the first element in the queue, or throws an error if there
    *  is no element contained in the queue.
    *
-   *  @throws Predef.NoSuchElementException
+   *  @throws java.util.NoSuchElementException
    *  @return the first element.
    */
   def front: A = head

src/library/scala/collection/immutable/Stack.scala

@@ -95,7 +95,7 @@ class Stack[+A] protected (protected val elems: List[A])
   /** Returns the top element of the stack. An error is signaled if
    *  there is no element on the stack.
    *
-   *  @throws Predef.NoSuchElementException
+   *  @throws java.util.NoSuchElementException
    *  @return the top element.
    */
   def top: A =
@@ -105,7 +105,7 @@ class Stack[+A] protected (protected val elems: List[A])
   /** Removes the top element from the stack.
    *  Note: should return `(A, Stack[A])` as for queues (mics)
    *
-   *  @throws Predef.NoSuchElementException
+   *  @throws java.util.NoSuchElementException
    *  @return the new stack without the former top element.
    */
   def pop: Stack[A] =

src/library/scala/collection/immutable/Stream.scala

@@ -225,7 +225,7 @@ self =>
    * }}}
    *
    *  @return The first element of the `Stream`.
-   *  @throws Predef.NoSuchElementException if the stream is empty.
+   *  @throws java.util.NoSuchElementException if the stream is empty.
    */
   def head: A
 
@@ -236,7 +236,7 @@ self =>
    *  returns the lazy result.
    *
    *  @return The tail of the `Stream`.
-   *  @throws Predef.UnsupportedOperationException if the stream is empty.
+   *  @throws UnsupportedOperationException if the stream is empty.
    */
   def tail: Stream[A]
 
@@ -876,7 +876,7 @@ self =>
    * @return A new `Stream` containing everything but the last element.  If your
    * `Stream` represents an infinite series, this method will not return.
    *
-   *  @throws `Predef.UnsupportedOperationException` if the stream is empty.
+   *  @throws UnsupportedOperationException if the stream is empty.
    */
   override def init: Stream[A] =
     if (isEmpty) super.init

src/library/scala/collection/immutable/StringLike.scala

@@ -230,31 +230,31 @@ self =>
   def r(groupNames: String*): Regex = new Regex(toString, groupNames: _*)
 
   /**
-   * @throws `java.lang.IllegalArgumentException` - If the string does not contain a parsable boolean.
+   * @throws java.lang.IllegalArgumentException - If the string does not contain a parsable boolean.
    */
   def toBoolean: Boolean = parseBoolean(toString)
   /**
-   * @throws `java.lang.NumberFormatException` - If the string does not contain a parsable byte.
+   * @throws java.lang.NumberFormatException - If the string does not contain a parsable byte.
    */
   def toByte: Byte       = java.lang.Byte.parseByte(toString)
   /**
-   * @throws `java.lang.NumberFormatException` - If the string does not contain a parsable short.
+   * @throws java.lang.NumberFormatException - If the string does not contain a parsable short.
    */
   def toShort: Short     = java.lang.Short.parseShort(toString)
   /**
-   * @throws `java.lang.NumberFormatException`  - If the string does not contain a parsable int.
+   * @throws java.lang.NumberFormatException  - If the string does not contain a parsable int.
    */
   def toInt: Int         = java.lang.Integer.parseInt(toString)
   /**
-   * @throws `java.lang.NumberFormatException`  - If the string does not contain a parsable long.
+   * @throws java.lang.NumberFormatException  - If the string does not contain a parsable long.
    */
   def toLong: Long       = java.lang.Long.parseLong(toString)
   /**
-   * @throws `java.lang.NumberFormatException` - If the string does not contain a parsable float.
+   * @throws java.lang.NumberFormatException - If the string does not contain a parsable float.
    */
   def toFloat: Float     = java.lang.Float.parseFloat(toString)
   /**
-   * @throws `java.lang.NumberFormatException` - If the string does not contain a parsable double.
+   * @throws java.lang.NumberFormatException - If the string does not contain a parsable double.
    */
   def toDouble: Double   = java.lang.Double.parseDouble(toString)
 
@@ -287,7 +287,7 @@ self =>
    *    understands.
    *
    *  @param args the arguments used to instantiating the pattern.
-   *  @throws `java.lang.IllegalArgumentException`
+   *  @throws java.lang.IllegalArgumentException
    */
   def format(args : Any*): String =
     java.lang.String.format(toString, args map unwrapArg: _*)
@@ -304,7 +304,7 @@ self =>
    *
    *  @param l    an instance of `java.util.Locale`
    *  @param args the arguments used to instantiating the pattern.
-   *  @throws `java.lang.IllegalArgumentException`
+   *  @throws java.lang.IllegalArgumentException
    */
   def formatLocal(l: java.util.Locale, args: Any*): String =
     java.lang.String.format(l, toString, args map unwrapArg: _*)

src/library/scala/collection/mutable/ArrayBuffer.scala

@@ -133,7 +133,7 @@ class ArrayBuffer[A](override protected val initialSize: Int)
    *
    *  @param n     the index where a new element will be inserted.
    *  @param seq   the traversable object providing all elements to insert.
-   *  @throws Predef.IndexOutOfBoundsException if `n` is out of bounds.
+   *  @throws IndexOutOfBoundsException if `n` is out of bounds.
    */
   def insertAll(n: Int, seq: Traversable[A]) {
     if (n < 0 || n > size0) throw new IndexOutOfBoundsException(n.toString)
@@ -150,7 +150,7 @@ class ArrayBuffer[A](override protected val initialSize: Int)
    *
    *  @param n       the index which refers to the first element to delete.
    *  @param count   the number of elements to delete
-   *  @throws Predef.IndexOutOfBoundsException if `n` is out of bounds.
+   *  @throws IndexOutOfBoundsException if `n` is out of bounds.
    */
   override def remove(n: Int, count: Int) {
     require(count >= 0, "removing negative number of elements")

src/library/scala/collection/mutable/ListBuffer.scala

@@ -132,7 +132,7 @@ final class ListBuffer[A]
    *
    *  @param n  the index of the element to replace.
    *  @param x  the new element.
-   *  @throws Predef.IndexOutOfBoundsException if `n` is out of bounds.
+   *  @throws IndexOutOfBoundsException if `n` is out of bounds.
    */
   def update(n: Int, x: A) {
     // We check the bounds early, so that we don't trigger copying.
@@ -217,7 +217,7 @@ final class ListBuffer[A]
    *
    *  @param  n     the index where a new element will be inserted.
    *  @param  seq   the iterable object providing all elements to insert.
-   *  @throws Predef.IndexOutOfBoundsException if `n` is out of bounds.
+   *  @throws IndexOutOfBoundsException if `n` is out of bounds.
    */
   def insertAll(n: Int, seq: Traversable[A]) {
     // We check the bounds early, so that we don't trigger copying.
@@ -330,7 +330,7 @@ final class ListBuffer[A]
    *  @param  n  the index which refers to the element to delete.
    *  @return n  the element that was formerly at position `n`.
    *  @note      an element must exists at position `n`.
-   *  @throws Predef.IndexOutOfBoundsException if `n` is out of bounds.
+   *  @throws IndexOutOfBoundsException if `n` is out of bounds.
    */
   def remove(n: Int): A = {
     if (n < 0 || n >= len) throw new IndexOutOfBoundsException(n.toString())

src/library/scala/collection/mutable/PriorityQueue.scala

@@ -126,7 +126,7 @@ class PriorityQueue[A](implicit val ord: Ordering[A])
   /** Returns the element with the highest priority in the queue,
    *  and removes this element from the queue.
    *
-   *  @throws Predef.NoSuchElementException
+   *  @throws java.util.NoSuchElementException
    *  @return   the element with the highest priority.
    */
   def dequeue(): A =

src/library/scala/collection/mutable/Queue.scala

@@ -58,7 +58,7 @@ extends MutableList[A]
   /** Returns the first element in the queue, and removes this element
    *  from the queue.
    *
-   *  @throws Predef.NoSuchElementException
+   *  @throws java.util.NoSuchElementException
    *  @return the first element of the queue.
    */
   def dequeue(): A =