Address doc comment rot in the standard library.

- Match @param/@tparam names to the actual parameter name
- Use @tparam for type parameters
- Whitespace is required between `*` and `@`
- Fix incorrect references to @define macros.
- Use of monospace `` and {{{}}} (much more needed)
- Remove `@param p1 ...` stubs, which appear in the generated docss.
  - But, retainsed `@param p1` stubs, assuming they will be filtered from
    the generated docs by SI-5795.
- Avoid use of the shorthand `@param   doc for the solitary param`
  (which works, but isn't recognized by the code inspection in IntelliJ
  I used to sweep through the problems)

The remaining warnings from `ant docs` seem spurious, I suspect they are
an unintended consequence of documenting extension methods.

  [scaladoc] /Users/jason/code/scala/src/library/scala/collection/TraversableOnce.scala:181: warning: Variable coll undefined in comment for method reduceOption in class Tuple2Zipped
  [scaladoc]   def reduceOption[A1 >: A](op: (A1, A1) => A1): Option[A1] = reduceLeftOption(op)
  [scaladoc]       ^

Author: retronym

src/library/scala/Array.scala

@@ -362,8 +362,8 @@ object Array extends FallbackArrayBuilding {
 
   /** Returns an array containing a sequence of increasing integers in a range.
    *
-   *  @param from the start value of the array
-   *  @param end the end value of the array, exclusive (in other words, this is the first value '''not''' returned)
+   *  @param start  the start value of the array
+   *  @param end    the end value of the array, exclusive (in other words, this is the first value '''not''' returned)
    *  @return  the array with values in range `start, start + 1, ..., end - 1`
    *  up to, but excluding, `end`.
    */

src/library/scala/Console.scala

@@ -186,7 +186,6 @@ object Console {
    *  }
    *  }}}
    *
-   *  @param in the new input stream.
    *  @param thunk the code to execute with
    *               the new input stream active
    *

src/library/scala/Either.scala

@@ -297,7 +297,7 @@ object Either {
      * Left(12).left.foreach(x => println(x))  // prints "12"
      * Right(12).left.foreach(x => println(x)) // doesn't print
      * }}}
-     * @param e The side-effecting function to execute.
+     * @param f The side-effecting function to execute.
      */
     def foreach[U](f: A => U) = e match {
       case Left(a) => f(a)
@@ -358,7 +358,7 @@ object Either {
      * Left(12).left.flatMap(x => Left("scala")) // Left("scala")
      * Right(12).left.flatMap(x => Left("scala") // Right(12)
      * }}}
-     * @param The function to bind across `Left`.
+     * @param f The function to bind across `Left`.
      */
     def flatMap[BB >: B, X](f: A => Either[X, BB]) = e match {
       case Left(a) => f(a)
@@ -462,7 +462,7 @@ object Either {
      * Right(12).right.foreach(x => println(x)) // prints "12"
      * Left(12).right.foreach(x => println(x))  // doesn't print
      * }}}
