Fixed a number of faulty Scaladoc comments in l...

Fixed a number of faulty Scaladoc comments in library and compiler
sources. No review.

32 files changed, 106 insertions, 148 deletions

diff --git a/src/library/scala/Console.scala b/src/library/scala/Console.scala
index 7923b6be65..fc33fa07ef 100644
--- a/src/library/scala/Console.scala
+++ b/src/library/scala/Console.scala
@@ -83,7 +83,7 @@ object Console {
 
   /** Set the default output stream.
    *
-   *  @param@ out the new output stream.
+   *  @param out the new output stream.
    */
   def setOut(out: OutputStream): Unit =
     setOut(new PrintStream(out))
diff --git a/src/library/scala/Option.scala b/src/library/scala/Option.scala
index 8511fa78a5..17bb6d0148 100644
--- a/src/library/scala/Option.scala
+++ b/src/library/scala/Option.scala
@@ -45,7 +45,7 @@ sealed abstract class Option[+A] extends Product {
   def isDefined: Boolean = !isEmpty
 
   /** get the value of this option.
-   *  @requires that the option is nonEmpty.
+   *  @note The option must be nonEmpty.
    *  @throws Predef.NoSuchElementException if the option is empty.
    */
   def get: A
diff --git a/src/library/scala/annotation/elidable.scala b/src/library/scala/annotation/elidable.scala
index 4f29c8f2ab..44ac7f050e 100644
--- a/src/library/scala/annotation/elidable.scala
+++ b/src/library/scala/annotation/elidable.scala
@@ -17,14 +17,14 @@ import java.util.logging.Level
  *  to scalac.  Methods marked elidable will be omitted from
  *  generated code if the priority given the annotation is lower
  *  than to the command line argument.  Examples:
- *
+ *  {{{
  *  import annotation.elidable._
  *
  *    @elidable(WARNING) def foo = log("foo")
  *    @elidable(FINE) def bar = log("bar")
  *
  *  scalac -Xelide-methods-below=1000
- *
+ *  }}}
  *  @since 2.8
  */
 final class elidable(final val level: Int) extends StaticAnnotation {}
diff --git a/src/library/scala/collection/BitSetLike.scala b/src/library/scala/collection/BitSetLike.scala
index aac731fec9..4b87e75dcb 100644
--- a/src/library/scala/collection/BitSetLike.scala
+++ b/src/library/scala/collection/BitSetLike.scala
@@ -28,11 +28,10 @@ import mutable.StringBuilder
  *  @since 2.8
  *  @define coll bitset
  *  @define Coll BitSet
- *  define bitsetinfo
+ *  @define bitsetinfo
  *  Bitsets are sets of non-negative integers which are represented as
  *  variable-size arrays of bits packed into 64-bit words. The size of a bitset is
  *  determined by the largest number stored in it.
-
  */
 trait BitSetLike[+This <: BitSetLike[This] with Set[Int]] extends SetLike[Int, This] { self =>
 
diff --git a/src/library/scala/collection/Iterator.scala b/src/library/scala/collection/Iterator.scala
index 7dbc39f5b7..4e8a409efd 100644
--- a/src/library/scala/collection/Iterator.scala
+++ b/src/library/scala/collection/Iterator.scala
@@ -328,7 +328,7 @@ trait Iterator[+A] { self =>
   }
 
   /** Concatenates this iterator with another.
-   *  @that   the other iterator
+   *  @param   that   the other iterator
    *  @return  a new iterator that first yields the values produced by this
    *  iterator followed by the values produced by iterator `that`.
    *  @usecase def ++(that: => Iterator[A]): Iterator[A]
@@ -1288,7 +1288,7 @@ trait Iterator[+A] { self =>
    *  @param  xs    the array to fill.
    *  @param  start the starting index.
    *  @param  sz    the maximum number of elements to be read.
-   *  @pre          the array must be large enough to hold `sz` elements.
+   *  @note          the array must be large enough to hold `sz` elements.
    */
   @deprecated("use copyToArray instead")
   def readInto[B >: A](xs: Array[B], start: Int, sz: Int) {
diff --git a/src/library/scala/collection/MapLike.scala b/src/library/scala/collection/MapLike.scala
index 55cea1a678..0a00abeb47 100644
--- a/src/library/scala/collection/MapLike.scala
+++ b/src/library/scala/collection/MapLike.scala
@@ -71,7 +71,7 @@ self =>
 
   /** Optionally returns the value associated with a key.
    *
-   *  @key    the key value
+   *  @param  key    the key value
    *  @return an option value containing the value associated with `key` in this map,
    *          or `None` if none exists.
    */
diff --git a/src/library/scala/collection/SeqLike.scala b/src/library/scala/collection/SeqLike.scala
index 9802f63fa2..9aa3141395 100644
--- a/src/library/scala/collection/SeqLike.scala
+++ b/src/library/scala/collection/SeqLike.scala
@@ -760,7 +760,7 @@ trait SeqLike[+A, +Repr] extends IterableLike[A, Repr] { self =>
    *              the desired ordering.
    *  @return     a $coll consisting of the elements of this $coll
    *              sorted according to the comparison function `lt`.
-   *  @ex {{{
+   *  @example {{{
    *    List("Steve", "Tom", "John", "Bob").sortWith(_.compareTo(_) < 0) =
    *    List("Bob", "John", "Steve", "Tom")
    *  }}}
@@ -805,7 +805,7 @@ trait SeqLike[+A, +Repr] extends IterableLike[A, Repr] { self =>
    *           sorted according to the ordering where `x < y` if
    *           `ord.lt(f(x), f(y))`.
    *
-   *  @ex {{{
+   *  @example {{{
    *    val words = "The quick brown fox jumped over the lazy dog".split(' ')
    *    // this works because scala.Ordering will implicitly provide an Ordering[Tuple2[Int, Char]]
    *    words.sortBy(x => (x.length, x.head))
@@ -823,7 +823,7 @@ trait SeqLike[+A, +Repr] extends IterableLike[A, Repr] { self =>
 
   /** Produces the range of all indices of this sequence.
    *
-   *  @range  a `Range` value from `0` to one less than the length of this $coll.
+   *  @return  a `Range` value from `0` to one less than the length of this $coll.
    */
   def indices: Range = 0 until length
 
diff --git a/src/library/scala/collection/TraversableLike.scala b/src/library/scala/collection/TraversableLike.scala
index fc666ddb92..78890ca406 100644
--- a/src/library/scala/collection/TraversableLike.scala
+++ b/src/library/scala/collection/TraversableLike.scala
@@ -1039,7 +1039,7 @@ self =>
    *               `end`. Inside, the string representations (w.r.t. the method `toString`)
    *               of all elements of this $coll are separated by the string `sep`.
    *
-   *  @ex  `List(1, 2, 3).mkString("(", "; ", ")") = "(1; 2; 3)"`
+   *  @example  `List(1, 2, 3).mkString("(", "; ", ")") = "(1; 2; 3)"`
    */
   def mkString(start: String, sep: String, end: String): String =
     addString(new StringBuilder(), start, sep, end).toString
@@ -1051,7 +1051,7 @@ self =>
    *               the string representations (w.r.t. the method `toString`)
    *               of all elements of this $coll are separated by the string `sep`.
    *
-   *  @ex  `List(1, 2, 3).mkString("|") = "1|2|3"`
+   *  @example  `List(1, 2, 3).mkString("|") = "1|2|3"`
    */
   def mkString(sep: String): String =
     addString(new StringBuilder(), sep).toString
@@ -1106,7 +1106,7 @@ self =>
   def addString(b: StringBuilder): StringBuilder = addString(b, "")
 
   /** Converts this $coll to a string
-   *  @returns  a string representation of this collection. By default this
+   *  @return   a string representation of this collection. By default this
    *            string consists of the `stringPrefix` of this $coll,
    *            followed by all elements separated by commas and enclosed in parentheses.
    */
diff --git a/src/library/scala/collection/generic/GenericTraversableTemplate.scala b/src/library/scala/collection/generic/GenericTraversableTemplate.scala
index 0e3c3c203b..683f609686 100644
--- a/src/library/scala/collection/generic/GenericTraversableTemplate.scala
+++ b/src/library/scala/collection/generic/GenericTraversableTemplate.scala
@@ -100,8 +100,8 @@ trait GenericTraversableTemplate[+A, +CC[X] <: Traversable[X]] extends HasNewBui
   }
 
   /** Transposes this $coll of traversable collections into
-   *  @B the type of the elements of each traversable collection.
-   *  @asTraversable an implicit conversion which asserts that the element type of this
+   *  @tparam B the type of the elements of each traversable collection.
+   *  @param  asTraversable an implicit conversion which asserts that the 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.
diff --git a/src/library/scala/collection/generic/Growable.scala b/src/library/scala/collection/generic/Growable.scala
index 7950dee9de..fc3712d81e 100644
--- a/src/library/scala/collection/generic/Growable.scala
+++ b/src/library/scala/collection/generic/Growable.scala
@@ -16,7 +16,6 @@ package generic
  *  a `clear` method.
  *
  *  @author   Martin Odersky
- *  @owner   Martin Odersky
  *  @version 2.8
  *  @since   2.8
  *  @define coll growable collection
diff --git a/src/library/scala/collection/generic/Shrinkable.scala b/src/library/scala/collection/generic/Shrinkable.scala
index bd773a97f9..fafeb51141 100644
--- a/src/library/scala/collection/generic/Shrinkable.scala
+++ b/src/library/scala/collection/generic/Shrinkable.scala
@@ -15,7 +15,6 @@ package generic
  *  using a `-=` operator.
  *
  *  @author   Martin Odersky
- *  @owner   Martin Odersky
  *  @version 2.8
  *  @since   2.8
  *  @define coll shrinkable collection
diff --git a/src/library/scala/collection/immutable/List.scala b/src/library/scala/collection/immutable/List.scala
index 2088f3ac78..415a31a02e 100644
--- a/src/library/scala/collection/immutable/List.scala
+++ b/src/library/scala/collection/immutable/List.scala
@@ -61,7 +61,7 @@ sealed abstract class List[+A] extends LinearSeq[A]
    *  @param x the element to prepend.
    *  @return  a list which contains `x` as first element and
    *           which continues with this list.
-   *  @ex `1 :: List(2, 3) = List(2, 3).::(1) = List(1, 2, 3)`
+   *  @example `1 :: List(2, 3) = List(2, 3).::(1) = List(1, 2, 3)`
    *  @usecase def ::(x: A): List[A]
    */
   def ::[B >: A] (x: B): List[B] =
@@ -71,7 +71,7 @@ sealed abstract class List[+A] extends LinearSeq[A]
    *  @param prefix  The list elements to prepend.
    *  @return a list resulting from the concatenation of the given
    *    list `prefix` and this list.
-   *  @ex `List(1, 2) ::: List(3, 4) = List(3, 4).:::(List(1, 2)) = List(1, 2, 3, 4)`
+   *  @example `List(1, 2) ::: List(3, 4) = List(3, 4).:::(List(1, 2)) = List(1, 2, 3, 4)`
    *  @usecase def :::(prefix: List[A]): List[A]
    */
   def :::[B >: A](prefix: List[B]): List[B] =
@@ -299,7 +299,7 @@ sealed abstract class List[+A] extends LinearSeq[A]
    *  @param lt the comparison function
    *  @return   a list sorted according to the comparison function
    *            `lt(e1: a, e2: a) =&gt; Boolean`.
-   *  @ex <pre>
+   *  @example <pre>
    *    List("Steve", "Tom", "John", "Bob")
    *      .sort((e1, e2) => (e1 compareTo e2) &lt; 0) =
    *    List("Bob", "John", "Steve", "Tom")</pre>
diff --git a/src/library/scala/collection/immutable/Range.scala b/src/library/scala/collection/immutable/Range.scala
index 47a97664de..cdf8cc6426 100644
--- a/src/library/scala/collection/immutable/Range.scala
+++ b/src/library/scala/collection/immutable/Range.scala
@@ -106,7 +106,7 @@ class Range(val start: Int, val end: Int, val step: Int) extends IndexedSeq[Int]
   final override def reverse: Range = new Range.Inclusive(last, start, -step)
 
   /** Make range inclusive.
-   * @pre if (step > 0) end != MaxInt else end != MinInt
+   * @note if (step > 0) end != MaxInt else end != MinInt
    */
   def inclusive = new Range.Inclusive(start, end, step)
 
@@ -148,18 +148,18 @@ object Range {
   def apply(start: Int, end: Int, step: Int): Range = new Range(start, end, step)
 
   /** Make an range from `start` to `end` inclusive with step value 1.
-   * @pre end != MaxInt
+   * @note end != MaxInt
    */
   def apply(start: Int, end: Int): Range with ByOne = new Range(start, end, 1) with ByOne
 
   /** Make an inclusive range from start to end with given step value.
-   * @pre step != 0
-   * @pre if (step > 0) end != MaxInt else end != MinInt
+   * @note step != 0
+   * @note if (step > 0) end != MaxInt else end != MinInt
    */
   def inclusive(start: Int, end: Int, step: Int): Range.Inclusive = new Inclusive(start, end, step)
 
   /** Make an inclusive range from start to end with step value 1.
-   * @pre end != MaxInt
+   * @note end != MaxInt
    */
   def inclusive(start: Int, end: Int): Range.Inclusive with ByOne = new Inclusive(start, end, 1) with ByOne
 
diff --git a/src/library/scala/collection/immutable/Stream.scala b/src/library/scala/collection/immutable/Stream.scala
index 1377fbe59d..7b9db5e21e 100644
--- a/src/library/scala/collection/immutable/Stream.scala
+++ b/src/library/scala/collection/immutable/Stream.scala
@@ -420,9 +420,9 @@ object Stream extends SeqFactory[Stream] {
   import scala.collection.{Iterable, Seq, IndexedSeq}
 
   /** A builder for streams
-   *  @note: This builder is lazy only in the sense that it does not go downs the spine
-   *         of traversables that are added as a whole. If more laziness can be achieved,
-   *         this builder should be bypassed.
+   *  @note This builder is lazy only in the sense that it does not go downs the spine
+   *        of traversables that are added as a whole. If more laziness can be achieved,
+   *        this builder should be bypassed.
    */
   class StreamBuilder[A] extends scala.collection.mutable.LazyBuilder[A, Stream[A]] {
     def result: Stream[A] = (for (xs <- parts.iterator; x <- xs.toIterable.iterator) yield x).toStream
diff --git a/src/library/scala/collection/mutable/BufferLike.scala b/src/library/scala/collection/mutable/BufferLike.scala
index 3516a60233..58dd7f139b 100644
--- a/src/library/scala/collection/mutable/BufferLike.scala
+++ b/src/library/scala/collection/mutable/BufferLike.scala
@@ -30,10 +30,6 @@ import script._
  *  @author  Martin Odersky
  *  @author  Matthias Zenger
  *  @version 2.8
- *  @since 2.8
- *  @author Matthias Zenger
- *  @author Martin Odersky
- *  @version 2.8
  *  @since   2.8
  *  @define buffernote @note
  *    This trait provides most of the operations of a `Buffer` independently of its representation.
diff --git a/src/library/scala/collection/mutable/Builder.scala b/src/library/scala/collection/mutable/Builder.scala
index c7932ae344..1706f598ec 100644
--- a/src/library/scala/collection/mutable/Builder.scala
+++ b/src/library/scala/collection/mutable/Builder.scala
@@ -48,7 +48,7 @@ trait Builder[-Elem, +To] extends Growable[Elem] {
    *  builder implementations are still required to work correctly even if the hint is
    *  wrong, i.e. a different number of elements is added.
    *
-   *  @size  the hint how many elements will be added.
+   *  @param size  the hint how many elements will be added.
    */
   def sizeHint(size: Int) {}
 
diff --git a/src/library/scala/collection/mutable/LinkedListLike.scala b/src/library/scala/collection/mutable/LinkedListLike.scala
index c363609762..2523ece370 100644
--- a/src/library/scala/collection/mutable/LinkedListLike.scala
+++ b/src/library/scala/collection/mutable/LinkedListLike.scala
@@ -55,7 +55,7 @@ trait LinkedListLike[A, This <: Seq[A] with LinkedListLike[A, This]] extends Seq
   }
 
   /** Insert linked list `that` at current position of this linked list
-   *  @pre this linked list is not empty
+   *  @note this linked list must not be empty
    */
   def insert(that: This): Unit = {
     require(nonEmpty, "insert into empty list")
diff --git a/src/library/scala/collection/mutable/ListBuffer.scala b/src/library/scala/collection/mutable/ListBuffer.scala
index 686b1acf8d..43892e3e87 100644
--- a/src/library/scala/collection/mutable/ListBuffer.scala
+++ b/src/library/scala/collection/mutable/ListBuffer.scala
@@ -231,7 +231,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 <code>n</code>.
-   *  @pre       an element exists at position <code>n</code>
+   *  @note      an element must exists at position <code>n</code>
    *  @throws Predef.IndexOutOfBoundsException if <code>n</code> is out of bounds.
    */
   def remove(n: Int): A = {
diff --git a/src/library/scala/collection/mutable/MapLike.scala b/src/library/scala/collection/mutable/MapLike.scala
index a1bb25910a..ad350f4263 100644
--- a/src/library/scala/collection/mutable/MapLike.scala
+++ b/src/library/scala/collection/mutable/MapLike.scala
@@ -195,11 +195,11 @@ trait MapLike[A, B, +This <: MapLike[A, B, This] with Map[A, B]]
   /** If given key is already in this map, returns associated value
    *  Otherwise, computes value from given expression `op`, stores with key
    *  in map and returns that value.
-   *  @param  the key to test
-   *  @param  the computation yielding the value to associate with `key`, if
-   *          `key` is previosuly unbound.
-   *  @return the value associated with key (either previously or as a result
-   *          of executing the method).
+   *  @param  key the key to test
+   *  @param  op  the computation yielding the value to associate with `key`, if
+   *              `key` is previosuly unbound.
+   *  @return     the value associated with key (either previously or as a result
+   *              of executing the method).
    */
   def getOrElseUpdate(key: A, op: => B): B =
     get(key) match {
diff --git a/src/library/scala/throws.scala b/src/library/scala/throws.scala
index 500db0a30a..b932ccc7ac 100644
--- a/src/library/scala/throws.scala
+++ b/src/library/scala/throws.scala
@@ -14,13 +14,13 @@ package scala
 /** <p>
  *    Annotation for specifying the exceptions thrown by a method.
  *    For example:
- *  </p><pre>
- *    <b>class</b> Reader(fname: String) {
- *      <b>private val</b> in =
- *        <b>new</b> BufferedReader(<b>new</b> <a class="java/io/FileReader" href="" target="_top">FileReader</a>(fname))
- *      @throws(classOf[<a class="java/io/IOException" href="" target="_top">IOException</a>])
- *      <b>def</b> read() = in.read()
- *    }</pre>
+ * {{{
+ * class Reader(fname: String) {
+ *   private val in = new BufferedReader(new FileReader(fname))
+ *   @throws(classOf[IOException])
+ *   def read() = in.read()
+ * }
+ * }}}
  *
  * @author  Nikolay Mihaylov
  * @version 1.0, 19/05/2006
diff --git a/src/library/scala/util/Sorting.scala b/src/library/scala/util/Sorting.scala
index 73228b53d5..5585457f07 100644
--- a/src/library/scala/util/Sorting.scala
+++ b/src/library/scala/util/Sorting.scala
@@ -12,22 +12,19 @@
 package scala.util
 import scala.reflect.ClassManifest
 
-/** <p>
- *    The Sorting object provides functions that can sort various kinds of
- *    objects. You can provide a comparison function, or you can request a sort
- *    of items that are viewable as <code>Ordered</code>. Some sorts that
- *    operate directly on a subset of value types are also provided. These
- *    implementations are derived from those in the Sun JDK.
- *  </p>
- *  <p>
- *    Note that stability doesn't matter for value types, so use the quickSort
- *    variants for those. <code>stableSort</code> is intended to be used with
- *    objects when the prior ordering should be preserved, where possible.
- *  </p>
- *
- *  @author  Ross Judson
- *  @version 1.0
- */
+/** The Sorting object provides functions that can sort various kinds of
+  * objects. You can provide a comparison function, or you can request a sort
+  * of items that are viewable as <code>Ordered</code>. Some sorts that
+  * operate directly on a subset of value types are also provided. These
+  * implementations are derived from those in the Sun JDK.
+  *
+  * Note that stability doesn't matter for value types, so use the quickSort
+  * variants for those. <code>stableSort</code> is intended to be used with
+  * objects when the prior ordering should be preserved, where possible.
+  *
+  * @author  Ross Judson
+  * @version 1.0
+  */
 object Sorting {
 
   /** Provides implicit access to sorting on arbitrary sequences of orderable
@@ -49,7 +46,7 @@ object Sorting {
   def quickSort(a: Array[Float]) = sort1(a, 0, a.length)
 
   /** Sort an array of K where K is Ordered, preserving the existing order
-      where the values are equal. */
+    * where the values are equal. */
   def stableSort[K <% Ordered[K] : ClassManifest](a: Array[K]) {
     stableSort(a, 0, a.length-1, new Array[K](a.length), (a:K, b:K) => a < b)
   }
diff --git a/src/library/scala/util/parsing/ast/Binders.scala b/src/library/scala/util/parsing/ast/Binders.scala
index b397e900da..7a9b8e5dcd 100644
--- a/src/library/scala/util/parsing/ast/Binders.scala
+++ b/src/library/scala/util/parsing/ast/Binders.scala
@@ -127,10 +127,8 @@ trait Binders extends AbstractSyntax with Mappable {
      * (e.g. the variable name in a local variable declaration)
      *
      * @param b a new binder that is distinct from the existing binders in this scope,
-     *           and shares their conceptual scope
-     * @pre canAddBinder(b)
-     * @post binds(b)
-     * @post getElementFor(b) eq b
+     *           and shares their conceptual scope. canAddBinder(b)` must hold.`
+     * @return `binds(b)` and `getElementFor(b) eq b` will hold.
      */
     def addBinder(b: binderType) { substitution += Pair(b, b) }
 
@@ -140,7 +138,7 @@ trait Binders extends AbstractSyntax with Mappable {
      *       linked to its `UnderBinder' (i.e., while parsing, BoundElements may be added to the Scope
      *       associated to the UnderBinder, but after that, no changes are allowed, except for substitution)?
      *
-     * @returns true if `b' had not been added yet
+     * @return true if `b' had not been added yet
      */
     def canAddBinder(b: binderType): Boolean = !binds(b)
 
@@ -150,17 +148,15 @@ trait Binders extends AbstractSyntax with Mappable {
      * a proxy for the element it is bound to by its binder, `substitute' may thus be thought of
      * as replacing all the bound occurrences of the given binder `b' by their new value `value'.
      *
-     * @param b    the binder whose bound occurrences should be given a new value
+     * @param b    the binder whose bound occurrences should be given a new value. `binds(b)` must hold.
      * @param value the new value for the bound occurrences of `b'
-     * @pre binds(b)
-     * @post getElementFor(b) eq value
+     * @return `getElementFor(b) eq value` will hold.
      */
     def substitute(b: binderType, value: Element): Unit = substitution(b) = value
 
     /** Returns the current value for the bound occurrences of `b'.
      *
-     * @param b the contained binder whose current value should be returned
-     * @pre binds(b)
+     * @param b the contained binder whose current value should be returned `binds(b)` must hold.
      */
     def getElementFor(b: binderType): Element = substitution(b)
 
@@ -173,7 +169,7 @@ trait Binders extends AbstractSyntax with Mappable {
     def allowForwardRef: Scope[binderType] = this // TODO
 
     /** Return a nested scope -- binders entered into it won't be visible in this scope, but if this scope allows forward references,
-        the binding in the returned scope also does, and thus the check that all variables are bound is deferred until this scope is left  **/
+      * the binding in the returned scope also does, and thus the check that all variables are bound is deferred until this scope is left  **/
     def nested: Scope[binderType] = this // TODO
 
     def onEnter {}
@@ -193,7 +189,7 @@ trait Binders extends AbstractSyntax with Mappable {
    * A `BoundElement' is represented textually by its bound element, followed by its scope's `id'.
    * For example: `x@1' represents the variable `x' that is bound in the scope with `id' `1'.
    *
-   * @invar scope.binds(el)
+   * @note `scope.binds(el)` holds before and after.
    */
   case class BoundElement[boundElement <: NameElement](el: boundElement, scope: Scope[boundElement]) extends NameElement with Proxy with BindingSensitive {
     /** Returns the element this `BoundElement' stands for.
@@ -300,7 +296,7 @@ trait Binders extends AbstractSyntax with Mappable {
    *
    * The name `sequence' comes from the fact that this method's type is equal to the type of monadic sequence.
    *
-   * @pre !orig.isEmpty implies orig.forall(ub => ub.scope eq orig(0).scope)
+   * @note `!orig.isEmpty` implies `orig.forall(ub => ub.scope eq orig(0).scope)`
    *
    */
   def sequence[bt <: NameElement, st <% Mappable[st]](orig: List[UnderBinder[bt, st]]): UnderBinder[bt, List[st]] =
diff --git a/src/library/scala/util/parsing/combinator/Parsers.scala b/src/library/scala/util/parsing/combinator/Parsers.scala
index 6fe35ad3b0..183465f84d 100644
--- a/src/library/scala/util/parsing/combinator/Parsers.scala
+++ b/src/library/scala/util/parsing/combinator/Parsers.scala
@@ -48,35 +48,21 @@ import scala.annotation.tailrec
  *    of the input.
  *  </p>
  *
- * @requires Elem the type of elements the provided parsers consume
- *              (When consuming invidual characters, a parser is typically called a ``scanner'',
- *               which produces ``tokens'' that are consumed by what is normally called a ``parser''.
- *               Nonetheless, the same principles apply, regardless of the input type.)</p>
- *<p>
- * @provides Input = Reader[Elem]
- *              The type of input the parsers in this component expect.</p>
- *<p>
- * @provides Parser[+T] extends (Input => ParseResult[T])
- *              Essentially, a `Parser[T]' is a function from `Input' to `ParseResult[T]'.</p>
- *<p>
- * @provides ParseResult[+T] is like an `Option[T]', in the sense that it is either
- *              `Success[T]', which consists of some result (:T) (and the rest of the input) or
- *              `Failure[T]', which provides an error message (and the rest of the input).</p>
- *
  * @author Martin Odersky, Iulian Dragos, Adriaan Moors
  */
 trait Parsers {
-  /** the type of input elements */
+  /** the type of input elements the provided parsers consume (When consuming invidual characters, a parser is typically
+   * called a ``scanner'', which produces ``tokens'' that are consumed by what is normally called a ``parser''.
+   * Nonetheless, the same principles apply, regardless of the input type.) */
   type Elem
 
-  /** The parser input is an abstract reader of input elements */
+  /** The parser input is an abstract reader of input elements, i.e. the type of input the parsers in this component
+   * expect. */
   type Input = Reader[Elem]
 
-  /** A base class for parser results.
-   *  A result is either successful or not (failure may be fatal, i.e.,
-   *  an Error, or not, i.e., a Failure)
-   *  On success, provides a result of type <code>T</code>.
-   */
+  /** A base class for parser results. A result is either successful or not (failure may be fatal, i.e., an Error, or
+   * not, i.e., a Failure). On success, provides a result of type `T` which consists of some result (and the rest of
+   * the input). */
   sealed abstract class ParseResult[+T] {
     /** Functional composition of ParseResults
      *
diff --git a/src/library/scala/util/parsing/combinator/lexical/Scanners.scala b/src/library/scala/util/parsing/combinator/lexical/Scanners.scala
index 07f4975cf8..5b01049c91 100644
--- a/src/library/scala/util/parsing/combinator/lexical/Scanners.scala
+++ b/src/library/scala/util/parsing/combinator/lexical/Scanners.scala
@@ -23,13 +23,6 @@ import scala.util.parsing.input._
  *    {@see StdLexical}, for more functionality.
  *  </p>
  *
- *  @requires token      a parser that produces a token (from a stream of characters)
- *  @requires whitespace a unit-parser for white-space
- *  @provides Scanner    essentially a parser that parses a stream of characters
- *                       to produce `Token's, which are typically passed to a
- *                       syntactical parser (which operates on `Token's, not on
- *                       individual characters).
- *
  *  @author Martin Odersky, Adriaan Moors
  */
 trait Scanners extends Parsers {
diff --git a/src/library/scala/util/parsing/combinator/syntactical/TokenParsers.scala b/src/library/scala/util/parsing/combinator/syntactical/TokenParsers.scala
index 01557c32a7..ff2c552deb 100644
--- a/src/library/scala/util/parsing/combinator/syntactical/TokenParsers.scala
+++ b/src/library/scala/util/parsing/combinator/syntactical/TokenParsers.scala
@@ -12,13 +12,7 @@
 package scala.util.parsing.combinator.syntactical
 import scala.util.parsing.combinator._
 
-/** <p>
- *    This is the core component for token-based parsers.
- *  </p>
- *  <p>
- *    @requires lexical a component providing the tokens consumed by the
- *    parsers in this component.
- *  </p>
+/** This is the core component for token-based parsers.
  *
  *  @author Martin Odersky, Adriaan Moors
  */
diff --git a/src/library/scala/xml/Node.scala b/src/library/scala/xml/Node.scala
index f206140fd4..500c11e41d 100644
--- a/src/library/scala/xml/Node.scala
+++ b/src/library/scala/xml/Node.scala
@@ -213,9 +213,10 @@ abstract class Node extends NodeSeq {
    *  Martin to Burak: to do: if you make this method abstract, the compiler will now
    *  complain if there's no implementation in a subclass. Is this what we want? Note that
    *  this would break doc/DocGenator and doc/ModelToXML, with an error message like:
-doc\DocGenerator.scala:1219: error: object creation impossible, since there is a deferred declaration of method text in class Node of type => String which is not implemented in a subclass
-    new SpecialNode {
-    ^
-   */
+   * {{{
+   * doc\DocGenerator.scala:1219: error: object creation impossible, since there is a deferred declaration of method text in class Node of type => String which is not implemented in a subclass
+   * new SpecialNode {
+   * ^
+   * }}} */
   override def text: String = super.text
 }
diff --git a/src/library/scala/xml/PrettyPrinter.scala b/src/library/scala/xml/PrettyPrinter.scala
index 1fb922eb95..17e7db679a 100644
--- a/src/library/scala/xml/PrettyPrinter.scala
+++ b/src/library/scala/xml/PrettyPrinter.scala
@@ -23,7 +23,7 @@ import Utility.sbToString
  *  @version 1.0
  *
  *  @param width the width to fit the output into
- *  @step  indentation
+ *  @param step  indentation
  */
 class PrettyPrinter(width: Int, step: Int) {
 
diff --git a/src/library/scala/xml/Utility.scala b/src/library/scala/xml/Utility.scala
index 1cfe9c79c9..c39c787bfe 100644
--- a/src/library/scala/xml/Utility.scala
+++ b/src/library/scala/xml/Utility.scala
@@ -84,7 +84,7 @@ object Utility extends AnyRef with parsing.TokenTests
 
   object Escapes {
     /** For reasons unclear escape and unescape are a long ways from
-        being logical inverses. */
+      * being logical inverses. */
     val pairs = Map(
       "lt"    -> '<',
       "gt"    -> '>',
diff --git a/src/library/scala/xml/dtd/ElementValidator.scala b/src/library/scala/xml/dtd/ElementValidator.scala
index cc37e2b527..9ebed8d87c 100644
--- a/src/library/scala/xml/dtd/ElementValidator.scala
+++ b/src/library/scala/xml/dtd/ElementValidator.scala
@@ -95,7 +95,7 @@ class ElementValidator() extends Function1[Node,Boolean] {
   }
 
   /** check children, return true if conform to content model
-   *  @pre contentModel != null
+   *  @note contentModel != null
    */
   def check(nodes: Seq[Node]): Boolean = contentModel match {
     case ANY    => true
@@ -120,7 +120,7 @@ class ElementValidator() extends Function1[Node,Boolean] {
   }
 
   /** applies various validations - accumulates error messages in exc
-   *  @todo: fail on first error, ignore other errors (rearranging conditions)
+   *  @todo fail on first error, ignore other errors (rearranging conditions)
    */
   def apply(n: Node): Boolean =
     //- ? check children
diff --git a/src/library/scala/xml/include/XIncludeException.scala b/src/library/scala/xml/include/XIncludeException.scala
index 26c66f9b1d..a671f32dca 100644
--- a/src/library/scala/xml/include/XIncludeException.scala
+++ b/src/library/scala/xml/include/XIncludeException.scala
@@ -43,7 +43,7 @@ class XIncludeException(message: String) extends Exception(message) {
    * This method allows you to store the original exception.
    *
    * @param   nestedException   the underlying exception which
-   caused the XIncludeException to be thrown
+   * caused the XIncludeException to be thrown
    */
   def setRootCause(nestedException: Throwable ) {
     this.rootCause = nestedException
diff --git a/src/library/scala/xml/parsing/ConstructingParser.scala b/src/library/scala/xml/parsing/ConstructingParser.scala
index f029fc745a..00f195e9fd 100644
--- a/src/library/scala/xml/parsing/ConstructingParser.scala
+++ b/src/library/scala/xml/parsing/ConstructingParser.scala
@@ -25,28 +25,27 @@ object ConstructingParser {
 }
 
 /** An xml parser. parses XML and invokes callback methods of a MarkupHandler.
- *  Don't forget to call next.ch on a freshly instantiated parser in order to
- *  initialize it. If you get the parser from the object method, initialization
- *  is already done for you.
- *
- *<pre>
-object parseFromURL {
-  def main(args:Array[String]): Unit = {
-    val url = args(0);
-    val src = scala.io.Source.fromURL(url);
-    val cpa = scala.xml.parsing.ConstructingParser.fromSource(src, false); // fromSource initializes automatically
-    val doc = cpa.document();
-
-    // let's see what it is
-    val ppr = new scala.xml.PrettyPrinter(80,5);
-    val ele = doc.docElem;
-    Console.println("finished parsing");
-    val out = ppr.format(ele);
-    Console.println(out);
-  }
-}
-</pre>
- */
+  * Don't forget to call next.ch on a freshly instantiated parser in order to
+  * initialize it. If you get the parser from the object method, initialization
+  * is already done for you.
+  *
+  * {{{
+  * object parseFromURL {
+  *   def main(args:Array[String]): Unit = {
+  *     val url = args(0);
+  *     val src = scala.io.Source.fromURL(url);
+  *     val cpa = scala.xml.parsing.ConstructingParser.fromSource(src, false); // fromSource initializes automatically
+  *     val doc = cpa.document();
+  *
+  *     // let's see what it is
+  *     val ppr = new scala.xml.PrettyPrinter(80,5);
+  *     val ele = doc.docElem;
+  *     Console.println("finished parsing");
+  *     val out = ppr.format(ele);
+  *     Console.println(out);
+  *   }
+  * }
+  * }}} */
 class ConstructingParser(val input: Source, val preserveWS: Boolean)
 extends  ConstructingHandler
 with     ExternalSources
diff --git a/src/library/scala/xml/parsing/MarkupParser.scala b/src/library/scala/xml/parsing/MarkupParser.scala
index 2f7f48c765..fdc216c3cd 100644
--- a/src/library/scala/xml/parsing/MarkupParser.scala
+++ b/src/library/scala/xml/parsing/MarkupParser.scala
@@ -719,8 +719,7 @@ trait MarkupParser extends MarkupParserCommon with TokenTests
       nextch
   }
 
-  /**  "rec-xml/#ExtSubset" pe references may not occur within markup
-   declarations
+  /**  "rec-xml/#ExtSubset" pe references may not occur within markup declarations
    */
   def intSubset() {
     //Console.println("(DEBUG) intSubset()")