diff options
author | Gilles Dubochet <gilles.dubochet@epfl.ch> | 2010-01-26 14:03:24 +0000 |
---|---|---|
committer | Gilles Dubochet <gilles.dubochet@epfl.ch> | 2010-01-26 14:03:24 +0000 |
commit | 6441087c31b9f550bb36d6afac4cfc7d4292b7cd (patch) | |
tree | bd2ab9f8d5c013b3f90460e6ea621d13208c5dad /src/library/scala | |
parent | 6975d16800499815a07c80c6d4fe85c2de693d96 (diff) | |
download | scala-6441087c31b9f550bb36d6afac4cfc7d4292b7cd.tar.gz scala-6441087c31b9f550bb36d6afac4cfc7d4292b7cd.tar.bz2 scala-6441087c31b9f550bb36d6afac4cfc7d4292b7cd.zip |
Fixed a number of faulty Scaladoc comments in l...
Fixed a number of faulty Scaladoc comments in library and compiler
sources. No review.
Diffstat (limited to 'src/library/scala')
32 files changed, 106 insertions, 148 deletions
diff --git a/src/library/scala/Console.scala b/src/library/scala/Console.scala index 7923b6be65..fc33fa07ef 100644 --- a/src/library/scala/Console.scala +++ b/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)) diff --git a/src/library/scala/Option.scala b/src/library/scala/Option.scala index 8511fa78a5..17bb6d0148 100644 --- a/src/library/scala/Option.scala +++ b/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 diff --git a/src/library/scala/annotation/elidable.scala b/src/library/scala/annotation/elidable.scala index 4f29c8f2ab..44ac7f050e 100644 --- a/src/library/scala/annotation/elidable.scala +++ b/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 {} diff --git a/src/library/scala/collection/BitSetLike.scala b/src/library/scala/collection/BitSetLike.scala index aac731fec9..4b87e75dcb 100644 --- a/src/library/scala/collection/BitSetLike.scala +++ b/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 => diff --git a/src/library/scala/collection/Iterator.scala b/src/library/scala/collection/Iterator.scala index 7dbc39f5b7..4e8a409efd 100644 --- a/src/library/scala/collection/Iterator.scala +++ b/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) { diff --git a/src/library/scala/collection/MapLike.scala b/src/library/scala/collection/MapLike.scala index 55cea1a678..0a00abeb47 100644 --- a/src/library/scala/collection/MapLike.scala +++ b/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. */ diff --git a/src/library/scala/collection/SeqLike.scala b/src/library/scala/collection/SeqLike.scala index 9802f63fa2..9aa3141395 100644 --- a/src/library/scala/collection/SeqLike.scala +++ b/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 diff --git a/src/library/scala/collection/TraversableLike.scala b/src/library/scala/collection/TraversableLike.scala index fc666ddb92..78890ca406 100644 --- a/src/library/scala/collection/TraversableLike.scala +++ b/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. */ diff --git a/src/library/scala/collection/generic/GenericTraversableTemplate.scala b/src/library/scala/collection/generic/GenericTraversableTemplate.scala index 0e3c3c203b..683f609686 100644 --- a/src/library/scala/collection/generic/GenericTraversableTemplate.scala +++ b/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. diff --git a/src/library/scala/collection/generic/Growable.scala b/src/library/scala/collection/generic/Growable.scala index 7950dee9de..fc3712d81e 100644 --- a/src/library/scala/collection/generic/Growable.scala +++ b/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 diff --git a/src/library/scala/collection/generic/Shrinkable.scala b/src/library/scala/collection/generic/Shrinkable.scala index bd773a97f9..fafeb51141 100644 --- a/src/library/scala/collection/generic/Shrinkable.scala +++ b/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 diff --git a/src/library/scala/collection/immutable/List.scala b/src/library/scala/collection/immutable/List.scala index 2088f3ac78..415a31a02e 100644 --- a/src/library/scala/collection/immutable/List.scala +++ b/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) < 0) = * List("Bob", "John", "Steve", "Tom")</pre> diff --git a/src/library/scala/collection/immutable/Range.scala b/src/library/scala/collection/immutable/Range.scala index 47a97664de..cdf8cc6426 100644 --- a/src/library/scala/collection/immutable/Range.scala +++ b/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 diff --git a/src/library/scala/collection/immutable/Stream.scala b/src/library/scala/collection/immutable/Stream.scala index 1377fbe59d..7b9db5e21e 100644 --- a/src/library/scala/collection/immutable/Stream.scala +++ b/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 diff --git a/src/library/scala/collection/mutable/BufferLike.scala b/src/library/scala/collection/mutable/BufferLike.scala index 3516a60233..58dd7f139b 100644 --- a/src/library/scala/collection/mutable/BufferLike.scala +++ b/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. diff --git a/src/library/scala/collection/mutable/Builder.scala b/src/library/scala/collection/mutable/Builder.scala index c7932ae344..1706f598ec 100644 --- a/src/library/scala/collection/mutable/Builder.scala +++ b/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) {} diff --git a/src/library/scala/collection/mutable/LinkedListLike.scala b/src/library/scala/collection/mutable/LinkedListLike.scala index c363609762..2523ece370 100644 --- a/src/library/scala/collection/mutable/LinkedListLike.scala +++ b/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") diff --git a/src/library/scala/collection/mutable/ListBuffer.scala b/src/library/scala/collection/mutable/ListBuffer.scala index 686b1acf8d..43892e3e87 100644 --- a/src/library/scala/collection/mutable/ListBuffer.scala +++ b/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 = { diff --git a/src/library/scala/collection/mutable/MapLike.scala b/src/library/scala/collection/mutable/MapLike.scala index a1bb25910a..ad350f4263 100644 --- a/src/library/scala/collection/mutable/MapLike.scala +++ b/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 { diff --git a/src/library/scala/throws.scala b/src/library/scala/throws.scala index 500db0a30a..b932ccc7ac 100644 --- a/src/library/scala/throws.scala +++ b/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 diff --git a/src/library/scala/util/Sorting.scala b/src/library/scala/util/Sorting.scala index 73228b53d5..5585457f07 100644 --- a/src/library/scala/util/Sorting.scala +++ b/src/library/scala/util/Sorting.scala @@ -12,22 +12,19 @@ package scala.util import scala.reflect.ClassManifest -/** <p> - * 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 - * operate directly on a subset of value types are also provided. These - * implementations are derived from those in the Sun JDK. - * </p> - * <p> - * 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 - * objects when the prior ordering should be preserved, where possible. - * </p> - * - * @author Ross Judson - * @version 1.0 - */ +/** 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 + * 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 + * objects when the prior ordering should be preserved, where possible. + * + * @author Ross Judson + * @version 1.0 + */ object Sorting { /** Provides implicit access to sorting on arbitrary sequences of orderable @@ -49,7 +46,7 @@ object Sorting { def quickSort(a: Array[Float]) = sort1(a, 0, a.length) /** Sort an array of K where K is Ordered, preserving the existing order - where the values are equal. */ + * where the values are equal. */ def stableSort[K <% Ordered[K] : ClassManifest](a: Array[K]) { stableSort(a, 0, a.length-1, new Array[K](a.length), (a:K, b:K) => a < b) } diff --git a/src/library/scala/util/parsing/ast/Binders.scala b/src/library/scala/util/parsing/ast/Binders.scala index b397e900da..7a9b8e5dcd 100644 --- a/src/library/scala/util/parsing/ast/Binders.scala +++ b/src/library/scala/util/parsing/ast/Binders.scala @@ -127,10 +127,8 @@ trait Binders extends AbstractSyntax with Mappable { * (e.g. 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 - * @pre canAddBinder(b) - * @post binds(b) - * @post getElementFor(b) eq b + * 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) } @@ -140,7 +138,7 @@ trait Binders extends AbstractSyntax with Mappable { * 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)? * - * @returns true if `b' had not been added yet + * @return true if `b' had not been added yet */ def canAddBinder(b: binderType): Boolean = !binds(b) @@ -150,17 +148,15 @@ trait Binders extends AbstractSyntax with Mappable { * 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 + * @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' - * @pre binds(b) - * @post getElementFor(b) eq value + * @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 - * @pre binds(b) + * @param b the contained binder whose current value should be returned `binds(b)` must hold. */ def getElementFor(b: binderType): Element = substitution(b) @@ -173,7 +169,7 @@ trait Binders extends AbstractSyntax with Mappable { 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 {} @@ -193,7 +189,7 @@ trait Binders extends AbstractSyntax with Mappable { * 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'. * - * @invar scope.binds(el) + * @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. @@ -300,7 +296,7 @@ trait Binders extends AbstractSyntax with Mappable { * * The name `sequence' comes from the fact that this method's type is equal to the type of monadic sequence. * - * @pre !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]] = diff --git a/src/library/scala/util/parsing/combinator/Parsers.scala b/src/library/scala/util/parsing/combinator/Parsers.scala index 6fe35ad3b0..183465f84d 100644 --- a/src/library/scala/util/parsing/combinator/Parsers.scala +++ b/src/library/scala/util/parsing/combinator/Parsers.scala @@ -48,35 +48,21 @@ import scala.annotation.tailrec * of the input. * </p> * - * @requires Elem the type of 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.)</p> - *<p> - * @provides Input = Reader[Elem] - * The type of input the parsers in this component expect.</p> - *<p> - * @provides Parser[+T] extends (Input => ParseResult[T]) - * Essentially, a `Parser[T]' is a function from `Input' to `ParseResult[T]'.</p> - *<p> - * @provides ParseResult[+T] is like an `Option[T]', in the sense that it is either - * `Success[T]', which consists of some result (:T) (and the rest of the input) or - * `Failure[T]', which provides an error message (and the rest of the input).</p> - * * @author Martin Odersky, Iulian Dragos, Adriaan Moors */ trait Parsers { - /** the type of input elements */ + /** the type of input elements the provided parsers consume (When consuming invidual characters, a parser is typically + * called a ``scanner'', which produces ``tokens'' that are consumed by what is normally called a ``parser''. + * Nonetheless, the same principles apply, regardless of the input type.) */ type Elem - /** The parser input is an abstract reader of input elements */ + /** The parser input is an abstract reader of input elements, i.e. the type of input the parsers in this component + * expect. */ type Input = Reader[Elem] - /** A base class for parser results. - * A result is either successful or not (failure may be fatal, i.e., - * an Error, or not, i.e., a Failure) - * On success, provides a result of type <code>T</code>. - */ + /** A base class for parser results. A result is either successful or not (failure may be fatal, i.e., an Error, or + * not, i.e., a Failure). On success, provides a result of type `T` which consists of some result (and the rest of + * the input). */ sealed abstract class ParseResult[+T] { /** Functional composition of ParseResults * diff --git a/src/library/scala/util/parsing/combinator/lexical/Scanners.scala b/src/library/scala/util/parsing/combinator/lexical/Scanners.scala index 07f4975cf8..5b01049c91 100644 --- a/src/library/scala/util/parsing/combinator/lexical/Scanners.scala +++ b/src/library/scala/util/parsing/combinator/lexical/Scanners.scala @@ -23,13 +23,6 @@ import scala.util.parsing.input._ * {@see StdLexical}, for more functionality. * </p> * - * @requires token a parser that produces a token (from a stream of characters) - * @requires whitespace a unit-parser for white-space - * @provides Scanner essentially a parser that parses a stream of characters - * to produce `Token's, which are typically passed to a - * syntactical parser (which operates on `Token's, not on - * individual characters). - * * @author Martin Odersky, Adriaan Moors */ trait Scanners extends Parsers { diff --git a/src/library/scala/util/parsing/combinator/syntactical/TokenParsers.scala b/src/library/scala/util/parsing/combinator/syntactical/TokenParsers.scala index 01557c32a7..ff2c552deb 100644 --- a/src/library/scala/util/parsing/combinator/syntactical/TokenParsers.scala +++ b/src/library/scala/util/parsing/combinator/syntactical/TokenParsers.scala @@ -12,13 +12,7 @@ package scala.util.parsing.combinator.syntactical import scala.util.parsing.combinator._ -/** <p> - * This is the core component for token-based parsers. - * </p> - * <p> - * @requires lexical a component providing the tokens consumed by the - * parsers in this component. - * </p> +/** This is the core component for token-based parsers. * * @author Martin Odersky, Adriaan Moors */ diff --git a/src/library/scala/xml/Node.scala b/src/library/scala/xml/Node.scala index f206140fd4..500c11e41d 100644 --- a/src/library/scala/xml/Node.scala +++ b/src/library/scala/xml/Node.scala @@ -213,9 +213,10 @@ abstract class Node extends NodeSeq { * Martin to Burak: to do: if you make this method abstract, the compiler will now * complain if there's no implementation in a subclass. Is this what we want? Note that * this would break doc/DocGenator and doc/ModelToXML, with an error message like: -doc\DocGenerator.scala:1219: error: object creation impossible, since there is a deferred declaration of method text in class Node of type => String which is not implemented in a subclass - new SpecialNode { - ^ - */ + * {{{ + * doc\DocGenerator.scala:1219: error: object creation impossible, since there is a deferred declaration of method text in class Node of type => String which is not implemented in a subclass + * new SpecialNode { + * ^ + * }}} */ override def text: String = super.text } diff --git a/src/library/scala/xml/PrettyPrinter.scala b/src/library/scala/xml/PrettyPrinter.scala index 1fb922eb95..17e7db679a 100644 --- a/src/library/scala/xml/PrettyPrinter.scala +++ b/src/library/scala/xml/PrettyPrinter.scala @@ -23,7 +23,7 @@ import Utility.sbToString * @version 1.0 * * @param width the width to fit the output into - * @step indentation + * @param step indentation */ class PrettyPrinter(width: Int, step: Int) { diff --git a/src/library/scala/xml/Utility.scala b/src/library/scala/xml/Utility.scala index 1cfe9c79c9..c39c787bfe 100644 --- a/src/library/scala/xml/Utility.scala +++ b/src/library/scala/xml/Utility.scala @@ -84,7 +84,7 @@ object Utility extends AnyRef with parsing.TokenTests object Escapes { /** For reasons unclear escape and unescape are a long ways from - being logical inverses. */ + * being logical inverses. */ val pairs = Map( "lt" -> '<', "gt" -> '>', diff --git a/src/library/scala/xml/dtd/ElementValidator.scala b/src/library/scala/xml/dtd/ElementValidator.scala index cc37e2b527..9ebed8d87c 100644 --- a/src/library/scala/xml/dtd/ElementValidator.scala +++ b/src/library/scala/xml/dtd/ElementValidator.scala @@ -95,7 +95,7 @@ class ElementValidator() extends Function1[Node,Boolean] { } /** check children, return true if conform to content model - * @pre contentModel != null + * @note contentModel != null */ def check(nodes: Seq[Node]): Boolean = contentModel match { case ANY => true @@ -120,7 +120,7 @@ class ElementValidator() extends Function1[Node,Boolean] { } /** applies various validations - accumulates error messages in exc - * @todo: fail on first error, ignore other errors (rearranging conditions) + * @todo fail on first error, ignore other errors (rearranging conditions) */ def apply(n: Node): Boolean = //- ? check children diff --git a/src/library/scala/xml/include/XIncludeException.scala b/src/library/scala/xml/include/XIncludeException.scala index 26c66f9b1d..a671f32dca 100644 --- a/src/library/scala/xml/include/XIncludeException.scala +++ b/src/library/scala/xml/include/XIncludeException.scala @@ -43,7 +43,7 @@ class XIncludeException(message: String) extends Exception(message) { * This method allows you to store the original exception. * * @param nestedException the underlying exception which - caused the XIncludeException to be thrown + * caused the XIncludeException to be thrown */ def setRootCause(nestedException: Throwable ) { this.rootCause = nestedException diff --git a/src/library/scala/xml/parsing/ConstructingParser.scala b/src/library/scala/xml/parsing/ConstructingParser.scala index f029fc745a..00f195e9fd 100644 --- a/src/library/scala/xml/parsing/ConstructingParser.scala +++ b/src/library/scala/xml/parsing/ConstructingParser.scala @@ -25,28 +25,27 @@ object ConstructingParser { } /** An xml parser. parses XML and invokes callback methods of a MarkupHandler. - * Don't forget to call next.ch on a freshly instantiated parser in order to - * initialize it. If you get the parser from the object method, initialization - * is already done for you. - * - *<pre> -object parseFromURL { - def main(args:Array[String]): Unit = { - val url = args(0); - val src = scala.io.Source.fromURL(url); - val cpa = scala.xml.parsing.ConstructingParser.fromSource(src, false); // fromSource initializes automatically - val doc = cpa.document(); - - // let's see what it is - val ppr = new scala.xml.PrettyPrinter(80,5); - val ele = doc.docElem; - Console.println("finished parsing"); - val out = ppr.format(ele); - Console.println(out); - } -} -</pre> - */ + * Don't forget to call next.ch on a freshly instantiated parser in order to + * initialize it. If you get the parser from the object method, initialization + * is already done for you. + * + * {{{ + * object parseFromURL { + * def main(args:Array[String]): Unit = { + * val url = args(0); + * val src = scala.io.Source.fromURL(url); + * val cpa = scala.xml.parsing.ConstructingParser.fromSource(src, false); // fromSource initializes automatically + * val doc = cpa.document(); + * + * // let's see what it is + * val ppr = new scala.xml.PrettyPrinter(80,5); + * val ele = doc.docElem; + * Console.println("finished parsing"); + * val out = ppr.format(ele); + * Console.println(out); + * } + * } + * }}} */ class ConstructingParser(val input: Source, val preserveWS: Boolean) extends ConstructingHandler with ExternalSources diff --git a/src/library/scala/xml/parsing/MarkupParser.scala b/src/library/scala/xml/parsing/MarkupParser.scala index 2f7f48c765..fdc216c3cd 100644 --- a/src/library/scala/xml/parsing/MarkupParser.scala +++ b/src/library/scala/xml/parsing/MarkupParser.scala @@ -719,8 +719,7 @@ trait MarkupParser extends MarkupParserCommon with TokenTests nextch } - /** "rec-xml/#ExtSubset" pe references may not occur within markup - declarations + /** "rec-xml/#ExtSubset" pe references may not occur within markup declarations */ def intSubset() { //Console.println("(DEBUG) intSubset()") |