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]       ^

1 files changed, 4 insertions, 4 deletions

diff --git a/src/library/scala/Either.scala b/src/library/scala/Either.scala
index 20451600a9..b35d8a7c8a 100644
--- a/src/library/scala/Either.scala
+++ b/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)