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

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

38 files changed, 222 insertions, 393 deletions

diff --git a/src/actors/scala/actors/Reaction.scala b/src/actors/scala/actors/Reaction.scala
index 753dd7da83..65584880f7 100644
--- a/src/actors/scala/actors/Reaction.scala
+++ b/src/actors/scala/actors/Reaction.scala
@@ -23,9 +23,9 @@ private[actors] class KillActorException extends Throwable with ControlException
  *    <code>java.lang.Runnable</code></a>.
  *  </p>
  *
- *  @deprecated("this class is going to be removed in a future release")
  *  @author Philipp Haller
  */
+@deprecated
 class Reaction(a: Actor, f: PartialFunction[Any, Any], msg: Any) extends ActorTask(a, () => {
   if (f == null)
     a.act()
diff --git a/src/compiler/scala/tools/ant/Pack200Task.scala b/src/compiler/scala/tools/ant/Pack200Task.scala
index d9aa8a1f5f..7d7d555226 100644
--- a/src/compiler/scala/tools/ant/Pack200Task.scala
+++ b/src/compiler/scala/tools/ant/Pack200Task.scala
@@ -99,7 +99,7 @@ class Pack200Task extends MatchingTask {
 \*============================================================================*/
 
   /** Gets the list of individual JAR files for processing.
-    * @returns The list of JAR files */
+    * @return The list of JAR files */
   private def getFileList: List[File] = {
     var files: List[File] = Nil
     val fs = getImplicitFileSet
diff --git a/src/compiler/scala/tools/ant/ScalaBazaar.scala b/src/compiler/scala/tools/ant/ScalaBazaar.scala
index 30fd8947f5..f560883a2d 100644
--- a/src/compiler/scala/tools/ant/ScalaBazaar.scala
+++ b/src/compiler/scala/tools/ant/ScalaBazaar.scala
@@ -177,19 +177,19 @@ package scala.tools.ant {
 \******************************************************************************/
 
     /** Gets the value of the file attribute in a Scala-friendly form.
-      * @returns The file as a file. */
+      * @return The file as a file. */
     private def getName: String =
       if (name.isEmpty) error("Name attribute must be defined first.")
       else name.get
 
     /** Gets the value of the file attribute in a Scala-friendly form.
-      * @returns The file as a file. */
+      * @return The file as a file. */
     private def getFile: File =
       if (file.isEmpty) error("Member 'file' is empty.")
       else getProject().resolveFile(file.get.toString())
 
     /** Gets the value of the adfile attribute in a Scala-friendly form.
-      * @returns The adfile as a file. */
+      * @return The adfile as a file. */
     private def getAdfile: File =
       if (adfile.isEmpty) error("Member 'adfile' is empty.")
       else getProject().resolveFile(adfile.get.toString())
diff --git a/src/compiler/scala/tools/ant/ScalaTool.scala b/src/compiler/scala/tools/ant/ScalaTool.scala
index e7912d8b59..f9f97140aa 100644
--- a/src/compiler/scala/tools/ant/ScalaTool.scala
+++ b/src/compiler/scala/tools/ant/ScalaTool.scala
@@ -166,12 +166,12 @@ class ScalaTool extends MatchingTask {
 \*============================================================================*/
 
     /** Gets the value of the classpath attribute in a Scala-friendly form.
-      * @returns The class path as a list of files. */
+      * @return The class path as a list of files. */
     private def getUnixclasspath: String =
       transposeVariableMarkup(classpath.mkString("", ":", "").replace('\\', '/'), "${", "}")
 
     /** Gets the value of the classpath attribute in a Scala-friendly form.
-      * @returns The class path as a list of files. */
+      * @return The class path as a list of files. */
     private def getWinclasspath: String =
       transposeVariableMarkup(classpath.mkString("", ";", "").replace('/', '\\'), "%", "%")
 
diff --git a/src/compiler/scala/tools/nsc/ScriptRunner.scala b/src/compiler/scala/tools/nsc/ScriptRunner.scala
index f9d4d7983a..0657a61133 100644
--- a/src/compiler/scala/tools/nsc/ScriptRunner.scala
+++ b/src/compiler/scala/tools/nsc/ScriptRunner.scala
@@ -240,7 +240,7 @@ object ScriptRunner
   /** Compile a script and then run the specified closure with
     * a classpath for the compiled script.
     *
-    * @returns true if compilation and the handler succeeds, false otherwise.
+    * @return true if compilation and the handler succeeds, false otherwise.
     */
   private def withCompiledScript(
     settings: GenericRunnerSettings,
@@ -300,7 +300,7 @@ object ScriptRunner
 
   /** Run a script after it has been compiled
    *
-   * @returns true if execution succeeded, false otherwise
+   * @return true if execution succeeded, false otherwise
    */
   private def runCompiled(
     settings: GenericRunnerSettings,
@@ -342,7 +342,7 @@ object ScriptRunner
   /** Run a script file with the specified arguments and compilation
    *  settings.
    *
-   * @returns true if compilation and execution succeeded, false otherwise.
+   * @return true if compilation and execution succeeded, false otherwise.
    */
   def runScript(
     settings: GenericRunnerSettings,
@@ -357,7 +357,7 @@ object ScriptRunner
 
   /** Run a command
    *
-   * @returns true if compilation and execution succeeded, false otherwise.
+   * @return true if compilation and execution succeeded, false otherwise.
    */
   def runCommand(
     settings: GenericRunnerSettings,
diff --git a/src/compiler/scala/tools/nsc/doc/SourcelessComments.scala b/src/compiler/scala/tools/nsc/doc/SourcelessComments.scala
index 0791c6fa51..46e45a861b 100644
--- a/src/compiler/scala/tools/nsc/doc/SourcelessComments.scala
+++ b/src/compiler/scala/tools/nsc/doc/SourcelessComments.scala
@@ -23,234 +23,155 @@ abstract class SourcelessComments {
     val comment = mutable.HashMap.empty[Symbol, DocComment]
 
     comment(NothingClass) = new DocComment("""
-      /** <p>
-        * Class <code>Nothing</code> is - together with class <a href="Null.html">
-        * <code>Null</code></a> - at the bottom of the
-        * <a href="http://scala-lang.org" target="_top">Scala</a> type
-        * hierarchy.
-        * </p>
-        * <p>
-        * Type <code>Nothing</code> is a subtype of every other type
-        * (including <a href="Null.html"><code>Null</code></a>); there
-        * exist <em>no instances</em> of this type. Even though type
-        * <code>Nothing</code> is empty, it is nevertheless useful as a
-        * type parameter. For instance, the <a href="http://scala-lang.org"
-        * target="_top">Scala</a> library defines a value
-        * <a href="Nil$object.html"><code>Nil</code></a> of type
-        * <code><a href="List.html">List</a>[Nothing]</code>. Because lists
-        * are covariant in <a href="http://scala-lang.org" target="_top">Scala</a>,
-        * this makes <a href="Nil$object.html"><code>Nil</code></a> an
-        * instance of <code><a href="List.html">List</a>[T]</code>, for
-        * any element type <code>T</code>.
-        * </p> */
+      /** Class `Nothing` is - together with class [[scala.Null]] - at the bottom of Scala's type hierarchy.
+        *
+        * Type `Nothing` is a subtype of every other type (including [[scala.Null]]); there exist ''no instances'' of
+        * this type. Even though type `Nothing` is empty, it is nevertheless useful as a type parameter. For instance,
+        * the Scala library defines a value [[scala.collection.immutable.Nil]] of type `List[Nothing]`. Because lists
+        * are covariant in Scala, this makes [[scala.collection.immutable.Nil]] an instance of `List[T]`, for any
+        * element of type `T`. */
       """)
 
      comment(NullClass) = new DocComment("""
-       /** <p>
-         * Class <code>Null</code> is - together with class <a href="Nothing.html">
-         * <code>Nothing</code> - at the bottom of the
-         * <a href="http://scala-lang.org" target="_top">Scala</a> type
-         * hierarchy.
-         * </p>
-         * <p>
-         * Type <code>Null</code> is a subtype of all reference types; its
-         * only instance is the <code>null</code> reference.
-         * Since <code>Null</code> is not a subtype of value types,
-         * <code>null</code> is not a member of any such type. For instance,
-         * it is not possible to assign <code>null</code> to a variable of
-         * type <a href="Int.html"><code>Int</code></a>.
-         * </p> */
+       /** Class `Null` is - together with class [[scala.Nothing]] - at the bottom of the Scala type hierarchy.
+         *
+         * Type `Null` is a subtype of all reference types; its only instance is the `null` reference. Since `Null` is
+         * not a subtype of value types, `null` is not a member of any such type. For instance, it is not possible to
+         * assign `null` to a variable of type [[scala.Int]]. */
        """)
 
      /*******************************************************************/
      /* Documentation for Any */
 
      comment(AnyClass) = new DocComment("""
-      /** <p>
-        * Class <code>Any</code> is the root of the <a
-        * href="http://scala-lang.org/"
-        * target="_top">Scala</a> class hierarchy. Every class in a
-        * <a href="http://scala-lang.org/" target="_top">Scala</a> execution
-        * environment inherits directly or indirectly from this class.
-        * Class <code>Any</code> has two direct subclasses:
-        * <a href="AnyRef.html"><code>AnyRef</code></a> and
-        * <a href="AnyVal.html"><code>AnyVal</code></a>.
-        * </p> */
+      /** Class `Any` is the root of the Scala class hierarchy. Every class in a Scala execution environment inherits
+        * directly or indirectly from this class. Class `Any` has two direct subclasses: [[scala.AnyRef]] and
+        * [[scala.AnyVal]]. */
       """)
 
     comment(Any_equals) = new DocComment("""
-      /** This method is used to compare the receiver object (<code>this</code>)
-        * with the argument object (<code>arg0</code>) for equivalence.
+      /** This method is used to compare the receiver object (`this`) with the argument object (`arg0`) for equivalence.
         *
-        * <p>
-        * The default implementations of this method is an <a
-        * href="http://en.wikipedia.org/wiki/Equivalence_relation">equivalence
-        * relation</a>:
-        *   <ul>
-        *  <li>It is reflexive: for any instance <code>x</code> of type <code>Any</code>,
-        *  <code>x.equals(x)</code> should return <code>true</code>.</li>
-        *  <li>It is symmetric: for any instances <code>x</code> and <code>y</code> of type
-        *  <code>Any</code>, <code>x.equals(y)</code> should return <code>true</code> if and only
-        *  if <code>y.equals(x)</code> returns <code>true</code>.</li>
-        *  <li>It is transitive: for any instances
-        *  <code>x</code>, <code>y</code>, and <code>z</code> of type <code>AnyRef</code>
-        *  if <code>x.equals(y)</code> returns <code>true</code> and
-        *  <code>y.equals(z)</code> returns
-        *  <code>true</code>, then <code>x.equals(z)</code> should return <code>true</code>.</li>
-        *</ul>
-        *</p>
+        * The default implementations of this method is an [http://en.wikipedia.org/wiki/Equivalence_relation equivalence
+        * relation]:
+        *  * It is reflexive: for any instance `x` of type `Any`, `x.equals(x)` should return `true`.
+        *  * It is symmetric: for any instances `x` and `y` of type `Any`, `x.equals(y)` should return `true` if and
+        *    only if `y.equals(x)` returns `true`.
+        *  * It is transitive: for any instances `x`, `y`, and `z` of type `AnyRef` if `x.equals(y)` returns `true` and
+        *    `y.equals(z)` returns `true`, then `x.equals(z)` should return `true`.
         *
-        * <p>
-        * If you override this method, you should verify that
-        * your implementation remains an equivalence relation.
-        * Additionally, when overriding this method it is often necessary to
-        * override <code>hashCode</code> to ensure that objects that are
-        * "equal" (<code>o1.equals(o2)</code> returns <code>true</code>)
-        * hash to the same <a href="Int.html"><code>Int</code></a>
-        * (<code>o1.hashCode.equals(o2.hashCode)</code>).
+        * If you override this method, you should verify that your implementation remains an equivalence relation.
+        * Additionally, when overriding this method it is often necessary to override `hashCode` to ensure that objects
+        * that are "equal" (`o1.equals(o2)` returns `true`) hash to the same [[scala.Int]]
+        * (`o1.hashCode.equals(o2.hashCode)`).
         *
         * @param arg0 the object to compare against this object for equality.
-        * @return <code>true</code> if the receiver object is equivalent to the argument; <code>false</code> otherwise.
-        * </p> */
+        * @return     `true` if the receiver object is equivalent to the argument; `false` otherwise. */
       """)
 
     comment(Any_==) = new DocComment("""
       /** `o == arg0` is the same as `o.equals(arg0)`.
-        * <p>
+        *
         * @param arg0 the object to compare against this object for equality.
-        * @return `true` if the receiver object is equivalent to the argument; `false` otherwise.
-        * </p> */
+        * @return     `true` if the receiver object is equivalent to the argument; `false` otherwise. */
       """)
 
     comment(Any_!=) = new DocComment("""
       /** `o != arg0` is the same as `!(o == (arg0))`.
-        * <p>
+        *
         * @param arg0 the object to compare against this object for dis-equality.
-        * @return `false` if the receiver object is equivalent to the argument; `true` otherwise.
-        * </p> */
+        * @return     `false` if the receiver object is equivalent to the argument; `true` otherwise. */
       """)
 
     comment(Any_toString) = new DocComment("""
       /** Returns a string representation of the object.
-        * <p>
+        *
         * The default representation is platform dependent.
         *
-        * @return a string representation of the object.
-        * </p>*/
+        * @return a string representation of the object. */
       """)
 
     comment(Any_asInstanceOf) = new DocComment("""
-      /**This method is used to cast the receiver object to be of type <code>T0</code>.
+      /** This method is used to cast the receiver object to be of type `T0`.
         *
-        * <p>Note that the success of a cast at runtime is modulo Scala's
-        * erasure semantics.  Therefore the expression
-        * <code>1.asInstanceOf[String]</code> will throw a
-        * <code>ClassCastException</code> at runtime, while the expression
-        * <code>List(1).asInstanceOf[List[String]]</code> will not.  In the
-        * latter example, because the type argument is erased as part of
-        * compilation it is not possible to check whether the contents of
-        * the list are of the requested typed.
+        * Note that the success of a cast at runtime is modulo Scala's erasure semantics.  Therefore the expression
+        * `1.asInstanceOf[String]` will throw a `ClassCastException` at runtime, while the expression
+        * `List(1).asInstanceOf[List[String]]` will not.  In the latter example, because the type argument is erased as
+        * part of compilation it is not possible to check whether the contents of the list are of the requested typed.
         *
-        * @throws ClassCastException if the receiver object is not an
-        * instance of erasure of type <code>T0</code>.
-        * @return the receiver object.
-        * </p> */
+        * @throws ClassCastException if the receiver object is not an instance of erasure of type `T0`.
+        * @return the receiver object. */
       """)
 
     comment(Any_isInstanceOf) = new DocComment("""
-      /** This method is used to test whether the dynamic type of the receiver object is <code>T0</code>.
+      /** This method is used to test whether the dynamic type of the receiver object is `T0`.
         *
-        * <p>Note that the test result of the test is modulo Scala's erasure
-        * semantics.  Therefore the expression
-        * <code>1.isInstanceOf[String]</code> will return
-        * <code>false</code>, while the expression
-        * <code>List(1).isInstanceOf[List[String]]</code> will return
-        * <code>true</code>.  In the latter example, because the type
-        * argument is erased as part of compilation it is not possible to
-        * check whether the contents of the list are of the requested typed.
+        * Note that the test result of the test is modulo Scala's erasure semantics.  Therefore the expression
+        * `1.isInstanceOf[String]` will return `false`, while the expression `List(1).isInstanceOf[List[String]]` will
+        * return `true`.  In the latter example, because the type argument is erased as part of compilation it is not
+        * possible to check whether the contents of the list are of the requested typed.
         *
-        * @return <code>true</code> if the receiver object is an
-        * instance of erasure of type <code>T0</code>; <code>false</code> otherwise. */
+        * @return `true` if the receiver object is an instance of erasure of type `T0`; `false` otherwise. */
       """)
 
     comment(Any_hashCode) = new DocComment("""
       /** Returns a hash code value for the object.
         *
-        * <p>
         * The default hashing algorithm is platform dependent.
         *
-        * Note that it is allowed for two objects to have identical hash
-        * codes (<code>o1.hashCode.equals(o2.hashCode)</code>) yet not be
-        * equal (<code>o1.equals(o2)</code> returns <code>false</code>).  A
-        * degenerate implementation could always return <code>0</code>.
-        * However, it is required that if two objects are equal
-        * (<code>o1.equals(o2)</code> returns <code>true</code>) that they
-        * have identical hash codes
-        * (<code>o1.hashCode.equals(o2.hashCode)</code>).  Therefore, when
-        * overriding this method, be sure to verify that the behavior is
-        * consistent with the <code>equals</code> method.
-        * </p>
+        * Note that it is allowed for two objects to have identical hash codes (`o1.hashCode.equals(o2.hashCode)`) yet
+        * not be equal (`o1.equals(o2)` returns `false`).  A degenerate implementation could always return `0`.
+        * However, it is required that if two objects are equal (`o1.equals(o2)` returns `true`) that they have
+        * identical hash codes (`o1.hashCode.equals(o2.hashCode)`).  Therefore, when overriding this method, be sure
+        * to verify that the behavior is consistent with the `equals` method.
         *
-        * <p>
-        * @return the hash code value for the object.
-        * </p> */
+        * @return the hash code value for the object. */
       """)
 
      /*******************************************************************/
      /* Documentation for AnyRef */
 
      comment(AnyRefClass) = new DocComment("""
-       /** <p>
-         * Class <code>AnyRef</code> is the root class of all
-         * <em>reference types</em>.
-         * </p> */
+       /** Class `AnyRef` is the root class of all ''reference types''. */
        """)
 
     comment(Object_==) = new DocComment("""
-      /** <code>o == arg0</code> is the same as <code>if (o eq null) arg0 eq null else o.equals(arg0)</code>.
-        * <p>
+      /** `o == arg0` is the same as `if (o eq null) arg0 eq null else o.equals(arg0)`.
+        *
         * @param arg0 the object to compare against this object for equality.
-        * @return <code>true</code> if the receiver object is equivalent to the argument; <code>false</code> otherwise.
-        * </p> */
+        * @return `true` if the receiver object is equivalent to the argument; `false` otherwise. */
       """)
 
     comment(Object_ne) = new DocComment("""
-      /** <code>o.ne(arg0)</code> is the same as <code>!(o.eq(arg0))</code>.
-        * <p>
+      /** `o.ne(arg0)` is the same as `!(o.eq(arg0))`.
+        *
         * @param arg0 the object to compare against this object for reference dis-equality.
-        * @return <code>false</code> if the argument is not a reference to the receiver object; <code>true</code> otherwise.
-        * </p> */
+        * @return `false` if the argument is not a reference to the receiver object; `true` otherwise. */
       """)
 
 
     comment(Object_finalize) = new DocComment("""
-      /** This method is called by the garbage collector on the receiver object when garbage
-        * collection determines that there are no more references to the object.
-        * <p>
-        * The details of when and if the <code>finalize</code> method are
-        * invoked, as well as the interaction between <code>finalize</code>
-        * and non-local returns and exceptions, are all platform dependent.
-        * </p> */
+      /** This method is called by the garbage collector on the receiver object when garbage collection determines that
+        * there are no more references to the object.
+        *
+        * The details of when and if the `finalize` method are invoked, as well as the interaction between `finalize`
+        * and non-local returns and exceptions, are all platform dependent. */
       """)
 
     comment(Object_clone) = new DocComment("""
       /** This method creates and returns a copy of the receiver object.
         *
-        * <p>
-        * The default implementation of the <code>clone</code> method is platform dependent.
+        * The default implementation of the `clone` method is platform dependent.
         *
-        * @return a copy of the receiver object.
-        * </p> */
+        * @return a copy of the receiver object. */
       """)
 
     comment(Object_getClass) = new DocComment("""
       /** Returns a representation that corresponds to the dynamic class of the receiver object.
         *
-        * <p>
         * The nature of the representation is platform dependent.
         *
-        * @return a representation that corresponds to the dynamic class of the receiver object.
-        * </p> */
+        * @return a representation that corresponds to the dynamic class of the receiver object. */
       """)
 
     comment(Object_notify) = new DocComment("""
@@ -262,113 +183,63 @@ abstract class SourcelessComments {
       """)
 
     comment(Object_eq) = new DocComment("""
-      /** This method is used to test whether the argument (<code>arg0</code>) is a reference to the
-        * receiver object (<code>this</code>).
-        *
-        * <p>
-        * The <code>eq</code> method implements an
-        * <a href="http://en.wikipedia.org/wiki/Equivalence_relation">equivalence relation</a> on non-null instances of
-        * <code>AnyRef</code>:
-        * <ul>
-        * <li>It is reflexive: for any non-null instance <code>x</code> of type <code>AnyRef</code>,
-        * <code>x.eq(x)</code> returns <code>true</code>.</li>
-        * <li>It is symmetric: for any non-null instances <code>x</code> and <code>y</code> of type
-        * <code>AnyRef</code>, <code>x.eq(y)</code> returns <code>true</code> if and only
-        * if <code>y.eq(x)</code> returns <code>true</code>.</li>
-        * <li>It is transitive: for any non-null instances
-        * <code>x</code>, <code>y</code>, and <code>z</code> of type <code>AnyRef</code>
-        * if <code>x.eq(y)</code> returns <code>true</code> and
-        * <code>y.eq(z)</code> returns
-        * <code>true</code>, then <code>x.eq(z)</code> returns <code>true</code>.</li>
-        * </ul>
-        * Additionally, the <code>eq</code> method has three other properties.
-        * <ul>
-        *  <li>It is consistent: for any non-null instances <code>x</code> and <code>y</code> of type <code>AnyRef</code>,
-        *    multiple invocations of <code>x.eq(y)</code> consistently returns <code>true</code>
-        *    or consistently returns <code>false</code>.</li>
-        *  <li>For any non-null instance <code>x</code> of type <code>AnyRef</code>,
-        *   <code>x.eq(null)</code> and <code>null.eq(x)</code> returns <code>false</code>.</li>
-        *  <li><code>null.eq(null)</code> returns <code>true</code>.</li>
-        *</ul>
-        *</p>
-        *
-        * <p> When overriding the <code>equals</code> or
-        * <code>hashCode</code> methods, it is important to ensure that
-        * their behavior is consistent with reference equality.  Therefore,
-        * if two objects are references to each other (<code>o1 eq
-        * o2</code>), they should be equal to each other (<code>o1 ==
-        * o2</code>) and they should hash to the same value
-        * (<code>o1.hashCode == o2.hashCode</code>).</p>
+      /** This method is used to test whether the argument (`arg0`) is a reference to the
+        * receiver object (`this`).
+        *
+        * The `eq` method implements an [http://en.wikipedia.org/wiki/Equivalence_relation equivalence relation] on
+        * non-null instances of `AnyRef`:
+        *  * It is reflexive: for any non-null instance `x` of type `AnyRef`, `x.eq(x)` returns `true`.
+        *  * It is symmetric: for any non-null instances `x` and `y` of type `AnyRef`, `x.eq(y)` returns `true` if and
+        *    only if `y.eq(x)` returns `true`.
+        *  * It is transitive: for any non-null instances `x`, `y`, and `z` of type `AnyRef` if `x.eq(y)` returns `true`
+        *    and `y.eq(z)` returns `true`, then `x.eq(z)` returns `true`.
+        *
+        * Additionally, the `eq` method has three other properties.
+        *  * It is consistent: for any non-null instances `x` and `y` of type `AnyRef`, multiple invocations of
+        *    `x.eq(y)` consistently returns `true` or consistently returns `false`.
+        *  * For any non-null instance `x` of type `AnyRef`, `x.eq(null)` and `null.eq(x)` returns `false`.
+        *  * `null.eq(null)` returns `true`.
+        *
+        * When overriding the `equals` or `hashCode` methods, it is important to ensure that their behavior is
+        * consistent with reference equality.  Therefore, if two objects are references to each other (`o1 eq o2`), they
+        * should be equal to each other (`o1 == o2`) and they should hash to the same value (`o1.hashCode == o2.hashCode`).
         *
         * @param arg0 the object to compare against this object for reference equality.
-        * @return <code>true</code> if the argument is a reference to the receiver object; <code>false</code> otherwise.
-        * </p> */
+        * @return `true` if the argument is a reference to the receiver object; `false` otherwise. */
       """)
 
     /*******************************************************************/
 
     comment(AnyValClass) = new DocComment("""
-      /** <p>
-        * Class <code>AnyVal</code> is the root class of all
-        * <em>value types</em>.
-        * </p>
-        * <p>
-        * <code>AnyVal</code> has a fixed number subclasses, which
-        * describe values which are not implemented as objects in the
+      /** Class `AnyVal` is the root class of all ''value types''.
+        *
+        * `AnyVal` has a fixed number of subclasses, which describe values which are not implemented as objects in the
         * underlying host system.
-        * </p>
-        * <p>
-        *  Classes <a href="Double.html"><code>Double</code></a>,
-        * <a href="Float.html"><code>Float</code></a>,
-        * <a href="Long.html"><code>Long</code></a>,
-        * <a href="Int.html"><code>Int</code></a>,
-        * <a href="Char.html"><code>Char</code></a>,
-        * <a href="Short.html"><code>Short</code></a>, and
-        * <a href="Byte.html"><code>Byte</code></a> are together called
-        * <em>numeric value types</em>.
-        * Classes <a href="Byte.html"><code>Byte</code></a>,
-        * <a href="Short.html"><code>Short</code></a>, or
-        * <a href="Char.html"><code>Char</code></a>
-        * are called <em>subrange types</em>. Subrange types, as well as
-        * <a href="Int.html"><code>Int</code></a> and
-        * <a href="Long.html"><code>Long</code></a> are called
-        * <em>integer types</em>, whereas
-        * <a href="Float.html"><code>Float</code></a> and
-        * <a href="Double.html"><code>Double</code></a> are called
-        * <em>floating point types</em>.
-        * </p> */
+        *
+        * Classes [[scala.Double]], [[scala.Float]], [[scala.Long]], [[scala.Int]], [[scala.Char]], [[scala.Short]],
+        * and [[scala.Byte]] are together called ''numeric value types''. Classes [[scala.Byte]], [[scala.Short]], and
+        * [[scala.Char]] are called ''subrange types''. Subrange types, as well as [[scala.Int]] and [[scala.Long]] are
+        * called ''integer types'', whereas [[scala.Float]] and [[scala.Double]] are called ''floating point types''. */
       """)
 
     comment(BooleanClass) = new DocComment("""
-      /** <p>
-        * Class <code>Boolean</code> has only two values: <code>true</code>
-        * and <code>false</code>.
-        * </p> */
+      /** Class `Boolean` has only two values: `true` and `false`. */
       """)
 
     comment(UnitClass) = new DocComment("""
-      /** <p>
-        * Class <code>Unit</code> has only one value: <code>()</code>.
-        * </p> */
+      /** Class `Unit` has only one value: `()`. */
       """)
 
     List(ByteClass, CharClass, DoubleClass, LongClass, FloatClass, IntClass, ShortClass) foreach { sym =>
       val maxValue = "MAX_" + sym.name.toString().toUpperCase()
       val minValue = "MIN_" + sym.name.toString().toUpperCase()
       comment(sym) = new DocComment("""
-        /** <p>
-          * Class <code>""" + sym.name + """</code> belongs to the value
-          * classes whose instances are not represented as objects by the
-          * underlying host system.  There is an implicit conversion from
-          * instances of <code>""" + sym.name + """</code> to instances of
-          * <a href="runtime/Rich""" + sym.name + """.html"><code>runtime.Rich""" + sym.name + """</code></a> which
-          * provides useful non-primitive operations.  All value classes inherit
-          * from class <a href="AnyVal.html"><code>AnyVal</code></a>.
-          * </p>
-          * <p>
-          *  Values <code>""" + maxValue + """</code> and <code>""" + minValue + """</code>
-          *  are in defined in object <a href="Math$object.html">scala.Math</a>.
-          * </p> */
+        /** Class `""" + sym.name + """` belongs to the value classes whose instances are not represented as objects by
+          * the underlying host system.  There is an implicit conversion from instances of `""" + sym.name + """` to
+          * instances of [[scala.runtime.Rich""" + sym.name + """]] which provides useful non-primitive operations.
+          * All value classes inherit from class [[scala.AnyVal]].
+          *
+          * Values `""" + maxValue + """` and `""" + minValue + """` are defined in object [[scala.Math]]. */
         """)
     }
 
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()")