Formatting fixes for scala.util.

37 files changed, 437 insertions, 481 deletions

diff --git a/src/library/scala/util/DynamicVariable.scala b/src/library/scala/util/DynamicVariable.scala
index fa9d17a4e9..740e2a3b3a 100644
--- a/src/library/scala/util/DynamicVariable.scala
+++ b/src/library/scala/util/DynamicVariable.scala
@@ -10,13 +10,13 @@ package scala.util
 
 import java.lang.InheritableThreadLocal
 
-/** DynamicVariables provide a binding mechanism where the current
+/** `DynamicVariables` provide a binding mechanism where the current
  *  value is found through dynamic scope, but where access to the
  *  variable itself is resolved through static scope.
  *
- *  The current value can be retrieved with the value method.  New values
- *  should be pushed using the withValue method. Values pushed via
- *  withValue only stay valid while the withValue's second argument, a
+ *  The current value can be retrieved with the value method. New values
+ *  should be pushed using the `withValue` method. Values pushed via
+ *  `withValue` only stay valid while the `withValue`'s second argument, a
  *  parameterless closure, executes. When the second argument finishes,
  *  the variable reverts to the previous value.
  *
@@ -28,7 +28,7 @@ import java.lang.InheritableThreadLocal
  *  }}}
  *
  *  Each thread gets its own stack of bindings.  When a
- *  new thread is created, the DynamicVariable gets a copy
+ *  new thread is created, the `DynamicVariable` gets a copy
  *  of the stack of bindings from the parent thread, and
  *  from then on the bindings for the new thread
  *  are independent of those for the original thread.
diff --git a/src/library/scala/util/Properties.scala b/src/library/scala/util/Properties.scala
index f86df0ee96..d2c9e6770b 100644
--- a/src/library/scala/util/Properties.scala
+++ b/src/library/scala/util/Properties.scala
@@ -11,7 +11,7 @@ package scala.util
 
 import java.io.{ IOException, PrintWriter }
 
-/** Loads library.properties from the jar. */
+/** Loads `library.properties` from the jar. */
 object Properties extends PropertiesTrait {
   protected def propCategory    = "library"
   protected def pickJarBasedOn  = classOf[ScalaObject]
@@ -59,7 +59,7 @@ private[scala] trait PropertiesTrait {
   def scalaPropOrEmpty(name: String): String             = scalaPropOrElse(name, "")
   def scalaPropOrNone(name: String): Option[String]      = Option(scalaProps.getProperty(name))
 
-  /** The numeric portion of the runtime scala version, if this is a final
+  /** The numeric portion of the runtime Scala version, if this is a final
    *  release.  If for instance the versionString says "version 2.9.0.final",
    *  this would return Some("2.9.0").
    *
@@ -72,7 +72,7 @@ private[scala] trait PropertiesTrait {
     if (segments.size == 4 && segments.last == "final") Some(segments take 3 mkString ".") else None
   }
 
-  /** The development scala version, if this is not a final release.
+  /** The development Scala version, if this is not a final release.
    *  The precise contents are not guaranteed, but it aims to provide a
    *  unique repository identifier (currently the svn revision) in the
    *  fourth dotted segment if the running version was built from source.
@@ -103,7 +103,7 @@ private[scala] trait PropertiesTrait {
   def sourceReader          = scalaPropOrElse("source.reader", "scala.tools.nsc.io.SourceReader")
 
   /** This is the default text encoding, overridden (unreliably) with
-   *  JAVA_OPTS="-Dfile.encoding=Foo"
+   *  `JAVA_OPTS="-Dfile.encoding=Foo"`
    */
   def encodingString        = propOrElse("file.encoding", "UTF-8")
 
diff --git a/src/library/scala/util/Random.scala b/src/library/scala/util/Random.scala
index cfd6154874..791582c9ec 100644
--- a/src/library/scala/util/Random.scala
+++ b/src/library/scala/util/Random.scala
@@ -100,8 +100,8 @@ class Random(val self: java.util.Random) {
 
   /** Returns a new collection of the same type in a randomly chosen order.
    *
-   *  @param  coll    the TraversableOnce to shuffle
-   *  @return         the shuffled TraversableOnce
+   *  @param  coll    the [[scala.collection.TraversableOnce]] to shuffle
+   *  @return         the shuffled [[scala.collection.TraversableOnce]]
    */
   def shuffle[T, CC[X] <: TraversableOnce[X]](xs: CC[T])(implicit bf: CanBuildFrom[CC[T], T, CC[T]]): CC[T] = {
     val buf = new ArrayBuffer[T] ++= xs
@@ -122,7 +122,7 @@ class Random(val self: java.util.Random) {
 
 }
 
-/** The object <code>Random</code> offers a default implementation
+/** The object `Random` offers a default implementation
  *  of scala.util.Random and random-related convenience methods.
  *
  *  @since 2.8
diff --git a/src/library/scala/util/Sorting.scala b/src/library/scala/util/Sorting.scala
index f286670f25..bf460a118f 100644
--- a/src/library/scala/util/Sorting.scala
+++ b/src/library/scala/util/Sorting.scala
@@ -13,12 +13,12 @@ import scala.math.Ordering
 
 /** The Sorting object provides functions that can sort various kinds of
   * objects. You can provide a comparison function, or you can request a sort
-  * of items that are viewable as <code>Ordered</code>. Some sorts that
+  * of items that are viewable as [[scala.math.Ordered]]. Some sorts that
   * operate directly on a subset of value types are also provided. These
   * implementations are derived from those in the Sun JDK.
   *
-  * Note that stability doesn't matter for value types, so use the quickSort
-  * variants for those. <code>stableSort</code> is intended to be used with
+  * Note that stability doesn't matter for value types, so use the `quickSort`
+  * variants for those. `stableSort` is intended to be used with
   * objects when the prior ordering should be preserved, where possible.
   *
   * @author  Ross Judson
@@ -43,17 +43,15 @@ object Sorting {
     stableSort(a, 0, a.length-1, new Array[K](a.length), Ordering[K].lt _)
   }
 
-  /** Sorts an array of <code>K</code> given an ordering function
-   *  <code>f</code>. <code>f</code> should return <code>true</code> iff
-   *  its first parameter is strictly less than its second parameter.
+  /** Sorts an array of `K` given an ordering function `f`.
+   *  `f` should return `true` iff its first parameter is strictly less than its second parameter.
    */
   def stableSort[K: ClassManifest](a: Array[K], f: (K, K) => Boolean) {
     stableSort(a, 0, a.length-1, new Array[K](a.length), f)
   }
 
   /** Sorts an arbitrary sequence into an array, given a comparison function
-   *  that should return <code>true</code> iff parameter one is strictly less
-   *  than parameter two.
+   *  that should return `true` iff parameter one is strictly less than parameter two.
    *
    *  @param  a the sequence to be sorted.
    *  @param  f the comparison function.
@@ -125,7 +123,7 @@ object Sorting {
           var l = off
           var n = off + len - 1
           if (len > 40) {        // Big arrays, pseudomedian of 9
-            var s = len / 8
+            val s = len / 8
             l = med3(l, l+s, l+2*s)
             m = med3(m-s, m, m+s)
             n = med3(n-2*s, n-s, n)
@@ -226,7 +224,7 @@ object Sorting {
           var l = off
           var n = off + len - 1
           if (len > 40) {        // Big arrays, pseudomedian of 9
-            var s = len / 8
+            val s = len / 8
             l = med3(l, l+s, l+2*s)
             m = med3(m-s, m, m+s)
             n = med3(n-2*s, n-s, n)
@@ -330,7 +328,7 @@ object Sorting {
           var l = off
           var n = off + len - 1
           if (len > 40) {        // Big arrays, pseudomedian of 9
-            var s = len / 8
+            val s = len / 8
             l = med3(l, l+s, l+2*s)
             m = med3(m-s, m, m+s)
             n = med3(n-2*s, n-s, n)
@@ -438,7 +436,7 @@ object Sorting {
           var l = off
           var n = off + len - 1
           if (len > 40) {        // Big arrays, pseudomedian of 9
-            var s = len / 8
+            val s = len / 8
             l = med3(l, l+s, l+2*s)
             m = med3(m-s, m, m+s)
             n = med3(n-2*s, n-s, n)
diff --git a/src/library/scala/util/automata/BaseBerrySethi.scala b/src/library/scala/util/automata/BaseBerrySethi.scala
index 4b1003ba33..51e15f0e71 100644
--- a/src/library/scala/util/automata/BaseBerrySethi.scala
+++ b/src/library/scala/util/automata/BaseBerrySethi.scala
@@ -15,10 +15,9 @@ import scala.collection.{ mutable, immutable }
 
 // todo: replace global variable pos with acc
 
-/** this turns a regexp over A into a 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.NondetWorkAutom]]
+  * over A using the celebrated position automata construction (also called ''Berry-Sethi'' or ''Glushkov'').
+  */
 abstract class BaseBerrySethi {
   val lang: Base
   import lang.{ Alt, Eps, Meta, RegExp, Sequ, Star }
@@ -47,10 +46,10 @@ abstract class BaseBerrySethi {
     case _        => throw new IllegalArgumentException("unexpected pattern " + r.getClass())
   }
 
-  /** computes first( r ) for the word regexp r */
+  /** Computes `first(r)` for the word regexp `r`. */
   protected def compFirst(r: RegExp): Set[Int] = doComp(r, compFirst)
 
-  /** computes last( r ) for the regexp r */
+  /** Computes `last(r)` for the regexp `r`. */
   protected def compLast(r: RegExp): Set[Int] = doComp(r, compLast)
 
   /** Starts from the right-to-left
@@ -73,8 +72,7 @@ abstract class BaseBerrySethi {
     follow(0)
   }
 
-  /** returns the first set of an expression, setting the follow set along
-   *  the way.
+  /** Returns the first set of an expression, setting the follow set along the way.
    *
    *  @param fol1 ...
    *  @param r    ...
@@ -94,8 +92,7 @@ abstract class BaseBerrySethi {
     case _          => throw new IllegalArgumentException("unexpected pattern: " + r.getClass())
   }
 
-  /** returns "Sethi-length" of a pattern, creating the set of position
-   *  along the way.
+  /** Returns the "Sethi-length" of a pattern, creating the set of position along the way.
    *
    *  @param r ...
    */
diff --git a/src/library/scala/util/automata/Inclusion.scala b/src/library/scala/util/automata/Inclusion.scala
index c45fca5824..63133998b4 100644
--- a/src/library/scala/util/automata/Inclusion.scala
+++ b/src/library/scala/util/automata/Inclusion.scala
@@ -12,7 +12,7 @@ package scala.util.automata
 
 
 /** A fast test of language inclusion between minimal automata.
- *  inspired by the AMoRE automata library
+ *  inspired by the ''AMoRE automata library''.
  *
  *  @author Burak Emir
  *  @version 1.0
@@ -21,7 +21,7 @@ trait Inclusion[A <: AnyRef] {
 
   val labels: Seq[A]
 
-  /** Returns true if dfa1 is included in dfa2.
+  /** Returns true if `dfa1` is included in `dfa2`.
    *
    *  @param dfa1 ...
    *  @param dfa2 ...
diff --git a/src/library/scala/util/automata/NondetWordAutom.scala b/src/library/scala/util/automata/NondetWordAutom.scala
index 05bb442e75..ece0a6c5e3 100644
--- a/src/library/scala/util/automata/NondetWordAutom.scala
+++ b/src/library/scala/util/automata/NondetWordAutom.scala
@@ -16,7 +16,7 @@ import scala.collection.{ immutable, mutable }
  *  in the delta function. Default transitions are transitions that
  *  are taken when no other transitions can be applied.
  *  All states are reachable. Accepting states are those for which
- *  the partial function 'finals' is defined.
+ *  the partial function `finals` is defined.
  */
 abstract class NondetWordAutom[T <: AnyRef] {
   import immutable.BitSet
@@ -27,22 +27,22 @@ abstract class NondetWordAutom[T <: AnyRef] {
   val delta: Array[mutable.Map[T, BitSet]]
   val default: Array[BitSet]
 
-  /** returns true if the state is final */
+  /** @return true if the state is final */
   final def isFinal(state: Int) = finals(state) > 0
 
-  /** returns tag of final state */
+  /** @return tag of final state */
   final def finalTag(state: Int) = finals(state)
 
-  /** returns true if the set of states contains at least one final state */
+  /** @return true if the set of states contains at least one final state */
   final def containsFinal(Q: BitSet): Boolean = Q exists isFinal
 
-  /** returns true if there are no accepting states */
+  /** @return true if there are no accepting states */
   final def isEmpty = (0 until nstates) forall (x => !isFinal(x))
 
-  /** returns a BitSet with the next states for given state and label */
+  /** @return a BitSet with the next states for given state and label */
   def next(q: Int, a: T): BitSet = delta(q).getOrElse(a, default(q))
 
-  /** returns a BitSet with the next states for given state and label */
+  /** @return a BitSet with the next states for given state and label */
   def next(Q: BitSet, a: T): BitSet = next(Q, next(_, a))
   def nextDefault(Q: BitSet): BitSet = next(Q, default)
 
diff --git a/src/library/scala/util/automata/WordBerrySethi.scala b/src/library/scala/util/automata/WordBerrySethi.scala
index ad15dc9ff3..4763b6fb9c 100644
--- a/src/library/scala/util/automata/WordBerrySethi.scala
+++ b/src/library/scala/util/automata/WordBerrySethi.scala
@@ -14,13 +14,12 @@ import scala.collection.{ immutable, mutable }
 import mutable.{ HashSet, HashMap }
 import scala.util.regexp.WordExp
 
-/** This class turns a regexp into a NondetWordAutom using the
- *  celebrated position automata construction (also called Berry-Sethi or
- *  Glushkov)
- *
- *  @author Burak Emir
- *  @version 1.0
- */
+/** This class turns a regular expression into a [[scala.util.automata.NondetWorkAutom]]
+  * celebrated position automata construction (also called ''Berry-Sethi'' or ''Glushkov'').
+  *
+  *  @author Burak Emir
+  *  @version 1.0
+  */
 abstract class WordBerrySethi extends BaseBerrySethi {
   override val lang: WordExp
 
@@ -33,20 +32,20 @@ abstract class WordBerrySethi extends BaseBerrySethi {
   protected var defaultq: Array[List[Int]]                 = _ // default transitions
   protected var initials: Set[Int]                         = _
 
-  /** Computes <code>first(r)</code> where the word regexp <code>r</code>.
+  /** Computes `first(r)` where the word regexp `r`.
    *
    *  @param r the regular expression
-   *  @return  the computed set <code>first(r)</code>
+   *  @return  the computed set `first(r)`
    */
   protected override def compFirst(r: RegExp): Set[Int] = r match {
     case x: Letter  => Set(x.pos)
     case _          => super.compFirst(r)
   }
 
-  /** Computes <code>last(r)</code> where the word regexp <code>r</code>.
+  /** Computes `last(r)` where the word regexp `r`.
    *
    *  @param r the regular expression
-   *  @return  the computed set <code>last(r)</code>
+   *  @return  the computed set `last(r)`
    */
   protected override def compLast(r: RegExp): Set[Int] = r match {
     case x: Letter  => Set(x.pos)
@@ -66,11 +65,11 @@ abstract class WordBerrySethi extends BaseBerrySethi {
       case _          => super.compFollow1(fol1, r)
     }
 
-  /** returns "Sethi-length" of a pattern, creating the set of position
+  /** Returns "Sethi-length" of a pattern, creating the set of position
    *  along the way
    */
 
-  /** called at the leaves of the regexp */
+  /** Called at the leaves of the regexp */
   protected def seenLabel(r: RegExp, i: Int, label: _labelT) {
     labelAt = labelAt.updated(i, label)
     this.labels += label
diff --git a/src/library/scala/util/control/Breaks.scala b/src/library/scala/util/control/Breaks.scala
index 331d30e0bb..80df8cc0bd 100644
--- a/src/library/scala/util/control/Breaks.scala
+++ b/src/library/scala/util/control/Breaks.scala
@@ -11,8 +11,9 @@
 package scala.util.control
 
 /** A class that can be instantiated for the break control abstraction.
- *  Example usage:<pre>
+ *  Example usage:
  *
+ *  <pre>
  *  val mybreaks = new Breaks
  *  import</b> mybreaks.{break, breakable}
  *
@@ -22,7 +23,7 @@ package scala.util.control
  *    }
  *  }</pre>
  *
- *  Calls to break from one instantiation of Breaks will never
+ *  Calls to break from one instantiation of `Breaks` will never
  *  target breakable objects of some other instantion.
  */
 class Breaks {
@@ -53,9 +54,9 @@ class Breaks {
     }
   }
 
-  /* Break from dynamically closest enclosing breakable block
-   * @note this might be different than the statically closest enclosing
-   * block!
+  /* Break from dynamically closest enclosing breakable block.
+   *
+   * @note This might be different than the statically closest enclosing block!
    */
   def break() { throw breakException }
 }
diff --git a/src/library/scala/util/control/ControlThrowable.scala b/src/library/scala/util/control/ControlThrowable.scala
index 122b0c937a..4d1116ba6f 100644
--- a/src/library/scala/util/control/ControlThrowable.scala
+++ b/src/library/scala/util/control/ControlThrowable.scala
@@ -10,18 +10,17 @@
 package scala.util.control
 
 /**
- * A marker trait indicating that the <code>Throwable</code> it is mixed
+ * A marker trait indicating that the `Throwable` it is mixed
  * into is intended for flow control.
  *
- * <p>Note that <code>Throwable</code> subclasses which extend this trait
- * may extend any other <code>Throwable</code> subclass (eg.
- * <code>RuntimeException</code>) and are not required to extend
- * <code>Throwable</code> directly.</p>
+ * Note that `Throwable` subclasses which extend this trait
+ * may extend any other `Throwable` subclass (eg.
+ * `RuntimeException`) and are not required to extend
+ * `Throwable` directly.
  *
- * <p>Instances of <code>Throwable</code> subclasses marked in
- * this way should not normally be caught. Where catch-all behaviour is
- * required <code>ControlThrowable</code>s should be propagated, for
- * example,</p>
+ * 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:
  *
  * <pre>
  *  import scala.util.control.ControlThrowable
diff --git a/src/library/scala/util/grammar/HedgeRHS.scala b/src/library/scala/util/grammar/HedgeRHS.scala
index 46c474a6eb..8fb3d4c5dc 100644
--- a/src/library/scala/util/grammar/HedgeRHS.scala
+++ b/src/library/scala/util/grammar/HedgeRHS.scala
@@ -12,11 +12,11 @@ package scala.util.grammar
 
 abstract class HedgeRHS
 
-/** right hand side of a hedge production, deriving a single tree */
+/** Right hand side of a hedge production, deriving a single tree. */
 case class ConsRHS(tnt: Int, hnt: Int) extends HedgeRHS
 
-/** right hand side of a hedge production, deriving any hedge */
+/** Right hand side of a hedge production, deriving any hedge. */
 case object AnyHedgeRHS extends HedgeRHS
 
-/** right hand side of a hedge production, deriving the empty hedge */
+/** Right hand side of a hedge production, deriving the empty hedge. */
 case object EmptyHedgeRHS extends HedgeRHS
diff --git a/src/library/scala/util/grammar/TreeRHS.scala b/src/library/scala/util/grammar/TreeRHS.scala
index b6e2b1a29f..ebe16b25bd 100644
--- a/src/library/scala/util/grammar/TreeRHS.scala
+++ b/src/library/scala/util/grammar/TreeRHS.scala
@@ -10,10 +10,10 @@
 
 package scala.util.grammar
 
-/** right hand side of a tree production */
+/** Right hand side of a tree production. */
 abstract class TreeRHS
 
-/** right hand side of a tree production, labelled with a letter from an alphabet */
+/** Right hand side of a tree production, labelled with a letter from an alphabet. */
 case class LabelledRHS[A](label: A, hnt: Int) extends TreeRHS
 
 case object AnyTreeRHS extends TreeRHS
diff --git a/src/library/scala/util/logging/ConsoleLogger.scala b/src/library/scala/util/logging/ConsoleLogger.scala
index 362a8e9f75..58284797b4 100644
--- a/src/library/scala/util/logging/ConsoleLogger.scala
+++ b/src/library/scala/util/logging/ConsoleLogger.scala
@@ -11,15 +11,15 @@
 package scala.util.logging
 
 /**
- *  The trait <code>ConsoleLogger</code> is mixed into a concrete class who
- *  has class <code>Logged</code> among its base classes.
+ *  The trait `ConsoleLogger` is mixed into a concrete class who
+ *  has class `Logged` among its base classes.
  *
  *  @author  Burak Emir
  *  @version 1.0
  */
 trait ConsoleLogger extends Logged {
 
-  /** logs argument to Console using <code>Console.println</code>
+  /** logs argument to Console using [[scala.Console.println]]
    */
   override def log(msg: String): Unit = Console.println(msg)
 }
diff --git a/src/library/scala/util/logging/Logged.scala b/src/library/scala/util/logging/Logged.scala
index 01757e1bfa..d23b38c569 100644
--- a/src/library/scala/util/logging/Logged.scala
+++ b/src/library/scala/util/logging/Logged.scala
@@ -9,17 +9,19 @@
 package scala.util.logging
 
 /** Mixing in Logged indicates that a class provides support for logging.
- *  For instance:
-{{{
-  // The developer of the library writes:
-  class MyClass extends Logged {
-    // do stuff, call log
-  }
-  // The user of the library instantiates:
-  val x = new MyClass() with ConsoleLogger
-}}}
- * and the logging is sent to the [[scala.util.logging.ConsoleLogger]] object.
- */
+  *
+  * For instance:
+  * {{{
+  * // The developer of the library writes:
+  * class MyClass extends Logged {
+  *   // do stuff, call log
+  * }
+  *
+  * // The user of the library instantiates:
+  * val x = new MyClass() with ConsoleLogger
+  * }}}
+  * and the logging is sent to the [[scala.util.logging.ConsoleLogger]] object.
+  */
 trait Logged {
   /** This method should log the message given as argument somewhere
    *  as a side-effect.
diff --git a/src/library/scala/util/matching/Regex.scala b/src/library/scala/util/matching/Regex.scala
index 663900dd0a..9ee2b37bbf 100644
--- a/src/library/scala/util/matching/Regex.scala
+++ b/src/library/scala/util/matching/Regex.scala
@@ -15,11 +15,9 @@ import java.util.regex.{ Pattern, Matcher }
 /** This class provides methods for creating and using regular expressions.
  *  It is based on the regular expressions of the JDK since 1.4.
  *
- *  <p>
- *  You can use special pattern syntax construct <code>(?idmsux-idmsux)</code> to switch
- *  various regex compilation options like <code>CASE_INSENSITIVE</code> or <code>UNICODE_CASE</code>.
- *  See <code>java.util.regex.Pattern</code> javadoc for details.
- *  </p>
+ *  You can use special pattern syntax construct `(?idmsux-idmsux)` to switch
+ *  various regex compilation options like `CASE_INSENSITIVE` or `UNICODE_CASE`.
+ *  See [[java.util.regex.Pattern]] for details.
  *
  *  @author  Thibaud Hottelier
  *  @author  Philipp Haller
@@ -37,8 +35,7 @@ class Regex(regex: String, groupNames: String*) extends Serializable {
   /** The compiled pattern */
   val pattern = Pattern.compile(regex)
 
-  /** Tries to match target (whole match) and returns
-   *  the matches.
+  /** Tries to match target (whole match) and returns the matches.
    *
    *  @param target The string to match
    *  @return       The matches
@@ -135,8 +132,7 @@ class Regex(regex: String, groupNames: String*) extends Serializable {
     m.replaceFirst(replacement)
   }
 
-  /** Splits the provided character sequence around matches of this
-   *  regexp.
+  /** Splits the provided character sequence around matches of this regexp.
    *
    *  @param toSplit The character sequence to split
    *  @return        The array of strings computed by splitting the
@@ -150,11 +146,13 @@ class Regex(regex: String, groupNames: String*) extends Serializable {
 }
 
 /** This object defines inner classes that describe
- *  regex matches. The class hierarchy is as follows.
+ *  regex matches. The class hierarchy is as follows:
  *
+ *  {{{
  *            MatchData
- *              |      \
- *      MatchIterator  Match
+ *            /      \
+ *   MatchIterator  Match
+ *  }}}
  */
 object Regex {
 
@@ -175,25 +173,24 @@ object Regex {
     /** The index of the first matched character, or -1 if nothing was matched */
     def start: Int
 
-    /** The index of the first matched character in group <code>i</code>,
+    /** The index of the first matched character in group `i`,
      *  or -1 if nothing was matched for that group */
     def start(i: Int): Int
 
     /** The index of the last matched character, or -1 if nothing was matched */
     def end: Int
 
-    /** The index following the last matched character in group <code>i</code>,
+    /** The index following the last matched character in group `i`,
      *  or -1 if nothing was matched for that group */
     def end(i: Int): Int
 
-    /** The matched string,
-     *  of <code>null</code> if nothing was matched */
+    /** The matched string, or `null` if nothing was matched */
     def matched: String =
       if (start >= 0) source.subSequence(start, end).toString
       else null
 
-    /** The matched string in group <code>i</code>,
-     *  or <code>null</code> if nothing was matched */
+    /** The matched string in group `i`,
+     *  or `null` if nothing was matched */
     def group(i: Int): String =
       if (start(i) >= 0) source.subSequence(start(i), end(i)).toString
       else null
@@ -202,25 +199,25 @@ object Regex {
     def subgroups: List[String] = (1 to groupCount).toList map group
 
     /** The char sequence before first character of match,
-     *  or <code>null</code> if nothing was matched */
+     *  or `null` if nothing was matched */
     def before: java.lang.CharSequence =
       if (start >= 0) source.subSequence(0, start)
       else null
 
-    /** The char sequence before first character of match in group <code>i</code>,
-     *  or <code>null</code> if nothing was matched for that group  */
+    /** The char sequence before first character of match in group `i`,
+     *  or `null` if nothing was matched for that group  */
     def before(i: Int): java.lang.CharSequence =
       if (start(i) >= 0) source.subSequence(0, start(i))
       else null
 
     /** Returns char sequence after last character of match,
-     *  or <code>null</code> if nothing was matched */
+     *  or `null` if nothing was matched */
     def after: java.lang.CharSequence =
       if (end >= 0) source.subSequence(end, source.length)
       else null
 
-    /** The char sequence after last character of match in group <code>i</code>,
-     *  or <code>null</code> if nothing was matched for that group  */
+    /** The char sequence after last character of match in group `i`,
+     *  or `null` if nothing was matched for that group  */
     def after(i: Int): java.lang.CharSequence =
       if (end(i) >= 0) source.subSequence(end(i), source.length)
       else null
@@ -231,15 +228,14 @@ object Regex {
      *
      *  @param id The group name
      *  @return   The requested group
-     *  @throws   <code>NoSuchElementException</code> if the requested
-     *            group name is not defined
+     *  @throws   NoSuchElementException if the requested group name is not defined
      */
     def group(id: String): String = nameToIndex.get(id) match {
       case None => throw new NoSuchElementException("group name "+id+" not defined")
       case Some(index) => group(index)
     }
 
-    /** The matched string; equivalent to <code>matched.toString</code> */
+    /** The matched string; equivalent to `matched.toString` */
     override def toString = matched
 
   }
@@ -264,10 +260,10 @@ object Regex {
     private lazy val ends: Array[Int] =
       ((0 to groupCount) map matcher.end).toArray
 
-    /** The index of the first matched character in group <code>i</code> */
+    /** The index of the first matched character in group `i` */
     def start(i: Int) = starts(i)
 
-    /** The index following the last matched character in group <code>i</code> */
+    /** The index following the last matched character in group `i` */
     def end(i: Int) = ends(i)
 
     /** The match itself with matcher-dependent lazy vals forced,
@@ -312,13 +308,13 @@ object Regex {
     /** The index of the first matched character */
     def start: Int = matcher.start
 
-    /** The index of the first matched character in group <code>i</code> */
+    /** The index of the first matched character in group `i` */
     def start(i: Int): Int = matcher.start(i)
 
     /** The index of the last matched character */
     def end: Int = matcher.end
 
-    /** The index following the last matched character in group <code>i</code> */
+    /** The index following the last matched character in group `i` */
     def end(i: Int): Int = matcher.end(i)
 
     /** The number of subgroups */
diff --git a/src/library/scala/util/parsing/ast/AbstractSyntax.scala b/src/library/scala/util/parsing/ast/AbstractSyntax.scala
index f0f0ec425f..220643a0d7 100644
--- a/src/library/scala/util/parsing/ast/AbstractSyntax.scala
+++ b/src/library/scala/util/parsing/ast/AbstractSyntax.scala
@@ -19,7 +19,7 @@ trait AbstractSyntax {
    */
   trait Element extends Positional
 
-  /** The base class for elements in the AST that represent names {@see Binders}.
+  /** The base class for elements in the AST that represent names [[scala.util.parsing.ast.Binders]].
    */
   trait NameElement extends Element {
     def name: String
diff --git a/src/library/scala/util/parsing/ast/Binders.scala b/src/library/scala/util/parsing/ast/Binders.scala
index 2ecb702446..c7b527984d 100644
--- a/src/library/scala/util/parsing/ast/Binders.scala
+++ b/src/library/scala/util/parsing/ast/Binders.scala
@@ -15,14 +15,10 @@ import scala.collection.mutable.Map
   // TODO: avoid clashes when substituting
   // TODO: check binders in the same scope are distinct
 
-/** <p>
- *    This trait provides the core Scrap-Your-Boilerplate abstractions as
- *    well as implementations for common datatypes.
- *  </p>
- *  <p>
- *    Based on Ralph Laemmel's <a target="_top"
- *    href="http://homepages.cwi.nl/~ralf/publications.html">SYB papers</a>.
- *  </p>
+/** This trait provides the core Scrap-Your-Boilerplate abstractions as
+ *  well as implementations for common datatypes.
+ *
+ *  Based on Ralph Laemmel's [[http://homepages.cwi.nl/~ralf/publications.html SYB papers]].
  *
  * @author Adriaan Moors
  */
@@ -58,57 +54,52 @@ trait Mappable {
     }
 }
 
-/** <p>
- *    This component provides functionality for enforcing variable binding
- *    during parse-time.
- *  </p>
- *  <p>
- *   When parsing simple languages, like Featherweight Scala, these parser
- *   combinators will fully enforce the binding discipline. When names are
- *   allowed to be left unqualified, these mechanisms would have to be
- *   complemented by an extra phase that resolves names that couldn't be
- *   resolved using the naive binding rules. (Maybe some machinery to
- *   model `implicit` binders (e.g., `this` and imported qualifiers)
- *   and selection on a binder will suffice?)
- * </p>
+/** This component provides functionality for enforcing variable binding
+ *  during parse-time.
+ *
+ *  When parsing simple languages, like Featherweight Scala, these parser
+ *  combinators will fully enforce the binding discipline. When names are
+ *  allowed to be left unqualified, these mechanisms would have to be
+ *  complemented by an extra phase that resolves names that couldn't be
+ *  resolved using the naive binding rules. (Maybe some machinery to
+ *  model `implicit` binders (e.g., `this` and imported qualifiers)
+ *  and selection on a binder will suffice?)
  *
  * @author Adriaan Moors
  */
 trait Binders extends AbstractSyntax with Mappable {
   /** A `Scope` keeps track of one or more syntactic elements that represent bound names.
-   * The elements it contains share the same scope and must all be distinct, as determined by `==`.
+   *  The elements it contains share the same scope and must all be distinct, as determined by `==`.
    *
-   * A `NameElement` `n` in the AST that is conceptually bound by a `Scope` `s`, is replaced by a
-   * `BoundElement(n, s)'. (For example, in `val x:Int=x+1', the first `x` is modelled by a
-   * Scope `s` that contains `x` and the second `x` is represented by a `BoundElement(`x`, s)')
-   * The term (`x+1`) in scope of the Scope becomes an `UnderBinder(s, `x+1`).
+   *  A `NameElement` `n` in the AST that is conceptually bound by a `Scope` `s`, is replaced by a
+   *  `BoundElement(n, s)`. (For example, in `val x:Int=x+1`, the first `x` is modelled by a
+   *  Scope `s` that contains `x` and the second `x` is represented by a `BoundElement(x, s)`)
+   *  The term (`x+1`) in scope of the Scope becomes an `UnderBinder(s, x+1)`.
    *
-   * A `NameElement` `n` is bound by a `Scope` `s` if it is wrapped as a `BoundElement(`n`, s)', and
-   * `s` has a binder element that is semantically equal (`equals` or `==`) to `n`.
+   *  A `NameElement` `n` is bound by a `Scope` `s` if it is wrapped as a `BoundElement(n, s)`, and
+   *  `s` has a binder element that is semantically equal (`equals` or `==`) to `n`.
    *
-   * A `Scope` is represented textually by its list of binder elements, followed by the scope's `id`.
-   * For example: `[x, y]!1` represents the scope with `id` `1` and binder elements `x` and `y`.
-   * (`id` is solely used for this textual representation.)
+   *  A `Scope` is represented textually by its list of binder elements, followed by the scope's `id`.
+   *  For example: `[x, y]!1` represents the scope with `id` `1` and binder elements `x` and `y`.
+   *  (`id` is solely used for this textual representation.)
    */
   class Scope[binderType <: NameElement] extends Iterable[binderType]{
     private val substitution: Map[binderType, Element] =
       new scala.collection.mutable.LinkedHashMap[binderType, Element] // a LinkedHashMap is ordered by insertion order -- important!
 
-    /** Returns a unique number identifying this Scope (only used for representation purposes).
-     */
+    /** Returns a unique number identifying this Scope (only used for representation purposes). */
     val id: Int = _Binder.genId
 
     /** Returns the binders in this scope.
-     * For a typical let-binding, this is just the variable name. For an argument list to a method body,
-     * there is one binder per formal argument.
+     *  For a typical let-binding, this is just the variable name. For an argument list to a method body,
+     *  there is one binder per formal argument.
      */
     def iterator = substitution.keysIterator
 
-    /** Return the `i`th binder in this scope.*/
+    /** Return the `i`th binder in this scope. */
     def apply(i: Int): binderType = this.iterator.toList(i)
 
-    /** Returns true if this container has a binder equal (==) to `b`
-     */
+    /** Returns true if this container has a binder equal (as determined by `==`) to `b`. */
     def binds(b: binderType): Boolean = substitution.contains(b)
 
     def indexFor(b: binderType): Option[Int] = {
@@ -123,53 +114,53 @@ trait Binders extends AbstractSyntax with Mappable {
       None
     }
 
-    /** Adds a new binder.
-     * (e.g. the variable name in a local variable declaration)
+    /** Adds a new binder, for example the variable name in a local variable declaration.
      *
      * @param b a new binder that is distinct from the existing binders in this scope,
-     *           and shares their conceptual scope. canAddBinder(b)` must hold.`
+     *           and shares their conceptual scope. `canAddBinder(b)` must hold.
      * @return `binds(b)` and `getElementFor(b) eq b` will hold.
      */
     def addBinder(b: binderType) { substitution += Pair(b, b) }
 
+    // TODO: strengthen this condition so that no binders may be added after this scope has been
+    //       linked to its `UnderBinder` (i.e., while parsing, BoundElements may be added to the Scope
+    //       associated to the UnderBinder, but after that, no changes are allowed, except for substitution)?
     /** `canAddElement` indicates whether `b` may be added to this scope.
      *
-     * TODO: strengthen this condition so that no binders may be added after this scope has been
-     *       linked to its `UnderBinder` (i.e., while parsing, BoundElements may be added to the Scope
-     *       associated to the UnderBinder, but after that, no changes are allowed, except for substitution)?
      *
      * @return true if `b` had not been added yet
      */
     def canAddBinder(b: binderType): Boolean = !binds(b)
 
-    /** ``Replaces'' the bound occurrences of a contained binder by their new value.
-     * The bound occurrences of `b` are not actually replaced; the scope keeps track
-     * of a substitution that maps every binder to its current value. Since a `BoundElement` is
-     * a proxy for the element it is bound to by its binder, `substitute` may thus be thought of
-     * as replacing all the bound occurrences of the given binder `b` by their new value `value`.
+    /** ''Replaces'' the bound occurrences of a contained binder by their new value.
+     *  The bound occurrences of `b` are not actually replaced; the scope keeps track
+     *  of a substitution that maps every binder to its current value. Since a `BoundElement` is
+     *  a proxy for the element it is bound to by its binder, `substitute` may thus be thought of
+     *  as replacing all the bound occurrences of the given binder `b` by their new value `value`.
      *
-     * @param b    the binder whose bound occurrences should be given a new value. `binds(b)` must hold.
-     * @param value the new value for the bound occurrences of `b`
-     * @return `getElementFor(b) eq value` will hold.
+     *  @param b    the binder whose bound occurrences should be given a new value. `binds(b)` must hold.
+     *  @param value the new value for the bound occurrences of `b`
+     *  @return `getElementFor(b) eq value` will hold.
      */
     def substitute(b: binderType, value: Element): Unit = substitution(b) = value
 
     /** Returns the current value for the bound occurrences of `b`.
      *
-     * @param b the contained binder whose current value should be returned `binds(b)` must hold.
+     *  @param b the contained binder whose current value should be returned `binds(b)` must hold.
      */
     def getElementFor(b: binderType): Element = substitution(b)
 
     override def toString: String =  this.iterator.toList.mkString("[",", ","]")+"!"+id // TODO show substitution?
 
-    /** Returns a list of strings that represent the binder elements, each tagged with this scope's id.*/
+    /** Returns a list of strings that represent the binder elements, each tagged with this scope's id. */
     def bindersToString: List[String] = (for(b <- this.iterator) yield b+"!"+id).toList
 
-    /** Return a new inheriting scope that won't check whether binding is respected until the scope is left (so as to support forward references) **/
+    /** Return a new inheriting scope that won't check whether binding is respected until the scope is left (so as to support forward references). */
     def allowForwardRef: Scope[binderType] = this // TODO
 
     /** Return a nested scope -- binders entered into it won't be visible in this scope, but if this scope allows forward references,
-      * the binding in the returned scope also does, and thus the check that all variables are bound is deferred until this scope is left  **/
+     *  the binding in the returned scope also does, and thus the check that all variables are bound is deferred until this scope is left.
+     */
     def nested: Scope[binderType] = this // TODO
 
     def onEnter() {}
@@ -184,17 +175,17 @@ trait Binders extends AbstractSyntax with Mappable {
   }
 
   /** A `BoundElement` is bound in a certain scope `scope`, which keeps track of the actual element that
-   * `el` stands for.
+   *  `el` stands for.
    *
-   * A `BoundElement` is represented textually by its bound element, followed by its scope's `id`.
-   * For example: `x@1` represents the variable `x` that is bound in the scope with `id` `1`.
+   *  A `BoundElement` is represented textually by its bound element, followed by its scope's `id`.
+   *  For example: `x@1` represents the variable `x` that is bound in the scope with `id` `1`.
    *
-   * @note `scope.binds(el)` holds before and after.
+   *  @note `scope.binds(el)` holds before and after.
    */
   case class BoundElement[boundElement <: NameElement](el: boundElement, scope: Scope[boundElement]) extends NameElement with Proxy with BindingSensitive {
     /** Returns the element this `BoundElement` stands for.
-     * The `Proxy` trait ensures `equals`, `hashCode` and `toString` are forwarded to
-     * the result of this method.
+     *  The `Proxy` trait ensures `equals`, `hashCode` and `toString` are forwarded to
+     *  the result of this method.
      */
     def self: Element = scope.getElementFor(el)
 
@@ -206,8 +197,7 @@ trait Binders extends AbstractSyntax with Mappable {
     def alpha_==[t <: NameElement](other: BoundElement[t]): Boolean = scope.indexFor(el) == other.scope.indexFor(other.el)
   }
 
-  /** A variable that escaped its scope (i.e., a free variable) -- we don't deal very well with these yet
-   */
+  /** A variable that escaped its scope (i.e., a free variable) -- we don't deal very well with these yet. */
   class UnboundElement[N <: NameElement](private val el: N) extends NameElement {
     def name = el.name+"@??"
   }
@@ -216,20 +206,22 @@ trait Binders extends AbstractSyntax with Mappable {
   // if we knew a more specific type for the element that the bound element represents, this could make sense
   // implicit def BoundElementProxy[t <: NameElement](e: BoundElement[t]): Element = e.self
 
-  /** Represents an element with variables that are bound in a certain scope.
-   */
+  /** Represents an element with variables that are bound in a certain scope. */
   class UnderBinder[binderType  <: NameElement, elementT <% Mappable[elementT]](val scope: Scope[binderType], private[Binders] val element: elementT) extends Element with BindingSensitive {
     override def toString: String = "(" + scope.toString + ") in { "+element.toString+" }"
 
     /** Alpha-equivalence -- TODO
-     * Returns true if the `element` of the `other` `UnderBinder` is equal to this `element` up to alpha-conversion.
+     *  Returns true if the `element` of the `other` `UnderBinder` is equal to this `element` up to alpha-conversion.
      *
-     * That is, regular equality is used for all elements but `BoundElement`s: such an element is
-     * equal to a `BoundElement` in `other` if their binders are equal. Binders are equal if they
-     * are at the same index in their respective scope.
+     *  That is, regular equality is used for all elements but `BoundElement`s: such an element is
+     *  equal to a `BoundElement` in `other` if their binders are equal. Binders are equal if they
+     *  are at the same index in their respective scope.
      *
-     * Example: UnderBinder([x, y]!1, x@1) alpha_== UnderBinder([a, b]!2, a@2)
-     *          ! (UnderBinder([x, y]!1, y@1) alpha_== UnderBinder([a, b]!2, a@2))
+     *  Example:
+     *  {{{
+     *    UnderBinder([x, y]!1, x@1) alpha_== UnderBinder([a, b]!2, a@2)
+     *    ! (UnderBinder([x, y]!1, y@1) alpha_== UnderBinder([a, b]!2, a@2))
+     *  }}}
      */
     /*def alpha_==[bt <: binderType, st <: elementT](other: UnderBinder[bt, st]): Boolean = {
        var result = true
@@ -259,7 +251,7 @@ trait Binders extends AbstractSyntax with Mappable {
     def extract: elementT = cloneElementNoBoundElements
     def extract(subst: scala.collection.immutable.Map[NameElement, NameElement]): elementT = cloneElementWithSubst(subst)
 
-    /** Get a string representation of element, normally we don't allow direct access to element, but just getting a string representation is ok*/
+    /** Get a string representation of element, normally we don't allow direct access to element, but just getting a string representation is ok. */
     def elementToString: String = element.toString
   }
 
@@ -291,12 +283,12 @@ trait Binders extends AbstractSyntax with Mappable {
     def unit[bt <: NameElement, elementT <% Mappable[elementT]](x: elementT) = UnderBinder(new Scope[bt](), x)
   }
 
-  /** If a list of `UnderBinder`s all have the same scope, they can be turned in to an UnderBinder
-   * containing a list of the elements in the original `UnderBinder`.
+  /** If a list of `UnderBinder`s all have the same scope, they can be turned in to an `UnderBinder`
+   *  containing a list of the elements in the original `UnderBinder`.
    *
-   * The name `sequence` comes from the fact that this method's type is equal to the type of monadic sequence.
+   *  The name `sequence` comes from the fact that this method's type is equal to the type of monadic sequence.
    *
-   * @note `!orig.isEmpty` implies `orig.forall(ub => ub.scope eq orig(0).scope)`
+   *  @note `!orig.isEmpty` implies `orig.forall(ub => ub.scope eq orig(0).scope)`
    *
    */
   def sequence[bt <: NameElement, st <% Mappable[st]](orig: List[UnderBinder[bt, st]]): UnderBinder[bt, List[st]] =
@@ -307,13 +299,13 @@ trait Binders extends AbstractSyntax with Mappable {
   def unsequence[bt <: NameElement, st <% Mappable[st]](orig: UnderBinder[bt, List[st]]): List[UnderBinder[bt, st]] =
     orig.element.map(sc => UnderBinder(orig.scope, sc))
 
+  //TODO: more documentation
   /** An environment that maps a `NameElement` to the scope in which it is bound.
-   * This can be used to model scoping during parsing.
-   *
-   * (This class is similar to Burak's ECOOP paper on pattern matching, except that we use `==`
-   *  instead of `eq`, thus types can't be unified in general)
+   *  This can be used to model scoping during parsing.
    *
-   * TODO: more documentation
+   *  @note This class uses similar techniques as described by ''Burak Emir'' in
+   *        [[http://library.epfl.ch/theses/?nr=3899 Object-oriented pattern matching]],
+   *        but uses `==` instead of `eq`, thus types can't be unified in general.
    */
   abstract class BinderEnv {
     def apply[A <: NameElement](v: A): Option[Scope[A]]
@@ -328,17 +320,16 @@ trait Binders extends AbstractSyntax with Mappable {
     def apply[A <: NameElement](v: A): Option[Scope[A]] = None
   }
 
+  // TODO: move this to some utility object higher in the scala hierarchy?
   /** Returns a given result, but executes the supplied closure before returning.
-   * (The effect of this closure does not influence the returned value.)
+   *  (The effect of this closure does not influence the returned value.)
    *
-   * TODO: move this to some utility object higher in the scala hierarchy?
-   *
-   * @param result the result to be returned
-   * @param block  code to be executed, purely for its side-effects
+   *  @param result the result to be returned
+   *  @param block  code to be executed, purely for its side-effects
    */
   trait ReturnAndDo[T]{
     def andDo(block: => Unit): T
-  } // gotta love Smalltalk syntax :-)
+  }
 
   def return_[T](result: T): ReturnAndDo[T] =
     new ReturnAndDo[T] {
diff --git a/src/library/scala/util/parsing/combinator/ImplicitConversions.scala b/src/library/scala/util/parsing/combinator/ImplicitConversions.scala
index 32261c102e..e993628e88 100644
--- a/src/library/scala/util/parsing/combinator/ImplicitConversions.scala
+++ b/src/library/scala/util/parsing/combinator/ImplicitConversions.scala
@@ -9,19 +9,22 @@
 
 package scala.util.parsing.combinator
 
-/** This object contains implicit conversions that come in handy when using the `^^` combinator
- * {@see Parsers} to construct an AST from the concrete syntax.
- *<p>
+/** This object contains implicit conversions that come in handy when using the `^^` combinator.
+ *
+ *  Refer to [[scala.util.parsing.combinator.Parsers]] to construct an AST from the concrete syntax.
+ *
  * The reason for this is that the sequential composition combinator (`~`) combines its constituents
  * into a ~. When several `~`s are combined, this results in nested `~`s (to the left).
- * The `flatten*` coercions makes it easy to apply an `n`-argument function to a nested ~ of
- * depth (`n-1`)</p>
- *<p>
- * The `headOptionTailToFunList` converts a function that takes a List[A] to a function that
- * accepts a ~[A, Option[List[A]]] (this happens when, e.g., parsing something of the following
- * shape: p ~ opt("." ~ repsep(p, ".")) -- where `p` is a parser that yields an A)</p>
+ * The `flatten*` coercions makes it easy to apply an `n`-argument function to a nested `~` of
+ * depth `n-1`
+ *
+ * The `headOptionTailToFunList` converts a function that takes a `List[A]` to a function that
+ * accepts a `~[A, Option[List[A]]]` (this happens when parsing something of the following
+ * shape: `p ~ opt("." ~ repsep(p, "."))` -- where `p` is a parser that yields an `A`).
  *
- * @author Martin Odersky, Iulian Dragos, Adriaan Moors
+ * @author Martin Odersky
+ * @author Iulian Dragos
+ * @author Adriaan Moors
  */
 trait ImplicitConversions { self: Parsers =>
   implicit def flatten2[A, B, C]         (f: (A, B) => C) =
diff --git a/src/library/scala/util/parsing/combinator/PackratParsers.scala b/src/library/scala/util/parsing/combinator/PackratParsers.scala
index f53b998e07..3f09ae506d 100644
--- a/src/library/scala/util/parsing/combinator/PackratParsers.scala
+++ b/src/library/scala/util/parsing/combinator/PackratParsers.scala
@@ -14,44 +14,36 @@ import scala.util.parsing.input.{ Reader, Position }
 import scala.collection.mutable
 
 /**
- *  <p>
- *    <code>PackratParsers</code> is a component that extends the parser combinators
- *    provided by <a href="Parsers.html"><code>Parsers</code></a> with a memoization facility
- *    (``Packrat Parsing'').
- *  </p>
- *  <p>
- *    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.
- *  </p>
- *  <p>
- *    Using <code>PackratParsers</code> is very similar to using <code>Parsers</code>:
- *  <ul>
- *    <li> any class/trait that extends <code>Parsers</code> (directly or through a subclass) can
- *         mix in <code>PackratParsers</code>. Example:
- *         <code>object MyGrammar extends StandardTokenParsers with PackratParsers </code>
- *    <li> each grammar production previously declared as a <code>def</code> without formal parameters
- *         becomes a <code>lazy val</code>, and its type is changed from <code>Parser[Elem]</code>
- *         to <code>PackratParser[Elem]</code>. So, for example, <code>def production: Parser[Int] = {...}</code>
- *         becomes <code>lazy val production: PackratParser[Int] = {...}</code>
- *    <li> Important: using <code>PackratParser</code>s is not an ``all or nothing'' decision. They
- *         can be free mixed with regular <code>Parser</code>s in a single grammar.
- *  </ul>
- *  </p>
- *  <p>
- *    Cached parse results are attached to the <i>input</i>, not the grammar.
- *    Therefore, <code>PackratsParser</code>s require a <code>PackratReader</code> as input, which
- *    adds memoization to an underlying <code>Reader</code>. Programmers can create <code>PackratReader</code>
- *    objects either manually, as in <code>production(new PackratReader(new lexical.Scanner("input")))</code>,
- *    but the common way should be to rely on the combinator <code>phrase</code> to wrap a given
- *    input with a <code>PackratReader</code> if the input is not one itself.
- *  </p>
+ *  `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,
+ *  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.
+ *     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.
  *
  * @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
  *
  * @since 2.8
- * @author Manohar Jonnalagedda, Tiark Rompf
+ * @author Manohar Jonnalagedda
+ * @author Tiark Rompf
  */
 
 trait PackratParsers extends Parsers {
@@ -59,7 +51,7 @@ trait PackratParsers extends Parsers {
   //type Input = PackratReader[Elem]
 
   /**
-   * A specialized <code>Reader</code> class that wraps an underlying <code>Reader</code>
+   * 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 =>
@@ -67,7 +59,6 @@ trait PackratParsers extends Parsers {
     /*
      * caching of intermediate parse results and information about recursion
      */
-
     private[PackratParsers] val cache = mutable.HashMap.empty[(Parser[_], Position), MemoEntry[_]]
 
     private[PackratParsers] def getFromCache[T](p: Parser[T]): Option[MemoEntry[T]] = {
@@ -102,13 +93,10 @@ trait PackratParsers extends Parsers {
 
 
   /**
-   *  <p>
-   *    A parser generator delimiting whole phrases (i.e. programs).
-   *  </p>
-   *  <p>
-   *    Overridden to make sure any input passed to the argument parser
-   *    is wrapped in a <code>PackratReader</code>.
-   *  </p>
+   *  A parser generator delimiting whole phrases (i.e. programs).
+   *
+   *  Overridden to make sure any input passed to the argument parser
+   *  is wrapped in a `PackratReader`.
    */
   override def phrase[T](p: Parser[T]) = {
     val q = super.phrase(p)
@@ -162,7 +150,6 @@ trait PackratParsers extends Parsers {
    * In the former case, it makes sure that rules involved in the recursion are evaluated.
    * It also prevents non-involved rules from getting evaluated further
    */
-
   private def recall(p: super.Parser[_], in: PackratReader[Elem]): Option[MemoEntry[_]] = {
     val cached = in.getFromCache(p)
     val head = in.recursionHeads.get(in.pos)
@@ -237,7 +224,7 @@ to update each parser involved in the recursion.
 
   /**
    * Explicitly convert a given parser to a memoizing packrat parser.
-   * In most cases, client code should avoid calling <code>memo</code> directly
+   * In most cases, client code should avoid calling `memo` directly
    * and rely on implicit conversion instead.
    */
   def memo[T](p: super.Parser[T]): PackratParser[T] = {
diff --git a/src/library/scala/util/parsing/combinator/Parsers.scala b/src/library/scala/util/parsing/combinator/Parsers.scala
index b0760f42ae..e9155afc55 100644
--- a/src/library/scala/util/parsing/combinator/Parsers.scala
+++ b/src/library/scala/util/parsing/combinator/Parsers.scala
@@ -16,69 +16,61 @@ import annotation.migration
 
 // TODO: better error handling (labelling like parsec's <?>)
 
-/** <p>
- *    <code>Parsers</code> is a component that <i>provides</i> generic
- *    parser combinators.
- *  </p>
- *  <p>
- *    It <i>requires</i> the type of the elements these parsers should parse
- *    (each parser is polymorphic in the type of result it produces).
- *  </p>
- *  <p>
- *    There are two aspects to the result of a parser: (1) success or failure,
- *    and (2) the result. A <code>Parser[T]</code> provides both kinds of
- *    information.
- *  </p>
- *  <p>
- *    The term ``parser combinator'' refers to the fact that these parsers
- *    are constructed from primitive parsers and composition operators, such
- *    as sequencing, alternation, optionality, repetition, lifting, and so on.
- *  </p>
- *  <p>
- *    A ``primitive parser'' is a parser that accepts or rejects a single
- *    piece of input, based on a certain criterion, such as whether the
- *    input...
- *  </p><ul>
- *    <li> is equal to some given object, </li>
- *    <li> satisfies a certain predicate, </li>
- *    <li> is in the domain of a given partial function,.... </li>
- *  </ul>
- *  <p>
- *    Even more primitive parsers always produce the same result, irrespective
- *    of the input.
- *  </p>
+/** `Parsers` is a component that ''provides'' generic parser combinators.
  *
- * @author Martin Odersky, Iulian Dragos, Adriaan Moors
+ *  It ''requires'' the type of the elements these parsers should parse
+ *  (each parser is polymorphic in the type of result it produces).
+ *
+ *  There are two aspects to the result of a parser:
+ *  1. success or failure
+ *  2. the result.
+ *  A `Parser[T]` provides both kinds of information.
+ *
+ *  The term ''parser combinator'' refers to the fact that these parsers
+ *  are constructed from primitive parsers and composition operators, such
+ *  as sequencing, alternation, optionality, repetition, lifting, and so on.
+ *
+ *  A ''primitive parser'' is a parser that accepts or rejects a single
+ *  piece of input, based on a certain criterion, such as whether the
+ *  input...
+ *  - is equal to some given object,
+ *  - satisfies a certain predicate,
+ *  - is in the domain of a given partial function, ...
+ *
+ *  Even more primitive parsers always produce the same result, irrespective of the input.
+ *
+ * @author Martin Odersky
+ * @author Iulian Dragos
+ * @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''.
-   * Nonetheless, the same principles apply, regardless of the input type.) */
+   *  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. */
+   *  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). */
+   *  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
+    /** Functional composition of ParseResults.
      *
      * @param `f` the function to be lifted over this result
      * @return `f` applied to the result of this `ParseResult`, packaged up as a new `ParseResult`
      */
     def map[U](f: T => U): ParseResult[U]
 
-    /** Partial functional composition of ParseResults
+    /** Partial functional composition of ParseResults.
      *
      * @param `f` the partial function to be lifted over this result
      * @param error a function that takes the same argument as `f` and produces an error message
      *        to explain why `f` wasn't applicable (it is called when this is the case)
-     * @return <i>if `f` f is defined at the result in this `ParseResult`,</i>
-     *         `f` applied to the result of this `ParseResult`, packaged up as a new `ParseResult`.
-     *         If `f` is not defined, `Failure`.
+     * @return if `f` f is defined at the result in this `ParseResult`, `f` applied to the result
+     *         of this `ParseResult`, packaged up as a new `ParseResult`. If `f` is not defined, `Failure`.
      */
     def mapPartial[U](f: PartialFunction[T, U], error: T => String): ParseResult[U]
 
@@ -88,7 +80,7 @@ trait Parsers {
 
     def isEmpty = !successful
 
-    /** Returns the embedded result */
+    /** Returns the embedded result. */
     def get: T
 
     def getOrElse[B >: T](default: => B): B =
@@ -117,7 +109,7 @@ trait Parsers {
 
     def get: T = result
 
-    /** The toString method of a Success */
+    /** The toString method of a Success. */
     override def toString = "["+next.pos+"] parsed: "+result
 
     val successful = true
@@ -125,8 +117,7 @@ trait Parsers {
 
   var lastNoSuccess: NoSuccess = null
 
-  /** A common super-class for unsuccessful parse results
-   */
+  /** A common super-class for unsuccessful parse results. */
   sealed abstract class NoSuccess(val msg: String, override val next: Input) extends ParseResult[Nothing] { // when we don't care about the difference between Failure and Error
     val successful = false
     if (!(lastNoSuccess != null && next.pos < lastNoSuccess.next.pos))
@@ -140,8 +131,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)
@@ -151,13 +141,13 @@ trait Parsers {
   }
 
   /** The failure case of ParseResult: contains an error-message and the remaining input.
-   * Parsing will back-track when a failure occurs.
+   *  Parsing will back-track when a failure occurs.
    *
    *  @param msg    An error message string describing the failure.
    *  @param next   The parser's unconsumed input at the point where the failure occurred.
    */
   case class Failure(override val msg: String, override val next: Input) extends NoSuccess(msg, next) {
-    /** The toString method of a Failure yields an error message */
+    /** The toString method of a Failure yields an error message. */
     override def toString = "["+next.pos+"] failure: "+msg+"\n\n"+next.pos.longString
 
     def append[U >: Nothing](a: => ParseResult[U]): ParseResult[U] = { val alt = a; alt match {
@@ -167,13 +157,13 @@ 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`
+   *  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.
    */
   case class Error(override val msg: String, override val next: Input) extends NoSuccess(msg, next) {
-    /** The toString method of an Error yields an error message */
+    /** The toString method of an Error yields an error message. */
     override def toString = "["+next.pos+"] error: "+msg+"\n\n"+next.pos.longString
     def append[U >: Nothing](a: => ParseResult[U]): ParseResult[U] = this
   }
@@ -186,15 +176,14 @@ trait Parsers {
     = new Parser[T] with OnceParser[T] { def apply(in: Input) = f(in) }
 
   /** The root class of parsers.
-   *  Parsers are functions from the Input type to ParseResult
+   *  Parsers are functions from the Input type to ParseResult.
    */
   abstract class Parser[+T] extends (Input => ParseResult[T]) {
     private var name: String = ""
     def named(n: String): this.type = {name=n; this}
     override def toString() = "Parser ("+ name +")"
 
-    /** An unspecified method that defines the behaviour of this parser.
-     */
+    /** An unspecified method that defines the behaviour of this parser. */
     def apply(in: Input): ParseResult[T]
 
     def flatMap[U](f: T => Parser[U]): Parser[U]
@@ -246,7 +235,7 @@ trait Parsers {
      * <p> `p <~ q` succeeds if `p` succeeds and `q` succeeds on the input
      *           left over by `p`.</p>
      *
-     * '''Note:''' <~ has lower operator precedence than ~ or ~>.
+     * @note <~ has lower operator precedence than ~ or ~>.
      *
      * @param q a parser that will be executed after `p` (this parser) succeeds -- evaluated at most once, and only when necessary
      * @return a `Parser` that -- on success -- returns the result of `p`.
@@ -372,7 +361,7 @@ trait Parsers {
      *  Use this combinator when a parser depends on the result of a previous parser. `p` should be
      *  a function that takes the result from the first parser and returns the second parser.
      *
-     *  `p into fq` (with `fq` typically `{x => q}') first applies `p`, and then, if `p` successfully
+     *  `p into fq` (with `fq` typically `{x => q}`) first applies `p`, and then, if `p` successfully
      *  returned result `r`, applies `fq(r)` to the rest of the input.
      *
      *  ''From: G. Hutton. Higher-order functions for parsing. J. Funct. Program., 2(3):323--343, 1992.''
@@ -384,20 +373,20 @@ trait Parsers {
 
     // shortcuts for combinators:
 
-    /** Returns into(fq) */
+    /** Returns `into(fq)`. */
     def >>[U](fq: T => Parser[U])=into(fq)
 
 
-    /** Returns a parser that repeatedly parses what this parser parses
+    /** Returns a parser that repeatedly parses what this parser parses.
      *
-     * @return rep(this)
+     *  @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.
+     *  The `sep` parser specifies how the results parsed by this parser should be combined.
      *
-     * @return chainl1(this, sep)
+     *  @return chainl1(this, sep)
      */
     def *[U >: T](sep: => Parser[(U, U) => U]) = chainl1(this, sep)
 
@@ -405,13 +394,13 @@ trait Parsers {
 
     /** Returns a parser that repeatedly (at least once) parses what this parser parses.
      *
-     * @return rep1(this)
+     *  @return rep1(this)
      */
     def + = rep1(this)
 
     /** Returns a parser that optionally parses what this parser parses.
      *
-     * @return opt(this)
+     *  @return opt(this)
      */
     def ? = opt(this)
   }
@@ -434,31 +423,31 @@ trait Parsers {
 
   /** 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.
+   *  `elem(kind, p)` succeeds if the input starts with an element `e` for which `p(e)` is true.
    *
-   * @param  kind   The element kind, used for error messages
-   * @param  p      A predicate that determines which elements match.
-   * @return
+   *  @param  kind   The element kind, used for error messages
+   *  @param  p      A predicate that determines which elements match.
+   *  @return
    */
   def elem(kind: String, p: Elem => Boolean) = acceptIf(p)(inEl => kind+" expected")
 
   /** A parser that matches only the given element `e`.
    *
-   * `elem(e)` succeeds if the input starts with an element `e`.
+   *  `elem(e)` succeeds if the input starts with an element `e`.
    *
-   * @param e the `Elem` that must be the next piece of input for the returned parser to succeed
-   * @return a `Parser` that succeeds if `e` is the next available input (and returns it).
+   *  @param e the `Elem` that must be the next piece of input for the returned parser to succeed
+   *  @return a `Parser` that succeeds if `e` is the next available input (and returns it).
    */
   def elem(e: Elem): Parser[Elem] = accept(e)
 
   /** A parser that matches only the given element `e`.
    *
-   * The method is implicit so that elements can automatically be lifted to their parsers.
-   * For example, when parsing `Token`s, `Identifier("new")` (which is a `Token`) can be used directly,
-   * instead of first creating a `Parser` using `accept(Identifier("new"))`.
+   *  The method is implicit so that elements can automatically be lifted to their parsers.
+   *  For example, when parsing `Token`s, `Identifier("new")` (which is a `Token`) can be used directly,
+   *  instead of first creating a `Parser` using `accept(Identifier("new"))`.
    *
-   * @param e the `Elem` that must be the next piece of input for the returned parser to succeed
-   * @return a `tParser` that succeeds if `e` is the next available input.
+   *  @param e the `Elem` that must be the next piece of input for the returned parser to succeed
+   *  @return a `tParser` that succeeds if `e` is the next available input.
    */
 
   implicit def accept(e: Elem): Parser[Elem] = acceptIf(_ == e)("`"+e+"' expected but " + _ + " found")
@@ -467,8 +456,8 @@ trait Parsers {
    *
    *  `accept(es)` succeeds if the input subsequently provides the elements in the list `es`.
    *
-   * @param  es the list of expected elements
-   * @return a Parser that recognizes a specified list of elements
+   *  @param  es the list of expected elements
+   *  @return a Parser that recognizes a specified list of elements
    */
   def accept[ES <% List[Elem]](es: ES): Parser[List[Elem]] = acceptSeq(es)
 
@@ -480,10 +469,10 @@ trait Parsers {
    *  Example: The parser `accept("name", {case Identifier(n) => Name(n)})`
    *          accepts an `Identifier(n)` and returns a `Name(n)`
    *
-   * @param expected a description of the kind of element this parser expects (for error messages)
-   * @param f a partial function that determines when this parser is successful and what its output is
-   * @return A parser that succeeds if `f` is applicable to the first element of the input,
-   *         applying `f` to it to produce the result.
+   *  @param expected a description of the kind of element this parser expects (for error messages)
+   *  @param f a partial function that determines when this parser is successful and what its output is
+   *  @return A parser that succeeds if `f` is applicable to the first element of the input,
+   *          applying `f` to it to produce the result.
    */
   def accept[U](expected: String, f: PartialFunction[Elem, U]): Parser[U] = acceptMatch(expected, f)
 
diff --git a/src/library/scala/util/parsing/combinator/lexical/Lexical.scala b/src/library/scala/util/parsing/combinator/lexical/Lexical.scala
index 917a4d3a44..9979a420d6 100644
--- a/src/library/scala/util/parsing/combinator/lexical/Lexical.scala
+++ b/src/library/scala/util/parsing/combinator/lexical/Lexical.scala
@@ -15,28 +15,25 @@ package lexical
 import token._
 import input.CharArrayReader.EofCh
 
-/** <p>
- *    This component complements the <code>Scanners</code> component with
- *    common operations for lexical parsers.
- *  </p>
- *  <p>
- *   {@see StdLexical} for a concrete implementation for a simple, Scala-like
- *   language.
- *  </p>
+/** This component complements the `Scanners` component with
+ *  common operations for lexical parsers.
+ *
+ *  Refer to [[scala.util.parsing.combinator.lexical.StdLexical]]
+ *  for a concrete implementation for a simple, Scala-like language.
  *
  * @author Martin Odersky, Adriaan Moors
  */
 abstract class Lexical extends Scanners with Tokens {
 
-  /** A character-parser that matches a letter (and returns it)*/
+  /** A character-parser that matches a letter (and returns it).*/
   def letter = elem("letter", _.isLetter)
 
-  /** A character-parser that matches a digit (and returns it)*/
+  /** A character-parser that matches a digit (and returns it).*/
   def digit = elem("digit", _.isDigit)
 
-  /** A character-parser that matches any character except the ones given in `cs` (and returns it)*/
+  /** A character-parser that matches any character except the ones given in `cs` (and returns it).*/
   def chrExcept(cs: Char*) = elem("", ch => (cs forall (ch !=)))
 
-  /** A character-parser that matches a white-space character (and returns it)*/
+  /** A character-parser that matches a white-space character (and returns it).*/
   def whitespaceChar = elem("space char", ch => ch <= ' ' && ch != EofCh)
 }
diff --git a/src/library/scala/util/parsing/combinator/lexical/Scanners.scala b/src/library/scala/util/parsing/combinator/lexical/Scanners.scala
index 80331e4e7c..d961f98f59 100644
--- a/src/library/scala/util/parsing/combinator/lexical/Scanners.scala
+++ b/src/library/scala/util/parsing/combinator/lexical/Scanners.scala
@@ -15,13 +15,10 @@ package lexical
 import token._
 import input._
 
-/** <p>
- *    This component provides core functionality for lexical parsers.
- *  </p>
- *  <p>
- *    See its subclasses {@see Lexical} and -- most interestingly
- *    {@see StdLexical}, for more functionality.
- *  </p>
+/** This component provides core functionality for lexical parsers.
+ *
+ *  See its subclasses [[scala.util.parsing.combinator.lexical.Lexical]] and -- most interestingly
+ *  [[scala.util.parsing.combinator.lexical.StdLexical]], for more functionality.
  *
  *  @author Martin Odersky, Adriaan Moors
  */
@@ -29,23 +26,20 @@ trait Scanners extends Parsers {
   type Elem = Char
   type Token
 
-  /** This token is produced by a scanner {@see Scanner} when scanning failed. */
+  /** This token is produced by a scanner `Scanner` when scanning failed. */
   def errorToken(msg: String): Token
 
-  /** a parser that produces a token (from a stream of characters) */
+  /** A parser that produces a token (from a stream of characters). */
   def token: Parser[Token]
 
-  /** a parser for white-space -- its result will be discarded */
+  /** A parser for white-space -- its result will be discarded. */
   def whitespace: Parser[Any]
 
-  /** <p>
-   *    <code>Scanner</code> is essentially(*) a parser that produces `Token`s
-   *    from a stream of characters. The tokens it produces are typically
-   *    passed to parsers in <code>TokenParsers</code>.
-   *  </p>
-   *  <p>
-   *   Note: (*) <code>Scanner</code> is really a `Reader` of `Token`s
-   *  </p>
+  /** `Scanner` is essentially¹ a parser that produces `Token`s
+   *  from a stream of characters. The tokens it produces are typically
+   *  passed to parsers in `TokenParsers`.
+   *
+   *  @note ¹ `Scanner` is really a `Reader` of `Token`s
    */
   class Scanner(in: Reader[Char]) extends Reader[Token] {
     /** Convenience constructor (makes a character reader out of the given string) */
diff --git a/src/library/scala/util/parsing/combinator/syntactical/TokenParsers.scala b/src/library/scala/util/parsing/combinator/syntactical/TokenParsers.scala
index 550589ea66..4571416e4e 100644
--- a/src/library/scala/util/parsing/combinator/syntactical/TokenParsers.scala
+++ b/src/library/scala/util/parsing/combinator/syntactical/TokenParsers.scala
@@ -13,13 +13,14 @@ package syntactical
 
 /** This is the core component for token-based parsers.
  *
- *  @author Martin Odersky, Adriaan Moors
+ *  @author Martin Odersky
+ *  @author Adriaan Moors
  */
 trait TokenParsers extends Parsers {
-  /** Tokens is the abstract type of the `Token`s consumed by the parsers in this component. */
+  /** `Tokens` is the abstract type of the `Token`s consumed by the parsers in this component. */
   type Tokens <: token.Tokens
 
-  /** lexical is the component responsible for consuming some basic kind of
+  /** `lexical` is the component responsible for consuming some basic kind of
    *  input (usually character-based) and turning it into the tokens
    *  understood by these parsers.
    */
diff --git a/src/library/scala/util/parsing/combinator/testing/Tester.scala b/src/library/scala/util/parsing/combinator/testing/Tester.scala
index 490442482a..ca1df2f6d4 100644
--- a/src/library/scala/util/parsing/combinator/testing/Tester.scala
+++ b/src/library/scala/util/parsing/combinator/testing/Tester.scala
@@ -13,22 +13,23 @@ import scala.util.parsing.combinator._
 import scala.util.parsing.combinator.lexical.Lexical
 import scala.util.parsing.combinator.syntactical.TokenParsers
 
-/** <p>
- *    Facilitates testing a given parser on various input strings.
- *  </p>
- *  <p>
- *    Example use:
- *  </p><pre>
- *    <b>val</b> syntactic = <b>new</b> MyParsers</pre>
- *  <p>
- *    and
- *  </p><pre>
- *    <b>val</b> parser = syntactic.term</pre>
- *  <p>
- *    (if MyParsers extends TokenParsers with a parser called `term`)
- *  </p>
+/** Facilitates testing a given parser on various input strings.
  *
- * @author Martin Odersky, Adriaan Moors
+ *  Example use:
+ *
+ *  <pre>
+ *    <b>val</b> syntactic = <b>new</b> MyParsers
+ *  </pre>
+ *  and
+ *  <pre>
+ *    <b>val</b> parser = syntactic.term
+ *  </pre>
+ *
+ *  (If `MyParsers` extends [[scala.util.parsing.combinator.syntactical.TokenParsers]]
+ *  with a parser called `term`.)
+ *
+ * @author Martin Odersky
+ * @author Adriaan Moors
  */
 abstract class Tester {
 
@@ -37,7 +38,7 @@ abstract class Tester {
 
 
   /** Scans a String (using a `syntactic.lexical.Scanner`), parses it
-   *  using <code>phrase(parser)</code>, and  prints the input and the
+   *  using `phrase(parser)`, and  prints the input and the
    *  parsed result to the console.
    */
   def test(in: String) {
diff --git a/src/library/scala/util/parsing/combinator/token/StdTokens.scala b/src/library/scala/util/parsing/combinator/token/StdTokens.scala
index 4ce62659f6..ce04da1fa4 100644
--- a/src/library/scala/util/parsing/combinator/token/StdTokens.scala
+++ b/src/library/scala/util/parsing/combinator/token/StdTokens.scala
@@ -12,7 +12,8 @@ package token
 
 /** This component provides the standard `Token`s for a simple, Scala-like language.
  *
- * @author Martin Odersky, Adriaan Moors
+ * @author Martin Odersky
+ * @author Adriaan Moors
  */
 trait StdTokens extends Tokens {
   /** The class of keyword tokens */
diff --git a/src/library/scala/util/parsing/combinator/token/Tokens.scala b/src/library/scala/util/parsing/combinator/token/Tokens.scala
index ad05427fa1..6b515fe6d9 100644
--- a/src/library/scala/util/parsing/combinator/token/Tokens.scala
+++ b/src/library/scala/util/parsing/combinator/token/Tokens.scala
@@ -13,11 +13,13 @@ package token
 /** This component provides the notion of `Token`, the unit of information that is passed from lexical
  * parsers in the `Lexical` component to the parsers in the `TokenParsers` component.
  *
- * @author Martin Odersky, Adriaan Moors
+ * @author Martin Odersky
+ * @author Adriaan Moors
  */
 trait Tokens {
-  /** Objects of this type are produced by a lexical parser or ``scanner'', and consumed by a parser
-   * {@see scala.util.parsing.combinator.syntactical.TokenParsers}.
+  /** Objects of this type are produced by a lexical parser or ``scanner'', and consumed by a parser.
+   *
+   *  @see [[scala.util.parsing.combinator.syntactical.TokenParsers]]
    */
   abstract class Token {
     def chars: String
@@ -35,6 +37,6 @@ trait Tokens {
     def chars = "<eof>"
   }
 
-  /** This token is produced by a scanner {@see Scanner} when scanning failed. */
+  /** This token is produced by a scanner `Scanner` when scanning failed. */
   def errorToken(msg: String): Token = new ErrorToken(msg)
 }
diff --git a/src/library/scala/util/parsing/input/CharArrayReader.scala b/src/library/scala/util/parsing/input/CharArrayReader.scala
index 67629eacd4..e798c9883a 100644
--- a/src/library/scala/util/parsing/input/CharArrayReader.scala
+++ b/src/library/scala/util/parsing/input/CharArrayReader.scala
@@ -9,9 +9,10 @@
 
 package scala.util.parsing.input
 
-/** An object encapsulating basic character constants
+/** An object encapsulating basic character constants.
  *
- * @author Martin Odersky, Adriaan Moors
+ * @author Martin Odersky
+ * @author Adriaan Moors
  */
 object CharArrayReader {
   final val EofCh = '\032'
@@ -25,10 +26,10 @@ object CharArrayReader {
  * @param line   the line number of the first element (counting from index `0` of `source`)
  * @param column the column number of the first element (counting from index `0` of `source`)
  *
- * @author Martin Odersky, Adriaan Moors
+ * @author Martin Odersky
+ * @author Adriaan Moors
  */
-class CharArrayReader(chars: Array[Char], index: Int)
-extends CharSequenceReader(chars, index) {
+class CharArrayReader(chars: Array[Char], index: Int) extends CharSequenceReader(chars, index) {
 
   def this(chars: Array[Char]) = this(chars, 0)
 
diff --git a/src/library/scala/util/parsing/input/CharSequenceReader.scala b/src/library/scala/util/parsing/input/CharSequenceReader.scala
index 8c3e1b24a8..ec1dce7be9 100644
--- a/src/library/scala/util/parsing/input/CharSequenceReader.scala
+++ b/src/library/scala/util/parsing/input/CharSequenceReader.scala
@@ -9,7 +9,7 @@
 
 package scala.util.parsing.input
 
-/** An object encapsulating basic character constants
+/** An object encapsulating basic character constants.
  *
  * @author Martin Odersky, Adriaan Moors
  */
@@ -29,27 +29,27 @@ class CharSequenceReader(override val source: java.lang.CharSequence,
                          override val offset: Int) extends Reader[Char] {
   import CharSequenceReader._
 
-  /** Construct a <code>CharSequenceReader</code> with its first element at
-   *  <code>source(0)</code> and position <code>(1,1)</code>.
+  /** Construct a `CharSequenceReader` with its first element at
+   *  `source(0)` and position `(1,1)`.
    */
   def this(source: java.lang.CharSequence) = this(source, 0)
 
-  /** Returns the first element of the reader, or EofCh if reader is at its end
+  /** Returns the first element of the reader, or EofCh if reader is at its end.
    */
   def first =
     if (offset < source.length) source.charAt(offset) else EofCh
 
-  /** Returns a CharSequenceReader consisting of all elements except the first
+  /** Returns a CharSequenceReader consisting of all elements except the first.
    *
-   * @return If <code>atEnd</code> is <code>true</code>, the result will be
-   *         <code>this'; otherwise, it's a <code>CharSequenceReader</code> containing
+   * @return If `atEnd` is `true`, the result will be
+   *         `this'; otherwise, it's a `CharSequenceReader` containing
    *         the rest of input.
    */
   def rest: CharSequenceReader =
     if (offset < source.length) new CharSequenceReader(source, offset + 1)
     else this
 
-  /** The position of the first element in the reader
+  /** The position of the first element in the reader.
    */
   def pos: Position = new OffsetPosition(source, offset)
 
@@ -59,7 +59,7 @@ class CharSequenceReader(override val source: java.lang.CharSequence,
   def atEnd = offset >= source.length
 
   /** Returns an abstract reader consisting of all elements except the first
-   *  <code>n</code> elements.
+   *  `n` elements.
    */
   override def drop(n: Int): CharSequenceReader =
     new CharSequenceReader(source, offset + n)
diff --git a/src/library/scala/util/parsing/input/NoPosition.scala b/src/library/scala/util/parsing/input/NoPosition.scala
index 174850165d..b34ce957d8 100644
--- a/src/library/scala/util/parsing/input/NoPosition.scala
+++ b/src/library/scala/util/parsing/input/NoPosition.scala
@@ -10,9 +10,10 @@
 
 package scala.util.parsing.input
 
-/** Undefined position
+/** Undefined position.
  *
- * @author Martin Odersky, Adriaan Moors
+ * @author Martin Odersky
+ * @author Adriaan Moors
  */
 object NoPosition extends Position {
   def line = 0
diff --git a/src/library/scala/util/parsing/input/OffsetPosition.scala b/src/library/scala/util/parsing/input/OffsetPosition.scala
index 1df1fa050e..c2483c44e3 100644
--- a/src/library/scala/util/parsing/input/OffsetPosition.scala
+++ b/src/library/scala/util/parsing/input/OffsetPosition.scala
@@ -10,17 +10,17 @@ package scala.util.parsing.input
 
 import collection.mutable.ArrayBuffer
 
-/** <p>
- *    <code>OffsetPosition</code> is a standard class for positions
- *    represented as offsets into a source ``document''.
- *    @param source   The source document
- *    @param offset   The offset indicating the position
+/** `OffsetPosition` is a standard class for positions
+ *   represented as offsets into a source ``document''.
+ *
+ *   @param source   The source document
+ *   @param offset   The offset indicating the position
  *
  * @author Martin Odersky
  */
 case class OffsetPosition(source: java.lang.CharSequence, offset: Int) extends Position {
 
-  /** An index that contains all line starts, including first line, and eof */
+  /** An index that contains all line starts, including first line, and eof. */
   private lazy val index: Array[Int] = {
     var lineStarts = new ArrayBuffer[Int]
     lineStarts += 0
@@ -30,7 +30,7 @@ case class OffsetPosition(source: java.lang.CharSequence, offset: Int) extends P
     lineStarts.toArray
   }
 
-  /** The line number referred to by the position; line numbers start at 1 */
+  /** The line number referred to by the position; line numbers start at 1. */
   def line: Int = {
     var lo = 0
     var hi = index.length - 1
@@ -42,7 +42,7 @@ case class OffsetPosition(source: java.lang.CharSequence, offset: Int) extends P
     lo + 1
   }
 
-  /** The column number referred to by the position; column numbers start at 1 */
+  /** The column number referred to by the position; column numbers start at 1. */
   def column: Int = offset - index(line - 1) + 1
 
   /** The contents of the line numbered `lnum` (must not contain a new-line character).
@@ -53,7 +53,7 @@ case class OffsetPosition(source: java.lang.CharSequence, offset: Int) extends P
   def lineContents: String =
     source.subSequence(index(line - 1), index(line)).toString
 
-  /** Returns a string representation of the `Position`, of the form `line.column` */
+  /** Returns a string representation of the `Position`, of the form `line.column`. */
   override def toString = line+"."+column
 
   /** Compare this position to another, by first comparing their line numbers,
diff --git a/src/library/scala/util/parsing/input/PagedSeqReader.scala b/src/library/scala/util/parsing/input/PagedSeqReader.scala
index 725287a9b8..8b69aa074b 100644
--- a/src/library/scala/util/parsing/input/PagedSeqReader.scala
+++ b/src/library/scala/util/parsing/input/PagedSeqReader.scala
@@ -11,9 +11,10 @@ package scala.util.parsing.input
 
 import scala.collection.immutable.PagedSeq
 
-/** An object encapsulating basic character constants
+/** An object encapsulating basic character constants.
  *
- * @author Martin Odersky, Adriaan Moors
+ * @author Martin Odersky
+ * @author Adriaan Moors
  */
 object PagedSeqReader {
   final val EofCh = '\032'
@@ -33,8 +34,8 @@ class PagedSeqReader(seq: PagedSeq[Char],
 
   override lazy val source: java.lang.CharSequence = seq
 
-  /** Construct a <code>PagedSeqReader</code> with its first element at
-   *  <code>source(0)</code> and position <code>(1,1)</code>.
+  /** Construct a `PagedSeqReader` with its first element at
+   *  `source(0)` and position `(1,1)`.
    */
   def this(seq: PagedSeq[Char]) = this(seq, 0)
 
@@ -45,25 +46,24 @@ class PagedSeqReader(seq: PagedSeq[Char],
 
   /** Returns a PagedSeqReader consisting of all elements except the first
    *
-   * @return If <code>atEnd</code> is <code>true</code>, the result will be
-   *         <code>this'; otherwise, it's a <code>PagedSeqReader</code> containing
-   *         the rest of input.
+   * @return If `atEnd` is `true`, the result will be `this';
+   *         otherwise, it's a `PagedSeqReader` containing the rest of input.
    */
   def rest: PagedSeqReader =
     if (seq.isDefinedAt(offset)) new PagedSeqReader(seq, offset + 1)
     else this
 
-  /** The position of the first element in the reader
+  /** The position of the first element in the reader.
    */
   def pos: Position = new OffsetPosition(source, offset)
 
   /** true iff there are no more elements in this reader (except for trailing
-   *  EofCh's)
+   *  EofCh's).
    */
   def atEnd = !seq.isDefinedAt(offset)
 
   /** Returns an abstract reader consisting of all elements except the first
-   *  <code>n</code> elements.
+   *  `n` elements.
    */
   override def drop(n: Int): PagedSeqReader =
     new PagedSeqReader(seq, offset + n)
diff --git a/src/library/scala/util/parsing/input/Position.scala b/src/library/scala/util/parsing/input/Position.scala
index b25f03667d..be817013a0 100644
--- a/src/library/scala/util/parsing/input/Position.scala
+++ b/src/library/scala/util/parsing/input/Position.scala
@@ -8,29 +8,23 @@
 
 package scala.util.parsing.input
 
-/** <p>
- *    <code>Position</code> is the base trait for objects describing a
- *    position in a ``document''.
- *  </p>
- *  <p>
- *    It provides functionality for:
- *  </p><ul>
- *    <li> generating a visual representation of this position (`longString`);
- *    <li> comparing two positions (`<`).
- *  </ul>
- *  <p>
- *    To use this class for a concrete kind of ``document'', implement the
- *    <code>lineContents</code> method.
- *  </p>
+/** `Position` is the base trait for objects describing a position in a ``document''.
  *
- * @author Martin Odersky, Adriaan Moors
+ *  It provides functionality for:
+ *   - generating a visual representation of this position (`longString`);
+ *   - comparing two positions (`<`).
+ *
+ *  To use this class for a concrete kind of ``document'', implement the `lineContents` method.
+ *
+ * @author Martin Odersky
+ * @author Adriaan Moors
  */
 trait Position {
 
-  /** The line number referred to by the position; line numbers start at 1 */
+  /** The line number referred to by the position; line numbers start at 1. */
   def line: Int
 
-  /** The column number referred to by the position; column numbers start at 1 */
+  /** The column number referred to by the position; column numbers start at 1. */
   def column: Int
 
   /** The contents of the line numbered `lnum` (must not contain a new-line character).
@@ -40,18 +34,19 @@ trait Position {
    */
   protected def lineContents: String
 
-  /** Returns a string representation of the `Position`, of the form `line.column` */
+  /** Returns a string representation of the `Position`, of the form `line.column`. */
   override def toString = ""+line+"."+column
 
   /** Returns a more ``visual'' representation of this position.
-   *  More precisely, the resulting string consists of two lines: <ol>
-   *    <li> the line in the document referred to by this position </li>
-   *    <li>a caret indicating the column</li></ol>
+   *  More precisely, the resulting string consists of two lines:
+   *   1. the line in the document referred to by this position
+   *   2. a caret indicating the column
    *
    *  Example:
-   *
-   *<pre>    List(this, is, a, line, from, the, document)
-   *                  ^</pre>
+   *  {{{
+   *    List(this, is, a, line, from, the, document)
+   *                 ^
+   *  }}}
    */
   def longString = lineContents+"\n"+lineContents.take(column-1).map{x => if (x == '\t') x else ' ' } + "^"
 
diff --git a/src/library/scala/util/parsing/input/Reader.scala b/src/library/scala/util/parsing/input/Reader.scala
index d0fddd2c6d..c44ed5ed00 100644
--- a/src/library/scala/util/parsing/input/Reader.scala
+++ b/src/library/scala/util/parsing/input/Reader.scala
@@ -13,12 +13,15 @@ package scala.util.parsing.input
 
 /** An interface for streams of values that have positions.
  *
- * @author Martin Odersky, Adriaan Moors
+ * @author Martin Odersky
+ * @author Adriaan Moors
  */
 abstract class Reader[+T] {
 
-  /** If this is a reader over character sequences, the underlying char sequence
-   *  If not, throws a <code>NoSuchMethodError</code> exception.
+  /** If this is a reader over character sequences, the underlying char sequence.
+   *  If not, throws a `NoSuchMethodError` exception.
+   *
+   *  @throws [[java.lang.NoSuchMethodError]] if this not a char sequence reader.
    */
   def source: java.lang.CharSequence =
     throw new NoSuchMethodError("not a char sequence reader")
@@ -32,14 +35,12 @@ abstract class Reader[+T] {
 
   /** Returns an abstract reader consisting of all elements except the first
    *
-   * @return If <code>atEnd</code> is <code>true</code>, the result will be
-   *         <code>this'; otherwise, it's a <code>Reader</code> containing
-   *         more elements.
+   * @return If `atEnd` is `true`, the result will be `this';
+   *         otherwise, it's a `Reader` containing more elements.
    */
   def rest: Reader[T]
 
-  /** Returns an abstract reader consisting of all elements except the first
-   *  <code>n</code> elements.
+  /** Returns an abstract reader consisting of all elements except the first `n` elements.
    */
   def drop(n: Int): Reader[T] = {
     var r: Reader[T] = this
@@ -50,11 +51,11 @@ abstract class Reader[+T] {
     r
   }
 
-  /** The position of the first element in the reader
+  /** The position of the first element in the reader.
    */
   def pos: Position
 
-  /** true iff there are no more elements in this reader
+  /** `true` iff there are no more elements in this reader.
    */
   def atEnd: Boolean
 }
diff --git a/src/library/scala/util/parsing/syntax/package.scala b/src/library/scala/util/parsing/syntax/package.scala
index 547136c21d..59053e2f54 100644
--- a/src/library/scala/util/parsing/syntax/package.scala
+++ b/src/library/scala/util/parsing/syntax/package.scala
@@ -10,9 +10,8 @@ package scala.util.parsing
 
 import scala.util.parsing.combinator.token
 
-/** If deprecating the whole package worked, that's what would best
- *  be done, but it doesn't (yet) so it isn't.
- */
+// If deprecating the whole package worked, that's what would best
+// be done, but it doesn't (yet) so it isn't.
 package object syntax {
   @deprecated("Moved to scala.util.parsing.combinator.token", "2.8.0")
   type Tokens = token.Tokens
diff --git a/src/library/scala/util/regexp/Base.scala b/src/library/scala/util/regexp/Base.scala
index 1404e9fa1b..8e23d46eb9 100644
--- a/src/library/scala/util/regexp/Base.scala
+++ b/src/library/scala/util/regexp/Base.scala
@@ -24,7 +24,7 @@ abstract class Base
   }
 
   object Alt {
-    /** Alt( R,R,R* ) */
+    /** `Alt( R,R,R* )`. */
     def apply(rs: _regexpT*) =
       if (rs.size < 2) throw new SyntaxError("need at least 2 branches in Alt")
       else new Alt(rs: _*)
@@ -57,7 +57,7 @@ abstract class Base
     override def toString() = "Eps"
   }
 
-  /** this class can be used to add meta information to regexps */
+  /** this class can be used to add meta information to regexps. */
   class Meta(r1: _regexpT) extends RegExp {
     final val isNullable = r1.isNullable
     def r = r1
diff --git a/src/library/scala/util/regexp/PointedHedgeExp.scala b/src/library/scala/util/regexp/PointedHedgeExp.scala
index ef68e600c8..23aa46448c 100644
--- a/src/library/scala/util/regexp/PointedHedgeExp.scala
+++ b/src/library/scala/util/regexp/PointedHedgeExp.scala
@@ -10,8 +10,7 @@
 
 package scala.util.regexp
 
-/** pointed regular hedge expressions, a useful subclass of
- *  regular hedge expressions.
+/** Pointed regular hedge expressions, a useful subclass of regular hedge expressions.
  *
  *  @author  Burak Emir
  *  @version 1.0
diff --git a/src/library/scala/util/regexp/WordExp.scala b/src/library/scala/util/regexp/WordExp.scala
index 1168b1e423..6a83794ef4 100644
--- a/src/library/scala/util/regexp/WordExp.scala
+++ b/src/library/scala/util/regexp/WordExp.scala
@@ -10,12 +10,14 @@
 
 package scala.util.regexp
 
-/** <p>
- *    The class <code>WordExp</code> provides regular word expressions.
- *    Users have to instantiate type member <code>_regexpT &lt;: RegExp</code>
- *    (from class <code>Base</code>) and a type member
- *    <code>_labelT &lt;: Label</code>. Here is a short example:
- *  </p><pre>
+/**
+ *  The class `WordExp` provides regular word expressions.
+ *
+ *  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 {