Changes to docs of collections in the `immutabl...

Changes to docs of collections in the `immutable` package. Review by
odersky.

20 files changed, 157 insertions, 98 deletions

diff --git a/src/library/scala/collection/MapLike.scala b/src/library/scala/collection/MapLike.scala
index 6a9fffe3e1..057224a705 100644
--- a/src/library/scala/collection/MapLike.scala
+++ b/src/library/scala/collection/MapLike.scala
@@ -233,13 +233,10 @@ self =>
   }
 
   /** Transforms this map by applying a function to every retrieved value.
-   *  @param  d   the function used to transform values of this map.
-   *  @return an immutable map which maps every key of this map
+   *  @param  f   the function used to transform values of this map.
+   *  @return a map view which maps every key of this map
    *          to `f(this(key))`. The resulting map wraps the original map without copying any elements.
    */
-  /** A map view resulting from applying a given function `f` to each value
-   *  associated with a key in this map.
-   */
   def mapValues[C](f: B => C): Map[A, C] = new DefaultMap[A, C] {
     override def foreach[D](g: ((A, C)) => D): Unit = for ((k, v) <- self) g((k, f(v)))
     def iterator = for ((k, v) <- self.iterator) yield (k, f(v))
diff --git a/src/library/scala/collection/immutable/BitSet.scala b/src/library/scala/collection/immutable/BitSet.scala
index e06218ff92..f644ce08e9 100644
--- a/src/library/scala/collection/immutable/BitSet.scala
+++ b/src/library/scala/collection/immutable/BitSet.scala
@@ -15,7 +15,7 @@ package immutable
 import generic._
 import BitSetLike.{LogWL, updateArray}
 
-/** A base class for immutable bit sets.
+/** A base class for immutable bit sets.x
  *  $bitsetinfo
  *
  *  @author Martin Odersky
diff --git a/src/library/scala/collection/immutable/DefaultMap.scala b/src/library/scala/collection/immutable/DefaultMap.scala
index 7ee8197150..a19b35aff0 100755
--- a/src/library/scala/collection/immutable/DefaultMap.scala
+++ b/src/library/scala/collection/immutable/DefaultMap.scala
@@ -19,7 +19,8 @@ import generic._
  *    methods of maps.<br/>
  *    Instances that inherit from <code>DefaultMap[A, B]</code> still have to
  *    define:
- *  </p><pre>
+ *  </p>
+ *  <pre>
  *    <b>def</b> get(key: A): Option[B]
  *    <b>def</b> iterator: Iterator[(A, B)]</pre>
  *  <p>
diff --git a/src/library/scala/collection/immutable/HashSet.scala b/src/library/scala/collection/immutable/HashSet.scala
index 16d4473de1..e79b456a2f 100644
--- a/src/library/scala/collection/immutable/HashSet.scala
+++ b/src/library/scala/collection/immutable/HashSet.scala
@@ -15,12 +15,11 @@ package immutable
 import generic._
 import annotation.unchecked.uncheckedVariance
 
-/** <p>
- *    This class implements immutable sets using a hash trie.
- *  </p>
+/**
+ *  This class implements immutable sets using a hash trie.
  *
- * @note the builder of a hash set returns specialized representations EmptySet,Set1,..., Set4
- * for sets of size <= 4.
+ * @note the builder of a hash set returns specialized representations `EmptySet`,`Set1`,..., `Set4`
+ * for sets of `size <= 4`.
  *
  *  @author  Martin Odersky
  *  @author  Tiark Rompf
diff --git a/src/library/scala/collection/immutable/IntMap.scala b/src/library/scala/collection/immutable/IntMap.scala
index 62309a9f48..75a25e0223 100644
--- a/src/library/scala/collection/immutable/IntMap.scala
+++ b/src/library/scala/collection/immutable/IntMap.scala
@@ -167,6 +167,8 @@ sealed abstract class IntMap[+T] extends Map[Int, T] with MapLike[Int, T, IntMap
 
   /**
    * Iterator over key, value pairs of the map in unsigned order of the keys.
+   *
+   * @return an iterator over pairs of integer keys and corresponding values.
    */
   def iterator : Iterator[(Int, T)] = this match {
     case IntMap.Nil => Iterator.empty;
@@ -278,15 +280,20 @@ sealed abstract class IntMap[+T] extends Map[Int, T] with MapLike[Int, T, IntMap
 
   /**
    * Updates the map, using the provided function to resolve conflicts if the key is already present.
-   * Equivalent to
-   * <pre>this.get(key) match {
-   *         case None => this.update(key, value);
-   *         case Some(oldvalue) => this.update(key, f(oldvalue, value) }
-   * </pre>
    *
-   * @param key The key to update
-   * @param value The value to use if there is no conflict
-   * @param f The function used to resolve conflicts.
+   * Equivalent to:
+   * {{{
+   *   this.get(key) match {
+   *     case None => this.update(key, value);
+   *     case Some(oldvalue) => this.update(key, f(oldvalue, value)
+   *   }
+   * }}}
+   *
+   * @tparam S     The supertype of values in this `LongMap`.
+   * @param key    The key to update
+   * @param value  The value to use if there is no conflict
+   * @param f      The function used to resolve conflicts.
+   * @return       The updated map.
    */
   def updateWith[S >: T](key : Int, value : S, f : (T, S) => S) : IntMap[S] = this match {
     case IntMap.Bin(prefix, mask, left, right) => if (!hasMatch(key, prefix, mask)) join(key, IntMap.Tip(key, value), prefix, this);
@@ -312,7 +319,9 @@ sealed abstract class IntMap[+T] extends Map[Int, T] with MapLike[Int, T, IntMap
    * A combined transform and filter function. Returns an IntMap such that for each (key, value) mapping
    * in this map, if f(key, value) == None the map contains no mapping for key, and if <code>f(key, value)
    *
-   * @param f The transforming function.
+   * @tparam S  The type of the values in the resulting `LongMap`.
+   * @param f   The transforming function.
+   * @return    The modified map.
    */
   def modifyOrRemove[S](f : (Int, T) => Option[S]) : IntMap[S] = this match {
       case IntMap.Bin(prefix, mask, left, right) => {
@@ -335,8 +344,10 @@ sealed abstract class IntMap[+T] extends Map[Int, T] with MapLike[Int, T, IntMap
   /**
    * Forms a union map with that map, using the combining function to resolve conflicts.
    *
-   * @param that the map to form a union with.
-   * @param f the function used to resolve conflicts between two mappings.
+   * @tparam S      The type of values in `that`, a supertype of values in `this`.
+   * @param that    The map to form a union with.
+   * @param f       The function used to resolve conflicts between two mappings.
+   * @return        Union of `this` and `that`, with identical key conflicts resolved using the function `f`.
    */
   def unionWith[S >: T](that : IntMap[S], f : (Int, S, S) => S) : IntMap[S] = (this, that) match{
     case (IntMap.Bin(p1, m1, l1, r1), that@(IntMap.Bin(p2, m2, l2, r2))) =>
@@ -364,8 +375,11 @@ sealed abstract class IntMap[+T] extends Map[Int, T] with MapLike[Int, T, IntMap
    * a map that has only keys present in both maps and has values produced from the original mappings
    * by combining them with f.
    *
-   * @param that The map to intersect with.
-   * @param f The combining function.
+   * @tparam S      The type of values in `that`.
+   * @tparam R      The type of values in the resulting `LongMap`.
+   * @param that    The map to intersect with.
+   * @param f       The combining function.
+   * @return        Intersection of `this` and `that`, with values for identical keys produced by function `f`.
    */
   def intersectionWith[S, R](that : IntMap[S], f : (Int, T, S) => R) : IntMap[R] = (this, that) match {
     case (IntMap.Bin(p1, m1, l1, r1), that@IntMap.Bin(p2, m2, l2, r2)) =>
@@ -394,7 +408,9 @@ sealed abstract class IntMap[+T] extends Map[Int, T] with MapLike[Int, T, IntMap
    * Left biased intersection. Returns the map that has all the same mappings as this but only for keys
    * which are present in the other map.
    *
-   * @param that The map to intersect with.
+   * @tparam R      The type of values in `that`.
+   * @param that    The map to intersect with.
+   * @return        A map with all the keys both in `this` and `that`, mapped to corresponding values from `this`.
    */
   def intersection[R](that : IntMap[R]) : IntMap[T] = this.intersectionWith(that, (key : Int, value : T, value2 : R) => value);
 
diff --git a/src/library/scala/collection/immutable/ListMap.scala b/src/library/scala/collection/immutable/ListMap.scala
index d8e3e0856b..4342e54a9d 100644
--- a/src/library/scala/collection/immutable/ListMap.scala
+++ b/src/library/scala/collection/immutable/ListMap.scala
@@ -104,6 +104,8 @@ class ListMap[A, +B] extends Map[A, B] with MapLike[A, B, ListMap[A, B]] {
   protected def value: B = throw new NoSuchElementException("empty map")
   protected def next: ListMap[A, B] = throw new NoSuchElementException("empty map")
 
+  /** This class represents an entry in the `ListMap`.
+   */
   @serializable @SerialVersionUID(-6453056603889598734L)
   protected class Node[B1 >: B](override protected val key: A,
                                 override protected val value: B1) extends ListMap[A, B1] {
diff --git a/src/library/scala/collection/immutable/ListSet.scala b/src/library/scala/collection/immutable/ListSet.scala
index 3863c16591..f7b76d2317 100644
--- a/src/library/scala/collection/immutable/ListSet.scala
+++ b/src/library/scala/collection/immutable/ListSet.scala
@@ -85,6 +85,8 @@ class ListSet[A] extends Set[A]
    */
   protected def next: ListSet[A] = throw new NoSuchElementException("Next of an empty set");
 
+  /** Represents an entry in the `ListSet`.
+   */
   @serializable
   protected class Node(override protected val elem: A) extends ListSet[A] {
 
diff --git a/src/library/scala/collection/immutable/LongMap.scala b/src/library/scala/collection/immutable/LongMap.scala
index 0d74e41cec..24afb65b99 100644
--- a/src/library/scala/collection/immutable/LongMap.scala
+++ b/src/library/scala/collection/immutable/LongMap.scala
@@ -153,6 +153,8 @@ sealed abstract class LongMap[+T] extends Map[Long, T] with MapLike[Long, T, Lon
 
   /**
    * Iterator over key, value pairs of the map in unsigned order of the keys.
+   *
+   * @return an iterator over pairs of long keys and corresponding values.
    */
   def iterator: Iterator[(Long, T)] = this match {
     case LongMap.Nil => Iterator.empty;
@@ -264,15 +266,20 @@ sealed abstract class LongMap[+T] extends Map[Long, T] with MapLike[Long, T, Lon
 
   /**
    * Updates the map, using the provided function to resolve conflicts if the key is already present.
+   *
    * Equivalent to
-   * <pre>this.get(key) match {
-   *         case None => this.update(key, value);
-   *         case Some(oldvalue) => this.update(key, f(oldvalue, value) }
-   * </pre>
+   * {{{
+   *   this.get(key) match {
+   *     case None => this.update(key, value);
+   *     case Some(oldvalue) => this.update(key, f(oldvalue, value)
+   *   }
+   * }}}
    *
-   * @param key The key to update
-   * @param value The value to use if there is no conflict
-   * @param f The function used to resolve conflicts.
+   * @tparam S     The supertype of values in this `LongMap`.
+   * @param key    The key to update.
+   * @param value  The value to use if there is no conflict.
+   * @param f      The function used to resolve conflicts.
+   * @return       The updated map.
    */
   def updateWith[S >: T](key : Long, value : S, f : (T, S) => S) : LongMap[S] = this match {
     case LongMap.Bin(prefix, mask, left, right) => if (!hasMatch(key, prefix, mask)) join(key, LongMap.Tip(key, value), prefix, this);
@@ -298,7 +305,9 @@ sealed abstract class LongMap[+T] extends Map[Long, T] with MapLike[Long, T, Lon
    * A combined transform and filter function. Returns an LongMap such that for each (key, value) mapping
    * in this map, if f(key, value) == None the map contains no mapping for key, and if <code>f(key, value)
    *
-   * @param f The transforming function.
+   * @tparam S    The type of the values in the resulting `LongMap`.
+   * @param f     The transforming function.
+   * @return      The modified map.
    */
   def modifyOrRemove[S](f : (Long, T) => Option[S]) : LongMap[S] = this match {
       case LongMap.Bin(prefix, mask, left, right) => {
@@ -321,8 +330,10 @@ sealed abstract class LongMap[+T] extends Map[Long, T] with MapLike[Long, T, Lon
   /**
    * Forms a union map with that map, using the combining function to resolve conflicts.
    *
-   * @param that the map to form a union with.
-   * @param f the function used to resolve conflicts between two mappings.
+   * @tparam S      The type of values in `that`, a supertype of values in `this`.
+   * @param that    The map to form a union with.
+   * @param f       The function used to resolve conflicts between two mappings.
+   * @return        Union of `this` and `that`, with identical key conflicts resolved using the function `f`.
    */
   def unionWith[S >: T](that : LongMap[S], f : (Long, S, S) => S) : LongMap[S] = (this, that) match{
     case (LongMap.Bin(p1, m1, l1, r1), that@(LongMap.Bin(p2, m2, l2, r2))) =>
@@ -350,8 +361,11 @@ sealed abstract class LongMap[+T] extends Map[Long, T] with MapLike[Long, T, Lon
    * a map that has only keys present in both maps and has values produced from the original mappings
    * by combining them with f.
    *
-   * @param that The map to intersect with.
-   * @param f The combining function.
+   * @tparam S      The type of values in `that`.
+   * @tparam R      The type of values in the resulting `LongMap`.
+   * @param that    The map to intersect with.
+   * @param f       The combining function.
+   * @return        Intersection of `this` and `that`, with values for identical keys produced by function `f`.
    */
   def intersectionWith[S, R](that : LongMap[S], f : (Long, T, S) => R) : LongMap[R] = (this, that) match {
     case (LongMap.Bin(p1, m1, l1, r1), that@LongMap.Bin(p2, m2, l2, r2)) =>
@@ -380,7 +394,9 @@ sealed abstract class LongMap[+T] extends Map[Long, T] with MapLike[Long, T, Lon
    * Left biased intersection. Returns the map that has all the same mappings as this but only for keys
    * which are present in the other map.
    *
-   * @param that The map to intersect with.
+   * @tparam R      The type of values in `that`.
+   * @param that    The map to intersect with.
+   * @return        A map with all the keys both in `this` and `that`, mapped to corresponding values from `this`.
    */
   def intersection[R](that : LongMap[R]) : LongMap[T] = this.intersectionWith(that, (key : Long, value : T, value2 : R) => value);
 
diff --git a/src/library/scala/collection/immutable/Map.scala b/src/library/scala/collection/immutable/Map.scala
index b5a852683a..e3469099b8 100644
--- a/src/library/scala/collection/immutable/Map.scala
+++ b/src/library/scala/collection/immutable/Map.scala
@@ -15,6 +15,16 @@ package immutable
 import generic._
 
 /**
+ * A generic trait for immutable maps. Concrete classes have to provide
+ * functionality for the abstract methods in `Map`:
+ *
+ * {{{
+ *    def get(key: A): Option[B]
+ *    def iterator: Iterator[(A, B)]
+ *    def + [B1 >: B](kv: (A, B1)): Map[A, B1]
+ *    def -(key: A): Map[A, B]
+ * }}}
+ *
  * @since 1
  */
 trait Map[A, +B] extends Iterable[(A, B)]
@@ -39,6 +49,8 @@ trait Map[A, +B] extends Iterable[(A, B)]
 }
 
 /**
+ * A companion object for immutable maps.
+ *
  * @since 1
  */
 object Map extends ImmutableMapFactory[Map] {
diff --git a/src/library/scala/collection/immutable/MapLike.scala b/src/library/scala/collection/immutable/MapLike.scala
index 662321bb0c..6f816ffa52 100644
--- a/src/library/scala/collection/immutable/MapLike.scala
+++ b/src/library/scala/collection/immutable/MapLike.scala
@@ -91,13 +91,10 @@ trait MapLike[A, +B, +This <: MapLike[A, B, This] with Map[A, B]]
   }
 
   /** Transforms this map by applying a function to every retrieved value.
-   *  @param  d   the function used to transform values of this map.
-   *  @return an immutable map which maps every key of this map
+   *  @param  f   the function used to transform values of this map.
+   *  @return a map view which maps every key of this map
    *          to `f(this(key))`. The resulting map wraps the original map without copying any elements.
    */
-  /** A map view resulting from applying a given function `f` to each value
-   *  associated with a key in this map.
-   */
   override def mapValues[C](f: B => C): Map[A, C] = new DefaultMap[A, C] {
     override def foreach[D](g: ((A, C)) => D): Unit = for ((k, v) <- self) g((k, f(v)))
     def iterator = for ((k, v) <- self.iterator) yield (k, f(v))
diff --git a/src/library/scala/collection/immutable/NumericRange.scala b/src/library/scala/collection/immutable/NumericRange.scala
index d3e4558884..645c5fed24 100644
--- a/src/library/scala/collection/immutable/NumericRange.scala
+++ b/src/library/scala/collection/immutable/NumericRange.scala
@@ -17,12 +17,12 @@ import generic._
 /** <p>
  *    <code>NumericRange</code> is a more generic version of the
  *    <code>Range</code> class which works with arbitrary types.
- *    It must be supplied with an Integral implementation of the
+ *    It must be supplied with an `Integral` implementation of the
  *    range type.
  *
- *    Factories for likely types include Range.BigInt, Range.Long,
- *    and Range.BigDecimal.  Range.Int exists for completeness, but
- *    the Int-based scala.Range should be more performant.
+ *    Factories for likely types include `Range.BigInt`, `Range.Long`,
+ *    and `Range.BigDecimal`.  `Range.Int` exists for completeness, but
+ *    the `Int`-based `scala.Range` should be more performant.
  *  </p><pre>
  *     <b>val</b> r1 = new Range(0, 100, 1)
  *     <b>val</b> veryBig = Int.MaxValue.toLong + 1
diff --git a/src/library/scala/collection/immutable/Range.scala b/src/library/scala/collection/immutable/Range.scala
index 43b11b67be..dc79d0d5e0 100644
--- a/src/library/scala/collection/immutable/Range.scala
+++ b/src/library/scala/collection/immutable/Range.scala
@@ -32,7 +32,7 @@ class Range(val start: Int, val end: Int, val step: Int) extends IndexedSeq[Int]
 
   protected def copy(start: Int, end: Int, step: Int): Range = new Range(start, end, step)
 
-  /** Create a new range with the start and end values of this range and
+  /** Create a new range with the `start` and `end` values of this range and
    *  a new <code>step</code>.
    */
   def by(step: Int): Range = copy(start, end, step)
diff --git a/src/library/scala/collection/immutable/RedBlack.scala b/src/library/scala/collection/immutable/RedBlack.scala
index e7b4f3c978..ffa6194838 100644
--- a/src/library/scala/collection/immutable/RedBlack.scala
+++ b/src/library/scala/collection/immutable/RedBlack.scala
@@ -12,7 +12,7 @@
 package scala.collection
 package immutable
 
-/** An base class containing the implementations for TreeMaps and TreeSets
+/** A base class containing the implementations for TreeMaps and TreeSets
  *
  * @since 2.3
  */
diff --git a/src/library/scala/collection/immutable/Seq.scala b/src/library/scala/collection/immutable/Seq.scala
index 9bd7084675..a3059000e8 100644
--- a/src/library/scala/collection/immutable/Seq.scala
+++ b/src/library/scala/collection/immutable/Seq.scala
@@ -15,7 +15,7 @@ package immutable
 import generic._
 import mutable.Builder
 
-/** A subtrait of collection.Seq which represents sequences
+/** A subtrait of `collection.Seq` which represents sequences
  *  that cannot be mutated.
  *
  *  @since 2.8
diff --git a/src/library/scala/collection/immutable/Set.scala b/src/library/scala/collection/immutable/Set.scala
index 1bec1b9a48..77f16c0d14 100644
--- a/src/library/scala/collection/immutable/Set.scala
+++ b/src/library/scala/collection/immutable/Set.scala
@@ -39,6 +39,9 @@ trait Set[A] extends Iterable[A]
   override def companion: GenericCompanion[Set] = Set
 }
 
+/**
+ * A companion object for immutable sets.
+ */
 object Set extends SetFactory[Set] {
   implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, Set[A]] = setCanBuildFrom[A]
   override def empty[A]: Set[A] = EmptySet.asInstanceOf[Set[A]]
diff --git a/src/library/scala/collection/immutable/SortedSet.scala b/src/library/scala/collection/immutable/SortedSet.scala
index 9d0b1882fa..10ff466ff8 100644
--- a/src/library/scala/collection/immutable/SortedSet.scala
+++ b/src/library/scala/collection/immutable/SortedSet.scala
@@ -15,7 +15,8 @@ package immutable
 import generic._
 import mutable.Builder
 
-/** A sorted set.
+/** A subtrait of `collection.SortedSet` which represents sorted sets
+ *  which cannot be mutated.
  *
  *  @author Sean McDirmid
  *  @author Martin Odersky
@@ -28,6 +29,8 @@ trait SortedSet[A] extends Set[A] with scala.collection.SortedSet[A] with Sorted
 }
 
 /**
+ * A companion object for immutable sorted sets.
+ *
  * @since 2.4
  */
 object SortedSet extends ImmutableSortedSetFactory[SortedSet] {
diff --git a/src/library/scala/collection/immutable/Stack.scala b/src/library/scala/collection/immutable/Stack.scala
index 640fb39af5..7d3c8c040b 100644
--- a/src/library/scala/collection/immutable/Stack.scala
+++ b/src/library/scala/collection/immutable/Stack.scala
@@ -67,8 +67,8 @@ class Stack[+A] protected (protected val elems: List[A]) extends LinearSeq[A]
   def push[B >: A](elem1: B, elem2: B, elems: B*): Stack[B] =
     this.push(elem1).push(elem2).pushAll(elems)
 
-  /** Push all elements provided by the given iterator object onto
-   *  the stack. The last element returned by the iterable object
+  /** Push all elements provided by the given traversable object onto
+   *  the stack. The last element returned by the traversable object
    *  will be on top of the new stack.
    *
    *  @param   elems      the iterator object.
diff --git a/src/library/scala/collection/immutable/StringLike.scala b/src/library/scala/collection/immutable/StringLike.scala
index 5b5a627cfe..8068267dd2 100644
--- a/src/library/scala/collection/immutable/StringLike.scala
+++ b/src/library/scala/collection/immutable/StringLike.scala
@@ -49,7 +49,7 @@ self =>
 
   override def mkString = toString
 
-  /** return n times the current string
+  /** Return the current string concatenated `n` times.
    */
   def * (n: Int): String = {
     val buf = new StringBuilder
@@ -61,18 +61,16 @@ self =>
 
   private def isLineBreak(c: Char) = c == LF || c == FF
 
-  /** <p>
+  /**
    *    Strip trailing line end character from this string if it has one.
+   *
    *    A line end character is one of
-   *  </p>
-   *  <ul style="list-style-type: none;">
-   *    <li>LF - line feed   (0x0A hex)</li>
-   *    <li>FF - form feed   (0x0C hex)</li>
-   *  </ul>
-   *  <p>
+   *    <ul style="list-style-type: none;">
+   *      <li>LF - line feed   (0x0A hex)</li>
+   *      <li>FF - form feed   (0x0C hex)</li>
+   *    </ul>
    *    If a line feed character LF is preceded by a carriage return CR
    *    (0x0D hex), the CR character is also stripped (Windows convention).
-   *  </p>
    */
   def stripLineEnd: String = {
     val len = toString.length
@@ -86,19 +84,18 @@ self =>
     }
   }
 
-  /** <p>
+  /**
    *    Return all lines in this string in an iterator, including trailing
    *    line end characters.
-   *  </p>
-   *  <p>
+   *
    *    The number of strings returned is one greater than the number of line
    *    end characters in this string. For an empty string, a single empty
    *    line is returned. A line end character is one of
-   *  </p>
-   *  <ul style="list-style-type: none;">
-   *    <li>LF - line feed   (0x0A hex)</li>
-   *    <li>FF - form feed   (0x0C hex)</li>
-   *  </ul>
+   *
+   *    <ul style="list-style-type: none;">
+   *      <li>LF - line feed   (0x0A hex)</li>
+   *      <li>FF - form feed   (0x0C hex)</li>
+   *    </ul>
    */
   def linesWithSeparators: Iterator[String] = new Iterator[String] {
     val str = self.toString
@@ -148,13 +145,13 @@ self =>
     if (toString.endsWith(suffix)) toString.substring(0, toString.length() - suffix.length)
     else toString
 
-  /** <p>
+  /**
    *    For every line in this string:
-   *  </p>
-   *  <blockquote>
-   *     Strip a leading prefix consisting of blanks or control characters
-   *     followed by <code>marginChar</code> from the line.
-   *  </blockquote>
+   *
+   *    <blockquote>
+   *       Strip a leading prefix consisting of blanks or control characters
+   *       followed by <code>marginChar</code> from the line.
+   *    </blockquote>
    */
   def stripMargin(marginChar: Char): String = {
     val buf = new StringBuilder
@@ -168,13 +165,13 @@ self =>
     buf.toString
   }
 
-  /** <p>
+  /**
    *    For every line in this string:
-   *  </p>
-   *  <blockquote>
-   *     Strip a leading prefix consisting of blanks or control characters
-   *     followed by <code>|</code> from the line.
-   *  </blockquote>
+   *
+   *    <blockquote>
+   *       Strip a leading prefix consisting of blanks or control characters
+   *       followed by <code>|</code> from the line.
+   *    </blockquote>
    */
   def stripMargin: String = stripMargin('|')
 
@@ -226,19 +223,18 @@ self =>
     case x              => x.asInstanceOf[AnyRef]
   }
 
-  /** <p>
+  /**
    *  Uses the underlying string as a pattern (in a fashion similar to
    *  printf in C), and uses the supplied arguments to fill in the
    *  holes.
-   *  </p>
-   *  <p>
+   *
    *    The interpretation of the formatting patterns is described in
    *    <a href="" target="contentFrame" class="java/util/Formatter">
    *    <code>java.util.Formatter</code></a>, with the addition that
-   *    classes deriving from ScalaNumber (such as scala.BigInt and
-   *    scala.BigDecimal) are unwrapped to pass a type which Formatter
+   *    classes deriving from `ScalaNumber` (such as `scala.BigInt` and
+   *    `scala.BigDecimal`) are unwrapped to pass a type which `Formatter`
    *    understands.
-   *  </p>
+   *
    *
    *  @param args the arguments used to instantiating the pattern.
    *  @throws java.lang.IllegalArgumentException
@@ -246,20 +242,20 @@ self =>
   def format(args : Any*): String =
     java.lang.String.format(toString, args map unwrapArg: _*)
 
-  /** <p>
-   *  Like format(args*) but takes an initial Locale parameter
-   *  which influences formatting as in java.lang.String's format.
-   *  </p>
-   *  <p>
+  /**
+   *  Like `format(args*)` but takes an initial `Locale` parameter
+   *  which influences formatting as in `java.lang.String`'s format.
+   *
+   *
    *    The interpretation of the formatting patterns is described in
    *    <a href="" target="contentFrame" class="java/util/Formatter">
    *    <code>java.util.Formatter</code></a>, with the addition that
-   *    classes deriving from ScalaNumber (such as scala.BigInt and
-   *    scala.BigDecimal) are unwrapped to pass a type which Formatter
+   *    classes deriving from `ScalaNumber` (such as `scala.BigInt` and
+   *    `scala.BigDecimal`) are unwrapped to pass a type which `Formatter`
    *    understands.
-   *  </p>
    *
-   *  @param locale an instance of java.util.Locale
+   *
+   *  @param locale an instance of `java.util.Locale`
    *  @param args the arguments used to instantiating the pattern.
    *  @throws java.lang.IllegalArgumentException
    */
diff --git a/src/library/scala/collection/immutable/StringOps.scala b/src/library/scala/collection/immutable/StringOps.scala
index 95509ab9d6..4949eb7056 100644
--- a/src/library/scala/collection/immutable/StringOps.scala
+++ b/src/library/scala/collection/immutable/StringOps.scala
@@ -15,6 +15,14 @@ package immutable
 import mutable.StringBuilder
 
 /**
+ * This class serves as a wrapper providing `String`s with all the operations
+ * found in indexed sequences. Where needed, instances of `String` object
+ * are implicitly converted into this class.
+ *
+ * The difference between this class and `WrappedString` is that calling transformer
+ * methods such as `filter` and `map` will yield a `String` object, whereas a
+ * `WrappedString` will remain a `WrappedString`.
+ *
  * @since 2.8
  */
 final class StringOps(override val repr: String) extends StringLike[String] {
diff --git a/src/library/scala/collection/immutable/WrappedString.scala b/src/library/scala/collection/immutable/WrappedString.scala
index e10b3ab0ee..cefbd96b5c 100644
--- a/src/library/scala/collection/immutable/WrappedString.scala
+++ b/src/library/scala/collection/immutable/WrappedString.scala
@@ -17,6 +17,13 @@ import mutable.{Builder, StringBuilder}
 import scala.util.matching.Regex
 
 /**
+ * This class serves as a wrapper augmenting `String`s with all the operations
+ * found in indexed sequences.
+ *
+ * The difference between this class and `StringOps` is that calling transformer
+ * methods such as `filter` and `map` will yield an object of type `WrappedString`
+ * rather than a `String`.
+ *
  * @since 2.8
  */
 class WrappedString(override val self: String) extends IndexedSeq[Char] with StringLike[WrappedString] with Proxy {