2nd round of clean ups (see r25285)

99 files changed, 1519 insertions, 1515 deletions

diff --git a/src/library/scala/Application.scala b/src/library/scala/Application.scala
index 021e499530..5b1098bd72 100644
--- a/src/library/scala/Application.scala
+++ b/src/library/scala/Application.scala
@@ -47,7 +47,7 @@ import scala.compat.Platform.currentTime
  *    fail to optimize or JIT the code in the body of an `object` extending
  *    `Application`.  This can lead to a significant performance degradation.
  *
- *  It is recommended to use the `[[scala.App]]` trait instead.
+ *  It is recommended to use the [[scala.App]] trait instead.
  *  {{{
  *  object Main {
  *    def main(args: Array[String]) {
diff --git a/src/library/scala/Array.scala b/src/library/scala/Array.scala
index 060a5250ba..a83f9f5679 100644
--- a/src/library/scala/Array.scala
+++ b/src/library/scala/Array.scala
@@ -35,6 +35,14 @@ class FallbackArrayBuilding {
 }
 
 /** Utility methods for operating on arrays.
+ *  For example:
+ *  {{{
+ *  val a = Array(1, 2)
+ *  val b = Array.ofDim[Int](2)
+ *  val c = Array.concat(a, b)
+ *  }}}
+ *  where the array objects `a`, `b` and `c` have respectively the values
+ *  `Array(1, 2)`, `Array(0, 0)` and `Array(1, 2, 0, 0)`.
  *
  *  @author Martin Odersky
  *  @version 1.0
diff --git a/src/library/scala/Console.scala b/src/library/scala/Console.scala
index 7eadcb7b09..5e62df6c71 100644
--- a/src/library/scala/Console.scala
+++ b/src/library/scala/Console.scala
@@ -253,7 +253,7 @@ object Console {
    */
   def printf(text: String, args: Any*) { out.print(text format (args : _*)) }
 
-  /** Read a full line from the default input.  Returns <code>null</code> if the end of the
+  /** Read a full line from the default input.  Returns `null` if the end of the
    * input stream has been reached.
    *
    * @return the string read from the terminal or null if the end of stream was reached.
@@ -397,14 +397,14 @@ object Console {
       s.toDouble
   }
 
-  /** Reads in some structured input (from the default input), specified by a format specifier.
-   *  See class <code>java.text.MessageFormat</code> for details of
+  /** Reads in some structured input (from the default input), specified by
+   *  a format specifier. See class `java.text.MessageFormat` for details of
    *  the format specification.
    *
    *  @param format the format of the input.
    *  @return a list of all extracted values.
-   *  @throws java.io.EOFException if the end of the
-   *  input stream has been reached.
+   *  @throws java.io.EOFException if the end of the input stream has been
+   *          reached.
    */
   def readf(format: String): List[Any] = {
     val s = readLine()
@@ -414,8 +414,9 @@ object Console {
       textComponents(new MessageFormat(format).parse(s))
   }
 
-  /** Reads in some structured input (from the default input), specified by a format specifier, returning
-   *  only the first value extracted, according to the format specification.
+  /** Reads in some structured input (from the default input), specified by
+   *  a format specifier, returning only the first value extracted, according
+   *  to the format specification.
    *
    *  @param format format string, as accepted by `readf`.
    *  @return The first value that was extracted from the input
diff --git a/src/library/scala/Enumeration.scala b/src/library/scala/Enumeration.scala
index 61609be22f..563b2d70c4 100644
--- a/src/library/scala/Enumeration.scala
+++ b/src/library/scala/Enumeration.scala
@@ -11,18 +11,17 @@ package scala
 import scala.collection.{ mutable, immutable, generic, SetLike }
 import java.lang.reflect.{ Modifier, Method => JMethod, Field => JField }
 
-/**
- *    Defines a finite set of values specific to the enumeration. Typically
- *    these values enumerate all possible forms something can take and provide a
- *    lightweight alternative to case classes.
+/** Defines a finite set of values specific to the enumeration. Typically
+ *  these values enumerate all possible forms something can take and provide
+ *  a lightweight alternative to case classes.
  *
- *    Each call to a `Value` method adds a new unique value to the
- *    enumeration. To be accessible, these values are usually defined as
- *    `val` members of the evaluation.
+ *  Each call to a `Value` method adds a new unique value to the enumeration.
+ *  To be accessible, these values are usually defined as `val` members of
+ *  the evaluation.
  *
- *    All values in an enumeration share a common, unique type defined as the
- *    `Value` type member of the enumeration (`Value`
- *    selected on the stable identifier path of the enumeration instance).
+ *  All values in an enumeration share a common, unique type defined as the
+ *  `Value` type member of the enumeration (`Value` selected on the stable
+ *  identifier path of the enumeration instance).
  *
  * @example {{{
  *  object Main extends Application {
@@ -108,29 +107,30 @@ abstract class Enumeration(initial: Int, names: String*) extends Serializable {
    */
   final def apply(x: Int): Value = vmap(x)
 
-  /** Returns a Value from this Enumeration whose name matches
-   * the argument <var>s</var>.
+  /**
+   * Return a `Value` from this `Enumeration` whose name matches
+   * the argument `s`.
    *
-   * You can pass a String* set of names to the constructor, or
-   * initialize each Enumeration with Value(String). Otherwise, the
-   * names are determined automatically through reflection.
+   * You can pass a String* set of names to the constructor, or initialize
+   * each `Enumeration` with `Value(String)`. Otherwise, the names are
+   * determined automatically through reflection.
    *
    * Note the change here wrt 2.7 is intentional. You should know whether
-   * a name is in an Enumeration beforehand. If not, just use find on
+   * a name is in an `Enumeration` beforehand. If not, just use find on
    * values.
    *
-   * @param  s an Enumeration name
-   * @return   the Value of this Enumeration if its name matches <var>s</var>
-   * @throws   java.util.NoSuchElementException if no Value with a matching
-   *           name is in this Enumeration
+   * @param  s an `Enumeration` name
+   * @return   the `Value` of this `Enumeration` if its name matches `s`
+   * @throws   java.util.NoSuchElementException if no `Value` with a matching
+   *           name is in this `Enumeration`
    */
   final def withName(s: String): Value = values.find(_.toString == s).get
 
   /** Creates a fresh value, part of this enumeration. */
   protected final def Value: Value = Value(nextId)
 
-  /** Creates a fresh value, part of this enumeration, identified by the integer
-   *  `i`.
+  /** Creates a fresh value, part of this enumeration, identified by the
+   *  integer `i`.
    *
    *  @param i An integer that identifies this value at run-time. It must be
    *           unique amongst all values of the enumeration.
@@ -197,16 +197,15 @@ abstract class Enumeration(initial: Int, names: String*) extends Serializable {
     override def hashCode: Int = id.##
   }
 
-  /** A class implementing the <a href="Enumeration.Value.html"
-   *  target="contentFrame">`Value`</a> type. This class can be
-   *  overridden to change the enumeration's naming and integer identification
-   *  behaviour.
+  /** A class implementing the [[scala.Enumeration.Value]] type. This class
+   *  can be overridden to change the enumeration's naming and integer
+   *  identification behaviour.
    */
   @SerialVersionUID(0 - 3501153230598116017L)
   protected class Val(i: Int, name: String) extends Value with Serializable {
-    def this(i: Int)        = this(i, nextNameOrNull)
-    def this(name: String)  = this(nextId, name)
-    def this()              = this(nextId)
+    def this(i: Int)       = this(i, nextNameOrNull)
+    def this(name: String) = this(nextId, name)
+    def this()             = this(nextId)
 
     assert(!vmap.isDefinedAt(i), "Duplicate id: " + i)
     vmap(i) = this
@@ -226,9 +225,10 @@ abstract class Enumeration(initial: Int, names: String*) extends Serializable {
     }
   }
 
-  /** A class for sets of values
+  /** A class for sets of values.
    *  Iterating through this set will yield values in increasing order of their ids.
-   *  @param   ids   The set of ids of values, organized as a SortedSet.
+   *
+   *  @param ids The set of ids of values, organized as a `SortedSet`.
    */
   class ValueSet private[Enumeration] (val ids: immutable.SortedSet[Int]) extends Set[Value] with SetLike[Value, ValueSet] {
     override def empty = ValueSet.empty
diff --git a/src/library/scala/Function.scala b/src/library/scala/Function.scala
index a6e2a2d056..0e2d357892 100644
--- a/src/library/scala/Function.scala
+++ b/src/library/scala/Function.scala
@@ -1,7 +1,7 @@
 /*                     __                                               *\
 **     ________ ___   / /  ___     Scala API                            **
 **    / __/ __// _ | / /  / _ |    (c) 2003-2011, LAMP/EPFL             **
-**  __\ \/ /__/ __ |/ /__/ __ |                                         **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
 ** /____/\___/_/ |_/____/_/ | |                                         **
 **                          |/                                          **
 \*                                                                      */
@@ -16,9 +16,8 @@ package scala
  *  @version 1.0, 29/11/2006
  */
 object Function {
-  /** Given a sequence of functions <code>f<sub>1</sub></code>, ...,
-   *  <code>f<sub>n</sub></code>, return the function <code>f<sub>1</sub>
-   *  andThen ... andThen f<sub>n</sub></code>.
+  /** Given a sequence of functions `f,,1,,`, ..., `f,,n,,`, return the
+   *  function `f,,1,, andThen ... andThen f,,n,,`.
    *
    *  @param fs The given sequence of functions
    *  @return   ...
@@ -28,15 +27,17 @@ object Function {
   /** The constant function */
   def const[T, U](x: T)(y: U): T = x
 
-  /** Turns a function `A => Option[B]` into a `PartialFunction[A, B]`.  Important note:
-   *  this transformation implies the original function will be called 2 or more
-   *  times on each logical invocation, because the only way to supply an implementation
-   *  of isDefinedAt is to call the function and examine the return value.
+  /** Turns a function `A => Option[B]` into a `PartialFunction[A, B]`.
    *
-   *  @param   f    a function T => Option[R]
+   *  '''Important note''': this transformation implies the original function
+   *  will be called 2 or more times on each logical invocation, because the
+   *  only way to supply an implementation of `isDefinedAt` is to call the
+   *  function and examine the return value.
+   *
+   *  @param   f    a function `T => Option[R]`
    *  @return       a partial function defined for those inputs where
-   *                f returns Some(_) and undefined where f returns None.
-   *  @see PartialFunction#lift
+   *                f returns `Some(_)` and undefined where `f` returns `None`.
+   *  @see [[scala.PartialFunction#lift]]
    */
   def unlift[T, R](f: T => Option[R]): PartialFunction[T, R] = new PartialFunction[T, R] {
     def apply(x: T): R = f(x).get
diff --git a/src/library/scala/Math.scala b/src/library/scala/Math.scala
index 706537333a..87db3ea877 100644
--- a/src/library/scala/Math.scala
+++ b/src/library/scala/Math.scala
@@ -9,9 +9,9 @@
 
 package scala
 
-/** The object <code>Math</code> contains methods for performing basic numeric
- *  operations such as the elementary exponential, logarithm, square root, and
- *  trigonometric functions.
+/** The object `Math` contains methods for performing basic numeric
+ *  operations such as the elementary exponential, logarithm, square root,
+ *  and trigonometric functions.
  */
 @deprecated("use the scala.math package object instead.\n(Example package object usage: scala.math.Pi )", "2.8.0")
 object Math extends MathCommon {
@@ -92,4 +92,4 @@ object Math extends MathCommon {
   /** Positive infinity of type [[scala.Double]]. */
   @deprecated("Use `scala.Double.PositiveInfinity` instead", "2.8.0")
   val POS_INF_DOUBLE = java.lang.Double.POSITIVE_INFINITY
-}
\ No newline at end of file
+}
diff --git a/src/library/scala/MathCommon.scala b/src/library/scala/MathCommon.scala
index a2450fd461..b7b54d50fa 100644
--- a/src/library/scala/MathCommon.scala
+++ b/src/library/scala/MathCommon.scala
@@ -9,23 +9,22 @@
 
 package scala
 
-/** Common code between the deprecated scala.Math object and
- *  the scala.math package object.
+/** Common code between the deprecated `scala.Math` object and
+ *  the `scala.math` package object.
  */
 private[scala] class MathCommon {
-  /** The <code>double</code> value that is closer than any other to
-   *  <code>e</code>, the base of the natural logarithms.
+  /** The `double` value that is closer than any other to `e`, the base of
+   *  the natural logarithms.
    */
   val E = java.lang.Math.E
 
-  /** The <code>double</code> value that is closer than any other to
-   *  <code>pi</code>, the ratio of the circumference of a circle to its
-   *  diameter.
+  /** The `double` value that is closer than any other to `pi`, the ratio of
+   *  the circumference of a circle to its diameter.
    */
   val Pi = java.lang.Math.PI
 
-  /** Returns a <code>double</code> value with a positive sign, greater than
-   *  or equal to <code>0.0</code> and less than <code>1.0</code>.
+  /** Returns a `double` value with a positive sign, greater than or equal
+   *  to `0.0` and less than `1.0`.
    */
   def random: Double = java.lang.Math.random()
 
@@ -40,7 +39,7 @@ private[scala] class MathCommon {
    *  angle measured in radians.
    *
    *  @param  x an angle, in degrees
-   *  @return the measurement of the angle <code>x</code> in radians.
+   *  @return the measurement of the angle `x` in radians.
    */
   def toRadians(x: Double): Double = java.lang.Math.toRadians(x)
 
@@ -48,16 +47,15 @@ private[scala] class MathCommon {
    *  angle measured in degrees.
    *
    *  @param  x angle, in radians
-   *  @return the measurement of the angle <code>x</code> in degrees.
+   *  @return the measurement of the angle `x` in degrees.
    */
   def toDegrees(x: Double): Double = java.lang.Math.toDegrees(x)
 
-  /** Returns Euler's number <code>e</code> raised to the power of a
-   *  <code>double</code> value.
+  /** Returns Euler's number `e` raised to the power of a `double` value.
    *
-   *  @param  x the exponent to raise <code>e</code> to.
-   *  @return the value <code>e<sup>a</sup></code>, where <code>e</code>
-   *          is the base of the natural logarithms.
+   *  @param  x the exponent to raise `e` to.
+   *  @return the value `e^a^`, where `e` is the base of the natural
+   *          logarithms.
    */
   def exp(x: Double): Double = java.lang.Math.exp(x)
   def log(x: Double): Double = java.lang.Math.log(x)
@@ -67,23 +65,22 @@ private[scala] class MathCommon {
   def ceil(x: Double): Double = java.lang.Math.ceil(x)
   def floor(x: Double): Double = java.lang.Math.floor(x)
 
-  /** Returns the <code>double</code> value that is closest in value to the
+  /** Returns the `double` value that is closest in value to the
    *  argument and is equal to a mathematical integer.
    *
-   *  @param  x a <code>double</code> value
+   *  @param  x a `double` value
    *  @return the closest floating-point value to a that is equal to a
    *          mathematical integer.
    */
   def rint(x: Double): Double = java.lang.Math.rint(x)
 
-  /** Converts rectangular coordinates <code>(x, y)</code> to polar
-   *  <code>(r, theta)</code>.
+  /** Converts rectangular coordinates `(x, y)` to polar `(r, theta)`.
    *
    *  @param  x the ordinate coordinate
    *  @param  y the abscissa coordinate
-   *  @return the <em>theta</em> component of the point <code>(r, theta)</code>
-   *          in polar coordinates that corresponds to the point
-   *          <code>(x, y)</code> in Cartesian coordinates.
+   *  @return the ''theta'' component of the point `(r, theta)` in polar
+   *          coordinates that corresponds to the point `(x, y)` in
+   *          Cartesian coordinates.
    */
   def atan2(y: Double, x: Double): Double = java.lang.Math.atan2(y, x)
 
@@ -92,15 +89,14 @@ private[scala] class MathCommon {
    *
    *  @param x the base.
    *  @param y the exponent.
-   *  @return the value <code>x<sup>y</sup></code>.
+   *  @return the value `x^y^`.
    */
   def pow(x: Double, y: Double): Double = java.lang.Math.pow(x, y)
 
-  /** Returns the closest <code>long</code> to the argument.
+  /** Returns the closest `long` to the argument.
    *
-   *  @param  x a floating-point value to be rounded to a <code>long</code>.
-   *  @return the value of the argument rounded to the nearest
-   *          <code>long</code> value.
+   *  @param  x a floating-point value to be rounded to a `long`.
+   *  @return the value of the argument rounded to the nearest`long` value.
    */
   def round(x: Float): Int = java.lang.Math.round(x)
   def round(x: Double): Long = java.lang.Math.round(x)
diff --git a/src/library/scala/Predef.scala b/src/library/scala/Predef.scala
index acc9e2b3ad..124858273d 100644
--- a/src/library/scala/Predef.scala
+++ b/src/library/scala/Predef.scala
@@ -15,9 +15,8 @@ import generic.CanBuildFrom
 import annotation.{ elidable, implicitNotFound }
 import annotation.elidable.ASSERTION
 
-/** The <code>Predef</code> object provides definitions that are
- *  accessible in all Scala compilation units without explicit
- *  qualification.
+/** The `Predef` object provides definitions that are accessible in all Scala
+ *  compilation units without explicit qualification.
  */
 object Predef extends LowPriorityImplicits {
   /** Return the runtime representation of a class type.  This is a stub method.
@@ -76,9 +75,9 @@ object Predef extends LowPriorityImplicits {
 
   // errors and asserts -------------------------------------------------
 
-  /** Tests an expression, throwing an AssertionError if false.
-   *  Calls to this method will not be generated if -Xelide-below
-   *  is at least ASSERTION.
+  /** Tests an expression, throwing an `AssertionError` if false.
+   *  Calls to this method will not be generated if `-Xelide-below`
+   *  is at least `ASSERTION`.
    *
    *  @see elidable
    *  @param p   the expression to test
@@ -89,9 +88,9 @@ object Predef extends LowPriorityImplicits {
       throw new java.lang.AssertionError("assertion failed")
   }
 
-  /** Tests an expression, throwing an AssertionError if false.
-   *  Calls to this method will not be generated if -Xelide-below
-   *  is at least ASSERTION.
+  /** Tests an expression, throwing an `AssertionError` if false.
+   *  Calls to this method will not be generated if `-Xelide-below`
+   *  is at least `ASSERTION`.
    *
    *  @see elidable
    *  @param p   the expression to test
@@ -103,11 +102,11 @@ object Predef extends LowPriorityImplicits {
       throw new java.lang.AssertionError("assertion failed: "+ message)
   }
 
-  /** Tests an expression, throwing an AssertionError if false.
+  /** Tests an expression, throwing an `AssertionError` if false.
    *  This method differs from assert only in the intent expressed:
    *  assert contains a predicate which needs to be proven, while
    *  assume contains an axiom for a static checker.  Calls to this method
-   *  will not be generated if -Xelide-below is at least ASSERTION.
+   *  will not be generated if `-Xelide-below` is at least `ASSERTION`.
    *
    *  @see elidable
    *  @param p   the expression to test
@@ -118,11 +117,11 @@ object Predef extends LowPriorityImplicits {
       throw new java.lang.AssertionError("assumption failed")
   }
 
-  /** Tests an expression, throwing an AssertionError if false.
+  /** Tests an expression, throwing an `AssertionError` if false.
    *  This method differs from assert only in the intent expressed:
    *  assert contains a predicate which needs to be proven, while
    *  assume contains an axiom for a static checker.  Calls to this method
-   *  will not be generated if -Xelide-below is at least ASSERTION.
+   *  will not be generated if `-Xelide-below` is at least `ASSERTION`.
    *
    *  @see elidable
    *  @param p   the expression to test
@@ -134,8 +133,8 @@ object Predef extends LowPriorityImplicits {
       throw new java.lang.AssertionError("assumption failed: "+ message)
   }
 
-  /** Tests an expression, throwing an IllegalArgumentException if false.
-   *  This method is similar to assert, but blames the caller of the method
+  /** Tests an expression, throwing an `IllegalArgumentException` if false.
+   *  This method is similar to `assert`, but blames the caller of the method
    *  for violating the condition.
    *
    *  @param p   the expression to test
@@ -145,8 +144,8 @@ object Predef extends LowPriorityImplicits {
       throw new IllegalArgumentException("requirement failed")
   }
 
-  /** Tests an expression, throwing an IllegalArgumentException if false.
-   *  This method is similar to assert, but blames the caller of the method
+  /** Tests an expression, throwing an `IllegalArgumentException` if false.
+   *  This method is similar to `assert`, but blames the caller of the method
    *  for violating the condition.
    *
    *  @param p   the expression to test
@@ -341,12 +340,12 @@ object Predef extends LowPriorityImplicits {
    *
    * @note we need a new type constructor `<:<` and evidence `conforms`,
    * as reusing `Function1` and `identity` leads to ambiguities in
-   * case of type errors (any2stringadd is inferred)
+   * case of type errors (`any2stringadd` is inferred)
    *
    * To constrain any abstract type T that's in scope in a method's
    * argument list (not just the method's own type parameters) simply
-   * add an implicit argument of type `T <:< U`, where U is the required
-   * upper bound; or for lower-bounds, use: `L <:< T`, where L is the
+   * add an implicit argument of type `T <:< U`, where `U` is the required
+   * upper bound; or for lower-bounds, use: `L <:< T`, where `L` is the
    * required lower bound.
    *
    * In part contributed by Jason Zaugg.
@@ -360,7 +359,7 @@ object Predef extends LowPriorityImplicits {
 
   /** An instance of `A =:= B` witnesses that the types `A` and `B` are equal.
    *
-   * @see <:< for expressing subtyping constraints
+   * @see `<:<` for expressing subtyping constraints
    */
   @implicitNotFound(msg = "Cannot prove that ${From} =:= ${To}.")
   sealed abstract class =:=[From, To] extends (From => To) with Serializable
@@ -383,7 +382,7 @@ object Predef extends LowPriorityImplicits {
 
   object DummyImplicit {
 
-    /** An implicit value yielding a DummyImplicit.
+    /** An implicit value yielding a `DummyImplicit`.
      *   @see fallbackCanBuildFrom in Array.scala
      */
     implicit def dummyImplicit: DummyImplicit = new DummyImplicit
diff --git a/src/library/scala/Product.scala b/src/library/scala/Product.scala
index 1dbf46b4c2..cb316f2da3 100644
--- a/src/library/scala/Product.scala
+++ b/src/library/scala/Product.scala
@@ -8,32 +8,32 @@
 
 package scala
 
-/** Base trait for all products, which in the standard library include at least
- *  [[scala.Product1]] through [[scala.Product22]] and therefore also their
- *  subclasses [[scala.Tuple1]] through [[scala.Tuple22]].  In addition, all case
- *  classes implement Product with synthetically generated methods.
+/** Base trait for all products, which in the standard library include at
+ *  least [[scala.Product1]] through [[scala.Product22]] and therefore also
+ *  their subclasses [[scala.Tuple1]] through [[scala.Tuple22]].  In addition,
+ *  all case classes implement `Product` with synthetically generated methods.
  *
  *  @author  Burak Emir
  *  @version 1.0
  *  @since   2.3
  */
 trait Product extends Equals {
-  /** The nth element of this product, 0-based.  In other words, for a
-   *  product `A(x_1, ..., x_k)`, returns x_(n+1) where 0 < n < k.
+  /** The n^th^ element of this product, 0-based.  In other words, for a
+   *  product `A(x,,1,,, ..., x,,k,,)`, returns `x,,(n+1),, where `0 < n < k`.
    *
    *  @param    n   the index of the element to return
-   *  @throws       IndexOutOfBoundsException
+   *  @throws       `IndexOutOfBoundsException`
    *  @return       the element `n` elements after the first element
    */
   def productElement(n: Int): Any
 
   /** The size of this product.
-   *  @return     for a product `A(x_1, ..., x_k)`, returns `k`
+   *  @return     for a product `A(x,,1,,, ..., x,,k,,)`, returns `k`
    */
   def productArity: Int
 
   /** An iterator over all the elements of this product.
-   *  @return     in the default implementation, an Iterator[Any]
+   *  @return     in the default implementation, an `Iterator[Any]`
    */
   def productIterator: Iterator[Any] = new Iterator[Any] {
     private var c: Int = 0
@@ -47,7 +47,7 @@ trait Product extends Equals {
 
   /** A string used in the `toString` methods of derived classes.
    *  Implementations may override this method to prepend a string prefix
-   *  to the result of toString methods.
+   *  to the result of `toString` methods.
    *
    *  @return   in the default implementation, the empty string
    */
diff --git a/src/library/scala/Responder.scala b/src/library/scala/Responder.scala
index 2c6556d4a4..919ba130d4 100644
--- a/src/library/scala/Responder.scala
+++ b/src/library/scala/Responder.scala
@@ -20,8 +20,7 @@ package scala
  */
 object Responder {
 
-  /** Creates a responder that answer continuations with the constant
-   *  <code>a</code>.
+  /** Creates a responder that answer continuations with the constant `a`.
    *
    *  @param x ...
    *  @return ...
@@ -30,15 +29,15 @@ object Responder {
     def respond(k: A => Unit) = k(x)
   }
 
-  /** Executes <code>x</code> and returns <code>true</code>, useful
-   *  as syntactic convenience in for comprehensions.
+  /** Executes `x` and returns `'''true'''`, useful as syntactic
+   *  convenience in for comprehensions.
    *
    *  @param x ...
    *  @return ...
    */
   def exec[A](x: => Unit): Boolean = { x; true }
 
-  /** runs a responder, returning an optional result
+  /** Runs a responder, returning an optional result.
   */
   def run[A](r: Responder[A]): Option[A] = {
     var result: Option[A] = None
@@ -92,4 +91,3 @@ abstract class Responder[+A] extends Serializable {
 
   override def toString = "Responder"
 }
-
diff --git a/src/library/scala/SerialVersionUID.scala b/src/library/scala/SerialVersionUID.scala
index 5e1b07b9b9..0cb924c3d4 100644
--- a/src/library/scala/SerialVersionUID.scala
+++ b/src/library/scala/SerialVersionUID.scala
@@ -6,13 +6,10 @@
 **                          |/                                          **
 */
 
-
-
 package scala
 
-
 /**
- * Annotation for specifying the <code>static SerialVersionUID</code> field
+ * Annotation for specifying the `static SerialVersionUID` field
  * of a serializable class.
  */
 class SerialVersionUID(uid: Long) extends annotation.StaticAnnotation
diff --git a/src/library/scala/Symbol.scala b/src/library/scala/Symbol.scala
index 79581f05d5..2cf8e21483 100644
--- a/src/library/scala/Symbol.scala
+++ b/src/library/scala/Symbol.scala
@@ -10,19 +10,14 @@
 
 package scala
 
-/** <p>
- *    This class provides a simple way to get unique objects for
- *    equal strings. Since symbols are interned, they can be compared using
- *    reference equality. Instances of
- *    <code>Symbol</code> can be created easily with Scala's built-in
-*     quote mechanism.
- *  </p>
- *  <p>
- *    For instance, the <a href="http://scala-lang.org/" target="_top">Scala</a>
- *    term <code>'mysym</code> will invoke the constructor of the
- *    <code>Symbol</code> class in the following way:
- *    <code>Symbol("mysym")</code>.
- *  </p>
+/** This class provides a simple way to get unique objects for equal strings.
+ *  Since symbols are interned, they can be compared using reference equality.
+ *  Instances of `Symbol` can be created easily with Scala's built-in quote
+ *  mechanism.
+ *
+ *  For instance, the [[http://scala-lang.org/#_top Scala]] term `'mysym` will
+ *  invoke the constructor of the `Symbol` class in the following way:
+ *  `Symbol("mysym")`.
  *
  *  @author  Martin Odersky, Iulian Dragos
  *  @version 1.8
diff --git a/src/library/scala/annotation/Annotation.scala b/src/library/scala/annotation/Annotation.scala
index 05ed5af0a4..914a7b99f2 100644
--- a/src/library/scala/annotation/Annotation.scala
+++ b/src/library/scala/annotation/Annotation.scala
@@ -8,14 +8,11 @@
 
 package scala.annotation
 
-/** <p>
- *   A base class for annotations. Annotations extending this class directly
- *   are not preserved for the Scala type checker and are also not stored
- *   as Java annotations in classfiles. To enable either or both of these,
- *   one needs to inherit from
- *   <a href="StaticAnnotation.html"><code>StaticAnnotation</code></a> or/and
- *   <a href="ClassfileAnnotation.html"><code>ClassfileAnnotation</code></a>.
- *  </p>
+/** A base class for annotations. Annotations extending this class directly
+ *  are not preserved for the Scala type checker and are also not stored as
+ *  Java annotations in classfiles. To enable either or both of these, one
+ *  needs to inherit from [[scala.annotation.StaticAnnotation]] or/and
+ *  [[scala.annotation.ClassfileAnnotation]].
  *
  *  @author  Martin Odersky
  *  @version 1.1, 2/02/2007
diff --git a/src/library/scala/annotation/ClassfileAnnotation.scala b/src/library/scala/annotation/ClassfileAnnotation.scala
index 1019601f41..582e51996a 100644
--- a/src/library/scala/annotation/ClassfileAnnotation.scala
+++ b/src/library/scala/annotation/ClassfileAnnotation.scala
@@ -8,11 +8,9 @@
 
 package scala.annotation
 
-/** <p>
- *    A base class for classfile annotations. These are stored as
- *    <a href="http://java.sun.com/j2se/1.5.0/docs/guide/language/annotations.html"
- *    target="_top">Java annotations</a> in classfiles.
- *  </p>
+/** A base class for classfile annotations. These are stored as
+ *  [[http://java.sun.com/j2se/1.5.0/docs/guide/language/annotations.html#_top Java annotations]]]
+ *  in classfiles.
  *
  *  @author  Martin Odersky
  *  @version 1.1, 2/02/2007
diff --git a/src/library/scala/annotation/StaticAnnotation.scala b/src/library/scala/annotation/StaticAnnotation.scala
index fad875bd8a..fc780ac7a5 100644
--- a/src/library/scala/annotation/StaticAnnotation.scala
+++ b/src/library/scala/annotation/StaticAnnotation.scala
@@ -8,10 +8,8 @@
 
 package scala.annotation
 
-/** <p>
- *    A base class for static annotations. These are available
- *    to the Scala type checker, even across different compilation units.
- *  </p>
+/** A base class for static annotations. These are available
+ *  to the Scala type checker, even across different compilation units.
  *
  *  @author  Martin Odersky
  *  @version 1.1, 2/02/2007
diff --git a/src/library/scala/annotation/TypeConstraint.scala b/src/library/scala/annotation/TypeConstraint.scala
index d13b0ac2b2..e1ed199d5c 100644
--- a/src/library/scala/annotation/TypeConstraint.scala
+++ b/src/library/scala/annotation/TypeConstraint.scala
@@ -8,18 +8,16 @@
 
 package scala.annotation
 
-/** <p>
- *    A marker for annotations that, when applied to a type,
- *    should be treated as a constraint on the annotated type.
- *    A proper constraint should restrict the type based only
- *    on information mentioned within the type.  A Scala compiler
- *    can use this assumption to rewrite the contents of the
- *    constraint as necessary.  To contrast, a type annotation
- *    whose meaning depends on the context where it is written
- *    down is not a proper constrained type, and this marker
- *    should not be applied.  A Scala compiler will drop such
- *    annotations in cases where it would rewrite a type constraint.
- *  </p>
+/** A marker for annotations that, when applied to a type, should be treated
+ *  as a constraint on the annotated type.
+ *
+ *  A proper constraint should restrict the type based only on information
+ *  mentioned within the type.  A Scala compiler can use this assumption to
+ *  rewrite the contents of the constraint as necessary.  To contrast, a type
+ *  annotation whose meaning depends on the context where it is written
+ *  down is not a proper constrained type, and this marker should not be
+ *  applied.  A Scala compiler will drop such annotations in cases where it
+ *  would rewrite a type constraint.
  *
  *  @author  Lex Spoon
  *  @version 1.1, 2007-11-5
diff --git a/src/library/scala/annotation/elidable.scala b/src/library/scala/annotation/elidable.scala
index 8239debeb8..8dc180d7ab 100644
--- a/src/library/scala/annotation/elidable.scala
+++ b/src/library/scala/annotation/elidable.scala
@@ -13,10 +13,10 @@ import java.util.logging.Level
 /** An annotation for methods for which invocations might
  *  be removed in the generated code.
  *
- *  Behavior is influenced by passing -Xelide-below <arg>
- *  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:
+ *  Behavior is influenced by passing `-Xelide-below <arg>` 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._
  *
@@ -33,20 +33,23 @@ final class elidable(final val level: Int) extends annotation.StaticAnnotation {
  *  named constants for the elidable annotation.  This is what it takes
  *  to convince the compiler to fold the constants: otherwise when it's
  *  time to check an elision level it's staring at a tree like
- *    (Select(Level, Select(FINEST, Apply(intValue, Nil))))
- *  instead of the number 300.
+ *  {{{
+ *  (Select(Level, Select(FINEST, Apply(intValue, Nil))))
+ *  }}}
+ *  instead of the number `300`.
  *
  *  @since 2.8
  */
 object elidable {
-  /** The levels ALL and OFF are confusing in this context because the
-   *  sentiment being expressed when using the annotation is at cross purposes
-   *  with the one being expressed via -Xelide-below.  This confusion reaches
-   *  its zenith at level OFF, where the annotation means "never elide this method"
-   *  but -Xelide-below OFF is how you would say "elide everything possible."
+  /** The levels `ALL` and `OFF` are confusing in this context because
+   *  the sentiment being expressed when using the annotation is at cross
+   *  purposes with the one being expressed via `-Xelide-below`.  This
+   *  confusion reaches its zenith at level `OFF`, where the annotation means
+   *  ''never elide this method'' but `-Xelide-below OFF` is how you would
+   *  say ''elide everything possible''.
    *
    *  With no simple remedy at hand, the issue is now at least documented,
-   *  and aliases MAXIMUM and MINIMUM are offered.
+   *  and aliases `MAXIMUM` and `MINIMUM` are offered.
    */
   final val ALL     = Int.MinValue  // Level.ALL.intValue()
   final val FINEST  = 300           // Level.FINEST.intValue()
diff --git a/src/library/scala/annotation/tailrec.scala b/src/library/scala/annotation/tailrec.scala
index a2c1791a44..14775535e8 100644
--- a/src/library/scala/annotation/tailrec.scala
+++ b/src/library/scala/annotation/tailrec.scala
@@ -5,13 +5,14 @@
 ** /____/\___/_/ |_/____/_/ | |                                         **
 **                          |/                                          **
 \*                                                                      */
+
 package scala.annotation
 
-/** <p>
- *    A method annotation which verifies that the method will be compiled
- *    with tail call optimization.  If it is present, the compiler will
- *    issue an error if the method cannot be optimized into a loop.
- *  </p>
+/** A method annotation which verifies that the method will be compiled
+ *  with tail call optimization.
+ *
+ *  If it is present, the compiler will issue an error if the method cannot
+ *  be optimized into a loop.
  *
  *  @since 2.8
  */
diff --git a/src/library/scala/annotation/varargs.scala b/src/library/scala/annotation/varargs.scala
index e29f7bacf0..1d7a2f7183 100644
--- a/src/library/scala/annotation/varargs.scala
+++ b/src/library/scala/annotation/varargs.scala
@@ -5,13 +5,12 @@
 ** /____/\___/_/ |_/____/_/ | |                                         **
 **                          |/                                          **
 \*                                                                      */
+
 package scala.annotation
 
-/** <p>
- *    A method annotation which instructs the compiler to generate a
- *    Java varargs-style forwarder method for interop. This annotation can
- *    only be applied to methods with repeated parameters.
- *  </p>
+/** A method annotation which instructs the compiler to generate a
+ *  Java varargs-style forwarder method for interop. This annotation can
+ *  only be applied to methods with repeated parameters.
  *
  *  @since 2.9
  */
diff --git a/src/library/scala/collection/GenSeqLike.scala b/src/library/scala/collection/GenSeqLike.scala
index 1a66a0029c..56034273f0 100644
--- a/src/library/scala/collection/GenSeqLike.scala
+++ b/src/library/scala/collection/GenSeqLike.scala
@@ -215,14 +215,13 @@ trait GenSeqLike[+A, +Repr] extends GenIterableLike[A, Repr] with Equals with Pa
 
   /** Tests whether this $coll contains the given sequence at a given index.
    *
-   * If the both the receiver object, <code>this</code> and
-   * the argument, <code>that</code> are infinite sequences
-   * this method may not terminate.
+   * '''Note''': If the both the receiver object `this` and the argument
+   * `that` are infinite sequences this method may not terminate.
    *
    * @param  that    the sequence to test
    * @param  offset  the index where the sequence is searched.
-   * @return `true` if the sequence `that` is contained in this $coll at index `offset`,
-   *         otherwise `false`.
+   * @return `true` if the sequence `that` is contained in this $coll at
+   *         index `offset`, otherwise `false`.
    */
   def startsWith[B](that: GenSeq[B], offset: Int): Boolean
 
diff --git a/src/library/scala/collection/GenTraversableLike.scala b/src/library/scala/collection/GenTraversableLike.scala
index 2a613a4645..fbb8b96ba4 100644
--- a/src/library/scala/collection/GenTraversableLike.scala
+++ b/src/library/scala/collection/GenTraversableLike.scala
@@ -26,10 +26,12 @@ import annotation.migration
  *    and the new element type `B`.
  *  @define orderDependent
  *
- *    Note: might return different results for different runs, unless the underlying collection type is ordered.
+ *    Note: might return different results for different runs, unless the
+ *    underlying collection type is ordered.
  *  @define orderDependentFold
  *
- *    Note: might return different results for different runs, unless the underlying collection type is ordered.
+ *    Note: might return different results for different runs, unless the
+ *    underlying collection type is ordered.
  *    or the operator is associative and commutative.
  *  @define mayNotTerminateInf
  *
diff --git a/src/library/scala/collection/GenTraversableOnce.scala b/src/library/scala/collection/GenTraversableOnce.scala
index f27a176c44..67ae044ebf 100644
--- a/src/library/scala/collection/GenTraversableOnce.scala
+++ b/src/library/scala/collection/GenTraversableOnce.scala
@@ -19,10 +19,12 @@ package scala.collection
  *  @define possiblyparinfo
  *  This trait may possibly have operations implemented in parallel.
  *  @define undefinedorder
- *  The order in which operations are performed on elements is unspecified and may be nondeterministic.
+ *  The order in which operations are performed on elements is unspecified
+ *  and may be nondeterministic.
  *  @define orderDependent
  *
- *    Note: might return different results for different runs, unless the underlying collection type is ordered.
+ *    Note: might return different results for different runs, unless the
+ *    underlying collection type is ordered.
  *  @define orderDependentFold
  *
  *    Note: might return different results for different runs, unless the
@@ -91,7 +93,8 @@ trait GenTraversableOnce[+A] {
    */
   def reduce[A1 >: A](op: (A1, A1) => A1): A1
 
-  /** Optionally reduces the elements of this sequence using the specified associative binary operator.
+  /** Optionally reduces the elements of this sequence using the specified
+   *  associative binary operator.
    *
    *  $undefinedorder
    *
@@ -107,13 +110,14 @@ trait GenTraversableOnce[+A] {
    */
   def reduceOption[A1 >: A](op: (A1, A1) => A1): Option[A1]
 
-  /** Folds the elements of this sequence using the specified associative binary operator.
-   *  The order in which the elements are reduced is unspecified and may be nondeterministic.
+  /** Folds the elements of this sequence using the specified associative
+   *  binary operator. The order in which the elements are reduced is
+   *  unspecified and may be nondeterministic.
    *
    *  Note this method has a different signature than the `foldLeft`
    *  and `foldRight` methods of the trait `Traversable`.
-   *  The result of folding may only be a supertype of this parallel collection's
-   *  type parameter `T`.
+   *  The result of folding may only be a supertype of this parallel
+   *  collection's type parameter `T`.
    *
    *  @tparam U      a type parameter for the binary operator, a supertype of `T`.
    *  @param z       a neutral element for the fold operation, it may be added to the result
@@ -141,7 +145,7 @@ trait GenTraversableOnce[+A] {
    *  @return  the result of inserting `op` between consecutive elements of this $coll,
    *           going left to right with the start value `z` on the left:
    *           {{{
-   *             op(...op(op(z, x,,1,,), x,,2,,), ..., x,,n,,)
+   *             op(...op(op(z, x1), x2), ..., xn)
    *           }}}
    *           where `x,,1,,, ..., x,,n,,` are the elements of this $coll.
    */
@@ -161,7 +165,7 @@ trait GenTraversableOnce[+A] {
    *  @return  the result of inserting `op` between consecutive elements of this $coll,
    *           going right to left with the start value `z` on the right:
    *           {{{
-   *             op(x,,1,,, op(x,,2,,, ... op(x,,n,,, z)...))
+   *             op(x1, op(x2, ... op(xn, z)...))
    *           }}}
    *           where `x,,1,,, ..., x,,n,,` are the elements of this $coll.
    */
@@ -179,7 +183,7 @@ trait GenTraversableOnce[+A] {
    *  @return  the result of inserting `op` between consecutive elements of this $coll,
    *           going left to right with the start value `z` on the left:
    *           {{{
-   *             op(...op(z, x,,1,,), x,,2,,, ..., x,,n,,)
+   *             op(...op(z, x1), x2, ..., xn)
    *           }}}
    *           where `x,,1,,, ..., x,,n,,` are the elements of this $coll.
    */
@@ -196,7 +200,7 @@ trait GenTraversableOnce[+A] {
    *  @return  the result of inserting `op` between consecutive elements of this $coll,
    *           going right to left with the start value `z` on the right:
    *           {{{
-   *             op(x,,1,,, op(x,,2,,, ... op(x,,n,,, z)...))
+   *             op(x1, op(x2, ... op(xn, z)...))
    *           }}}
    *           where `x,,1,,, ..., x,,n,,` are the elements of this $coll.
    */
@@ -204,18 +208,18 @@ trait GenTraversableOnce[+A] {
 
   /** Aggregates the results of applying an operator to subsequent elements.
    *
-   *  This is a more general form of `fold` and `reduce`. It has similar semantics, but does
-   *  not require the result to be a supertype of the element type. It traverses the elements in
-   *  different partitions sequentially, using `seqop` to update the result, and then
-   *  applies `combop` to results from different partitions. The implementation of this
-   *  operation may operate on an arbitrary number of collection partitions, so `combop`
-   *  may be invoked arbitrary number of times.
-   *
-   *  For example, one might want to process some elements and then produce a `Set`. In this
-   *  case, `seqop` would process an element and append it to the list, while `combop`
-   *  would concatenate two lists from different partitions together. The initial value
-   *  `z` would be an empty set.
-   *
+   *  This is a more general form of `fold` and `reduce`. It has similar
+   *  semantics, but does not require the result to be a supertype of the
+   *  element type. It traverses the elements in different partitions
+   *  sequentially, using `seqop` to update the result, and then applies
+   *  `combop` to results from different partitions. The implementation of
+   *  this operation may operate on an arbitrary number of collection
+   *  partitions, so `combop` may be invoked arbitrary number of times.
+   *
+   *  For example, one might want to process some elements and then produce
+   *  a `Set`. In this case, `seqop` would process an element and append it
+   *  to the list, while `combop` would concatenate two lists from different
+   *  partitions together. The initial value `z` would be an empty set.
    *  {{{
    *    pc.aggregate(Set[Int]())(_ += process(_), _ ++ _)
    *  }}}
diff --git a/src/library/scala/collection/IterableProxy.scala b/src/library/scala/collection/IterableProxy.scala
index a05a3cff5b..e0ba720a33 100644
--- a/src/library/scala/collection/IterableProxy.scala
+++ b/src/library/scala/collection/IterableProxy.scala
@@ -6,16 +6,12 @@
 **                          |/                                          **
 \*                                                                      */
 
-
-
 package scala.collection
 
 import generic._
 
-/** <p>
- *    This trait implements a proxy for iterable objects. It forwards
- *    all calls to a different iterable object.
- *  </p>
+/** This trait implements a proxy for iterable objects. It forwards all calls
+ *  to a different iterable object.
  *
  *  @author  Martin Odersky
  *  @version 2.8
diff --git a/src/library/scala/collection/JavaConversions.scala b/src/library/scala/collection/JavaConversions.scala
index 8b98f10875..39b86ad85d 100644
--- a/src/library/scala/collection/JavaConversions.scala
+++ b/src/library/scala/collection/JavaConversions.scala
@@ -275,17 +275,18 @@ object JavaConversions {
   def asMap[A, B](m : mutable.Map[A, B]): ju.Map[A, B] = mutableMapAsJavaMap[A, B](m)
 
   /**
-   * Implicitly converts a Scala mutable Map to a Java Dictionary.
-   * The returned Java Dictionary is backed by the provided Scala
-   * Dictionary and any side-effects of using it via the Java interface will
-   * be visible via the Scala interface and vice versa.
+   * Implicitly converts a Scala mutable `Map` to a Java `Dictionary`.
+   *
+   * The returned Java `Dictionary` is backed by the provided Scala
+   * `Dictionary` and any side-effects of using it via the Java interface
+   * will be visible via the Scala interface and vice versa.
    *
-   * If the Scala Dictionary was previously obtained from an implicit or
-   * explicit call of asMap(java.util.Dictionary) then the original
+   * If the Scala `Dictionary` was previously obtained from an implicit or
+   * explicit call of `asMap(java.util.Dictionary)` then the original
    * Java Dictionary will be returned.
    *
-   * @param m The Map to be converted.
-   * @return A Java Dictionary view of the argument.
+   * @param m The `Map` to be converted.
+   * @return A Java `Dictionary` view of the argument.
    */
   implicit def asJavaDictionary[A, B](m : mutable.Map[A, B]): ju.Dictionary[A, B] = m match {
     //case JConcurrentMapWrapper(wrapped) => wrapped
@@ -297,17 +298,18 @@ object JavaConversions {
   def asDictionary[A, B](m : mutable.Map[A, B]): ju.Dictionary[A, B] = asJavaDictionary[A, B](m)
 
   /**
-   * Implicitly converts a Scala Map to a Java Map.
-   * The returned Java Map is backed by the provided Scala
-   * Map and any side-effects of using it via the Java interface will
-   * be visible via the Scala interface and vice versa.
+   * Implicitly converts a Scala `Map` to a Java `Map`.
    *
-   * If the Scala Map was previously obtained from an implicit or
-   * explicit call of asMap(java.util.Map) then the original
-   * Java Map will be returned.
+   * The returned Java `Map` is backed by the provided Scala `Map` and
+   * any side-effects of using it via the Java interface will be visible
+   * via the Scala interface and vice versa.
    *
-   * @param m The Map to be converted.
-   * @return A Java Map view of the argument.
+   * If the Scala `Map` was previously obtained from an implicit or
+   * explicit call of `asMap(java.util.Map)` then the original
+   * Java `Map` will be returned.
+   *
+   * @param m The `Map` to be converted.
+   * @return A Java `Map` view of the argument.
    */
   implicit def mapAsJavaMap[A, B](m : Map[A, B]): ju.Map[A, B] = m match {
     //case JConcurrentMapWrapper(wrapped) => wrapped
@@ -321,17 +323,19 @@ object JavaConversions {
   def asMap[A, B](m : Map[A, B]): ju.Map[A, B] = mapAsJavaMap[A, B](m)
 
   /**
-   * Implicitly converts a Scala mutable `ConcurrentMap` to a Java `ConcurrentMap`.
-   * The returned Java `ConcurrentMap` is backed by the provided Scala `ConcurrentMap`
-   * and any side-effects of using it via the Java interface will be visible
-   * via the Scala interface and vice versa.
+   * Implicitly converts a Scala mutable `ConcurrentMap` to a Java
+   * `ConcurrentMap`.
    *
-   * If the Scala ConcurrentMap was previously obtained from an implicit or
-   * explicit call of asConcurrentMap(java.util.concurrect.ConcurrentMap) then the original
-   * Java ConcurrentMap will be returned.
+   * The returned Java `ConcurrentMap` is backed by the provided Scala
+   * `ConcurrentMap` and any side-effects of using it via the Java interface
+   * will be visible via the Scala interface and vice versa.
    *
-   * @param m The ConcurrentMap to be converted.
-   * @return A Java ConcurrentMap view of the argument.
+   * If the Scala `ConcurrentMap` was previously obtained from an implicit or
+   * explicit call of `asConcurrentMap(java.util.concurrect.ConcurrentMap)`
+   * then the original Java ConcurrentMap will be returned.
+   *
+   * @param m The `ConcurrentMap` to be converted.
+   * @return A Java `ConcurrentMap` view of the argument.
    */
   implicit def asJavaConcurrentMap[A, B](m: mutable.ConcurrentMap[A, B]): juc.ConcurrentMap[A, B] = m match {
     case JConcurrentMapWrapper(wrapped) => wrapped
@@ -344,17 +348,18 @@ object JavaConversions {
   // Java => Scala
 
   /**
-   * Implicitly converts a Java Iterator to a Scala Iterator.
-   * The returned Scala Iterator is backed by the provided Java
-   * Iterator and any side-effects of using it via the Scala interface will
-   * be visible via the Java interface and vice versa.
+   * Implicitly converts a Java `Iterator` to a Scala `Iterator`.
    *
-   * If the Java Iterator was previously obtained from an implicit or
-   * explicit call of asIterator(scala.collection.Iterator) then the original
-   * Scala Iterator will be returned.
+   * The returned Scala `Iterator` is backed by the provided Java `Iterator`
+   * and any side-effects of using it via the Scala interface will be visible
+   * via the Java interface and vice versa.
    *
-   * @param i The Iterator to be converted.
-   * @return A Scala Iterator view of the argument.
+   * If the Java `Iterator` was previously obtained from an implicit or
+   * explicit call of `asIterator(scala.collection.Iterator)` then the
+   * original Scala `Iterator` will be returned.
+   *
+   * @param i The `Iterator` to be converted.
+   * @return A Scala `Iterator` view of the argument.
    */
   implicit def asScalaIterator[A](i : ju.Iterator[A]): Iterator[A] = i match {
     case IteratorWrapper(wrapped) => wrapped
@@ -386,14 +391,15 @@ object JavaConversions {
   def asIterator[A](i : ju.Enumeration[A]): Iterator[A] = enumerationAsScalaIterator[A](i)
 
   /**
-   * Implicitly converts a Java Iterable to a Scala Iterable.
-   * The returned Scala Iterable is backed by the provided Java
-   * Iterable and any side-effects of using it via the Scala interface will
-   * be visible via the Java interface and vice versa.
+   * Implicitly converts a Java `Iterable` to a Scala `Iterable`.
    *
-   * If the Java Iterable was previously obtained from an implicit or
-   * explicit call of iterableAsScalaIterable(scala.collection.Iterable) then the original
-   * Scala Iterable will be returned.
+   * The returned Scala `Iterable` is backed by the provided Java `Iterable`
+   * and any side-effects of using it via the Scala interface will be visible
+   * via the Java interface and vice versa.
+   *
+   * If the Java `Iterable` was previously obtained from an implicit or
+   * explicit call of `iterableAsScalaIterable(scala.collection.Iterable)`
+   * then the original Scala Iterable will be returned.
    *
    * @param i The Iterable to be converted.
    * @return A Scala Iterable view of the argument.
@@ -409,11 +415,11 @@ object JavaConversions {
   def asIterable[A](i : jl.Iterable[A]): Iterable[A] = iterableAsScalaIterable[A](i)
 
   /**
-   * Implicitly converts a Java Collection to an Scala Iterable.
+   * Implicitly converts a Java `Collection` to an Scala `Iterable`.
    *
-   * If the Java Collection was previously obtained from an implicit or
-   * explicit call of collectionAsScalaIterable(scala.collection.SizedIterable) then
-   * the original Scala Iterable will be returned.
+   * If the Java `Collection` was previously obtained from an implicit or
+   * explicit call of `collectionAsScalaIterable(scala.collection.SizedIterable)`
+   * then the original Scala `Iterable` will be returned.
    *
    * @param i The Collection to be converted.
    * @return A Scala Iterable view of the argument.
@@ -428,17 +434,18 @@ object JavaConversions {
   def asIterable[A](i : ju.Collection[A]): Iterable[A] = collectionAsScalaIterable[A](i)
 
   /**
-   * Implicitly converts a Java List to a Scala mutable Buffer.
-   * The returned Scala Buffer is backed by the provided Java
-   * List and any side-effects of using it via the Scala interface will
+   * Implicitly converts a Java `List` to a Scala mutable `Buffer`.
+   *
+   * The returned Scala `Buffer` is backed by the provided Java `List`
+   * and any side-effects of using it via the Scala interface will
    * be visible via the Java interface and vice versa.
    *
-   * If the Java List was previously obtained from an implicit or
-   * explicit call of asScalaBuffer(scala.collection.mutable.Buffer) then the original
-   * Scala Buffer will be returned.
+   * If the Java `List` was previously obtained from an implicit or
+   * explicit call of `asScalaBuffer(scala.collection.mutable.Buffer)`
+   * then the original Scala `Buffer` will be returned.
    *
-   * @param l The List to be converted.
-   * @return A Scala mutable Buffer view of the argument.
+   * @param l The `List` to be converted.
+   * @return A Scala mutable `Buffer` view of the argument.
    */
   implicit def asScalaBuffer[A](l : ju.List[A]): mutable.Buffer[A] = l match {
     case MutableBufferWrapper(wrapped) => wrapped
@@ -470,13 +477,14 @@ object JavaConversions {
   def asSet[A](s : ju.Set[A]): mutable.Set[A] = asScalaSet[A](s)
 
   /**
-   * Implicitly converts a Java Map to a Scala mutable Map.
-   * The returned Scala Map is backed by the provided Java
-   * Map and any side-effects of using it via the Scala interface will
-   * be visible via the Java interface and vice versa.
+   * Implicitly converts a Java `Map` to a Scala mutable `Map`.
+   *
+   * The returned Scala `Map` is backed by the provided Java `Map` and any
+   * side-effects of using it via the Scala interface will be visible via
+   * the Java interface and vice versa.
    *
-   * If the Java Map was previously obtained from an implicit or
-   * explicit call of mapAsScalaMap(scala.collection.mutable.Map) then the original
+   * If the Java `Map` was previously obtained from an implicit or
+   * explicit call of `mapAsScalaMap(scala.collection.mutable.Map)` then the original
    * Scala Map will be returned.
    *
    * @param m The Map to be converted.
@@ -515,10 +523,12 @@ object JavaConversions {
   def asConcurrentMap[A, B](m: juc.ConcurrentMap[A, B]): mutable.ConcurrentMap[A, B] = asScalaConcurrentMap[A, B](m)
 
   /**
-   * Implicitly converts a Java Dictionary to a Scala mutable Map[String, String].
-   * The returned Scala Map[String, String] is backed by the provided Java
-   * Dictionary and any side-effects of using it via the Scala interface will
-   * be visible via the Java interface and vice versa.
+   * Implicitly converts a Java `Dictionary` to a Scala mutable
+   * `Map[String, String]`.
+   *
+   * The returned Scala `Map[String, String]` is backed by the provided Java
+   * `Dictionary` and any side-effects of using it via the Scala interface
+   * will be visible via the Java interface and vice versa.
    *
    * @param m The Dictionary to be converted.
    * @return A Scala mutable Map[String, String] view of the argument.
@@ -532,10 +542,11 @@ object JavaConversions {
   def asMap[A, B](p: ju.Dictionary[A, B]): mutable.Map[A, B] = dictionaryAsScalaMap[A, B](p)
 
   /**
-   * Implicitly converts a Java Properties to a Scala mutable Map[String, String].
-   * The returned Scala Map[String, String] is backed by the provided Java
-   * Properties and any side-effects of using it via the Scala interface will
-   * be visible via the Java interface and vice versa.
+   * Implicitly converts a Java `Properties` to a Scala `mutable Map[String, String]`.
+   *
+   * The returned Scala `Map[String, String]` is backed by the provided Java
+   * `Properties` and any side-effects of using it via the Scala interface
+   * will be visible via the Java interface and vice versa.
    *
    * @param m The Properties to be converted.
    * @return A Scala mutable Map[String, String] view of the argument.
@@ -930,7 +941,7 @@ object JavaConversions {
     def iterator = new Iterator[(String, String)] {
       val ui = underlying.entrySet.iterator
       def hasNext = ui.hasNext
-      def next() = { val e = ui.next ; (e.getKey.asInstanceOf[String], e.getValue.asInstanceOf[String]) }
+      def next() = { val e = ui.next; (e.getKey.asInstanceOf[String], e.getValue.asInstanceOf[String]) }
     }
 
     override def clear() = underlying.clear()
@@ -944,4 +955,3 @@ object JavaConversions {
     def setProperty(key: String, value: String) = underlying.setProperty(key, value)
   }
 }
-
diff --git a/src/library/scala/collection/JavaConverters.scala b/src/library/scala/collection/JavaConverters.scala
index b0abf09ddb..d5baacedf8 100755
--- a/src/library/scala/collection/JavaConverters.scala
+++ b/src/library/scala/collection/JavaConverters.scala
@@ -8,51 +8,42 @@
 
 package scala.collection
 
-/** <p>
- *    A collection of decorators that allow to convert between
- *    Scala and Java collections using `asScala` and `asJava` methods.
- *  </p>
- *  <p>
- *    The following conversions are supported via `asJava`, `asScala`
- *  </p>
- *  <ul>
- *    <li><code>scala.collection.Iterable</code> <=> <code>java.lang.Iterable</code></li>
- *    <li><code>scala.collection.Iterator</code> <=> <code>java.util.Iterator</code></li>
- *    <li><code>scala.collection.mutable.Buffer</code> <=> <code>java.util.List</code></li>
- *    <li><code>scala.collection.mutable.Set</code> <=> <code>java.util.Set</code></li>
- *    <li><code>scala.collection.mutable.Map</code> <=> <code>java.util.Map</code></li>
- *    <li><code>scala.collection.mutable.ConcurrentMap</code> <=> <code>java.util.concurrent.ConcurrentMap</code></li>
- *  </ul>
- *  <p>
- *    In all cases, converting from a source type to a target type and back
- *    again will return the original source object, e.g.
- *  </p>
- *  <pre>
- *    <b>import</b> scala.collection.JavaConverters._
+/** A collection of decorators that allow to convert between
+ *  Scala and Java collections using `asScala` and `asJava` methods.
+ *
+ *  The following conversions are supported via `asJava`, `asScala`
+ *
+ *  - `scala.collection.Iterable` <=> `java.lang.Iterable`
+ *  - `scala.collection.Iterator` <=> `java.util.Iterator`
+ *  - `scala.collection.mutable.Buffer` <=> `java.util.List`
+ *  - `scala.collection.mutable.Set` <=> `java.util.Set`
+ *  - `scala.collection.mutable.Map` <=> `java.util.Map`
+ *  - `scala.collection.mutable.ConcurrentMap` <=> `java.util.concurrent.ConcurrentMap`
+ *
+ *  In all cases, converting from a source type to a target type and back
+ *  again will return the original source object, e.g.
+ *  {{{
+ *    import scala.collection.JavaConverters._
+ *
+ *    val sl = new scala.collection.mutable.ListBuffer[Int]
+ *    val jl : java.util.List[Int] = sl.asJava
+ *    val sl2 : scala.collection.mutable.Buffer[Int] = jl.asScala
+ *    assert(sl eq sl2)
+ *  }}}
+ *  The following conversions also are supported, but the
+ *  direction Scala to Java is done my a more specifically named method:
+ *  `asJavaCollection`, `asJavaEnumeration`, `asJavaDictionary`.
+ *
+ *  - `scala.collection.Iterable` <=> `java.util.Collection`
+ *  - `scala.collection.Iterator` <=> `java.util.Enumeration`
+ *  - `scala.collection.mutable.Map` <=> `java.util.Dictionary`
  *
- *    <b>val</b> sl = <b>new</b> scala.collection.mutable.ListBuffer[Int]
- *    <b>val</b> jl : java.util.List[Int] = sl.asJava
- *    <b>val</b> sl2 : scala.collection.mutable.Buffer[Int] = jl.asScala
- *    assert(sl eq sl2)g</pre>
- *  <p>
- *  <p>
- *    The following conversions also are supported, but the
- *    direction Scala to Java is done my a more specifically named method:
- *    `asJavaCollection`, `asJavaEnumeration`, `asJavaDictionary`.
- *  </p>
- *  <ul>
- *    <li><code>scala.collection.Iterable</code> <=> <code>java.util.Collection</code></li>
- *    <li><code>scala.collection.Iterator</code> <=> <code>java.util.Enumeration</code></li>
- *    <li><code>scala.collection.mutable.Map</code> <=> <code>java.util.Dictionary</code></li>
- *  </ul>
  *  In addition, the following one way conversions are provided via `asJava`:
- *  </p>
- *  <ul>
- *    <li><code>scala.collection.Seq</code> => <code>java.util.List</code></li>
- *    <li><code>scala.collection.mutable.Seq</code> => <code>java.util.List</code></li>
- *    <li><code>scala.collection.Set</code> => <code>java.util.Set</code></li>
- *    <li><code>scala.collection.Map</code> => <code>java.util.Map</code></li>
- *  </ul>
+ *
+ *  - `scala.collection.Seq` => `java.util.List`
+ *  - `scala.collection.mutable.Seq` => `java.util.List`
+ *  - `scala.collection.Set` => `java.util.Set`
+ *  - `scala.collection.Map` => `java.util.Map`
  *
  *  @author Martin Odersky
  *  @since  2.8.1
@@ -101,111 +92,125 @@ object JavaConverters {
   // Scala => Java
 
   /**
-   * Adds an `asJava` method that implicitly converts a Scala <code>Iterator</code> to a Java <code>Iterator</code>.
-   * The returned Java <code>Iterator</code> is backed by the provided Scala
-   * <code>Iterator</code> and any side-effects of using it via the Java interface will
+   * Adds an `asJava` method that implicitly converts a Scala `Iterator` to a
+   * Java `Iterator`. The returned Java `Iterator` is backed by the provided Scala
+   * `Iterator` and any side-effects of using it via the Java interface will
    * be visible via the Scala interface and vice versa.
-   * <p>
-   * If the Scala <code>Iterator</code> was previously obtained from an implicit or
-   * explicit call of <code>asIterator(java.util.Iterator)</code> then the original
-   * Java <code>Iterator</code> will be returned by the `asJava` method.
    *
-   * @param i The <code>Iterator</code> to be converted.
-   * @return An object with an `asJava` method that returns a Java <code>Iterator</code> view of the argument.
+   * If the Scala `Iterator` was previously obtained from an implicit or explicit
+   * call of `asIterator(java.util.Iterator)` then the original Java `Iterator`
+   * will be returned by the `asJava` method.
+   *
+   * @param i The `Iterator` to be converted.
+   * @return An object with an `asJava` method that returns a Java `Iterator` view of the argument.
    */
   implicit def asJavaIteratorConverter[A](i : Iterator[A]): AsJava[ju.Iterator[A]] =
     new AsJava(asJavaIterator(i))
 
   /**
-   * Adds an `asJavaEnumeration` method that implicitly converts a Scala <code>Iterator</code> to a Java <code>Enumeration</code>.
-   * The returned Java <code>Enumeration</code> is backed by the provided Scala
-   * <code>Iterator</code> and any side-effects of using it via the Java interface will
-   * be visible via the Scala interface and vice versa.
-   * <p>
-   * If the Scala <code>Iterator</code> was previously obtained from an implicit or
-   * explicit call of <code>asIterator(java.util.Enumeration)</code> then the
-   * original Java <code>Enumeration</code> will be returned.
+   * Adds an `asJavaEnumeration` method that implicitly converts a Scala
+   * `Iterator` to a Java `Enumeration`. The returned Java `Enumeration` is
+   * backed by the provided Scala `Iterator` and any side-effects of using
+   * it via the Java interface will be visible via the Scala interface and
+   * vice versa.
+   *
+   * If the Scala `Iterator` was previously obtained from an implicit or
+   * explicit call of `asIterator(java.util.Enumeration)` then the
+   * original Java `Enumeration` will be returned.
    *
-   * @param i The <code>Iterator</code> to be converted.
-   * @return An object with an `asJavaEnumeration` method that returns a Java <code>Enumeration</code> view of the argument.
+   * @param i The `Iterator` to be converted.
+   * @return An object with an `asJavaEnumeration` method that returns a Java
+   *         `Enumeration` view of the argument.
    */
   implicit def asJavaEnumerationConverter[A](i : Iterator[A]): AsJavaEnumeration[A] =
     new AsJavaEnumeration(i)
 
   /**
-   * Adds an `asJava` method that implicitly converts a Scala <code>Iterable</code> to a Java <code>Iterable</code>.
-   * The returned Java <code>Iterable</code> is backed by the provided Scala
-   * <code>Iterable</code> and any side-effects of using it via the Java interface will
-   * be visible via the Scala interface and vice versa.
-   * <p>
-   * If the Scala <code>Iterable</code> was previously obtained from an implicit or
-   * explicit call of <code>asIterable(java.lang.Iterable)</code> then the original
-   * Java <code>Iterable</code> will be returned.
+   * Adds an `asJava` method that implicitly converts a Scala `Iterable` to
+   * a Java `Iterable`.
    *
-   * @param i The <code>Iterable</code> to be converted.
-   * @return An object with an `asJavaCollection` method that returns a Java <code>Iterable</code> view of the argument.
+   * The returned Java `Iterable` is backed by the provided Scala `Iterable`
+   * and any side-effects of using it via the Java interface will be visible
+   * via the Scala interface and vice versa.
+   *
+   * If the Scala `Iterable` was previously obtained from an implicit or
+   * explicit call of `asIterable(java.lang.Iterable)` then the original
+   * Java `Iterable` will be returned.
+   *
+   * @param i The `Iterable` to be converted.
+   * @return An object with an `asJavaCollection` method that returns a Java
+   *         `Iterable` view of the argument.
    */
   implicit def asJavaIterableConverter[A](i : Iterable[A]): AsJava[jl.Iterable[A]] =
     new AsJava(asJavaIterable(i))
 
   /**
-   * Adds an `asJavaCollection` method that implicitly converts a Scala <code>Iterable</code> to an immutable Java
-   * <code>Collection</code>.
-   * <p>
-   * If the Scala <code>Iterable</code> was previously obtained from an implicit or
-   * explicit call of <code>asSizedIterable(java.util.Collection)</code> then the original
-   * Java <code>Collection</code> will be returned.
+   * Adds an `asJavaCollection` method that implicitly converts a Scala
+   * `Iterable` to an immutable Java `Collection`.
+   *
+   * If the Scala `Iterable` was previously obtained from an implicit or
+   * explicit call of `asSizedIterable(java.util.Collection)` then the
+   * original Java `Collection` will be returned.
    *
-   * @param i The <code>SizedIterable</code> to be converted.
-   * @return An object with an `asJava` method that returns a Java <code>Collection</code> view of the argument.
+   * @param i The `SizedIterable` to be converted.
+   * @return An object with an `asJava` method that returns a Java
+   *         `Collection` view of the argument.
    */
   implicit def asJavaCollectionConverter[A](i : Iterable[A]): AsJavaCollection[A] =
     new AsJavaCollection(i)
 
   /**
-   * Adds an `asJava` method that implicitly converts a Scala mutable <code>Buffer</code> to a Java <code>List</code>.
-   * The returned Java <code>List</code> is backed by the provided Scala
-   * <code>Buffer</code> and any side-effects of using it via the Java interface will
-   * be visible via the Scala interface and vice versa.
-   * <p>
-   * If the Scala <code>Buffer</code> was previously obtained from an implicit or
-   * explicit call of <code>asBuffer(java.util.List)</code> then the original
-   * Java <code>List</code> will be returned.
+   * Adds an `asJava` method that implicitly converts a Scala mutable `Buffer`
+   * to a Java `List`.
    *
-   * @param b The <code>Buffer</code> to be converted.
+   * The returned Java `List` is backed by the provided Scala `Buffer` and any
+   * side-effects of using it via the Java interface will be visible via the
+   * Scala interface and vice versa.
+   *
+   * If the Scala `Buffer` was previously obtained from an implicit or explicit
+   * call of `asBuffer(java.util.List)` then the original Java `List` will be
+   * returned.
+   *
+   * @param b The `Buffer` to be converted.
    * @return An object with an `asJava` method that returns a Java <code>List</code> view of the argument.
    */
   implicit def bufferAsJavaListConverter[A](b : mutable.Buffer[A]): AsJava[ju.List[A]] =
     new AsJava(bufferAsJavaList(b))
 
   /**
-   * Adds an `asJava` method that implicitly converts a Scala mutable <code>Seq</code> to a Java <code>List</code>.
-   * The returned Java <code>List</code> is backed by the provided Scala
-   * <code>Seq</code> and any side-effects of using it via the Java interface will
-   * be visible via the Scala interface and vice versa.
-   * <p>
-   * If the Scala <code>Seq</code> was previously obtained from an implicit or
-   * explicit call of <code>asSeq(java.util.List)</code> then the original
-   * Java <code>List</code> will be returned.
+   * Adds an `asJava` method that implicitly converts a Scala mutable `Seq`
+   * to a Java `List`.
    *
-   * @param b The <code>Seq</code> to be converted.
-   * @return An object with an `asJava` method that returns a Java <code>List</code> view of the argument.
+   * The returned Java `List` is backed by the provided Scala `Seq` and any
+   * side-effects of using it via the Java interface will be visible via the
+   * Scala interface and vice versa.
+   *
+   * If the Scala `Seq` was previously obtained from an implicit or explicit
+   * call of `asSeq(java.util.List)` then the original Java `List` will be
+   * returned.
+   *
+   * @param b The `Seq` to be converted.
+   * @return An object with an `asJava` method that returns a Java `List`
+   *         view of the argument.
    */
   implicit def mutableSeqAsJavaListConverter[A](b : mutable.Seq[A]): AsJava[ju.List[A]] =
     new AsJava(mutableSeqAsJavaList(b))
 
   /**
-   * Adds an `asJava` method that implicitly converts a Scala <code>Seq</code> to a Java <code>List</code>.
-   * The returned Java <code>List</code> is backed by the provided Scala
-   * <code>Seq</code> and any side-effects of using it via the Java interface will
-   * be visible via the Scala interface and vice versa.
-   * <p>
-   * If the Scala <code>Seq</code> was previously obtained from an implicit or
-   * explicit call of <code>asSeq(java.util.List)</code> then the original
-   * Java <code>List</code> will be returned.
+   * Adds an `asJava` method that implicitly converts a Scala `Seq` to a
+   * Java `List`.
    *
-   * @param b The <code>Seq</code> to be converted.
-   * @return An object with an `asJava` method that returns a Java <code>List</code> view of the argument.
+   * The returned Java `List` is backed by the provided Scala `Seq` and any
+   * side-effects of using it via the Java interface will be visible via the
+   * Scala interface and vice versa.
+   *
+   * If the Scala `Seq` was previously obtained from an implicit or explicit
+   * call of `asSeq(java.util.List)` then the original Java `List` will be
+   * returned.
+   *
+   * @param b The `Seq` to be converted.
+   * @return An object with an `asJava` method that returns a Java `List`
+   *         view of the argument.
    */
   implicit def seqAsJavaListConverter[A](b : Seq[A]): AsJava[ju.List[A]] =
     new AsJava(seqAsJavaList(b))
@@ -218,14 +223,16 @@ object JavaConverters {
   def asJavaListConverter[A](b : Seq[A]): AsJava[ju.List[A]] = seqAsJavaListConverter(b)
 
   /**
-   * Adds an `asJava` method that implicitly converts a Scala mutable <code>Set</code> to a Java <code>Set</code>.
-   * The returned Java <code>Set</code> is backed by the provided Scala
-   * <code>Set</code> and any side-effects of using it via the Java interface will
-   * be visible via the Scala interface and vice versa.
-   * <p>
-   * If the Scala <code>Set</code> was previously obtained from an implicit or
-   * explicit call of <code>asSet(java.util.Set)</code> then the original
-   * Java <code>Set</code> will be returned.
+   * Adds an `asJava` method that implicitly converts a Scala mutable `Set`>
+   * to a Java `Set`.
+   *
+   * The returned Java `Set` is backed by the provided Scala `Set` and any
+   * side-effects of using it via the Java interface will be visible via
+   * the Scala interface and vice versa.
+   *
+   * If the Scala `Set` was previously obtained from an implicit or explicit
+   * call of `asSet(java.util.Set)` then the original Java `Set` will be
+   * returned.
    *
    * @param s The <code>Set</code> to be converted.
    * @return An object with an `asJava` method that returns a Java <code>Set</code> view of the argument.
@@ -237,17 +244,20 @@ object JavaConverters {
   def asJavaSetConverter[A](s : mutable.Set[A]): AsJava[ju.Set[A]] = mutableSetAsJavaSetConverter(s)
 
   /**
-   * Adds an `asJava` method that implicitly converts a Scala <code>Set</code> to a Java <code>Set</code>.
-   * The returned Java <code>Set</code> is backed by the provided Scala
-   * <code>Set</code> and any side-effects of using it via the Java interface will
-   * be visible via the Scala interface and vice versa.
-   * <p>
-   * If the Scala <code>Set</code> was previously obtained from an implicit or
-   * explicit call of <code>asSet(java.util.Set)</code> then the original
-   * Java <code>Set</code> will be returned.
+   * Adds an `asJava` method that implicitly converts a Scala `Set` to a
+   * Java `Set`.
    *
-   * @param s The <code>Set</code> to be converted.
-   * @return An object with an `asJava` method that returns a Java <code>Set</code> view of the argument.
+   * The returned Java `Set` is backed by the provided Scala `Set` and any
+   * side-effects of using it via the Java interface will be visible via
+   * the Scala interface and vice versa.
+   *
+   * If the Scala `Set` was previously obtained from an implicit or explicit
+   * call of <code>asSet(java.util.Set)</code> then the original Java `Set`
+   * will be returned.
+   *
+   * @param s The `Set` to be converted.
+   * @return An object with an `asJava` method that returns a Java `Set` view
+   *         of the argument.
    */
   implicit def setAsJavaSetConverter[A](s : Set[A]): AsJava[ju.Set[A]] =
     new AsJava(setAsJavaSet(s))
@@ -256,17 +266,20 @@ object JavaConverters {
   def asJavaSetConverter[A](s : Set[A]): AsJava[ju.Set[A]] = setAsJavaSetConverter(s)
 
   /**
-   * Adds an `asJava` method that implicitly converts a Scala mutable <code>Map</code> to a Java <code>Map</code>.
-   * The returned Java <code>Map</code> is backed by the provided Scala
-   * <code>Map</code> and any side-effects of using it via the Java interface will
-   * be visible via the Scala interface and vice versa.
-   * <p>
-   * If the Scala <code>Map</code> was previously obtained from an implicit or
-   * explicit call of <code>asMap(java.util.Map)</code> then the original
-   * Java <code>Map</code> will be returned.
+   * Adds an `asJava` method that implicitly converts a Scala mutable `Map`
+   * to a Java `Map`.
    *
-   * @param m The <code>Map</code> to be converted.
-   * @return An object with an `asJava` method that returns a Java <code>Map</code> view of the argument.
+   * The returned Java `Map` is backed by the provided Scala `Map` and any
+   * side-effects of using it via the Java interface will be visible via the
+   * Scala interface and vice versa.
+   *
+   * If the Scala `Map` was previously obtained from an implicit or explicit
+   * call of `asMap(java.util.Map)` then the original Java `Map` will be
+   * returned.
+   *
+   * @param m The `Map` to be converted.
+   * @return An object with an `asJava` method that returns a Java `Map` view
+   *         of the argument.
    */
   implicit def mutableMapAsJavaMapConverter[A, B](m : mutable.Map[A, B]): AsJava[ju.Map[A, B]] =
     new AsJava(mutableMapAsJavaMap(m))
@@ -275,33 +288,39 @@ object JavaConverters {
   def asJavaMapConverter[A, B](m : mutable.Map[A, B]): AsJava[ju.Map[A, B]] = mutableMapAsJavaMapConverter(m)
 
   /**
-   * Adds an `asJavaDictionary` method that implicitly converts a Scala mutable <code>Map</code> to a Java <code>Dictionary</code>.
-   * The returned Java <code>Dictionary</code> is backed by the provided Scala
-   * <code>Dictionary</code> and any side-effects of using it via the Java interface will
-   * be visible via the Scala interface and vice versa.
-   * <p>
-   * If the Scala <code>Dictionary</code> was previously obtained from an implicit or
-   * explicit call of <code>asMap(java.util.Dictionary)</code> then the original
-   * Java <code>Dictionary</code> will be returned.
+   * Adds an `asJavaDictionary` method that implicitly converts a Scala
+   * mutable `Map` to a Java `Dictionary`.
+   *
+   * The returned Java `Dictionary` is backed by the provided Scala
+   * `Dictionary` and any side-effects of using it via the Java interface
+   * will be visible via the Scala interface and vice versa.
+   *
+   * If the Scala `Dictionary` was previously obtained from an implicit or
+   * explicit call of `asMap(java.util.Dictionary)` then the original
+   * Java `Dictionary` will be returned.
    *
    * @param m The <code>Map</code> to be converted.
-   * @return An object with an `asJavaDictionary` method that returns a Java <code>Dictionary</code> view of the argument.
+   * @return An object with an `asJavaDictionary` method that returns a
+   *         Java `Dictionary` view of the argument.
    */
   implicit def asJavaDictionaryConverter[A, B](m : mutable.Map[A, B]): AsJavaDictionary[A, B] =
     new AsJavaDictionary(m)
 
   /**
-   * Adds an `asJava` method that implicitly converts a Scala <code>Map</code> to a Java <code>Map</code>.
-   * The returned Java <code>Map</code> is backed by the provided Scala
-   * <code>Map</code> and any side-effects of using it via the Java interface will
-   * be visible via the Scala interface and vice versa.
-   * <p>
-   * If the Scala <code>Map</code> was previously obtained from an implicit or
-   * explicit call of <code>asMap(java.util.Map)</code> then the original
-   * Java <code>Map</code> will be returned.
+   * Adds an `asJava` method that implicitly converts a Scala `Map` to
+   * a Java `Map`.
    *
-   * @param m The <code>Map</code> to be converted.
-   * @return An object with an `asJava` method that returns a Java <code>Map</code> view of the argument.
+   * The returned Java `Map` is backed by the provided Scala `Map` and any
+   * side-effects of using it via the Java interface will be visible via
+   * the Scala interface and vice versa.
+   *
+   * If the Scala `Map` was previously obtained from an implicit or explicit
+   * call of `asMap(java.util.Map)` then the original Java `Map` will be
+   * returned.
+   *
+   * @param m The `Map` to be converted.
+   * @return An object with an `asJava` method that returns a Java `Map` view
+   *         of the argument.
    */
   implicit def mapAsJavaMapConverter[A, B](m : Map[A, B]): AsJava[ju.Map[A, B]] =
     new AsJava(mapAsJavaMap(m))
@@ -310,49 +329,58 @@ object JavaConverters {
   def asJavaMapConverter[A, B](m : Map[A, B]): AsJava[ju.Map[A, B]] = mapAsJavaMapConverter(m)
 
   /**
-   * Adds an `asJava` method that implicitly converts a Scala mutable `ConcurrentMap` to a Java `ConcurrentMap`.
-   * The returned Java `ConcurrentMap` is backed by the provided Scala `ConcurrentMap`
-   * and any side-effects of using it via the Java interface will be visible
-   * via the Scala interface and vice versa.
-   * <p>
-   * If the Scala <code>ConcurrentMap</code> was previously obtained from an implicit or
-   * explicit call of <code>asConcurrentMap(java.util.concurrect.ConcurrentMap)</code> then the original
-   * Java <code>ConcurrentMap</code> will be returned.
+   * Adds an `asJava` method that implicitly converts a Scala mutable
+   * `ConcurrentMap` to a Java `ConcurrentMap`.
    *
-   * @param m The <code>ConcurrentMap</code> to be converted.
-   * @return An object with an `asJava` method that returns a Java <code>ConcurrentMap</code> view of the argument.
+   * The returned Java `ConcurrentMap` is backed by the provided Scala
+   * `ConcurrentMap` and any side-effects of using it via the Java interface
+   * will be visible via the Scala interface and vice versa.
+   *
+   * If the Scala `ConcurrentMap` was previously obtained from an implicit or
+   * explicit call of `asConcurrentMap(java.util.concurrect.ConcurrentMap)`
+   * then the original Java `ConcurrentMap` will be returned.
+   *
+   * @param m The `ConcurrentMap` to be converted.
+   * @return An object with an `asJava` method that returns a Java
+   *         `ConcurrentMap` view of the argument.
    */
   implicit def asJavaConcurrentMapConverter[A, B](m: mutable.ConcurrentMap[A, B]): AsJava[juc.ConcurrentMap[A, B]] =
     new AsJava(asJavaConcurrentMap(m))
 
   /**
-   * Adds an `asScala` method that implicitly converts a Java <code>Iterator</code> to a Scala <code>Iterator</code>.
-   * The returned Scala <code>Iterator</code> is backed by the provided Java
-   * <code>Iterator</code> and any side-effects of using it via the Scala interface will
-   * be visible via the Java interface and vice versa.
-   * <p>
-   * If the Java <code>Iterator</code> was previously obtained from an implicit or
-   * explicit call of <code>asIterator(scala.collection.Iterator)</code> then the original
-   * Scala <code>Iterator</code> will be returned.
+   * Adds an `asScala` method that implicitly converts a Java `Iterator` to
+   * a Scala `Iterator`.
+   *
+   * The returned Scala `Iterator` is backed by the provided Java `Iterator`
+   * and any side-effects of using it via the Scala interface will be visible
+   * via the Java interface and vice versa.
    *
-   * @param i The <code>Iterator</code> to be converted.
-   * @return An object with an `asScala` method that returns a Scala <code>Iterator</code> view of the argument.
+   * If the Java `Iterator` was previously obtained from an implicit or
+   * explicit call of `asIterator(scala.collection.Iterator)` then the
+   * original Scala `Iterator` will be returned.
+   *
+   * @param i The `Iterator` to be converted.
+   * @return An object with an `asScala` method that returns a Scala
+   *         `Iterator` view of the argument.
    */
   implicit def asScalaIteratorConverter[A](i : ju.Iterator[A]): AsScala[Iterator[A]] =
     new AsScala(asScalaIterator(i))
 
   /**
-   * Adds an `asScala` method that implicitly converts a Java <code>Enumeration</code> to a Scala <code>Iterator</code>.
-   * The returned Scala <code>Iterator</code> is backed by the provided Java
-   * <code>Enumeration</code> and any side-effects of using it via the Scala interface will
-   * be visible via the Java interface and vice versa.
-   * <p>
-   * If the Java <code>Enumeration</code> was previously obtained from an implicit or
-   * explicit call of <code>asEnumeration(scala.collection.Iterator)</code> then the
-   * original Scala <code>Iterator</code> will be returned.
+   * Adds an `asScala` method that implicitly converts a Java `Enumeration`
+   * to a Scala `Iterator`.
    *
-   * @param i The <code>Enumeration</code> to be converted.
-   * @return An object with an `asScala` method that returns a Scala <code>Iterator</code> view of the argument.
+   * The returned Scala `Iterator` is backed by the provided Java
+   * `Enumeration` and any side-effects of using it via the Scala interface
+   * will be visible via the Java interface and vice versa.
+   *
+   * If the Java `Enumeration` was previously obtained from an implicit or
+   * explicit call of `asEnumeration(scala.collection.Iterator)` then the
+   * original Scala `Iterator` will be returned.
+   *
+   * @param i The `Enumeration` to be converted.
+   * @return An object with an `asScala` method that returns a Scala
+   *         `Iterator` view of the argument.
    */
   implicit def enumerationAsScalaIteratorConverter[A](i : ju.Enumeration[A]): AsScala[Iterator[A]] =
     new AsScala(enumerationAsScalaIterator(i))
@@ -393,49 +421,56 @@ object JavaConverters {
   def asScalaIterableConverter[A](i : ju.Collection[A]): AsScala[Iterable[A]] = collectionAsScalaIterableConverter(i)
 
   /**
-   * Adds an `asScala` method that implicitly converts a Java <code>List</code> to a Scala mutable <code>Buffer</code>.
-   * The returned Scala <code>Buffer</code> is backed by the provided Java
-   * <code>List</code> and any side-effects of using it via the Scala interface will
-   * be visible via the Java interface and vice versa.
-   * <p>
-   * If the Java <code>List</code> was previously obtained from an implicit or
-   * explicit call of <code>asList(scala.collection.mutable.Buffer)</code> then the original
-   * Scala <code>Buffer</code> will be returned.
+   * Adds an `asScala` method that implicitly converts a Java `List` to a
+   * Scala mutable `Buffer`.
+   *
+   * The returned Scala `Buffer` is backed by the provided Java `List` and
+   * any side-effects of using it via the Scala interface will be visible via
+   * the Java interface and vice versa.
+   *
+   * If the Java `List` was previously obtained from an implicit or explicit
+   * call of `asList(scala.collection.mutable.Buffer)` then the original
+   * Scala `Buffer` will be returned.
    *
-   * @param l The <code>List</code> to be converted.
-   * @return An object with an `asScala` method that returns a Scala mutable <code>Buffer</code> view of the argument.
+   * @param l The `List` to be converted.
+   * @return An object with an `asScala` method that returns a Scala mutable
+   *        `Buffer` view of the argument.
    */
   implicit def asScalaBufferConverter[A](l : ju.List[A]): AsScala[mutable.Buffer[A]] =
     new AsScala(asScalaBuffer(l))
 
   /**
-   * Adds an `asScala` method that implicitly converts a Java <code>Set</code> to a Scala mutable <code>Set</code>.
-   * The returned Scala <code>Set</code> is backed by the provided Java
-   * <code>Set</code> and any side-effects of using it via the Scala interface will
-   * be visible via the Java interface and vice versa.
-   * <p>
-   * If the Java <code>Set</code> was previously obtained from an implicit or
-   * explicit call of <code>asSet(scala.collection.mutable.Set)</code> then the original
-   * Scala <code>Set</code> will be returned.
+   * Adds an `asScala` method that implicitly converts a Java `Set` to a
+   * Scala mutable `Set`.
    *
-   * @param s The <code>Set</code> to be converted.
-   * @return An object with an `asScala` method that returns a Scala mutable <code>Set</code> view of the argument.
+   * The returned Scala `Set` is backed by the provided Java `Set` and any
+   * side-effects of using it via the Scala interface will be visible via
+   * the Java interface and vice versa.
+   *
+   * If the Java `Set` was previously obtained from an implicit or explicit
+   * call of `asSet(scala.collection.mutable.Set)` then the original
+   * Scala `Set` will be returned.
+   *
+   * @param s The `Set` to be converted.
+   * @return An object with an `asScala` method that returns a Scala mutable
+   *         `Set` view of the argument.
    */
   implicit def asScalaSetConverter[A](s : ju.Set[A]): AsScala[mutable.Set[A]] =
     new AsScala(asScalaSet(s))
 
   /**
-   * Adds an `asScala` method that implicitly converts a Java <code>Map</code> to a Scala mutable <code>Map</code>.
-   * The returned Scala <code>Map</code> is backed by the provided Java
-   * <code>Map</code> and any side-effects of using it via the Scala interface will
+   * Adds an `asScala` method that implicitly converts a Java `Map` to a Scala
+   * mutable `Map`. The returned Scala `Map` is backed by the provided Java
+   * `Map` and any side-effects of using it via the Scala interface will
    * be visible via the Java interface and vice versa.
-   * <p>
-   * If the Java <code>Map</code> was previously obtained from an implicit or
-   * explicit call of <code>asMap(scala.collection.mutable.Map)</code> then the original
-   * Scala <code>Map</code> will be returned.
    *
-   * @param m The <code>Map</code> to be converted.
-   * @return An object with an `asScala` method that returns a Scala mutable <code>Map</code> view of the argument.
+   * If the Java `Map` was previously obtained from an implicit or explicit
+   * call of `asMap(scala.collection.mutable.Map)` then the original
+   * Scala `Map` will be returned.
+   *
+   * @param m The `Map` to be converted.
+   * @return An object with an `asScala` method that returns a Scala mutable
+   *         `Map` view of the argument.
    */
   implicit def mapAsScalaMapConverter[A, B](m : ju.Map[A, B]): AsScala[mutable.Map[A, B]] =
     new AsScala(mapAsScalaMap(m))
@@ -444,41 +479,47 @@ object JavaConverters {
   def asScalaMapConverter[A, B](m : ju.Map[A, B]): AsScala[mutable.Map[A, B]] = mapAsScalaMapConverter(m)
 
   /**
-   * Adds an `asScala` method that implicitly converts a Java <code>ConcurrentMap</code> to a Scala mutable <code>ConcurrentMap</code>.
-   * The returned Scala <code>ConcurrentMap</code> is backed by the provided Java
-   * <code>ConcurrentMap</code> and any side-effects of using it via the Scala interface will
-   * be visible via the Java interface and vice versa.
-   * <p>
-   * If the Java <code>ConcurrentMap</code> was previously obtained from an implicit or
-   * explicit call of <code>asConcurrentMap(scala.collection.mutable.ConcurrentMap)</code> then the original
-   * Scala <code>ConcurrentMap</code> will be returned.
+   * Adds an `asScala` method that implicitly converts a Java `ConcurrentMap`
+   * to a Scala mutable `ConcurrentMap`. The returned Scala `ConcurrentMap` is
+   * backed by the provided Java `ConcurrentMap` and any side-effects of using
+   * it via the Scala interface will be visible via the Java interface and
+   * vice versa.
+   *
+   * If the Java `ConcurrentMap` was previously obtained from an implicit or
+   * explicit call of `asConcurrentMap(scala.collection.mutable.ConcurrentMap)`
+   * then the original Scala `ConcurrentMap` will be returned.
    *
-   * @param m The <code>ConcurrentMap</code> to be converted.
-   * @return An object with an `asScala` method that returns a Scala mutable <code>ConcurrentMap</code> view of the argument.
+   * @param m The `ConcurrentMap` to be converted.
+   * @return An object with an `asScala` method that returns a Scala mutable
+   *         `ConcurrentMap` view of the argument.
    */
   implicit def asScalaConcurrentMapConverter[A, B](m: juc.ConcurrentMap[A, B]): AsScala[mutable.ConcurrentMap[A, B]] =
     new AsScala(asScalaConcurrentMap(m))
 
   /**
-   * Adds an `asScala` method that implicitly converts a Java <code>Dictionary</code> to a Scala mutable <code>Map[String, String]</code>.
-   * The returned Scala <code>Map[String, String]</code> is backed by the provided Java
-   * <code>Dictionary</code> and any side-effects of using it via the Scala interface will
-   * be visible via the Java interface and vice versa.
+   * Adds an `asScala` method that implicitly converts a Java `Dictionary`
+   * to a Scala mutable `Map[String, String]`. The returned Scala
+   * `Map[String, String]` is backed by the provided Java `Dictionary` and
+   * any side-effects of using it via the Scala interface will be visible via
+   * the Java interface and vice versa.
    *
-   * @param m The <code>Dictionary</code> to be converted.
-   * @return An object with an `asScala` method that returns a Scala mutable <code>Map[String, String]</code> view of the argument.
+   * @param m The `Dictionary` to be converted.
+   * @return An object with an `asScala` method that returns a Scala mutable
+   *         `Map[String, String]` view of the argument.
    */
   implicit def dictionaryAsScalaMapConverter[A, B](p: ju.Dictionary[A, B]): AsScala[mutable.Map[A, B]] =
     new AsScala(dictionaryAsScalaMap(p))
 
   /**
-   * Adds an `asScala` method that implicitly converts a Java <code>Properties</code> to a Scala mutable <code>Map[String, String]</code>.
-   * The returned Scala <code>Map[String, String]</code> is backed by the provided Java
-   * <code>Properties</code> and any side-effects of using it via the Scala interface will
-   * be visible via the Java interface and vice versa.
+   * Adds an `asScala` method that implicitly converts a Java `Properties`
+   * to a Scala mutable `Map[String, String]`. The returned Scala
+   * `Map[String, String]` is backed by the provided Java `Properties` and
+   * any side-effects of using it via the Scala interface will be visible via
+   * the Java interface and vice versa.
    *
-   * @param m The <code>Properties</code> to be converted.
-   * @return An object with an `asScala` method that returns a Scala mutable <code>Map[String, String]</code> view of the argument.
+   * @param m The `Properties` to be converted.
+   * @return An object with an `asScala` method that returns a Scala mutable
+   *         `Map[String, String]` view of the argument.
    */
   implicit def propertiesAsScalaMapConverter(p: ju.Properties): AsScala[mutable.Map[String, String]] =
     new AsScala(propertiesAsScalaMap(p))
diff --git a/src/library/scala/collection/SeqViewLike.scala b/src/library/scala/collection/SeqViewLike.scala
index 37c66802ef..6e8afdd04f 100644
--- a/src/library/scala/collection/SeqViewLike.scala
+++ b/src/library/scala/collection/SeqViewLike.scala
@@ -6,8 +6,6 @@
 **                          |/                                          **
 \*                                                                      */
 
-
-
 package scala.collection
 
 import generic._
@@ -20,7 +18,8 @@ import annotation.bridge
  *
  *  @define seqViewInfo
  *  $viewInfo
- *  All views for sequences are defined by re-interpreting the `length` and `apply` methods.
+ *  All views for sequences are defined by re-interpreting the `length` and
+ * `apply` methods.
  *
  *  @author Martin Odersky
  *  @version 2.8
@@ -142,5 +141,3 @@ trait SeqViewLike[+A,
 
   override def stringPrefix = "SeqView"
 }
-
-
diff --git a/src/library/scala/collection/TraversableLike.scala b/src/library/scala/collection/TraversableLike.scala
index c8b8dfda5f..1f6c6ff0bb 100644
--- a/src/library/scala/collection/TraversableLike.scala
+++ b/src/library/scala/collection/TraversableLike.scala
@@ -39,8 +39,7 @@ import parallel.ParIterable
  *  a non-strict collection class may defer computation of some of their
  *  elements until after the instance is available as a value.
  *  A typical example of a non-strict collection class is a
- *  <a href="../immutable/Stream.html" target="ContentFrame">
- *  `scala.collection.immutable.Stream`</a>.
+ *  [[scala.collection.immutable/Stream]].
  *  A more general class of examples are `TraversableViews`.
  *
  *  If a collection is an instance of an ordered collection class, traversing
@@ -134,13 +133,15 @@ trait TraversableLike[+A, +Repr] extends HasNewBuilder[A, Repr]
   }
 
   /** Tests whether this $coll is known to have a finite size.
-   *  All strict collections are known to have finite size. For a non-strict collection
-   *  such as `Stream`, the predicate returns `true` if all elements have been computed.
-   *  It returns `false` if the stream is not yet evaluated to the end.
+   *  All strict collections are known to have finite size. For a non-strict
+   *  collection such as `Stream`, the predicate returns `'''true'''` if all
+   *  elements have been computed. It returns `'''false'''` if the stream is
+   *  not yet evaluated to the end.
    *
    *  Note: many collection methods will not work on collections of infinite sizes.
    *
-   *  @return  `true` if this collection is known to have finite size, `false` otherwise.
+   *  @return  `'''true'''` if this collection is known to have finite size,
+   *           `'''false'''` otherwise.
    */
   def hasDefiniteSize = true
 
@@ -157,8 +158,8 @@ trait TraversableLike[+A, +Repr] extends HasNewBuilder[A, Repr]
     ++(that: GenTraversableOnce[B])(bf)
 
   /** Concatenates this $coll with the elements of a traversable collection.
-   *  It differs from ++ in that the right operand determines the type of the
-   *  resulting collection rather than the left one.
+   *  It differs from `++` in that the right operand determines the type of
+   *  the resulting collection rather than the left one.
    *
    *  @param that   the traversable to append.
    *  @tparam B     the element type of the returned collection.
@@ -180,10 +181,12 @@ trait TraversableLike[+A, +Repr] extends HasNewBuilder[A, Repr]
     b.result
   }
 
-  /** This overload exists because: for the implementation of ++: we should reuse
-   *  that of ++ because many collections override it with more efficient versions.
-   *  Since TraversableOnce has no '++' method, we have to implement that directly,
-   *  but Traversable and down can use the overload.
+  /** This overload exists because: for the implementation of `++`: we should
+   *  reuse that of `++` because many collections override it with more
+   *  efficient versions.
+   *
+   *  Since `TraversableOnce` has no `++` method, we have to implement that
+   *  directly, but `Traversable` and down can use the overload.
    */
   def ++:[B >: A, That](that: Traversable[B])(implicit bf: CanBuildFrom[Repr, B, That]): That =
     (that ++ seq)(breakOut)
diff --git a/src/library/scala/collection/generic/IterableForwarder.scala b/src/library/scala/collection/generic/IterableForwarder.scala
index 8f9c4c9542..89b67a6c18 100644
--- a/src/library/scala/collection/generic/IterableForwarder.scala
+++ b/src/library/scala/collection/generic/IterableForwarder.scala
@@ -13,20 +13,15 @@ import scala.collection._
 
 import collection.mutable.Buffer
 
-/** <p>
- *    This trait implements a forwarder for iterable objects. It forwards
- *    all calls to a different iterable object, except for
- *  </p>
- *  <ul>
- *    <li><code>toString</code>, <code>hashCode</code>, <code>equals</code>,
- *      <code>stringPrefix</code></li>
- *    <li><code>newBuilder</code>, <code>view</code></li>
- *    <li>all calls creating a new iterable object of the same kind</li>
- *  </ul>
- *  <p>
- *    The above methods are forwarded by subclass <a href="../IterableProxy.html"
- *    target="ContentFrame"><code>IterableProxy</code></a>.
- *  </p>
+/** This trait implements a forwarder for iterable objects. It forwards
+ *  all calls to a different iterable object, except for
+ *
+ *  - `toString`, `hashCode`, `equals`, `stringPrefix`
+ *  - `newBuilder`, `view`
+ *  - all calls creating a new iterable object of the same kind
+ *
+ *  The above methods are forwarded by subclass <a href="../IterableProxy.html"
+ *  target="ContentFrame">`IterableProxy`</a>.
  *
  *  @author  Martin Odersky
  *  @version 2.8
diff --git a/src/library/scala/collection/generic/SeqForwarder.scala b/src/library/scala/collection/generic/SeqForwarder.scala
index 2624e63a90..eb8e0b3ee9 100644
--- a/src/library/scala/collection/generic/SeqForwarder.scala
+++ b/src/library/scala/collection/generic/SeqForwarder.scala
@@ -6,8 +6,6 @@
 **                          |/                                          **
 \*                                                                      */
 
-
-
 package scala.collection.generic
 import scala.collection._
 import scala.collection.immutable.Range
@@ -15,11 +13,11 @@ import scala.collection.immutable.Range
 /** This class implements a forwarder for sequences. It forwards
  *  all calls to a different sequence object except for
  *
- *    - toString, hashCode, equals, stringPrefix
- *    - newBuilder, view, toSeq
+ *    - `toString`, `hashCode`, `equals`, `stringPrefix`
+ *    - `newBuilder`, `view`, `toSeq`
  *    - all calls creating a new sequence of the same kind
  *
- *  The above methods are forwarded by subclass SeqProxy
+ *  The above methods are forwarded by subclass `SeqProxy`.
  *
  *  @author  Martin Odersky
  *  @version 2.8
@@ -31,29 +29,29 @@ trait SeqForwarder[+A] extends Seq[A] with IterableForwarder[A] {
 
   override def length: Int = underlying.length
   override def apply(idx: Int): A = underlying.apply(idx)
-  override def lengthCompare(len: Int): Int = underlying.lengthCompare(len)
-  override def isDefinedAt(x: Int): Boolean = underlying.isDefinedAt(x)
+  override def lengthCompare(len: Int): Int = underlying lengthCompare len
+  override def isDefinedAt(x: Int): Boolean = underlying isDefinedAt x
   override def segmentLength(p: A => Boolean, from: Int): Int = underlying.segmentLength(p, from)
-  override def prefixLength(p: A => Boolean) = underlying.prefixLength(p)
-  override def indexWhere(p: A => Boolean): Int = underlying.indexWhere(p)
+  override def prefixLength(p: A => Boolean) = underlying prefixLength p
+  override def indexWhere(p: A => Boolean): Int = underlying indexWhere p
   override def indexWhere(p: A => Boolean, from: Int): Int = underlying.indexWhere(p, from)
-  override def findIndexOf(p: A => Boolean): Int = underlying.indexWhere(p)
-  override def indexOf[B >: A](elem: B): Int = underlying.indexOf(elem)
+  override def findIndexOf(p: A => Boolean): Int = underlying indexWhere p
+  override def indexOf[B >: A](elem: B): Int = underlying indexOf elem
   override def indexOf[B >: A](elem: B, from: Int): Int = underlying.indexOf(elem, from)
-  override def lastIndexOf[B >: A](elem: B): Int = underlying.lastIndexOf(elem)
+  override def lastIndexOf[B >: A](elem: B): Int = underlying lastIndexOf elem
   override def lastIndexOf[B >: A](elem: B, end: Int): Int = underlying.lastIndexOf(elem, end)
-  override def lastIndexWhere(p: A => Boolean): Int = underlying.lastIndexWhere(p)
+  override def lastIndexWhere(p: A => Boolean): Int = underlying lastIndexWhere p
   override def lastIndexWhere(p: A => Boolean, end: Int): Int = underlying.lastIndexWhere(p, end)
   override def reverseIterator: Iterator[A] = underlying.reverseIterator
   override def startsWith[B](that: GenSeq[B], offset: Int): Boolean = underlying.startsWith(that, offset)
-  override def startsWith[B](that: GenSeq[B]): Boolean = underlying.startsWith(that)
-  override def endsWith[B](that: GenSeq[B]): Boolean = underlying.endsWith(that)
-  override def indexOfSlice[B >: A](that: GenSeq[B]): Int = underlying.indexOfSlice(that)
+  override def startsWith[B](that: GenSeq[B]): Boolean = underlying startsWith that
+  override def endsWith[B](that: GenSeq[B]): Boolean = underlying endsWith that
+  override def indexOfSlice[B >: A](that: GenSeq[B]): Int = underlying indexOfSlice that
   override def indexOfSlice[B >: A](that: GenSeq[B], from: Int): Int = underlying.indexOfSlice(that, from)
-  override def lastIndexOfSlice[B >: A](that: GenSeq[B]): Int = underlying.lastIndexOfSlice(that)
+  override def lastIndexOfSlice[B >: A](that: GenSeq[B]): Int = underlying lastIndexOfSlice that
   override def lastIndexOfSlice[B >: A](that: GenSeq[B], end: Int): Int = underlying.lastIndexOfSlice(that, end)
-  override def containsSlice[B](that: GenSeq[B]): Boolean = underlying.containsSlice(that)
-  override def contains(elem: Any): Boolean = underlying.contains(elem)
+  override def containsSlice[B](that: GenSeq[B]): Boolean = underlying containsSlice that
+  override def contains(elem: Any): Boolean = underlying contains elem
   override def corresponds[B](that: GenSeq[B])(p: (A,B) => Boolean): Boolean = underlying.corresponds(that)(p)
   override def indices: Range = underlying.indices
 }
diff --git a/src/library/scala/collection/generic/TraversableForwarder.scala b/src/library/scala/collection/generic/TraversableForwarder.scala
index 0049d23a86..6529fe4a79 100644
--- a/src/library/scala/collection/generic/TraversableForwarder.scala
+++ b/src/library/scala/collection/generic/TraversableForwarder.scala
@@ -14,9 +14,10 @@ import immutable.{ List, Stream }
 
 /** This trait implements a forwarder for traversable objects. It forwards
  *  all calls to a different traversable, except for:
- {{{
-  toString, hashCode, equals, stringPrefix, newBuilder, view
- }}}
+ *
+ *  - `toString`, `hashCode`, `equals`, `stringPrefix`
+ *  - `newBuilder`, `view`
+ *
  *  All calls creating a new traversable of the same kind.
  *
  *  @author  Martin Odersky
@@ -27,15 +28,15 @@ trait TraversableForwarder[+A] extends Traversable[A] {
   /** The traversable object to which calls are forwarded. */
   protected def underlying: Traversable[A]
 
-  override def foreach[B](f: A => B): Unit = underlying.foreach(f)
+  override def foreach[B](f: A => B): Unit = underlying foreach f
   override def isEmpty: Boolean = underlying.isEmpty
   override def nonEmpty: Boolean = underlying.nonEmpty
   override def size: Int = underlying.size
   override def hasDefiniteSize = underlying.hasDefiniteSize
-  override def forall(p: A => Boolean): Boolean = underlying.forall(p)
-  override def exists(p: A => Boolean): Boolean = underlying.exists(p)
-  override def count(p: A => Boolean): Int = underlying.count(p)
-  override def find(p: A => Boolean): Option[A] = underlying.find(p)
+  override def forall(p: A => Boolean): Boolean = underlying forall p
+  override def exists(p: A => Boolean): Boolean = underlying exists p
+  override def count(p: A => Boolean): Int = underlying count p
+  override def find(p: A => Boolean): Option[A] = underlying find p
   override def foldLeft[B](z: B)(op: (B, A) => B): B = underlying.foldLeft(z)(op)
   override def /: [B](z: B)(op: (B, A) => B): B = underlying./:(z)(op)
   override def foldRight[B](z: B)(op: (A, B) => B): B = underlying.foldRight(z)(op)
@@ -44,10 +45,10 @@ trait TraversableForwarder[+A] extends Traversable[A] {
   override def reduceLeftOption[B >: A](op: (B, A) => B): Option[B] = underlying.reduceLeftOption(op)
   override def reduceRight[B >: A](op: (A, B) => B): B = underlying.reduceRight(op)
   override def reduceRightOption[B >: A](op: (A, B) => B): Option[B] = underlying.reduceRightOption(op)
-  override def sum[B >: A](implicit num: Numeric[B]): B = underlying.sum(num)
-  override def product[B >: A](implicit num: Numeric[B]): B = underlying.product(num)
-  override def min[B >: A](implicit cmp: Ordering[B]): A = underlying.min(cmp)
-  override def max[B >: A](implicit cmp: Ordering[B]): A = underlying.max(cmp)
+  override def sum[B >: A](implicit num: Numeric[B]): B = underlying sum num
+  override def product[B >: A](implicit num: Numeric[B]): B = underlying product num
+  override def min[B >: A](implicit cmp: Ordering[B]): A = underlying min cmp
+  override def max[B >: A](implicit cmp: Ordering[B]): A = underlying max cmp
   override def head: A = underlying.head
   override def headOption: Option[A] = underlying.headOption
   override def last: A = underlying.last
diff --git a/src/library/scala/collection/immutable/BitSet.scala b/src/library/scala/collection/immutable/BitSet.scala
index 918c79ef0d..bc82c4c133 100644
--- a/src/library/scala/collection/immutable/BitSet.scala
+++ b/src/library/scala/collection/immutable/BitSet.scala
@@ -29,8 +29,7 @@ abstract class BitSet extends Set[Int]
 
   def fromArray(elems: Array[Long]): BitSet = BitSet.fromArray(elems)
 
-  /** Update word at index <code>idx</code>; enlarge set if <code>idx</code>
-   *  outside range of set.
+  /** Update word at index `idx`; enlarge set if `idx` outside range of set.
    */
   protected def updateWord(idx: Int, w: Long): BitSet
 
@@ -103,4 +102,3 @@ object BitSet extends BitSetFactory[BitSet] {
     protected def updateWord(idx: Int, w: Long): BitSet = fromArray(updateArray(elems, idx, w))
   }
 }
-
diff --git a/src/library/scala/collection/immutable/IntMap.scala b/src/library/scala/collection/immutable/IntMap.scala
index ea68b53518..cb1065d786 100644
--- a/src/library/scala/collection/immutable/IntMap.scala
+++ b/src/library/scala/collection/immutable/IntMap.scala
@@ -312,31 +312,32 @@ sealed abstract class IntMap[+T] extends Map[Int, T] with MapLike[Int, T, IntMap
   }
 
   /**
-   * A combined transform and filter function. Returns an IntMap such that for each (key, value) mapping
-   * in this map, if f(key, value) == None the map contains no mapping for key, and if <code>f(key, value)
+   * A combined transform and filter function. Returns an `IntMap` such that
+   * for each `(key, value)` mapping in this map, if `f(key, value) == None`
+   * the map contains no mapping for key, and if `f(key, value)`.
    *
    * @tparam S  The type of the values in the resulting `LongMap`.
    * @param f   The transforming function.
    * @return    The modified map.
    */
   def modifyOrRemove[S](f : (Int, T) => Option[S]) : IntMap[S] = this match {
-      case IntMap.Bin(prefix, mask, left, right) => {
-        val newleft = left.modifyOrRemove(f);
-        val newright = right.modifyOrRemove(f);
-        if ((left eq newleft) && (right eq newright)) this.asInstanceOf[IntMap[S]];
-        else bin(prefix, mask, newleft, newright)
-      }
+    case IntMap.Bin(prefix, mask, left, right) =>
+      val newleft = left.modifyOrRemove(f)
+      val newright = right.modifyOrRemove(f)
+      if ((left eq newleft) && (right eq newright)) this.asInstanceOf[IntMap[S]]
+      else bin(prefix, mask, newleft, newright)
     case IntMap.Tip(key, value) => f(key, value) match {
-      case None => IntMap.Nil;
+      case None =>
+        IntMap.Nil
       case Some(value2) =>
         //hack to preserve sharing
         if (value.asInstanceOf[AnyRef] eq value2.asInstanceOf[AnyRef]) this.asInstanceOf[IntMap[S]]
-        else IntMap.Tip(key, value2);
+        else IntMap.Tip(key, value2)
       }
-    case IntMap.Nil => IntMap.Nil;
+    case IntMap.Nil =>
+      IntMap.Nil
   }
 
-
   /**
    * Forms a union map with that map, using the combining function to resolve conflicts.
    *
@@ -367,9 +368,9 @@ sealed abstract class IntMap[+T] extends Map[Int, T] with MapLike[Int, T, IntMap
   }
 
   /**
-   * Forms the intersection of these two maps with a combining function. The resulting map is
-   * a map that has only keys present in both maps and has values produced from the original mappings
-   * by combining them with f.
+   * Forms the intersection of these two maps with a combining function. The
+   * resulting map is a map that has only keys present in both maps and has
+   * values produced from the original mappings by combining them with `f`.
    *
    * @tparam S      The type of values in `that`.
    * @tparam R      The type of values in the resulting `LongMap`.
@@ -380,29 +381,29 @@ sealed abstract class IntMap[+T] extends Map[Int, T] with MapLike[Int, T, IntMap
   def intersectionWith[S, R](that : IntMap[S], f : (Int, T, S) => R) : IntMap[R] = (this, that) match {
     case (IntMap.Bin(p1, m1, l1, r1), that@IntMap.Bin(p2, m2, l2, r2)) =>
       if (shorter(m1, m2)) {
-        if (!hasMatch(p2, p1, m1)) IntMap.Nil;
-        else if (zero(p2, m1)) l1.intersectionWith(that, f);
-        else r1.intersectionWith(that, f);
+        if (!hasMatch(p2, p1, m1)) IntMap.Nil
+        else if (zero(p2, m1)) l1.intersectionWith(that, f)
+        else r1.intersectionWith(that, f)
       } else if (m1 == m2) bin(p1, m1, l1.intersectionWith(l2, f), r1.intersectionWith(r2, f));
         else {
-        if (!hasMatch(p1, p2, m2)) IntMap.Nil;
-        else if (zero(p1, m2)) this.intersectionWith(l2, f);
-        else this.intersectionWith(r2, f);
+        if (!hasMatch(p1, p2, m2)) IntMap.Nil
+        else if (zero(p1, m2)) this.intersectionWith(l2, f)
+        else this.intersectionWith(r2, f)
       }
     case (IntMap.Tip(key, value), that) => that.get(key) match {
-      case None => IntMap.Nil;
-      case Some(value2) => IntMap.Tip(key, f(key, value, value2));
+      case None => IntMap.Nil
+      case Some(value2) => IntMap.Tip(key, f(key, value, value2))
     }
     case (_, IntMap.Tip(key, value)) => this.get(key) match {
-      case None => IntMap.Nil;
-      case Some(value2) => IntMap.Tip(key, f(key, value2, value));
+      case None => IntMap.Nil
+      case Some(value2) => IntMap.Tip(key, f(key, value2, value))
     }
-    case (_, _) => IntMap.Nil;
+    case (_, _) => IntMap.Nil
   }
 
   /**
-   * Left biased intersection. Returns the map that has all the same mappings as this but only for keys
-   * which are present in the other map.
+   * Left biased intersection. Returns the map that has all the same mappings
+   * as this but only for keys which are present in the other map.
    *
    * @tparam R      The type of values in `that`.
    * @param that    The map to intersect with.
@@ -417,8 +418,8 @@ sealed abstract class IntMap[+T] extends Map[Int, T] with MapLike[Int, T, IntMap
    * The entry with the lowest key value considered in unsigned order.
    */
   final def firstKey : Int = this match {
-    case Bin(_, _, l, r) => l.firstKey;
-    case Tip(k, v) => k;
+    case Bin(_, _, l, r) => l.firstKey
+    case Tip(k, v) => k
     case IntMap.Nil => sys.error("Empty set")
   }
 
@@ -426,8 +427,8 @@ sealed abstract class IntMap[+T] extends Map[Int, T] with MapLike[Int, T, IntMap
    * The entry with the highest key value considered in unsigned order.
    */
   final def lastKey : Int = this match {
-    case Bin(_, _, l, r) => r.lastKey;
-    case Tip(k, v) => k;
+    case Bin(_, _, l, r) => r.lastKey
+    case Tip(k, v) => k
     case IntMap.Nil => sys.error("Empty set")
   }
 }
diff --git a/src/library/scala/collection/immutable/List.scala b/src/library/scala/collection/immutable/List.scala
index 7d962d2908..8f7d92f9e5 100644
--- a/src/library/scala/collection/immutable/List.scala
+++ b/src/library/scala/collection/immutable/List.scala
@@ -246,7 +246,7 @@ sealed abstract class List[+A] extends LinearSeq[A]
     if (isEmpty) Stream.Empty
     else new Stream.Cons(head, tail.toStream)
 
-  /** Like <code>span</code> but with the predicate inverted.
+  /** Like `span` but with the predicate inverted.
    */
   @deprecated("use `span { x => !p(x) }` instead", "2.8.0")
   def break(p: A => Boolean): (List[A], List[A]) = span { x => !p(x) }
@@ -254,12 +254,10 @@ sealed abstract class List[+A] extends LinearSeq[A]
   @deprecated("use `filterNot` instead", "2.8.0")
   def remove(p: A => Boolean): List[A] = filterNot(p)
 
-  /** Computes the difference between this list and the given list
-   *  `that`.
+  /** Computes the difference between this list and the given list `that`.
    *
    *  @param that the list of elements to remove from this list.
-   *  @return     this list without the elements of the given list
-   *              `that`.
+   *  @return     this list without the elements of the given list `that`.
    */
   @deprecated("use `list1 filterNot (list2 contains)` instead", "2.8.0")
   def -- [B >: A](that: List[B]): List[B] = {
@@ -272,8 +270,7 @@ sealed abstract class List[+A] extends LinearSeq[A]
     b.toList
   }
 
-  /** Computes the difference between this list and the given object
-   *  `x`.
+  /** Computes the difference between this list and the given object `x`.
    *
    *  @param x    the object to remove from this list.
    *  @return     this list without occurrences of the given object
@@ -317,7 +314,7 @@ sealed abstract class List[+A] extends LinearSeq[A]
       res.toList
     }
 
-    /** Split a list into two lists of about the same size */
+    /** Split a list `lst` into two lists of about the same size */
     def split(lst: List[A]) = {
       val res1 = new ListBuffer[A]
       val res2 = new ListBuffer[A]
@@ -335,7 +332,6 @@ sealed abstract class List[+A] extends LinearSeq[A]
       (res1.toList, res2.toList)
     }
 
-
     /** Merge-sort the specified list */
     def ms(lst: List[A]): List[A] =
       lst match {
@@ -435,18 +431,16 @@ object List extends SeqFactory[List] {
 
   override def apply[A](xs: A*): List[A] = xs.toList
 
-  /** Create a sorted list with element values
-   * `v<sub>n+1</sub> = step(v<sub>n</sub>)`
-   * where `v<sub>0</sub> = start`
-   * and elements are in the range between `start` (inclusive)
-   * and `end` (exclusive)
+  /** Create a sorted list with element values `v,,>n+1,, = step(v,,n,,)`
+   * where `v,,0,, = start` and elements are in the range between `start`
+   * (inclusive) and `end` (exclusive).
    *
    *  @param start the start value of the list
    *  @param end  the end value of the list
-   *  @param step the increment function of the list, which given `v<sub>n</sub>`,
-   *              computes `v<sub>n+1</sub>`. Must be monotonically increasing
+   *  @param step the increment function of the list, which given `v,,n,,`,
+   *              computes `v,,n+1,,`. Must be monotonically increasing
    *              or decreasing.
-   *  @return     the sorted list of all integers in range [start;end).
+   *  @return     the sorted list of all integers in range `[start;end)`.
    */
   @deprecated("use `iterate` instead", "2.8.0")
   def range(start: Int, end: Int, step: Int => Int): List[Int] = {
@@ -468,7 +462,7 @@ object List extends SeqFactory[List] {
    *
    *  @param n    the length of the resulting list
    *  @param elem the element composing the resulting list
-   *  @return     a list composed of n elements all equal to elem
+   *  @return     a list composed of `n` elements all equal to `elem`
    */
   @deprecated("use `fill` instead", "2.8.0")
   def make[A](n: Int, elem: A): List[A] = {
@@ -529,8 +523,7 @@ object List extends SeqFactory[List] {
       }
 
   /**
-   * Returns the `Left` values in the given `Iterable`
-   * of `Either`s.
+   * Returns the `Left` values in the given `Iterable` of `Either`s.
    */
   @deprecated("use `xs collect { case Left(x: A) => x }` instead of `List.lefts(xs)`", "2.8.0")
   def lefts[A, B](es: Iterable[Either[A, B]]) =
@@ -540,7 +533,7 @@ object List extends SeqFactory[List] {
     })
 
   /**
-   * Returns the `Right` values in the given`Iterable` of  `Either`s.
+   * Returns the `Right` values in the given `Iterable` of  `Either`s.
    */
   @deprecated("use `xs collect { case Right(x: B) => x }` instead of `List.rights(xs)`", "2.8.0")
   def rights[A, B](es: Iterable[Either[A, B]]) =
@@ -667,8 +660,8 @@ object List extends SeqFactory[List] {
    *  to corresponding elements of the argument lists.
    *
    *  @param f function to apply to each pair of elements.
-   *  @return `[f(a0,b0), ..., f(an,bn)]` if the lists are
-   *          `[a0, ..., ak]`, `[b0, ..., bl]` and
+   *  @return `[f(a,,0,,,b,,0,,), ..., f(a,,n,,,b,,n,,)]` if the lists are
+   *          `[a,,0,,, ..., a,,k,,]`, `[b,,0,,, ..., b,,l,,]` and
    *          `n = min(k,l)`
    */
   @deprecated("use `(xs, ys).zipped.map(f)` instead of `List.map2(xs, ys)(f)`", "2.8.0")
@@ -688,12 +681,10 @@ object List extends SeqFactory[List] {
    *  `f` to corresponding elements of the argument lists.
    *
    *  @param f function to apply to each pair of elements.
-   *  @return  `[f(a<sub>0</sub>,b<sub>0</sub>,c<sub>0</sub>),
-   *           ..., f(a<sub>n</sub>,b<sub>n</sub>,c<sub>n</sub>)]`
-   *           if the lists are `[a<sub>0</sub>, ..., a<sub>k</sub>]`,
-   *           `[b<sub>0</sub>, ..., b<sub>l</sub>]`,
-   *           `[c<sub>0</sub>, ..., c<sub>m</sub>]` and
-   *           `n = min(k,l,m)`
+   *  @return  `[f(a,,0,,,b,,0,,,c,,0,,), ..., f(a,,n,,,b,,n,,,c,,n,,)]`
+   *           if the lists are `[a,,0,,, ..., a,,k,,]`,
+   *           `[b<sub>0</sub>, ..., b,,l,,]`,
+   *           `[c<sub>0</sub>, ..., c,,m,,]` and `n = min(k,l,m)`
    */
   @deprecated("use `(xs, ys, zs).zipped.map(f)` instead of `List.map3(xs, ys, zs)(f)`", "2.8.0")
   def map3[A,B,C,D](xs: List[A], ys: List[B], zs: List[C])(f: (A, B, C) => D): List[D] = {
@@ -775,4 +766,3 @@ object List extends SeqFactory[List] {
 /** Only used for list serialization */
 @SerialVersionUID(0L - 8476791151975527571L)
 private[scala] case object ListSerializeEnd
-
diff --git a/src/library/scala/collection/immutable/LongMap.scala b/src/library/scala/collection/immutable/LongMap.scala
index 030dd72d35..6c951a6ff2 100644
--- a/src/library/scala/collection/immutable/LongMap.scala
+++ b/src/library/scala/collection/immutable/LongMap.scala
@@ -309,8 +309,9 @@ sealed abstract class LongMap[+T] extends Map[Long, T] with MapLike[Long, T, Lon
   }
 
   /**
-   * A combined transform and filter function. Returns an LongMap such that for each (key, value) mapping
-   * in this map, if f(key, value) == None the map contains no mapping for key, and if <code>f(key, value)
+   * A combined transform and filter function. Returns an `LongMap` such that
+   * for each `(key, value)` mapping in this map, if `f(key, value) == None`
+   * the map contains no mapping for key, and if `f(key, value)`.
    *
    * @tparam S    The type of the values in the resulting `LongMap`.
    * @param f     The transforming function.
@@ -333,7 +334,6 @@ sealed abstract class LongMap[+T] extends Map[Long, T] with MapLike[Long, T, Lon
     case LongMap.Nil => LongMap.Nil;
   }
 
-
   /**
    * Forms a union map with that map, using the combining function to resolve conflicts.
    *
@@ -364,9 +364,9 @@ sealed abstract class LongMap[+T] extends Map[Long, T] with MapLike[Long, T, Lon
   }
 
   /**
-   * Forms the intersection of these two maps with a combining function. The resulting map is
-   * a map that has only keys present in both maps and has values produced from the original mappings
-   * by combining them with f.
+   * Forms the intersection of these two maps with a combining function. The
+   * resulting map is a map that has only keys present in both maps and has
+   * values produced from the original mappings by combining them with `f`.
    *
    * @tparam S      The type of values in `that`.
    * @tparam R      The type of values in the resulting `LongMap`.
diff --git a/src/library/scala/collection/immutable/Queue.scala b/src/library/scala/collection/immutable/Queue.scala
index e09e4b7196..c3ae2ffa19 100644
--- a/src/library/scala/collection/immutable/Queue.scala
+++ b/src/library/scala/collection/immutable/Queue.scala
@@ -6,8 +6,6 @@
 **                          |/                                          **
 \*                                                                      */
 
-
-
 package scala.collection
 package immutable
 
@@ -36,7 +34,7 @@ class Queue[+A] protected(protected val in: List[A], protected val out: List[A])
   override def companion: GenericCompanion[Queue] = Queue
 
   /** Returns the `n`-th element of this queue.
-   *  The first element is at position 0.
+   *  The first element is at position `0`.
    *
    *  @param  n index of the element to return
    *  @return   the element at position `n` in this queue.
@@ -91,22 +89,22 @@ class Queue[+A] protected(protected val in: List[A], protected val out: List[A])
    */
   def enqueue[B >: A](elem: B) = new Queue(elem :: in, out)
 
-  /** Returns a new queue with all all elements provided by
-   *  an <code>Iterable</code> object added at the end of
-   *  the queue.
-   *  The elements are prepended in the order they
-   *  are given out by the iterator.
+  /** Returns a new queue with all elements provided by an `Iterable` object
+   *  added at the end of the queue.
+   *
+   *  The elements are prepended in the order they are given out by the
+   *  iterator.
    *
    *  @param  iter        an iterable object
    */
   @deprecated("Use `enqueue` instead", "2.7.2")
   def +[B >: A](iter: Iterable[B]) = enqueue(iter)
 
-  /** Returns a new queue with all elements provided by
-   *  an <code>Iterable</code> object added at the end of
-   *  the queue.
-   *  The elements are prepended in the order they
-   *  are given out by the iterator.
+  /** Returns a new queue with all elements provided by an `Iterable` object
+   *  added at the end of the queue.
+   *
+   *  The elements are prepended in the order they are given out by the
+   *  iterator.
    *
    *  @param  iter        an iterable object
    */
diff --git a/src/library/scala/collection/immutable/Stack.scala b/src/library/scala/collection/immutable/Stack.scala
index adbe34ed09..b172908f85 100644
--- a/src/library/scala/collection/immutable/Stack.scala
+++ b/src/library/scala/collection/immutable/Stack.scala
@@ -6,8 +6,6 @@
 **                          |/                                          **
 \*                                                                      */
 
-
-
 package scala.collection
 package immutable
 
@@ -102,7 +100,7 @@ class Stack[+A] protected (protected val elems: List[A])
     else throw new NoSuchElementException("top of empty stack")
 
   /** Removes the top element from the stack.
-   *  Note: should return <code>(A, Stack[A])</code> as for queues (mics)
+   *  Note: should return `(A, Stack[A])` as for queues (mics)
    *
    *  @throws Predef.NoSuchElementException
    *  @return the new stack without the former top element.
@@ -129,4 +127,3 @@ class Stack[+A] protected (protected val elems: List[A])
    */
   override def toString() = elems.mkString("Stack(", ", ", ")")
 }
-
diff --git a/src/library/scala/collection/mutable/AddingBuilder.scala b/src/library/scala/collection/mutable/AddingBuilder.scala
index 6f198b81ad..d7f739d240 100644
--- a/src/library/scala/collection/mutable/AddingBuilder.scala
+++ b/src/library/scala/collection/mutable/AddingBuilder.scala
@@ -6,14 +6,13 @@
 **                          |/                                          **
 \*                                                                      */
 
-
 package scala.collection
 package mutable
 
 import generic._
 
-/** The canonical builder for collections that are addable, i.e. that support an efficient `+` method
- *  which adds an element to the collection.
+/** The canonical builder for collections that are addable, i.e. that support
+ *  an efficient `+` method which adds an element to the collection.
  *
  *  Collections are built from their empty element using this `+` method.
  *  @param  empty   the empty element of the collection.
diff --git a/src/library/scala/collection/mutable/ConcurrentMap.scala b/src/library/scala/collection/mutable/ConcurrentMap.scala
index a88679a8c9..7e526fd4ea 100644
--- a/src/library/scala/collection/mutable/ConcurrentMap.scala
+++ b/src/library/scala/collection/mutable/ConcurrentMap.scala
@@ -1,7 +1,14 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2010-2011, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
 package scala.collection
 package mutable
 
-
 /** A template trait for mutable maps that allow concurrent access.
  *
  *  $concurrentmapinfo
@@ -17,7 +24,8 @@ package mutable
  *  This is a base trait for all Scala concurrent map implementations. It
  *  provides all of the methods a `Map` does, with the difference that all the
  *  changes are atomic. It also describes methods specific to concurrent maps.
- *  Note: The concurrent maps do not accept `null` for keys or values.
+ *
+ *  '''Note''': The concurrent maps do not accept `'''null'''` for keys or values.
  *
  *  @define atomicop
  *  This is an atomic operation.
@@ -25,42 +33,49 @@ package mutable
 trait ConcurrentMap[A, B] extends Map[A, B] {
 
   /**
-   * Associates the given key with a given value, unless the key was already associated with some other value.
+   * Associates the given key with a given value, unless the key was already
+   * associated with some other value.
    *
    * $atomicop
    *
    * @param k   key with which the specified value is to be associated with
    * @param v   value to be associated with the specified key
-   * @return    `Some(oldvalue)` if there was a value `oldvalue` previously associated with the
-   *            specified key, or `None` if there was no mapping for the specified key
+   * @return    `Some(oldvalue)` if there was a value `oldvalue` previously
+   *            associated with the specified key, or `None` if there was no
+   *            mapping for the specified key
    */
   def putIfAbsent(k: A, v: B): Option[B]
 
   /**
-   * Removes the entry for the specified key if its currently mapped to the specified value.
+   * Removes the entry for the specified key if its currently mapped to the
+   * specified value.
    *
    * $atomicop
    *
    * @param k   key for which the entry should be removed
-   * @param v   value expected to be associated with the specified key if the removal is to take place
+   * @param v   value expected to be associated with the specified key if
+   *            the removal is to take place
    * @return    `true` if the removal took place, `false` otherwise
    */
   def remove(k: A, v: B): Boolean
 
   /**
-   * Replaces the entry for the given key only if it was previously mapped to a given value.
+   * Replaces the entry for the given key only if it was previously mapped to
+   * a given value.
    *
    * $atomicop
    *
    * @param k         key for which the entry should be replaced
-   * @param oldvalue  value expected to be associated with the specified key if replacing is to happen
+   * @param oldvalue  value expected to be associated with the specified key
+   *                  if replacing is to happen
    * @param newvalue  value to be associated with the specified key
    * @return          `true` if the entry was replaced, `false` otherwise
    */
   def replace(k: A, oldvalue: B, newvalue: B): Boolean
 
   /**
-   * Replaces the entry for the given key only if it was previously mapped to some value.
+   * Replaces the entry for the given key only if it was previously mapped
+   * to some value.
    *
    * $atomicop
    *
diff --git a/src/library/scala/collection/mutable/MapProxy.scala b/src/library/scala/collection/mutable/MapProxy.scala
index d32f1559c0..5a77a0d23b 100644
--- a/src/library/scala/collection/mutable/MapProxy.scala
+++ b/src/library/scala/collection/mutable/MapProxy.scala
@@ -6,14 +6,11 @@
 **                          |/                                          **
 \*                                                                      */
 
-
-
 package scala.collection
 package mutable
 
 /**
- *  This trait implements a proxy for <a href="Map.html"
- *  target="contentFrame"><code>scala.collection.mutable.Map</code></a>.
+ *  This trait implements a proxy for [[scala.collection.mutable.Map]].
  *
  *  It is most useful for assembling customized map abstractions
  *  dynamically using object composition and forwarding.
diff --git a/src/library/scala/collection/mutable/MutableList.scala b/src/library/scala/collection/mutable/MutableList.scala
index 3eb60698cd..dbabeafd0a 100644
--- a/src/library/scala/collection/mutable/MutableList.scala
+++ b/src/library/scala/collection/mutable/MutableList.scala
@@ -72,17 +72,17 @@ extends LinearSeq[A]
    */
   override def length: Int = len
 
-  /** Returns the <code>n</code>th element of this list.
+  /** Returns the `n`-th element of this list.
    *  @throws IndexOutOfBoundsException if index does not exist.
    */
   override def apply(n: Int): A = first0.apply(n)
 
-  /** Updates the <code>n</code>th element of this list to a new value.
+  /** Updates the `n`-th element of this list to a new value.
    *  @throws IndexOutOfBoundsException if index does not exist.
    */
   def update(n: Int, x: A): Unit = first0.update(n, x)
 
-  /** Returns the <code>n</code>th element of this list or <code>None</code>
+  /** Returns the `n`-th element of this list or `None`
    *  if index does not exist.
    */
   def get(n: Int): Option[A] = first0.get(n)
@@ -93,7 +93,7 @@ extends LinearSeq[A]
     len = len + 1
   }
 
-  protected def appendElem(elem: A): Unit =
+  protected def appendElem(elem: A) {
     if (len == 0) {
       prependElem(elem)
     } else {
@@ -103,6 +103,7 @@ extends LinearSeq[A]
       last0.next = new LinkedList[A] // for performance, use sentinel `object` instead?
       len = len + 1
     }
+  }
 
   @deprecated("use clear() instead", "2.8.0")
   def reset() { clear() }
@@ -116,7 +117,7 @@ extends LinearSeq[A]
     last0.elem
   }
 
-  /** Returns an instance of <code>scala.List</code> containing the same
+  /** Returns an instance of [[scala.List]] containing the same
    *  sequence of elements.
    */
   override def toList: List[A] = first0.toList
@@ -143,11 +144,8 @@ extends LinearSeq[A]
 
 
 object MutableList extends SeqFactory[MutableList] {
-  implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, MutableList[A]] = ReusableCBF.asInstanceOf[GenericCanBuildFrom[A]]
+  implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, MutableList[A]] =
+    ReusableCBF.asInstanceOf[GenericCanBuildFrom[A]]
 
   def newBuilder[A]: Builder[A, MutableList[A]] = new MutableList[A]
 }
-
-
-
-
diff --git a/src/library/scala/collection/mutable/QueueProxy.scala b/src/library/scala/collection/mutable/QueueProxy.scala
index be26d41e69..df86545a70 100644
--- a/src/library/scala/collection/mutable/QueueProxy.scala
+++ b/src/library/scala/collection/mutable/QueueProxy.scala
@@ -1,7 +1,7 @@
 /*                     __                                               *\
 **     ________ ___   / /  ___     Scala API                            **
 **    / __/ __// _ | / /  / _ |    (c) 2003-2011, LAMP/EPFL             **
-**  __\ \/ /__/ __ |/ /__/ __ |                                         **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
 ** /____/\___/_/ |_/____/_/ | |                                         **
 **                          |/                                          **
 \*                                                                      */
@@ -24,9 +24,9 @@ trait QueueProxy[A] extends Queue[A] with Proxy {
 
   def self: Queue[A]
 
-  /** Access element number <code>n</code>.
+  /** Access element number `n`.
    *
-   *  @return  the element at index <code>n</code>.
+   *  @return  the element at index `n`.
    */
   override def apply(n: Int): A = self.apply(n)
 
@@ -46,9 +46,8 @@ trait QueueProxy[A] extends Queue[A] with Proxy {
    */
   override def +=(elem: A): this.type = { self += elem; this }
 
-  /** Adds all elements provided by an iterator
-   *  at the end of the queue. The elements are prepended in the order they
-   *  are given out by the iterator.
+  /** Adds all elements provided by an iterator at the end of the queue. The
+   *  elements are prepended in the order they are given out by the iterator.
    *
    *  @param  iter        an iterator
    */
@@ -61,7 +60,7 @@ trait QueueProxy[A] extends Queue[A] with Proxy {
    *
    *  @param  elems       the elements to add.
    */
-  override def enqueue(elems: A*): Unit = self ++= elems
+  override def enqueue(elems: A*) { self ++= elems }
 
   /** Returns the first element in the queue, and removes this element
    *  from the queue.
diff --git a/src/library/scala/collection/mutable/ResizableArray.scala b/src/library/scala/collection/mutable/ResizableArray.scala
index d57e6477b3..c7d10573c9 100644
--- a/src/library/scala/collection/mutable/ResizableArray.scala
+++ b/src/library/scala/collection/mutable/ResizableArray.scala
@@ -6,8 +6,6 @@
 **                          |/                                          **
 \*                                                                      */
 
-
-
 package scala.collection
 package mutable
 
@@ -62,10 +60,12 @@ trait ResizableArray[A] extends IndexedSeq[A]
     }
   }
 
-  /** Fills the given array <code>xs</code> with at most `len` elements of
-   *  this traversable starting at position `start`.
-   *  Copying will stop once either the end of the current traversable is reached or
-   *  `len` elements have been copied or the end of the array is reached.
+  /** Fills the given array `xs` with at most `len` elements of this
+   *  traversable starting at position `start`.
+   *
+   *  Copying will stop once either the end of the current traversable is
+   *  reached or `len` elements have been copied or the end of the array
+   *  is reached.
    *
    *  @param  xs the array to fill.
    *  @param  start starting index.
@@ -78,7 +78,7 @@ trait ResizableArray[A] extends IndexedSeq[A]
 
   //##########################################################################
 
-  /** remove elements of this array at indices after <code>sz</code>
+  /** Remove elements of this array at indices after `sz`.
    */
   def reduceToSize(sz: Int) {
     require(sz <= size0)
@@ -88,7 +88,7 @@ trait ResizableArray[A] extends IndexedSeq[A]
     }
   }
 
-  /** ensure that the internal array has at n cells */
+  /** Ensure that the internal array has at `n` cells. */
   protected def ensureSize(n: Int) {
     if (n > array.length) {
       var newsize = array.length * 2
@@ -117,6 +117,8 @@ trait ResizableArray[A] extends IndexedSeq[A]
 }
 
 object ResizableArray extends SeqFactory[ResizableArray] {
-  implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, ResizableArray[A]] = ReusableCBF.asInstanceOf[GenericCanBuildFrom[A]]
+  implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, ResizableArray[A]] =
+    ReusableCBF.asInstanceOf[GenericCanBuildFrom[A]]
+
   def newBuilder[A]: Builder[A, ResizableArray[A]] = new ArrayBuffer[A]
 }
diff --git a/src/library/scala/collection/mutable/SetProxy.scala b/src/library/scala/collection/mutable/SetProxy.scala
index 9168c7476b..6ebe1e581b 100644
--- a/src/library/scala/collection/mutable/SetProxy.scala
+++ b/src/library/scala/collection/mutable/SetProxy.scala
@@ -6,12 +6,10 @@
 **                          |/                                          **
 \*                                                                      */
 
-
 package scala.collection
 package mutable
 
-/** This is a simple wrapper class for <a href="Set.html"
- *  target="contentFrame"><code>scala.collection.mutable.Set</code></a>.
+/** This is a simple wrapper class for [[scala.collection.mutable.Set]].
  *  It is most useful for assembling customized set abstractions
  *  dynamically using object composition and forwarding.
  *
diff --git a/src/library/scala/collection/mutable/Stack.scala b/src/library/scala/collection/mutable/Stack.scala
index 63503d77de..aa79d3df7e 100644
--- a/src/library/scala/collection/mutable/Stack.scala
+++ b/src/library/scala/collection/mutable/Stack.scala
@@ -75,7 +75,7 @@ extends Seq[A]
   /** The number of elements in the stack */
   override def length = elems.length
 
-  /** Retrieve n'th element from stack, where top of stack has index 0.
+  /** Retrieve `n`-th element from stack, where top of stack has index `0`.
    *
    *  This is a linear time operation.
    *
@@ -85,8 +85,7 @@ extends Seq[A]
    */
   override def apply(index: Int) = elems(index)
 
-  /** Replace element at index <code>n</code> with the new element
-   *  <code>newelem</code>.
+  /** Replace element at index `n` with the new element `newelem`.
    *
    *  This is a linear time operation.
    *
@@ -114,9 +113,8 @@ extends Seq[A]
   def push(elem1: A, elem2: A, elems: A*): this.type =
     this.push(elem1).push(elem2).pushAll(elems)
 
-  /** Push all elements in the given traversable object onto
-   *  the stack. The last element in the traversable object
-   *  will be on top of the new stack.
+  /** Push all elements in the given traversable object onto the stack. The
+   *  last element in the traversable object will be on top of the new stack.
    *
    *  @param xs the traversable object.
    *  @return the stack with the new elements on top.
@@ -157,8 +155,8 @@ extends Seq[A]
   /** Returns an iterator over all elements on the stack. This iterator
    *  is stable with respect to state changes in the stack object; i.e.
    *  such changes will not be reflected in the iterator. The iterator
-   *  issues elements in the reversed order they were inserted into the stack
-   *  (LIFO order).
+   *  issues elements in the reversed order they were inserted into the
+   *  stack (LIFO order).
    *
    *  @return an iterator over all stack elements.
    */
@@ -181,4 +179,3 @@ extends Seq[A]
    */
   override def clone(): Stack[A] = new Stack[A](elems)
 }
-
diff --git a/src/library/scala/collection/mutable/StringBuilder.scala b/src/library/scala/collection/mutable/StringBuilder.scala
index d6d0951594..c1558f522f 100644
--- a/src/library/scala/collection/mutable/StringBuilder.scala
+++ b/src/library/scala/collection/mutable/StringBuilder.scala
@@ -14,8 +14,8 @@ import annotation.migration
 import immutable.StringLike
 
 /** A builder for mutable sequence of characters.  This class provides an API
- *  mostly compatible with java.lang.StringBuilder, except where there are conflicts
- *  with the Scala collections API (such as the `reverse` method.)
+ *  mostly compatible with `java.lang.StringBuilder`, except where there are
+ *  conflicts with the Scala collections API (such as the `reverse` method.)
  *
  *  @author Stephane Micheloud
  *  @author Martin Odersky
@@ -36,8 +36,8 @@ final class StringBuilder(private val underlying: JavaStringBuilder)
   /** Creates a string builder buffer as builder for this class */
   override protected[this] def newBuilder = new GrowingBuilder(new StringBuilder)
 
-  /** Constructs a string builder initialized with String initValue
-   *  and with additional Char capacity initCapacity.
+  /** Constructs a string builder initialized with string value `initValue`
+   *  and with additional character capacity `initCapacity`.
    */
   def this(initCapacity: Int, initValue: String) =
     this(new JavaStringBuilder(initValue.length + initCapacity) append initValue)
@@ -48,7 +48,7 @@ final class StringBuilder(private val underlying: JavaStringBuilder)
   def this() = this(16, "")
 
   /** Constructs a string builder with no characters in it and an
-   *  initial capacity specified by the capacity argument.
+   *  initial capacity specified by the `capacity` argument.
    *
    *  @param  capacity  the initial capacity.
    *  @throws NegativeArraySizeException  if capacity < 0.
@@ -96,11 +96,11 @@ final class StringBuilder(private val underlying: JavaStringBuilder)
   /** Ensure that the capacity is at least the given argument.
    *  If the argument is greater than the current capacity, new
    *  storage will be allocated with size equal to the given
-   *  argument or to (2 * capacity + 2), whichever is larger.
+   *  argument or to `(2 * capacity + 2)`, whichever is larger.
    *
    *  @param newCapacity    the minimum desired capacity.
    */
-  def ensureCapacity(newCapacity: Int): Unit = underlying ensureCapacity newCapacity
+  def ensureCapacity(newCapacity: Int) { underlying ensureCapacity newCapacity }
 
   /** Returns the Char at the specified index, counting from 0 as in Arrays.
    *
@@ -165,7 +165,8 @@ final class StringBuilder(private val underlying: JavaStringBuilder)
 
   /** For implementing CharSequence.
    */
-  def subSequence(start: Int, end: Int): java.lang.CharSequence = substring(start, end)
+  def subSequence(start: Int, end: Int): java.lang.CharSequence =
+    substring(start, end)
 
   /** Appends the given Char to the end of the sequence.
    */
@@ -177,6 +178,7 @@ final class StringBuilder(private val underlying: JavaStringBuilder)
     underlying append s
     this
   }
+
   def appendAll(xs: String): StringBuilder = {
     underlying append xs
     this
@@ -187,9 +189,9 @@ final class StringBuilder(private val underlying: JavaStringBuilder)
   def +(x: Char): this.type = { +=(x); this }
 
   /** Appends the string representation of the given argument,
-   *  which is converted to a String with String.valueOf.
+   *  which is converted to a String with `String.valueOf`.
    *
-   *  @param  x   an <code>Any</code> object.
+   *  @param  x   an `Any` object.
    *  @return     this StringBuilder.
    */
   def append(x: Any): StringBuilder = {
diff --git a/src/library/scala/collection/mutable/Subscriber.scala b/src/library/scala/collection/mutable/Subscriber.scala
index 29474b686c..c9ae87d558 100644
--- a/src/library/scala/collection/mutable/Subscriber.scala
+++ b/src/library/scala/collection/mutable/Subscriber.scala
@@ -6,16 +6,12 @@
 **                          |/                                          **
 \*                                                                      */
 
-
-
 package scala.collection
 package mutable
 
-
-/** <code>Subscriber[A, B]</code> objects may subscribe to events of
- *  type <code>A</code> published by an object of type <code>B</code>.
- *  <code>B</code> is typically a subtype of <a href="Publisher.html"
- *  target="contentFrame"><code>Publisher</code></a>.
+/** `Subscriber[A, B]` objects may subscribe to events of type `A`
+ *  published by an object of type `B`. `B` is typically a subtype of
+ *  [[scala.collection.immutable.Publisher]].
  *
  *  @author  Matthias Zenger
  *  @author  Martin Odersky
diff --git a/src/library/scala/collection/script/Location.scala b/src/library/scala/collection/script/Location.scala
index fea7e63788..279cb6183c 100644
--- a/src/library/scala/collection/script/Location.scala
+++ b/src/library/scala/collection/script/Location.scala
@@ -6,14 +6,11 @@
 **                          |/                                          **
 \*                                                                      */
 
-
-
 package scala.collection
 package script
 
-
-/** Class <code>Location</code> describes locations in messages implemented by
- *  class <a href="Message.html" target="contentFrame"><code>Message</code></a>.
+/** Class `Location` describes locations in messages implemented by
+ *  class [[scala.collection.script.Message]].
  *
  *  @author  Matthias Zenger
  *  @version 1.0, 10/05/2004
diff --git a/src/library/scala/collection/script/Scriptable.scala b/src/library/scala/collection/script/Scriptable.scala
index 904088efd7..2d9a2949d5 100644
--- a/src/library/scala/collection/script/Scriptable.scala
+++ b/src/library/scala/collection/script/Scriptable.scala
@@ -6,14 +6,11 @@
 **                          |/                                          **
 \*                                                                      */
 
-
-
 package scala.collection
 package script
 
-
-/** Classes that mix in the <code>Scriptable</code> class allow
- *  messages to be sent to objects of that class.
+/** Classes that mix in the `Scriptable` class allow messages to be sent to
+ *  objects of that class.
  *
  *  @author  Matthias Zenger
  *  @version 1.0, 09/05/2004
diff --git a/src/library/scala/concurrent/DelayedLazyVal.scala b/src/library/scala/concurrent/DelayedLazyVal.scala
index 2a143aca72..e308c3b5a6 100644
--- a/src/library/scala/concurrent/DelayedLazyVal.scala
+++ b/src/library/scala/concurrent/DelayedLazyVal.scala
@@ -6,18 +6,17 @@
 **                          |/                                          **
 \*                                                                      */
 
-
 package scala.concurrent
 
 import ops.future
 
-/** A <code>DelayedLazyVal</code> is a wrapper for lengthy
- *  computations which have a valid partially computed result.
- *  The first argument is a function for obtaining the result
- *  at any given point in time, and the second is the lengthy
- *  computation.  Once the computation is complete, the apply()
- *  method will stop recalculating it and return a fixed value
- *  from that point forward.
+/** A `DelayedLazyVal` is a wrapper for lengthy computations which have a
+ *  valid partially computed result.
+ *
+ *  The first argument is a function for obtaining the result at any given
+ *  point in time, and the second is the lengthy computation.  Once the
+ *  computation is complete, the `apply` method will stop recalculating it
+ *  and return a fixed value from that point forward.
  *
  *  @param  f      the function to obtain the current value at any point in time
  *  @param  body   the computation to run to completion in another thread
diff --git a/src/library/scala/concurrent/JavaConversions.scala b/src/library/scala/concurrent/JavaConversions.scala
index 2fa213ee06..db3c490882 100644
--- a/src/library/scala/concurrent/JavaConversions.scala
+++ b/src/library/scala/concurrent/JavaConversions.scala
@@ -6,13 +6,12 @@
 **                          |/                                          **
 \*                                                                      */
 
-
-
 package scala.concurrent
 
 import java.util.concurrent.{ExecutorService, Executor}
 
-/** The <code>JavaConversions</code> object...
+/** The `JavaConversions` object provides implicit converstions supporting
+ *  interoperability between Scala and Java concurrency classes.
  *
  *  @author Philipp Haller
  */
diff --git a/src/library/scala/concurrent/ManagedBlocker.scala b/src/library/scala/concurrent/ManagedBlocker.scala
index a0a58aabc2..9c6f4d51d6 100644
--- a/src/library/scala/concurrent/ManagedBlocker.scala
+++ b/src/library/scala/concurrent/ManagedBlocker.scala
@@ -6,11 +6,9 @@
 **                          |/                                          **
 \*                                                                      */
 
-
-
 package scala.concurrent
 
-/** The <code>ManagedBlocker</code> trait...
+/** The `ManagedBlocker` trait...
  *
  *  @author Philipp Haller
  */
@@ -19,15 +17,16 @@ trait ManagedBlocker {
   /**
    * Possibly blocks the current thread, for example waiting for
    * a lock or condition.
+   *
    * @return true if no additional blocking is necessary (i.e.,
-   * if isReleasable would return true).
+   *         if `isReleasable` would return `true`).
    * @throws InterruptedException if interrupted while waiting
-   * (the method is not required to do so, but is allowed to).
+   *         (the method is not required to do so, but is allowed to).
    */
   def block(): Boolean
 
   /**
-   * Returns true if blocking is unnecessary.
+   * Returns `true` if blocking is unnecessary.
    */
   def isReleasable: Boolean
 
diff --git a/src/library/scala/concurrent/ops.scala b/src/library/scala/concurrent/ops.scala
index db6e81cc26..d0ea51db51 100644
--- a/src/library/scala/concurrent/ops.scala
+++ b/src/library/scala/concurrent/ops.scala
@@ -6,14 +6,12 @@
 **                          |/                                          **
 \*                                                                      */
 
-
-
 package scala.concurrent
 
 import java.lang.Thread
 import scala.util.control.Exception.allCatch
 
-/** The object <code>ops</code> ...
+/** The object `ops` ...
  *
  *  @author  Martin Odersky, Stepan Koltsov, Philipp Haller
  */
@@ -39,8 +37,8 @@ object ops
     runner execute runner.functionAsTask(() => p)
   }
 
-  /** Evaluates an expression asynchronously, and returns a closure for retrieving
-   *  the result.
+  /** Evaluates an expression asynchronously, and returns a closure for
+   *  retrieving the result.
    *
    *  @param  p the expression to evaluate
    *  @return   a closure which returns the result once it has been computed
diff --git a/src/library/scala/concurrent/pilib.scala b/src/library/scala/concurrent/pilib.scala
index 7a3758b9c6..c2968b990d 100644
--- a/src/library/scala/concurrent/pilib.scala
+++ b/src/library/scala/concurrent/pilib.scala
@@ -10,19 +10,17 @@
 
 package scala.concurrent
 
-/** <p>
- *    Library for using Pi-calculus concurrent primitives in
- *    <a href="http://scala-lang.org/" target="_top">Scala</a>. As an
- *    example, the definition of a two-place buffer using the <code>pilib</code>
- *    library looks like:
- *  </p><pre>
- *  <b>def</b> Buffer[a](put: Chan[a], get: Chan[a]) {
- *    <b>def</b> B0 { choice ( put * { x => B1(x) } ) }
- *    <b>def</b> B1(x: a) { choice ( get(x) * B0, put * { y => B2(x, y) } ) }
- *    <b>def</b> B2(x: a, y: a) { choice ( get(x) * B1(y) ) }
+/** Library for using Pi-calculus concurrent primitives in
+ *  [[http://scala-lang.org/#_top Scala]]. As an example, the definition of
+ *  a two-place buffer using the `pilib` library looks like:
+ *  {{{
+ *  def Buffer[a](put: Chan[a], get: Chan[a]) {
+ *    def B0 { choice ( put * { x => B1(x) } ) }
+ *    def B1(x: a) { choice ( get(x) * B0, put * { y => B2(x, y) } ) }
+ *    def B2(x: a, y: a) { choice ( get(x) * B1(y) ) }
  *    B0
  *  }
- *  </pre>
+ *  }}}
  *
  *  @see     <a href="http://scala-lang.org/docu/papers.html" target="_top">
  *           PiLib: A Hosted Language for Pi-Calculus Style Concurrency</a>
diff --git a/src/library/scala/deprecatedName.scala b/src/library/scala/deprecatedName.scala
index e91ce6e8f4..090ec133fe 100644
--- a/src/library/scala/deprecatedName.scala
+++ b/src/library/scala/deprecatedName.scala
@@ -1,3 +1,11 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2010-2011, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
 package scala
 
 import annotation.target._
@@ -7,6 +15,17 @@ import annotation.target._
  * applied as deprecated. Using that name in a named argument generates
  * a deprecation warning.
  *
+ * For instance, evaluating the code below in the Scala interpreter
+ * {{{
+ *   def inc(x: Int, @deprecatedName('y) n: Int): Int = x + n
+ *   inc(1, y = 2)
+ * }}}
+ * will produce the following output:
+ * {{{
+ * warning: there were 1 deprecation warnings; re-run with -deprecation for details
+ * res0: Int = 3
+ * }}}
+ *
  * @since 2.8.1
  */
 @param
diff --git a/src/library/scala/math/Equiv.scala b/src/library/scala/math/Equiv.scala
index 37654bd3fd..ac3a3017f2 100644
--- a/src/library/scala/math/Equiv.scala
+++ b/src/library/scala/math/Equiv.scala
@@ -15,14 +15,14 @@ import java.util.Comparator
  *  equivalence and a representation of equivalence on some type. This
  *  trait is for representing the latter.
  *
- *  An <a href="http://en.wikipedia.org/wiki/Equivalence_relation">equivalence
- *  relation</a> is a binary relation on a type. This relation is exposed as
+ *  An [[http://en.wikipedia.org/wiki/Equivalence_relation equivalence relation]]
+ *  is a binary relation on a type. This relation is exposed as
  *  the `equiv` method of the `Equiv` trait.  The relation must be:
  *
  *  1. reflexive: `equiv(x, x) == true` for any x of type `T`.
- *  2. symmetric: `equiv(x, y) == equiv(y, x)` for any x and y of type T.
- *  3. transitive: if `equiv(x, y) == true` and `equiv(y, z) == true`, then
- *  `equiv(x, z) == true` for any x, y, and z of type T.
+ *  1. symmetric: `equiv(x, y) == equiv(y, x)` for any `x` and `y` of type `T`.
+ *  1. transitive: if `equiv(x, y) == true` and `equiv(y, z) == true`, then
+ *     `equiv(x, z) == true` for any `x`, `y`, and `z` of type `T`.
  *
  *  @author  Geoffrey Washburn, Paul Phillips
  *  @version 1.0, 2008-04-03
@@ -30,7 +30,7 @@ import java.util.Comparator
  */
 
 trait Equiv[T] {
-  /** Returns true iff x is equivalent to y.
+  /** Returns `true` iff `x` is equivalent to `y`.
    */
   def equiv(x: T, y: T): Boolean
 }
diff --git a/src/library/scala/math/Ordered.scala b/src/library/scala/math/Ordered.scala
index 64cbd5e8f2..9645b9b840 100644
--- a/src/library/scala/math/Ordered.scala
+++ b/src/library/scala/math/Ordered.scala
@@ -6,39 +6,37 @@
 **                          |/                                          **
 \*                                                                      */
 
-
-
 package scala.math
 
 /** A trait for totally ordered data.
  *
- * Note that since version 2006-07-24 this trait is no longer covariant in a.
+ *  Note that since version 2006-07-24 this trait is no longer covariant
+ *  in `A`.
  *
- * It is important that the equals method for an instance of
- * Ordered[A] be consistent with the compare method.  However,
- * due to limitations inherent in the type erasure semantics,
- * there is no reasonable way to provide a default implementation
- * of equality for instances of Ordered[A].  Therefore, if you need
- * to be able to use equality on an instance of Ordered[A] you must
- * provide it yourself either when inheriting or instantiating.
+ *  It is important that the `equals` method for an instance of `Ordered[A]`
+ *  be consistent with the compare method.  However,  due to limitations
+ *  inherent in the type erasure semantics, there is no reasonable way to
+ *  provide a default implementation of equality for instances of `Ordered[A]`.
+ *  Therefore, if you need to be able to use equality on an instance of
+ *  `Ordered[A]` you must provide it yourself either when inheriting or
+ *  instantiating.
  *
- * It is important that the hashCode method for an instance of
- * Ordered[A] be consistent with the compare method. However,
- * it is not possible to provide a sensible default implementation.
- * Therefore, if you need to be able compute the hash of an
- * instance of Ordered[A] you must provide it yourself either when
- * inheriting or instantiating.
+ *  It is important that the `hashCode` method for an instance of `Ordered[A]`
+ *  be consistent with the `compare` method. However, it is not possible to
+ *  provide a sensible default implementation. Therefore, if you need to be
+ *  able compute the hash of an instance of `Ordered[A]` you must provide it
+ *  yourself either when inheriting or instantiating.
  *
  *  @author  Martin Odersky
  *  @version 1.1, 2006-07-24
  */
 trait Ordered[A] extends java.lang.Comparable[A] {
 
-  /** Result of comparing <code>this</code> with operand <code>that</code>.
-   *  returns <code>x</code> where
-   *  <code>x &lt; 0</code>    iff    <code>this &lt; that</code>
-   *  <code>x == 0</code>   iff    <code>this == that</code>
-   *  <code>x &gt; 0</code>    iff    <code>this &gt; that</code>
+  /** Result of comparing `this` with operand `that`.
+   *  returns `x` where
+   *  `x &lt; 0`    iff    `this &lt; that`
+   *  `x == 0`     iff    `this == that`
+   *  `x &gt; 0`    iff    `this &gt; that`
    */
   def compare(that: A): Int
 
@@ -50,7 +48,7 @@ trait Ordered[A] extends java.lang.Comparable[A] {
 }
 
 object Ordered {
-  /** Lens from Ordering[T] to Ordered[T] */
+  /** Lens from `Ordering[T]` to `Ordered[T]` */
   implicit def orderingToOrdered[T](x: T)(implicit ord: Ordering[T]): Ordered[T] =
     new Ordered[T] { def compare(that: T): Int = ord.compare(x, that) }
 }
diff --git a/src/library/scala/math/Ordering.scala b/src/library/scala/math/Ordering.scala
index 10e42a6de4..8582a11f2d 100644
--- a/src/library/scala/math/Ordering.scala
+++ b/src/library/scala/math/Ordering.scala
@@ -11,37 +11,34 @@ package scala.math
 import java.util.Comparator
 
 /** A trait for representing total orderings.  It is important to
- * distinguish between a type that has a total order and a representation
- * of total ordering on some type.  This trait is for the latter.
+ *  distinguish between a type that has a total order and a representation
+ *  of total ordering on some type.  This trait is for the latter.
  *
- * A [[http://en.wikipedia.org/wiki/Total_order|total ordering]]
- * is a binary relation on a type `T` that is also an equivalence relation
- * and partial ordering on values of type `T`.  This relation is exposed as
- * the `compare` method of the `Ordering` trait.
+ *  A [[http://en.wikipedia.org/wiki/Total_order total ordering]]
+ *  is a binary relation on a type `T` that is also an equivalence relation
+ *  and partial ordering on values of type `T`.  This relation is exposed as
+ *  the `compare` method of the `Ordering` trait.
  *
- * This relation must be:
- {{{
-      reflexive:  x == x
-  antisymmetric:  if x <= y && y <= x, then x == y
-     transitive:  if x <= y && y <= z, then x <= z
- }}}
+ *  This relation must be:
  *
- * @author Geoffrey Washburn
- * @version 0.9.5, 2008-04-15
- * @since 2.7
+ *  - reflexive:  `x == x`
+ *  - antisymmetric:  if `x <= y && y <= x`, then `x == y`
+ *  - transitive:  if `x <= y && y <= z`, then `x <= z`
+ *
+ *  @author Geoffrey Washburn
+ *  @version 0.9.5, 2008-04-15
+ *  @since 2.7
  */
 @annotation.implicitNotFound(msg = "No implicit Ordering defined for ${T}.")
 trait Ordering[T] extends Comparator[T] with PartialOrdering[T] with Serializable {
   outer =>
 
-  /** An Ordering is defined at all x and y. */
+  /** An `Ordering` is defined at all `x` and `y`. */
   def tryCompare(x: T, y: T) = Some(compare(x, y))
 
- /** Returns a negative integer iff `x` comes before
-   * `y` in the ordering, returns 0 iff `x`
-   * is the same in the ordering as `y`, and returns a
-   * positive number iff `x` comes after
-   * `y` in the ordering.
+ /** Returns a negative integer iff `x` comes before `y` in the ordering,
+   * returns 0 iff `x` is the same in the ordering as `y`, and returns a
+   * positive number iff `x` comes after `y` in the ordering.
    */
   def compare(x: T, y: T): Int
 
@@ -76,7 +73,7 @@ trait Ordering[T] extends Comparator[T] with PartialOrdering[T] with Serializabl
     def compare(x: T, y: T) = outer.compare(y, x)
   }
 
-  /** Given a function U => T, creates Ordering[U]. */
+  /** Given a function `U => T`, creates `Ordering[U]`. */
   def on[U](f: U => T): Ordering[U] = new Ordering[U] {
     def compare(x: U, y: U) = outer.compare(f(x), f(y))
   }
@@ -96,9 +93,9 @@ trait Ordering[T] extends Comparator[T] with PartialOrdering[T] with Serializabl
 trait LowPriorityOrderingImplicits {
   /** This would conflict with all the nice implicit Orderings
    *  available, but thanks to the magic of prioritized implicits
-   *  via subclassing we can make Ordered[A] => Ordering[A] only
-   *  turn up if nothing else works.  Since Ordered[A] extends
-   *  Comparable[A] anyway, we can throw in some java interop too.
+   *  via subclassing we can make `Ordered[A] => Ordering[A]` only
+   *  turn up if nothing else works.  Since `Ordered[A]` extends
+   *  `Comparable[A]` anyway, we can throw in some Java interop too.
    */
   implicit def ordered[A <% Comparable[A]]: Ordering[A] = new Ordering[A] {
     def compare(x: A, y: A): Int = x compareTo y
@@ -113,7 +110,7 @@ object Ordering extends LowPriorityOrderingImplicits {
 
   trait ExtraImplicits {
     /** Not in the standard scope due to the potential for divergence:
-     *  For instance implicitly[Ordering[Any]] diverges in its presence.
+     *  For instance `implicitly[Ordering[Any]]` diverges in its presence.
      */
     implicit def seqDerivedOrdering[CC[X] <: collection.Seq[X], T](implicit ord: Ordering[T]): Ordering[CC[T]] =
       new Ordering[CC[T]] {
@@ -130,9 +127,9 @@ object Ordering extends LowPriorityOrderingImplicits {
         }
       }
 
-    /** This implicit creates a conversion from any value for which an implicit Ordering
-     *  exists to the class which creates infix operations.  With it imported, you can write
-     *  methods as follows:
+    /** This implicit creates a conversion from any value for which an
+     *  implicit `Ordering` exists to the class which creates infix operations.
+     *  With it imported, you can write methods as follows:
      *  {{{
      *  def lessThen[T: Ordering](x: T, y: T) = x < y
      *  }}}
diff --git a/src/library/scala/reflect/BeanInfo.scala b/src/library/scala/reflect/BeanInfo.scala
index ba8cc8b9e2..0522377f8e 100644
--- a/src/library/scala/reflect/BeanInfo.scala
+++ b/src/library/scala/reflect/BeanInfo.scala
@@ -6,15 +6,14 @@
 **                          |/                                          **
 \*                                                                      */
 
-
 package scala.reflect
 
-/** <p>
- *    This annotation indicates that a JavaBean-compliant BeanInfo
- *    class should be generated for this annotated Scala class.
- *    A val becomes a read-only property. A var becomes a read-write
- *    property. A def becomes a method.
- *  </p>
+/** This annotation indicates that a JavaBean-compliant `BeanInfo` class
+ *  should be generated for this annotated Scala class.
+ *
+ *  - A `'''val'''` becomes a read-only property.
+ *  - A `'''var'''` becomes a read-write property.
+ *  - A `'''def'''` becomes a method.
  *
  *  @author Ross Judson (rjudson@managedobjects.com)
  */
diff --git a/src/library/scala/reflect/BooleanBeanProperty.scala b/src/library/scala/reflect/BooleanBeanProperty.scala
index fa0bf27802..97c05ffb7c 100644
--- a/src/library/scala/reflect/BooleanBeanProperty.scala
+++ b/src/library/scala/reflect/BooleanBeanProperty.scala
@@ -6,18 +6,13 @@
 **                          |/                                          **
 \*                                                                      */
 
-
-
 package scala.reflect
 
 import annotation.target._
 
-/** <p>
- *    This annotation has the same functionality as
- *    <code>scala.reflect.BeanProperty</code>, but the generated
- *    Bean getter will be named <code>isFieldName</code> instead
- *    of <code>getFieldName</code>.
- *  </p>
+/** This annotation has the same functionality as
+ *  `scala.reflect.BeanProperty`, but the generated Bean getter will be
+ *  named `isFieldName` instead of `getFieldName`.
  */
 @field
 class BooleanBeanProperty extends annotation.StaticAnnotation
diff --git a/src/library/scala/reflect/ClassManifest.scala b/src/library/scala/reflect/ClassManifest.scala
index 2189f6df82..3dff72659a 100644
--- a/src/library/scala/reflect/ClassManifest.scala
+++ b/src/library/scala/reflect/ClassManifest.scala
@@ -11,21 +11,20 @@ package scala.reflect
 import scala.collection.mutable.{ WrappedArray, ArrayBuilder }
 import java.lang.{ Class => JClass }
 
-/** A ClassManifest[T] is an opaque descriptor for type T.
+/** A `ClassManifest[T]` is an opaque descriptor for type `T`.
  *  It is used by the compiler to preserve information necessary
- *  for instantiating Arrays in those cases where the element type
+ *  for instantiating `Arrays` in those cases where the element type
  *  is unknown at compile time.
  *
- *  The type-relation operators make an effort to present a
- *  more accurate picture than can be realized with erased types,
- *  but they should not be relied upon to give correct answers.
- *  In particular they are likely to be wrong when variance is
- *  involved or when a subtype has a different number of type
- *  arguments than a supertype.
+ *  The type-relation operators make an effort to present a more accurate
+ *  picture than can be realized with erased types, but they should not be
+ *  relied upon to give correct answers. In particular they are likely to
+ *  be wrong when variance is involved or when a subtype has a different
+ *  number of type arguments than a supertype.
  */
 trait ClassManifest[T] extends OptManifest[T] with Equals with Serializable {
-  /** A class representing the type U to which T would be erased. Note
-    * that there is no subtyping relationship between T and U. */
+  /** A class representing the type `U` to which `T` would be erased. Note
+    * that there is no subtyping relationship between `T` and `U`. */
   def erasure: JClass[_]
 
   private def subtype(sub: JClass[_], sup: JClass[_]): Boolean = {
@@ -89,8 +88,8 @@ trait ClassManifest[T] extends OptManifest[T] with Equals with Serializable {
     that <:< this
 
   def canEqual(other: Any) = other match {
-    case _: ClassManifest[_]  => true
-    case _                    => false
+    case _: ClassManifest[_] => true
+    case _                   => false
   }
 
   /** Tests whether the type represented by this manifest is equal to
@@ -144,9 +143,8 @@ trait ClassManifest[T] extends OptManifest[T] with Equals with Serializable {
     else ""
 }
 
-/** The object ClassManifest defines factory methods for manifests.
- *  It is intended for use by the compiler and should not be used
- *  in client code.
+/** The object `ClassManifest` defines factory methods for manifests.
+ *  It is intended for use by the compiler and should not be used in client code.
  */
 object ClassManifest {
   val Byte    = Manifest.Byte
diff --git a/src/library/scala/reflect/Manifest.scala b/src/library/scala/reflect/Manifest.scala
index a75f90ebf0..10512e134a 100644
--- a/src/library/scala/reflect/Manifest.scala
+++ b/src/library/scala/reflect/Manifest.scala
@@ -10,12 +10,12 @@ package scala.reflect
 
 import scala.collection.mutable.{ ArrayBuilder, WrappedArray }
 
-/** A Manifest[T] is an opaque descriptor for type T.  Its
- *  supported use is to give access to the erasure of the type
- *  as a Class instance, as is necessary for the creation of native
- *  Arrays if the class is not known at compile time.
+/** A `Manifest[T]` is an opaque descriptor for type T.  Its supported use
+ *  is to give access to the erasure of the type as a `Class` instance, as
+ *  is necessary for the creation of native `Arrays` if the class is not
+ *  known at compile time.
  *
- *  The type-relation operators <:< and =:= should be considered
+ *  The type-relation operators `<:<` and `=:=` should be considered
  *  approximations only, as there are numerous aspects of type conformance
  *  which are not yet adequately represented in manifests.
  *
@@ -70,7 +70,7 @@ trait AnyValManifest[T] extends Manifest[T] with Equals {
   override def hashCode = System.identityHashCode(this)
 }
 
-/** The object Manifest defines factory methods for manifests.
+/** The object `Manifest` defines factory methods for manifests.
  *  It is intended for use by the compiler and should not be used
  *  in client code.
  */
diff --git a/src/library/scala/reflect/OptManifest.scala b/src/library/scala/reflect/OptManifest.scala
index 8e64da32fb..2a955deb2c 100644
--- a/src/library/scala/reflect/OptManifest.scala
+++ b/src/library/scala/reflect/OptManifest.scala
@@ -6,15 +6,11 @@
 **                          |/                                          **
 \*                                                                      */
 
-
-
 package scala.reflect
 
-/** <p>
- *    A <code>OptManifest[T]</code> is an optional <a href="Manifest.html"
- *    target="ContentFrame"><code>Manifest</code></a>.<br/>
- *    It is either a <code>Manifest</code> or the value <code>NoManifest</code>.
- *  </p>
+/** A `OptManifest[T]` is an optional [[scala.reflect.Manifest]].
+ *
+ *  It is either a `Manifest` or the value `NoManifest`.
  *
  *  @author Martin Odersky
  */
diff --git a/src/library/scala/reflect/generic/HasFlags.scala b/src/library/scala/reflect/generic/HasFlags.scala
index 3d9d121adf..7f869bfdc2 100644
--- a/src/library/scala/reflect/generic/HasFlags.scala
+++ b/src/library/scala/reflect/generic/HasFlags.scala
@@ -1,3 +1,8 @@
+/* NSC -- new Scala compiler
+ * Copyright 2005-2011 LAMP/EPFL
+ * @author  Martin Odersky
+ */
+
 package scala.reflect
 package generic
 
@@ -73,15 +78,16 @@ package generic
 
 import Flags._
 
-/** Common code utilized by Modifiers (which carry the flags associated
- *  with Trees) and Symbol.
+/** Common code utilized by `Modifiers` (which carry the flags associated
+ *  with `Trees`) and `Symbol`.
  */
-@deprecated("scala.reflect.generic will be removed", "2.9.1") trait HasFlags {
+@deprecated("scala.reflect.generic will be removed", "2.9.1")
+trait HasFlags {
   type FlagsType
   type AccessBoundaryType
   type AnnotationType
 
-  /** Though both Symbol and Modifiers widen this method to public, it's
+  /** Though both `Symbol` and `Modifiers` widen this method to public, it's
    *  defined protected here to give us the option in the future to route
    *  flag methods through accessors and disallow raw flag manipulation.
    *  And after that, perhaps, on some magical day: a typesafe enumeration.
@@ -93,8 +99,8 @@ import Flags._
    */
   def hasFlagsToString(mask: FlagsType): String
 
-  /** Access level encoding: there are three scala flags (PRIVATE, PROTECTED,
-   *  and LOCAL) which combine with value privateWithin (the "foo" in private[foo])
+  /** Access level encoding: there are three scala flags (`PRIVATE`, `PROTECTED`,
+   *  and `LOCAL`) which combine with value privateWithin (the `foo` in `private[foo]`)
    *  to define from where an entity can be accessed.  The meanings are as follows:
    *
    *  PRIVATE     access restricted to class only.
@@ -102,18 +108,19 @@ import Flags._
    *  LOCAL       can only be set in conjunction with PRIVATE or PROTECTED.
    *              Further restricts access to the same object instance.
    *
-   *  In addition, privateWithin can be used to set a visibility barrier.
+   *  In addition, `privateWithin` can be used to set a visibility barrier.
    *  When set, everything contained in the named enclosing package or class
-   *  has access.  It is incompatible with PRIVATE or LOCAL, but is additive
-   *  with PROTECTED (i.e. if either the flags or privateWithin allow access,
+   *  has access.  It is incompatible with `PRIVATE` or `LOCAL`, but is additive
+   *  with `PROTECTED` (i.e. if either the flags or privateWithin allow access,
    *  then it is allowed.)
    *
-   *  The java access levels translate as follows:
-   *
+   *  The Java access levels translate as follows:
+   *  {{{
    *  java private:     hasFlag(PRIVATE)                && !hasAccessBoundary
    *  java package:     !hasFlag(PRIVATE | PROTECTED)   && (privateWithin == enclosing package)
    *  java protected:   hasFlag(PROTECTED)              && (privateWithin == enclosing package)
    *  java public:      !hasFlag(PRIVATE | PROTECTED)   && !hasAccessBoundary
+   *  }}}
    */
   def privateWithin: AccessBoundaryType
 
@@ -158,7 +165,7 @@ import Flags._
   def isSuperAccessor  = hasFlag(SUPERACCESSOR)
   def isLifted         = hasFlag(LIFTED)
 
-  // Formerly the Modifiers impl did not include the access boundary check,
+  // Formerly the `Modifiers` impl did not include the access boundary check,
   // which must have been a bug.
   def isPublic = hasNoFlags(PRIVATE | PROTECTED) && !hasAccessBoundary
 
@@ -228,4 +235,3 @@ import Flags._
   // def isAccessor      = hasFlag(ACCESSOR )
   // final def isGetterOrSetter = hasAccessorFlag
 }
-
diff --git a/src/library/scala/reflect/generic/Trees.scala b/src/library/scala/reflect/generic/Trees.scala
index dace1628da..30dc68981f 100755
--- a/src/library/scala/reflect/generic/Trees.scala
+++ b/src/library/scala/reflect/generic/Trees.scala
@@ -225,22 +225,17 @@ import Flags._
   case class TypeDef(mods: Modifiers, name: TypeName, tparams: List[TypeDef], rhs: Tree)
        extends MemberDef
 
-  /** <p>
-   *    Labelled expression - the symbols in the array (must be Idents!)
-   *    are those the label takes as argument
-   *  </p>
-   *  <p>
-   *    The symbol that is given to the labeldef should have a MethodType
-   *    (as if it were a nested function)
-   *  </p>
-   *  <p>
-   *    Jumps are apply nodes attributed with label symbol, the arguments
-   *    will get assigned to the idents.
-   *  </p>
-   *  <p>
-   *  Note: on 2005-06-09 Martin, Iuli, Burak agreed to have forward
-   *        jumps within a Block.
-   *  </p>
+  /** Labelled expression - the symbols in the array (must be Idents!)
+   *  are those the label takes as argument.
+   *
+   *  The symbol that is given to the `labeldef` should have a `MethodType`
+   *  (as if it were a nested function).
+   *
+   *  Jumps are apply nodes attributed with label symbol, the arguments
+   *  will get assigned to the idents.
+   *
+   *  '''Note''': on 2005-06-09 Martin, Iuli, Burak agreed to have forward
+   *        jumps within a `Block`.
    */
   case class LabelDef(name: TermName, params: List[Ident], rhs: Tree)
        extends DefTree with TermTree
@@ -337,20 +332,17 @@ import Flags._
   case class If(cond: Tree, thenp: Tree, elsep: Tree)
        extends TermTree
 
-  /** <p>
-   *    Pattern matching expression  (before explicitouter)
-   *    Switch statements            (after explicitouter)
-   *  </p>
-   *  <p>
-   *    After explicitouter, cases will satisfy the following constraints:
-   *  </p>
-   *  <ul>
-   *    <li>all guards are EmptyTree,</li>
-   *    <li>all patterns will be either <code>Literal(Constant(x:Int))</code>
-   *      or <code>Alternative(lit|...|lit)</code></li>
-   *    <li>except for an "otherwise" branch, which has pattern
-   *      <code>Ident(nme.WILDCARD)</code></li>
-   *  </ul>
+  /**
+   *  - Pattern matching expression  (before explicitouter)
+   *  - Switch statements            (after explicitouter)
+   *
+   *  After explicitouter, cases will satisfy the following constraints:
+   *
+   *  - all guards are EmptyTree,
+   *  - all patterns will be either `Literal(Constant(x:Int))`
+   *    or `Alternative(lit|...|lit)`
+   *  - except for an "otherwise" branch, which has pattern
+   *    `Ident(nme.WILDCARD)`
    */
   case class Match(selector: Tree, cases: List[CaseDef])
        extends TermTree
@@ -400,10 +392,10 @@ import Flags._
   }
 
   /** Dynamic value application.
-   *  In a dynamic application   q.f(as)
-   *   - q is stored in qual
-   *   - as is stored in args
-   *   - f is stored as the node's symbol field.
+   *  In a dynamic application `q.f(as)`
+   *   - `q` is stored in parameter `qual`
+   *   - `as` is stored in parameter `args`
+   *   - `f` is stored as the node's symbol field.
    */
   case class ApplyDynamic(qual: Tree, args: List[Tree])
        extends TermTree with SymTree
diff --git a/src/library/scala/remote.scala b/src/library/scala/remote.scala
index 01805101be..bf6b440031 100644
--- a/src/library/scala/remote.scala
+++ b/src/library/scala/remote.scala
@@ -6,11 +6,22 @@
 **                          |/                                          **
 \*                                                                      */
 
-
-
 package scala
 
 /**
  * An annotation that designates the class to which it is applied as remotable.
+ *
+ * For instance, the Scala code
+ * {{{
+ * @remote trait Hello {
+ *   def sayHello(): String
+ * }
+ * }}}
+ * is equivalent to the following Java code:
+ * {{{
+ * public interface Hello extends java.rmi.Remote {
+ *     String sayHello() throws java.rmi.RemoteException;
+ * }
+ * }}}
  */
 class remote extends annotation.StaticAnnotation {}
diff --git a/src/library/scala/sys/process/ProcessLogger.scala b/src/library/scala/sys/process/ProcessLogger.scala
index 1ce77c9196..556d9ad922 100644
--- a/src/library/scala/sys/process/ProcessLogger.scala
+++ b/src/library/scala/sys/process/ProcessLogger.scala
@@ -12,10 +12,10 @@ package process
 import java.io._
 
 /** Encapsulates the output and error streams of a running process.
- *  Many of the methods of ProcessBuilder accept a ProcessLogger as
+ *  Many of the methods of `ProcessBuilder` accept a `ProcessLogger` as
  *  an argument.
  *
- *  @see      ProcessBuilder
+ *  @see [[scala.sys.process.ProcessBuilder]]
  */
 trait ProcessLogger {
   /** Will be called with each line read from the process output stream.
@@ -26,14 +26,15 @@ trait ProcessLogger {
    */
   def err(s: => String): Unit
 
-  /** If a process is begun with one of these ProcessBuilder methods:
-   *
+  /** If a process is begun with one of these `ProcessBuilder` methods:
+   *  {{{
    *    def !(log: ProcessLogger): Int
    *    def !<(log: ProcessLogger): Int
-   *
+   *  }}}
    *  The run will be wrapped in a call to buffer.  This gives the logger
    *  an opportunity to set up and tear down buffering.  At present the
-   *  library implementations of ProcessLogger simply execute the body unbuffered.
+   *  library implementations of `ProcessLogger` simply execute the body
+   *  unbuffered.
    */
   def buffer[T](f: => T): T
 }
@@ -58,9 +59,10 @@ class FileProcessLogger(file: File) extends ProcessLogger with Closeable with Fl
 object ProcessLogger {
   def apply(file: File): FileProcessLogger = new FileProcessLogger(file)
   def apply(fn: String => Unit): ProcessLogger = apply(fn, fn)
-  def apply(fout: String => Unit, ferr: String => Unit): ProcessLogger = new ProcessLogger {
-    def out(s: => String): Unit = fout(s)
-    def err(s: => String): Unit = ferr(s)
-    def buffer[T](f: => T): T = f
-  }
+  def apply(fout: String => Unit, ferr: String => Unit): ProcessLogger =
+    new ProcessLogger {
+      def out(s: => String): Unit = fout(s)
+      def err(s: => String): Unit = ferr(s)
+      def buffer[T](f: => T): T = f
+    }
 }
diff --git a/src/library/scala/testing/Benchmark.scala b/src/library/scala/testing/Benchmark.scala
index c6ab992306..a7548aa844 100644
--- a/src/library/scala/testing/Benchmark.scala
+++ b/src/library/scala/testing/Benchmark.scala
@@ -6,33 +6,24 @@
 **                          |/                                          **
 \*                                                                      */
 
-
-
 package scala.testing
 
-
 import compat.Platform
 
-/** <p>
- *    <code>Benchmark</code> can be used to quickly turn an existing
- *    class into a benchmark. Here is a short example:
- *  </p><pre>
- *  <b>object</b> sort1 <b>extends</b> Sorter <b>with</b> Benchmark {
- *    <b>def</b> run = sort(List.range(1, 1000))
+/** `Benchmark` can be used to quickly turn an existing class into a
+ *  benchmark. Here is a short example:
+ *  {{{
+ *  object sort1 extends Sorter with Benchmark {
+ *    def run = sort(List.range(1, 1000))
  *  }
- *  </pre>
- *  <p>
- *    The <code>run</code> method has to be defined by the user, who
- *    will perform the timed operation there.
- *    Run the benchmark as follows:
- *  </p>
- *  <pre>
- *  &gt; scala sort1 5 times.log
- *  </pre>
- *  <p>
- *    This will run the benchmark 5 times and log the execution times in
- *    a file called <code>times.log</code>
- *  </p>
+ *  }}}
+ *  The `run` method has to be defined by the user, who will perform the
+ *  timed operation there. Run the benchmark as follows:
+ *  {{{
+ *  > scala sort1 5 times.log
+ *  }}}
+ *  This will run the benchmark 5 times and log the execution times in
+ *  a file called `times.log`.
  *
  *  @author Iulian Dragos, Burak Emir
  */
@@ -49,9 +40,8 @@ trait Benchmark {
 
   var multiplier = 1
 
-  /** Run the benchmark the specified number of times
-   *  and return a list with the execution times in milliseconds
-   *  in reverse order of the execution
+  /** Run the benchmark the specified number of times and return a list with
+   *  the execution times in milliseconds in reverse order of the execution.
    *
    *  @param noTimes ...
    *  @return        ...
@@ -75,8 +65,7 @@ trait Benchmark {
    *  should not be measured. This method is run before each call to the
    *  benchmark payload, 'run'.
    */
-  def setUp() {
-  }
+  def setUp() {}
 
   /** Perform cleanup operations after each 'run'. For micro benchmarks,
    *  think about using the result of 'run' in a way that prevents the JVM
@@ -84,8 +73,7 @@ trait Benchmark {
    *  write the results to a file. The execution time of this method is not
    *  measured.
    */
-  def tearDown() {
-  }
+  def tearDown() {}
 
   /** a string that is written at the beginning of the output line
    *   that contains the timings. By default, this is the class name.
@@ -93,11 +81,10 @@ trait Benchmark {
   def prefix: String = getClass().getName()
 
   /**
-   * The entry point. It takes two arguments (n),
-   *  and an optional argument multiplier (mult).
-   *  (n) is the number of consecutive runs,
-   *  if (mult) is present, the n runs are repeated (mult)
-   *  times.
+   * The entry point. It takes two arguments:
+   * - argument `n` is the number of consecutive runs
+   * - optional argument `mult` specifies that the `n` runs are repeated
+   *   `mult` times.
    */
   def main(args: Array[String]) {
     if (args.length > 0) {
@@ -120,4 +107,3 @@ trait Benchmark {
     }
   }
 }
-
diff --git a/src/library/scala/testing/Show.scala b/src/library/scala/testing/Show.scala
index f5670ac11a..b0d094e466 100644
--- a/src/library/scala/testing/Show.scala
+++ b/src/library/scala/testing/Show.scala
@@ -10,20 +10,19 @@
 
 package scala.testing
 
-/** Classes inheriting trait `Show` can test their member methods
- *  using the notattion <code>meth(arg<sub>1</sub>, ..., arg<sub>n</sub>)</code>,
- *  where `meth` is the name of the method and
- *  <code>arg<sub>1</sub>,...,arg<sub>n</sub></code> are the arguments.
+/** Classes inheriting trait `Show` can test their member methods using the
+ *  notattion `meth(arg,,1,,, ..., arg,,n,,)`, where `meth` is the name of
+ *  the method and `arg,,1,,,...,arg,,n,,` are the arguments.
  *
  *  The only difference to a normal method call is the leading quote
- *  character (`'`). A quoted method call like the one above will produces a
- *  legible diagnostic to be printed on [[scala.Console]].
+ *  character (`'`). A quoted method call like the one above will produces
+ *  a legible diagnostic to be printed on [[scala.Console]].
  *
  *  It is of the form
- *  <pre>
- *    meth(arg<sub>1</sub>, ..., arg<sub>n</sub>)  gives  &lt;result&gt;</pre>
  *
- *  where <code>&lt;result&gt;</code> is the result of evaluating the call.
+ *    `meth(arg,,1,,, ..., arg,,n,,)`  gives  `&lt;result&gt;`
+ *
+ *  where `&lt;result&gt;` is the result of evaluating the call.
  *
  */
 trait Show {
diff --git a/src/library/scala/throws.scala b/src/library/scala/throws.scala
index 1ff8cdc3b8..4621c789ab 100644
--- a/src/library/scala/throws.scala
+++ b/src/library/scala/throws.scala
@@ -6,13 +6,11 @@
 **                          |/                                          **
 \*                                                                      */
 
-
-
 package scala
 
-/** <p>
- *    Annotation for specifying the exceptions thrown by a method.
- *    For example:
+/**
+ * Annotation for specifying the exceptions thrown by a method.
+ * For example:
  * {{{
  * class Reader(fname: String) {
  *   private val in = new BufferedReader(new FileReader(fname))
diff --git a/src/library/scala/unchecked.scala b/src/library/scala/unchecked.scala
index 74cb14e6e3..4f1f3f1957 100644
--- a/src/library/scala/unchecked.scala
+++ b/src/library/scala/unchecked.scala
@@ -29,11 +29,9 @@ package scala
  *                              ^
  *    one warning found
  *  }}}
- *  The above message may be suppressed by substituting the expression
- *  `x` with `(x: @unchecked)`. Then the
- *  modified code will compile silently, but, in any case, a
- *  <a href="MatchError.html"><code>MatchError</code></a>
- *  will be raised at runtime.
+ *  The above message may be suppressed by substituting the expression `x`
+ *  with `(x: @unchecked)`. Then the modified code will compile silently,
+ *  but, in any case, a [[scala.MatchError]] will be raised at runtime.
  *
  *  @since 2.4
  */
diff --git a/src/library/scala/util/automata/BaseBerrySethi.scala b/src/library/scala/util/automata/BaseBerrySethi.scala
index 51e15f0e71..18f36f9496 100644
--- a/src/library/scala/util/automata/BaseBerrySethi.scala
+++ b/src/library/scala/util/automata/BaseBerrySethi.scala
@@ -6,8 +6,6 @@
 **                          |/                                          **
 \*                                                                      */
 
-
-
 package scala.util.automata
 
 import scala.util.regexp.{ Base }
@@ -15,8 +13,9 @@ import scala.collection.{ mutable, immutable }
 
 // todo: replace global variable pos with acc
 
-/** This class turns a regular expression over A into a [[scala.util.automata.NondetWorkAutom]]
-  * over A using the celebrated position automata construction (also called ''Berry-Sethi'' or ''Glushkov'').
+/** This class turns a regular expression over `A` into a
+  * [[scala.util.automata.NondetWordAutom]] over `A` using the celebrated
+  * position automata construction (also called ''Berry-Sethi'' or ''Glushkov'').
   */
 abstract class BaseBerrySethi {
   val lang: Base
@@ -43,7 +42,7 @@ abstract class BaseBerrySethi {
       val (l1, l2) = x.rs span (_.isNullable)
       ((l1 ++ (l2 take 1)) map compFunction).foldLeft(emptySet)(_ ++ _)
     case Star(t)  => compFunction(t)
-    case _        => throw new IllegalArgumentException("unexpected pattern " + r.getClass())
+    case _        => throw new IllegalArgumentException("unexpected pattern " + r.getClass)
   }
 
   /** Computes `first(r)` for the word regexp `r`. */
@@ -89,7 +88,7 @@ abstract class BaseBerrySethi {
         if (p.isNullable) fol ++ first
         else first
       }
-    case _          => throw new IllegalArgumentException("unexpected pattern: " + r.getClass())
+    case _          => throw new IllegalArgumentException("unexpected pattern: " + r.getClass)
   }
 
   /** Returns the "Sethi-length" of a pattern, creating the set of position along the way.
@@ -98,10 +97,10 @@ abstract class BaseBerrySethi {
    */
   protected def traverse(r: RegExp): Unit = r match {
     // (is tree automaton stuff, more than Berry-Sethi)
-    case x: Alt   => x.rs foreach traverse
-    case x: Sequ  => x.rs foreach traverse
-    case x: Meta  => traverse(x.r)
-    case Star(t)  => traverse(t)
-    case _        => throw new IllegalArgumentException("unexp pattern " + r.getClass())
+    case x: Alt  => x.rs foreach traverse
+    case x: Sequ => x.rs foreach traverse
+    case x: Meta => traverse(x.r)
+    case Star(t) => traverse(t)
+    case _       => throw new IllegalArgumentException("unexp pattern " + r.getClass)
   }
 }
diff --git a/src/library/scala/util/control/Breaks.scala b/src/library/scala/util/control/Breaks.scala
index 80df8cc0bd..9b1abefe00 100644
--- a/src/library/scala/util/control/Breaks.scala
+++ b/src/library/scala/util/control/Breaks.scala
@@ -6,31 +6,28 @@
 **                          |/                                          **
 \*                                                                      */
 
-
-
 package scala.util.control
 
 /** A class that can be instantiated for the break control abstraction.
  *  Example usage:
- *
- *  <pre>
+ *  {{{
  *  val mybreaks = new Breaks
- *  import</b> mybreaks.{break, breakable}
+ *  import mybreaks.{break, breakable}
  *
  *  breakable {
- *    <b>for</b> (...) {
- *      <b>if</b> (...) break
+ *    for (...) {
+ *      if (...) break
  *    }
- *  }</pre>
- *
+ *  }
+ *  }}}
  *  Calls to break from one instantiation of `Breaks` will never
- *  target breakable objects of some other instantion.
+ *  target breakable objects of some other instantiation.
  */
 class Breaks {
 
   private val breakException = new BreakControl
 
-  /** A block from which one can exit with a `break`'. */
+  /** A block from which one can exit with a `break`. */
   def breakable(op: => Unit) {
     try {
       op
@@ -54,26 +51,25 @@ class Breaks {
     }
   }
 
-  /* Break from dynamically closest enclosing breakable block.
+  /** Break from dynamically closest enclosing breakable block.
    *
-   * @note This might be different than the statically closest enclosing block!
+   *  @note This might be different than the statically closest enclosing block!
    */
   def break() { throw breakException }
 }
 
 /** An object that can be used for the break control abstraction.
- *  Example usage:<pre>
- *
- *  <b>import</b> Breaks.{break, breakable}
+ *  Example usage:
+ *  {{{
+ *  import Breaks.{break, breakable}
  *
  *  breakable {
- *    <b>for</b> (...) {
- *      <b>if</b> (...) break
+ *    for (...) {
+ *      if (...) break
  *    }
- *  }</pre>
- *
+ *  }
+ *  }}}
  */
 object Breaks extends Breaks
 
 private class BreakControl extends ControlThrowable
-
diff --git a/src/library/scala/util/control/ControlThrowable.scala b/src/library/scala/util/control/ControlThrowable.scala
index 4d1116ba6f..8cbe3064ef 100644
--- a/src/library/scala/util/control/ControlThrowable.scala
+++ b/src/library/scala/util/control/ControlThrowable.scala
@@ -6,32 +6,28 @@
 **                          |/                                          **
 \*                                                                      */
 
-
 package scala.util.control
 
-/**
- * A marker trait indicating that the `Throwable` it is mixed
- * into is intended for flow control.
- *
- * Note that `Throwable` subclasses which extend this trait
- * may extend any other `Throwable` subclass (eg.
- * `RuntimeException`) and are not required to extend
- * `Throwable` directly.
+/** A marker trait indicating that the `Throwable` it is mixed into is
+ *  intended for flow control.
  *
- * Instances of `Throwable` subclasses marked in this way should
- * not normally be caught. Where catch-all behaviour is required
- * `ControlThrowable`s should be propagated, for example:
+ *  Note that `Throwable` subclasses which extend this trait may extend any
+ *  other `Throwable` subclass (eg. `RuntimeException`) and are not required
+ *  to extend `Throwable` directly.
  *
- * <pre>
+ *  Instances of `Throwable` subclasses marked in this way should not normally
+ *  be caught. Where catch-all behaviour is required `ControlThrowable`
+ *  should be propagated, for example:
+ *  {{{
  *  import scala.util.control.ControlThrowable
  *
  *  try {
  *    // Body might throw arbitrarily
- * } catch {
- *   case ce : ControlThrowable => throw ce // propagate
- *   case t : Exception => log(t)           // log and suppress
- * </pre>
+ *  } catch {
+ *    case ce : ControlThrowable => throw ce // propagate
+ *    case t : Exception => log(t)           // log and suppress
+ *  }}}
  *
- * @author Miles Sabin
+ *  @author Miles Sabin
  */
 trait ControlThrowable extends Throwable with NoStackTrace
diff --git a/src/library/scala/util/control/Exception.scala b/src/library/scala/util/control/Exception.scala
index ad90b222c2..c8470d2504 100644
--- a/src/library/scala/util/control/Exception.scala
+++ b/src/library/scala/util/control/Exception.scala
@@ -1,3 +1,11 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2011, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
 package scala.util.control
 
 import collection.immutable.List
@@ -5,17 +13,14 @@ import java.lang.reflect.InvocationTargetException
 
 /** Classes representing the components of exception handling.
  *  Each class is independently composable.  Some example usages:
+ *  {{{
+ *  import scala.util.control.Exception._
+ *  import java.net._
  *
- *
- *
- *  <pre>
- *  <b>import</b> scala.util.control.Exception._
- *  <b>import</b> java.net._
- *
- *  <b>val</b> s = "http://www.scala-lang.org/"
- *  <b>val</b> x1 = catching(classOf[MalformedURLException]) opt new URL(s)
- *  <b>val</b> x2 = catching(classOf[MalformedURLException], classOf[NullPointerException]) either new URL(s)
- *  </pre>
+ *  val s = "http://www.scala-lang.org/"
+ *  val x1 = catching(classOf[MalformedURLException]) opt new URL(s)
+ *  val x2 = catching(classOf[MalformedURLException], classOf[NullPointerException]) either new URL(s)
+ *  }}}
  *
  *  @author Paul Phillips
  */
@@ -31,6 +36,7 @@ object Exception {
     def isDefinedAt(x: Throwable) = downcast(x) exists isDef
     def apply(x: Throwable): T = f(downcast(x).get)
   }
+
   def mkThrowableCatcher[T](isDef: Throwable => Boolean, f: Throwable => T) = mkCatcher(isDef, f)
 
   implicit def throwableSubtypeToCatcher[Ex <: Throwable: ClassManifest, T](pf: PartialFunction[Ex, T]) =
@@ -62,7 +68,7 @@ object Exception {
     protected val name = "Finally"
 
     def and(other: => Unit): Finally = new Finally({ body ; other })
-    def invoke(): Unit = { body }
+    def invoke() { body }
   }
 
   /** A container class for catch/finally logic.
@@ -92,14 +98,14 @@ object Exception {
       }
       finally fin map (_.invoke())
 
-    /* Create an empty Try container with this Catch and the supplied Finally */
+    /* Create an empty Try container with this Catch and the supplied `Finally`. */
     def andFinally(body: => Unit): Catch[T] = fin match {
       case None     => new Catch(pf, Some(new Finally(body)), rethrow)
       case Some(f)  => new Catch(pf, Some(f and body), rethrow)
     }
 
     /** Apply this catch logic to the supplied body, mapping the result
-     *  into Option[T] - None if any exception was caught, Some(T) otherwise.
+     *  into `Option[T]` - `None` if any exception was caught, `Some(T)` otherwise.
      */
     def opt[U >: T](body: => U): Option[U] = toOption(Some(body))
 
@@ -109,8 +115,8 @@ object Exception {
      */
     def either[U >: T](body: => U): Either[Throwable, U] = toEither(Right(body))
 
-    /** Create a new Catch with the same isDefinedAt logic as this one,
-      * but with the supplied apply method replacing the current one. */
+    /** Create a `Catch` object with the same `isDefinedAt` logic as this one,
+      * but with the supplied `apply` method replacing the current one. */
     def withApply[U](f: Throwable => U): Catch[U] = {
       val pf2 = new Catcher[U] {
         def isDefinedAt(x: Throwable) = pf isDefinedAt x
@@ -130,21 +136,21 @@ object Exception {
     def apply(): T                    = catcher(body)
     def apply[U >: T](other: => U): U = catcher(other)
 
-    /** As apply, but map caught exceptions to None and success to Some(T) */
+    /** As apply, but map caught exceptions to `None` and success to `Some(T)`. */
     def opt(): Option[T]                      = catcher opt body
     def opt[U >: T](other: => U): Option[U]   = catcher opt other
 
-    /** As apply, but map caught exceptions to Left(ex) and success to Right(x) */
+    /** As apply, but map caught exceptions to `Left(ex)` and success to Right(x) */
     def either(): Either[Throwable, T]                    = catcher either body
     def either[U >: T](other: => U): Either[Throwable, U] = catcher either other
 
-    /** Create a new Try with the supplied body replacing the current body */
+    /** Create a `Try` object with the supplied body replacing the current body. */
     def tryInstead[U >: T](other: => U) = new Try(other, catcher)
 
-    /** Create a new Try with the supplied logic appended to the existing Catch logic. */
+    /** Create a `Try` object with the supplied logic appended to the existing Catch logic. */
     def or[U >: T](pf: Catcher[U]) = new Try(body, catcher or pf)
 
-    /** Create a new Try with the supplied code appended to the existing Finally. */
+    /** Create a `Try`object with the supplied code appended to the existing `Finally`. */
     def andFinally(fin: => Unit) = new Try(body, catcher andFinally fin)
 
     override def toString() = List("Try(<body>)", catcher.toString) mkString " "
@@ -153,49 +159,51 @@ object Exception {
   final val nothingCatcher: Catcher[Nothing]  = mkThrowableCatcher(_ => false, throw _)
   final def allCatcher[T]: Catcher[T]         = mkThrowableCatcher(_ => true, throw _)
 
-  /** The empty Catch object. */
+  /** The empty `Catch` object. */
   final val noCatch: Catch[Nothing] = new Catch(nothingCatcher) withDesc "<nothing>"
 
-  /** A Catch object which catches everything. */
+  /** A `Catch` object which catches everything. */
   final def allCatch[T]: Catch[T] = new Catch(allCatcher[T]) withDesc "<everything>"
 
-  /** Creates a Catch object which will catch any of the supplied exceptions.
-   *  Since the returned Catch object has no specific logic defined and will simply
-   *  rethrow the exceptions it catches, you will typically want to call "opt" or
-   *  "either" on the return value, or assign custom logic by calling "withApply".
+  /** Creates a `Catch` object which will catch any of the supplied exceptions.
+   *  Since the returned `Catch` object has no specific logic defined and will simply
+   *  rethrow the exceptions it catches, you will typically want to call `opt` or
+   *  `either` on the return value, or assign custom logic by calling "withApply".
    *
-   *  Note that Catch objects automatically rethrow ControlExceptions and others
+   *  Note that `Catch` objects automatically rethrow `ControlExceptions` and others
    *  which should only be caught in exceptional circumstances.  If you really want
-   *  to catch exactly what you specify, use "catchingPromiscuously" instead.
+   *  to catch exactly what you specify, use `catchingPromiscuously` instead.
    */
   def catching[T](exceptions: Class[_]*): Catch[T] =
     new Catch(pfFromExceptions(exceptions : _*)) withDesc (exceptions map (_.getName) mkString ", ")
 
   def catching[T](c: Catcher[T]): Catch[T] = new Catch(c)
 
-  /** Creates a Catch object which will catch any of the supplied exceptions.
+  /** Creates a `Catch` object which will catch any of the supplied exceptions.
    *  Unlike "catching" which filters out those in shouldRethrow, this one will
-   *  catch whatever you ask of it: ControlThrowable, InterruptedException,
-   *  OutOfMemoryError, you name it.
+   *  catch whatever you ask of it: `ControlThrowable`, `InterruptedException`,
+   *  `OutOfMemoryError`, you name it.
    */
   def catchingPromiscuously[T](exceptions: Class[_]*): Catch[T] = catchingPromiscuously(pfFromExceptions(exceptions : _*))
   def catchingPromiscuously[T](c: Catcher[T]): Catch[T]         = new Catch(c, None, _ => false)
 
-  /** Creates a Catch object which catches and ignores any of the supplied exceptions. */
+  /** Creates a `Catch` object which catches and ignores any of the supplied exceptions. */
   def ignoring(exceptions: Class[_]*): Catch[Unit] =
     catching(exceptions: _*) withApply (_ => ())
 
-  /** Creates a Catch object which maps all the supplied exceptions to 'None'. */
+  /** Creates a `Catch` object which maps all the supplied exceptions to `None`. */
   def failing[T](exceptions: Class[_]*): Catch[Option[T]] =
     catching(exceptions: _*) withApply (_ => None)
 
-  /** Creates a Catch object which maps all the supplied exceptions to the given value. */
+  /** Creates a `Catch` object which maps all the supplied exceptions to the given value. */
   def failAsValue[T](exceptions: Class[_]*)(value: => T): Catch[T] =
     catching(exceptions: _*) withApply (_ => value)
 
-  /** Returns a partially constructed Catch object, which you must give
-    * an exception handler function as an argument to "by".  Example:
-    * handling(ex1, ex2) by (_.printStackTrace)
+  /** Returns a partially constructed `Catch` object, which you must give
+    * an exception handler function as an argument to `by`.  Example:
+    * {{{
+    *   handling(ex1, ex2) by (_.printStackTrace)
+    * }}}
     */
   class By[T,R](f: T => R) {
     def by(x: T): R = f(x)
@@ -205,10 +213,10 @@ object Exception {
     new By[Throwable => T, Catch[T]](fun _)
   }
 
-  /** Returns a Catch object with no catch logic and the argument as Finally. */
+  /** Returns a `Catch` object with no catch logic and the argument as `Finally`. */
   def ultimately[T](body: => Unit): Catch[T] = noCatch andFinally body
 
-  /** Creates a Catch object which unwraps any of the supplied exceptions. */
+  /** Creates a `Catch` object which unwraps any of the supplied exceptions. */
   def unwrapping[T](exceptions: Class[_]*): Catch[T] = {
     def unwrap(x: Throwable): Throwable =
       if (wouldMatch(x, exceptions) && x.getCause != null) unwrap(x.getCause)
diff --git a/src/library/scala/util/control/TailCalls.scala b/src/library/scala/util/control/TailCalls.scala
index 59e9618028..ca5442046c 100644
--- a/src/library/scala/util/control/TailCalls.scala
+++ b/src/library/scala/util/control/TailCalls.scala
@@ -1,10 +1,18 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2011, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
 package scala.util.control
 
 /** Methods exported by this object implement tail calls via trampolining.
- *  Tail calling methods have to return their result using `done` or call the next
- *  method using `tailcall`. Both return a `TailRec` object. The result of evaluating
- *  a tailcalling function can be retrieved from a `Tailrec` value using method result`.
- *  Here's a usage example:
+ *  Tail calling methods have to return their result using `done` or call the
+ *  next method using `tailcall`. Both return a `TailRec` object. The result
+ *  of evaluating a tailcalling function can be retrieved from a `Tailrec`
+ *  value using method `result`. Here's a usage example:
  *  {{{
  *  import scala.util.control.TailCalls._
  *
@@ -19,10 +27,10 @@ package scala.util.control
  */
 object TailCalls {
 
-  /** This class represents a tailcalling computation.
+  /** This class represents a tailcalling computation
    */
   abstract class TailRec[+A] {
-    /** Returns the result of the tailcalling computation
+    /** Returns the result of the tailcalling computation.
      */
     def result: A = {
       def loop(body: TailRec[A]): A = body match {
@@ -36,7 +44,8 @@ object TailCalls {
   /** Internal class representing a tailcall */
   protected case class Call[A](rest: () => TailRec[A]) extends TailRec[A]
 
-  /** Internal class representing the final result return from a tailcalling computation */
+  /** Internal class representing the final result returned from a tailcalling
+    * computation */
   protected case class Done[A](override val result: A) extends TailRec[A]
 
   /** Performs a tailcall
@@ -47,10 +56,9 @@ object TailCalls {
 
   /** Used to return final result from tailcalling computation
    *  @param  `result` the result value
-   *  @return a `TailRec` object representing a computation which immediately returns `result`
+   *  @return a `TailRec` object representing a computation which immediately
+   *          returns `result`
    */
   def done[A](result: A): TailRec[A] = new Done(result)
 
 }
-
-
diff --git a/src/library/scala/util/parsing/combinator/PackratParsers.scala b/src/library/scala/util/parsing/combinator/PackratParsers.scala
index 3f09ae506d..ea856efc3a 100644
--- a/src/library/scala/util/parsing/combinator/PackratParsers.scala
+++ b/src/library/scala/util/parsing/combinator/PackratParsers.scala
@@ -6,7 +6,6 @@
 **                          |/                                          **
 \*                                                                      */
 
-
 package scala.util.parsing.combinator
 
 import scala.util.parsing.combinator._
@@ -14,29 +13,34 @@ import scala.util.parsing.input.{ Reader, Position }
 import scala.collection.mutable
 
 /**
- *  `PackratParsers` is a component that extends the parser combinators provided by
- *  [[scala.util.parsing.combinator.Parsers]] with a memoization facility (``Packrat Parsing'').
+ *  `PackratParsers` is a component that extends the parser combinators
+ *  provided by [[scala.util.parsing.combinator.Parsers]] with a memoization
+ *  facility (''Packrat Parsing'').
  *
- *  Packrat Parsing is a technique for implementing backtracking, recursive-descent parsers, with the
- *  advantage that it guarantees unlimited lookahead and a linear parse time. Using this technique,
+ *  Packrat Parsing is a technique for implementing backtracking,
+ *  recursive-descent parsers, with the advantage that it guarantees
+ *  unlimited lookahead and a linear parse time. Using this technique,
  *  left recursive grammars can also be accepted.
  *
  *  Using `PackratParsers` is very similar to using `Parsers`:
- *   - any class/trait that extends `Parsers` (directly or through a subclass) can mix in `PackratParsers`.
- *     Example: `object MyGrammar extends StandardTokenParsers with PackratParsers `
- *   - each grammar production previously declared as a `def` without formal parameters
- *     becomes a `lazy val`, and its type is changed from `Parser[Elem]` to `PackratParser[Elem]`.
- *     So, for example, `def production: Parser[Int] = {...}`
- *     becomes `lazy val production: PackratParser[Int] = {...}`
- *   - Important: using `PackratParser`s is not an ``all or nothing'' decision.
+ *   - any class/trait that extends `Parsers` (directly or through a subclass)
+ *     can mix in `PackratParsers`.
+ *     Example: `'''object''' MyGrammar '''extends''' StandardTokenParsers '''with''' PackratParsers`
+ *   - each grammar production previously declared as a `def` without formal
+ *     parameters becomes a `lazy val`, and its type is changed from
+ *     `Parser[Elem]` to `PackratParser[Elem]`.
+ *     So, for example, `'''def''' production: Parser[Int] = {...}`
+ *     becomes `'''lazy val''' production: PackratParser[Int] = {...}`
+ *   - Important: using `PackratParser`s is not an ''all or nothing'' decision.
  *     They can be free mixed with regular `Parser`s in a single grammar.
  *
  *  Cached parse results are attached to the ''input'', not the grammar.
  *  Therefore, `PackratsParser`s require a `PackratReader` as input, which
- *  adds memoization to an underlying `Reader`. Programmers can create `PackratReader`
- *  objects either manually, as in `production(new PackratReader(new lexical.Scanner("input")))`,
- *  but the common way should be to rely on the combinator `phrase` to wrap a given
- *  input with a `PackratReader` if the input is not one itself.
+ *  adds memoization to an underlying `Reader`. Programmers can create
+ *  `PackratReader` objects either manually, as in
+ *  `production('''new''' PackratReader('''new''' lexical.Scanner("input")))`,
+ *  but the common way should be to rely on the combinator `phrase` to wrap
+ *  a given input with a `PackratReader` if the input is not one itself.
  *
  * @see Bryan Ford: "Packrat Parsing: Simple, Powerful, Lazy, Linear Time." ICFP'02
  * @see Alessandro Warth, James R. Douglass, Todd Millstein: "Packrat Parsers Can Support Left Recursion." PEPM'08
@@ -54,7 +58,7 @@ trait PackratParsers extends Parsers {
    * A specialized `Reader` class that wraps an underlying `Reader`
    * and provides memoization of parse results.
    */
-  class PackratReader[+T](underlying: Reader[T]) extends Reader[T]  { outer =>
+  class PackratReader[+T](underlying: Reader[T]) extends Reader[T] { outer =>
 
     /*
      * caching of intermediate parse results and information about recursion
@@ -91,7 +95,6 @@ trait PackratParsers extends Parsers {
     def atEnd: Boolean = underlying.atEnd
   }
 
-
   /**
    *  A parser generator delimiting whole phrases (i.e. programs).
    *
@@ -108,7 +111,6 @@ trait PackratParsers extends Parsers {
     }
   }
 
-
   private def getPosFromResult(r: ParseResult[_]): Position = r.next.pos
 
   // auxiliary data structures
@@ -136,14 +138,14 @@ trait PackratParsers extends Parsers {
   /**
    * Implicitly convert a parser to a packrat parser.
    * The conversion is triggered by giving the appropriate target type:
-   * val myParser: PackratParser[MyResult] = aParser
-   */
+   * {{{
+   *   val myParser: PackratParser[MyResult] = aParser
+   * }}} */
   implicit def parser2packrat[T](p: => super.Parser[T]): PackratParser[T] = {
     lazy val q = p
     memo(super.Parser {in => q(in)})
   }
 
-
   /*
    * An unspecified function that is called when a packrat reader is applied.
    * It verifies whether we are in the process of growing a parse or not.
diff --git a/src/library/scala/util/parsing/combinator/Parsers.scala b/src/library/scala/util/parsing/combinator/Parsers.scala
index e9155afc55..bb73b28ea8 100644
--- a/src/library/scala/util/parsing/combinator/Parsers.scala
+++ b/src/library/scala/util/parsing/combinator/Parsers.scala
@@ -23,7 +23,8 @@ import annotation.migration
  *
  *  There are two aspects to the result of a parser:
  *  1. success or failure
- *  2. the result.
+ *  1. the result.
+ *
  *  A `Parser[T]` provides both kinds of information.
  *
  *  The term ''parser combinator'' refers to the fact that these parsers
@@ -44,18 +45,20 @@ import annotation.migration
  * @author Adriaan Moors
  */
 trait Parsers {
-  /** 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''.
+  /** 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, i.e. the type of input the parsers in this component
-   *  expect. */
+  /** 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 `T` which consists of some result (and the rest of
-   *  the input). */
+  /** 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.
      *
@@ -91,7 +94,7 @@ trait Parsers {
     val successful: Boolean
   }
 
-  /** The success case of ParseResult: contains the result and the remaining input.
+  /** The success case of `ParseResult`: contains the result and the remaining input.
    *
    *  @param result The parser's output
    *  @param next   The parser's remaining input
@@ -131,7 +134,7 @@ trait Parsers {
 
     def get: Nothing = sys.error("No result when parsing failed")
   }
-  /** An extractor so NoSuccess(msg, next) can be used in matches. */
+  /** An extractor so `NoSuccess(msg, next)` can be used in matches. */
   object NoSuccess {
     def unapply[T](x: ParseResult[T]) = x match {
       case Failure(msg, next)   => Some(msg, next)
@@ -140,7 +143,7 @@ trait Parsers {
     }
   }
 
-  /** The failure case of ParseResult: contains an error-message and the remaining input.
+  /** The failure case of `ParseResult`: contains an error-message and the remaining input.
    *  Parsing will back-track when a failure occurs.
    *
    *  @param msg    An error message string describing the failure.
@@ -156,8 +159,9 @@ trait Parsers {
     }}
   }
 
-  /** The fatal failure case of ParseResult: contains an error-message and the remaining input.
-   *  No back-tracking is done when a parser returns an `Error`
+  /** The fatal failure case of ParseResult: contains an error-message and
+   *  the remaining input.
+   *  No back-tracking is done when a parser returns an `Error`.
    *
    *  @param msg    An error message string describing the error.
    *  @param next   The parser's unconsumed input at the point where the error occurred.
@@ -168,7 +172,6 @@ trait Parsers {
     def append[U >: Nothing](a: => ParseResult[U]): ParseResult[U] = this
   }
 
-
   def Parser[T](f: Input => ParseResult[T]): Parser[T]
     = new Parser[T]{ def apply(in: Input) = f(in) }
 
@@ -199,7 +202,6 @@ trait Parsers {
       Parser{ in => this(in) append p(in)}
     }
 
-
     // the operator formerly known as +++, ++, &, but now, behold the venerable ~
     // it's short, light (looks like whitespace), has few overloaded meaning (thanks to the recent change from ~ to unary_~)
     // and we love it! (or do we like `,` better?)
@@ -313,7 +315,6 @@ trait Parsers {
      */
     def ^^ [U](f: T => U): Parser[U] = map(f).named(toString+"^^")
 
-
     /** A parser combinator that changes a successful result into the specified value.
      *
      *  `p ^^^ v` succeeds if `p` succeeds; discards its result, and returns `v` instead.
@@ -355,7 +356,6 @@ trait Parsers {
      */
     def ^? [U](f: PartialFunction[T, U]): Parser[U] = ^?(f, r => "Constructor function not defined at "+r)
 
-
     /** A parser combinator that parameterizes a subsequent parser with the result of this one.
      *
      *  Use this combinator when a parser depends on the result of a previous parser. `p` should be
@@ -376,15 +376,15 @@ trait Parsers {
     /** Returns `into(fq)`. */
     def >>[U](fq: T => Parser[U])=into(fq)
 
-
     /** Returns a parser that repeatedly parses what this parser parses.
      *
      *  @return rep(this)
      */
     def * = rep(this)
 
-    /** Returns a parser that repeatedly parses what this parser parses, interleaved with the `sep` parser.
-     *  The `sep` parser specifies how the results parsed by this parser should be combined.
+    /** Returns a parser that repeatedly parses what this parser parses,
+     *  interleaved with the `sep` parser. The `sep` parser specifies how
+     *  the results parsed by this parser should be combined.
      *
      *  @return chainl1(this, sep)
      */
@@ -405,8 +405,9 @@ trait Parsers {
     def ? = opt(this)
   }
 
-  /** Wrap a parser so that its failures become errors (the `|` combinator will give up as soon as
-   *  it encounters an error, on failure it simply tries the next alternative).
+  /** Wrap a parser so that its failures become errors (the `|` combinator
+   *  will give up as soon as it encounters an error, on failure it simply
+   *  tries the next alternative).
    */
   def commit[T](p: => Parser[T]) = Parser{ in =>
     p(in) match{
@@ -420,7 +421,6 @@ trait Parsers {
   case class EFCons(hd: Elem => ElemFun, tl: ElemFun) extends ElemFun
   case class EFNil(res: Boolean) extends ElemFun*/
 
-
   /** A parser matching input elements that satisfy a given predicate.
    *
    *  `elem(kind, p)` succeeds if the input starts with an element `e` for which `p(e)` is true.
@@ -463,8 +463,8 @@ trait Parsers {
 
   /** The parser that matches an element in the domain of the partial function `f`.
    *
-   *  If `f` is defined on the first element in the input, `f` is applied to it to produce
-   *  this parser's result.
+   *  If `f` is defined on the first element in the input, `f` is applied
+   *  to it to produce this parser's result.
    *
    *  Example: The parser `accept("name", {case Identifier(n) => Name(n)})`
    *          accepts an `Identifier(n)` and returns a `Name(n)`
@@ -476,7 +476,6 @@ trait Parsers {
    */
   def accept[U](expected: String, f: PartialFunction[Elem, U]): Parser[U] = acceptMatch(expected, f)
 
-
   def acceptIf(p: Elem => Boolean)(err: Elem => String): Parser[Elem] = Parser { in =>
     if (p(in.first)) Success(in.first, in.rest)
     else Failure(err(in.first), in)
@@ -487,7 +486,8 @@ trait Parsers {
     else Failure(expected+" expected", in)
   }
 
-  def acceptSeq[ES <% Iterable[Elem]](es: ES): Parser[List[Elem]] = es.foldRight[Parser[List[Elem]]](success(Nil)){(x, pxs) => accept(x) ~ pxs ^^ mkList}
+  def acceptSeq[ES <% Iterable[Elem]](es: ES): Parser[List[Elem]] =
+    es.foldRight[Parser[List[Elem]]](success(Nil)){(x, pxs) => accept(x) ~ pxs ^^ mkList}
 
   /** A parser that always fails.
    *
@@ -503,7 +503,6 @@ trait Parsers {
    */
   def err(msg: String) = Parser{ in => Error(msg, in) }
 
-
   /** A parser that always succeeds.
    *
    * @param v The result for the parser
@@ -520,8 +519,8 @@ trait Parsers {
 
   /** A parser generator for repetitions.
    *
-   *  `rep(p)` repeatedly uses `p` to parse the input until `p` fails (the result is a List
-   *  of the consecutive results of `p`).
+   *  `rep(p)` repeatedly uses `p` to parse the input until `p` fails
+   *  (the result is a List of the consecutive results of `p`).
    *
    * @param p a `Parser` that is to be applied successively to the input
    * @return A parser that returns a list of results produced by repeatedly applying `p` to the input.
@@ -604,8 +603,8 @@ trait Parsers {
       @tailrec def applyp(in0: Input): ParseResult[List[T]] =
         if (elems.length == num) Success(elems.toList, in0)
         else p0(in0) match {
-          case Success(x, rest)   => elems += x ; applyp(rest)
-          case ns: NoSuccess      => return ns
+          case Success(x, rest) => elems += x ; applyp(rest)
+          case ns: NoSuccess    => return ns
         }
 
       applyp(in)
@@ -613,8 +612,8 @@ trait Parsers {
 
   /** A parser generator for non-empty repetitions.
    *
-   *  `rep1sep(p, q)` repeatedly applies `p` interleaved with `q` to parse the input, until `p` fails.
-   *  The parser `p` must succeed at least once.
+   *  `rep1sep(p, q)` repeatedly applies `p` interleaved with `q` to parse the
+   *  input, until `p` fails. The parser `p` must succeed at least once.
    *
    * @param p a `Parser` that is to be applied successively to the input
    * @param q a `Parser` that parses the elements that separate the elements parsed by `p`
@@ -626,8 +625,9 @@ trait Parsers {
   def rep1sep[T](p : => Parser[T], q : => Parser[Any]): Parser[List[T]] =
     p ~ rep(q ~> p) ^^ {case x~y => x::y}
 
-  /** A parser generator that, roughly, generalises the rep1sep generator so that `q`, which parses the separator,
-   *  produces a left-associative function that combines the elements it separates.
+  /** A parser generator that, roughly, generalises the rep1sep generator so
+   *  that `q`, which parses the separator, produces a left-associative
+   *  function that combines the elements it separates.
    *
    *  ''From: J. Fokker. Functional parsers. In J. Jeuring and E. Meijer, editors, Advanced Functional Programming,
    *  volume 925 of Lecture Notes in Computer Science, pages 1--23. Springer, 1995.''
@@ -639,22 +639,25 @@ trait Parsers {
   def chainl1[T](p: => Parser[T], q: => Parser[(T, T) => T]): Parser[T]
     = chainl1(p, p, q)
 
-  /** A parser generator that, roughly, generalises the `rep1sep` generator so that `q`, which parses the separator,
-   * produces a left-associative function that combines the elements it separates.
+  /** A parser generator that, roughly, generalises the `rep1sep` generator
+   *  so that `q`, which parses the separator, produces a left-associative
+   *  function that combines the elements it separates.
    *
    * @param first a parser that parses the first element
    * @param p a parser that parses the subsequent elements
-   * @param q a parser that parses the token(s) separating the elements, yielding a left-associative function that
-   *          combines two elements into one
+   * @param q a parser that parses the token(s) separating the elements,
+   *          yielding a left-associative function that combines two elements
+   *          into one
    */
   def chainl1[T, U](first: => Parser[T], p: => Parser[U], q: => Parser[(T, U) => T]): Parser[T]
     = first ~ rep(q ~ p) ^^ {
         case x ~ xs => xs.foldLeft(x){(_, _) match {case (a, f ~ b) => f(a, b)}}
       }
 
-  /** A parser generator that generalises the `rep1sep` generator so that `q`, which parses the separator,
-   * produces a right-associative function that combines the elements it separates. Additionally,
-   * The right-most (last) element and the left-most combining function have to be supplied.
+  /** A parser generator that generalises the `rep1sep` generator so that `q`,
+   *  which parses the separator, produces a right-associative function that
+   *  combines the elements it separates. Additionally, the right-most (last)
+   *  element and the left-most combining function have to be supplied.
    *
    * rep1sep(p: Parser[T], q) corresponds to chainr1(p, q ^^ cons, cons, Nil) (where val cons = (x: T, y: List[T]) => x :: y)
    *
@@ -681,7 +684,8 @@ trait Parsers {
   def opt[T](p: => Parser[T]): Parser[Option[T]] =
     p ^^ (x => Some(x)) | success(None)
 
-  /** Wrap a parser so that its failures and errors become success and vice versa -- it never consumes any input.
+  /** Wrap a parser so that its failures and errors become success and
+   *  vice versa -- it never consumes any input.
    */
   def not[T](p: => Parser[T]): Parser[Unit] = Parser { in =>
     p(in) match {
@@ -690,11 +694,13 @@ trait Parsers {
     }
   }
 
-  /** A parser generator for guard expressions. The resulting parser will fail or succeed
-   * just like the one given as parameter but it will not consume any input.
+  /** A parser generator for guard expressions. The resulting parser will
+   *  fail or succeed just like the one given as parameter but it will not
+   *  consume any input.
    *
    * @param p a `Parser` that is to be applied to the input
-   * @return A parser that returns success if and only if `p` succeeds but never consumes any input
+   * @return A parser that returns success if and only if `p` succeeds but
+   *         never consumes any input
    */
   def guard[T](p: => Parser[T]): Parser[T] = Parser { in =>
     p(in) match{
@@ -703,12 +709,13 @@ trait Parsers {
     }
   }
 
-
-  /** `positioned` decorates a parser's result with the start position of the input it consumed.
+  /** `positioned` decorates a parser's result with the start position of the
+   *  input it consumed.
    *
    * @param p a `Parser` whose result conforms to `Positional`.
-   * @return A parser that has the same behaviour as `p`, but which marks its result with the
-   *         start position of the input it consumed, if it didn't already have a position.
+   * @return A parser that has the same behaviour as `p`, but which marks its
+   *         result with the start position of the input it consumed,
+   *         if it didn't already have a position.
    */
   def positioned[T <: Positional](p: => Parser[T]): Parser[T] = Parser { in =>
     p(in) match {
diff --git a/src/library/scala/util/parsing/combinator/lexical/StdLexical.scala b/src/library/scala/util/parsing/combinator/lexical/StdLexical.scala
index 6c8bad01c1..3ac5c07dc4 100644
--- a/src/library/scala/util/parsing/combinator/lexical/StdLexical.scala
+++ b/src/library/scala/util/parsing/combinator/lexical/StdLexical.scala
@@ -6,8 +6,6 @@
 **                          |/                                          **
 \*                                                                      */
 
-
-
 package scala.util.parsing
 package combinator
 package lexical
@@ -16,16 +14,19 @@ import token._
 import input.CharArrayReader.EofCh
 import scala.collection.mutable
 
-/** This component provides a standard lexical parser for a simple, Scala-like language.
- *  It parses keywords and identifiers, numeric literals (integers), strings, and delimiters.
+/** This component provides a standard lexical parser for a simple,
+ *  [[http://scala-lang.org Scala]]-like language. It parses keywords and
+ *  identifiers, numeric literals (integers), strings, and delimiters.
  *
- *  To distinguish between identifiers and keywords, it uses a set of reserved identifiers:
- *  every string contained in `reserved` is returned as a keyword token.
- *  (Note that "=>" is hard-coded as a keyword.)
- *  Additionally, the kinds of delimiters can be specified by the `delimiters` set.
+ *  To distinguish between identifiers and keywords, it uses a set of
+ *  reserved identifiers:  every string contained in `reserved` is returned
+ *  as a keyword token. (Note that `=>` is hard-coded as a keyword.)
+ *  Additionally, the kinds of delimiters can be specified by the
+ *  `delimiters` set.
  *
- *  Usually this component is used to break character-based input into bigger tokens,
- *  which are then passed to a token-parser {@see TokenParsers}.
+ *  Usually this component is used to break character-based input into
+ *  bigger tokens, which are then passed to a token-parser {@see
+ *  [[scala.util.parsing.combinator.syntactical.TokenParsers]]}.
  *
  * @author Martin Odersky
  * @author Iulian Dragos
diff --git a/src/library/scala/util/parsing/combinator/testing/Tester.scala b/src/library/scala/util/parsing/combinator/testing/Tester.scala
index ca1df2f6d4..4607dc8843 100644
--- a/src/library/scala/util/parsing/combinator/testing/Tester.scala
+++ b/src/library/scala/util/parsing/combinator/testing/Tester.scala
@@ -6,7 +6,6 @@
 **                          |/                                          **
 \*                                                                      */
 
-
 package scala.util.parsing.combinator.testing
 import scala.util.parsing.combinator._
 
@@ -16,15 +15,13 @@ import scala.util.parsing.combinator.syntactical.TokenParsers
 /** Facilitates testing a given parser on various input strings.
  *
  *  Example use:
- *
- *  <pre>
- *    <b>val</b> syntactic = <b>new</b> MyParsers
- *  </pre>
+ *  {{{
+ *    val syntactic = new MyParsers
+ *  }}}
  *  and
- *  <pre>
- *    <b>val</b> parser = syntactic.term
- *  </pre>
- *
+ *  {{{
+ *    val parser = syntactic.term
+ *  }}}
  *  (If `MyParsers` extends [[scala.util.parsing.combinator.syntactical.TokenParsers]]
  *  with a parser called `term`.)
  *
@@ -36,10 +33,9 @@ abstract class Tester {
   val syntactic: TokenParsers { val lexical: Lexical }
   val parser: syntactic.Parser[Any]
 
-
-  /** Scans a String (using a `syntactic.lexical.Scanner`), parses it
-   *  using `phrase(parser)`, and  prints the input and the
-   *  parsed result to the console.
+  /** Scans a String (using a `syntactic.lexical.Scanner`), parses it using
+   *  `phrase(parser)`, and  prints the input and the parsed result to the
+   *  console.
    */
   def test(in: String) {
     Console.println("\nin : "+in)
diff --git a/src/library/scala/util/parsing/json/JSON.scala b/src/library/scala/util/parsing/json/JSON.scala
index 036964680e..b0926d20e7 100644
--- a/src/library/scala/util/parsing/json/JSON.scala
+++ b/src/library/scala/util/parsing/json/JSON.scala
@@ -6,21 +6,19 @@
 **                          |/                                          **
 \*                                                                      */
 
-
-
 package scala.util.parsing.json
 import scala.util.parsing.combinator._
 import scala.util.parsing.combinator.syntactical._
 import scala.util.parsing.combinator.lexical._
 
 /**
- * This object provides a simple interface to the JSON parser class. The default conversion
- * for numerics is into a double. If you wish to override this behavior at the global level,
- * you can set the globalNumberParser property to your own (String => Any) function. If you only
- * want to override at the per-thread level then you can set the perThreadNumberParser property to your
- * function. For example:
- *
- * <pre>
+ * This object provides a simple interface to the JSON parser class.
+ * The default conversion for numerics is into a double. If you wish to
+ * override this behavior at the global level, you can set the
+ * `globalNumberParser` property to your own `(String => Any)` function.
+ * If you only want to override at the per-thread level then you can set
+ * the `perThreadNumberParser` property to your function. For example:
+ * {{{
  * val myConversionFunc = {input : String => BigDecimal(input)}
  *
  * // Global override
@@ -28,18 +26,18 @@ import scala.util.parsing.combinator.lexical._
  *
  * // Per-thread override
  * JSON.perThreadNumberParser = myConversionFunc
- * </pre>
+ * }}}
  *
- *  @author Derek Chen-Becker <"java"+@+"chen-becker"+"."+"org">
+ * @author Derek Chen-Becker <"java"+@+"chen-becker"+"."+"org">
  */
 object JSON extends Parser {
 
   /**
-   * Parse the given JSON string and return a list of elements. If the
-   * string is a JSON object it will be a list of pairs. If it's a JSON
+   * Parse the given `JSON` string and return a list of elements. If the
+   * string is a `JSON` object it will be a list of pairs. If it's a `JSON`
    * array it will be be a list of individual elements.
    *
-   * @param input the given JSON string.
+   * @param input the given `JSON` string.
    * @return      an optional list of of elements.
    */
   @deprecated("Use parseFull or parseRaw as needed.", "2.8.0")
@@ -49,7 +47,7 @@ object JSON extends Parser {
   })
 
   /**
-   * This method converts "raw" results back into the original, deprecated
+   * This method converts ''raw'' results back into the original, deprecated
    * form.
    */
   private def unRaw (in : Any) : Any = in match {
@@ -59,12 +57,12 @@ object JSON extends Parser {
   }
 
   /**
-   * Parse the given JSON string and return a list of elements. If the
-   * string is a JSON object it will be a JSONObject. If it's a JSON
-   * array it will be be a JSONArray.
+   * Parse the given `JSON` string and return a list of elements. If the
+   * string is a `JSON` object it will be a `JSONObject`. If it's a `JSON`
+   * array it will be be a `JSONArray`.
    *
-   * @param input the given JSON string.
-   * @return      an optional JSONType element.
+   * @param input the given `JSON` string.
+   * @return      an optional `JSONType` element.
    */
   def parseRaw(input : String) : Option[JSONType] =
     phrase(root)(new lexical.Scanner(input)) match {
@@ -73,11 +71,11 @@ object JSON extends Parser {
     }
 
   /**
-   * Parse the given JSON string and return either a <code>List[Any]</code>
-   * if the JSON string specifies an <code>Array</code>, or a
-   * <code>Map[String,Any]</code> if the JSON string specifies an object.
+   * Parse the given `JSON` string and return either a `List[Any]`
+   * if the `JSON` string specifies an `Array`, or a
+   * `Map[String,Any]` if the `JSON` string specifies an object.
    *
-   * @param input the given JSON string.
+   * @param input the given `JSON` string.
    * @return      an optional list or map.
    */
   def parseFull(input: String): Option[Any] =
@@ -87,8 +85,8 @@ object JSON extends Parser {
     }
 
   /**
-   * A utility method to resolve a parsed JSON list into objects or
-   * arrays. See the parse method for details.
+   * A utility method to resolve a parsed `JSON` list into objects or
+   * arrays. See the `parse` method for details.
    */
   def resolveType(input: Any): Any = input match {
     case JSONObject(data) => data.transform {
@@ -105,8 +103,9 @@ object JSON extends Parser {
   def globalNumberParser : NumericParser = defaultNumberParser
 
   /**
-   * Defines the function used to convert a numeric string literal into a numeric format on a per-thread
-   * basis. Use globalNumberParser for a global override
+   * Defines the function used to convert a numeric string literal into a
+   * numeric format on a per-thread basis. Use `globalNumberParser` for a
+   * global override.
    */
    def perThreadNumberParser_=(f : NumericParser) { numberParser.set(f) }
    def perThreadNumberParser : NumericParser = numberParser.get()
diff --git a/src/library/scala/util/regexp/WordExp.scala b/src/library/scala/util/regexp/WordExp.scala
index 6a83794ef4..cf146934d1 100644
--- a/src/library/scala/util/regexp/WordExp.scala
+++ b/src/library/scala/util/regexp/WordExp.scala
@@ -13,27 +13,27 @@ package scala.util.regexp
 /**
  *  The class `WordExp` provides regular word expressions.
  *
- *  Users have to instantiate type member `_regexpT <;: RegExp` (from class `Base`)
- *  and a type member `_labelT <;: Label`.
+ *  Users have to instantiate type member `_regexpT <;: RegExp`
+ *  (from class `Base`) and a type member `_labelT <;: Label`.
  *
  *  Here is a short example:
- *  <pre>
- *  <b>import</b> scala.util.regexp._
- *  <b>import</b> scala.util.automata._
- *  <b>object</b> MyLang <b>extends</b> WordExp {
- *    <b>type</b> _regexpT = RegExp
- *    <b>type</b> _labelT = MyChar
+ *  {{{
+ *  import scala.util.regexp._
+ *  import scala.util.automata._
+ *  object MyLang extends WordExp {
+ *    type _regexpT = RegExp
+ *    type _labelT = MyChar
  *
- *    <b>case class</b> MyChar(c:Char) <b>extends</b> Label
+ *    case class MyChar(c:Char) extends Label
  *  }
- *  <b>import</b> MyLang._
+ *  import MyLang._
  *  // (a* | b)*
- *  <b>val</b> rex = Star(Alt(Star(Letter(MyChar('a'))),Letter(MyChar('b'))))
- *  <b>object</b> MyBerriSethi <b>extends</b> WordBerrySethi {
- *    <b>override val</b> lang = MyLang
+ *  val rex = Star(Alt(Star(Letter(MyChar('a'))),Letter(MyChar('b'))))
+ *  object MyBerriSethi extends WordBerrySethi {
+ *    override val lang = MyLang
  *  }
- *  <b>val</b> nfa = MyBerriSethi.automatonFrom(Sequ(rex), 1)
- *  </pre>
+ *  val nfa = MyBerriSethi.automatonFrom(Sequ(rex), 1)
+ *  }}}
  *
  *  @author  Burak Emir
  *  @version 1.0
@@ -55,4 +55,3 @@ abstract class WordExp extends Base {
     var pos = -1
   }
 }
-
diff --git a/src/library/scala/xml/Equality.scala b/src/library/scala/xml/Equality.scala
index 1e7cd482ed..051783c1cd 100644
--- a/src/library/scala/xml/Equality.scala
+++ b/src/library/scala/xml/Equality.scala
@@ -8,26 +8,23 @@
 
 package scala.xml
 
-/** In an attempt to contain the damage being inflicted on
- *  consistency by the ad hoc equals methods spread around
- *  xml, the logic is centralized and all the xml classes
- *  go through the xml.Equality trait.  There are two forms
- *  of xml comparison.
+/** In an attempt to contain the damage being inflicted on consistency by the
+ *  ad hoc `equals` methods spread around `xml`, the logic is centralized and
+ *  all the `xml` classes go through the `xml.Equality trait`.  There are two
+ *  forms of `xml` comparison.
  *
- *  1) def strict_==(other: xml.Equality)
+ *  1. `'''def''' strict_==(other: xml.Equality)`
  *
- *  This one tries to honor the little things like symmetry
- *  and hashCode contracts.  The equals method routes all
- *  comparisons through this.
+ *  This one tries to honor the little things like symmetry and hashCode
+ *  contracts.  The `equals` method routes all comparisons through this.
  *
- *  2) xml_==(other: Any)
+ *  1. `xml_==(other: Any)`
  *
- *  This one picks up where strict_== leaves off.  It might
- *  declare any two things equal.
+ *  This one picks up where `strict_==` leaves off.  It might declare any two
+ *  things equal.
  *
- *  As things stood, the logic not only made a mockery of
- *  the collections equals contract, but also laid waste to
- *  that of case classes.
+ *  As things stood, the logic not only made a mockery of the collections
+ *  equals contract, but also laid waste to that of case classes.
  *
  *  Among the obstacles to sanity are/were:
  *
@@ -74,7 +71,7 @@ trait Equality extends scala.Equals {
   def strict_==(other: Equality): Boolean
   def strict_!=(other: Equality) = !strict_==(other)
 
-  /** We insist we're only equal to other xml.Equality implementors,
+  /** We insist we're only equal to other `xml.Equality` implementors,
    *  which heads off a lot of inconsistency up front.
    */
   override def canEqual(other: Any): Boolean = other match {
@@ -107,4 +104,3 @@ trait Equality extends scala.Equals {
     strictlyEqual || (blithe && compareBlithely(this, asRef(other)))
   }
 }
-
diff --git a/src/library/scala/xml/NodeBuffer.scala b/src/library/scala/xml/NodeBuffer.scala
index 2495cb0f0f..1af225d856 100644
--- a/src/library/scala/xml/NodeBuffer.scala
+++ b/src/library/scala/xml/NodeBuffer.scala
@@ -6,20 +6,15 @@
 **                          |/                                          **
 \*                                                                      */
 
-
 package scala.xml
 
 /**
- * <p>
- *   This class acts as a Buffer for nodes. If it is used as a sequence
- *   of nodes <code>Seq[Node]</code>, it must be ensured that no updates
- *   occur after that point, because <code>scala.xml.Node</code> is assumed
- *   to be immutable.
- * </p>
- * <p>
- *   Despite this being a sequence, don't use it as key in a hashtable.
- *   Calling the hashcode function will result in a runtime error.
- * </p>
+ * This class acts as a Buffer for nodes. If it is used as a sequence of
+ * nodes `Seq[Node]`, it must be ensured that no updates occur after that
+ * point, because `scala.xml.Node` is assumed to be immutable.
+ *
+ * Despite this being a sequence, don't use it as key in a hashtable.
+ * Calling the hashcode function will result in a runtime error.
  *
  * @author  Burak Emir
  * @version 1.0
@@ -27,10 +22,12 @@ package scala.xml
 class NodeBuffer extends scala.collection.mutable.ArrayBuffer[Node] {
 
   /**
-   * Append given object to this buffer, returns reference on this NodeBuffer
-   * for convenience. Some rules apply: If o is null, it is ignored. If it is
-   * an Iterator or Iterable, its elements will be added. If o is a node, it is
-   * added as it is. If it is anything else, it gets wrapped in an Atom.
+   * Append given object to this buffer, returns reference on this
+   * `NodeBuffer` for convenience. Some rules apply:
+   * - If argument `o` is `'''null'''`, it is ignored.
+   * - If it is an `Iterator` or `Iterable`, its elements will be added.
+   * - If `o` is a node, it is added as it is.
+   * - If it is anything else, it gets wrapped in an [[scala.xml.Atom]].
    *
    * @param o converts to an xml node and adds to this node buffer
    * @return  this nodebuffer
diff --git a/src/library/scala/xml/NodeSeq.scala b/src/library/scala/xml/NodeSeq.scala
index 1524ab852f..2732223e19 100644
--- a/src/library/scala/xml/NodeSeq.scala
+++ b/src/library/scala/xml/NodeSeq.scala
@@ -6,8 +6,6 @@
 **                          |/                                          **
 \*                                                                      */
 
-
-
 package scala.xml
 
 import collection.{ mutable, immutable, generic, SeqLike }
@@ -34,8 +32,8 @@ object NodeSeq {
   implicit def seqToNodeSeq(s: Seq[Node]): NodeSeq = fromSeq(s)
 }
 
-/** This class implements a wrapper around <code>Seq[Node]</code> that
- *  adds XPath and comprehension methods.
+/** This class implements a wrapper around `Seq[Node]` that adds XPath
+ *  and comprehension methods.
  *
  *  @author  Burak Emir
  *  @version 1.0
@@ -72,15 +70,16 @@ abstract class NodeSeq extends immutable.Seq[Node] with SeqLike[Node, NodeSeq] w
     case _          => false
   }
 
-  /** Projection function, which returns  elements of `this` sequence based on the string `that`. Use:
+  /** Projection function, which returns  elements of `this` sequence based
+   *  on the string `that`. Use:
    *   - `this \ "foo"` to get a list of all elements that are labelled with `"foo"`;
    *   - `\ "_"` to get a list of all elements (wildcard);
    *   - `ns \ "@foo"` to get the unprefixed attribute `"foo"`;
-   *   - `ns \ "@{uri}foo"` to get the prefixed attribute `"pre:foo"` whose prefix `"pre"` is resolved to the
-   *     namespace `"uri"`.
+   *   - `ns \ "@{uri}foo"` to get the prefixed attribute `"pre:foo"` whose
+   *     prefix `"pre"` is resolved to the namespace `"uri"`.
    *
-   *  For attribute projections, the resulting [[scala.xml.NodeSeq]] attribute values are wrapped in a
-   *  [[scala.xml.Group]].
+   *  For attribute projections, the resulting [[scala.xml.NodeSeq]] attribute
+   *  values are wrapped in a [[scala.xml.Group]].
    *
    *  There is no support for searching a prefixed attribute by its literal prefix.
    *
@@ -121,16 +120,16 @@ abstract class NodeSeq extends immutable.Seq[Node] with SeqLike[Node, NodeSeq] w
     }
   }
 
-  /** Projection function, which returns elements of `this` sequence and of all its subsequences, based on
-   *  the string `that`. Use:
+  /** Projection function, which returns elements of `this` sequence and of
+   *  all its subsequences, based on the string `that`. Use:
    *   - `this \\ 'foo` to get a list of all elements that are labelled with `"foo"`;
    *   - `\\ "_"` to get a list of all elements (wildcard);
    *   - `ns \\ "@foo"` to get the unprefixed attribute `"foo"`;
-   *   - `ns \\ "@{uri}foo"` to get each prefixed attribute `"pre:foo"` whose prefix `"pre"` is resolved to the
-   *     namespace `"uri"`.
+   *   - `ns \\ "@{uri}foo"` to get each prefixed attribute `"pre:foo"` whose
+   *     prefix `"pre"` is resolved to the namespace `"uri"`.
    *
-   *  For attribute projections, the resulting [[scala.xml.NodeSeq]] attribute values are wrapped in a
-   *  [[scala.xml.Group]].
+   *  For attribute projections, the resulting [[scala.xml.NodeSeq]] attribute
+   *  values are wrapped in a [[scala.xml.Group]].
    *
    *  There is no support for searching a prefixed attribute by its literal prefix.
    *
@@ -149,5 +148,6 @@ abstract class NodeSeq extends immutable.Seq[Node] with SeqLike[Node, NodeSeq] w
   }
 
   override def toString(): String = theSeq.mkString
-  def text: String                = this map (_.text) mkString
+
+  def text: String = this map (_.text) mkString
 }
diff --git a/src/library/scala/xml/SpecialNode.scala b/src/library/scala/xml/SpecialNode.scala
index d69dbac913..758b018a13 100644
--- a/src/library/scala/xml/SpecialNode.scala
+++ b/src/library/scala/xml/SpecialNode.scala
@@ -9,13 +9,10 @@
 
 package scala.xml
 
-/** <p>
- *    <code>SpecialNode</code> is a special XML node which
- *    represents either text (PCDATA), a comment, a PI, or an entity ref.
- *  </p>
- *  <p>
- *    SpecialNodes also play the role of XMLEvents for pull-parsing.
- *  </p>
+/** `SpecialNode` is a special XML node which represents either text
+ *  `(PCDATA)`, a comment, a `PI`, or an entity ref.
+ *
+ *  SpecialNodes also play the role of XMLEvents for pull-parsing.
  *
  *  @author Burak Emir
  */
@@ -30,6 +27,6 @@ abstract class SpecialNode extends Node with pull.XMLEvent
   /** always empty */
   final def child = Nil
 
-  /** append string representation to the given stringbuffer */
+  /** Append string representation to the given stringbuffer argument. */
   def buildString(sb: StringBuilder): StringBuilder
 }
diff --git a/src/library/scala/xml/Text.scala b/src/library/scala/xml/Text.scala
index 734cbe3904..e9e09b0048 100644
--- a/src/library/scala/xml/Text.scala
+++ b/src/library/scala/xml/Text.scala
@@ -6,7 +6,6 @@
 **                          |/                                          **
 \*                                                                      */
 
-
 package scala.xml
 
 // XXX This attempt to make Text not a case class revealed a bug in the pattern
@@ -26,7 +25,7 @@ package scala.xml
 //   }
 // }
 
-/** The class <code>Text</code> implements an XML node for text (PCDATA).
+/** The class `Text` implements an XML node for text (PCDATA).
  *  It is used in both non-bound and bound XML representations.
  *
  *  @author Burak Emir
diff --git a/src/library/scala/xml/TextBuffer.scala b/src/library/scala/xml/TextBuffer.scala
index 817cf03ef4..bcd5fc731f 100644
--- a/src/library/scala/xml/TextBuffer.scala
+++ b/src/library/scala/xml/TextBuffer.scala
@@ -15,10 +15,10 @@ object TextBuffer {
   def fromString(str: String): TextBuffer = new TextBuffer() append str
 }
 
-/** The class <code>TextBuffer</code> is for creating text nodes without
- *  surplus whitespace. All occurrences of one or more whitespace in strings
- *  appended with the <code>append</code> method will be replaced by a single
- *  space character, and leading and trailing space will be removed completely.
+/** The class `TextBuffer` is for creating text nodes without surplus
+ *  whitespace. All occurrences of one or more whitespace in strings
+ *  appended with the `append` method will be replaced by a single space
+ *  character, and leading and trailing space will be removed completely.
  */
 class TextBuffer
 {
diff --git a/src/library/scala/xml/Utility.scala b/src/library/scala/xml/Utility.scala
index 05cc7b116b..3969bb9338 100644
--- a/src/library/scala/xml/Utility.scala
+++ b/src/library/scala/xml/Utility.scala
@@ -12,8 +12,8 @@ import scala.collection.mutable
 import parsing.XhtmlEntities
 
 /**
- * The <code>Utility</code> object provides utility functions for processing
- * instances of bound and not bound XML classes, as well as escaping text nodes.
+ * The `Utility` object provides utility functions for processing instances
+ * of bound and not bound XML classes, as well as escaping text nodes.
  *
  * @author Burak Emir
  */
@@ -31,22 +31,21 @@ object Utility extends AnyRef with parsing.TokenTests {
   }
   private[xml] def isAtomAndNotText(x: Node) = x.isAtom && !x.isInstanceOf[Text]
 
-  /** trims an element - call this method, when you know that it is an
+  /** Trims an element - call this method, when you know that it is an
    *  element (and not a text node) so you know that it will not be trimmed
-   *  away. With this assumption, the function can return a <code>Node</code>,
-   *  rather than a <code>Seq[Node]</code>. If you don't know, call
-   *  <code>trimProper</code> and account for the fact that you may get back
-   *  an empty sequence of nodes.
+   *  away. With this assumption, the function can return a `Node`, rather
+   *  than a `Seq[Node]`. If you don't know, call `trimProper` and account
+   *  for the fact that you may get back an empty sequence of nodes.
    *
-   *  precondition: node is not a text node (it might be trimmed)
+   *  Precondition: node is not a text node (it might be trimmed)
    */
   def trim(x: Node): Node = x match {
     case Elem(pre, lab, md, scp, child@_*) =>
       Elem(pre, lab, md, scp, (child flatMap trimProper):_*)
   }
 
-  /** trim a child of an element. <code>Attribute</code> values and
-   *  <code>Atom</code> nodes that are not <code>Text</code> nodes are unaffected.
+  /** trim a child of an element. `Attribute` values and `Atom` nodes that
+   *  are not `Text` nodes are unaffected.
    */
   def trimProper(x:Node): Seq[Node] = x match {
     case Elem(pre,lab,md,scp,child@_*) =>
@@ -56,6 +55,7 @@ object Utility extends AnyRef with parsing.TokenTests {
     case _ =>
       x
   }
+
   /** returns a sorted attribute list */
   def sort(md: MetaData): MetaData = if((md eq Null) || (md.next eq Null)) md else {
     val key = md.key
@@ -64,11 +64,12 @@ object Utility extends AnyRef with parsing.TokenTests {
     smaller.append( Null ).append(md.copy ( greater ))
   }
 
-  /** returns the node with its attribute list sorted alphabetically (prefixes are ignored) */
+  /** Return the node with its attribute list sorted alphabetically
+   *  (prefixes are ignored) */
   def sort(n:Node): Node = n match {
-	  case Elem(pre,lab,md,scp,child@_*) =>
-		  Elem(pre,lab,sort(md),scp, (child map sort):_*)
-	  case _ => n
+	case Elem(pre,lab,md,scp,child@_*) =>
+      Elem(pre,lab,sort(md),scp, (child map sort):_*)
+    case _ => n
   }
 
   /**
@@ -128,8 +129,8 @@ object Utility extends AnyRef with parsing.TokenTests {
   }
 
   /**
-   * Appends unescaped string to <code>s</code>, amp becomes &amp;
-   * lt becomes &lt; etc..
+   * Appends unescaped string to `s`, `amp` becomes `&amp;`,
+   * `lt` becomes `&lt;` etc..
    *
    * @param ref ...
    * @param s   ...
@@ -313,7 +314,7 @@ object Utility extends AnyRef with parsing.TokenTests {
   }
 
   /**
-   * Returns <code>null</code> if the value is a correct attribute value,
+   * Returns `'''null'''` if the value is a correct attribute value,
    * error message if it isn't.
    *
    * @param value ...
@@ -395,13 +396,11 @@ object Utility extends AnyRef with parsing.TokenTests {
   }
 
   /**
-   * <pre>
+   * {{{
    *   CharRef ::= "&amp;#" '0'..'9' {'0'..'9'} ";"
    *             | "&amp;#x" '0'..'9'|'A'..'F'|'a'..'f' { hexdigit } ";"
-   * </pre>
-   * <p>
-   *   see [66]
-   * <p>
+   * }}}
+   * See [66]
    *
    * @param ch                ...
    * @param nextch            ...
diff --git a/src/library/scala/xml/include/CircularIncludeException.scala b/src/library/scala/xml/include/CircularIncludeException.scala
index 2b2d357f8f..0260f5adc6 100644
--- a/src/library/scala/xml/include/CircularIncludeException.scala
+++ b/src/library/scala/xml/include/CircularIncludeException.scala
@@ -6,23 +6,19 @@
 **                          |/                                          **
 \*                                                                      */
 
-
 package scala.xml
 package include
 
 /**
- * <p>
- * A <code>CircularIncludeException</code> is thrown when
- * an included document attempts to include itself or
- * one of its ancestor documents.
- * </p>
+ *  A `CircularIncludeException` is thrown when an included document attempts
+ *  to include itself or one of its ancestor documents.
  */
 class CircularIncludeException(message: String) extends XIncludeException {
 
-    /**
-     * Constructs a <code>CircularIncludeException</code> with <code>null</code>
-     * as its error detail message.
-     */
-    def this() = this(null);
+  /**
+   * Constructs a `CircularIncludeException` with `'''null'''`.
+   * as its error detail message.
+   */
+  def this() = this(null)
 
 }
diff --git a/src/library/scala/xml/include/UnavailableResourceException.scala b/src/library/scala/xml/include/UnavailableResourceException.scala
index e5115616dd..d3b66ad498 100644
--- a/src/library/scala/xml/include/UnavailableResourceException.scala
+++ b/src/library/scala/xml/include/UnavailableResourceException.scala
@@ -6,16 +6,12 @@
 **                          |/                                          **
 \*                                                                      */
 
-
 package scala.xml
 package include
 
 /**
- * <p>
- * An <code>UnavailableResourceException</code> is thrown when
- * an included document cannot be found or loaded.
- * </p>
- *
+ * An `UnavailableResourceException` is thrown when an included document
+ * cannot be found or loaded.
  */
 class UnavailableResourceException(message: String)
 extends XIncludeException(message) {
diff --git a/src/library/scala/xml/include/sax/XIncludeFilter.scala b/src/library/scala/xml/include/sax/XIncludeFilter.scala
index a572ff3a66..adcaf1738b 100644
--- a/src/library/scala/xml/include/sax/XIncludeFilter.scala
+++ b/src/library/scala/xml/include/sax/XIncludeFilter.scala
@@ -265,12 +265,8 @@ class XIncludeFilter extends XMLFilterImpl {
     locationString
   }
 
-  /**
-    * <p>
-    * This utility method reads a document at a specified URL
-    * and fires off calls to <code>characters()</code>.
-    * It's used to include files with <code>parse="text"</code>
-    * </p>
+  /** This utility method reads a document at a specified URL and fires off
+    * calls to `characters()`. It's used to include files with `parse="text"`.
     *
     * @param  url          URL of the document that will be read
     * @param  encoding     Encoding of the document; e.g. UTF-8,
@@ -291,9 +287,9 @@ class XIncludeFilter extends XMLFilterImpl {
     catch {
       case e: MalformedURLException =>
         val ex = new UnavailableResourceException("Unresolvable URL " + url
-                                                  + getLocation());
-      ex.setRootCause(e);
-      throw new SAXException("Unresolvable URL " + url + getLocation(), ex);
+                                                  + getLocation())
+      ex.setRootCause(e)
+      throw new SAXException("Unresolvable URL " + url + getLocation(), ex)
     }
 
     try {
diff --git a/src/library/scala/xml/include/sax/XIncluder.scala b/src/library/scala/xml/include/sax/XIncluder.scala
index b291a38164..f4d69ffe44 100644
--- a/src/library/scala/xml/include/sax/XIncluder.scala
+++ b/src/library/scala/xml/include/sax/XIncluder.scala
@@ -16,13 +16,10 @@ import org.xml.sax.{ ContentHandler, XMLReader, Locator, Attributes }
 import org.xml.sax.ext.LexicalHandler
 import java.io.{ File, OutputStream, OutputStreamWriter, Writer, IOException }
 
-/** XIncluder is a SAX <code>ContentHandler</code>
- * that writes its XML document onto an output stream after resolving
- * all <code>xinclude:include</code> elements.
+/** XIncluder is a SAX `ContentHandler` that writes its XML document onto
+ * an output stream after resolving all `xinclude:include` elements.
  *
- * <p>
- *   based on Eliotte Rusty Harold's SAXXIncluder
- * </p>
+ * Based on Eliotte Rusty Harold's SAXXIncluder.
  */
 class XIncluder(outs: OutputStream, encoding: String) extends ContentHandler with LexicalHandler {
 
@@ -100,7 +97,7 @@ class XIncluder(outs: OutputStream, encoding: String) extends ContentHandler wit
         // (The end CDATA section delimiter)
         else if (c == '>') out.write("&gt;");
         else out.write(c);
-        i = i+1;
+        i += 1
       }
     }
     catch {
diff --git a/src/library/scala/xml/parsing/ConstructingParser.scala b/src/library/scala/xml/parsing/ConstructingParser.scala
index 8ea3fc839d..5571c9844d 100644
--- a/src/library/scala/xml/parsing/ConstructingParser.scala
+++ b/src/library/scala/xml/parsing/ConstructingParser.scala
@@ -36,7 +36,7 @@ object ConstructingParser {
   *     val doc = cpa.document()
   *
   *     // let's see what it is
-  *     val ppr = new scala.xml.PrettyPrinter(80,5)
+  *     val ppr = new scala.xml.PrettyPrinter(80, 5)
   *     val ele = doc.docElem
   *     println("finished parsing")
   *     val out = ppr.format(ele)
diff --git a/src/library/scala/xml/parsing/FactoryAdapter.scala b/src/library/scala/xml/parsing/FactoryAdapter.scala
index 67e06ff5ca..5aad0e7ce1 100644
--- a/src/library/scala/xml/parsing/FactoryAdapter.scala
+++ b/src/library/scala/xml/parsing/FactoryAdapter.scala
@@ -49,7 +49,7 @@ abstract class FactoryAdapter extends DefaultHandler with factory.XMLLoader[Node
   // abstract methods
 
   /** Tests if an XML element contains text.
-   * @return true if element named <code>localName</code> contains text.
+   * @return true if element named `localName` contains text.
    */
   def nodeContainsText(localName: String): Boolean // abstract
 
diff --git a/src/library/scala/xml/parsing/MarkupParser.scala b/src/library/scala/xml/parsing/MarkupParser.scala
index f6cdb1d679..39fb70904e 100644
--- a/src/library/scala/xml/parsing/MarkupParser.scala
+++ b/src/library/scala/xml/parsing/MarkupParser.scala
@@ -16,10 +16,9 @@ import Utility.Escapes.{ pairs => unescape }
 /**
  * An XML parser.
  *
- * Parses XML 1.0, invokes callback methods of a MarkupHandler
- * and returns whatever the markup handler returns. Use
- * <code>ConstructingParser</code> if you just want to parse XML to
- * construct instances of <code>scala.xml.Node</code>.
+ * Parses XML 1.0, invokes callback methods of a `MarkupHandler` and returns
+ * whatever the markup handler returns. Use `ConstructingParser` if you just
+ * want to parse XML to construct instances of `scala.xml.Node`.
  *
  * While XML elements are returned, DTD declarations - if handled - are
  * collected using side-effects.
@@ -72,7 +71,8 @@ trait MarkupParser extends MarkupParserCommon with TokenTests
   }
 
   def lookahead(): BufferedIterator[Char] = curInput match {
-    case curInputWLA:WithLookAhead => curInputWLA.lookahead()
+    case curInputWLA:WithLookAhead =>
+      curInputWLA.lookahead()
     case _ =>
       val newInput = new WithLookAhead(curInput)
       curInput = newInput
@@ -133,8 +133,9 @@ trait MarkupParser extends MarkupParserCommon with TokenTests
   // methods
   //
 
-  /** &lt;? prolog ::= xml S ... ?&gt;
-   */
+  /** {{{
+   *  &lt;? prolog ::= xml S ... ?&gt;
+   *  }}} */
   def xmlProcInstr(): MetaData = {
     xToken("xml")
     xSpace
@@ -160,14 +161,14 @@ trait MarkupParser extends MarkupParserCommon with TokenTests
       xSpaceOpt
 
     m("version") match {
-      case null => ;
+      case null =>
       case Text("1.0") => info_ver = Some("1.0"); n += 1
       case _     => reportSyntaxError("cannot deal with versions != 1.0")
     }
 
     m("encoding") match {
-      case null => ;
-      case Text(enc)  =>
+      case null =>
+      case Text(enc) =>
         if (!isValidIANAEncoding(enc))
           reportSyntaxError("\"" + enc + "\" is not a valid encoding")
         else {
@@ -178,7 +179,7 @@ trait MarkupParser extends MarkupParserCommon with TokenTests
 
     if (isProlog) {
       m("standalone") match {
-        case null => ;
+        case null =>
         case Text("yes") => info_stdl = Some(true);  n += 1
         case Text("no")  => info_stdl = Some(false); n += 1
         case _     => reportSyntaxError("either 'yes' or 'no' expected")
@@ -193,9 +194,10 @@ trait MarkupParser extends MarkupParserCommon with TokenTests
     (info_ver, info_enc, info_stdl)
   }
 
-  /** &lt;? prolog ::= xml S?
+  /** {{{
+   *  &lt;? prolog ::= xml S?
    *  // this is a bit more lenient than necessary...
-   */
+   *  }}} */
   def prolog(): (Option[String], Option[String], Option[Boolean]) =
     prologOrTextDecl(true)
 
@@ -203,20 +205,19 @@ trait MarkupParser extends MarkupParserCommon with TokenTests
   def textDecl(): (Option[String], Option[String]) =
     prologOrTextDecl(false) match { case (x1, x2, _)  => (x1, x2) }
 
-  /**
-   *[22]        prolog     ::=          XMLDecl? Misc* (doctypedecl Misc*)?
-   *[23]        XMLDecl    ::=          '&lt;?xml' VersionInfo EncodingDecl? SDDecl? S? '?>'
-   *[24]        VersionInfo        ::=          S 'version' Eq ("'" VersionNum "'" | '"' VersionNum '"')
-   *[25]        Eq         ::=          S? '=' S?
-   *[26]        VersionNum         ::=          '1.0'
-   *[27]        Misc       ::=          Comment | PI | S
-   */
-
+  /** {{{
+   *  [22]     prolog      ::= XMLDecl? Misc* (doctypedecl Misc*)?
+   *  [23]     XMLDecl     ::= '<?xml' VersionInfo EncodingDecl? SDDecl? S? '?>'
+   *  [24]     VersionInfo ::= S 'version' Eq ("'" VersionNum "'" | '"' VersionNum '"')
+   *  [25]     Eq          ::= S? '=' S?
+   *  [26]     VersionNum  ::= '1.0'
+   *  [27]     Misc        ::= Comment | PI | S
+   * }}} */
   def document(): Document = {
     doc = new Document()
 
     this.dtd = null
-    var info_prolog: Tuple3[Option[String], Option[String], Option[Boolean]] = Tuple3(None, None, None);
+    var info_prolog: (Option[String], Option[String], Option[Boolean]) = (None, None, None)
     if ('<' != ch) {
       reportSyntaxError("< expected")
       return null
@@ -225,7 +226,7 @@ trait MarkupParser extends MarkupParserCommon with TokenTests
     nextch // is prolog ?
     var children: NodeSeq = null
     if ('?' == ch) {
-      nextch;
+      nextch
       info_prolog = prolog()
       doc.version    = info_prolog._1
       doc.encoding   = info_prolog._2
@@ -234,25 +235,25 @@ trait MarkupParser extends MarkupParserCommon with TokenTests
       children = content(TopScope) // DTD handled as side effect
     }
     else {
-      val ts = new NodeBuffer();
-      content1(TopScope, ts); // DTD handled as side effect
-      ts &+ content(TopScope);
-      children = NodeSeq.fromSeq(ts);
-    }
-    //Console.println("[MarkupParser::document] children now: "+children.toList);
-    var elemCount = 0;
-    var theNode: Node = null;
+      val ts = new NodeBuffer()
+      content1(TopScope, ts)  // DTD handled as side effect
+      ts &+ content(TopScope)
+      children = NodeSeq.fromSeq(ts)
+    }
+    //println("[MarkupParser::document] children now: "+children.toList)
+    var elemCount = 0
+    var theNode: Node = null
     for (c <- children) c match {
-      case _:ProcInstr => ;
-      case _:Comment => ;
+      case _:ProcInstr =>
+      case _:Comment =>
       case _:EntityRef => // todo: fix entities, shouldn't be "special"
         reportSyntaxError("no entity references allowed here");
       case s:SpecialNode =>
         if (s.toString().trim().length > 0) //non-empty text nodes not allowed
-          elemCount = elemCount + 2;
+          elemCount += 2
       case m:Node =>
-        elemCount = elemCount + 1;
-        theNode = m;
+        elemCount += 1
+        theNode = m
     }
     if (1 != elemCount) {
       reportSyntaxError("document must contain exactly one element")
@@ -293,9 +294,11 @@ trait MarkupParser extends MarkupParserCommon with TokenTests
   }
 
   /** parse attribute and create namespace scope, metadata
+   *  {{{
    *  [41] Attributes    ::= { S Name Eq AttValue }
+   *  }}}
    */
-  def xAttributes(pscope:NamespaceBinding): (MetaData,NamespaceBinding) = {
+  def xAttributes(pscope: NamespaceBinding): (MetaData, NamespaceBinding) = {
     var scope: NamespaceBinding = pscope
     var aMap: MetaData = Null
     while (isNameStart(ch)) {
@@ -307,22 +310,22 @@ trait MarkupParser extends MarkupParserCommon with TokenTests
 
       Utility.prefix(qname) match {
         case Some("xmlns") =>
-          val prefix = qname.substring(6 /*xmlns:*/ , qname.length);
-          scope = new NamespaceBinding(prefix, value, scope);
+          val prefix = qname.substring(6 /*xmlns:*/ , qname.length)
+          scope = new NamespaceBinding(prefix, value, scope)
 
-        case Some(prefix)       =>
-          val key = qname.substring(prefix.length+1, qname.length);
-          aMap = new PrefixedAttribute(prefix, key, Text(value), aMap);
+        case Some(prefix) =>
+          val key = qname.substring(prefix.length+1, qname.length)
+          aMap = new PrefixedAttribute(prefix, key, Text(value), aMap)
 
-        case _             =>
+        case _ =>
           if( qname == "xmlns" )
-            scope = new NamespaceBinding(null, value, scope);
+            scope = new NamespaceBinding(null, value, scope)
           else
-            aMap = new UnprefixedAttribute(qname, Text(value), aMap);
+            aMap = new UnprefixedAttribute(qname, Text(value), aMap)
       }
 
       if ((ch != '/') && (ch != '>') && ('?' != ch))
-        xSpace;
+        xSpace
     }
 
     if(!aMap.wellformed(scope))
@@ -332,8 +335,10 @@ trait MarkupParser extends MarkupParserCommon with TokenTests
   }
 
   /** entity value, terminated by either ' or ". value may not contain &lt;.
+   *  {{{
    *       AttValue     ::= `'` { _  } `'`
    *                      | `"` { _ } `"`
+   *  }}}
    */
   def xEntityValue(): String = {
     val endch = ch
@@ -348,10 +353,11 @@ trait MarkupParser extends MarkupParserCommon with TokenTests
     str
   }
 
-  /** '&lt;! CharData ::= [CDATA[ ( {char} - {char}"]]&gt;"{char} ) ']]&gt;'
+  /** {{{
+   *  '&lt;! CharData ::= [CDATA[ ( {char} - {char}"]]&gt;"{char} ) ']]&gt;'
    *
-   * see [15]
-   */
+   *  see [15]
+   *  }}} */
   def xCharData: NodeSeq = {
     xToken("[CDATA[")
     def mkResult(pos: Int, s: String): NodeSeq = {
@@ -361,10 +367,11 @@ trait MarkupParser extends MarkupParserCommon with TokenTests
     xTakeUntil(mkResult, () => pos, "]]>")
   }
 
-  /** Comment ::= '&lt;!--' ((Char - '-') | ('-' (Char - '-')))* '--&gt;'
+  /** {{{
+   *  Comment ::= '&lt;!--' ((Char - '-') | ('-' (Char - '-')))* '--&gt;'
    *
    * see [15]
-   */
+   *  }}} */
   def xComment: NodeSeq = {
     val sb: StringBuilder = new StringBuilder()
     xToken("--")
@@ -390,8 +397,10 @@ trait MarkupParser extends MarkupParserCommon with TokenTests
       }
   }
 
-  /** '&lt;' content1 ::=  ... */
-  def content1(pscope: NamespaceBinding, ts: NodeBuffer): Unit =
+  /** {{{
+   *  '&lt;' content1 ::=  ...
+   *  }}} */
+  def content1(pscope: NamespaceBinding, ts: NodeBuffer) {
     ch match {
       case '!' =>
         nextch
@@ -407,8 +416,11 @@ trait MarkupParser extends MarkupParserCommon with TokenTests
       case _   =>
         ts &+ element1(pscope)      // child
     }
+  }
 
-  /** content1 ::=  '&lt;' content1 | '&amp;' charref ... */
+  /** {{{
+   *  content1 ::=  '&lt;' content1 | '&amp;' charref ...
+   *  }}} */
   def content(pscope: NamespaceBinding): NodeSeq = {
     var ts = new NodeBuffer
     var exit = eof
@@ -447,16 +459,16 @@ trait MarkupParser extends MarkupParserCommon with TokenTests
               } else push(n)
           }
         case _ => // text content
-          appendText(tmppos, ts, xText);
+          appendText(tmppos, ts, xText)
       }
     }
     done
   } // content(NamespaceBinding)
 
-  /** externalID ::= SYSTEM S syslit
+  /** {{{
+   *  externalID ::= SYSTEM S syslit
    *                 PUBLIC S pubid S syslit
-   */
-
+   *  }}} */
   def externalID(): ExternalID = ch match {
     case 'S' =>
       nextch
@@ -476,14 +488,13 @@ trait MarkupParser extends MarkupParserCommon with TokenTests
 
   /** parses document type declaration and assigns it to instance variable
    *  dtd.
-   *
+   *  {{{
    *  &lt;! parseDTD ::= DOCTYPE name ... >
-   */
-  def parseDTD(): Unit = { // dirty but fast
-    //Console.println("(DEBUG) parseDTD");
+   *  }}} */
+  def parseDTD() { // dirty but fast
     var extID: ExternalID = null
     if (this.dtd ne null)
-      reportSyntaxError("unexpected character (DOCTYPE already defined");
+      reportSyntaxError("unexpected character (DOCTYPE already defined")
     xToken("DOCTYPE")
     xSpace
     val n = xName
@@ -532,9 +543,10 @@ trait MarkupParser extends MarkupParserCommon with TokenTests
     element1(pscope)
   }
 
-  /** '&lt;' element ::= xmlTag1 '&gt;'  { xmlExpr | '{' simpleExpr '}' } ETag
+  /** {{{
+   *  '&lt;' element ::= xmlTag1 '&gt;'  { xmlExpr | '{' simpleExpr '}' } ETag
    *               | xmlTag1 '/' '&gt;'
-   */
+   *  }}} */
   def element1(pscope: NamespaceBinding): NodeSeq = {
     val pos = this.pos
     val (qname, (aMap, scope)) = xTag(pscope)
@@ -561,8 +573,9 @@ trait MarkupParser extends MarkupParserCommon with TokenTests
     res
   }
 
-  /** parse character data.
-   *   precondition: xEmbeddedBlock == false (we are not in a scala block)
+  /** Parse character data.
+   *
+   *  precondition: `xEmbeddedBlock == false` (we are not in a scala block)
    */
   def xText: String = {
     var exit = false;
@@ -579,9 +592,10 @@ trait MarkupParser extends MarkupParserCommon with TokenTests
   }
 
   /** attribute value, terminated by either ' or ". value may not contain &lt;.
+   *  {{{
    *       AttValue     ::= `'` { _ } `'`
    *                      | `"` { _ } `"`
-   */
+   *  }}} */
   def systemLiteral(): String = {
     val endch = ch
     if (ch != '\'' && ch != '"')
@@ -597,7 +611,9 @@ trait MarkupParser extends MarkupParserCommon with TokenTests
     str
   }
 
-  /* [12]       PubidLiteral ::=        '"' PubidChar* '"' | "'" (PubidChar - "'")* "'" */
+  /** {{{
+   *  [12]       PubidLiteral ::=        '"' PubidChar* '"' | "'" (PubidChar - "'")* "'"
+   *  }}} */
   def pubidLiteral(): String = {
     val endch = ch
     if (ch!='\'' && ch != '"')
@@ -605,9 +621,9 @@ trait MarkupParser extends MarkupParserCommon with TokenTests
     nextch
     while (ch != endch && !eof) {
       putChar(ch)
-      //Console.println("hello '"+ch+"'"+isPubIDChar(ch));
+      //println("hello '"+ch+"'"+isPubIDChar(ch))
       if (!isPubIDChar(ch))
-        reportSyntaxError("char '"+ch+"' is not allowed in public id");
+        reportSyntaxError("char '"+ch+"' is not allowed in public id")
       nextch
     }
     nextch
@@ -621,10 +637,10 @@ trait MarkupParser extends MarkupParserCommon with TokenTests
   //
 
   def extSubset(): Unit = {
-    var textdecl:Tuple2[Option[String],Option[String]] = null;
-    if (ch=='<') {
+    var textdecl: (Option[String],Option[String]) = null
+    if (ch == '<') {
       nextch
-      if (ch=='?') {
+      if (ch == '?') {
         nextch
         textdecl = textDecl()
       } else
@@ -683,8 +699,8 @@ trait MarkupParser extends MarkupParserCommon with TokenTests
 
               stmt match {
                 // parameter entity
-                case "INCLUDE"  => doInclude()
-                case "IGNORE"   => doIgnore()
+                case "INCLUDE" => doInclude()
+                case "IGNORE"  => doIgnore()
               }
             case 'I' =>
               nextch
@@ -760,8 +776,9 @@ trait MarkupParser extends MarkupParserCommon with TokenTests
     handle.elemDecl(n, cmstr)
   }
 
-  /** &lt;! attlist := ATTLIST
-   */
+  /** {{{
+   *  &lt;! attlist := ATTLIST
+   *  }}} */
   def attrDecl() = {
     xToken("TTLIST")
     xSpace
@@ -776,8 +793,8 @@ trait MarkupParser extends MarkupParserCommon with TokenTests
       // could be enumeration (foo,bar) parse this later :-/
       while ('"' != ch && '\'' != ch && '#' != ch && '<' != ch) {
         if (!isSpace(ch))
-          cbuf.append(ch);
-        nextch;
+          cbuf.append(ch)
+        nextch
       }
       val atpe = cbuf.toString()
       cbuf.length = 0
@@ -805,10 +822,10 @@ trait MarkupParser extends MarkupParserCommon with TokenTests
     handle.attListDecl(n, attList.reverse)
   }
 
-  /** &lt;! element := ELEMENT
-   */
+  /** {{{
+   *  &lt;! element := ELEMENT
+   *  }}} */
   def entityDecl() = {
-    //Console.println("entityDecl()")
     var isParameterEntity = false
     var entdef: EntityDef = null
     xToken("NTITY")
@@ -854,8 +871,9 @@ trait MarkupParser extends MarkupParserCommon with TokenTests
     {}
   } // entityDecl
 
-  /** 'N' notationDecl ::= "OTATION"
-   */
+  /** {{{
+   *  'N' notationDecl ::= "OTATION"
+   *  }}} */
   def notationDecl() {
     xToken("OTATION")
     xSpace
@@ -885,9 +903,9 @@ trait MarkupParser extends MarkupParserCommon with TokenTests
     handle.notationDecl(notat, extID)
   }
 
-  def reportSyntaxError(pos: Int, str: String): Unit = curInput.reportError(pos, str)
-  def reportSyntaxError(str: String): Unit = reportSyntaxError(pos, str)
-  def reportValidationError(pos: Int, str: String): Unit = reportSyntaxError(pos, str)
+  def reportSyntaxError(pos: Int, str: String) { curInput.reportError(pos, str) }
+  def reportSyntaxError(str: String) { reportSyntaxError(pos, str) }
+  def reportValidationError(pos: Int, str: String) { reportSyntaxError(pos, str) }
 
   def push(entityName: String) {
     if (!eof)
diff --git a/src/library/scala/xml/parsing/TokenTests.scala b/src/library/scala/xml/parsing/TokenTests.scala
index 4cf0c640b3..d49aa418a0 100644
--- a/src/library/scala/xml/parsing/TokenTests.scala
+++ b/src/library/scala/xml/parsing/TokenTests.scala
@@ -1,13 +1,11 @@
 /*                     __                                               *\
 **     ________ ___   / /  ___     Scala API                            **
 **    / __/ __// _ | / /  / _ |    (c) 2003-2011, LAMP/EPFL             **
-**  __\ \/ /__/ __ |/ /__/ __ |                                         **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
 ** /____/\___/_/ |_/____/_/ | |                                         **
 **                          |/                                          **
 \*                                                                      */
 
-
-
 package scala.xml
 package parsing
 
@@ -16,22 +14,27 @@ package parsing
  */
 trait TokenTests {
 
-  /** (#x20 | #x9 | #xD | #xA) */
+  /** {{{
+   *  (#x20 | #x9 | #xD | #xA)
+   *  }}} */
   final def isSpace(ch: Char): Boolean = ch match {
     case '\u0009' | '\u000A' | '\u000D' | '\u0020' => true
     case _                                         => false
   }
-  /** (#x20 | #x9 | #xD | #xA)+ */
+  /** {{{
+   *  (#x20 | #x9 | #xD | #xA)+
+   *  }}} */
   final def isSpace(cs: Seq[Char]): Boolean = cs.nonEmpty && (cs forall isSpace)
 
   /** These are 99% sure to be redundant but refactoring on the safe side. */
   def isAlpha(c: Char) = (c >= 'A' && c <= 'Z') || (c >= 'a' && c <= 'z')
   def isAlphaDigit(c: Char) = isAlpha(c) || (c >= '0' && c <= '9')
 
-  /** NameChar ::= Letter | Digit | '.' | '-' | '_' | ':'
+  /** {{{
+   *  NameChar ::= Letter | Digit | '.' | '-' | '_' | ':'
    *             | CombiningChar | Extender
-   *
-   * see [4] and Appendix B of XML 1.0 specification
+   *  }}}
+   *  See [4] and Appendix B of XML 1.0 specification.
   */
   def isNameChar(ch: Char) = {
     import java.lang.Character._
@@ -40,17 +43,19 @@ trait TokenTests {
     isNameStart(ch) || (getType(ch).toByte match {
       case COMBINING_SPACING_MARK |
               ENCLOSING_MARK | NON_SPACING_MARK |
-              MODIFIER_LETTER | DECIMAL_DIGIT_NUMBER    => true
-      case _                                            => ".-:" contains ch
+              MODIFIER_LETTER | DECIMAL_DIGIT_NUMBER => true
+      case _                                         => ".-:" contains ch
     })
   }
 
-  /** NameStart ::= ( Letter | '_' )
+  /** {{{
+   *  NameStart ::= ( Letter | '_' )
+   *  }}}
    *  where Letter means in one of the Unicode general
-   *  categories { Ll, Lu, Lo, Lt, Nl }
+   *  categories `{ Ll, Lu, Lo, Lt, Nl }`.
    *
-   *  We do not allow a name to start with ':'.
-   *  see [3] and Appendix B of XML 1.0 specification
+   *  We do not allow a name to start with `:`.
+   *  See [3] and Appendix B of XML 1.0 specification
    */
   def isNameStart(ch: Char) = {
     import java.lang.Character._
@@ -58,14 +63,15 @@ trait TokenTests {
     getType(ch).toByte match {
       case LOWERCASE_LETTER |
               UPPERCASE_LETTER | OTHER_LETTER |
-              TITLECASE_LETTER | LETTER_NUMBER    => true
-      case _                                      => ch == '_'
+              TITLECASE_LETTER | LETTER_NUMBER => true
+      case _                                   => ch == '_'
     }
   }
 
-  /** Name ::= ( Letter | '_' ) (NameChar)*
-   *
-   *  see  [5] of XML 1.0 specification
+  /** {{{
+   *  Name ::= ( Letter | '_' ) (NameChar)*
+   *  }}}
+   *  See [5] of XML 1.0 specification.
    */
   def isName(s: String) =
     s.nonEmpty && isNameStart(s.head) && (s.tail forall isNameChar)
@@ -75,7 +81,7 @@ trait TokenTests {
     ("""-\()+,./:=?;!*#@$_%""" contains ch)
 
   /**
-   * Returns true if the encoding name is a valid IANA encoding.
+   * Returns `true` if the encoding name is a valid IANA encoding.
    * This method does not verify that there is a decoder available
    * for this encoding, only that the characters are valid for an
    * IANA encoding name.
diff --git a/src/library/scala/xml/parsing/XhtmlEntities.scala b/src/library/scala/xml/parsing/XhtmlEntities.scala
index 8ab229affd..53a4a32613 100644
--- a/src/library/scala/xml/parsing/XhtmlEntities.scala
+++ b/src/library/scala/xml/parsing/XhtmlEntities.scala
@@ -6,15 +6,14 @@
 **                          |/                                          **
 \*                                                                      */
 
-
 package scala.xml
 package parsing
 
 import scala.xml.dtd.{ IntDef, ParsedEntityDecl }
 
-/** <p>
- *    (c) David Pollak 2007 WorldWide Conferencing, LLC.
- *  </p>
+/**
+ *  @author (c) David Pollak 2007 WorldWide Conferencing, LLC.
+ *
  */
 object XhtmlEntities {
   val entList = List(("quot",34), ("amp",38), ("lt",60), ("gt",62), ("nbsp",160), ("iexcl",161), ("cent",162), ("pound",163), ("curren",164), ("yen",165),
diff --git a/src/library/scala/xml/parsing/XhtmlParser.scala b/src/library/scala/xml/parsing/XhtmlParser.scala
index fb61376321..de9a3f2243 100644
--- a/src/library/scala/xml/parsing/XhtmlParser.scala
+++ b/src/library/scala/xml/parsing/XhtmlParser.scala
@@ -6,30 +6,24 @@
 **                          |/                                          **
 \*                                                                      */
 
-
 package scala.xml
 package parsing
 
 import scala.io.Source
 
-/** <p>
- *    An XML Parser that preserves CDATA blocks and knows about HtmlEntities.
- *  </p>
- *  <p>
- *    (c) David Pollak, 2007 WorldWide Conferencing, LLC.
- *  </p>
+/** An XML Parser that preserves `CDATA` blocks and knows about
+ *  [[scala.xml.parsing.HtmlEntities]].
+ *
+ *  @author (c) David Pollak, 2007 WorldWide Conferencing, LLC.
  */
 class XhtmlParser(val input: Source) extends ConstructingHandler with MarkupParser with ExternalSources  {
   val preserveWS = true
   ent ++= XhtmlEntities()
 }
 
-/** <p>
- *    Convenience method that instantiates, initializes and runs an XhtmlParser.
- *  </p>
- *  <p>
- *    (c) Burak Emir
- *  </p>
+/** Convenience method that instantiates, initializes and runs an `XhtmlParser`.
+ *
+ *  @author Burak Emir
  */
 object XhtmlParser {
   def apply(source: Source): NodeSeq = new XhtmlParser(source).initialize.document
diff --git a/src/library/scala/xml/persistent/CachedFileStorage.scala b/src/library/scala/xml/persistent/CachedFileStorage.scala
index bcdd1a3f2d..68a475ae90 100644
--- a/src/library/scala/xml/persistent/CachedFileStorage.scala
+++ b/src/library/scala/xml/persistent/CachedFileStorage.scala
@@ -6,7 +6,6 @@
 **                          |/                                          **
 \*                                                                      */
 
-
 package scala.xml
 package persistent
 
@@ -17,13 +16,12 @@ import java.lang.Thread
 import scala.util.logging.Logged
 import scala.collection.Iterator
 
-/** <p>
- *    Mutable storage of immutable xml trees. Everything is kept in memory,
- *    with a thread periodically checking for changes and writing to file.
- *    To ensure atomicity, two files are used, filename1 and '$'+filename1.
- *    The implementation switches between the two, deleting the older one
- *    after a complete dump of the database has been written.
- *  </p>
+/** Mutable storage of immutable xml trees. Everything is kept in memory,
+ *  with a thread periodically checking for changes and writing to file.
+ *
+ *  To ensure atomicity, two files are used, `filename1` and `'$'+filename1`.
+ *  The implementation switches between the two, deleting the older one
+ *  after a complete dump of the database has been written.
  *
  *  @author Burak Emir
  */
@@ -31,7 +29,8 @@ abstract class CachedFileStorage(private val file1: File) extends Thread with Lo
 
   private val file2 = new File(file1.getParent, file1.getName+"$")
 
-  /**  either equals file1 or file2, references the next file in which updates will be stored
+  /** Either equals `file1` or `file2`, references the next file in which
+   *  updates will be stored.
    */
   private var theFile: File = null
 
@@ -85,10 +84,10 @@ abstract class CachedFileStorage(private val file1: File) extends Thread with Lo
 
   /** saves the XML to file */
   private def save() = if (this.dirty) {
-    log("[save]\ndeleting "+theFile);
-    theFile.delete();
-    log("creating new "+theFile);
-    theFile.createNewFile();
+    log("[save]\ndeleting "+theFile)
+    theFile.delete()
+    log("creating new "+theFile)
+    theFile.createNewFile()
     val fos = new FileOutputStream(theFile)
     val c   = fos.getChannel()
 
@@ -97,7 +96,7 @@ abstract class CachedFileStorage(private val file1: File) extends Thread with Lo
     val w = Channels.newWriter(c, "utf-8")
     XML.write(w, storageNode, "utf-8", true, null)
 
-    log("writing to "+theFile);
+    log("writing to "+theFile)
 
     w.close
     c.close
@@ -107,19 +106,20 @@ abstract class CachedFileStorage(private val file1: File) extends Thread with Lo
     log("[save done]")
   }
 
-  /** run method of the thread. remember to use start() to start a thread, not run. */
+  /** Run method of the thread. remember to use `start()` to start a thread,
+    * not `run`. */
   override def run = {
-    log("[run]\nstarting storage thread, checking every "+interval+" ms");
-    while(true) {
-      Thread.sleep( this.interval );
+    log("[run]\nstarting storage thread, checking every "+interval+" ms")
+    while (true) {
+      Thread.sleep( this.interval )
       save
     }
   }
 
-  /** forces writing of contents to the file, even if there has not been any update. */
+  /** Force writing of contents to the file, even if there has not been any
+    * update. */
   def flush() = {
-    this.dirty = true;
+    this.dirty = true
     save
   }
 }
-