Cleaned up some hopelessly atrophied documentat...

Cleaned up some hopelessly atrophied documentation, no review.

2 files changed, 17 insertions, 42 deletions

diff --git a/src/library/scala/annotation/switch.scala b/src/library/scala/annotation/switch.scala
index e4cb8c55a2..3734686b27 100644
--- a/src/library/scala/annotation/switch.scala
+++ b/src/library/scala/annotation/switch.scala
@@ -7,32 +7,23 @@
 \*                                                                      */
 package scala.annotation
 
-/** <p>
- *    An annotation to be applied to a match expression.  If present,
- *    the compiler will verify that the match has been compiled to a
- *    <a href="http://java.sun.com/docs/books/jvms/second_edition/html/Instructions2.doc14.html"
- *    target="_top"><code>tableswitch</code></a> or
- *    <a href="http://java.sun.com/docs/books/jvms/second_edition/html/Instructions2.doc8.html#lookupswitch"
- *    target="_top"><code>lookupswitch</code></a>, and issue an error if it
- *    instead compiles into a series of conditional expressions.<br/>
- *    Example:
- *  </p>
- *  <pre>
- *    <b>def</b> fetchToken() {
- *      (ch: @switch) <b>match</b> {
- *        <b>case</b> ' ' | '\t' | CR | LF | FF <b>=&gt;</b>
- *          nextChar()
- *          fetchToken()
- *        <b>case</b> 'A' &#47;*..'Z'*&#47; | '$' | '_' | 'a' &#47;*..'z'*&#47; <b>=&gt;</b>
- *          putChar(ch)
- *          nextChar()
- *          getIdentRest()
- *        <b>case</b> ',' <b>=&gt;</b>
- *          nextChar(); token = COMMA
- *        // more cases
- *      }
- *    }</pre>
+/** An annotation to be applied to a match expression.  If present,
+ *  the compiler will verify that the match has been compiled to a
+ *  [[http://java.sun.com/docs/books/jvms/second_edition/html/Instructions2.doc14.html tableswitch]]
+ *  or [[http://java.sun.com/docs/books/jvms/second_edition/html/Instructions2.doc8.html#lookupswitch lookupswitch]]
+ *  and issue an error if it instead compiles into a series of conditional expressions.
+ *  Example usage:
+{{{
+  val Constant = 'Q'
+  def tokenMe(ch: Char) = (ch: @switch) match {
+    case ' ' | '\t' | '\n'  => 1
+    case 'A' | 'Z' | '$'    => 2
+    case '5' | Constant     => 3  // a non-literal may prevent switch generation: this would not compile
+    case _                  => 4
+  }
+}}}
  *
- *  @since 2.8
+ *  @author   Paul Phillips
+ *  @since    2.8
  */
 final class switch extends annotation.StaticAnnotation
diff --git a/src/library/scala/collection/immutable/List.scala b/src/library/scala/collection/immutable/List.scala
index d8c8268a2e..ea0bc7523c 100644
--- a/src/library/scala/collection/immutable/List.scala
+++ b/src/library/scala/collection/immutable/List.scala
@@ -292,22 +292,6 @@ sealed abstract class List[+A] extends LinearSeq[A]
   @deprecated("use `distinct' instead", "2.8.0")
   def removeDuplicates: List[A] = distinct
 
-  /** <p>
-   *    Sort the list according to the comparison function
-   *    `lt(e1: a, e2: a) =&gt; Boolean`,
-   *    which should be true iff `e1` precedes
-   *    `e2` in the desired ordering.
-   *  !!! todo: move sorting to IterableLike
-   *  </p>
-   *
-   *  @param lt the comparison function
-   *  @return   a list sorted according to the comparison function
-   *            `lt(e1: a, e2: a) =&gt; Boolean`.
-   *  @example <pre>
-   *    List("Steve", "Tom", "John", "Bob")
-   *      .sort((e1, e2) => (e1 compareTo e2) &lt; 0) =
-   *    List("Bob", "John", "Steve", "Tom")</pre>
-   */
   @deprecated("use `sortWith' instead", "2.8.0")
   def sort(lt : (A,A) => Boolean): List[A] = {
     /** Merge two already-sorted lists */