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, 2 insertions, 4 deletions

diff --git a/src/library/scala/reflect/api/Types.scala b/src/library/scala/reflect/api/Types.scala
index 5c7563c2c5..3d42242641 100755
--- a/src/library/scala/reflect/api/Types.scala
+++ b/src/library/scala/reflect/api/Types.scala
@@ -111,10 +111,12 @@ trait Types { self: Universe =>
      *  Proceed analogously for thistypes referring to outer classes.
      *
      *  Example:
+     *  {{{
      *    class D[T] { def m: T }
      *    class C extends p.D[Int]
      *    T.asSeenFrom(ThisType(C), D)  (where D is owner of m)
      *      = Int
+     *  }}} 
      */
     def asSeenFrom(pre: Type, clazz: Symbol): Type
 
@@ -481,10 +483,6 @@ trait Types { self: Universe =>
   def refinedType(parents: List[Type], owner: Symbol, decls: Scope, pos: Position): Type
 
   /** The canonical creator for a refined type with an initially empty scope.
-   *
-   *  @param parents ...
-   *  @param owner   ...
-   *  @return        ...
    */
   def refinedType(parents: List[Type], owner: Symbol): Type