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, 8 deletions

diff --git a/src/library/scala/collection/immutable/ListMap.scala b/src/library/scala/collection/immutable/ListMap.scala
index 9289b35632..091443f909 100644
--- a/src/library/scala/collection/immutable/ListMap.scala
+++ b/src/library/scala/collection/immutable/ListMap.scala
@@ -152,7 +152,7 @@ extends AbstractMap[A, B]
      *  method throws an exception if there is no mapping from the given
      *  key to a value.
      *
-     *  @param  key the key
+     *  @param  k   the key
      *  @return     the value associated with the given key.
      */
     override def apply(k: A): B1 = apply0(this, k)
@@ -162,7 +162,7 @@ extends AbstractMap[A, B]
     /** Checks if this map maps `key` to a value and return the
      *  value if it exists.
      *
-     *  @param  key the key of the mapping of interest
+     *  @param  k   the key of the mapping of interest
      *  @return     the value of the mapping, if it exists
      */
     override def get(k: A): Option[B1] = get0(this, k)
@@ -174,9 +174,6 @@ extends AbstractMap[A, B]
     /** This method allows one to create a new map with an additional mapping
      *  from `key` to `value`. If the map contains already a mapping for `key`,
      *  it will be overridden by this function.
-     *
-     *  @param k ...
-     *  @param v ...
      */
     override def updated [B2 >: B1](k: A, v: B2): ListMap[A, B2] = {
       val m = if (contains(k)) this - k else this
@@ -186,9 +183,6 @@ extends AbstractMap[A, B]
     /** Creates a new mapping without the given `key`.
      *  If the map does not contain a mapping for the given key, the
      *  method returns the same map.
-     *
-     *  @param k ...
-     *  @return  ...
      */
     override def - (k: A): ListMap[A, B1] = {
       // This definition used to result in stack overflows