-     * @param e The side-effecting function to execute.
+     * @param f The side-effecting function to execute.
      */
     def foreach[U](f: B => U) = e match {
       case Left(_) => {}
@@ -516,7 +516,7 @@ object Either {
     /**
      * Binds the given function across `Right`.
      *
-     * @param The function to bind across `Right`.
+     * @param f The function to bind across `Right`.
      */
     def flatMap[AA >: A, Y](f: B => Either[AA, Y]) = e match {
       case Left(a) => Left(a)

src/library/scala/Function.scala

@@ -20,7 +20,6 @@ object Function {
    *  function `f,,1,, andThen ... andThen f,,n,,`.
    *
    *  @param fs The given sequence of functions
-   *  @return   ...
    */
   def chain[a](fs: Seq[a => a]): a => a = { x => (x /: fs) ((x, f) => f(x)) }
 
@@ -72,9 +71,6 @@ object Function {
    *
    *  @note  These functions are slotted for deprecation, but it is on
    *  hold pending superior type inference for tupling anonymous functions.
-   *
-   *  @param f  ...
-   *  @return   ...
    */
   // @deprecated("Use `f.tupled` instead")
   def tupled[a1, a2, b](f: (a1, a2) => b): Tuple2[a1, a2] => b = {

src/library/scala/Option.scala

@@ -146,7 +146,7 @@ sealed abstract class Option[+A] extends Product with Serializable {
 
   /** Returns the result of applying $f to this $option's
    *  value if the $option is nonempty.  Otherwise, evaluates
-   *  expression $ifEmpty.
+   *  expression `ifEmpty`.
    *
    *  @note This is equivalent to `$option map f getOrElse ifEmpty`.
    *

src/library/scala/Predef.scala

@@ -160,7 +160,7 @@ object Predef extends LowPriorityImplicits {
    *  is at least `ASSERTION`.
    *
    *  @see elidable
-   *  @param p   the expression to test
+   *  @param assertion   the expression to test
    */
   @elidable(ASSERTION)
   def assert(assertion: Boolean) {
@@ -173,8 +173,8 @@ object Predef extends LowPriorityImplicits {
    *  is at least `ASSERTION`.
    *
    *  @see elidable
-   *  @param p   the expression to test
-   *  @param msg a String to include in the failure message
+   *  @param assertion   the expression to test
+   *  @param message     a String to include in the failure message
    */
   @elidable(ASSERTION) @inline
   final def assert(assertion: Boolean, message: => Any) {
@@ -189,7 +189,7 @@ object Predef extends LowPriorityImplicits {
    *  will not be generated if `-Xelide-below` is at least `ASSERTION`.
    *
    *  @see elidable
-   *  @param p   the expression to test
+   *  @param assumption   the expression to test
    */
   @elidable(ASSERTION)
   def assume(assumption: Boolean) {
@@ -204,8 +204,8 @@ object Predef extends LowPriorityImplicits {
    *  will not be generated if `-Xelide-below` is at least `ASSERTION`.
    *
    *  @see elidable
-   *  @param p   the expression to test
-   *  @param msg a String to include in the failure message
+   *  @param assumption   the expression to test
+   *  @param message      a String to include in the failure message
    */
   @elidable(ASSERTION) @inline
   final def assume(assumption: Boolean, message: => Any) {
@@ -217,7 +217,7 @@ object Predef extends LowPriorityImplicits {
    *  This method is similar to `assert`, but blames the caller of the method
    *  for violating the condition.
    *
-   *  @param p   the expression to test
+   *  @param requirement   the expression to test
    */
   def require(requirement: Boolean) {
     if (!requirement)
@@ -228,8 +228,8 @@ object Predef extends LowPriorityImplicits {
    *  This method is similar to `assert`, but blames the caller of the method
    *  for violating the condition.
    *
-   *  @param p   the expression to test
-   *  @param msg a String to include in the failure message
+   *  @param requirement   the expression to test
+   *  @param message       a String to include in the failure message
    */
   @inline final def require(requirement: Boolean, message: => Any) {
     if (!requirement)

src/library/scala/Product.scala

@@ -19,7 +19,7 @@ package scala
  */
 trait Product extends Any with Equals {
   /** The n^th^ element of this product, 0-based.  In other words, for a
-   *  product `A(x,,1,,, ..., x,,k,,)`, returns `x,,(n+1),, where `0 < n < k`.
+   *  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`

src/library/scala/Responder.scala

@@ -21,19 +21,13 @@ package scala
 object Responder {
 
   /** Creates a responder that answer continuations with the constant `a`.
-   *
-   *  @param x ...
-   *  @return ...
    */
   def constant[A](x: A) = new Responder[A] {
     def respond(k: A => Unit) = k(x)
   }
 
   /** Executes `x` and returns `'''true'''`, useful as syntactic
    *  convenience in for comprehensions.
-   *
-   *  @param x ...
-   *  @return ...
    */
   def exec[A](x: => Unit): Boolean = { x; true }
 

src/library/scala/StringContext.scala

@@ -132,7 +132,7 @@ object StringContext {
    *   escape:  `\\`, `\"`, `\'`
    *   octal:   `\d` `\dd` `\ddd` where `d` is an octal digit between `0` and `7`.
    *
-   *  @param  A string that may contain escape sequences
+   *  @param  str  A string that may contain escape sequences
    *  @return The string with all escape sequences expanded.
    */
   def treatEscapes(str: String): String = {

src/library/scala/annotation/elidable.scala

@@ -18,18 +18,22 @@ import java.util.logging.Level
  *  be omitted from generated code if the priority given the annotation
  *  is lower than that given on the command line.
  *
+ *  {{{
  *     @elidable(123)           // annotation priority
  *     scalac -Xelide-below 456 // command line priority
- *
+ *  }}}
+ *  
  *  The method call will be replaced with an expression which depends on
  *  the type of the elided expression.  In decreasing order of precedence:
  *
+ *  {{{
  *    Unit            ()
  *    Boolean         false
  *    T <: AnyVal     0
  *    T >: Null       null
  *    T >: Nothing    Predef.???
- *
+ *  }}}
+ *  
  *  Complete example:
  {{{
    import annotation._, elidable._

src/library/scala/collection/BitSetLike.scala

@@ -137,7 +137,7 @@ trait BitSetLike[+This <: BitSetLike[This] with SortedSet[Int]] extends SortedSe
 
   /** Computes the intersection between this bitset and another bitset by performing
    *  a bitwise "and".
-   *  @param   that  the bitset to intersect with.
+   *  @param   other  the bitset to intersect with.
    *  @return  a new bitset consisting of all elements that are both in this
    *  bitset and in the given bitset `other`.
    */
@@ -152,7 +152,7 @@ trait BitSetLike[+This <: BitSetLike[This] with SortedSet[Int]] extends SortedSe
   /** Computes the difference of this bitset and another bitset by performing
    *  a bitwise "and-not".
    *
-   *  @param that the set of bits to exclude.
+   *  @param other the set of bits to exclude.
    *  @return     a bitset containing those bits of this
    *              bitset that are not also contained in the given bitset `other`.
    */
@@ -167,7 +167,7 @@ trait BitSetLike[+This <: BitSetLike[This] with SortedSet[Int]] extends SortedSe
   /** Computes the symmetric difference of this bitset and another bitset by performing
    *  a bitwise "exclusive-or".
    *
-   *  @param that the other bitset to take part in the symmetric difference.
+   *  @param other the other bitset to take part in the symmetric difference.
    *  @return     a bitset containing those bits of this
    *              bitset or the other bitset that are not contained in both bitsets.
    */
@@ -184,7 +184,7 @@ trait BitSetLike[+This <: BitSetLike[This] with SortedSet[Int]] extends SortedSe
 
   /** Tests whether this bitset is a subset of another bitset.
    *
-   *  @param that  the bitset to test.
+   *  @param other  the bitset to test.
    *  @return     `true` if this bitset is a subset of `other`, i.e. if
    *              every bit of this set is also an element in `other`.
    */

src/library/scala/collection/GenIterableLike.scala

@@ -41,7 +41,7 @@ trait GenIterableLike[+A, +Repr] extends Any with GenTraversableLike[A, Repr] {
   /** Checks if the other iterable collection contains the same elements in the same order as this $coll.
    *
    *  @param that  the collection to compare with.
-   *  @tparam B    the type of the elements of collection `that`.
+   *  @tparam A1   the type of the elements of collection `that`.
    *  @return `true`, if both collections contain the same elements in the same order, `false` otherwise.
    *
    *  @usecase  def sameElements(that: GenIterable[A]): Boolean
@@ -87,13 +87,13 @@ trait GenIterableLike[+A, +Repr] extends Any with GenTraversableLike[A, Repr] {
    *  @tparam  A1    the type of the first half of the returned pairs (this is always a supertype
    *                 of the collection's element type `A`).
    *  @tparam  That  the class of the returned collection. Where possible, `That` is
-   *    the same class as the current collection class `Repr`, but this
-   *    depends on the element type `(A1, Int)` being admissible for that class,
-   *    which means that an implicit instance of type `CanBuildFrom[Repr, (A1, Int), That]`.
-   *    is found.
-   *  @tparam  bf    an implicit value of class `CanBuildFrom` which determines the
-   *    result class `That` from the current representation type `Repr`
-   *    and the new element type `(A1, Int)`.
+   *                 the same class as the current collection class `Repr`, but this
+   *                 depends on the element type `(A1, Int)` being admissible for that class,
+   *                 which means that an implicit instance of type `CanBuildFrom[Repr, (A1, Int), That]`.
+   *                 is found.
+   *  @param  bf     an implicit value of class `CanBuildFrom` which determines the
+   *                 result class `That` from the current representation type `Repr`
+   *                 and the new element type `(A1, Int)`.
    *  @return        A new collection of type `That` containing pairs consisting of all elements of this
    *                 $coll paired with their index. Indices start at `0`.
    *

src/library/scala/collection/GenMapLike.scala

@@ -42,7 +42,6 @@ trait GenMapLike[A, +B, +Repr] extends GenIterableLike[(A, B), Repr] with Equals
    *            otherwise the result of the `default` computation.
    *   @usecase def getOrElse(key: A, default: => B): B
    *     @inheritdoc
-   *     @tparam  B        the result type of the default computation.
    */
   def getOrElse[B1 >: B](key: A, default: => B1): B1
 

src/library/scala/collection/GenSeqLike.scala

@@ -413,8 +413,6 @@ trait GenSeqLike[+A, +Repr] extends Any with GenIterableLike[A, Repr] with Equal
    *
    *  @param that   the sequence of elements to remove
    *  @tparam B     the element type of the returned $coll.
-   *  @tparam That  $thatinfo
-   *  @param bf     $bfinfo
    *  @return       a new collection of type `That` which contains all elements of this $coll
    *                except some of occurrences of elements that also appear in `that`.
    *                If an element value `x` appears
@@ -438,8 +436,6 @@ trait GenSeqLike[+A, +Repr] extends Any with GenIterableLike[A, Repr] with Equal
    *
    *  @param that   the sequence of elements to intersect with.
    *  @tparam B     the element type of the returned $coll.
-   *  @tparam That  $thatinfo
-   *  @param bf     $bfinfo
    *  @return       a new collection of type `That` which contains all elements of this $coll
    *                which also appear in `that`.
    *                If an element value `x` appears

src/library/scala/collection/GenTraversableLike.scala

@@ -289,27 +289,27 @@ trait GenTraversableLike[+A, +Repr] extends Any with GenTraversableOnce[A] with
 
   /** Selects all elements of this $coll which satisfy a predicate.
    *
-   *  @param p     the predicate used to test elements.
+   *  @param pred  the predicate used to test elements.
    *  @return      a new $coll consisting of all elements of this $coll that satisfy the given
    *               predicate `p`. Their order may not be preserved.
    */
   def filter(pred: A => Boolean): Repr
 
   /** Selects all elements of this $coll which do not satisfy a predicate.
    *
-   *  @param p     the predicate used to test elements.
+   *  @param pred  the predicate used to test elements.
    *  @return      a new $coll consisting of all elements of this $coll that do not satisfy the given
    *               predicate `p`. Their order may not be preserved.
    */
   def filterNot(pred: A => Boolean): Repr
 
   /** Partitions this $coll in two ${coll}s according to a predicate.
    *
-   *  @param p the predicate on which to partition.
-   *  @return  a pair of ${coll}s: the first $coll consists of all elements that
-   *           satisfy the predicate `p` and the second $coll consists of all elements
-   *           that don't. The relative order of the elements in the resulting ${coll}s
-   *           may not be preserved.
+   *  @param pred the predicate on which to partition.
+   *  @return     a pair of ${coll}s: the first $coll consists of all elements that
+   *              satisfy the predicate `p` and the second $coll consists of all elements
+   *              that don't. The relative order of the elements in the resulting ${coll}s
+   *              may not be preserved.
    */
   def partition(pred: A => Boolean): (Repr, Repr)
 
@@ -354,8 +354,8 @@ trait GenTraversableLike[+A, +Repr] extends Any with GenTraversableOnce[A] with
    *  }}}
    *  $orderDependent
    *
-   *  @param from   the lowest index to include from this $coll.
-   *  @param until  the lowest index to EXCLUDE from this $coll.
+   *  @param unc_from   the lowest index to include from this $coll.
+   *  @param unc_until  the lowest index to EXCLUDE from this $coll.
    *  @return  a $coll containing the elements greater than or equal to
    *           index `from` extending up to (but not including) index `until`
    *           of this $coll.
@@ -375,7 +375,7 @@ trait GenTraversableLike[+A, +Repr] extends Any with GenTraversableOnce[A] with
 
   /** Takes longest prefix of elements that satisfy a predicate.
    *  $orderDependent
-   *  @param   p  The predicate used to test elements.
+   *  @param   pred  The predicate used to test elements.
    *  @return  the longest prefix of this $coll whose elements all satisfy
    *           the predicate `p`.
    */
@@ -388,15 +388,15 @@ trait GenTraversableLike[+A, +Repr] extends Any with GenTraversableOnce[A] with
    *  predicate `p` does not cause any side-effects.
    *  $orderDependent
    *
-   *  @param p the test predicate
+   *  @param pred the test predicate
    *  @return  a pair consisting of the longest prefix of this $coll whose
    *           elements all satisfy `p`, and the rest of this $coll.
    */
   def span(pred: A => Boolean): (Repr, Repr)
 
   /** Drops longest prefix of elements that satisfy a predicate.
    *  $orderDependent
-   *  @param   p  The predicate used to test elements.
+   *  @param   pred  The predicate used to test elements.
    *  @return  the longest suffix of this $coll whose first element
    *           does not satisfy the predicate `p`.
    */