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

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

src/actors/scala/actors/Reaction.scala

@@ -23,9 +23,9 @@ private[actors] class KillActorException extends Throwable with ControlException
  *    <code>java.lang.Runnable</code></a>.
  *  </p>
  *
- *  @deprecated("this class is going to be removed in a future release")
  *  @author Philipp Haller
  */
+@deprecated
 class Reaction(a: Actor, f: PartialFunction[Any, Any], msg: Any) extends ActorTask(a, () => {
   if (f == null)
     a.act()

src/compiler/scala/tools/ant/Pack200Task.scala

@@ -99,7 +99,7 @@ class Pack200Task extends MatchingTask {
 \*============================================================================*/
 
   /** Gets the list of individual JAR files for processing.
-    * @returns The list of JAR files */
+    * @return The list of JAR files */
   private def getFileList: List[File] = {
     var files: List[File] = Nil
     val fs = getImplicitFileSet

src/compiler/scala/tools/ant/ScalaBazaar.scala

@@ -177,19 +177,19 @@ package scala.tools.ant {
 \******************************************************************************/
 
     /** Gets the value of the file attribute in a Scala-friendly form.
-      * @returns The file as a file. */
+      * @return The file as a file. */
     private def getName: String =
       if (name.isEmpty) error("Name attribute must be defined first.")
       else name.get
 
     /** Gets the value of the file attribute in a Scala-friendly form.
-      * @returns The file as a file. */
+      * @return The file as a file. */
     private def getFile: File =
       if (file.isEmpty) error("Member 'file' is empty.")
       else getProject().resolveFile(file.get.toString())
 
     /** Gets the value of the adfile attribute in a Scala-friendly form.
-      * @returns The adfile as a file. */
+      * @return The adfile as a file. */
     private def getAdfile: File =
       if (adfile.isEmpty) error("Member 'adfile' is empty.")
       else getProject().resolveFile(adfile.get.toString())

src/compiler/scala/tools/ant/ScalaTool.scala

@@ -166,12 +166,12 @@ class ScalaTool extends MatchingTask {
 \*============================================================================*/
 
     /** Gets the value of the classpath attribute in a Scala-friendly form.
-      * @returns The class path as a list of files. */
+      * @return The class path as a list of files. */
     private def getUnixclasspath: String =
       transposeVariableMarkup(classpath.mkString("", ":", "").replace('\\', '/'), "${", "}")
 
     /** Gets the value of the classpath attribute in a Scala-friendly form.
-      * @returns The class path as a list of files. */
+      * @return The class path as a list of files. */
     private def getWinclasspath: String =
       transposeVariableMarkup(classpath.mkString("", ";", "").replace('/', '\\'), "%", "%")
 

src/compiler/scala/tools/nsc/ScriptRunner.scala

@@ -240,7 +240,7 @@ object ScriptRunner
   /** Compile a script and then run the specified closure with
     * a classpath for the compiled script.
     *
-    * @returns true if compilation and the handler succeeds, false otherwise.
+    * @return true if compilation and the handler succeeds, false otherwise.
     */
   private def withCompiledScript(
     settings: GenericRunnerSettings,
@@ -300,7 +300,7 @@ object ScriptRunner
 
   /** Run a script after it has been compiled
    *
-   * @returns true if execution succeeded, false otherwise
+   * @return true if execution succeeded, false otherwise
    */
   private def runCompiled(
     settings: GenericRunnerSettings,
@@ -342,7 +342,7 @@ object ScriptRunner
   /** Run a script file with the specified arguments and compilation
    *  settings.
    *
-   * @returns true if compilation and execution succeeded, false otherwise.
+   * @return true if compilation and execution succeeded, false otherwise.
    */
   def runScript(
     settings: GenericRunnerSettings,
@@ -357,7 +357,7 @@ object ScriptRunner
 
   /** Run a command
    *
-   * @returns true if compilation and execution succeeded, false otherwise.
+   * @return true if compilation and execution succeeded, false otherwise.
    */
   def runCommand(
     settings: GenericRunnerSettings,

src/library/scala/Console.scala

@@ -83,7 +83,7 @@ object Console {
 
   /** Set the default output stream.
    *
-   *  @param@ out the new output stream.
+   *  @param out the new output stream.
    */
   def setOut(out: OutputStream): Unit =
     setOut(new PrintStream(out))

src/library/scala/Option.scala

@@ -45,7 +45,7 @@ sealed abstract class Option[+A] extends Product {
   def isDefined: Boolean = !isEmpty
 
   /** get the value of this option.
-   *  @requires that the option is nonEmpty.
+   *  @note The option must be nonEmpty.
    *  @throws Predef.NoSuchElementException if the option is empty.
    */
   def get: A

src/library/scala/annotation/elidable.scala

@@ -17,14 +17,14 @@ import java.util.logging.Level
  *  to scalac.  Methods marked elidable will be omitted from
  *  generated code if the priority given the annotation is lower
  *  than to the command line argument.  Examples:
- *
+ *  {{{
  *  import annotation.elidable._
  *
  *    @elidable(WARNING) def foo = log("foo")
  *    @elidable(FINE) def bar = log("bar")
  *
  *  scalac -Xelide-methods-below=1000
- *
+ *  }}}
  *  @since 2.8
  */
 final class elidable(final val level: Int) extends StaticAnnotation {}

src/library/scala/collection/BitSetLike.scala

@@ -28,11 +28,10 @@ import mutable.StringBuilder
  *  @since 2.8
  *  @define coll bitset
  *  @define Coll BitSet
- *  define bitsetinfo
+ *  @define bitsetinfo
  *  Bitsets are sets of non-negative integers which are represented as
  *  variable-size arrays of bits packed into 64-bit words. The size of a bitset is
  *  determined by the largest number stored in it.
-
  */
 trait BitSetLike[+This <: BitSetLike[This] with Set[Int]] extends SetLike[Int, This] { self =>
 

src/library/scala/collection/Iterator.scala

@@ -328,7 +328,7 @@ trait Iterator[+A] { self =>
   }
 
   /** Concatenates this iterator with another.
-   *  @that   the other iterator
+   *  @param   that   the other iterator
    *  @return  a new iterator that first yields the values produced by this
    *  iterator followed by the values produced by iterator `that`.
    *  @usecase def ++(that: => Iterator[A]): Iterator[A]
@@ -1288,7 +1288,7 @@ trait Iterator[+A] { self =>
    *  @param  xs    the array to fill.
    *  @param  start the starting index.
    *  @param  sz    the maximum number of elements to be read.
-   *  @pre          the array must be large enough to hold `sz` elements.
+   *  @note          the array must be large enough to hold `sz` elements.
    */
   @deprecated("use copyToArray instead")
   def readInto[B >: A](xs: Array[B], start: Int, sz: Int) {

src/library/scala/collection/MapLike.scala

@@ -71,7 +71,7 @@ self =>
 
   /** Optionally returns the value associated with a key.
    *
-   *  @key    the key value
+   *  @param  key    the key value
    *  @return an option value containing the value associated with `key` in this map,
    *          or `None` if none exists.
    */

src/library/scala/collection/SeqLike.scala

@@ -760,7 +760,7 @@ trait SeqLike[+A, +Repr] extends IterableLike[A, Repr] { self =>
    *              the desired ordering.
    *  @return     a $coll consisting of the elements of this $coll
    *              sorted according to the comparison function `lt`.
-   *  @ex {{{
+   *  @example {{{
    *    List("Steve", "Tom", "John", "Bob").sortWith(_.compareTo(_) < 0) =
    *    List("Bob", "John", "Steve", "Tom")
    *  }}}
@@ -805,7 +805,7 @@ trait SeqLike[+A, +Repr] extends IterableLike[A, Repr] { self =>
    *           sorted according to the ordering where `x < y` if
    *           `ord.lt(f(x), f(y))`.
    *
-   *  @ex {{{
+   *  @example {{{
    *    val words = "The quick brown fox jumped over the lazy dog".split(' ')
    *    // this works because scala.Ordering will implicitly provide an Ordering[Tuple2[Int, Char]]
    *    words.sortBy(x => (x.length, x.head))
@@ -823,7 +823,7 @@ trait SeqLike[+A, +Repr] extends IterableLike[A, Repr] { self =>
 
   /** Produces the range of all indices of this sequence.
    *
-   *  @range  a `Range` value from `0` to one less than the length of this $coll.
+   *  @return  a `Range` value from `0` to one less than the length of this $coll.
    */
   def indices: Range = 0 until length
 

src/library/scala/collection/TraversableLike.scala

@@ -1039,7 +1039,7 @@ self =>
    *               `end`. Inside, the string representations (w.r.t. the method `toString`)
    *               of all elements of this $coll are separated by the string `sep`.
    *
-   *  @ex  `List(1, 2, 3).mkString("(", "; ", ")") = "(1; 2; 3)"`
+   *  @example  `List(1, 2, 3).mkString("(", "; ", ")") = "(1; 2; 3)"`
    */
   def mkString(start: String, sep: String, end: String): String =
     addString(new StringBuilder(), start, sep, end).toString
@@ -1051,7 +1051,7 @@ self =>
    *               the string representations (w.r.t. the method `toString`)
    *               of all elements of this $coll are separated by the string `sep`.
    *
-   *  @ex  `List(1, 2, 3).mkString("|") = "1|2|3"`
+   *  @example  `List(1, 2, 3).mkString("|") = "1|2|3"`
    */
   def mkString(sep: String): String =
     addString(new StringBuilder(), sep).toString
@@ -1106,7 +1106,7 @@ self =>
   def addString(b: StringBuilder): StringBuilder = addString(b, "")
 
   /** Converts this $coll to a string
-   *  @returns  a string representation of this collection. By default this
+   *  @return   a string representation of this collection. By default this
    *            string consists of the `stringPrefix` of this $coll,
    *            followed by all elements separated by commas and enclosed in parentheses.
    */

src/library/scala/collection/generic/GenericTraversableTemplate.scala

@@ -100,8 +100,8 @@ trait GenericTraversableTemplate[+A, +CC[X] <: Traversable[X]] extends HasNewBui
   }
 
   /** Transposes this $coll of traversable collections into
-   *  @B the type of the elements of each traversable collection.
-   *  @asTraversable an implicit conversion which asserts that the element type of this
+   *  @tparam B the type of the elements of each traversable collection.
+   *  @param  asTraversable an implicit conversion which asserts that the element type of this
    *          $coll is a `Traversable`.
    *  @return a two-dimensional $coll of ${coll}s which has as ''n''th row
    *          the ''n''th column of this $coll.

src/library/scala/collection/generic/Growable.scala

@@ -16,7 +16,6 @@ package generic
  *  a `clear` method.
  *
  *  @author   Martin Odersky
- *  @owner   Martin Odersky
  *  @version 2.8
  *  @since   2.8
  *  @define coll growable collection

src/library/scala/collection/generic/Shrinkable.scala

@@ -15,7 +15,6 @@ package generic
  *  using a `-=` operator.
  *
  *  @author   Martin Odersky
- *  @owner   Martin Odersky
  *  @version 2.8
  *  @since   2.8
  *  @define coll shrinkable collection

src/library/scala/collection/immutable/List.scala

@@ -61,7 +61,7 @@ sealed abstract class List[+A] extends LinearSeq[A]
    *  @param x the element to prepend.
    *  @return  a list which contains `x` as first element and
    *           which continues with this list.
-   *  @ex `1 :: List(2, 3) = List(2, 3).::(1) = List(1, 2, 3)`
+   *  @example `1 :: List(2, 3) = List(2, 3).::(1) = List(1, 2, 3)`
    *  @usecase def ::(x: A): List[A]
    */
   def ::[B >: A] (x: B): List[B] =
@@ -71,7 +71,7 @@ sealed abstract class List[+A] extends LinearSeq[A]
    *  @param prefix  The list elements to prepend.
    *  @return a list resulting from the concatenation of the given
    *    list `prefix` and this list.
-   *  @ex `List(1, 2) ::: List(3, 4) = List(3, 4).:::(List(1, 2)) = List(1, 2, 3, 4)`
+   *  @example `List(1, 2) ::: List(3, 4) = List(3, 4).:::(List(1, 2)) = List(1, 2, 3, 4)`
    *  @usecase def :::(prefix: List[A]): List[A]
    */
   def :::[B >: A](prefix: List[B]): List[B] =
@@ -299,7 +299,7 @@ sealed abstract class List[+A] extends LinearSeq[A]
    *  @param lt the comparison function
    *  @return   a list sorted according to the comparison function
    *            `lt(e1: a, e2: a) => Boolean`.
-   *  @ex <pre>
+   *  @example <pre>
    *    List("Steve", "Tom", "John", "Bob")
    *      .sort((e1, e2) => (e1 compareTo e2) &lt; 0) =
    *    List("Bob", "John", "Steve", "Tom")</pre>

src/library/scala/collection/immutable/Range.scala

@@ -106,7 +106,7 @@ class Range(val start: Int, val end: Int, val step: Int) extends IndexedSeq[Int]
   final override def reverse: Range = new Range.Inclusive(last, start, -step)
 
   /** Make range inclusive.
-   * @pre if (step > 0) end != MaxInt else end != MinInt
+   * @note if (step > 0) end != MaxInt else end != MinInt
    */
   def inclusive = new Range.Inclusive(start, end, step)
 
@@ -148,18 +148,18 @@ object Range {
   def apply(start: Int, end: Int, step: Int): Range = new Range(start, end, step)
 
   /** Make an range from `start` to `end` inclusive with step value 1.
-   * @pre end != MaxInt
+   * @note end != MaxInt
    */
   def apply(start: Int, end: Int): Range with ByOne = new Range(start, end, 1) with ByOne
 
   /** Make an inclusive range from start to end with given step value.
-   * @pre step != 0
-   * @pre if (step > 0) end != MaxInt else end != MinInt
+   * @note step != 0
+   * @note if (step > 0) end != MaxInt else end != MinInt
    */
   def inclusive(start: Int, end: Int, step: Int): Range.Inclusive = new Inclusive(start, end, step)
 
   /** Make an inclusive range from start to end with step value 1.
-   * @pre end != MaxInt
+   * @note end != MaxInt
    */
   def inclusive(start: Int, end: Int): Range.Inclusive with ByOne = new Inclusive(start, end, 1) with ByOne
 

src/library/scala/collection/immutable/Stream.scala

@@ -420,9 +420,9 @@ object Stream extends SeqFactory[Stream] {
   import scala.collection.{Iterable, Seq, IndexedSeq}
 
   /** A builder for streams
-   *  @note: This builder is lazy only in the sense that it does not go downs the spine
-   *         of traversables that are added as a whole. If more laziness can be achieved,
-   *         this builder should be bypassed.
+   *  @note This builder is lazy only in the sense that it does not go downs the spine
+   *        of traversables that are added as a whole. If more laziness can be achieved,
+   *        this builder should be bypassed.
    */
   class StreamBuilder[A] extends scala.collection.mutable.LazyBuilder[A, Stream[A]] {
     def result: Stream[A] = (for (xs <- parts.iterator; x <- xs.toIterable.iterator) yield x).toStream

src/library/scala/collection/mutable/BufferLike.scala

@@ -30,10 +30,6 @@ import script._
  *  @author  Martin Odersky
  *  @author  Matthias Zenger
  *  @version 2.8
- *  @since 2.8
- *  @author Matthias Zenger
- *  @author Martin Odersky
- *  @version 2.8
  *  @since   2.8
  *  @define buffernote @note
  *    This trait provides most of the operations of a `Buffer` independently of its representation.

src/library/scala/collection/mutable/Builder.scala

@@ -48,7 +48,7 @@ trait Builder[-Elem, +To] extends Growable[Elem] {
    *  builder implementations are still required to work correctly even if the hint is
    *  wrong, i.e. a different number of elements is added.
    *
-   *  @size  the hint how many elements will be added.
+   *  @param size  the hint how many elements will be added.
    */
   def sizeHint(size: Int) {}
 

src/library/scala/collection/mutable/LinkedListLike.scala

@@ -55,7 +55,7 @@ trait LinkedListLike[A, This <: Seq[A] with LinkedListLike[A, This]] extends Seq
   }
 
   /** Insert linked list `that` at current position of this linked list
-   *  @pre this linked list is not empty
+   *  @note this linked list must not be empty
    */
   def insert(that: This): Unit = {
     require(nonEmpty, "insert into empty list")

src/library/scala/collection/mutable/ListBuffer.scala

@@ -231,7 +231,7 @@ final class ListBuffer[A]
    *
    *  @param  n  the index which refers to the element to delete.
    *  @return n  the element that was formerly at position <code>n</code>.
-   *  @pre       an element exists at position <code>n</code>
+   *  @note      an element must exists at position <code>n</code>
    *  @throws Predef.IndexOutOfBoundsException if <code>n</code> is out of bounds.
    */
   def remove(n: Int): A = {

src/library/scala/collection/mutable/MapLike.scala

@@ -195,11 +195,11 @@ trait MapLike[A, B, +This <: MapLike[A, B, This] with Map[A, B]]
   /** If given key is already in this map, returns associated value
    *  Otherwise, computes value from given expression `op`, stores with key
    *  in map and returns that value.
-   *  @param  the key to test
-   *  @param  the computation yielding the value to associate with `key`, if
-   *          `key` is previosuly unbound.
-   *  @return the value associated with key (either previously or as a result
-   *          of executing the method).
+   *  @param  key the key to test
+   *  @param  op  the computation yielding the value to associate with `key`, if
+   *              `key` is previosuly unbound.
+   *  @return     the value associated with key (either previously or as a result
+   *              of executing the method).
    */
   def getOrElseUpdate(key: A, op: => B): B =
     get(key) match {

src/library/scala/throws.scala

@@ -14,13 +14,13 @@ package scala
 /** <p>
  *    Annotation for specifying the exceptions thrown by a method.
  *    For example:
- *  </p><pre>
- *    <b>class</b> Reader(fname: String) {
- *      <b>private val</b> in =
- *        <b>new</b> BufferedReader(<b>new</b> <a class="java/io/FileReader" href="" target="_top">FileReader</a>(fname))
- *      @throws(classOf[<a class="java/io/IOException" href="" target="_top">IOException</a>])
- *      <b>def</b> read() = in.read()
- *    }</pre>
+ * {{{
+ * class Reader(fname: String) {
+ *   private val in = new BufferedReader(new FileReader(fname))
+ *   @throws(classOf[IOException])
+ *   def read() = in.read()
+ * }
+ * }}}
  *
  * @author  Nikolay Mihaylov
  * @version 1.0, 19/05/2006