diff options
author | michelou <michelou@epfl.ch> | 2011-07-15 16:25:42 +0000 |
---|---|---|
committer | michelou <michelou@epfl.ch> | 2011-07-15 16:25:42 +0000 |
commit | a0476af6bce252a7e724e6e99e50a80f0021ce78 (patch) | |
tree | 8d1cc42b8ae676330d776e7b722afa623585818b | |
parent | d79493bb728b4d47a1e333a0d8451b8e73c08041 (diff) | |
download | scala-a0476af6bce252a7e724e6e99e50a80f0021ce78.tar.gz scala-a0476af6bce252a7e724e6e99e50a80f0021ce78.tar.bz2 scala-a0476af6bce252a7e724e6e99e50a80f0021ce78.zip |
2nd round of clean ups (see r25285)
99 files changed, 1519 insertions, 1515 deletions
diff --git a/src/library/scala/Application.scala b/src/library/scala/Application.scala index 021e499530..5b1098bd72 100644 --- a/src/library/scala/Application.scala +++ b/src/library/scala/Application.scala @@ -47,7 +47,7 @@ import scala.compat.Platform.currentTime * fail to optimize or JIT the code in the body of an `object` extending * `Application`. This can lead to a significant performance degradation. * - * It is recommended to use the `[[scala.App]]` trait instead. + * It is recommended to use the [[scala.App]] trait instead. * {{{ * object Main { * def main(args: Array[String]) { diff --git a/src/library/scala/Array.scala b/src/library/scala/Array.scala index 060a5250ba..a83f9f5679 100644 --- a/src/library/scala/Array.scala +++ b/src/library/scala/Array.scala @@ -35,6 +35,14 @@ class FallbackArrayBuilding { } /** Utility methods for operating on arrays. + * For example: + * {{{ + * val a = Array(1, 2) + * val b = Array.ofDim[Int](2) + * val c = Array.concat(a, b) + * }}} + * where the array objects `a`, `b` and `c` have respectively the values + * `Array(1, 2)`, `Array(0, 0)` and `Array(1, 2, 0, 0)`. * * @author Martin Odersky * @version 1.0 diff --git a/src/library/scala/Console.scala b/src/library/scala/Console.scala index 7eadcb7b09..5e62df6c71 100644 --- a/src/library/scala/Console.scala +++ b/src/library/scala/Console.scala @@ -253,7 +253,7 @@ object Console { */ def printf(text: String, args: Any*) { out.print(text format (args : _*)) } - /** Read a full line from the default input. Returns <code>null</code> if the end of the + /** Read a full line from the default input. Returns `null` if the end of the * input stream has been reached. * * @return the string read from the terminal or null if the end of stream was reached. @@ -397,14 +397,14 @@ object Console { s.toDouble } - /** Reads in some structured input (from the default input), specified by a format specifier. - * See class <code>java.text.MessageFormat</code> for details of + /** Reads in some structured input (from the default input), specified by + * a format specifier. See class `java.text.MessageFormat` for details of * the format specification. * * @param format the format of the input. * @return a list of all extracted values. - * @throws java.io.EOFException if the end of the - * input stream has been reached. + * @throws java.io.EOFException if the end of the input stream has been + * reached. */ def readf(format: String): List[Any] = { val s = readLine() @@ -414,8 +414,9 @@ object Console { textComponents(new MessageFormat(format).parse(s)) } - /** Reads in some structured input (from the default input), specified by a format specifier, returning - * only the first value extracted, according to the format specification. + /** Reads in some structured input (from the default input), specified by + * a format specifier, returning only the first value extracted, according + * to the format specification. * * @param format format string, as accepted by `readf`. * @return The first value that was extracted from the input diff --git a/src/library/scala/Enumeration.scala b/src/library/scala/Enumeration.scala index 61609be22f..563b2d70c4 100644 --- a/src/library/scala/Enumeration.scala +++ b/src/library/scala/Enumeration.scala @@ -11,18 +11,17 @@ package scala import scala.collection.{ mutable, immutable, generic, SetLike } import java.lang.reflect.{ Modifier, Method => JMethod, Field => JField } -/** - * Defines a finite set of values specific to the enumeration. Typically - * these values enumerate all possible forms something can take and provide a - * lightweight alternative to case classes. +/** Defines a finite set of values specific to the enumeration. Typically + * these values enumerate all possible forms something can take and provide + * a lightweight alternative to case classes. * - * Each call to a `Value` method adds a new unique value to the - * enumeration. To be accessible, these values are usually defined as - * `val` members of the evaluation. + * Each call to a `Value` method adds a new unique value to the enumeration. + * To be accessible, these values are usually defined as `val` members of + * the evaluation. * - * All values in an enumeration share a common, unique type defined as the - * `Value` type member of the enumeration (`Value` - * selected on the stable identifier path of the enumeration instance). + * All values in an enumeration share a common, unique type defined as the + * `Value` type member of the enumeration (`Value` selected on the stable + * identifier path of the enumeration instance). * * @example {{{ * object Main extends Application { @@ -108,29 +107,30 @@ abstract class Enumeration(initial: Int, names: String*) extends Serializable { */ final def apply(x: Int): Value = vmap(x) - /** Returns a Value from this Enumeration whose name matches - * the argument <var>s</var>. + /** + * Return a `Value` from this `Enumeration` whose name matches + * the argument `s`. * - * You can pass a String* set of names to the constructor, or - * initialize each Enumeration with Value(String). Otherwise, the - * names are determined automatically through reflection. + * You can pass a String* set of names to the constructor, or initialize + * each `Enumeration` with `Value(String)`. Otherwise, the names are + * determined automatically through reflection. * * Note the change here wrt 2.7 is intentional. You should know whether - * a name is in an Enumeration beforehand. If not, just use find on + * a name is in an `Enumeration` beforehand. If not, just use find on * values. * - * @param s an Enumeration name - * @return the Value of this Enumeration if its name matches <var>s</var> - * @throws java.util.NoSuchElementException if no Value with a matching - * name is in this Enumeration + * @param s an `Enumeration` name + * @return the `Value` of this `Enumeration` if its name matches `s` + * @throws java.util.NoSuchElementException if no `Value` with a matching + * name is in this `Enumeration` */ final def withName(s: String): Value = values.find(_.toString == s).get /** Creates a fresh value, part of this enumeration. */ protected final def Value: Value = Value(nextId) - /** Creates a fresh value, part of this enumeration, identified by the integer - * `i`. + /** Creates a fresh value, part of this enumeration, identified by the + * integer `i`. * * @param i An integer that identifies this value at run-time. It must be * unique amongst all values of the enumeration. @@ -197,16 +197,15 @@ abstract class Enumeration(initial: Int, names: String*) extends Serializable { override def hashCode: Int = id.## } - /** A class implementing the <a href="Enumeration.Value.html" - * target="contentFrame">`Value`</a> type. This class can be - * overridden to change the enumeration's naming and integer identification - * behaviour. + /** A class implementing the [[scala.Enumeration.Value]] type. This class + * can be overridden to change the enumeration's naming and integer + * identification behaviour. */ @SerialVersionUID(0 - 3501153230598116017L) protected class Val(i: Int, name: String) extends Value with Serializable { - def this(i: Int) = this(i, nextNameOrNull) - def this(name: String) = this(nextId, name) - def this() = this(nextId) + def this(i: Int) = this(i, nextNameOrNull) + def this(name: String) = this(nextId, name) + def this() = this(nextId) assert(!vmap.isDefinedAt(i), "Duplicate id: " + i) vmap(i) = this @@ -226,9 +225,10 @@ abstract class Enumeration(initial: Int, names: String*) extends Serializable { } } - /** A class for sets of values + /** A class for sets of values. * Iterating through this set will yield values in increasing order of their ids. - * @param ids The set of ids of values, organized as a SortedSet. + * + * @param ids The set of ids of values, organized as a `SortedSet`. */ class ValueSet private[Enumeration] (val ids: immutable.SortedSet[Int]) extends Set[Value] with SetLike[Value, ValueSet] { override def empty = ValueSet.empty diff --git a/src/library/scala/Function.scala b/src/library/scala/Function.scala index a6e2a2d056..0e2d357892 100644 --- a/src/library/scala/Function.scala +++ b/src/library/scala/Function.scala @@ -1,7 +1,7 @@ /* __ *\ ** ________ ___ / / ___ Scala API ** ** / __/ __// _ | / / / _ | (c) 2003-2011, LAMP/EPFL ** -** __\ \/ /__/ __ |/ /__/ __ | ** +** __\ \/ /__/ __ |/ /__/ __ | http://scala-lang.org/ ** ** /____/\___/_/ |_/____/_/ | | ** ** |/ ** \* */ @@ -16,9 +16,8 @@ package scala * @version 1.0, 29/11/2006 */ object Function { - /** Given a sequence of functions <code>f<sub>1</sub></code>, ..., - * <code>f<sub>n</sub></code>, return the function <code>f<sub>1</sub> - * andThen ... andThen f<sub>n</sub></code>. + /** Given a sequence of functions `f,,1,,`, ..., `f,,n,,`, return the + * function `f,,1,, andThen ... andThen f,,n,,`. * * @param fs The given sequence of functions * @return ... @@ -28,15 +27,17 @@ object Function { /** The constant function */ def const[T, U](x: T)(y: U): T = x - /** Turns a function `A => Option[B]` into a `PartialFunction[A, B]`. Important note: - * this transformation implies the original function will be called 2 or more - * times on each logical invocation, because the only way to supply an implementation - * of isDefinedAt is to call the function and examine the return value. + /** Turns a function `A => Option[B]` into a `PartialFunction[A, B]`. * - * @param f a function T => Option[R] + * '''Important note''': this transformation implies the original function + * will be called 2 or more times on each logical invocation, because the + * only way to supply an implementation of `isDefinedAt` is to call the + * function and examine the return value. + * + * @param f a function `T => Option[R]` * @return a partial function defined for those inputs where - * f returns Some(_) and undefined where f returns None. - * @see PartialFunction#lift + * f returns `Some(_)` and undefined where `f` returns `None`. + * @see [[scala.PartialFunction#lift]] */ def unlift[T, R](f: T => Option[R]): PartialFunction[T, R] = new PartialFunction[T, R] { def apply(x: T): R = f(x).get diff --git a/src/library/scala/Math.scala b/src/library/scala/Math.scala index 706537333a..87db3ea877 100644 --- a/src/library/scala/Math.scala +++ b/src/library/scala/Math.scala @@ -9,9 +9,9 @@ package scala -/** The object <code>Math</code> contains methods for performing basic numeric - * operations such as the elementary exponential, logarithm, square root, and - * trigonometric functions. +/** The object `Math` contains methods for performing basic numeric + * operations such as the elementary exponential, logarithm, square root, + * and trigonometric functions. */ @deprecated("use the scala.math package object instead.\n(Example package object usage: scala.math.Pi )", "2.8.0") object Math extends MathCommon { @@ -92,4 +92,4 @@ object Math extends MathCommon { /** Positive infinity of type [[scala.Double]]. */ @deprecated("Use `scala.Double.PositiveInfinity` instead", "2.8.0") val POS_INF_DOUBLE = java.lang.Double.POSITIVE_INFINITY -}
\ No newline at end of file +} diff --git a/src/library/scala/MathCommon.scala b/src/library/scala/MathCommon.scala index a2450fd461..b7b54d50fa 100644 --- a/src/library/scala/MathCommon.scala +++ b/src/library/scala/MathCommon.scala @@ -9,23 +9,22 @@ package scala -/** Common code between the deprecated scala.Math object and - * the scala.math package object. +/** Common code between the deprecated `scala.Math` object and + * the `scala.math` package object. */ private[scala] class MathCommon { - /** The <code>double</code> value that is closer than any other to - * <code>e</code>, the base of the natural logarithms. + /** The `double` value that is closer than any other to `e`, the base of + * the natural logarithms. */ val E = java.lang.Math.E - /** The <code>double</code> value that is closer than any other to - * <code>pi</code>, the ratio of the circumference of a circle to its - * diameter. + /** The `double` value that is closer than any other to `pi`, the ratio of + * the circumference of a circle to its diameter. */ val Pi = java.lang.Math.PI - /** Returns a <code>double</code> value with a positive sign, greater than - * or equal to <code>0.0</code> and less than <code>1.0</code>. + /** Returns a `double` value with a positive sign, greater than or equal + * to `0.0` and less than `1.0`. */ def random: Double = java.lang.Math.random() @@ -40,7 +39,7 @@ private[scala] class MathCommon { * angle measured in radians. * * @param x an angle, in degrees - * @return the measurement of the angle <code>x</code> in radians. + * @return the measurement of the angle `x` in radians. */ def toRadians(x: Double): Double = java.lang.Math.toRadians(x) @@ -48,16 +47,15 @@ private[scala] class MathCommon { * angle measured in degrees. * * @param x angle, in radians - * @return the measurement of the angle <code>x</code> in degrees. + * @return the measurement of the angle `x` in degrees. */ def toDegrees(x: Double): Double = java.lang.Math.toDegrees(x) - /** Returns Euler's number <code>e</code> raised to the power of a - * <code>double</code> value. + /** Returns Euler's number `e` raised to the power of a `double` value. * - * @param x the exponent to raise <code>e</code> to. - * @return the value <code>e<sup>a</sup></code>, where <code>e</code> - * is the base of the natural logarithms. + * @param x the exponent to raise `e` to. + * @return the value `e^a^`, where `e` is the base of the natural + * logarithms. */ def exp(x: Double): Double = java.lang.Math.exp(x) def log(x: Double): Double = java.lang.Math.log(x) @@ -67,23 +65,22 @@ private[scala] class MathCommon { def ceil(x: Double): Double = java.lang.Math.ceil(x) def floor(x: Double): Double = java.lang.Math.floor(x) - /** Returns the <code>double</code> value that is closest in value to the + /** Returns the `double` value that is closest in value to the * argument and is equal to a mathematical integer. * - * @param x a <code>double</code> value + * @param x a `double` value * @return the closest floating-point value to a that is equal to a * mathematical integer. */ def rint(x: Double): Double = java.lang.Math.rint(x) - /** Converts rectangular coordinates <code>(x, y)</code> to polar - * <code>(r, theta)</code>. + /** Converts rectangular coordinates `(x, y)` to polar `(r, theta)`. * * @param x the ordinate coordinate * @param y the abscissa coordinate - * @return the <em>theta</em> component of the point <code>(r, theta)</code> - * in polar coordinates that corresponds to the point - * <code>(x, y)</code> in Cartesian coordinates. + * @return the ''theta'' component of the point `(r, theta)` in polar + * coordinates that corresponds to the point `(x, y)` in + * Cartesian coordinates. */ def atan2(y: Double, x: Double): Double = java.lang.Math.atan2(y, x) @@ -92,15 +89,14 @@ private[scala] class MathCommon { * * @param x the base. * @param y the exponent. - * @return the value <code>x<sup>y</sup></code>. + * @return the value `x^y^`. */ def pow(x: Double, y: Double): Double = java.lang.Math.pow(x, y) - /** Returns the closest <code>long</code> to the argument. + /** Returns the closest `long` to the argument. * - * @param x a floating-point value to be rounded to a <code>long</code>. - * @return the value of the argument rounded to the nearest - * <code>long</code> value. + * @param x a floating-point value to be rounded to a `long`. + * @return the value of the argument rounded to the nearest`long` value. */ def round(x: Float): Int = java.lang.Math.round(x) def round(x: Double): Long = java.lang.Math.round(x) diff --git a/src/library/scala/Predef.scala b/src/library/scala/Predef.scala index acc9e2b3ad..124858273d 100644 --- a/src/library/scala/Predef.scala +++ b/src/library/scala/Predef.scala @@ -15,9 +15,8 @@ import generic.CanBuildFrom import annotation.{ elidable, implicitNotFound } import annotation.elidable.ASSERTION -/** The <code>Predef</code> object provides definitions that are - * accessible in all Scala compilation units without explicit - * qualification. +/** The `Predef` object provides definitions that are accessible in all Scala + * compilation units without explicit qualification. */ object Predef extends LowPriorityImplicits { /** Return the runtime representation of a class type. This is a stub method. @@ -76,9 +75,9 @@ object Predef extends LowPriorityImplicits { // errors and asserts ------------------------------------------------- - /** Tests an expression, throwing an AssertionError if false. - * Calls to this method will not be generated if -Xelide-below - * is at least ASSERTION. + /** Tests an expression, throwing an `AssertionError` if false. + * Calls to this method will not be generated if `-Xelide-below` + * is at least `ASSERTION`. * * @see elidable * @param p the expression to test @@ -89,9 +88,9 @@ object Predef extends LowPriorityImplicits { throw new java.lang.AssertionError("assertion failed") } - /** Tests an expression, throwing an AssertionError if false. - * Calls to this method will not be generated if -Xelide-below - * is at least ASSERTION. + /** Tests an expression, throwing an `AssertionError` if false. + * Calls to this method will not be generated if `-Xelide-below` + * is at least `ASSERTION`. * * @see elidable * @param p the expression to test @@ -103,11 +102,11 @@ object Predef extends LowPriorityImplicits { throw new java.lang.AssertionError("assertion failed: "+ message) } - /** Tests an expression, throwing an AssertionError if false. + /** Tests an expression, throwing an `AssertionError` if false. * This method differs from assert only in the intent expressed: * assert contains a predicate which needs to be proven, while * assume contains an axiom for a static checker. Calls to this method - * will not be generated if -Xelide-below is at least ASSERTION. + * will not be generated if `-Xelide-below` is at least `ASSERTION`. * * @see elidable * @param p the expression to test @@ -118,11 +117,11 @@ object Predef extends LowPriorityImplicits { throw new java.lang.AssertionError("assumption failed") } - /** Tests an expression, throwing an AssertionError if false. + /** Tests an expression, throwing an `AssertionError` if false. * This method differs from assert only in the intent expressed: * assert contains a predicate which needs to be proven, while * assume contains an axiom for a static checker. Calls to this method - * will not be generated if -Xelide-below is at least ASSERTION. + * will not be generated if `-Xelide-below` is at least `ASSERTION`. * * @see elidable * @param p the expression to test @@ -134,8 +133,8 @@ object Predef extends LowPriorityImplicits { throw new java.lang.AssertionError("assumption failed: "+ message) } - /** Tests an expression, throwing an IllegalArgumentException if false. - * This method is similar to assert, but blames the caller of the method + /** Tests an expression, throwing an `IllegalArgumentException` if false. + * This method is similar to `assert`, but blames the caller of the method * for violating the condition. * * @param p the expression to test @@ -145,8 +144,8 @@ object Predef extends LowPriorityImplicits { throw new IllegalArgumentException("requirement failed") } - /** Tests an expression, throwing an IllegalArgumentException if false. - * This method is similar to assert, but blames the caller of the method + /** Tests an expression, throwing an `IllegalArgumentException` if false. + * This method is similar to `assert`, but blames the caller of the method * for violating the condition. * * @param p the expression to test @@ -341,12 +340,12 @@ object Predef extends LowPriorityImplicits { * * @note we need a new type constructor `<:<` and evidence `conforms`, * as reusing `Function1` and `identity` leads to ambiguities in - * case of type errors (any2stringadd is inferred) + * case of type errors (`any2stringadd` is inferred) * * To constrain any abstract type T that's in scope in a method's * argument list (not just the method's own type parameters) simply - * add an implicit argument of type `T <:< U`, where U is the required - * upper bound; or for lower-bounds, use: `L <:< T`, where L is the + * add an implicit argument of type `T <:< U`, where `U` is the required + * upper bound; or for lower-bounds, use: `L <:< T`, where `L` is the * required lower bound. * * In part contributed by Jason Zaugg. @@ -360,7 +359,7 @@ object Predef extends LowPriorityImplicits { /** An instance of `A =:= B` witnesses that the types `A` and `B` are equal. * - * @see <:< for expressing subtyping constraints + * @see `<:<` for expressing subtyping constraints */ @implicitNotFound(msg = "Cannot prove that ${From} =:= ${To}.") sealed abstract class =:=[From, To] extends (From => To) with Serializable @@ -383,7 +382,7 @@ object Predef extends LowPriorityImplicits { object DummyImplicit { - /** An implicit value yielding a DummyImplicit. + /** An implicit value yielding a `DummyImplicit`. * @see fallbackCanBuildFrom in Array.scala */ implicit def dummyImplicit: DummyImplicit = new DummyImplicit diff --git a/src/library/scala/Product.scala b/src/library/scala/Product.scala index 1dbf46b4c2..cb316f2da3 100644 --- a/src/library/scala/Product.scala +++ b/src/library/scala/Product.scala @@ -8,32 +8,32 @@ package scala -/** Base trait for all products, which in the standard library include at least - * [[scala.Product1]] through [[scala.Product22]] and therefore also their - * subclasses [[scala.Tuple1]] through [[scala.Tuple22]]. In addition, all case - * classes implement Product with synthetically generated methods. +/** Base trait for all products, which in the standard library include at + * least [[scala.Product1]] through [[scala.Product22]] and therefore also + * their subclasses [[scala.Tuple1]] through [[scala.Tuple22]]. In addition, + * all case classes implement `Product` with synthetically generated methods. * * @author Burak Emir * @version 1.0 * @since 2.3 */ trait Product extends Equals { - /** The nth element of this product, 0-based. In other words, for a - * product `A(x_1, ..., x_k)`, returns x_(n+1) where 0 < n < k. + /** The n^th^ element of this product, 0-based. In other words, for a + * product `A(x,,1,,, ..., x,,k,,)`, returns `x,,(n+1),, where `0 < n < k`. * * @param n the index of the element to return - * @throws IndexOutOfBoundsException + * @throws `IndexOutOfBoundsException` * @return the element `n` elements after the first element */ def productElement(n: Int): Any /** The size of this product. - * @return for a product `A(x_1, ..., x_k)`, returns `k` + * @return for a product `A(x,,1,,, ..., x,,k,,)`, returns `k` */ def productArity: Int /** An iterator over all the elements of this product. - * @return in the default implementation, an Iterator[Any] + * @return in the default implementation, an `Iterator[Any]` */ def productIterator: Iterator[Any] = new Iterator[Any] { private var c: Int = 0 @@ -47,7 +47,7 @@ trait Product extends Equals { /** A string used in the `toString` methods of derived classes. * Implementations may override this method to prepend a string prefix - * to the result of toString methods. + * to the result of `toString` methods. * * @return in the default implementation, the empty string */ diff --git a/src/library/scala/Responder.scala b/src/library/scala/Responder.scala index 2c6556d4a4..919ba130d4 100644 --- a/src/library/scala/Responder.scala +++ b/src/library/scala/Responder.scala @@ -20,8 +20,7 @@ package scala */ object Responder { - /** Creates a responder that answer continuations with the constant - * <code>a</code>. + /** Creates a responder that answer continuations with the constant `a`. * * @param x ... * @return ... @@ -30,15 +29,15 @@ object Responder { def respond(k: A => Unit) = k(x) } - /** Executes <code>x</code> and returns <code>true</code>, useful - * as syntactic convenience in for comprehensions. + /** Executes `x` and returns `'''true'''`, useful as syntactic + * convenience in for comprehensions. * * @param x ... * @return ... */ def exec[A](x: => Unit): Boolean = { x; true } - /** runs a responder, returning an optional result + /** Runs a responder, returning an optional result. */ def run[A](r: Responder[A]): Option[A] = { var result: Option[A] = None @@ -92,4 +91,3 @@ abstract class Responder[+A] extends Serializable { override def toString = "Responder" } - diff --git a/src/library/scala/SerialVersionUID.scala b/src/library/scala/SerialVersionUID.scala index 5e1b07b9b9..0cb924c3d4 100644 --- a/src/library/scala/SerialVersionUID.scala +++ b/src/library/scala/SerialVersionUID.scala @@ -6,13 +6,10 @@ ** |/ ** */ - - package scala - /** - * Annotation for specifying the <code>static SerialVersionUID</code> field + * Annotation for specifying the `static SerialVersionUID` field * of a serializable class. */ class SerialVersionUID(uid: Long) extends annotation.StaticAnnotation diff --git a/src/library/scala/Symbol.scala b/src/library/scala/Symbol.scala index 79581f05d5..2cf8e21483 100644 --- a/src/library/scala/Symbol.scala +++ b/src/library/scala/Symbol.scala @@ -10,19 +10,14 @@ package scala -/** <p> - * This class provides a simple way to get unique objects for - * equal strings. Since symbols are interned, they can be compared using - * reference equality. Instances of - * <code>Symbol</code> can be created easily with Scala's built-in -* quote mechanism. - * </p> - * <p> - * For instance, the <a href="http://scala-lang.org/" target="_top">Scala</a> - * term <code>'mysym</code> will invoke the constructor of the - * <code>Symbol</code> class in the following way: - * <code>Symbol("mysym")</code>. - * </p> +/** This class provides a simple way to get unique objects for equal strings. + * Since symbols are interned, they can be compared using reference equality. + * Instances of `Symbol` can be created easily with Scala's built-in quote + * mechanism. + * + * For instance, the [[http://scala-lang.org/#_top Scala]] term `'mysym` will + * invoke the constructor of the `Symbol` class in the following way: + * `Symbol("mysym")`. * * @author Martin Odersky, Iulian Dragos * @version 1.8 diff --git a/src/library/scala/annotation/Annotation.scala b/src/library/scala/annotation/Annotation.scala index 05ed5af0a4..914a7b99f2 100644 --- a/src/library/scala/annotation/Annotation.scala +++ b/src/library/scala/annotation/Annotation.scala @@ -8,14 +8,11 @@ package scala.annotation -/** <p> - * A base class for annotations. Annotations extending this class directly - * are not preserved for the Scala type checker and are also not stored - * as Java annotations in classfiles. To enable either or both of these, - * one needs to inherit from - * <a href="StaticAnnotation.html"><code>StaticAnnotation</code></a> or/and - * <a href="ClassfileAnnotation.html"><code>ClassfileAnnotation</code></a>. - * </p> +/** A base class for annotations. Annotations extending this class directly + * are not preserved for the Scala type checker and are also not stored as + * Java annotations in classfiles. To enable either or both of these, one + * needs to inherit from [[scala.annotation.StaticAnnotation]] or/and + * [[scala.annotation.ClassfileAnnotation]]. * * @author Martin Odersky * @version 1.1, 2/02/2007 diff --git a/src/library/scala/annotation/ClassfileAnnotation.scala b/src/library/scala/annotation/ClassfileAnnotation.scala index 1019601f41..582e51996a 100644 --- a/src/library/scala/annotation/ClassfileAnnotation.scala +++ b/src/library/scala/annotation/ClassfileAnnotation.scala @@ -8,11 +8,9 @@ package scala.annotation -/** <p> - * A base class for classfile annotations. These are stored as - * <a href="http://java.sun.com/j2se/1.5.0/docs/guide/language/annotations.html" - * target="_top">Java annotations</a> in classfiles. - * </p> +/** A base class for classfile annotations. These are stored as + * [[http://java.sun.com/j2se/1.5.0/docs/guide/language/annotations.html#_top Java annotations]]] + * in classfiles. * * @author Martin Odersky * @version 1.1, 2/02/2007 diff --git a/src/library/scala/annotation/StaticAnnotation.scala b/src/library/scala/annotation/StaticAnnotation.scala index fad875bd8a..fc780ac7a5 100644 --- a/src/library/scala/annotation/StaticAnnotation.scala +++ b/src/library/scala/annotation/StaticAnnotation.scala @@ -8,10 +8,8 @@ package scala.annotation -/** <p> - * A base class for static annotations. These are available - * to the Scala type checker, even across different compilation units. - * </p> +/** A base class for static annotations. These are available + * to the Scala type checker, even across different compilation units. * * @author Martin Odersky * @version 1.1, 2/02/2007 diff --git a/src/library/scala/annotation/TypeConstraint.scala b/src/library/scala/annotation/TypeConstraint.scala index d13b0ac2b2..e1ed199d5c 100644 --- a/src/library/scala/annotation/TypeConstraint.scala +++ b/src/library/scala/annotation/TypeConstraint.scala @@ -8,18 +8,16 @@ package scala.annotation -/** <p> - * A marker for annotations that, when applied to a type, - * should be treated as a constraint on the annotated type. - * A proper constraint should restrict the type based only - * on information mentioned within the type. A Scala compiler - * can use this assumption to rewrite the contents of the - * constraint as necessary. To contrast, a type annotation - * whose meaning depends on the context where it is written - * down is not a proper constrained type, and this marker - * should not be applied. A Scala compiler will drop such - * annotations in cases where it would rewrite a type constraint. - * </p> +/** A marker for annotations that, when applied to a type, should be treated + * as a constraint on the annotated type. + * + * A proper constraint should restrict the type based only on information + * mentioned within the type. A Scala compiler can use this assumption to + * rewrite the contents of the constraint as necessary. To contrast, a type + * annotation whose meaning depends on the context where it is written + * down is not a proper constrained type, and this marker should not be + * applied. A Scala compiler will drop such annotations in cases where it + * would rewrite a type constraint. * * @author Lex Spoon * @version 1.1, 2007-11-5 diff --git a/src/library/scala/annotation/elidable.scala b/src/library/scala/annotation/elidable.scala index 8239debeb8..8dc180d7ab 100644 --- a/src/library/scala/annotation/elidable.scala +++ b/src/library/scala/annotation/elidable.scala @@ -13,10 +13,10 @@ import java.util.logging.Level /** An annotation for methods for which invocations might * be removed in the generated code. * - * Behavior is influenced by passing -Xelide-below <arg> - * 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: + * Behavior is influenced by passing `-Xelide-below <arg>` 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._ * @@ -33,20 +33,23 @@ final class elidable(final val level: Int) extends annotation.StaticAnnotation { * named constants for the elidable annotation. This is what it takes * to convince the compiler to fold the constants: otherwise when it's * time to check an elision level it's staring at a tree like - * (Select(Level, Select(FINEST, Apply(intValue, Nil)))) - * instead of the number 300. + * {{{ + * (Select(Level, Select(FINEST, Apply(intValue, Nil)))) + * }}} + * instead of the number `300`. * * @since 2.8 */ object elidable { - /** The levels ALLÂ and OFF are confusing in this context because the - * sentiment being expressed when using the annotation is at cross purposes - * with the one being expressed via -Xelide-below. This confusion reaches - * its zenith at level OFF, where the annotation means "never elide this method" - * but -Xelide-below OFF is how you would say "elide everything possible." + /** The levels `ALL` and `OFF` are confusing in this context because + * the sentiment being expressed when using the annotation is at cross + * purposes with the one being expressed via `-Xelide-below`. This + * confusion reaches its zenith at level `OFF`, where the annotation means + * ''never elide this method'' but `-Xelide-below OFF` is how you would + * say ''elide everything possible''. * * With no simple remedy at hand, the issue is now at least documented, - * and aliases MAXIMUM and MINIMUM are offered. + * and aliases `MAXIMUM` and `MINIMUM` are offered. */ final val ALL = Int.MinValue // Level.ALL.intValue() final val FINEST = 300 // Level.FINEST.intValue() diff --git a/src/library/scala/annotation/tailrec.scala b/src/library/scala/annotation/tailrec.scala index a2c1791a44..14775535e8 100644 --- a/src/library/scala/annotation/tailrec.scala +++ b/src/library/scala/annotation/tailrec.scala @@ -5,13 +5,14 @@ ** /____/\___/_/ |_/____/_/ | | ** ** |/ ** \* */ + package scala.annotation -/** <p> - * A method annotation which verifies that the method will be compiled - * with tail call optimization. If it is present, the compiler will - * issue an error if the method cannot be optimized into a loop. - * </p> +/** A method annotation which verifies that the method will be compiled + * with tail call optimization. + * + * If it is present, the compiler will issue an error if the method cannot + * be optimized into a loop. * * @since 2.8 */ diff --git a/src/library/scala/annotation/varargs.scala b/src/library/scala/annotation/varargs.scala index e29f7bacf0..1d7a2f7183 100644 --- a/src/library/scala/annotation/varargs.scala +++ b/src/library/scala/annotation/varargs.scala @@ -5,13 +5,12 @@ ** /____/\___/_/ |_/____/_/ | | ** ** |/ ** \* */ + package scala.annotation -/** <p> - * A method annotation which instructs the compiler to generate a - * Java varargs-style forwarder method for interop. This annotation can - * only be applied to methods with repeated parameters. - * </p> +/** A method annotation which instructs the compiler to generate a + * Java varargs-style forwarder method for interop. This annotation can + * only be applied to methods with repeated parameters. * * @since 2.9 */ diff --git a/src/library/scala/collection/GenSeqLike.scala b/src/library/scala/collection/GenSeqLike.scala index 1a66a0029c..56034273f0 100644 --- a/src/library/scala/collection/GenSeqLike.scala +++ b/src/library/scala/collection/GenSeqLike.scala @@ -215,14 +215,13 @@ trait GenSeqLike[+A, +Repr] extends GenIterableLike[A, Repr] with Equals with Pa /** Tests whether this $coll contains the given sequence at a given index. * - * If the both the receiver object, <code>this</code> and - * the argument, <code>that</code> are infinite sequences - * this method may not terminate. + * '''Note''': If the both the receiver object `this` and the argument + * `that` are infinite sequences this method may not terminate. * * @param that the sequence to test * @param offset the index where the sequence is searched. - * @return `true` if the sequence `that` is contained in this $coll at index `offset`, - * otherwise `false`. + * @return `true` if the sequence `that` is contained in this $coll at + * index `offset`, otherwise `false`. */ def startsWith[B](that: GenSeq[B], offset: Int): Boolean diff --git a/src/library/scala/collection/GenTraversableLike.scala b/src/library/scala/collection/GenTraversableLike.scala index 2a613a4645..fbb8b96ba4 100644 --- a/src/library/scala/collection/GenTraversableLike.scala +++ b/src/library/scala/collection/GenTraversableLike.scala @@ -26,10 +26,12 @@ import annotation.migration * and the new element type `B`. * @define orderDependent * - * Note: might return different results for different runs, unless the underlying collection type is ordered. + * Note: might return different results for different runs, unless the + * underlying collection type is ordered. * @define orderDependentFold * - * Note: might return different results for different runs, unless the underlying collection type is ordered. + * Note: might return different results for different runs, unless the + * underlying collection type is ordered. * or the operator is associative and commutative. * @define mayNotTerminateInf * diff --git a/src/library/scala/collection/GenTraversableOnce.scala b/src/library/scala/collection/GenTraversableOnce.scala index f27a176c44..67ae044ebf 100644 --- a/src/library/scala/collection/GenTraversableOnce.scala +++ b/src/library/scala/collection/GenTraversableOnce.scala @@ -19,10 +19,12 @@ package scala.collection * @define possiblyparinfo * This trait may possibly have operations implemented in parallel. * @define undefinedorder - * The order in which operations are performed on elements is unspecified and may be nondeterministic. + * The order in which operations are performed on elements is unspecified + * and may be nondeterministic. * @define orderDependent * - * Note: might return different results for different runs, unless the underlying collection type is ordered. + * Note: might return different results for different runs, unless the + * underlying collection type is ordered. * @define orderDependentFold * * Note: might return different results for different runs, unless the @@ -91,7 +93,8 @@ trait GenTraversableOnce[+A] { */ def reduce[A1 >: A](op: (A1, A1) => A1): A1 - /** Optionally reduces the elements of this sequence using the specified associative binary operator. + /** Optionally reduces the elements of this sequence using the specified + * associative binary operator. * * $undefinedorder * @@ -107,13 +110,14 @@ trait GenTraversableOnce[+A] { */ def reduceOption[A1 >: A](op: (A1, A1) => A1): Option[A1] - /** Folds the elements of this sequence using the specified associative binary operator. - * The order in which the elements are reduced is unspecified and may be nondeterministic. + /** Folds the elements of this sequence using the specified associative + * binary operator. The order in which the elements are reduced is + * unspecified and may be nondeterministic. * * Note this method has a different signature than the `foldLeft` * and `foldRight` methods of the trait `Traversable`. - * The result of folding may only be a supertype of this parallel collection's - * type parameter `T`. + * The result of folding may only be a supertype of this parallel + * collection's type parameter `T`. * * @tparam U a type parameter for the binary operator, a supertype of `T`. * @param z a neutral element for the fold operation, it may be added to the result @@ -141,7 +145,7 @@ trait GenTraversableOnce[+A] { * @return the result of inserting `op` between consecutive elements of this $coll, * going left to right with the start value `z` on the left: * {{{ - * op(...op(op(z, x,,1,,), x,,2,,), ..., x,,n,,) + * op(...op(op(z, x1), x2), ..., xn) * }}} * where `x,,1,,, ..., x,,n,,` are the elements of this $coll. */ @@ -161,7 +165,7 @@ trait GenTraversableOnce[+A] { * @return the result of inserting `op` between consecutive elements of this $coll, * going right to left with the start value `z` on the right: * {{{ - * op(x,,1,,, op(x,,2,,, ... op(x,,n,,, z)...)) + * op(x1, op(x2, ... op(xn, z)...)) * }}} * where `x,,1,,, ..., x,,n,,` are the elements of this $coll. */ @@ -179,7 +183,7 @@ trait GenTraversableOnce[+A] { * @return the result of inserting `op` between consecutive elements of this $coll, * going left to right with the start value `z` on the left: * {{{ - * op(...op(z, x,,1,,), x,,2,,, ..., x,,n,,) + * op(...op(z, x1), x2, ..., xn) * }}} * where `x,,1,,, ..., x,,n,,` are the elements of this $coll. */ @@ -196,7 +200,7 @@ trait GenTraversableOnce[+A] { * @return the result of inserting `op` between consecutive elements of this $coll, * going right to left with the start value `z` on the right: * {{{ - * op(x,,1,,, op(x,,2,,, ... op(x,,n,,, z)...)) + * op(x1, op(x2, ... op(xn, z)...)) * }}} * where `x,,1,,, ..., x,,n,,` are the elements of this $coll. */ @@ -204,18 +208,18 @@ trait GenTraversableOnce[+A] { /** Aggregates the results of applying an operator to subsequent elements. * - * This is a more general form of `fold` and `reduce`. It has similar semantics, but does - * not require the result to be a supertype of the element type. It traverses the elements in - * different partitions sequentially, using `seqop` to update the result, and then - * applies `combop` to results from different partitions. The implementation of this - * operation may operate on an arbitrary number of collection partitions, so `combop` - * may be invoked arbitrary number of times. - * - * For example, one might want to process some elements and then produce a `Set`. In this - * case, `seqop` would process an element and append it to the list, while `combop` - * would concatenate two lists from different partitions together. The initial value - * `z` would be an empty set. - * + * This is a more general form of `fold` and `reduce`. It has similar + * semantics, but does not require the result to be a supertype of the + * element type. It traverses the elements in different partitions + * sequentially, using `seqop` to update the result, and then applies + * `combop` to results from different partitions. The implementation of + * this operation may operate on an arbitrary number of collection + * partitions, so `combop` may be invoked arbitrary number of times. + * + * For example, one might want to process some elements and then produce + * a `Set`. In this case, `seqop` would process an element and append it + * to the list, while `combop` would concatenate two lists from different + * partitions together. The initial value `z` would be an empty set. * {{{ * pc.aggregate(Set[Int]())(_ += process(_), _ ++ _) * }}} diff --git a/src/library/scala/collection/IterableProxy.scala b/src/library/scala/collection/IterableProxy.scala index a05a3cff5b..e0ba720a33 100644 --- a/src/library/scala/collection/IterableProxy.scala +++ b/src/library/scala/collection/IterableProxy.scala @@ -6,16 +6,12 @@ ** |/ ** \* */ - - package scala.collection import generic._ -/** <p> - * This trait implements a proxy for iterable objects. It forwards - * all calls to a different iterable object. - * </p> +/** This trait implements a proxy for iterable objects. It forwards all calls + * to a different iterable object. * * @author Martin Odersky * @version 2.8 diff --git a/src/library/scala/collection/JavaConversions.scala b/src/library/scala/collection/JavaConversions.scala index 8b98f10875..39b86ad85d 100644 --- a/src/library/scala/collection/JavaConversions.scala +++ b/src/library/scala/collection/JavaConversions.scala @@ -275,17 +275,18 @@ object JavaConversions { def asMap[A, B](m : mutable.Map[A, B]): ju.Map[A, B] = mutableMapAsJavaMap[A, B](m) /** - * Implicitly converts a Scala mutable Map to a Java Dictionary. - * The returned Java Dictionary is backed by the provided Scala - * Dictionary and any side-effects of using it via the Java interface will - * be visible via the Scala interface and vice versa. + * Implicitly converts a Scala mutable `Map` to a Java `Dictionary`. + * + * The returned Java `Dictionary` is backed by the provided Scala + * `Dictionary` and any side-effects of using it via the Java interface + * will be visible via the Scala interface and vice versa. * - * If the Scala Dictionary was previously obtained from an implicit or - * explicit call of asMap(java.util.Dictionary) then the original + * If the Scala `Dictionary` was previously obtained from an implicit or + * explicit call of `asMap(java.util.Dictionary)` then the original * Java Dictionary will be returned. * - * @param m The Map to be converted. - * @return A Java Dictionary view of the argument. + * @param m The `Map` to be converted. + * @return A Java `Dictionary` view of the argument. */ implicit def asJavaDictionary[A, B](m : mutable.Map[A, B]): ju.Dictionary[A, B] = m match { //case JConcurrentMapWrapper(wrapped) => wrapped @@ -297,17 +298,18 @@ object JavaConversions { def asDictionary[A, B](m : mutable.Map[A, B]): ju.Dictionary[A, B] = asJavaDictionary[A, B](m) /** - * Implicitly converts a Scala Map to a Java Map. - * The returned Java Map is backed by the provided Scala - * Map and any side-effects of using it via the Java interface will - * be visible via the Scala interface and vice versa. + * Implicitly converts a Scala `Map` to a Java `Map`. * - * If the Scala Map was previously obtained from an implicit or - * explicit call of asMap(java.util.Map) then the original - * Java Map will be returned. + * The returned Java `Map` is backed by the provided Scala `Map` and + * any side-effects of using it via the Java interface will be visible + * via the Scala interface and vice versa. * - * @param m The Map to be converted. - * @return A Java Map view of the argument. + * If the Scala `Map` was previously obtained from an implicit or + * explicit call of `asMap(java.util.Map)` then the original + * Java `Map` will be returned. + * + * @param m The `Map` to be converted. + * @return A Java `Map` view of the argument. */ implicit def mapAsJavaMap[A, B](m : Map[A, B]): ju.Map[A, B] = m match { //case JConcurrentMapWrapper(wrapped) => wrapped @@ -321,17 +323,19 @@ object JavaConversions { def asMap[A, B](m : Map[A, B]): ju.Map[A, B] = mapAsJavaMap[A, B](m) /** - * Implicitly converts a Scala mutable `ConcurrentMap` to a Java `ConcurrentMap`. - * The returned Java `ConcurrentMap` is backed by the provided Scala `ConcurrentMap` - * and any side-effects of using it via the Java interface will be visible - * via the Scala interface and vice versa. + * Implicitly converts a Scala mutable `ConcurrentMap` to a Java + * `ConcurrentMap`. * - * If the Scala ConcurrentMap was previously obtained from an implicit or - * explicit call of asConcurrentMap(java.util.concurrect.ConcurrentMap) then the original - * Java ConcurrentMap will be returned. + * The returned Java `ConcurrentMap` is backed by the provided Scala + * `ConcurrentMap` and any side-effects of using it via the Java interface + * will be visible via the Scala interface and vice versa. * - * @param m The ConcurrentMap to be converted. - * @return A Java ConcurrentMap view of the argument. + * If the Scala `ConcurrentMap` was previously obtained from an implicit or + * explicit call of `asConcurrentMap(java.util.concurrect.ConcurrentMap)` + * then the original Java ConcurrentMap will be returned. + * + * @param m The `ConcurrentMap` to be converted. + * @return A Java `ConcurrentMap` view of the argument. */ implicit def asJavaConcurrentMap[A, B](m: mutable.ConcurrentMap[A, B]): juc.ConcurrentMap[A, B] = m match { case JConcurrentMapWrapper(wrapped) => wrapped @@ -344,17 +348,18 @@ object JavaConversions { // Java => Scala /** - * Implicitly converts a Java Iterator to a Scala Iterator. - * The returned Scala Iterator is backed by the provided Java - * Iterator and any side-effects of using it via the Scala interface will - * be visible via the Java interface and vice versa. + * Implicitly converts a Java `Iterator` to a Scala `Iterator`. * - * If the Java Iterator was previously obtained from an implicit or - * explicit call of asIterator(scala.collection.Iterator) then the original - * Scala Iterator will be returned. + * The returned Scala `Iterator` is backed by the provided Java `Iterator` + * and any side-effects of using it via the Scala interface will be visible + * via the Java interface and vice versa. * - * @param i The Iterator to be converted. - * @return A Scala Iterator view of the argument. + * If the Java `Iterator` was previously obtained from an implicit or + * explicit call of `asIterator(scala.collection.Iterator)` then the + * original Scala `Iterator` will be returned. + * + * @param i The `Iterator` to be converted. + * @return A Scala `Iterator` view of the argument. */ implicit def asScalaIterator[A](i : ju.Iterator[A]): Iterator[A] = i match { case IteratorWrapper(wrapped) => wrapped @@ -386,14 +391,15 @@ object JavaConversions { def asIterator[A](i : ju.Enumeration[A]): Iterator[A] = enumerationAsScalaIterator[A](i) /** - * Implicitly converts a Java Iterable to a Scala Iterable. - * The returned Scala Iterable is backed by the provided Java - * Iterable and any side-effects of using it via the Scala interface will - * be visible via the Java interface and vice versa. + * Implicitly converts a Java `Iterable` to a Scala `Iterable`. * - * If the Java Iterable was previously obtained from an implicit or - * explicit call of iterableAsScalaIterable(scala.collection.Iterable) then the original - * Scala Iterable will be returned. + * The returned Scala `Iterable` is backed by the provided Java `Iterable` + * and any side-effects of using it via the Scala interface will be visible + * via the Java interface and vice versa. + * + * If the Java `Iterable` was previously obtained from an implicit or + * explicit call of `iterableAsScalaIterable(scala.collection.Iterable)` + * then the original Scala Iterable will be returned. * * @param i The Iterable to be converted. * @return A Scala Iterable view of the argument. @@ -409,11 +415,11 @@ object JavaConversions { def asIterable[A](i : jl.Iterable[A]): Iterable[A] = iterableAsScalaIterable[A](i) /** - * Implicitly converts a Java Collection to an Scala Iterable. + * Implicitly converts a Java `Collection` to an Scala `Iterable`. * - * If the Java Collection was previously obtained from an implicit or - * explicit call of collectionAsScalaIterable(scala.collection.SizedIterable) then - * the original Scala Iterable will be returned. + * If the Java `Collection` was previously obtained from an implicit or + * explicit call of `collectionAsScalaIterable(scala.collection.SizedIterable)` + * then the original Scala `Iterable` will be returned. * * @param i The Collection to be converted. * @return A Scala Iterable view of the argument. @@ -428,17 +434,18 @@ object JavaConversions { def asIterable[A](i : ju.Collection[A]): Iterable[A] = collectionAsScalaIterable[A](i) /** - * Implicitly converts a Java List to a Scala mutable Buffer. - * The returned Scala Buffer is backed by the provided Java - * List and any side-effects of using it via the Scala interface will + * Implicitly converts a Java `List` to a Scala mutable `Buffer`. + * + * The returned Scala `Buffer` is backed by the provided Java `List` + * and any side-effects of using it via the Scala interface will * be visible via the Java interface and vice versa. * - * If the Java List was previously obtained from an implicit or - * explicit call of asScalaBuffer(scala.collection.mutable.Buffer) then the original - * Scala Buffer will be returned. + * If the Java `List` was previously obtained from an implicit or + * explicit call of `asScalaBuffer(scala.collection.mutable.Buffer)` + * then the original Scala `Buffer` will be returned. * - * @param l The List to be converted. - * @return A Scala mutable Buffer view of the argument. + * @param l The `List` to be converted. + * @return A Scala mutable `Buffer` view of the argument. */ implicit def asScalaBuffer[A](l : ju.List[A]): mutable.Buffer[A] = l match { case MutableBufferWrapper(wrapped) => wrapped @@ -470,13 +477,14 @@ object JavaConversions { def asSet[A](s : ju.Set[A]): mutable.Set[A] = asScalaSet[A](s) /** - * Implicitly converts a Java Map to a Scala mutable Map. - * The returned Scala Map is backed by the provided Java - * Map and any side-effects of using it via the Scala interface will - * be visible via the Java interface and vice versa. + * Implicitly converts a Java `Map` to a Scala mutable `Map`. + * + * The returned Scala `Map` is backed by the provided Java `Map` and any + * side-effects of using it via the Scala interface will be visible via + * the Java interface and vice versa. * - * If the Java Map was previously obtained from an implicit or - * explicit call of mapAsScalaMap(scala.collection.mutable.Map) then the original + * If the Java `Map` was previously obtained from an implicit or + * explicit call of `mapAsScalaMap(scala.collection.mutable.Map)` then the original * Scala Map will be returned. * * @param m The Map to be converted. @@ -515,10 +523,12 @@ object JavaConversions { def asConcurrentMap[A, B](m: juc.ConcurrentMap[A, B]): mutable.ConcurrentMap[A, B] = asScalaConcurrentMap[A, B](m) /** - * Implicitly converts a Java Dictionary to a Scala mutable Map[String, String]. - * The returned Scala Map[String, String] is backed by the provided Java - * Dictionary and any side-effects of using it via the Scala interface will - * be visible via the Java interface and vice versa. + * Implicitly converts a Java `Dictionary` to a Scala mutable + * `Map[String, String]`. + * + * The returned Scala `Map[String, String]` is backed by the provided Java + * `Dictionary` and any side-effects of using it via the Scala interface + * will be visible via the Java interface and vice versa. * * @param m The Dictionary to be converted. * @return A Scala mutable Map[String, String] view of the argument. @@ -532,10 +542,11 @@ object JavaConversions { def asMap[A, B](p: ju.Dictionary[A, B]): mutable.Map[A, B] = dictionaryAsScalaMap[A, B](p) /** - * Implicitly converts a Java Properties to a Scala mutable Map[String, String]. - * The returned Scala Map[String, String] is backed by the provided Java - * Properties and any side-effects of using it via the Scala interface will - * be visible via the Java interface and vice versa. + * Implicitly converts a Java `Properties` to a Scala `mutable Map[String, String]`. + * + * The returned Scala `Map[String, String]` is backed by the provided Java + * `Properties` and any side-effects of using it via the Scala interface + * will be visible via the Java interface and vice versa. * * @param m The Properties to be converted. * @return A Scala mutable Map[String, String] view of the argument. @@ -930,7 +941,7 @@ object JavaConversions { def iterator = new Iterator[(String, String)] { val ui = underlying.entrySet.iterator def hasNext = ui.hasNext - def next() = { val e = ui.next ; (e.getKey.asInstanceOf[String], e.getValue.asInstanceOf[String]) } + def next() = { val e = ui.next; (e.getKey.asInstanceOf[String], e.getValue.asInstanceOf[String]) } } override def clear() = underlying.clear() @@ -944,4 +955,3 @@ object JavaConversions { def setProperty(key: String, value: String) = underlying.setProperty(key, value) } } - diff --git a/src/library/scala/collection/JavaConverters.scala b/src/library/scala/collection/JavaConverters.scala index b0abf09ddb..d5baacedf8 100755 --- a/src/library/scala/collection/JavaConverters.scala +++ b/src/library/scala/collection/JavaConverters.scala @@ -8,51 +8,42 @@ package scala.collection -/** <p> - * A collection of decorators that allow to convert between - * Scala and Java collections using `asScala` and `asJava` methods. - * </p> - * <p> - * The following conversions are supported via `asJava`, `asScala` - * </p> - * <ul> - * <li><code>scala.collection.Iterable</code> <=> <code>java.lang.Iterable</code></li> - * <li><code>scala.collection.Iterator</code> <=> <code>java.util.Iterator</code></li> - * <li><code>scala.collection.mutable.Buffer</code> <=> <code>java.util.List</code></li> - * <li><code>scala.collection.mutable.Set</code> <=> <code>java.util.Set</code></li> - * <li><code>scala.collection.mutable.Map</code> <=> <code>java.util.Map</code></li> - * <li><code>scala.collection.mutable.ConcurrentMap</code> <=> <code>java.util.concurrent.ConcurrentMap</code></li> - * </ul> - * <p> - * In all cases, converting from a source type to a target type and back - * again will return the original source object, e.g. - * </p> - * <pre> - * <b>import</b> scala.collection.JavaConverters._ +/** A collection of decorators that allow to convert between + * Scala and Java collections using `asScala` and `asJava` methods. + * + * The following conversions are supported via `asJava`, `asScala` + * + * - `scala.collection.Iterable` <=> `java.lang.Iterable` + * - `scala.collection.Iterator` <=> `java.util.Iterator` + * - `scala.collection.mutable.Buffer` <=> `java.util.List` + * - `scala.collection.mutable.Set` <=> `java.util.Set` + * - `scala.collection.mutable.Map` <=> `java.util.Map` + * - `scala.collection.mutable.ConcurrentMap` <=> `java.util.concurrent.ConcurrentMap` + * + * In all cases, converting from a source type to a target type and back + * again will return the original source object, e.g. + * {{{ + * import scala.collection.JavaConverters._ + * + * val sl = new scala.collection.mutable.ListBuffer[Int] + * val jl : java.util.List[Int] = sl.asJava + * val sl2 : scala.collection.mutable.Buffer[Int] = jl.asScala + * assert(sl eq sl2) + * }}} + * The following conversions also are supported, but the + * direction Scala to Java is done my a more specifically named method: + * `asJavaCollection`, `asJavaEnumeration`, `asJavaDictionary`. + * + * - `scala.collection.Iterable` <=> `java.util.Collection` + * - `scala.collection.Iterator` <=> `java.util.Enumeration` + * - `scala.collection.mutable.Map` <=> `java.util.Dictionary` * - * <b>val</b> sl = <b>new</b> scala.collection.mutable.ListBuffer[Int] - * <b>val</b> jl : java.util.List[Int] = sl.asJava - * <b>val</b> sl2 : scala.collection.mutable.Buffer[Int] = jl.asScala - * assert(sl eq sl2)g</pre> - * <p> - * <p> - * The following conversions also are supported, but the - * direction Scala to Java is done my a more specifically named method: - * `asJavaCollection`, `asJavaEnumeration`, `asJavaDictionary`. - * </p> - * <ul> - * <li><code>scala.collection.Iterable</code> <=> <code>java.util.Collection</code></li> - * <li><code>scala.collection.Iterator</code> <=> <code>java.util.Enumeration</code></li> - * <li><code>scala.collection.mutable.Map</code> <=> <code>java.util.Dictionary</code></li> - * </ul> * In addition, the following one way conversions are provided via `asJava`: - * </p> - * <ul> - * <li><code>scala.collection.Seq</code> => <code>java.util.List</code></li> - * <li><code>scala.collection.mutable.Seq</code> => <code>java.util.List</code></li> - * <li><code>scala.collection.Set</code> => <code>java.util.Set</code></li> - * <li><code>scala.collection.Map</code> => <code>java.util.Map</code></li> - * </ul> + * + * - `scala.collection.Seq` => `java.util.List` + * - `scala.collection.mutable.Seq` => `java.util.List` + * - `scala.collection.Set` => `java.util.Set` + * - `scala.collection.Map` => `java.util.Map` * * @author Martin Odersky * @since 2.8.1 @@ -101,111 +92,125 @@ object JavaConverters { // Scala => Java /** - * Adds an `asJava` method that implicitly converts a Scala <code>Iterator</code> to a Java <code>Iterator</code>. - * The returned Java <code>Iterator</code> is backed by the provided Scala - * <code>Iterator</code> and any side-effects of using it via the Java interface will + * Adds an `asJava` method that implicitly converts a Scala `Iterator` to a + * Java `Iterator`. The returned Java `Iterator` is backed by the provided Scala + * `Iterator` and any side-effects of using it via the Java interface will * be visible via the Scala interface and vice versa. - * <p> - * If the Scala <code>Iterator</code> was previously obtained from an implicit or - * explicit call of <code>asIterator(java.util.Iterator)</code> then the original - * Java <code>Iterator</code> will be returned by the `asJava` method. * - * @param i The <code>Iterator</code> to be converted. - * @return An object with an `asJava` method that returns a Java <code>Iterator</code> view of the argument. + * If the Scala `Iterator` was previously obtained from an implicit or explicit + * call of `asIterator(java.util.Iterator)` then the original Java `Iterator` + * will be returned by the `asJava` method. + * + * @param i The `Iterator` to be converted. + * @return An object with an `asJava` method that returns a Java `Iterator` view of the argument. */ implicit def asJavaIteratorConverter[A](i : Iterator[A]): AsJava[ju.Iterator[A]] = new AsJava(asJavaIterator(i)) /** - * Adds an `asJavaEnumeration` method that implicitly converts a Scala <code>Iterator</code> to a Java <code>Enumeration</code>. - * The returned Java <code>Enumeration</code> is backed by the provided Scala - * <code>Iterator</code> and any side-effects of using it via the Java interface will - * be visible via the Scala interface and vice versa. - * <p> - * If the Scala <code>Iterator</code> was previously obtained from an implicit or - * explicit call of <code>asIterator(java.util.Enumeration)</code> then the - * original Java <code>Enumeration</code> will be returned. + * Adds an `asJavaEnumeration` method that implicitly converts a Scala + * `Iterator` to a Java `Enumeration`. The returned Java `Enumeration` is + * backed by the provided Scala `Iterator` and any side-effects of using + * it via the Java interface will be visible via the Scala interface and + * vice versa. + * + * If the Scala `Iterator` was previously obtained from an implicit or + * explicit call of `asIterator(java.util.Enumeration)` then the + * original Java `Enumeration` will be returned. * - * @param i The <code>Iterator</code> to be converted. - * @return An object with an `asJavaEnumeration` method that returns a Java <code>Enumeration</code> view of the argument. + * @param i The `Iterator` to be converted. + * @return An object with an `asJavaEnumeration` method that returns a Java + * `Enumeration` view of the argument. */ implicit def asJavaEnumerationConverter[A](i : Iterator[A]): AsJavaEnumeration[A] = new AsJavaEnumeration(i) /** - * Adds an `asJava` method that implicitly converts a Scala <code>Iterable</code> to a Java <code>Iterable</code>. - * The returned Java <code>Iterable</code> is backed by the provided Scala - * <code>Iterable</code> and any side-effects of using it via the Java interface will - * be visible via the Scala interface and vice versa. - * <p> - * If the Scala <code>Iterable</code> was previously obtained from an implicit or - * explicit call of <code>asIterable(java.lang.Iterable)</code> then the original - * Java <code>Iterable</code> will be returned. + * Adds an `asJava` method that implicitly converts a Scala `Iterable` to + * a Java `Iterable`. * - * @param i The <code>Iterable</code> to be converted. - * @return An object with an `asJavaCollection` method that returns a Java <code>Iterable</code> view of the argument. + * The returned Java `Iterable` is backed by the provided Scala `Iterable` + * and any side-effects of using it via the Java interface will be visible + * via the Scala interface and vice versa. + * + * If the Scala `Iterable` was previously obtained from an implicit or + * explicit call of `asIterable(java.lang.Iterable)` then the original + * Java `Iterable` will be returned. + * + * @param i The `Iterable` to be converted. + * @return An object with an `asJavaCollection` method that returns a Java + * `Iterable` view of the argument. */ implicit def asJavaIterableConverter[A](i : Iterable[A]): AsJava[jl.Iterable[A]] = new AsJava(asJavaIterable(i)) /** - * Adds an `asJavaCollection` method that implicitly converts a Scala <code>Iterable</code> to an immutable Java - * <code>Collection</code>. - * <p> - * If the Scala <code>Iterable</code> was previously obtained from an implicit or - * explicit call of <code>asSizedIterable(java.util.Collection)</code> then the original - * Java <code>Collection</code> will be returned. + * Adds an `asJavaCollection` method that implicitly converts a Scala + * `Iterable` to an immutable Java `Collection`. + * + * If the Scala `Iterable` was previously obtained from an implicit or + * explicit call of `asSizedIterable(java.util.Collection)` then the + * original Java `Collection` will be returned. * - * @param i The <code>SizedIterable</code> to be converted. - * @return An object with an `asJava` method that returns a Java <code>Collection</code> view of the argument. + * @param i The `SizedIterable` to be converted. + * @return An object with an `asJava` method that returns a Java + * `Collection` view of the argument. */ implicit def asJavaCollectionConverter[A](i : Iterable[A]): AsJavaCollection[A] = new AsJavaCollection(i) /** - * Adds an `asJava` method that implicitly converts a Scala mutable <code>Buffer</code> to a Java <code>List</code>. - * The returned Java <code>List</code> is backed by the provided Scala - * <code>Buffer</code> and any side-effects of using it via the Java interface will - * be visible via the Scala interface and vice versa. - * <p> - * If the Scala <code>Buffer</code> was previously obtained from an implicit or - * explicit call of <code>asBuffer(java.util.List)</code> then the original - * Java <code>List</code> will be returned. + * Adds an `asJava` method that implicitly converts a Scala mutable `Buffer` + * to a Java `List`. * - * @param b The <code>Buffer</code> to be converted. + * The returned Java `List` is backed by the provided Scala `Buffer` and any + * side-effects of using it via the Java interface will be visible via the + * Scala interface and vice versa. + * + * If the Scala `Buffer` was previously obtained from an implicit or explicit + * call of `asBuffer(java.util.List)` then the original Java `List` will be + * returned. + * + * @param b The `Buffer` to be converted. * @return An object with an `asJava` method that returns a Java <code>List</code> view of the argument. */ implicit def bufferAsJavaListConverter[A](b : mutable.Buffer[A]): AsJava[ju.List[A]] = new AsJava(bufferAsJavaList(b)) /** - * Adds an `asJava` method that implicitly converts a Scala mutable <code>Seq</code> to a Java <code>List</code>. - * The returned Java <code>List</code> is backed by the provided Scala - * <code>Seq</code> and any side-effects of using it via the Java interface will - * be visible via the Scala interface and vice versa. - * <p> - * If the Scala <code>Seq</code> was previously obtained from an implicit or - * explicit call of <code>asSeq(java.util.List)</code> then the original - * Java <code>List</code> will be returned. + * Adds an `asJava` method that implicitly converts a Scala mutable `Seq` + * to a Java `List`. * - * @param b The <code>Seq</code> to be converted. - * @return An object with an `asJava` method that returns a Java <code>List</code> view of the argument. + * The returned Java `List` is backed by the provided Scala `Seq` and any + * side-effects of using it via the Java interface will be visible via the + * Scala interface and vice versa. + * + * If the Scala `Seq` was previously obtained from an implicit or explicit + * call of `asSeq(java.util.List)` then the original Java `List` will be + * returned. + * + * @param b The `Seq` to be converted. + * @return An object with an `asJava` method that returns a Java `List` + * view of the argument. */ implicit def mutableSeqAsJavaListConverter[A](b : mutable.Seq[A]): AsJava[ju.List[A]] = new AsJava(mutableSeqAsJavaList(b)) /** - * Adds an `asJava` method that implicitly converts a Scala <code>Seq</code> to a Java <code>List</code>. - * The returned Java <code>List</code> is backed by the provided Scala - * <code>Seq</code> and any side-effects of using it via the Java interface will - * be visible via the Scala interface and vice versa. - * <p> - * If the Scala <code>Seq</code> was previously obtained from an implicit or - * explicit call of <code>asSeq(java.util.List)</code> then the original - * Java <code>List</code> will be returned. + * Adds an `asJava` method that implicitly converts a Scala `Seq` to a + * Java `List`. * - * @param b The <code>Seq</code> to be converted. - * @return An object with an `asJava` method that returns a Java <code>List</code> view of the argument. + * The returned Java `List` is backed by the provided Scala `Seq` and any + * side-effects of using it via the Java interface will be visible via the + * Scala interface and vice versa. + * + * If the Scala `Seq` was previously obtained from an implicit or explicit + * call of `asSeq(java.util.List)` then the original Java `List` will be + * returned. + * + * @param b The `Seq` to be converted. + * @return An object with an `asJava` method that returns a Java `List` + * view of the argument. */ implicit def seqAsJavaListConverter[A](b : Seq[A]): AsJava[ju.List[A]] = new AsJava(seqAsJavaList(b)) @@ -218,14 +223,16 @@ object JavaConverters { def asJavaListConverter[A](b : Seq[A]): AsJava[ju.List[A]] = seqAsJavaListConverter(b) /** - * Adds an `asJava` method that implicitly converts a Scala mutable <code>Set</code> to a Java <code>Set</code>. - * The returned Java <code>Set</code> is backed by the provided Scala - * <code>Set</code> and any side-effects of using it via the Java interface will - * be visible via the Scala interface and vice versa. - * <p> - * If the Scala <code>Set</code> was previously obtained from an implicit or - * explicit call of <code>asSet(java.util.Set)</code> then the original - * Java <code>Set</code> will be returned. + * Adds an `asJava` method that implicitly converts a Scala mutable `Set`> + * to a Java `Set`. + * + * The returned Java `Set` is backed by the provided Scala `Set` and any + * side-effects of using it via the Java interface will be visible via + * the Scala interface and vice versa. + * + * If the Scala `Set` was previously obtained from an implicit or explicit + * call of `asSet(java.util.Set)` then the original Java `Set` will be + * returned. * * @param s The <code>Set</code> to be converted. * @return An object with an `asJava` method that returns a Java <code>Set</code> view of the argument. @@ -237,17 +244,20 @@ object JavaConverters { def asJavaSetConverter[A](s : mutable.Set[A]): AsJava[ju.Set[A]] = mutableSetAsJavaSetConverter(s) /** - * Adds an `asJava` method that implicitly converts a Scala <code>Set</code> to a Java <code>Set</code>. - * The returned Java <code>Set</code> is backed by the provided Scala - * <code>Set</code> and any side-effects of using it via the Java interface will - * be visible via the Scala interface and vice versa. - * <p> - * If the Scala <code>Set</code> was previously obtained from an implicit or - * explicit call of <code>asSet(java.util.Set)</code> then the original - * Java <code>Set</code> will be returned. + * Adds an `asJava` method that implicitly converts a Scala `Set` to a + * Java `Set`. * - * @param s The <code>Set</code> to be converted. - * @return An object with an `asJava` method that returns a Java <code>Set</code> view of the argument. + * The returned Java `Set` is backed by the provided Scala `Set` and any + * side-effects of using it via the Java interface will be visible via + * the Scala interface and vice versa. + * + * If the Scala `Set` was previously obtained from an implicit or explicit + * call of <code>asSet(java.util.Set)</code> then the original Java `Set` + * will be returned. + * + * @param s The `Set` to be converted. + * @return An object with an `asJava` method that returns a Java `Set` view + * of the argument. */ implicit def setAsJavaSetConverter[A](s : Set[A]): AsJava[ju.Set[A]] = new AsJava(setAsJavaSet(s)) @@ -256,17 +266,20 @@ object JavaConverters { def asJavaSetConverter[A](s : Set[A]): AsJava[ju.Set[A]] = setAsJavaSetConverter(s) /** - * Adds an `asJava` method that implicitly converts a Scala mutable <code>Map</code> to a Java <code>Map</code>. - * The returned Java <code>Map</code> is backed by the provided Scala - * <code>Map</code> and any side-effects of using it via the Java interface will - * be visible via the Scala interface and vice versa. - * <p> - * If the Scala <code>Map</code> was previously obtained from an implicit or - * explicit call of <code>asMap(java.util.Map)</code> then the original - * Java <code>Map</code> will be returned. + * Adds an `asJava` method that implicitly converts a Scala mutable `Map` + * to a Java `Map`. * - * @param m The <code>Map</code> to be converted. - * @return An object with an `asJava` method that returns a Java <code>Map</code> view of the argument. + * The returned Java `Map` is backed by the provided Scala `Map` and any + * side-effects of using it via the Java interface will be visible via the + * Scala interface and vice versa. + * + * If the Scala `Map` was previously obtained from an implicit or explicit + * call of `asMap(java.util.Map)` then the original Java `Map` will be + * returned. + * + * @param m The `Map` to be converted. + * @return An object with an `asJava` method that returns a Java `Map` view + * of the argument. */ implicit def mutableMapAsJavaMapConverter[A, B](m : mutable.Map[A, B]): AsJava[ju.Map[A, B]] = new AsJava(mutableMapAsJavaMap(m)) @@ -275,33 +288,39 @@ object JavaConverters { def asJavaMapConverter[A, B](m : mutable.Map[A, B]): AsJava[ju.Map[A, B]] = mutableMapAsJavaMapConverter(m) /** - * Adds an `asJavaDictionary` method that implicitly converts a Scala mutable <code>Map</code> to a Java <code>Dictionary</code>. - * The returned Java <code>Dictionary</code> is backed by the provided Scala - * <code>Dictionary</code> and any side-effects of using it via the Java interface will - * be visible via the Scala interface and vice versa. - * <p> - * If the Scala <code>Dictionary</code> was previously obtained from an implicit or - * explicit call of <code>asMap(java.util.Dictionary)</code> then the original - * Java <code>Dictionary</code> will be returned. + * Adds an `asJavaDictionary` method that implicitly converts a Scala + * mutable `Map` to a Java `Dictionary`. + * + * The returned Java `Dictionary` is backed by the provided Scala + * `Dictionary` and any side-effects of using it via the Java interface + * will be visible via the Scala interface and vice versa. + * + * If the Scala `Dictionary` was previously obtained from an implicit or + * explicit call of `asMap(java.util.Dictionary)` then the original + * Java `Dictionary` will be returned. * * @param m The <code>Map</code> to be converted. - * @return An object with an `asJavaDictionary` method that returns a Java <code>Dictionary</code> view of the argument. + * @return An object with an `asJavaDictionary` method that returns a + * Java `Dictionary` view of the argument. */ implicit def asJavaDictionaryConverter[A, B](m : mutable.Map[A, B]): AsJavaDictionary[A, B] = new AsJavaDictionary(m) /** - * Adds an `asJava` method that implicitly converts a Scala <code>Map</code> to a Java <code>Map</code>. - * The returned Java <code>Map</code> is backed by the provided Scala - * <code>Map</code> and any side-effects of using it via the Java interface will - * be visible via the Scala interface and vice versa. - * <p> - * If the Scala <code>Map</code> was previously obtained from an implicit or - * explicit call of <code>asMap(java.util.Map)</code> then the original - * Java <code>Map</code> will be returned. + * Adds an `asJava` method that implicitly converts a Scala `Map` to + * a Java `Map`. * - * @param m The <code>Map</code> to be converted. - * @return An object with an `asJava` method that returns a Java <code>Map</code> view of the argument. + * The returned Java `Map` is backed by the provided Scala `Map` and any + * side-effects of using it via the Java interface will be visible via + * the Scala interface and vice versa. + * + * If the Scala `Map` was previously obtained from an implicit or explicit + * call of `asMap(java.util.Map)` then the original Java `Map` will be + * returned. + * + * @param m The `Map` to be converted. + * @return An object with an `asJava` method that returns a Java `Map` view + * of the argument. */ implicit def mapAsJavaMapConverter[A, B](m : Map[A, B]): AsJava[ju.Map[A, B]] = new AsJava(mapAsJavaMap(m)) @@ -310,49 +329,58 @@ object JavaConverters { def asJavaMapConverter[A, B](m : Map[A, B]): AsJava[ju.Map[A, B]] = mapAsJavaMapConverter(m) /** - * Adds an `asJava` method that implicitly converts a Scala mutable `ConcurrentMap` to a Java `ConcurrentMap`. - * The returned Java `ConcurrentMap` is backed by the provided Scala `ConcurrentMap` - * and any side-effects of using it via the Java interface will be visible - * via the Scala interface and vice versa. - * <p> - * If the Scala <code>ConcurrentMap</code> was previously obtained from an implicit or - * explicit call of <code>asConcurrentMap(java.util.concurrect.ConcurrentMap)</code> then the original - * Java <code>ConcurrentMap</code> will be returned. + * Adds an `asJava` method that implicitly converts a Scala mutable + * `ConcurrentMap` to a Java `ConcurrentMap`. * - * @param m The <code>ConcurrentMap</code> to be converted. - * @return An object with an `asJava` method that returns a Java <code>ConcurrentMap</code> view of the argument. + * The returned Java `ConcurrentMap` is backed by the provided Scala + * `ConcurrentMap` and any side-effects of using it via the Java interface + * will be visible via the Scala interface and vice versa. + * + * If the Scala `ConcurrentMap` was previously obtained from an implicit or + * explicit call of `asConcurrentMap(java.util.concurrect.ConcurrentMap)` + * then the original Java `ConcurrentMap` will be returned. + * + * @param m The `ConcurrentMap` to be converted. + * @return An object with an `asJava` method that returns a Java + * `ConcurrentMap` view of the argument. */ implicit def asJavaConcurrentMapConverter[A, B](m: mutable.ConcurrentMap[A, B]): AsJava[juc.ConcurrentMap[A, B]] = new AsJava(asJavaConcurrentMap(m)) /** - * Adds an `asScala` method that implicitly converts a Java <code>Iterator</code> to a Scala <code>Iterator</code>. - * The returned Scala <code>Iterator</code> is backed by the provided Java - * <code>Iterator</code> and any side-effects of using it via the Scala interface will - * be visible via the Java interface and vice versa. - * <p> - * If the Java <code>Iterator</code> was previously obtained from an implicit or - * explicit call of <code>asIterator(scala.collection.Iterator)</code> then the original - * Scala <code>Iterator</code> will be returned. + * Adds an `asScala` method that implicitly converts a Java `Iterator` to + * a Scala `Iterator`. + * + * The returned Scala `Iterator` is backed by the provided Java `Iterator` + * and any side-effects of using it via the Scala interface will be visible + * via the Java interface and vice versa. * - * @param i The <code>Iterator</code> to be converted. - * @return An object with an `asScala` method that returns a Scala <code>Iterator</code> view of the argument. + * If the Java `Iterator` was previously obtained from an implicit or + * explicit call of `asIterator(scala.collection.Iterator)` then the + * original Scala `Iterator` will be returned. + * + * @param i The `Iterator` to be converted. + * @return An object with an `asScala` method that returns a Scala + * `Iterator` view of the argument. */ implicit def asScalaIteratorConverter[A](i : ju.Iterator[A]): AsScala[Iterator[A]] = new AsScala(asScalaIterator(i)) /** - * Adds an `asScala` method that implicitly converts a Java <code>Enumeration</code> to a Scala <code>Iterator</code>. - * The returned Scala <code>Iterator</code> is backed by the provided Java - * <code>Enumeration</code> and any side-effects of using it via the Scala interface will - * be visible via the Java interface and vice versa. - * <p> - * If the Java <code>Enumeration</code> was previously obtained from an implicit or - * explicit call of <code>asEnumeration(scala.collection.Iterator)</code> then the - * original Scala <code>Iterator</code> will be returned. + * Adds an `asScala` method that implicitly converts a Java `Enumeration` + * to a Scala `Iterator`. * - * @param i The <code>Enumeration</code> to be converted. - * @return An object with an `asScala` method that returns a Scala <code>Iterator</code> view of the argument. + * The returned Scala `Iterator` is backed by the provided Java + * `Enumeration` and any side-effects of using it via the Scala interface + * will be visible via the Java interface and vice versa. + * + * If the Java `Enumeration` was previously obtained from an implicit or + * explicit call of `asEnumeration(scala.collection.Iterator)` then the + * original Scala `Iterator` will be returned. + * + * @param i The `Enumeration` to be converted. + * @return An object with an `asScala` method that returns a Scala + * `Iterator` view of the argument. */ implicit def enumerationAsScalaIteratorConverter[A](i : ju.Enumeration[A]): AsScala[Iterator[A]] = new AsScala(enumerationAsScalaIterator(i)) @@ -393,49 +421,56 @@ object JavaConverters { def asScalaIterableConverter[A](i : ju.Collection[A]): AsScala[Iterable[A]] = collectionAsScalaIterableConverter(i) /** - * Adds an `asScala` method that implicitly converts a Java <code>List</code> to a Scala mutable <code>Buffer</code>. - * The returned Scala <code>Buffer</code> is backed by the provided Java - * <code>List</code> and any side-effects of using it via the Scala interface will - * be visible via the Java interface and vice versa. - * <p> - * If the Java <code>List</code> was previously obtained from an implicit or - * explicit call of <code>asList(scala.collection.mutable.Buffer)</code> then the original - * Scala <code>Buffer</code> will be returned. + * Adds an `asScala` method that implicitly converts a Java `List` to a + * Scala mutable `Buffer`. + * + * The returned Scala `Buffer` is backed by the provided Java `List` and + * any side-effects of using it via the Scala interface will be visible via + * the Java interface and vice versa. + * + * If the Java `List` was previously obtained from an implicit or explicit + * call of `asList(scala.collection.mutable.Buffer)` then the original + * Scala `Buffer` will be returned. * - * @param l The <code>List</code> to be converted. - * @return An object with an `asScala` method that returns a Scala mutable <code>Buffer</code> view of the argument. + * @param l The `List` to be converted. + * @return An object with an `asScala` method that returns a Scala mutable + * `Buffer` view of the argument. */ implicit def asScalaBufferConverter[A](l : ju.List[A]): AsScala[mutable.Buffer[A]] = new AsScala(asScalaBuffer(l)) /** - * Adds an `asScala` method that implicitly converts a Java <code>Set</code> to a Scala mutable <code>Set</code>. - * The returned Scala <code>Set</code> is backed by the provided Java - * <code>Set</code> and any side-effects of using it via the Scala interface will - * be visible via the Java interface and vice versa. - * <p> - * If the Java <code>Set</code> was previously obtained from an implicit or - * explicit call of <code>asSet(scala.collection.mutable.Set)</code> then the original - * Scala <code>Set</code> will be returned. + * Adds an `asScala` method that implicitly converts a Java `Set` to a + * Scala mutable `Set`. * - * @param s The <code>Set</code> to be converted. - * @return An object with an `asScala` method that returns a Scala mutable <code>Set</code> view of the argument. + * The returned Scala `Set` is backed by the provided Java `Set` and any + * side-effects of using it via the Scala interface will be visible via + * the Java interface and vice versa. + * + * If the Java `Set` was previously obtained from an implicit or explicit + * call of `asSet(scala.collection.mutable.Set)` then the original + * Scala `Set` will be returned. + * + * @param s The `Set` to be converted. + * @return An object with an `asScala` method that returns a Scala mutable + * `Set` view of the argument. */ implicit def asScalaSetConverter[A](s : ju.Set[A]): AsScala[mutable.Set[A]] = new AsScala(asScalaSet(s)) /** - * Adds an `asScala` method that implicitly converts a Java <code>Map</code> to a Scala mutable <code>Map</code>. - * The returned Scala <code>Map</code> is backed by the provided Java - * <code>Map</code> and any side-effects of using it via the Scala interface will + * Adds an `asScala` method that implicitly converts a Java `Map` to a Scala + * mutable `Map`. The returned Scala `Map` is backed by the provided Java + * `Map` and any side-effects of using it via the Scala interface will * be visible via the Java interface and vice versa. - * <p> - * If the Java <code>Map</code> was previously obtained from an implicit or - * explicit call of <code>asMap(scala.collection.mutable.Map)</code> then the original - * Scala <code>Map</code> will be returned. * - * @param m The <code>Map</code> to be converted. - * @return An object with an `asScala` method that returns a Scala mutable <code>Map</code> view of the argument. + * If the Java `Map` was previously obtained from an implicit or explicit + * call of `asMap(scala.collection.mutable.Map)` then the original + * Scala `Map` will be returned. + * + * @param m The `Map` to be converted. + * @return An object with an `asScala` method that returns a Scala mutable + * `Map` view of the argument. */ implicit def mapAsScalaMapConverter[A, B](m : ju.Map[A, B]): AsScala[mutable.Map[A, B]] = new AsScala(mapAsScalaMap(m)) @@ -444,41 +479,47 @@ object JavaConverters { def asScalaMapConverter[A, B](m : ju.Map[A, B]): AsScala[mutable.Map[A, B]] = mapAsScalaMapConverter(m) /** - * Adds an `asScala` method that implicitly converts a Java <code>ConcurrentMap</code> to a Scala mutable <code>ConcurrentMap</code>. - * The returned Scala <code>ConcurrentMap</code> is backed by the provided Java - * <code>ConcurrentMap</code> and any side-effects of using it via the Scala interface will - * be visible via the Java interface and vice versa. - * <p> - * If the Java <code>ConcurrentMap</code> was previously obtained from an implicit or - * explicit call of <code>asConcurrentMap(scala.collection.mutable.ConcurrentMap)</code> then the original - * Scala <code>ConcurrentMap</code> will be returned. + * Adds an `asScala` method that implicitly converts a Java `ConcurrentMap` + * to a Scala mutable `ConcurrentMap`. The returned Scala `ConcurrentMap` is + * backed by the provided Java `ConcurrentMap` and any side-effects of using + * it via the Scala interface will be visible via the Java interface and + * vice versa. + * + * If the Java `ConcurrentMap` was previously obtained from an implicit or + * explicit call of `asConcurrentMap(scala.collection.mutable.ConcurrentMap)` + * then the original Scala `ConcurrentMap` will be returned. * - * @param m The <code>ConcurrentMap</code> to be converted. - * @return An object with an `asScala` method that returns a Scala mutable <code>ConcurrentMap</code> view of the argument. + * @param m The `ConcurrentMap` to be converted. + * @return An object with an `asScala` method that returns a Scala mutable + * `ConcurrentMap` view of the argument. */ implicit def asScalaConcurrentMapConverter[A, B](m: juc.ConcurrentMap[A, B]): AsScala[mutable.ConcurrentMap[A, B]] = new AsScala(asScalaConcurrentMap(m)) /** - * Adds an `asScala` method that implicitly converts a Java <code>Dictionary</code> to a Scala mutable <code>Map[String, String]</code>. - * The returned Scala <code>Map[String, String]</code> is backed by the provided Java - * <code>Dictionary</code> and any side-effects of using it via the Scala interface will - * be visible via the Java interface and vice versa. + * Adds an `asScala` method that implicitly converts a Java `Dictionary` + * to a Scala mutable `Map[String, String]`. The returned Scala + * `Map[String, String]` is backed by the provided Java `Dictionary` and + * any side-effects of using it via the Scala interface will be visible via + * the Java interface and vice versa. * - * @param m The <code>Dictionary</code> to be converted. - * @return An object with an `asScala` method that returns a Scala mutable <code>Map[String, String]</code> view of the argument. + * @param m The `Dictionary` to be converted. + * @return An object with an `asScala` method that returns a Scala mutable + * `Map[String, String]` view of the argument. */ implicit def dictionaryAsScalaMapConverter[A, B](p: ju.Dictionary[A, B]): AsScala[mutable.Map[A, B]] = new AsScala(dictionaryAsScalaMap(p)) /** - * Adds an `asScala` method that implicitly converts a Java <code>Properties</code> to a Scala mutable <code>Map[String, String]</code>. - * The returned Scala <code>Map[String, String]</code> is backed by the provided Java - * <code>Properties</code> and any side-effects of using it via the Scala interface will - * be visible via the Java interface and vice versa. + * Adds an `asScala` method that implicitly converts a Java `Properties` + * to a Scala mutable `Map[String, String]`. The returned Scala + * `Map[String, String]` is backed by the provided Java `Properties` and + * any side-effects of using it via the Scala interface will be visible via + * the Java interface and vice versa. * - * @param m The <code>Properties</code> to be converted. - * @return An object with an `asScala` method that returns a Scala mutable <code>Map[String, String]</code> view of the argument. + * @param m The `Properties` to be converted. + * @return An object with an `asScala` method that returns a Scala mutable + * `Map[String, String]` view of the argument. */ implicit def propertiesAsScalaMapConverter(p: ju.Properties): AsScala[mutable.Map[String, String]] = new AsScala(propertiesAsScalaMap(p)) diff --git a/src/library/scala/collection/SeqViewLike.scala b/src/library/scala/collection/SeqViewLike.scala index 37c66802ef..6e8afdd04f 100644 --- a/src/library/scala/collection/SeqViewLike.scala +++ b/src/library/scala/collection/SeqViewLike.scala @@ -6,8 +6,6 @@ ** |/ ** \* */ - - package scala.collection import generic._ @@ -20,7 +18,8 @@ import annotation.bridge * * @define seqViewInfo * $viewInfo - * All views for sequences are defined by re-interpreting the `length` and `apply` methods. + * All views for sequences are defined by re-interpreting the `length` and + * `apply` methods. * * @author Martin Odersky * @version 2.8 @@ -142,5 +141,3 @@ trait SeqViewLike[+A, override def stringPrefix = "SeqView" } - - diff --git a/src/library/scala/collection/TraversableLike.scala b/src/library/scala/collection/TraversableLike.scala index c8b8dfda5f..1f6c6ff0bb 100644 --- a/src/library/scala/collection/TraversableLike.scala +++ b/src/library/scala/collection/TraversableLike.scala @@ -39,8 +39,7 @@ import parallel.ParIterable * a non-strict collection class may defer computation of some of their * elements until after the instance is available as a value. * A typical example of a non-strict collection class is a - * <a href="../immutable/Stream.html" target="ContentFrame"> - * `scala.collection.immutable.Stream`</a>. + * [[scala.collection.immutable/Stream]]. * A more general class of examples are `TraversableViews`. * * If a collection is an instance of an ordered collection class, traversing @@ -134,13 +133,15 @@ trait TraversableLike[+A, +Repr] extends HasNewBuilder[A, Repr] } /** Tests whether this $coll is known to have a finite size. - * All strict collections are known to have finite size. For a non-strict collection - * such as `Stream`, the predicate returns `true` if all elements have been computed. - * It returns `false` if the stream is not yet evaluated to the end. + * All strict collections are known to have finite size. For a non-strict + * collection such as `Stream`, the predicate returns `'''true'''` if all + * elements have been computed. It returns `'''false'''` if the stream is + * not yet evaluated to the end. * * Note: many collection methods will not work on collections of infinite sizes. * - * @return `true` if this collection is known to have finite size, `false` otherwise. + * @return `'''true'''` if this collection is known to have finite size, + * `'''false'''` otherwise. */ def hasDefiniteSize = true @@ -157,8 +158,8 @@ trait TraversableLike[+A, +Repr] extends HasNewBuilder[A, Repr] ++(that: GenTraversableOnce[B])(bf) /** Concatenates this $coll with the elements of a traversable collection. - * It differs from ++ in that the right operand determines the type of the - * resulting collection rather than the left one. + * It differs from `++` in that the right operand determines the type of + * the resulting collection rather than the left one. * * @param that the traversable to append. * @tparam B the element type of the returned collection. @@ -180,10 +181,12 @@ trait TraversableLike[+A, +Repr] extends HasNewBuilder[A, Repr] b.result } - /** This overload exists because: for the implementation of ++: we should reuse - * that of ++ because many collections override it with more efficient versions. - * Since TraversableOnce has no '++' method, we have to implement that directly, - * but Traversable and down can use the overload. + /** This overload exists because: for the implementation of `++`: we should + * reuse that of `++` because many collections override it with more + * efficient versions. + * + * Since `TraversableOnce` has no `++` method, we have to implement that + * directly, but `Traversable` and down can use the overload. */ def ++:[B >: A, That](that: Traversable[B])(implicit bf: CanBuildFrom[Repr, B, That]): That = (that ++ seq)(breakOut) diff --git a/src/library/scala/collection/generic/IterableForwarder.scala b/src/library/scala/collection/generic/IterableForwarder.scala index 8f9c4c9542..89b67a6c18 100644 --- a/src/library/scala/collection/generic/IterableForwarder.scala +++ b/src/library/scala/collection/generic/IterableForwarder.scala @@ -13,20 +13,15 @@ import scala.collection._ import collection.mutable.Buffer -/** <p> - * This trait implements a forwarder for iterable objects. It forwards - * all calls to a different iterable object, except for - * </p> - * <ul> - * <li><code>toString</code>, <code>hashCode</code>, <code>equals</code>, - * <code>stringPrefix</code></li> - * <li><code>newBuilder</code>, <code>view</code></li> - * <li>all calls creating a new iterable object of the same kind</li> - * </ul> - * <p> - * The above methods are forwarded by subclass <a href="../IterableProxy.html" - * target="ContentFrame"><code>IterableProxy</code></a>. - * </p> +/** This trait implements a forwarder for iterable objects. It forwards + * all calls to a different iterable object, except for + * + * - `toString`, `hashCode`, `equals`, `stringPrefix` + * - `newBuilder`, `view` + * - all calls creating a new iterable object of the same kind + * + * The above methods are forwarded by subclass <a href="../IterableProxy.html" + * target="ContentFrame">`IterableProxy`</a>. * * @author Martin Odersky * @version 2.8 diff --git a/src/library/scala/collection/generic/SeqForwarder.scala b/src/library/scala/collection/generic/SeqForwarder.scala index 2624e63a90..eb8e0b3ee9 100644 --- a/src/library/scala/collection/generic/SeqForwarder.scala +++ b/src/library/scala/collection/generic/SeqForwarder.scala @@ -6,8 +6,6 @@ ** |/ ** \* */ - - package scala.collection.generic import scala.collection._ import scala.collection.immutable.Range @@ -15,11 +13,11 @@ import scala.collection.immutable.Range /** This class implements a forwarder for sequences. It forwards * all calls to a different sequence object except for * - * - toString, hashCode, equals, stringPrefix - * - newBuilder, view, toSeq + * - `toString`, `hashCode`, `equals`, `stringPrefix` + * - `newBuilder`, `view`, `toSeq` * - all calls creating a new sequence of the same kind * - * The above methods are forwarded by subclass SeqProxy + * The above methods are forwarded by subclass `SeqProxy`. * * @author Martin Odersky * @version 2.8 @@ -31,29 +29,29 @@ trait SeqForwarder[+A] extends Seq[A] with IterableForwarder[A] { override def length: Int = underlying.length override def apply(idx: Int): A = underlying.apply(idx) - override def lengthCompare(len: Int): Int = underlying.lengthCompare(len) - override def isDefinedAt(x: Int): Boolean = underlying.isDefinedAt(x) + override def lengthCompare(len: Int): Int = underlying lengthCompare len + override def isDefinedAt(x: Int): Boolean = underlying isDefinedAt x override def segmentLength(p: A => Boolean, from: Int): Int = underlying.segmentLength(p, from) - override def prefixLength(p: A => Boolean) = underlying.prefixLength(p) - override def indexWhere(p: A => Boolean): Int = underlying.indexWhere(p) + override def prefixLength(p: A => Boolean) = underlying prefixLength p + override def indexWhere(p: A => Boolean): Int = underlying indexWhere p override def indexWhere(p: A => Boolean, from: Int): Int = underlying.indexWhere(p, from) - override def findIndexOf(p: A => Boolean): Int = underlying.indexWhere(p) - override def indexOf[B >: A](elem: B): Int = underlying.indexOf(elem) + override def findIndexOf(p: A => Boolean): Int = underlying indexWhere p + override def indexOf[B >: A](elem: B): Int = underlying indexOf elem override def indexOf[B >: A](elem: B, from: Int): Int = underlying.indexOf(elem, from) - override def lastIndexOf[B >: A](elem: B): Int = underlying.lastIndexOf(elem) + override def lastIndexOf[B >: A](elem: B): Int = underlying lastIndexOf elem override def lastIndexOf[B >: A](elem: B, end: Int): Int = underlying.lastIndexOf(elem, end) - override def lastIndexWhere(p: A => Boolean): Int = underlying.lastIndexWhere(p) + override def lastIndexWhere(p: A => Boolean): Int = underlying lastIndexWhere p override def lastIndexWhere(p: A => Boolean, end: Int): Int = underlying.lastIndexWhere(p, end) override def reverseIterator: Iterator[A] = underlying.reverseIterator override def startsWith[B](that: GenSeq[B], offset: Int): Boolean = underlying.startsWith(that, offset) - override def startsWith[B](that: GenSeq[B]): Boolean = underlying.startsWith(that) - override def endsWith[B](that: GenSeq[B]): Boolean = underlying.endsWith(that) - override def indexOfSlice[B >: A](that: GenSeq[B]): Int = underlying.indexOfSlice(that) + override def startsWith[B](that: GenSeq[B]): Boolean = underlying startsWith that + override def endsWith[B](that: GenSeq[B]): Boolean = underlying endsWith that + override def indexOfSlice[B >: A](that: GenSeq[B]): Int = underlying indexOfSlice that override def indexOfSlice[B >: A](that: GenSeq[B], from: Int): Int = underlying.indexOfSlice(that, from) - override def lastIndexOfSlice[B >: A](that: GenSeq[B]): Int = underlying.lastIndexOfSlice(that) + override def lastIndexOfSlice[B >: A](that: GenSeq[B]): Int = underlying lastIndexOfSlice that override def lastIndexOfSlice[B >: A](that: GenSeq[B], end: Int): Int = underlying.lastIndexOfSlice(that, end) - override def containsSlice[B](that: GenSeq[B]): Boolean = underlying.containsSlice(that) - override def contains(elem: Any): Boolean = underlying.contains(elem) + override def containsSlice[B](that: GenSeq[B]): Boolean = underlying containsSlice that + override def contains(elem: Any): Boolean = underlying contains elem override def corresponds[B](that: GenSeq[B])(p: (A,B) => Boolean): Boolean = underlying.corresponds(that)(p) override def indices: Range = underlying.indices } diff --git a/src/library/scala/collection/generic/TraversableForwarder.scala b/src/library/scala/collection/generic/TraversableForwarder.scala index 0049d23a86..6529fe4a79 100644 --- a/src/library/scala/collection/generic/TraversableForwarder.scala +++ b/src/library/scala/collection/generic/TraversableForwarder.scala @@ -14,9 +14,10 @@ import immutable.{ List, Stream } /** This trait implements a forwarder for traversable objects. It forwards * all calls to a different traversable, except for: - {{{ - toString, hashCode, equals, stringPrefix, newBuilder, view - }}} + * + * - `toString`, `hashCode`, `equals`, `stringPrefix` + * - `newBuilder`, `view` + * * All calls creating a new traversable of the same kind. * * @author Martin Odersky @@ -27,15 +28,15 @@ trait TraversableForwarder[+A] extends Traversable[A] { /** The traversable object to which calls are forwarded. */ protected def underlying: Traversable[A] - override def foreach[B](f: A => B): Unit = underlying.foreach(f) + override def foreach[B](f: A => B): Unit = underlying foreach f override def isEmpty: Boolean = underlying.isEmpty override def nonEmpty: Boolean = underlying.nonEmpty override def size: Int = underlying.size override def hasDefiniteSize = underlying.hasDefiniteSize - override def forall(p: A => Boolean): Boolean = underlying.forall(p) - override def exists(p: A => Boolean): Boolean = underlying.exists(p) - override def count(p: A => Boolean): Int = underlying.count(p) - override def find(p: A => Boolean): Option[A] = underlying.find(p) + override def forall(p: A => Boolean): Boolean = underlying forall p + override def exists(p: A => Boolean): Boolean = underlying exists p + override def count(p: A => Boolean): Int = underlying count p + override def find(p: A => Boolean): Option[A] = underlying find p override def foldLeft[B](z: B)(op: (B, A) => B): B = underlying.foldLeft(z)(op) override def /: [B](z: B)(op: (B, A) => B): B = underlying./:(z)(op) override def foldRight[B](z: B)(op: (A, B) => B): B = underlying.foldRight(z)(op) @@ -44,10 +45,10 @@ trait TraversableForwarder[+A] extends Traversable[A] { override def reduceLeftOption[B >: A](op: (B, A) => B): Option[B] = underlying.reduceLeftOption(op) override def reduceRight[B >: A](op: (A, B) => B): B = underlying.reduceRight(op) override def reduceRightOption[B >: A](op: (A, B) => B): Option[B] = underlying.reduceRightOption(op) - override def sum[B >: A](implicit num: Numeric[B]): B = underlying.sum(num) - override def product[B >: A](implicit num: Numeric[B]): B = underlying.product(num) - override def min[B >: A](implicit cmp: Ordering[B]): A = underlying.min(cmp) - override def max[B >: A](implicit cmp: Ordering[B]): A = underlying.max(cmp) + override def sum[B >: A](implicit num: Numeric[B]): B = underlying sum num + override def product[B >: A](implicit num: Numeric[B]): B = underlying product num + override def min[B >: A](implicit cmp: Ordering[B]): A = underlying min cmp + override def max[B >: A](implicit cmp: Ordering[B]): A = underlying max cmp override def head: A = underlying.head override def headOption: Option[A] = underlying.headOption override def last: A = underlying.last diff --git a/src/library/scala/collection/immutable/BitSet.scala b/src/library/scala/collection/immutable/BitSet.scala index 918c79ef0d..bc82c4c133 100644 --- a/src/library/scala/collection/immutable/BitSet.scala +++ b/src/library/scala/collection/immutable/BitSet.scala @@ -29,8 +29,7 @@ abstract class BitSet extends Set[Int] def fromArray(elems: Array[Long]): BitSet = BitSet.fromArray(elems) - /** Update word at index <code>idx</code>; enlarge set if <code>idx</code> - * outside range of set. + /** Update word at index `idx`; enlarge set if `idx` outside range of set. */ protected def updateWord(idx: Int, w: Long): BitSet @@ -103,4 +102,3 @@ object BitSet extends BitSetFactory[BitSet] { protected def updateWord(idx: Int, w: Long): BitSet = fromArray(updateArray(elems, idx, w)) } } - diff --git a/src/library/scala/collection/immutable/IntMap.scala b/src/library/scala/collection/immutable/IntMap.scala index ea68b53518..cb1065d786 100644 --- a/src/library/scala/collection/immutable/IntMap.scala +++ b/src/library/scala/collection/immutable/IntMap.scala @@ -312,31 +312,32 @@ 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) + * 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 `f(key, value)`. * * @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) => { - val newleft = left.modifyOrRemove(f); - val newright = right.modifyOrRemove(f); - if ((left eq newleft) && (right eq newright)) this.asInstanceOf[IntMap[S]]; - else bin(prefix, mask, newleft, newright) - } + case IntMap.Bin(prefix, mask, left, right) => + val newleft = left.modifyOrRemove(f) + val newright = right.modifyOrRemove(f) + if ((left eq newleft) && (right eq newright)) this.asInstanceOf[IntMap[S]] + else bin(prefix, mask, newleft, newright) case IntMap.Tip(key, value) => f(key, value) match { - case None => IntMap.Nil; + case None => + IntMap.Nil case Some(value2) => //hack to preserve sharing if (value.asInstanceOf[AnyRef] eq value2.asInstanceOf[AnyRef]) this.asInstanceOf[IntMap[S]] - else IntMap.Tip(key, value2); + else IntMap.Tip(key, value2) } - case IntMap.Nil => IntMap.Nil; + case IntMap.Nil => + IntMap.Nil } - /** * Forms a union map with that map, using the combining function to resolve conflicts. * @@ -367,9 +368,9 @@ sealed abstract class IntMap[+T] extends Map[Int, T] with MapLike[Int, T, IntMap } /** - * Forms the intersection of these two maps with a combining function. The resulting map is - * a map that has only keys present in both maps and has values produced from the original mappings - * by combining them with f. + * Forms the intersection of these two maps with a combining function. The + * resulting map is a map that has only keys present in both maps and has + * values produced from the original mappings by combining them with `f`. * * @tparam S The type of values in `that`. * @tparam R The type of values in the resulting `LongMap`. @@ -380,29 +381,29 @@ sealed abstract class IntMap[+T] extends Map[Int, T] with MapLike[Int, T, IntMap 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)) => if (shorter(m1, m2)) { - if (!hasMatch(p2, p1, m1)) IntMap.Nil; - else if (zero(p2, m1)) l1.intersectionWith(that, f); - else r1.intersectionWith(that, f); + if (!hasMatch(p2, p1, m1)) IntMap.Nil + else if (zero(p2, m1)) l1.intersectionWith(that, f) + else r1.intersectionWith(that, f) } else if (m1 == m2) bin(p1, m1, l1.intersectionWith(l2, f), r1.intersectionWith(r2, f)); else { - if (!hasMatch(p1, p2, m2)) IntMap.Nil; - else if (zero(p1, m2)) this.intersectionWith(l2, f); - else this.intersectionWith(r2, f); + if (!hasMatch(p1, p2, m2)) IntMap.Nil + else if (zero(p1, m2)) this.intersectionWith(l2, f) + else this.intersectionWith(r2, f) } case (IntMap.Tip(key, value), that) => that.get(key) match { - case None => IntMap.Nil; - case Some(value2) => IntMap.Tip(key, f(key, value, value2)); + case None => IntMap.Nil + case Some(value2) => IntMap.Tip(key, f(key, value, value2)) } case (_, IntMap.Tip(key, value)) => this.get(key) match { - case None => IntMap.Nil; - case Some(value2) => IntMap.Tip(key, f(key, value2, value)); + case None => IntMap.Nil + case Some(value2) => IntMap.Tip(key, f(key, value2, value)) } - case (_, _) => IntMap.Nil; + case (_, _) => IntMap.Nil } /** - * 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. + * 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. * * @tparam R The type of values in `that`. * @param that The map to intersect with. @@ -417,8 +418,8 @@ sealed abstract class IntMap[+T] extends Map[Int, T] with MapLike[Int, T, IntMap * The entry with the lowest key value considered in unsigned order. */ final def firstKey : Int = this match { - case Bin(_, _, l, r) => l.firstKey; - case Tip(k, v) => k; + case Bin(_, _, l, r) => l.firstKey + case Tip(k, v) => k case IntMap.Nil => sys.error("Empty set") } @@ -426,8 +427,8 @@ sealed abstract class IntMap[+T] extends Map[Int, T] with MapLike[Int, T, IntMap * The entry with the highest key value considered in unsigned order. */ final def lastKey : Int = this match { - case Bin(_, _, l, r) => r.lastKey; - case Tip(k, v) => k; + case Bin(_, _, l, r) => r.lastKey + case Tip(k, v) => k case IntMap.Nil => sys.error("Empty set") } } diff --git a/src/library/scala/collection/immutable/List.scala b/src/library/scala/collection/immutable/List.scala index 7d962d2908..8f7d92f9e5 100644 --- a/src/library/scala/collection/immutable/List.scala +++ b/src/library/scala/collection/immutable/List.scala @@ -246,7 +246,7 @@ sealed abstract class List[+A] extends LinearSeq[A] if (isEmpty) Stream.Empty else new Stream.Cons(head, tail.toStream) - /** Like <code>span</code> but with the predicate inverted. + /** Like `span` but with the predicate inverted. */ @deprecated("use `span { x => !p(x) }` instead", "2.8.0") def break(p: A => Boolean): (List[A], List[A]) = span { x => !p(x) } @@ -254,12 +254,10 @@ sealed abstract class List[+A] extends LinearSeq[A] @deprecated("use `filterNot` instead", "2.8.0") def remove(p: A => Boolean): List[A] = filterNot(p) - /** Computes the difference between this list and the given list - * `that`. + /** Computes the difference between this list and the given list `that`. * * @param that the list of elements to remove from this list. - * @return this list without the elements of the given list - * `that`. + * @return this list without the elements of the given list `that`. */ @deprecated("use `list1 filterNot (list2 contains)` instead", "2.8.0") def -- [B >: A](that: List[B]): List[B] = { @@ -272,8 +270,7 @@ sealed abstract class List[+A] extends LinearSeq[A] b.toList } - /** Computes the difference between this list and the given object - * `x`. + /** Computes the difference between this list and the given object `x`. * * @param x the object to remove from this list. * @return this list without occurrences of the given object @@ -317,7 +314,7 @@ sealed abstract class List[+A] extends LinearSeq[A] res.toList } - /** Split a list into two lists of about the same size */ + /** Split a list `lst` into two lists of about the same size */ def split(lst: List[A]) = { val res1 = new ListBuffer[A] val res2 = new ListBuffer[A] @@ -335,7 +332,6 @@ sealed abstract class List[+A] extends LinearSeq[A] (res1.toList, res2.toList) } - /** Merge-sort the specified list */ def ms(lst: List[A]): List[A] = lst match { @@ -435,18 +431,16 @@ object List extends SeqFactory[List] { override def apply[A](xs: A*): List[A] = xs.toList - /** Create a sorted list with element values - * `v<sub>n+1</sub> = step(v<sub>n</sub>)` - * where `v<sub>0</sub> = start` - * and elements are in the range between `start` (inclusive) - * and `end` (exclusive) + /** Create a sorted list with element values `v,,>n+1,, = step(v,,n,,)` + * where `v,,0,, = start` and elements are in the range between `start` + * (inclusive) and `end` (exclusive). * * @param start the start value of the list * @param end the end value of the list - * @param step the increment function of the list, which given `v<sub>n</sub>`, - * computes `v<sub>n+1</sub>`. Must be monotonically increasing + * @param step the increment function of the list, which given `v,,n,,`, + * computes `v,,n+1,,`. Must be monotonically increasing * or decreasing. - * @return the sorted list of all integers in range [start;end). + * @return the sorted list of all integers in range `[start;end)`. */ @deprecated("use `iterate` instead", "2.8.0") def range(start: Int, end: Int, step: Int => Int): List[Int] = { @@ -468,7 +462,7 @@ object List extends SeqFactory[List] { * * @param n the length of the resulting list * @param elem the element composing the resulting list - * @return a list composed of n elements all equal to elem + * @return a list composed of `n` elements all equal to `elem` */ @deprecated("use `fill` instead", "2.8.0") def make[A](n: Int, elem: A): List[A] = { @@ -529,8 +523,7 @@ object List extends SeqFactory[List] { } /** - * Returns the `Left` values in the given `Iterable` - * of `Either`s. + * Returns the `Left` values in the given `Iterable` of `Either`s. */ @deprecated("use `xs collect { case Left(x: A) => x }` instead of `List.lefts(xs)`", "2.8.0") def lefts[A, B](es: Iterable[Either[A, B]]) = @@ -540,7 +533,7 @@ object List extends SeqFactory[List] { }) /** - * Returns the `Right` values in the given`Iterable` of `Either`s. + * Returns the `Right` values in the given `Iterable` of `Either`s. */ @deprecated("use `xs collect { case Right(x: B) => x }` instead of `List.rights(xs)`", "2.8.0") def rights[A, B](es: Iterable[Either[A, B]]) = @@ -667,8 +660,8 @@ object List extends SeqFactory[List] { * to corresponding elements of the argument lists. * * @param f function to apply to each pair of elements. - * @return `[f(a0,b0), ..., f(an,bn)]` if the lists are - * `[a0, ..., ak]`, `[b0, ..., bl]` and + * @return `[f(a,,0,,,b,,0,,), ..., f(a,,n,,,b,,n,,)]` if the lists are + * `[a,,0,,, ..., a,,k,,]`, `[b,,0,,, ..., b,,l,,]` and * `n = min(k,l)` */ @deprecated("use `(xs, ys).zipped.map(f)` instead of `List.map2(xs, ys)(f)`", "2.8.0") @@ -688,12 +681,10 @@ object List extends SeqFactory[List] { * `f` to corresponding elements of the argument lists. * * @param f function to apply to each pair of elements. - * @return `[f(a<sub>0</sub>,b<sub>0</sub>,c<sub>0</sub>), - * ..., f(a<sub>n</sub>,b<sub>n</sub>,c<sub>n</sub>)]` - * if the lists are `[a<sub>0</sub>, ..., a<sub>k</sub>]`, - * `[b<sub>0</sub>, ..., b<sub>l</sub>]`, - * `[c<sub>0</sub>, ..., c<sub>m</sub>]` and - * `n = min(k,l,m)` + * @return `[f(a,,0,,,b,,0,,,c,,0,,), ..., f(a,,n,,,b,,n,,,c,,n,,)]` + * if the lists are `[a,,0,,, ..., a,,k,,]`, + * `[b<sub>0</sub>, ..., b,,l,,]`, + * `[c<sub>0</sub>, ..., c,,m,,]` and `n = min(k,l,m)` */ @deprecated("use `(xs, ys, zs).zipped.map(f)` instead of `List.map3(xs, ys, zs)(f)`", "2.8.0") def map3[A,B,C,D](xs: List[A], ys: List[B], zs: List[C])(f: (A, B, C) => D): List[D] = { @@ -775,4 +766,3 @@ object List extends SeqFactory[List] { /** Only used for list serialization */ @SerialVersionUID(0L - 8476791151975527571L) private[scala] case object ListSerializeEnd - diff --git a/src/library/scala/collection/immutable/LongMap.scala b/src/library/scala/collection/immutable/LongMap.scala index 030dd72d35..6c951a6ff2 100644 --- a/src/library/scala/collection/immutable/LongMap.scala +++ b/src/library/scala/collection/immutable/LongMap.scala @@ -309,8 +309,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) + * 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 `f(key, value)`. * * @tparam S The type of the values in the resulting `LongMap`. * @param f The transforming function. @@ -333,7 +334,6 @@ sealed abstract class LongMap[+T] extends Map[Long, T] with MapLike[Long, T, Lon case LongMap.Nil => LongMap.Nil; } - /** * Forms a union map with that map, using the combining function to resolve conflicts. * @@ -364,9 +364,9 @@ sealed abstract class LongMap[+T] extends Map[Long, T] with MapLike[Long, T, Lon } /** - * Forms the intersection of these two maps with a combining function. The resulting map is - * a map that has only keys present in both maps and has values produced from the original mappings - * by combining them with f. + * Forms the intersection of these two maps with a combining function. The + * resulting map is a map that has only keys present in both maps and has + * values produced from the original mappings by combining them with `f`. * * @tparam S The type of values in `that`. * @tparam R The type of values in the resulting `LongMap`. diff --git a/src/library/scala/collection/immutable/Queue.scala b/src/library/scala/collection/immutable/Queue.scala index e09e4b7196..c3ae2ffa19 100644 --- a/src/library/scala/collection/immutable/Queue.scala +++ b/src/library/scala/collection/immutable/Queue.scala @@ -6,8 +6,6 @@ ** |/ ** \* */ - - package scala.collection package immutable @@ -36,7 +34,7 @@ class Queue[+A] protected(protected val in: List[A], protected val out: List[A]) override def companion: GenericCompanion[Queue] = Queue /** Returns the `n`-th element of this queue. - * The first element is at position 0. + * The first element is at position `0`. * * @param n index of the element to return * @return the element at position `n` in this queue. @@ -91,22 +89,22 @@ class Queue[+A] protected(protected val in: List[A], protected val out: List[A]) */ def enqueue[B >: A](elem: B) = new Queue(elem :: in, out) - /** Returns a new queue with all all elements provided by - * an <code>Iterable</code> object added at the end of - * the queue. - * The elements are prepended in the order they - * are given out by the iterator. + /** Returns a new queue with all elements provided by an `Iterable` object + * added at the end of the queue. + * + * The elements are prepended in the order they are given out by the + * iterator. * * @param iter an iterable object */ @deprecated("Use `enqueue` instead", "2.7.2") def +[B >: A](iter: Iterable[B]) = enqueue(iter) - /** Returns a new queue with all elements provided by - * an <code>Iterable</code> object added at the end of - * the queue. - * The elements are prepended in the order they - * are given out by the iterator. + /** Returns a new queue with all elements provided by an `Iterable` object + * added at the end of the queue. + * + * The elements are prepended in the order they are given out by the + * iterator. * * @param iter an iterable object */ diff --git a/src/library/scala/collection/immutable/Stack.scala b/src/library/scala/collection/immutable/Stack.scala index adbe34ed09..b172908f85 100644 --- a/src/library/scala/collection/immutable/Stack.scala +++ b/src/library/scala/collection/immutable/Stack.scala @@ -6,8 +6,6 @@ ** |/ ** \* */ - - package scala.collection package immutable @@ -102,7 +100,7 @@ class Stack[+A] protected (protected val elems: List[A]) else throw new NoSuchElementException("top of empty stack") /** Removes the top element from the stack. - * Note: should return <code>(A, Stack[A])</code> as for queues (mics) + * Note: should return `(A, Stack[A])` as for queues (mics) * * @throws Predef.NoSuchElementException * @return the new stack without the former top element. @@ -129,4 +127,3 @@ class Stack[+A] protected (protected val elems: List[A]) */ override def toString() = elems.mkString("Stack(", ", ", ")") } - diff --git a/src/library/scala/collection/mutable/AddingBuilder.scala b/src/library/scala/collection/mutable/AddingBuilder.scala index 6f198b81ad..d7f739d240 100644 --- a/src/library/scala/collection/mutable/AddingBuilder.scala +++ b/src/library/scala/collection/mutable/AddingBuilder.scala @@ -6,14 +6,13 @@ ** |/ ** \* */ - package scala.collection package mutable import generic._ -/** The canonical builder for collections that are addable, i.e. that support an efficient `+` method - * which adds an element to the collection. +/** The canonical builder for collections that are addable, i.e. that support + * an efficient `+` method which adds an element to the collection. * * Collections are built from their empty element using this `+` method. * @param empty the empty element of the collection. diff --git a/src/library/scala/collection/mutable/ConcurrentMap.scala b/src/library/scala/collection/mutable/ConcurrentMap.scala index a88679a8c9..7e526fd4ea 100644 --- a/src/library/scala/collection/mutable/ConcurrentMap.scala +++ b/src/library/scala/collection/mutable/ConcurrentMap.scala @@ -1,7 +1,14 @@ +/* __ *\ +** ________ ___ / / ___ Scala API ** +** / __/ __// _ | / / / _ | (c) 2010-2011, LAMP/EPFL ** +** __\ \/ /__/ __ |/ /__/ __ | http://scala-lang.org/ ** +** /____/\___/_/ |_/____/_/ | | ** +** |/ ** +\* */ + package scala.collection package mutable - /** A template trait for mutable maps that allow concurrent access. * * $concurrentmapinfo @@ -17,7 +24,8 @@ package mutable * This is a base trait for all Scala concurrent map implementations. It * provides all of the methods a `Map` does, with the difference that all the * changes are atomic. It also describes methods specific to concurrent maps. - * Note: The concurrent maps do not accept `null` for keys or values. + * + * '''Note''': The concurrent maps do not accept `'''null'''` for keys or values. * * @define atomicop * This is an atomic operation. @@ -25,42 +33,49 @@ package mutable trait ConcurrentMap[A, B] extends Map[A, B] { /** - * Associates the given key with a given value, unless the key was already associated with some other value. + * Associates the given key with a given value, unless the key was already + * associated with some other value. * * $atomicop * * @param k key with which the specified value is to be associated with * @param v value to be associated with the specified key - * @return `Some(oldvalue)` if there was a value `oldvalue` previously associated with the - * specified key, or `None` if there was no mapping for the specified key + * @return `Some(oldvalue)` if there was a value `oldvalue` previously + * associated with the specified key, or `None` if there was no + * mapping for the specified key */ def putIfAbsent(k: A, v: B): Option[B] /** - * Removes the entry for the specified key if its currently mapped to the specified value. + * Removes the entry for the specified key if its currently mapped to the + * specified value. * * $atomicop * * @param k key for which the entry should be removed - * @param v value expected to be associated with the specified key if the removal is to take place + * @param v value expected to be associated with the specified key if + * the removal is to take place * @return `true` if the removal took place, `false` otherwise */ def remove(k: A, v: B): Boolean /** - * Replaces the entry for the given key only if it was previously mapped to a given value. + * Replaces the entry for the given key only if it was previously mapped to + * a given value. * * $atomicop * * @param k key for which the entry should be replaced - * @param oldvalue value expected to be associated with the specified key if replacing is to happen + * @param oldvalue value expected to be associated with the specified key + * if replacing is to happen * @param newvalue value to be associated with the specified key * @return `true` if the entry was replaced, `false` otherwise */ def replace(k: A, oldvalue: B, newvalue: B): Boolean /** - * Replaces the entry for the given key only if it was previously mapped to some value. + * Replaces the entry for the given key only if it was previously mapped + * to some value. * * $atomicop * diff --git a/src/library/scala/collection/mutable/MapProxy.scala b/src/library/scala/collection/mutable/MapProxy.scala index d32f1559c0..5a77a0d23b 100644 --- a/src/library/scala/collection/mutable/MapProxy.scala +++ b/src/library/scala/collection/mutable/MapProxy.scala @@ -6,14 +6,11 @@ ** |/ ** \* */ - - package scala.collection package mutable /** - * This trait implements a proxy for <a href="Map.html" - * target="contentFrame"><code>scala.collection.mutable.Map</code></a>. + * This trait implements a proxy for [[scala.collection.mutable.Map]]. * * It is most useful for assembling customized map abstractions * dynamically using object composition and forwarding. diff --git a/src/library/scala/collection/mutable/MutableList.scala b/src/library/scala/collection/mutable/MutableList.scala index 3eb60698cd..dbabeafd0a 100644 --- a/src/library/scala/collection/mutable/MutableList.scala +++ b/src/library/scala/collection/mutable/MutableList.scala @@ -72,17 +72,17 @@ extends LinearSeq[A] */ override def length: Int = len - /** Returns the <code>n</code>th element of this list. + /** Returns the `n`-th element of this list. * @throws IndexOutOfBoundsException if index does not exist. */ override def apply(n: Int): A = first0.apply(n) - /** Updates the <code>n</code>th element of this list to a new value. + /** Updates the `n`-th element of this list to a new value. * @throws IndexOutOfBoundsException if index does not exist. */ def update(n: Int, x: A): Unit = first0.update(n, x) - /** Returns the <code>n</code>th element of this list or <code>None</code> + /** Returns the `n`-th element of this list or `None` * if index does not exist. */ def get(n: Int): Option[A] = first0.get(n) @@ -93,7 +93,7 @@ extends LinearSeq[A] len = len + 1 } - protected def appendElem(elem: A): Unit = + protected def appendElem(elem: A) { if (len == 0) { prependElem(elem) } else { @@ -103,6 +103,7 @@ extends LinearSeq[A] last0.next = new LinkedList[A] // for performance, use sentinel `object` instead? len = len + 1 } + } @deprecated("use clear() instead", "2.8.0") def reset() { clear() } @@ -116,7 +117,7 @@ extends LinearSeq[A] last0.elem } - /** Returns an instance of <code>scala.List</code> containing the same + /** Returns an instance of [[scala.List]] containing the same * sequence of elements. */ override def toList: List[A] = first0.toList @@ -143,11 +144,8 @@ extends LinearSeq[A] object MutableList extends SeqFactory[MutableList] { - implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, MutableList[A]] = ReusableCBF.asInstanceOf[GenericCanBuildFrom[A]] + implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, MutableList[A]] = + ReusableCBF.asInstanceOf[GenericCanBuildFrom[A]] def newBuilder[A]: Builder[A, MutableList[A]] = new MutableList[A] } - - - - diff --git a/src/library/scala/collection/mutable/QueueProxy.scala b/src/library/scala/collection/mutable/QueueProxy.scala index be26d41e69..df86545a70 100644 --- a/src/library/scala/collection/mutable/QueueProxy.scala +++ b/src/library/scala/collection/mutable/QueueProxy.scala @@ -1,7 +1,7 @@ /* __ *\ ** ________ ___ / / ___ Scala API ** ** / __/ __// _ | / / / _ | (c) 2003-2011, LAMP/EPFL ** -** __\ \/ /__/ __ |/ /__/ __ | ** +** __\ \/ /__/ __ |/ /__/ __ | http://scala-lang.org/ ** ** /____/\___/_/ |_/____/_/ | | ** ** |/ ** \* */ @@ -24,9 +24,9 @@ trait QueueProxy[A] extends Queue[A] with Proxy { def self: Queue[A] - /** Access element number <code>n</code>. + /** Access element number `n`. * - * @return the element at index <code>n</code>. + * @return the element at index `n`. */ override def apply(n: Int): A = self.apply(n) @@ -46,9 +46,8 @@ trait QueueProxy[A] extends Queue[A] with Proxy { */ override def +=(elem: A): this.type = { self += elem; this } - /** Adds all elements provided by an iterator - * at the end of the queue. The elements are prepended in the order they - * are given out by the iterator. + /** Adds all elements provided by an iterator at the end of the queue. The + * elements are prepended in the order they are given out by the iterator. * * @param iter an iterator */ @@ -61,7 +60,7 @@ trait QueueProxy[A] extends Queue[A] with Proxy { * * @param elems the elements to add. */ - override def enqueue(elems: A*): Unit = self ++= elems + override def enqueue(elems: A*) { self ++= elems } /** Returns the first element in the queue, and removes this element * from the queue. diff --git a/src/library/scala/collection/mutable/ResizableArray.scala b/src/library/scala/collection/mutable/ResizableArray.scala index d57e6477b3..c7d10573c9 100644 --- a/src/library/scala/collection/mutable/ResizableArray.scala +++ b/src/library/scala/collection/mutable/ResizableArray.scala @@ -6,8 +6,6 @@ ** |/ ** \* */ - - package scala.collection package mutable @@ -62,10 +60,12 @@ trait ResizableArray[A] extends IndexedSeq[A] } } - /** Fills the given array <code>xs</code> with at most `len` elements of - * this traversable starting at position `start`. - * Copying will stop once either the end of the current traversable is reached or - * `len` elements have been copied or the end of the array is reached. + /** Fills the given array `xs` with at most `len` elements of this + * traversable starting at position `start`. + * + * Copying will stop once either the end of the current traversable is + * reached or `len` elements have been copied or the end of the array + * is reached. * * @param xs the array to fill. * @param start starting index. @@ -78,7 +78,7 @@ trait ResizableArray[A] extends IndexedSeq[A] //########################################################################## - /** remove elements of this array at indices after <code>sz</code> + /** Remove elements of this array at indices after `sz`. */ def reduceToSize(sz: Int) { require(sz <= size0) @@ -88,7 +88,7 @@ trait ResizableArray[A] extends IndexedSeq[A] } } - /** ensure that the internal array has at n cells */ + /** Ensure that the internal array has at `n` cells. */ protected def ensureSize(n: Int) { if (n > array.length) { var newsize = array.length * 2 @@ -117,6 +117,8 @@ trait ResizableArray[A] extends IndexedSeq[A] } object ResizableArray extends SeqFactory[ResizableArray] { - implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, ResizableArray[A]] = ReusableCBF.asInstanceOf[GenericCanBuildFrom[A]] + implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, ResizableArray[A]] = + ReusableCBF.asInstanceOf[GenericCanBuildFrom[A]] + def newBuilder[A]: Builder[A, ResizableArray[A]] = new ArrayBuffer[A] } diff --git a/src/library/scala/collection/mutable/SetProxy.scala b/src/library/scala/collection/mutable/SetProxy.scala index 9168c7476b..6ebe1e581b 100644 --- a/src/library/scala/collection/mutable/SetProxy.scala +++ b/src/library/scala/collection/mutable/SetProxy.scala @@ -6,12 +6,10 @@ ** |/ ** \* */ - package scala.collection package mutable -/** This is a simple wrapper class for <a href="Set.html" - * target="contentFrame"><code>scala.collection.mutable.Set</code></a>. +/** This is a simple wrapper class for [[scala.collection.mutable.Set]]. * It is most useful for assembling customized set abstractions * dynamically using object composition and forwarding. * diff --git a/src/library/scala/collection/mutable/Stack.scala b/src/library/scala/collection/mutable/Stack.scala index 63503d77de..aa79d3df7e 100644 --- a/src/library/scala/collection/mutable/Stack.scala +++ b/src/library/scala/collection/mutable/Stack.scala @@ -75,7 +75,7 @@ extends Seq[A] /** The number of elements in the stack */ override def length = elems.length - /** Retrieve n'th element from stack, where top of stack has index 0. + /** Retrieve `n`-th element from stack, where top of stack has index `0`. * * This is a linear time operation. * @@ -85,8 +85,7 @@ extends Seq[A] */ override def apply(index: Int) = elems(index) - /** Replace element at index <code>n</code> with the new element - * <code>newelem</code>. + /** Replace element at index `n` with the new element `newelem`. * * This is a linear time operation. * @@ -114,9 +113,8 @@ extends Seq[A] def push(elem1: A, elem2: A, elems: A*): this.type = this.push(elem1).push(elem2).pushAll(elems) - /** Push all elements in the given traversable object onto - * the stack. The last element in the traversable object - * will be on top of the new stack. + /** Push all elements in the given traversable object onto the stack. The + * last element in the traversable object will be on top of the new stack. * * @param xs the traversable object. * @return the stack with the new elements on top. @@ -157,8 +155,8 @@ extends Seq[A] /** Returns an iterator over all elements on the stack. This iterator * is stable with respect to state changes in the stack object; i.e. * such changes will not be reflected in the iterator. The iterator - * issues elements in the reversed order they were inserted into the stack - * (LIFO order). + * issues elements in the reversed order they were inserted into the + * stack (LIFO order). * * @return an iterator over all stack elements. */ @@ -181,4 +179,3 @@ extends Seq[A] */ override def clone(): Stack[A] = new Stack[A](elems) } - diff --git a/src/library/scala/collection/mutable/StringBuilder.scala b/src/library/scala/collection/mutable/StringBuilder.scala index d6d0951594..c1558f522f 100644 --- a/src/library/scala/collection/mutable/StringBuilder.scala +++ b/src/library/scala/collection/mutable/StringBuilder.scala @@ -14,8 +14,8 @@ import annotation.migration import immutable.StringLike /** A builder for mutable sequence of characters. This class provides an API - * mostly compatible with java.lang.StringBuilder, except where there are conflicts - * with the Scala collections API (such as the `reverse` method.) + * mostly compatible with `java.lang.StringBuilder`, except where there are + * conflicts with the Scala collections API (such as the `reverse` method.) * * @author Stephane Micheloud * @author Martin Odersky @@ -36,8 +36,8 @@ final class StringBuilder(private val underlying: JavaStringBuilder) /** Creates a string builder buffer as builder for this class */ override protected[this] def newBuilder = new GrowingBuilder(new StringBuilder) - /** Constructs a string builder initialized with String initValue - * and with additional Char capacity initCapacity. + /** Constructs a string builder initialized with string value `initValue` + * and with additional character capacity `initCapacity`. */ def this(initCapacity: Int, initValue: String) = this(new JavaStringBuilder(initValue.length + initCapacity) append initValue) @@ -48,7 +48,7 @@ final class StringBuilder(private val underlying: JavaStringBuilder) def this() = this(16, "") /** Constructs a string builder with no characters in it and an - * initial capacity specified by the capacity argument. + * initial capacity specified by the `capacity` argument. * * @param capacity the initial capacity. * @throws NegativeArraySizeException if capacity < 0. @@ -96,11 +96,11 @@ final class StringBuilder(private val underlying: JavaStringBuilder) /** Ensure that the capacity is at least the given argument. * If the argument is greater than the current capacity, new * storage will be allocated with size equal to the given - * argument or to (2 * capacity + 2), whichever is larger. + * argument or to `(2 * capacity + 2)`, whichever is larger. * * @param newCapacity the minimum desired capacity. */ - def ensureCapacity(newCapacity: Int): Unit = underlying ensureCapacity newCapacity + def ensureCapacity(newCapacity: Int) { underlying ensureCapacity newCapacity } /** Returns the Char at the specified index, counting from 0 as in Arrays. * @@ -165,7 +165,8 @@ final class StringBuilder(private val underlying: JavaStringBuilder) /** For implementing CharSequence. */ - def subSequence(start: Int, end: Int): java.lang.CharSequence = substring(start, end) + def subSequence(start: Int, end: Int): java.lang.CharSequence = + substring(start, end) /** Appends the given Char to the end of the sequence. */ @@ -177,6 +178,7 @@ final class StringBuilder(private val underlying: JavaStringBuilder) underlying append s this } + def appendAll(xs: String): StringBuilder = { underlying append xs this @@ -187,9 +189,9 @@ final class StringBuilder(private val underlying: JavaStringBuilder) def +(x: Char): this.type = { +=(x); this } /** Appends the string representation of the given argument, - * which is converted to a String with String.valueOf. + * which is converted to a String with `String.valueOf`. * - * @param x an <code>Any</code> object. + * @param x an `Any` object. * @return this StringBuilder. */ def append(x: Any): StringBuilder = { diff --git a/src/library/scala/collection/mutable/Subscriber.scala b/src/library/scala/collection/mutable/Subscriber.scala index 29474b686c..c9ae87d558 100644 --- a/src/library/scala/collection/mutable/Subscriber.scala +++ b/src/library/scala/collection/mutable/Subscriber.scala @@ -6,16 +6,12 @@ ** |/ ** \* */ - - package scala.collection package mutable - -/** <code>Subscriber[A, B]</code> objects may subscribe to events of - * type <code>A</code> published by an object of type <code>B</code>. - * <code>B</code> is typically a subtype of <a href="Publisher.html" - * target="contentFrame"><code>Publisher</code></a>. +/** `Subscriber[A, B]` objects may subscribe to events of type `A` + * published by an object of type `B`. `B` is typically a subtype of + * [[scala.collection.immutable.Publisher]]. * * @author Matthias Zenger * @author Martin Odersky diff --git a/src/library/scala/collection/script/Location.scala b/src/library/scala/collection/script/Location.scala index fea7e63788..279cb6183c 100644 --- a/src/library/scala/collection/script/Location.scala +++ b/src/library/scala/collection/script/Location.scala @@ -6,14 +6,11 @@ ** |/ ** \* */ - - package scala.collection package script - -/** Class <code>Location</code> describes locations in messages implemented by - * class <a href="Message.html" target="contentFrame"><code>Message</code></a>. +/** Class `Location` describes locations in messages implemented by + * class [[scala.collection.script.Message]]. * * @author Matthias Zenger * @version 1.0, 10/05/2004 diff --git a/src/library/scala/collection/script/Scriptable.scala b/src/library/scala/collection/script/Scriptable.scala index 904088efd7..2d9a2949d5 100644 --- a/src/library/scala/collection/script/Scriptable.scala +++ b/src/library/scala/collection/script/Scriptable.scala @@ -6,14 +6,11 @@ ** |/ ** \* */ - - package scala.collection package script - -/** Classes that mix in the <code>Scriptable</code> class allow - * messages to be sent to objects of that class. +/** Classes that mix in the `Scriptable` class allow messages to be sent to + * objects of that class. * * @author Matthias Zenger * @version 1.0, 09/05/2004 diff --git a/src/library/scala/concurrent/DelayedLazyVal.scala b/src/library/scala/concurrent/DelayedLazyVal.scala index 2a143aca72..e308c3b5a6 100644 --- a/src/library/scala/concurrent/DelayedLazyVal.scala +++ b/src/library/scala/concurrent/DelayedLazyVal.scala @@ -6,18 +6,17 @@ ** |/ ** \* */ - package scala.concurrent import ops.future -/** A <code>DelayedLazyVal</code> is a wrapper for lengthy - * computations which have a valid partially computed result. - * The first argument is a function for obtaining the result - * at any given point in time, and the second is the lengthy - * computation. Once the computation is complete, the apply() - * method will stop recalculating it and return a fixed value - * from that point forward. +/** A `DelayedLazyVal` is a wrapper for lengthy computations which have a + * valid partially computed result. + * + * The first argument is a function for obtaining the result at any given + * point in time, and the second is the lengthy computation. Once the + * computation is complete, the `apply` method will stop recalculating it + * and return a fixed value from that point forward. * * @param f the function to obtain the current value at any point in time * @param body the computation to run to completion in another thread diff --git a/src/library/scala/concurrent/JavaConversions.scala b/src/library/scala/concurrent/JavaConversions.scala index 2fa213ee06..db3c490882 100644 --- a/src/library/scala/concurrent/JavaConversions.scala +++ b/src/library/scala/concurrent/JavaConversions.scala @@ -6,13 +6,12 @@ ** |/ ** \* */ - - package scala.concurrent import java.util.concurrent.{ExecutorService, Executor} -/** The <code>JavaConversions</code> object... +/** The `JavaConversions` object provides implicit converstions supporting + * interoperability between Scala and Java concurrency classes. * * @author Philipp Haller */ diff --git a/src/library/scala/concurrent/ManagedBlocker.scala b/src/library/scala/concurrent/ManagedBlocker.scala index a0a58aabc2..9c6f4d51d6 100644 --- a/src/library/scala/concurrent/ManagedBlocker.scala +++ b/src/library/scala/concurrent/ManagedBlocker.scala @@ -6,11 +6,9 @@ ** |/ ** \* */ - - package scala.concurrent -/** The <code>ManagedBlocker</code> trait... +/** The `ManagedBlocker` trait... * * @author Philipp Haller */ @@ -19,15 +17,16 @@ trait ManagedBlocker { /** * Possibly blocks the current thread, for example waiting for * a lock or condition. + * * @return true if no additional blocking is necessary (i.e., - * if isReleasable would return true). + * if `isReleasable` would return `true`). * @throws InterruptedException if interrupted while waiting - * (the method is not required to do so, but is allowed to). + * (the method is not required to do so, but is allowed to). */ def block(): Boolean /** - * Returns true if blocking is unnecessary. + * Returns `true` if blocking is unnecessary. */ def isReleasable: Boolean diff --git a/src/library/scala/concurrent/ops.scala b/src/library/scala/concurrent/ops.scala index db6e81cc26..d0ea51db51 100644 --- a/src/library/scala/concurrent/ops.scala +++ b/src/library/scala/concurrent/ops.scala @@ -6,14 +6,12 @@ ** |/ ** \* */ - - package scala.concurrent import java.lang.Thread import scala.util.control.Exception.allCatch -/** The object <code>ops</code> ... +/** The object `ops` ... * * @author Martin Odersky, Stepan Koltsov, Philipp Haller */ @@ -39,8 +37,8 @@ object ops runner execute runner.functionAsTask(() => p) } - /** Evaluates an expression asynchronously, and returns a closure for retrieving - * the result. + /** Evaluates an expression asynchronously, and returns a closure for + * retrieving the result. * * @param p the expression to evaluate * @return a closure which returns the result once it has been computed diff --git a/src/library/scala/concurrent/pilib.scala b/src/library/scala/concurrent/pilib.scala index 7a3758b9c6..c2968b990d 100644 --- a/src/library/scala/concurrent/pilib.scala +++ b/src/library/scala/concurrent/pilib.scala @@ -10,19 +10,17 @@ package scala.concurrent -/** <p> - * Library for using Pi-calculus concurrent primitives in - * <a href="http://scala-lang.org/" target="_top">Scala</a>. As an - * example, the definition of a two-place buffer using the <code>pilib</code> - * library looks like: - * </p><pre> - * <b>def</b> Buffer[a](put: Chan[a], get: Chan[a]) { - * <b>def</b> B0 { choice ( put * { x => B1(x) } ) } - * <b>def</b> B1(x: a) { choice ( get(x) * B0, put * { y => B2(x, y) } ) } - * <b>def</b> B2(x: a, y: a) { choice ( get(x) * B1(y) ) } +/** Library for using Pi-calculus concurrent primitives in + * [[http://scala-lang.org/#_top Scala]]. As an example, the definition of + * a two-place buffer using the `pilib` library looks like: + * {{{ + * def Buffer[a](put: Chan[a], get: Chan[a]) { + * def B0 { choice ( put * { x => B1(x) } ) } + * def B1(x: a) { choice ( get(x) * B0, put * { y => B2(x, y) } ) } + * def B2(x: a, y: a) { choice ( get(x) * B1(y) ) } * B0 * } - * </pre> + * }}} * * @see <a href="http://scala-lang.org/docu/papers.html" target="_top"> * PiLib: A Hosted Language for Pi-Calculus Style Concurrency</a> diff --git a/src/library/scala/deprecatedName.scala b/src/library/scala/deprecatedName.scala index e91ce6e8f4..090ec133fe 100644 --- a/src/library/scala/deprecatedName.scala +++ b/src/library/scala/deprecatedName.scala @@ -1,3 +1,11 @@ +/* __ *\ +** ________ ___ / / ___ Scala API ** +** / __/ __// _ | / / / _ | (c) 2010-2011, LAMP/EPFL ** +** __\ \/ /__/ __ |/ /__/ __ | http://scala-lang.org/ ** +** /____/\___/_/ |_/____/_/ | | ** +** |/ ** +\* */ + package scala import annotation.target._ @@ -7,6 +15,17 @@ import annotation.target._ * applied as deprecated. Using that name in a named argument generates * a deprecation warning. * + * For instance, evaluating the code below in the Scala interpreter + * {{{ + * def inc(x: Int, @deprecatedName('y) n: Int): Int = x + n + * inc(1, y = 2) + * }}} + * will produce the following output: + * {{{ + * warning: there were 1 deprecation warnings; re-run with -deprecation for details + * res0: Int = 3 + * }}} + * * @since 2.8.1 */ @param diff --git a/src/library/scala/math/Equiv.scala b/src/library/scala/math/Equiv.scala index 37654bd3fd..ac3a3017f2 100644 --- a/src/library/scala/math/Equiv.scala +++ b/src/library/scala/math/Equiv.scala @@ -15,14 +15,14 @@ import java.util.Comparator * equivalence and a representation of equivalence on some type. This * trait is for representing the latter. * - * An <a href="http://en.wikipedia.org/wiki/Equivalence_relation">equivalence - * relation</a> is a binary relation on a type. This relation is exposed as + * An [[http://en.wikipedia.org/wiki/Equivalence_relation equivalence relation]] + * is a binary relation on a type. This relation is exposed as * the `equiv` method of the `Equiv` trait. The relation must be: * * 1. reflexive: `equiv(x, x) == true` for any x of type `T`. - * 2. symmetric: `equiv(x, y) == equiv(y, x)` for any x and y of type T. - * 3. transitive: if `equiv(x, y) == true` and `equiv(y, z) == true`, then - * `equiv(x, z) == true` for any x, y, and z of type T. + * 1. symmetric: `equiv(x, y) == equiv(y, x)` for any `x` and `y` of type `T`. + * 1. transitive: if `equiv(x, y) == true` and `equiv(y, z) == true`, then + * `equiv(x, z) == true` for any `x`, `y`, and `z` of type `T`. * * @author Geoffrey Washburn, Paul Phillips * @version 1.0, 2008-04-03 @@ -30,7 +30,7 @@ import java.util.Comparator */ trait Equiv[T] { - /** Returns true iff x is equivalent to y. + /** Returns `true` iff `x` is equivalent to `y`. */ def equiv(x: T, y: T): Boolean } diff --git a/src/library/scala/math/Ordered.scala b/src/library/scala/math/Ordered.scala index 64cbd5e8f2..9645b9b840 100644 --- a/src/library/scala/math/Ordered.scala +++ b/src/library/scala/math/Ordered.scala @@ -6,39 +6,37 @@ ** |/ ** \* */ - - package scala.math /** A trait for totally ordered data. * - * Note that since version 2006-07-24 this trait is no longer covariant in a. + * Note that since version 2006-07-24 this trait is no longer covariant + * in `A`. * - * It is important that the equals method for an instance of - * Ordered[A] be consistent with the compare method. However, - * due to limitations inherent in the type erasure semantics, - * there is no reasonable way to provide a default implementation - * of equality for instances of Ordered[A]. Therefore, if you need - * to be able to use equality on an instance of Ordered[A] you must - * provide it yourself either when inheriting or instantiating. + * It is important that the `equals` method for an instance of `Ordered[A]` + * be consistent with the compare method. However, due to limitations + * inherent in the type erasure semantics, there is no reasonable way to + * provide a default implementation of equality for instances of `Ordered[A]`. + * Therefore, if you need to be able to use equality on an instance of + * `Ordered[A]` you must provide it yourself either when inheriting or + * instantiating. * - * It is important that the hashCode method for an instance of - * Ordered[A] be consistent with the compare method. However, - * it is not possible to provide a sensible default implementation. - * Therefore, if you need to be able compute the hash of an - * instance of Ordered[A] you must provide it yourself either when - * inheriting or instantiating. + * It is important that the `hashCode` method for an instance of `Ordered[A]` + * be consistent with the `compare` method. However, it is not possible to + * provide a sensible default implementation. Therefore, if you need to be + * able compute the hash of an instance of `Ordered[A]` you must provide it + * yourself either when inheriting or instantiating. * * @author Martin Odersky * @version 1.1, 2006-07-24 */ trait Ordered[A] extends java.lang.Comparable[A] { - /** Result of comparing <code>this</code> with operand <code>that</code>. - * returns <code>x</code> where - * <code>x < 0</code> iff <code>this < that</code> - * <code>x == 0</code> iff <code>this == that</code> - * <code>x > 0</code> iff <code>this > that</code> + /** Result of comparing `this` with operand `that`. + * returns `x` where + * `x < 0` iff `this < that` + * `x == 0` iff `this == that` + * `x > 0` iff `this > that` */ def compare(that: A): Int @@ -50,7 +48,7 @@ trait Ordered[A] extends java.lang.Comparable[A] { } object Ordered { - /** Lens from Ordering[T] to Ordered[T] */ + /** Lens from `Ordering[T]` to `Ordered[T]` */ implicit def orderingToOrdered[T](x: T)(implicit ord: Ordering[T]): Ordered[T] = new Ordered[T] { def compare(that: T): Int = ord.compare(x, that) } } diff --git a/src/library/scala/math/Ordering.scala b/src/library/scala/math/Ordering.scala index 10e42a6de4..8582a11f2d 100644 --- a/src/library/scala/math/Ordering.scala +++ b/src/library/scala/math/Ordering.scala @@ -11,37 +11,34 @@ package scala.math import java.util.Comparator /** A trait for representing total orderings. It is important to - * distinguish between a type that has a total order and a representation - * of total ordering on some type. This trait is for the latter. + * distinguish between a type that has a total order and a representation + * of total ordering on some type. This trait is for the latter. * - * A [[http://en.wikipedia.org/wiki/Total_order|total ordering]] - * is a binary relation on a type `T` that is also an equivalence relation - * and partial ordering on values of type `T`. This relation is exposed as - * the `compare` method of the `Ordering` trait. + * A [[http://en.wikipedia.org/wiki/Total_order total ordering]] + * is a binary relation on a type `T` that is also an equivalence relation + * and partial ordering on values of type `T`. This relation is exposed as + * the `compare` method of the `Ordering` trait. * - * This relation must be: - {{{ - reflexive: x == x - antisymmetric: if x <= y && y <= x, then x == y - transitive: if x <= y && y <= z, then x <= z - }}} + * This relation must be: * - * @author Geoffrey Washburn - * @version 0.9.5, 2008-04-15 - * @since 2.7 + * - reflexive: `x == x` + * - antisymmetric: if `x <= y && y <= x`, then `x == y` + * - transitive: if `x <= y && y <= z`, then `x <= z` + * + * @author Geoffrey Washburn + * @version 0.9.5, 2008-04-15 + * @since 2.7 */ @annotation.implicitNotFound(msg = "No implicit Ordering defined for ${T}.") trait Ordering[T] extends Comparator[T] with PartialOrdering[T] with Serializable { outer => - /** An Ordering is defined at all x and y. */ + /** An `Ordering` is defined at all `x` and `y`. */ def tryCompare(x: T, y: T) = Some(compare(x, y)) - /** Returns a negative integer iff `x` comes before - * `y` in the ordering, returns 0 iff `x` - * is the same in the ordering as `y`, and returns a - * positive number iff `x` comes after - * `y` in the ordering. + /** Returns a negative integer iff `x` comes before `y` in the ordering, + * returns 0 iff `x` is the same in the ordering as `y`, and returns a + * positive number iff `x` comes after `y` in the ordering. */ def compare(x: T, y: T): Int @@ -76,7 +73,7 @@ trait Ordering[T] extends Comparator[T] with PartialOrdering[T] with Serializabl def compare(x: T, y: T) = outer.compare(y, x) } - /** Given a function U => T, creates Ordering[U]. */ + /** Given a function `U => T`, creates `Ordering[U]`. */ def on[U](f: U => T): Ordering[U] = new Ordering[U] { def compare(x: U, y: U) = outer.compare(f(x), f(y)) } @@ -96,9 +93,9 @@ trait Ordering[T] extends Comparator[T] with PartialOrdering[T] with Serializabl trait LowPriorityOrderingImplicits { /** This would conflict with all the nice implicit Orderings * available, but thanks to the magic of prioritized implicits - * via subclassing we can make Ordered[A] => Ordering[A] only - * turn up if nothing else works. Since Ordered[A] extends - * Comparable[A] anyway, we can throw in some java interop too. + * via subclassing we can make `Ordered[A] => Ordering[A]` only + * turn up if nothing else works. Since `Ordered[A]` extends + * `Comparable[A]` anyway, we can throw in some Java interop too. */ implicit def ordered[A <% Comparable[A]]: Ordering[A] = new Ordering[A] { def compare(x: A, y: A): Int = x compareTo y @@ -113,7 +110,7 @@ object Ordering extends LowPriorityOrderingImplicits { trait ExtraImplicits { /** Not in the standard scope due to the potential for divergence: - * For instance implicitly[Ordering[Any]] diverges in its presence. + * For instance `implicitly[Ordering[Any]]` diverges in its presence. */ implicit def seqDerivedOrdering[CC[X] <: collection.Seq[X], T](implicit ord: Ordering[T]): Ordering[CC[T]] = new Ordering[CC[T]] { @@ -130,9 +127,9 @@ object Ordering extends LowPriorityOrderingImplicits { } } - /** This implicit creates a conversion from any value for which an implicit Ordering - * exists to the class which creates infix operations. With it imported, you can write - * methods as follows: + /** This implicit creates a conversion from any value for which an + * implicit `Ordering` exists to the class which creates infix operations. + * With it imported, you can write methods as follows: * {{{ * def lessThen[T: Ordering](x: T, y: T) = x < y * }}} diff --git a/src/library/scala/reflect/BeanInfo.scala b/src/library/scala/reflect/BeanInfo.scala index ba8cc8b9e2..0522377f8e 100644 --- a/src/library/scala/reflect/BeanInfo.scala +++ b/src/library/scala/reflect/BeanInfo.scala @@ -6,15 +6,14 @@ ** |/ ** \* */ - package scala.reflect -/** <p> - * This annotation indicates that a JavaBean-compliant BeanInfo - * class should be generated for this annotated Scala class. - * A val becomes a read-only property. A var becomes a read-write - * property. A def becomes a method. - * </p> +/** This annotation indicates that a JavaBean-compliant `BeanInfo` class + * should be generated for this annotated Scala class. + * + * - A `'''val'''` becomes a read-only property. + * - A `'''var'''` becomes a read-write property. + * - A `'''def'''` becomes a method. * * @author Ross Judson (rjudson@managedobjects.com) */ diff --git a/src/library/scala/reflect/BooleanBeanProperty.scala b/src/library/scala/reflect/BooleanBeanProperty.scala index fa0bf27802..97c05ffb7c 100644 --- a/src/library/scala/reflect/BooleanBeanProperty.scala +++ b/src/library/scala/reflect/BooleanBeanProperty.scala @@ -6,18 +6,13 @@ ** |/ ** \* */ - - package scala.reflect import annotation.target._ -/** <p> - * This annotation has the same functionality as - * <code>scala.reflect.BeanProperty</code>, but the generated - * Bean getter will be named <code>isFieldName</code> instead - * of <code>getFieldName</code>. - * </p> +/** This annotation has the same functionality as + * `scala.reflect.BeanProperty`, but the generated Bean getter will be + * named `isFieldName` instead of `getFieldName`. */ @field class BooleanBeanProperty extends annotation.StaticAnnotation diff --git a/src/library/scala/reflect/ClassManifest.scala b/src/library/scala/reflect/ClassManifest.scala index 2189f6df82..3dff72659a 100644 --- a/src/library/scala/reflect/ClassManifest.scala +++ b/src/library/scala/reflect/ClassManifest.scala @@ -11,21 +11,20 @@ package scala.reflect import scala.collection.mutable.{ WrappedArray, ArrayBuilder } import java.lang.{ Class => JClass } -/** A ClassManifest[T] is an opaque descriptor for type T. +/** A `ClassManifest[T]` is an opaque descriptor for type `T`. * It is used by the compiler to preserve information necessary - * for instantiating Arrays in those cases where the element type + * for instantiating `Arrays` in those cases where the element type * is unknown at compile time. * - * The type-relation operators make an effort to present a - * more accurate picture than can be realized with erased types, - * but they should not be relied upon to give correct answers. - * In particular they are likely to be wrong when variance is - * involved or when a subtype has a different number of type - * arguments than a supertype. + * The type-relation operators make an effort to present a more accurate + * picture than can be realized with erased types, but they should not be + * relied upon to give correct answers. In particular they are likely to + * be wrong when variance is involved or when a subtype has a different + * number of type arguments than a supertype. */ trait ClassManifest[T] extends OptManifest[T] with Equals with Serializable { - /** A class representing the type U to which T would be erased. Note - * that there is no subtyping relationship between T and U. */ + /** A class representing the type `U` to which `T` would be erased. Note + * that there is no subtyping relationship between `T` and `U`. */ def erasure: JClass[_] private def subtype(sub: JClass[_], sup: JClass[_]): Boolean = { @@ -89,8 +88,8 @@ trait ClassManifest[T] extends OptManifest[T] with Equals with Serializable { that <:< this def canEqual(other: Any) = other match { - case _: ClassManifest[_] => true - case _ => false + case _: ClassManifest[_] => true + case _ => false } /** Tests whether the type represented by this manifest is equal to @@ -144,9 +143,8 @@ trait ClassManifest[T] extends OptManifest[T] with Equals with Serializable { else "" } -/** The object ClassManifest defines factory methods for manifests. - * It is intended for use by the compiler and should not be used - * in client code. +/** The object `ClassManifest` defines factory methods for manifests. + * It is intended for use by the compiler and should not be used in client code. */ object ClassManifest { val Byte = Manifest.Byte diff --git a/src/library/scala/reflect/Manifest.scala b/src/library/scala/reflect/Manifest.scala index a75f90ebf0..10512e134a 100644 --- a/src/library/scala/reflect/Manifest.scala +++ b/src/library/scala/reflect/Manifest.scala @@ -10,12 +10,12 @@ package scala.reflect import scala.collection.mutable.{ ArrayBuilder, WrappedArray } -/** A Manifest[T] is an opaque descriptor for type T. Its - * supported use is to give access to the erasure of the type - * as a Class instance, as is necessary for the creation of native - * Arrays if the class is not known at compile time. +/** A `Manifest[T]` is an opaque descriptor for type T. Its supported use + * is to give access to the erasure of the type as a `Class` instance, as + * is necessary for the creation of native `Arrays` if the class is not + * known at compile time. * - * The type-relation operators <:< and =:= should be considered + * The type-relation operators `<:<` and `=:=` should be considered * approximations only, as there are numerous aspects of type conformance * which are not yet adequately represented in manifests. * @@ -70,7 +70,7 @@ trait AnyValManifest[T] extends Manifest[T] with Equals { override def hashCode = System.identityHashCode(this) } -/** The object Manifest defines factory methods for manifests. +/** The object `Manifest` defines factory methods for manifests. * It is intended for use by the compiler and should not be used * in client code. */ diff --git a/src/library/scala/reflect/OptManifest.scala b/src/library/scala/reflect/OptManifest.scala index 8e64da32fb..2a955deb2c 100644 --- a/src/library/scala/reflect/OptManifest.scala +++ b/src/library/scala/reflect/OptManifest.scala @@ -6,15 +6,11 @@ ** |/ ** \* */ - - package scala.reflect -/** <p> - * A <code>OptManifest[T]</code> is an optional <a href="Manifest.html" - * target="ContentFrame"><code>Manifest</code></a>.<br/> - * It is either a <code>Manifest</code> or the value <code>NoManifest</code>. - * </p> +/** A `OptManifest[T]` is an optional [[scala.reflect.Manifest]]. + * + * It is either a `Manifest` or the value `NoManifest`. * * @author Martin Odersky */ diff --git a/src/library/scala/reflect/generic/HasFlags.scala b/src/library/scala/reflect/generic/HasFlags.scala index 3d9d121adf..7f869bfdc2 100644 --- a/src/library/scala/reflect/generic/HasFlags.scala +++ b/src/library/scala/reflect/generic/HasFlags.scala @@ -1,3 +1,8 @@ +/* NSC -- new Scala compiler + * Copyright 2005-2011 LAMP/EPFL + * @author Martin Odersky + */ + package scala.reflect package generic @@ -73,15 +78,16 @@ package generic import Flags._ -/** Common code utilized by Modifiers (which carry the flags associated - * with Trees) and Symbol. +/** Common code utilized by `Modifiers` (which carry the flags associated + * with `Trees`) and `Symbol`. */ -@deprecated("scala.reflect.generic will be removed", "2.9.1") trait HasFlags { +@deprecated("scala.reflect.generic will be removed", "2.9.1") +trait HasFlags { type FlagsType type AccessBoundaryType type AnnotationType - /** Though both Symbol and Modifiers widen this method to public, it's + /** Though both `Symbol` and `Modifiers` widen this method to public, it's * defined protected here to give us the option in the future to route * flag methods through accessors and disallow raw flag manipulation. * And after that, perhaps, on some magical day: a typesafe enumeration. @@ -93,8 +99,8 @@ import Flags._ */ def hasFlagsToString(mask: FlagsType): String - /** Access level encoding: there are three scala flags (PRIVATE, PROTECTED, - * and LOCAL) which combine with value privateWithin (the "foo" in private[foo]) + /** Access level encoding: there are three scala flags (`PRIVATE`, `PROTECTED`, + * and `LOCAL`) which combine with value privateWithin (the `foo` in `private[foo]`) * to define from where an entity can be accessed. The meanings are as follows: * * PRIVATE access restricted to class only. @@ -102,18 +108,19 @@ import Flags._ * LOCAL can only be set in conjunction with PRIVATE or PROTECTED. * Further restricts access to the same object instance. * - * In addition, privateWithin can be used to set a visibility barrier. + * In addition, `privateWithin` can be used to set a visibility barrier. * When set, everything contained in the named enclosing package or class - * has access. It is incompatible with PRIVATE or LOCAL, but is additive - * with PROTECTED (i.e. if either the flags or privateWithin allow access, + * has access. It is incompatible with `PRIVATE` or `LOCAL`, but is additive + * with `PROTECTED` (i.e. if either the flags or privateWithin allow access, * then it is allowed.) * - * The java access levels translate as follows: - * + * The Java access levels translate as follows: + * {{{ * java private: hasFlag(PRIVATE) && !hasAccessBoundary * java package: !hasFlag(PRIVATE | PROTECTED) && (privateWithin == enclosing package) * java protected: hasFlag(PROTECTED) && (privateWithin == enclosing package) * java public: !hasFlag(PRIVATE | PROTECTED) && !hasAccessBoundary + * }}} */ def privateWithin: AccessBoundaryType @@ -158,7 +165,7 @@ import Flags._ def isSuperAccessor = hasFlag(SUPERACCESSOR) def isLifted = hasFlag(LIFTED) - // Formerly the Modifiers impl did not include the access boundary check, + // Formerly the `Modifiers` impl did not include the access boundary check, // which must have been a bug. def isPublic = hasNoFlags(PRIVATE | PROTECTED) && !hasAccessBoundary @@ -228,4 +235,3 @@ import Flags._ // def isAccessor = hasFlag(ACCESSOR ) // final def isGetterOrSetter = hasAccessorFlag } - diff --git a/src/library/scala/reflect/generic/Trees.scala b/src/library/scala/reflect/generic/Trees.scala index dace1628da..30dc68981f 100755 --- a/src/library/scala/reflect/generic/Trees.scala +++ b/src/library/scala/reflect/generic/Trees.scala @@ -225,22 +225,17 @@ import Flags._ case class TypeDef(mods: Modifiers, name: TypeName, tparams: List[TypeDef], rhs: Tree) extends MemberDef - /** <p> - * Labelled expression - the symbols in the array (must be Idents!) - * are those the label takes as argument - * </p> - * <p> - * The symbol that is given to the labeldef should have a MethodType - * (as if it were a nested function) - * </p> - * <p> - * Jumps are apply nodes attributed with label symbol, the arguments - * will get assigned to the idents. - * </p> - * <p> - * Note: on 2005-06-09 Martin, Iuli, Burak agreed to have forward - * jumps within a Block. - * </p> + /** Labelled expression - the symbols in the array (must be Idents!) + * are those the label takes as argument. + * + * The symbol that is given to the `labeldef` should have a `MethodType` + * (as if it were a nested function). + * + * Jumps are apply nodes attributed with label symbol, the arguments + * will get assigned to the idents. + * + * '''Note''': on 2005-06-09 Martin, Iuli, Burak agreed to have forward + * jumps within a `Block`. */ case class LabelDef(name: TermName, params: List[Ident], rhs: Tree) extends DefTree with TermTree @@ -337,20 +332,17 @@ import Flags._ case class If(cond: Tree, thenp: Tree, elsep: Tree) extends TermTree - /** <p> - * Pattern matching expression (before explicitouter) - * Switch statements (after explicitouter) - * </p> - * <p> - * After explicitouter, cases will satisfy the following constraints: - * </p> - * <ul> - * <li>all guards are EmptyTree,</li> - * <li>all patterns will be either <code>Literal(Constant(x:Int))</code> - * or <code>Alternative(lit|...|lit)</code></li> - * <li>except for an "otherwise" branch, which has pattern - * <code>Ident(nme.WILDCARD)</code></li> - * </ul> + /** + * - Pattern matching expression (before explicitouter) + * - Switch statements (after explicitouter) + * + * After explicitouter, cases will satisfy the following constraints: + * + * - all guards are EmptyTree, + * - all patterns will be either `Literal(Constant(x:Int))` + * or `Alternative(lit|...|lit)` + * - except for an "otherwise" branch, which has pattern + * `Ident(nme.WILDCARD)` */ case class Match(selector: Tree, cases: List[CaseDef]) extends TermTree @@ -400,10 +392,10 @@ import Flags._ } /** Dynamic value application. - * In a dynamic application q.f(as) - * - q is stored in qual - * - as is stored in args - * - f is stored as the node's symbol field. + * In a dynamic application `q.f(as)` + * - `q` is stored in parameter `qual` + * - `as` is stored in parameter `args` + * - `f` is stored as the node's symbol field. */ case class ApplyDynamic(qual: Tree, args: List[Tree]) extends TermTree with SymTree diff --git a/src/library/scala/remote.scala b/src/library/scala/remote.scala index 01805101be..bf6b440031 100644 --- a/src/library/scala/remote.scala +++ b/src/library/scala/remote.scala @@ -6,11 +6,22 @@ ** |/ ** \* */ - - package scala /** * An annotation that designates the class to which it is applied as remotable. + * + * For instance, the Scala code + * {{{ + * @remote trait Hello { + * def sayHello(): String + * } + * }}} + * is equivalent to the following Java code: + * {{{ + * public interface Hello extends java.rmi.Remote { + * String sayHello() throws java.rmi.RemoteException; + * } + * }}} */ class remote extends annotation.StaticAnnotation {} diff --git a/src/library/scala/sys/process/ProcessLogger.scala b/src/library/scala/sys/process/ProcessLogger.scala index 1ce77c9196..556d9ad922 100644 --- a/src/library/scala/sys/process/ProcessLogger.scala +++ b/src/library/scala/sys/process/ProcessLogger.scala @@ -12,10 +12,10 @@ package process import java.io._ /** Encapsulates the output and error streams of a running process. - * Many of the methods of ProcessBuilder accept a ProcessLogger as + * Many of the methods of `ProcessBuilder` accept a `ProcessLogger` as * an argument. * - * @see ProcessBuilder + * @see [[scala.sys.process.ProcessBuilder]] */ trait ProcessLogger { /** Will be called with each line read from the process output stream. @@ -26,14 +26,15 @@ trait ProcessLogger { */ def err(s: => String): Unit - /** If a process is begun with one of these ProcessBuilder methods: - * + /** If a process is begun with one of these `ProcessBuilder` methods: + * {{{ * def !(log: ProcessLogger): Int * def !<(log: ProcessLogger): Int - * + * }}} * The run will be wrapped in a call to buffer. This gives the logger * an opportunity to set up and tear down buffering. At present the - * library implementations of ProcessLogger simply execute the body unbuffered. + * library implementations of `ProcessLogger` simply execute the body + * unbuffered. */ def buffer[T](f: => T): T } @@ -58,9 +59,10 @@ class FileProcessLogger(file: File) extends ProcessLogger with Closeable with Fl object ProcessLogger { def apply(file: File): FileProcessLogger = new FileProcessLogger(file) def apply(fn: String => Unit): ProcessLogger = apply(fn, fn) - def apply(fout: String => Unit, ferr: String => Unit): ProcessLogger = new ProcessLogger { - def out(s: => String): Unit = fout(s) - def err(s: => String): Unit = ferr(s) - def buffer[T](f: => T): T = f - } + def apply(fout: String => Unit, ferr: String => Unit): ProcessLogger = + new ProcessLogger { + def out(s: => String): Unit = fout(s) + def err(s: => String): Unit = ferr(s) + def buffer[T](f: => T): T = f + } } diff --git a/src/library/scala/testing/Benchmark.scala b/src/library/scala/testing/Benchmark.scala index c6ab992306..a7548aa844 100644 --- a/src/library/scala/testing/Benchmark.scala +++ b/src/library/scala/testing/Benchmark.scala @@ -6,33 +6,24 @@ ** |/ ** \* */ - - package scala.testing - import compat.Platform -/** <p> - * <code>Benchmark</code> can be used to quickly turn an existing - * class into a benchmark. Here is a short example: - * </p><pre> - * <b>object</b> sort1 <b>extends</b> Sorter <b>with</b> Benchmark { - * <b>def</b> run = sort(List.range(1, 1000)) +/** `Benchmark` can be used to quickly turn an existing class into a + * benchmark. Here is a short example: + * {{{ + * object sort1 extends Sorter with Benchmark { + * def run = sort(List.range(1, 1000)) * } - * </pre> - * <p> - * The <code>run</code> method has to be defined by the user, who - * will perform the timed operation there. - * Run the benchmark as follows: - * </p> - * <pre> - * > scala sort1 5 times.log - * </pre> - * <p> - * This will run the benchmark 5 times and log the execution times in - * a file called <code>times.log</code> - * </p> + * }}} + * The `run` method has to be defined by the user, who will perform the + * timed operation there. Run the benchmark as follows: + * {{{ + * > scala sort1 5 times.log + * }}} + * This will run the benchmark 5 times and log the execution times in + * a file called `times.log`. * * @author Iulian Dragos, Burak Emir */ @@ -49,9 +40,8 @@ trait Benchmark { var multiplier = 1 - /** Run the benchmark the specified number of times - * and return a list with the execution times in milliseconds - * in reverse order of the execution + /** Run the benchmark the specified number of times and return a list with + * the execution times in milliseconds in reverse order of the execution. * * @param noTimes ... * @return ... @@ -75,8 +65,7 @@ trait Benchmark { * should not be measured. This method is run before each call to the * benchmark payload, 'run'. */ - def setUp() { - } + def setUp() {} /** Perform cleanup operations after each 'run'. For micro benchmarks, * think about using the result of 'run' in a way that prevents the JVM @@ -84,8 +73,7 @@ trait Benchmark { * write the results to a file. The execution time of this method is not * measured. */ - def tearDown() { - } + def tearDown() {} /** a string that is written at the beginning of the output line * that contains the timings. By default, this is the class name. @@ -93,11 +81,10 @@ trait Benchmark { def prefix: String = getClass().getName() /** - * The entry point. It takes two arguments (n), - * and an optional argument multiplier (mult). - * (n) is the number of consecutive runs, - * if (mult) is present, the n runs are repeated (mult) - * times. + * The entry point. It takes two arguments: + * - argument `n` is the number of consecutive runs + * - optional argument `mult` specifies that the `n` runs are repeated + * `mult` times. */ def main(args: Array[String]) { if (args.length > 0) { @@ -120,4 +107,3 @@ trait Benchmark { } } } - diff --git a/src/library/scala/testing/Show.scala b/src/library/scala/testing/Show.scala index f5670ac11a..b0d094e466 100644 --- a/src/library/scala/testing/Show.scala +++ b/src/library/scala/testing/Show.scala @@ -10,20 +10,19 @@ package scala.testing -/** Classes inheriting trait `Show` can test their member methods - * using the notattion <code>meth(arg<sub>1</sub>, ..., arg<sub>n</sub>)</code>, - * where `meth` is the name of the method and - * <code>arg<sub>1</sub>,...,arg<sub>n</sub></code> are the arguments. +/** Classes inheriting trait `Show` can test their member methods using the + * notattion `meth(arg,,1,,, ..., arg,,n,,)`, where `meth` is the name of + * the method and `arg,,1,,,...,arg,,n,,` are the arguments. * * The only difference to a normal method call is the leading quote - * character (`'`). A quoted method call like the one above will produces a - * legible diagnostic to be printed on [[scala.Console]]. + * character (`'`). A quoted method call like the one above will produces + * a legible diagnostic to be printed on [[scala.Console]]. * * It is of the form - * <pre> - * meth(arg<sub>1</sub>, ..., arg<sub>n</sub>) gives <result></pre> * - * where <code><result></code> is the result of evaluating the call. + * `meth(arg,,1,,, ..., arg,,n,,)` gives `<result>` + * + * where `<result>` is the result of evaluating the call. * */ trait Show { diff --git a/src/library/scala/throws.scala b/src/library/scala/throws.scala index 1ff8cdc3b8..4621c789ab 100644 --- a/src/library/scala/throws.scala +++ b/src/library/scala/throws.scala @@ -6,13 +6,11 @@ ** |/ ** \* */ - - package scala -/** <p> - * Annotation for specifying the exceptions thrown by a method. - * For example: +/** + * Annotation for specifying the exceptions thrown by a method. + * For example: * {{{ * class Reader(fname: String) { * private val in = new BufferedReader(new FileReader(fname)) diff --git a/src/library/scala/unchecked.scala b/src/library/scala/unchecked.scala index 74cb14e6e3..4f1f3f1957 100644 --- a/src/library/scala/unchecked.scala +++ b/src/library/scala/unchecked.scala @@ -29,11 +29,9 @@ package scala * ^ * one warning found * }}} - * The above message may be suppressed by substituting the expression - * `x` with `(x: @unchecked)`. Then the - * modified code will compile silently, but, in any case, a - * <a href="MatchError.html"><code>MatchError</code></a> - * will be raised at runtime. + * The above message may be suppressed by substituting the expression `x` + * with `(x: @unchecked)`. Then the modified code will compile silently, + * but, in any case, a [[scala.MatchError]] will be raised at runtime. * * @since 2.4 */ diff --git a/src/library/scala/util/automata/BaseBerrySethi.scala b/src/library/scala/util/automata/BaseBerrySethi.scala index 51e15f0e71..18f36f9496 100644 --- a/src/library/scala/util/automata/BaseBerrySethi.scala +++ b/src/library/scala/util/automata/BaseBerrySethi.scala @@ -6,8 +6,6 @@ ** |/ ** \* */ - - package scala.util.automata import scala.util.regexp.{ Base } @@ -15,8 +13,9 @@ import scala.collection.{ mutable, immutable } // todo: replace global variable pos with acc -/** 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''). +/** This class turns a regular expression over `A` into a + * [[scala.util.automata.NondetWordAutom]] over `A` using the celebrated + * position automata construction (also called ''Berry-Sethi'' or ''Glushkov''). */ abstract class BaseBerrySethi { val lang: Base @@ -43,7 +42,7 @@ abstract class BaseBerrySethi { val (l1, l2) = x.rs span (_.isNullable) ((l1 ++ (l2 take 1)) map compFunction).foldLeft(emptySet)(_ ++ _) case Star(t) => compFunction(t) - case _ => throw new IllegalArgumentException("unexpected pattern " + r.getClass()) + case _ => throw new IllegalArgumentException("unexpected pattern " + r.getClass) } /** Computes `first(r)` for the word regexp `r`. */ @@ -89,7 +88,7 @@ abstract class BaseBerrySethi { if (p.isNullable) fol ++ first else first } - case _ => throw new IllegalArgumentException("unexpected pattern: " + r.getClass()) + case _ => throw new IllegalArgumentException("unexpected pattern: " + r.getClass) } /** Returns the "Sethi-length" of a pattern, creating the set of position along the way. @@ -98,10 +97,10 @@ abstract class BaseBerrySethi { */ protected def traverse(r: RegExp): Unit = r match { // (is tree automaton stuff, more than Berry-Sethi) - case x: Alt => x.rs foreach traverse - case x: Sequ => x.rs foreach traverse - case x: Meta => traverse(x.r) - case Star(t) => traverse(t) - case _ => throw new IllegalArgumentException("unexp pattern " + r.getClass()) + case x: Alt => x.rs foreach traverse + case x: Sequ => x.rs foreach traverse + case x: Meta => traverse(x.r) + case Star(t) => traverse(t) + case _ => throw new IllegalArgumentException("unexp pattern " + r.getClass) } } diff --git a/src/library/scala/util/control/Breaks.scala b/src/library/scala/util/control/Breaks.scala index 80df8cc0bd..9b1abefe00 100644 --- a/src/library/scala/util/control/Breaks.scala +++ b/src/library/scala/util/control/Breaks.scala @@ -6,31 +6,28 @@ ** |/ ** \* */ - - package scala.util.control /** A class that can be instantiated for the break control abstraction. * Example usage: - * - * <pre> + * {{{ * val mybreaks = new Breaks - * import</b> mybreaks.{break, breakable} + * import mybreaks.{break, breakable} * * breakable { - * <b>for</b> (...) { - * <b>if</b> (...) break + * for (...) { + * if (...) break * } - * }</pre> - * + * } + * }}} * Calls to break from one instantiation of `Breaks` will never - * target breakable objects of some other instantion. + * target breakable objects of some other instantiation. */ class Breaks { private val breakException = new BreakControl - /** A block from which one can exit with a `break`'. */ + /** A block from which one can exit with a `break`. */ def breakable(op: => Unit) { try { op @@ -54,26 +51,25 @@ class Breaks { } } - /* Break from dynamically closest enclosing breakable block. + /** Break from dynamically closest enclosing breakable block. * - * @note This might be different than the statically closest enclosing block! + * @note This might be different than the statically closest enclosing block! */ def break() { throw breakException } } /** An object that can be used for the break control abstraction. - * Example usage:<pre> - * - * <b>import</b> Breaks.{break, breakable} + * Example usage: + * {{{ + * import Breaks.{break, breakable} * * breakable { - * <b>for</b> (...) { - * <b>if</b> (...) break + * for (...) { + * if (...) break * } - * }</pre> - * + * } + * }}} */ object Breaks extends Breaks private class BreakControl extends ControlThrowable - diff --git a/src/library/scala/util/control/ControlThrowable.scala b/src/library/scala/util/control/ControlThrowable.scala index 4d1116ba6f..8cbe3064ef 100644 --- a/src/library/scala/util/control/ControlThrowable.scala +++ b/src/library/scala/util/control/ControlThrowable.scala @@ -6,32 +6,28 @@ ** |/ ** \* */ - package scala.util.control -/** - * A marker trait indicating that the `Throwable` it is mixed - * into is intended for flow control. - * - * Note that `Throwable` subclasses which extend this trait - * may extend any other `Throwable` subclass (eg. - * `RuntimeException`) and are not required to extend - * `Throwable` directly. +/** A marker trait indicating that the `Throwable` it is mixed into is + * intended for flow control. * - * 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: + * Note that `Throwable` subclasses which extend this trait may extend any + * other `Throwable` subclass (eg. `RuntimeException`) and are not required + * to extend `Throwable` directly. * - * <pre> + * Instances of `Throwable` subclasses marked in this way should not normally + * be caught. Where catch-all behaviour is required `ControlThrowable` + * should be propagated, for example: + * {{{ * import scala.util.control.ControlThrowable * * try { * // Body might throw arbitrarily - * } catch { - * case ce : ControlThrowable => throw ce // propagate - * case t : Exception => log(t) // log and suppress - * </pre> + * } catch { + * case ce : ControlThrowable => throw ce // propagate + * case t : Exception => log(t) // log and suppress + * }}} * - * @author Miles Sabin + * @author Miles Sabin */ trait ControlThrowable extends Throwable with NoStackTrace diff --git a/src/library/scala/util/control/Exception.scala b/src/library/scala/util/control/Exception.scala index ad90b222c2..c8470d2504 100644 --- a/src/library/scala/util/control/Exception.scala +++ b/src/library/scala/util/control/Exception.scala @@ -1,3 +1,11 @@ +/* __ *\ +** ________ ___ / / ___ Scala API ** +** / __/ __// _ | / / / _ | (c) 2003-2011, LAMP/EPFL ** +** __\ \/ /__/ __ |/ /__/ __ | http://scala-lang.org/ ** +** /____/\___/_/ |_/____/_/ | | ** +** |/ ** +\* */ + package scala.util.control import collection.immutable.List @@ -5,17 +13,14 @@ import java.lang.reflect.InvocationTargetException /** Classes representing the components of exception handling. * Each class is independently composable. Some example usages: + * {{{ + * import scala.util.control.Exception._ + * import java.net._ * - * - * - * <pre> - * <b>import</b> scala.util.control.Exception._ - * <b>import</b> java.net._ - * - * <b>val</b> s = "http://www.scala-lang.org/" - * <b>val</b> x1 = catching(classOf[MalformedURLException]) opt new URL(s) - * <b>val</b> x2 = catching(classOf[MalformedURLException], classOf[NullPointerException]) either new URL(s) - * </pre> + * val s = "http://www.scala-lang.org/" + * val x1 = catching(classOf[MalformedURLException]) opt new URL(s) + * val x2 = catching(classOf[MalformedURLException], classOf[NullPointerException]) either new URL(s) + * }}} * * @author Paul Phillips */ @@ -31,6 +36,7 @@ object Exception { def isDefinedAt(x: Throwable) = downcast(x) exists isDef def apply(x: Throwable): T = f(downcast(x).get) } + def mkThrowableCatcher[T](isDef: Throwable => Boolean, f: Throwable => T) = mkCatcher(isDef, f) implicit def throwableSubtypeToCatcher[Ex <: Throwable: ClassManifest, T](pf: PartialFunction[Ex, T]) = @@ -62,7 +68,7 @@ object Exception { protected val name = "Finally" def and(other: => Unit): Finally = new Finally({ body ; other }) - def invoke(): Unit = { body } + def invoke() { body } } /** A container class for catch/finally logic. @@ -92,14 +98,14 @@ object Exception { } finally fin map (_.invoke()) - /* Create an empty Try container with this Catch and the supplied Finally */ + /* Create an empty Try container with this Catch and the supplied `Finally`. */ def andFinally(body: => Unit): Catch[T] = fin match { case None => new Catch(pf, Some(new Finally(body)), rethrow) case Some(f) => new Catch(pf, Some(f and body), rethrow) } /** Apply this catch logic to the supplied body, mapping the result - * into Option[T] - None if any exception was caught, Some(T) otherwise. + * into `Option[T]` - `None` if any exception was caught, `Some(T)` otherwise. */ def opt[U >: T](body: => U): Option[U] = toOption(Some(body)) @@ -109,8 +115,8 @@ object Exception { */ def either[U >: T](body: => U): Either[Throwable, U] = toEither(Right(body)) - /** Create a new Catch with the same isDefinedAt logic as this one, - * but with the supplied apply method replacing the current one. */ + /** Create a `Catch` object with the same `isDefinedAt` logic as this one, + * but with the supplied `apply` method replacing the current one. */ def withApply[U](f: Throwable => U): Catch[U] = { val pf2 = new Catcher[U] { def isDefinedAt(x: Throwable) = pf isDefinedAt x @@ -130,21 +136,21 @@ object Exception { def apply(): T = catcher(body) def apply[U >: T](other: => U): U = catcher(other) - /** As apply, but map caught exceptions to None and success to Some(T) */ + /** As apply, but map caught exceptions to `None` and success to `Some(T)`. */ def opt(): Option[T] = catcher opt body def opt[U >: T](other: => U): Option[U] = catcher opt other - /** As apply, but map caught exceptions to Left(ex) and success to Right(x) */ + /** As apply, but map caught exceptions to `Left(ex)` and success to Right(x) */ def either(): Either[Throwable, T] = catcher either body def either[U >: T](other: => U): Either[Throwable, U] = catcher either other - /** Create a new Try with the supplied body replacing the current body */ + /** Create a `Try` object with the supplied body replacing the current body. */ def tryInstead[U >: T](other: => U) = new Try(other, catcher) - /** Create a new Try with the supplied logic appended to the existing Catch logic. */ + /** Create a `Try` object with the supplied logic appended to the existing Catch logic. */ def or[U >: T](pf: Catcher[U]) = new Try(body, catcher or pf) - /** Create a new Try with the supplied code appended to the existing Finally. */ + /** Create a `Try`object with the supplied code appended to the existing `Finally`. */ def andFinally(fin: => Unit) = new Try(body, catcher andFinally fin) override def toString() = List("Try(<body>)", catcher.toString) mkString " " @@ -153,49 +159,51 @@ object Exception { final val nothingCatcher: Catcher[Nothing] = mkThrowableCatcher(_ => false, throw _) final def allCatcher[T]: Catcher[T] = mkThrowableCatcher(_ => true, throw _) - /** The empty Catch object. */ + /** The empty `Catch` object. */ final val noCatch: Catch[Nothing] = new Catch(nothingCatcher) withDesc "<nothing>" - /** A Catch object which catches everything. */ + /** A `Catch` object which catches everything. */ final def allCatch[T]: Catch[T] = new Catch(allCatcher[T]) withDesc "<everything>" - /** Creates a Catch object which will catch any of the supplied exceptions. - * Since the returned Catch object has no specific logic defined and will simply - * rethrow the exceptions it catches, you will typically want to call "opt" or - * "either" on the return value, or assign custom logic by calling "withApply". + /** Creates a `Catch` object which will catch any of the supplied exceptions. + * Since the returned `Catch` object has no specific logic defined and will simply + * rethrow the exceptions it catches, you will typically want to call `opt` or + * `either` on the return value, or assign custom logic by calling "withApply". * - * Note that Catch objects automatically rethrow ControlExceptions and others + * Note that `Catch` objects automatically rethrow `ControlExceptions` and others * which should only be caught in exceptional circumstances. If you really want - * to catch exactly what you specify, use "catchingPromiscuously" instead. + * to catch exactly what you specify, use `catchingPromiscuously` instead. */ def catching[T](exceptions: Class[_]*): Catch[T] = new Catch(pfFromExceptions(exceptions : _*)) withDesc (exceptions map (_.getName) mkString ", ") def catching[T](c: Catcher[T]): Catch[T] = new Catch(c) - /** Creates a Catch object which will catch any of the supplied exceptions. + /** Creates a `Catch` object which will catch any of the supplied exceptions. * Unlike "catching" which filters out those in shouldRethrow, this one will - * catch whatever you ask of it: ControlThrowable, InterruptedException, - * OutOfMemoryError, you name it. + * catch whatever you ask of it: `ControlThrowable`, `InterruptedException`, + * `OutOfMemoryError`, you name it. */ def catchingPromiscuously[T](exceptions: Class[_]*): Catch[T] = catchingPromiscuously(pfFromExceptions(exceptions : _*)) def catchingPromiscuously[T](c: Catcher[T]): Catch[T] = new Catch(c, None, _ => false) - /** Creates a Catch object which catches and ignores any of the supplied exceptions. */ + /** Creates a `Catch` object which catches and ignores any of the supplied exceptions. */ def ignoring(exceptions: Class[_]*): Catch[Unit] = catching(exceptions: _*) withApply (_ => ()) - /** Creates a Catch object which maps all the supplied exceptions to 'None'. */ + /** Creates a `Catch` object which maps all the supplied exceptions to `None`. */ def failing[T](exceptions: Class[_]*): Catch[Option[T]] = catching(exceptions: _*) withApply (_ => None) - /** Creates a Catch object which maps all the supplied exceptions to the given value. */ + /** Creates a `Catch` object which maps all the supplied exceptions to the given value. */ def failAsValue[T](exceptions: Class[_]*)(value: => T): Catch[T] = catching(exceptions: _*) withApply (_ => value) - /** Returns a partially constructed Catch object, which you must give - * an exception handler function as an argument to "by". Example: - * handling(ex1, ex2) by (_.printStackTrace) + /** Returns a partially constructed `Catch` object, which you must give + * an exception handler function as an argument to `by`. Example: + * {{{ + * handling(ex1, ex2) by (_.printStackTrace) + * }}} */ class By[T,R](f: T => R) { def by(x: T): R = f(x) @@ -205,10 +213,10 @@ object Exception { new By[Throwable => T, Catch[T]](fun _) } - /** Returns a Catch object with no catch logic and the argument as Finally. */ + /** Returns a `Catch` object with no catch logic and the argument as `Finally`. */ def ultimately[T](body: => Unit): Catch[T] = noCatch andFinally body - /** Creates a Catch object which unwraps any of the supplied exceptions. */ + /** Creates a `Catch` object which unwraps any of the supplied exceptions. */ def unwrapping[T](exceptions: Class[_]*): Catch[T] = { def unwrap(x: Throwable): Throwable = if (wouldMatch(x, exceptions) && x.getCause != null) unwrap(x.getCause) diff --git a/src/library/scala/util/control/TailCalls.scala b/src/library/scala/util/control/TailCalls.scala index 59e9618028..ca5442046c 100644 --- a/src/library/scala/util/control/TailCalls.scala +++ b/src/library/scala/util/control/TailCalls.scala @@ -1,10 +1,18 @@ +/* __ *\ +** ________ ___ / / ___ Scala API ** +** / __/ __// _ | / / / _ | (c) 2003-2011, LAMP/EPFL ** +** __\ \/ /__/ __ |/ /__/ __ | http://scala-lang.org/ ** +** /____/\___/_/ |_/____/_/ | | ** +** |/ ** +\* */ + package scala.util.control /** Methods exported by this object implement tail calls via trampolining. - * Tail calling methods have to return their result using `done` or call the next - * method using `tailcall`. Both return a `TailRec` object. The result of evaluating - * a tailcalling function can be retrieved from a `Tailrec` value using method result`. - * Here's a usage example: + * Tail calling methods have to return their result using `done` or call the + * next method using `tailcall`. Both return a `TailRec` object. The result + * of evaluating a tailcalling function can be retrieved from a `Tailrec` + * value using method `result`. Here's a usage example: * {{{ * import scala.util.control.TailCalls._ * @@ -19,10 +27,10 @@ package scala.util.control */ object TailCalls { - /** This class represents a tailcalling computation. + /** This class represents a tailcalling computation */ abstract class TailRec[+A] { - /** Returns the result of the tailcalling computation + /** Returns the result of the tailcalling computation. */ def result: A = { def loop(body: TailRec[A]): A = body match { @@ -36,7 +44,8 @@ object TailCalls { /** Internal class representing a tailcall */ protected case class Call[A](rest: () => TailRec[A]) extends TailRec[A] - /** Internal class representing the final result return from a tailcalling computation */ + /** Internal class representing the final result returned from a tailcalling + * computation */ protected case class Done[A](override val result: A) extends TailRec[A] /** Performs a tailcall @@ -47,10 +56,9 @@ object TailCalls { /** Used to return final result from tailcalling computation * @param `result` the result value - * @return a `TailRec` object representing a computation which immediately returns `result` + * @return a `TailRec` object representing a computation which immediately + * returns `result` */ def done[A](result: A): TailRec[A] = new Done(result) } - - diff --git a/src/library/scala/util/parsing/combinator/PackratParsers.scala b/src/library/scala/util/parsing/combinator/PackratParsers.scala index 3f09ae506d..ea856efc3a 100644 --- a/src/library/scala/util/parsing/combinator/PackratParsers.scala +++ b/src/library/scala/util/parsing/combinator/PackratParsers.scala @@ -6,7 +6,6 @@ ** |/ ** \* */ - package scala.util.parsing.combinator import scala.util.parsing.combinator._ @@ -14,29 +13,34 @@ import scala.util.parsing.input.{ Reader, Position } import scala.collection.mutable /** - * `PackratParsers` is a component that extends the parser combinators provided by - * [[scala.util.parsing.combinator.Parsers]] with a memoization facility (``Packrat Parsing''). + * `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, + * 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. + * - 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. + * 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 @@ -54,7 +58,7 @@ trait PackratParsers extends Parsers { * 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 => + class PackratReader[+T](underlying: Reader[T]) extends Reader[T] { outer => /* * caching of intermediate parse results and information about recursion @@ -91,7 +95,6 @@ trait PackratParsers extends Parsers { def atEnd: Boolean = underlying.atEnd } - /** * A parser generator delimiting whole phrases (i.e. programs). * @@ -108,7 +111,6 @@ trait PackratParsers extends Parsers { } } - private def getPosFromResult(r: ParseResult[_]): Position = r.next.pos // auxiliary data structures @@ -136,14 +138,14 @@ trait PackratParsers extends Parsers { /** * Implicitly convert a parser to a packrat parser. * The conversion is triggered by giving the appropriate target type: - * val myParser: PackratParser[MyResult] = aParser - */ + * {{{ + * val myParser: PackratParser[MyResult] = aParser + * }}} */ implicit def parser2packrat[T](p: => super.Parser[T]): PackratParser[T] = { lazy val q = p memo(super.Parser {in => q(in)}) } - /* * An unspecified function that is called when a packrat reader is applied. * It verifies whether we are in the process of growing a parse or not. diff --git a/src/library/scala/util/parsing/combinator/Parsers.scala b/src/library/scala/util/parsing/combinator/Parsers.scala index e9155afc55..bb73b28ea8 100644 --- a/src/library/scala/util/parsing/combinator/Parsers.scala +++ b/src/library/scala/util/parsing/combinator/Parsers.scala @@ -23,7 +23,8 @@ import annotation.migration * * There are two aspects to the result of a parser: * 1. success or failure - * 2. the result. + * 1. the result. + * * A `Parser[T]` provides both kinds of information. * * The term ''parser combinator'' refers to the fact that these parsers @@ -44,18 +45,20 @@ import annotation.migration * @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''. + /** 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, i.e. the type of input the parsers in this component - * expect. */ + /** 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 `T` which consists of some result (and the rest of - * the input). */ + /** 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. * @@ -91,7 +94,7 @@ trait Parsers { val successful: Boolean } - /** The success case of ParseResult: contains the result and the remaining input. + /** The success case of `ParseResult`: contains the result and the remaining input. * * @param result The parser's output * @param next The parser's remaining input @@ -131,7 +134,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) @@ -140,7 +143,7 @@ trait Parsers { } } - /** The failure case of ParseResult: contains an error-message and the remaining input. + /** The failure case of `ParseResult`: contains an error-message and the remaining input. * Parsing will back-track when a failure occurs. * * @param msg An error message string describing the failure. @@ -156,8 +159,9 @@ 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` + /** 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`. * * @param msg An error message string describing the error. * @param next The parser's unconsumed input at the point where the error occurred. @@ -168,7 +172,6 @@ trait Parsers { def append[U >: Nothing](a: => ParseResult[U]): ParseResult[U] = this } - def Parser[T](f: Input => ParseResult[T]): Parser[T] = new Parser[T]{ def apply(in: Input) = f(in) } @@ -199,7 +202,6 @@ trait Parsers { Parser{ in => this(in) append p(in)} } - // the operator formerly known as +++, ++, &, but now, behold the venerable ~ // it's short, light (looks like whitespace), has few overloaded meaning (thanks to the recent change from ~ to unary_~) // and we love it! (or do we like `,` better?) @@ -313,7 +315,6 @@ trait Parsers { */ def ^^ [U](f: T => U): Parser[U] = map(f).named(toString+"^^") - /** A parser combinator that changes a successful result into the specified value. * * `p ^^^ v` succeeds if `p` succeeds; discards its result, and returns `v` instead. @@ -355,7 +356,6 @@ trait Parsers { */ def ^? [U](f: PartialFunction[T, U]): Parser[U] = ^?(f, r => "Constructor function not defined at "+r) - /** A parser combinator that parameterizes a subsequent parser with the result of this one. * * Use this combinator when a parser depends on the result of a previous parser. `p` should be @@ -376,15 +376,15 @@ trait Parsers { /** Returns `into(fq)`. */ def >>[U](fq: T => Parser[U])=into(fq) - /** Returns a parser that repeatedly parses what this parser parses. * * @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. + /** 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. * * @return chainl1(this, sep) */ @@ -405,8 +405,9 @@ trait Parsers { def ? = opt(this) } - /** Wrap a parser so that its failures become errors (the `|` combinator will give up as soon as - * it encounters an error, on failure it simply tries the next alternative). + /** Wrap a parser so that its failures become errors (the `|` combinator + * will give up as soon as it encounters an error, on failure it simply + * tries the next alternative). */ def commit[T](p: => Parser[T]) = Parser{ in => p(in) match{ @@ -420,7 +421,6 @@ trait Parsers { case class EFCons(hd: Elem => ElemFun, tl: ElemFun) extends ElemFun case class EFNil(res: Boolean) extends ElemFun*/ - /** 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. @@ -463,8 +463,8 @@ trait Parsers { /** The parser that matches an element in the domain of the partial function `f`. * - * If `f` is defined on the first element in the input, `f` is applied to it to produce - * this parser's result. + * If `f` is defined on the first element in the input, `f` is applied + * to it to produce this parser's result. * * Example: The parser `accept("name", {case Identifier(n) => Name(n)})` * accepts an `Identifier(n)` and returns a `Name(n)` @@ -476,7 +476,6 @@ trait Parsers { */ def accept[U](expected: String, f: PartialFunction[Elem, U]): Parser[U] = acceptMatch(expected, f) - def acceptIf(p: Elem => Boolean)(err: Elem => String): Parser[Elem] = Parser { in => if (p(in.first)) Success(in.first, in.rest) else Failure(err(in.first), in) @@ -487,7 +486,8 @@ trait Parsers { else Failure(expected+" expected", in) } - def acceptSeq[ES <% Iterable[Elem]](es: ES): Parser[List[Elem]] = es.foldRight[Parser[List[Elem]]](success(Nil)){(x, pxs) => accept(x) ~ pxs ^^ mkList} + def acceptSeq[ES <% Iterable[Elem]](es: ES): Parser[List[Elem]] = + es.foldRight[Parser[List[Elem]]](success(Nil)){(x, pxs) => accept(x) ~ pxs ^^ mkList} /** A parser that always fails. * @@ -503,7 +503,6 @@ trait Parsers { */ def err(msg: String) = Parser{ in => Error(msg, in) } - /** A parser that always succeeds. * * @param v The result for the parser @@ -520,8 +519,8 @@ trait Parsers { /** A parser generator for repetitions. * - * `rep(p)` repeatedly uses `p` to parse the input until `p` fails (the result is a List - * of the consecutive results of `p`). + * `rep(p)` repeatedly uses `p` to parse the input until `p` fails + * (the result is a List of the consecutive results of `p`). * * @param p a `Parser` that is to be applied successively to the input * @return A parser that returns a list of results produced by repeatedly applying `p` to the input. @@ -604,8 +603,8 @@ trait Parsers { @tailrec def applyp(in0: Input): ParseResult[List[T]] = if (elems.length == num) Success(elems.toList, in0) else p0(in0) match { - case Success(x, rest) => elems += x ; applyp(rest) - case ns: NoSuccess => return ns + case Success(x, rest) => elems += x ; applyp(rest) + case ns: NoSuccess => return ns } applyp(in) @@ -613,8 +612,8 @@ trait Parsers { /** A parser generator for non-empty repetitions. * - * `rep1sep(p, q)` repeatedly applies `p` interleaved with `q` to parse the input, until `p` fails. - * The parser `p` must succeed at least once. + * `rep1sep(p, q)` repeatedly applies `p` interleaved with `q` to parse the + * input, until `p` fails. The parser `p` must succeed at least once. * * @param p a `Parser` that is to be applied successively to the input * @param q a `Parser` that parses the elements that separate the elements parsed by `p` @@ -626,8 +625,9 @@ trait Parsers { def rep1sep[T](p : => Parser[T], q : => Parser[Any]): Parser[List[T]] = p ~ rep(q ~> p) ^^ {case x~y => x::y} - /** A parser generator that, roughly, generalises the rep1sep generator so that `q`, which parses the separator, - * produces a left-associative function that combines the elements it separates. + /** A parser generator that, roughly, generalises the rep1sep generator so + * that `q`, which parses the separator, produces a left-associative + * function that combines the elements it separates. * * ''From: J. Fokker. Functional parsers. In J. Jeuring and E. Meijer, editors, Advanced Functional Programming, * volume 925 of Lecture Notes in Computer Science, pages 1--23. Springer, 1995.'' @@ -639,22 +639,25 @@ trait Parsers { def chainl1[T](p: => Parser[T], q: => Parser[(T, T) => T]): Parser[T] = chainl1(p, p, q) - /** A parser generator that, roughly, generalises the `rep1sep` generator so that `q`, which parses the separator, - * produces a left-associative function that combines the elements it separates. + /** A parser generator that, roughly, generalises the `rep1sep` generator + * so that `q`, which parses the separator, produces a left-associative + * function that combines the elements it separates. * * @param first a parser that parses the first element * @param p a parser that parses the subsequent elements - * @param q a parser that parses the token(s) separating the elements, yielding a left-associative function that - * combines two elements into one + * @param q a parser that parses the token(s) separating the elements, + * yielding a left-associative function that combines two elements + * into one */ def chainl1[T, U](first: => Parser[T], p: => Parser[U], q: => Parser[(T, U) => T]): Parser[T] = first ~ rep(q ~ p) ^^ { case x ~ xs => xs.foldLeft(x){(_, _) match {case (a, f ~ b) => f(a, b)}} } - /** A parser generator that generalises the `rep1sep` generator so that `q`, which parses the separator, - * produces a right-associative function that combines the elements it separates. Additionally, - * The right-most (last) element and the left-most combining function have to be supplied. + /** A parser generator that generalises the `rep1sep` generator so that `q`, + * which parses the separator, produces a right-associative function that + * combines the elements it separates. Additionally, the right-most (last) + * element and the left-most combining function have to be supplied. * * rep1sep(p: Parser[T], q) corresponds to chainr1(p, q ^^ cons, cons, Nil) (where val cons = (x: T, y: List[T]) => x :: y) * @@ -681,7 +684,8 @@ trait Parsers { def opt[T](p: => Parser[T]): Parser[Option[T]] = p ^^ (x => Some(x)) | success(None) - /** Wrap a parser so that its failures and errors become success and vice versa -- it never consumes any input. + /** Wrap a parser so that its failures and errors become success and + * vice versa -- it never consumes any input. */ def not[T](p: => Parser[T]): Parser[Unit] = Parser { in => p(in) match { @@ -690,11 +694,13 @@ trait Parsers { } } - /** A parser generator for guard expressions. The resulting parser will fail or succeed - * just like the one given as parameter but it will not consume any input. + /** A parser generator for guard expressions. The resulting parser will + * fail or succeed just like the one given as parameter but it will not + * consume any input. * * @param p a `Parser` that is to be applied to the input - * @return A parser that returns success if and only if `p` succeeds but never consumes any input + * @return A parser that returns success if and only if `p` succeeds but + * never consumes any input */ def guard[T](p: => Parser[T]): Parser[T] = Parser { in => p(in) match{ @@ -703,12 +709,13 @@ trait Parsers { } } - - /** `positioned` decorates a parser's result with the start position of the input it consumed. + /** `positioned` decorates a parser's result with the start position of the + * input it consumed. * * @param p a `Parser` whose result conforms to `Positional`. - * @return A parser that has the same behaviour as `p`, but which marks its result with the - * start position of the input it consumed, if it didn't already have a position. + * @return A parser that has the same behaviour as `p`, but which marks its + * result with the start position of the input it consumed, + * if it didn't already have a position. */ def positioned[T <: Positional](p: => Parser[T]): Parser[T] = Parser { in => p(in) match { diff --git a/src/library/scala/util/parsing/combinator/lexical/StdLexical.scala b/src/library/scala/util/parsing/combinator/lexical/StdLexical.scala index 6c8bad01c1..3ac5c07dc4 100644 --- a/src/library/scala/util/parsing/combinator/lexical/StdLexical.scala +++ b/src/library/scala/util/parsing/combinator/lexical/StdLexical.scala @@ -6,8 +6,6 @@ ** |/ ** \* */ - - package scala.util.parsing package combinator package lexical @@ -16,16 +14,19 @@ import token._ import input.CharArrayReader.EofCh import scala.collection.mutable -/** This component provides a standard lexical parser for a simple, Scala-like language. - * It parses keywords and identifiers, numeric literals (integers), strings, and delimiters. +/** This component provides a standard lexical parser for a simple, + * [[http://scala-lang.org Scala]]-like language. It parses keywords and + * identifiers, numeric literals (integers), strings, and delimiters. * - * To distinguish between identifiers and keywords, it uses a set of reserved identifiers: - * every string contained in `reserved` is returned as a keyword token. - * (Note that "=>" is hard-coded as a keyword.) - * Additionally, the kinds of delimiters can be specified by the `delimiters` set. + * To distinguish between identifiers and keywords, it uses a set of + * reserved identifiers: every string contained in `reserved` is returned + * as a keyword token. (Note that `=>` is hard-coded as a keyword.) + * Additionally, the kinds of delimiters can be specified by the + * `delimiters` set. * - * Usually this component is used to break character-based input into bigger tokens, - * which are then passed to a token-parser {@see TokenParsers}. + * Usually this component is used to break character-based input into + * bigger tokens, which are then passed to a token-parser {@see + * [[scala.util.parsing.combinator.syntactical.TokenParsers]]}. * * @author Martin Odersky * @author Iulian Dragos diff --git a/src/library/scala/util/parsing/combinator/testing/Tester.scala b/src/library/scala/util/parsing/combinator/testing/Tester.scala index ca1df2f6d4..4607dc8843 100644 --- a/src/library/scala/util/parsing/combinator/testing/Tester.scala +++ b/src/library/scala/util/parsing/combinator/testing/Tester.scala @@ -6,7 +6,6 @@ ** |/ ** \* */ - package scala.util.parsing.combinator.testing import scala.util.parsing.combinator._ @@ -16,15 +15,13 @@ import scala.util.parsing.combinator.syntactical.TokenParsers /** Facilitates testing a given parser on various input strings. * * Example use: - * - * <pre> - * <b>val</b> syntactic = <b>new</b> MyParsers - * </pre> + * {{{ + * val syntactic = new MyParsers + * }}} * and - * <pre> - * <b>val</b> parser = syntactic.term - * </pre> - * + * {{{ + * val parser = syntactic.term + * }}} * (If `MyParsers` extends [[scala.util.parsing.combinator.syntactical.TokenParsers]] * with a parser called `term`.) * @@ -36,10 +33,9 @@ abstract class Tester { val syntactic: TokenParsers { val lexical: Lexical } val parser: syntactic.Parser[Any] - - /** Scans a String (using a `syntactic.lexical.Scanner`), parses it - * using `phrase(parser)`, and prints the input and the - * parsed result to the console. + /** Scans a String (using a `syntactic.lexical.Scanner`), parses it using + * `phrase(parser)`, and prints the input and the parsed result to the + * console. */ def test(in: String) { Console.println("\nin : "+in) diff --git a/src/library/scala/util/parsing/json/JSON.scala b/src/library/scala/util/parsing/json/JSON.scala index 036964680e..b0926d20e7 100644 --- a/src/library/scala/util/parsing/json/JSON.scala +++ b/src/library/scala/util/parsing/json/JSON.scala @@ -6,21 +6,19 @@ ** |/ ** \* */ - - package scala.util.parsing.json import scala.util.parsing.combinator._ import scala.util.parsing.combinator.syntactical._ import scala.util.parsing.combinator.lexical._ /** - * This object provides a simple interface to the JSON parser class. The default conversion - * for numerics is into a double. If you wish to override this behavior at the global level, - * you can set the globalNumberParser property to your own (String => Any) function. If you only - * want to override at the per-thread level then you can set the perThreadNumberParser property to your - * function. For example: - * - * <pre> + * This object provides a simple interface to the JSON parser class. + * The default conversion for numerics is into a double. If you wish to + * override this behavior at the global level, you can set the + * `globalNumberParser` property to your own `(String => Any)` function. + * If you only want to override at the per-thread level then you can set + * the `perThreadNumberParser` property to your function. For example: + * {{{ * val myConversionFunc = {input : String => BigDecimal(input)} * * // Global override @@ -28,18 +26,18 @@ import scala.util.parsing.combinator.lexical._ * * // Per-thread override * JSON.perThreadNumberParser = myConversionFunc - * </pre> + * }}} * - * @author Derek Chen-Becker <"java"+@+"chen-becker"+"."+"org"> + * @author Derek Chen-Becker <"java"+@+"chen-becker"+"."+"org"> */ object JSON extends Parser { /** - * Parse the given JSON string and return a list of elements. If the - * string is a JSON object it will be a list of pairs. If it's a JSON + * Parse the given `JSON` string and return a list of elements. If the + * string is a `JSON` object it will be a list of pairs. If it's a `JSON` * array it will be be a list of individual elements. * - * @param input the given JSON string. + * @param input the given `JSON` string. * @return an optional list of of elements. */ @deprecated("Use parseFull or parseRaw as needed.", "2.8.0") @@ -49,7 +47,7 @@ object JSON extends Parser { }) /** - * This method converts "raw" results back into the original, deprecated + * This method converts ''raw'' results back into the original, deprecated * form. */ private def unRaw (in : Any) : Any = in match { @@ -59,12 +57,12 @@ object JSON extends Parser { } /** - * Parse the given JSON string and return a list of elements. If the - * string is a JSON object it will be a JSONObject. If it's a JSON - * array it will be be a JSONArray. + * Parse the given `JSON` string and return a list of elements. If the + * string is a `JSON` object it will be a `JSONObject`. If it's a `JSON` + * array it will be be a `JSONArray`. * - * @param input the given JSON string. - * @return an optional JSONType element. + * @param input the given `JSON` string. + * @return an optional `JSONType` element. */ def parseRaw(input : String) : Option[JSONType] = phrase(root)(new lexical.Scanner(input)) match { @@ -73,11 +71,11 @@ object JSON extends Parser { } /** - * Parse the given JSON string and return either a <code>List[Any]</code> - * if the JSON string specifies an <code>Array</code>, or a - * <code>Map[String,Any]</code> if the JSON string specifies an object. + * Parse the given `JSON` string and return either a `List[Any]` + * if the `JSON` string specifies an `Array`, or a + * `Map[String,Any]` if the `JSON` string specifies an object. * - * @param input the given JSON string. + * @param input the given `JSON` string. * @return an optional list or map. */ def parseFull(input: String): Option[Any] = @@ -87,8 +85,8 @@ object JSON extends Parser { } /** - * A utility method to resolve a parsed JSON list into objects or - * arrays. See the parse method for details. + * A utility method to resolve a parsed `JSON` list into objects or + * arrays. See the `parse` method for details. */ def resolveType(input: Any): Any = input match { case JSONObject(data) => data.transform { @@ -105,8 +103,9 @@ object JSON extends Parser { def globalNumberParser : NumericParser = defaultNumberParser /** - * Defines the function used to convert a numeric string literal into a numeric format on a per-thread - * basis. Use globalNumberParser for a global override + * Defines the function used to convert a numeric string literal into a + * numeric format on a per-thread basis. Use `globalNumberParser` for a + * global override. */ def perThreadNumberParser_=(f : NumericParser) { numberParser.set(f) } def perThreadNumberParser : NumericParser = numberParser.get() diff --git a/src/library/scala/util/regexp/WordExp.scala b/src/library/scala/util/regexp/WordExp.scala index 6a83794ef4..cf146934d1 100644 --- a/src/library/scala/util/regexp/WordExp.scala +++ b/src/library/scala/util/regexp/WordExp.scala @@ -13,27 +13,27 @@ package scala.util.regexp /** * The class `WordExp` provides regular word expressions. * - * Users have to instantiate type member `_regexpT <;: RegExp` (from class `Base`) - * and a type member `_labelT <;: Label`. + * 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 { - * <b>type</b> _regexpT = RegExp - * <b>type</b> _labelT = MyChar + * {{{ + * import scala.util.regexp._ + * import scala.util.automata._ + * object MyLang extends WordExp { + * type _regexpT = RegExp + * type _labelT = MyChar * - * <b>case class</b> MyChar(c:Char) <b>extends</b> Label + * case class MyChar(c:Char) extends Label * } - * <b>import</b> MyLang._ + * import MyLang._ * // (a* | b)* - * <b>val</b> rex = Star(Alt(Star(Letter(MyChar('a'))),Letter(MyChar('b')))) - * <b>object</b> MyBerriSethi <b>extends</b> WordBerrySethi { - * <b>override val</b> lang = MyLang + * val rex = Star(Alt(Star(Letter(MyChar('a'))),Letter(MyChar('b')))) + * object MyBerriSethi extends WordBerrySethi { + * override val lang = MyLang * } - * <b>val</b> nfa = MyBerriSethi.automatonFrom(Sequ(rex), 1) - * </pre> + * val nfa = MyBerriSethi.automatonFrom(Sequ(rex), 1) + * }}} * * @author Burak Emir * @version 1.0 @@ -55,4 +55,3 @@ abstract class WordExp extends Base { var pos = -1 } } - diff --git a/src/library/scala/xml/Equality.scala b/src/library/scala/xml/Equality.scala index 1e7cd482ed..051783c1cd 100644 --- a/src/library/scala/xml/Equality.scala +++ b/src/library/scala/xml/Equality.scala @@ -8,26 +8,23 @@ package scala.xml -/** In an attempt to contain the damage being inflicted on - * consistency by the ad hoc equals methods spread around - * xml, the logic is centralized and all the xml classes - * go through the xml.Equality trait. There are two forms - * of xml comparison. +/** In an attempt to contain the damage being inflicted on consistency by the + * ad hoc `equals` methods spread around `xml`, the logic is centralized and + * all the `xml` classes go through the `xml.Equality trait`. There are two + * forms of `xml` comparison. * - * 1) def strict_==(other: xml.Equality) + * 1. `'''def''' strict_==(other: xml.Equality)` * - * This one tries to honor the little things like symmetry - * and hashCode contracts. The equals method routes all - * comparisons through this. + * This one tries to honor the little things like symmetry and hashCode + * contracts. The `equals` method routes all comparisons through this. * - * 2) xml_==(other: Any) + * 1. `xml_==(other: Any)` * - * This one picks up where strict_== leaves off. It might - * declare any two things equal. + * This one picks up where `strict_==` leaves off. It might declare any two + * things equal. * - * As things stood, the logic not only made a mockery of - * the collections equals contract, but also laid waste to - * that of case classes. + * As things stood, the logic not only made a mockery of the collections + * equals contract, but also laid waste to that of case classes. * * Among the obstacles to sanity are/were: * @@ -74,7 +71,7 @@ trait Equality extends scala.Equals { def strict_==(other: Equality): Boolean def strict_!=(other: Equality) = !strict_==(other) - /** We insist we're only equal to other xml.Equality implementors, + /** We insist we're only equal to other `xml.Equality` implementors, * which heads off a lot of inconsistency up front. */ override def canEqual(other: Any): Boolean = other match { @@ -107,4 +104,3 @@ trait Equality extends scala.Equals { strictlyEqual || (blithe && compareBlithely(this, asRef(other))) } } - diff --git a/src/library/scala/xml/NodeBuffer.scala b/src/library/scala/xml/NodeBuffer.scala index 2495cb0f0f..1af225d856 100644 --- a/src/library/scala/xml/NodeBuffer.scala +++ b/src/library/scala/xml/NodeBuffer.scala @@ -6,20 +6,15 @@ ** |/ ** \* */ - package scala.xml /** - * <p> - * This class acts as a Buffer for nodes. If it is used as a sequence - * of nodes <code>Seq[Node]</code>, it must be ensured that no updates - * occur after that point, because <code>scala.xml.Node</code> is assumed - * to be immutable. - * </p> - * <p> - * Despite this being a sequence, don't use it as key in a hashtable. - * Calling the hashcode function will result in a runtime error. - * </p> + * This class acts as a Buffer for nodes. If it is used as a sequence of + * nodes `Seq[Node]`, it must be ensured that no updates occur after that + * point, because `scala.xml.Node` is assumed to be immutable. + * + * Despite this being a sequence, don't use it as key in a hashtable. + * Calling the hashcode function will result in a runtime error. * * @author Burak Emir * @version 1.0 @@ -27,10 +22,12 @@ package scala.xml class NodeBuffer extends scala.collection.mutable.ArrayBuffer[Node] { /** - * Append given object to this buffer, returns reference on this NodeBuffer - * for convenience. Some rules apply: If o is null, it is ignored. If it is - * an Iterator or Iterable, its elements will be added. If o is a node, it is - * added as it is. If it is anything else, it gets wrapped in an Atom. + * Append given object to this buffer, returns reference on this + * `NodeBuffer` for convenience. Some rules apply: + * - If argument `o` is `'''null'''`, it is ignored. + * - If it is an `Iterator` or `Iterable`, its elements will be added. + * - If `o` is a node, it is added as it is. + * - If it is anything else, it gets wrapped in an [[scala.xml.Atom]]. * * @param o converts to an xml node and adds to this node buffer * @return this nodebuffer diff --git a/src/library/scala/xml/NodeSeq.scala b/src/library/scala/xml/NodeSeq.scala index 1524ab852f..2732223e19 100644 --- a/src/library/scala/xml/NodeSeq.scala +++ b/src/library/scala/xml/NodeSeq.scala @@ -6,8 +6,6 @@ ** |/ ** \* */ - - package scala.xml import collection.{ mutable, immutable, generic, SeqLike } @@ -34,8 +32,8 @@ object NodeSeq { implicit def seqToNodeSeq(s: Seq[Node]): NodeSeq = fromSeq(s) } -/** This class implements a wrapper around <code>Seq[Node]</code> that - * adds XPath and comprehension methods. +/** This class implements a wrapper around `Seq[Node]` that adds XPath + * and comprehension methods. * * @author Burak Emir * @version 1.0 @@ -72,15 +70,16 @@ abstract class NodeSeq extends immutable.Seq[Node] with SeqLike[Node, NodeSeq] w case _ => false } - /** Projection function, which returns elements of `this` sequence based on the string `that`. Use: + /** Projection function, which returns elements of `this` sequence based + * on the string `that`. Use: * - `this \ "foo"` to get a list of all elements that are labelled with `"foo"`; * - `\ "_"` to get a list of all elements (wildcard); * - `ns \ "@foo"` to get the unprefixed attribute `"foo"`; - * - `ns \ "@{uri}foo"` to get the prefixed attribute `"pre:foo"` whose prefix `"pre"` is resolved to the - * namespace `"uri"`. + * - `ns \ "@{uri}foo"` to get the prefixed attribute `"pre:foo"` whose + * prefix `"pre"` is resolved to the namespace `"uri"`. * - * For attribute projections, the resulting [[scala.xml.NodeSeq]] attribute values are wrapped in a - * [[scala.xml.Group]]. + * For attribute projections, the resulting [[scala.xml.NodeSeq]] attribute + * values are wrapped in a [[scala.xml.Group]]. * * There is no support for searching a prefixed attribute by its literal prefix. * @@ -121,16 +120,16 @@ abstract class NodeSeq extends immutable.Seq[Node] with SeqLike[Node, NodeSeq] w } } - /** Projection function, which returns elements of `this` sequence and of all its subsequences, based on - * the string `that`. Use: + /** Projection function, which returns elements of `this` sequence and of + * all its subsequences, based on the string `that`. Use: * - `this \\ 'foo` to get a list of all elements that are labelled with `"foo"`; * - `\\ "_"` to get a list of all elements (wildcard); * - `ns \\ "@foo"` to get the unprefixed attribute `"foo"`; - * - `ns \\ "@{uri}foo"` to get each prefixed attribute `"pre:foo"` whose prefix `"pre"` is resolved to the - * namespace `"uri"`. + * - `ns \\ "@{uri}foo"` to get each prefixed attribute `"pre:foo"` whose + * prefix `"pre"` is resolved to the namespace `"uri"`. * - * For attribute projections, the resulting [[scala.xml.NodeSeq]] attribute values are wrapped in a - * [[scala.xml.Group]]. + * For attribute projections, the resulting [[scala.xml.NodeSeq]] attribute + * values are wrapped in a [[scala.xml.Group]]. * * There is no support for searching a prefixed attribute by its literal prefix. * @@ -149,5 +148,6 @@ abstract class NodeSeq extends immutable.Seq[Node] with SeqLike[Node, NodeSeq] w } override def toString(): String = theSeq.mkString - def text: String = this map (_.text) mkString + + def text: String = this map (_.text) mkString } diff --git a/src/library/scala/xml/SpecialNode.scala b/src/library/scala/xml/SpecialNode.scala index d69dbac913..758b018a13 100644 --- a/src/library/scala/xml/SpecialNode.scala +++ b/src/library/scala/xml/SpecialNode.scala @@ -9,13 +9,10 @@ package scala.xml -/** <p> - * <code>SpecialNode</code> is a special XML node which - * represents either text (PCDATA), a comment, a PI, or an entity ref. - * </p> - * <p> - * SpecialNodes also play the role of XMLEvents for pull-parsing. - * </p> +/** `SpecialNode` is a special XML node which represents either text + * `(PCDATA)`, a comment, a `PI`, or an entity ref. + * + * SpecialNodes also play the role of XMLEvents for pull-parsing. * * @author Burak Emir */ @@ -30,6 +27,6 @@ abstract class SpecialNode extends Node with pull.XMLEvent /** always empty */ final def child = Nil - /** append string representation to the given stringbuffer */ + /** Append string representation to the given stringbuffer argument. */ def buildString(sb: StringBuilder): StringBuilder } diff --git a/src/library/scala/xml/Text.scala b/src/library/scala/xml/Text.scala index 734cbe3904..e9e09b0048 100644 --- a/src/library/scala/xml/Text.scala +++ b/src/library/scala/xml/Text.scala @@ -6,7 +6,6 @@ ** |/ ** \* */ - package scala.xml // XXX This attempt to make Text not a case class revealed a bug in the pattern @@ -26,7 +25,7 @@ package scala.xml // } // } -/** The class <code>Text</code> implements an XML node for text (PCDATA). +/** The class `Text` implements an XML node for text (PCDATA). * It is used in both non-bound and bound XML representations. * * @author Burak Emir diff --git a/src/library/scala/xml/TextBuffer.scala b/src/library/scala/xml/TextBuffer.scala index 817cf03ef4..bcd5fc731f 100644 --- a/src/library/scala/xml/TextBuffer.scala +++ b/src/library/scala/xml/TextBuffer.scala @@ -15,10 +15,10 @@ object TextBuffer { def fromString(str: String): TextBuffer = new TextBuffer() append str } -/** The class <code>TextBuffer</code> is for creating text nodes without - * surplus whitespace. All occurrences of one or more whitespace in strings - * appended with the <code>append</code> method will be replaced by a single - * space character, and leading and trailing space will be removed completely. +/** The class `TextBuffer` is for creating text nodes without surplus + * whitespace. All occurrences of one or more whitespace in strings + * appended with the `append` method will be replaced by a single space + * character, and leading and trailing space will be removed completely. */ class TextBuffer { diff --git a/src/library/scala/xml/Utility.scala b/src/library/scala/xml/Utility.scala index 05cc7b116b..3969bb9338 100644 --- a/src/library/scala/xml/Utility.scala +++ b/src/library/scala/xml/Utility.scala @@ -12,8 +12,8 @@ import scala.collection.mutable import parsing.XhtmlEntities /** - * The <code>Utility</code> object provides utility functions for processing - * instances of bound and not bound XML classes, as well as escaping text nodes. + * The `Utility` object provides utility functions for processing instances + * of bound and not bound XML classes, as well as escaping text nodes. * * @author Burak Emir */ @@ -31,22 +31,21 @@ object Utility extends AnyRef with parsing.TokenTests { } private[xml] def isAtomAndNotText(x: Node) = x.isAtom && !x.isInstanceOf[Text] - /** trims an element - call this method, when you know that it is an + /** Trims an element - call this method, when you know that it is an * element (and not a text node) so you know that it will not be trimmed - * away. With this assumption, the function can return a <code>Node</code>, - * rather than a <code>Seq[Node]</code>. If you don't know, call - * <code>trimProper</code> and account for the fact that you may get back - * an empty sequence of nodes. + * away. With this assumption, the function can return a `Node`, rather + * than a `Seq[Node]`. If you don't know, call `trimProper` and account + * for the fact that you may get back an empty sequence of nodes. * - * precondition: node is not a text node (it might be trimmed) + * Precondition: node is not a text node (it might be trimmed) */ def trim(x: Node): Node = x match { case Elem(pre, lab, md, scp, child@_*) => Elem(pre, lab, md, scp, (child flatMap trimProper):_*) } - /** trim a child of an element. <code>Attribute</code> values and - * <code>Atom</code> nodes that are not <code>Text</code> nodes are unaffected. + /** trim a child of an element. `Attribute` values and `Atom` nodes that + * are not `Text` nodes are unaffected. */ def trimProper(x:Node): Seq[Node] = x match { case Elem(pre,lab,md,scp,child@_*) => @@ -56,6 +55,7 @@ object Utility extends AnyRef with parsing.TokenTests { case _ => x } + /** returns a sorted attribute list */ def sort(md: MetaData): MetaData = if((md eq Null) || (md.next eq Null)) md else { val key = md.key @@ -64,11 +64,12 @@ object Utility extends AnyRef with parsing.TokenTests { smaller.append( Null ).append(md.copy ( greater )) } - /** returns the node with its attribute list sorted alphabetically (prefixes are ignored) */ + /** Return the node with its attribute list sorted alphabetically + * (prefixes are ignored) */ def sort(n:Node): Node = n match { - case Elem(pre,lab,md,scp,child@_*) => - Elem(pre,lab,sort(md),scp, (child map sort):_*) - case _ => n + case Elem(pre,lab,md,scp,child@_*) => + Elem(pre,lab,sort(md),scp, (child map sort):_*) + case _ => n } /** @@ -128,8 +129,8 @@ object Utility extends AnyRef with parsing.TokenTests { } /** - * Appends unescaped string to <code>s</code>, amp becomes & - * lt becomes < etc.. + * Appends unescaped string to `s`, `amp` becomes `&`, + * `lt` becomes `<` etc.. * * @param ref ... * @param s ... @@ -313,7 +314,7 @@ object Utility extends AnyRef with parsing.TokenTests { } /** - * Returns <code>null</code> if the value is a correct attribute value, + * Returns `'''null'''` if the value is a correct attribute value, * error message if it isn't. * * @param value ... @@ -395,13 +396,11 @@ object Utility extends AnyRef with parsing.TokenTests { } /** - * <pre> + * {{{ * CharRef ::= "&#" '0'..'9' {'0'..'9'} ";" * | "&#x" '0'..'9'|'A'..'F'|'a'..'f' { hexdigit } ";" - * </pre> - * <p> - * see [66] - * <p> + * }}} + * See [66] * * @param ch ... * @param nextch ... diff --git a/src/library/scala/xml/include/CircularIncludeException.scala b/src/library/scala/xml/include/CircularIncludeException.scala index 2b2d357f8f..0260f5adc6 100644 --- a/src/library/scala/xml/include/CircularIncludeException.scala +++ b/src/library/scala/xml/include/CircularIncludeException.scala @@ -6,23 +6,19 @@ ** |/ ** \* */ - package scala.xml package include /** - * <p> - * A <code>CircularIncludeException</code> is thrown when - * an included document attempts to include itself or - * one of its ancestor documents. - * </p> + * A `CircularIncludeException` is thrown when an included document attempts + * to include itself or one of its ancestor documents. */ class CircularIncludeException(message: String) extends XIncludeException { - /** - * Constructs a <code>CircularIncludeException</code> with <code>null</code> - * as its error detail message. - */ - def this() = this(null); + /** + * Constructs a `CircularIncludeException` with `'''null'''`. + * as its error detail message. + */ + def this() = this(null) } diff --git a/src/library/scala/xml/include/UnavailableResourceException.scala b/src/library/scala/xml/include/UnavailableResourceException.scala index e5115616dd..d3b66ad498 100644 --- a/src/library/scala/xml/include/UnavailableResourceException.scala +++ b/src/library/scala/xml/include/UnavailableResourceException.scala @@ -6,16 +6,12 @@ ** |/ ** \* */ - package scala.xml package include /** - * <p> - * An <code>UnavailableResourceException</code> is thrown when - * an included document cannot be found or loaded. - * </p> - * + * An `UnavailableResourceException` is thrown when an included document + * cannot be found or loaded. */ class UnavailableResourceException(message: String) extends XIncludeException(message) { diff --git a/src/library/scala/xml/include/sax/XIncludeFilter.scala b/src/library/scala/xml/include/sax/XIncludeFilter.scala index a572ff3a66..adcaf1738b 100644 --- a/src/library/scala/xml/include/sax/XIncludeFilter.scala +++ b/src/library/scala/xml/include/sax/XIncludeFilter.scala @@ -265,12 +265,8 @@ class XIncludeFilter extends XMLFilterImpl { locationString } - /** - * <p> - * This utility method reads a document at a specified URL - * and fires off calls to <code>characters()</code>. - * It's used to include files with <code>parse="text"</code> - * </p> + /** This utility method reads a document at a specified URL and fires off + * calls to `characters()`. It's used to include files with `parse="text"`. * * @param url URL of the document that will be read * @param encoding Encoding of the document; e.g. UTF-8, @@ -291,9 +287,9 @@ class XIncludeFilter extends XMLFilterImpl { catch { case e: MalformedURLException => val ex = new UnavailableResourceException("Unresolvable URL " + url - + getLocation()); - ex.setRootCause(e); - throw new SAXException("Unresolvable URL " + url + getLocation(), ex); + + getLocation()) + ex.setRootCause(e) + throw new SAXException("Unresolvable URL " + url + getLocation(), ex) } try { diff --git a/src/library/scala/xml/include/sax/XIncluder.scala b/src/library/scala/xml/include/sax/XIncluder.scala index b291a38164..f4d69ffe44 100644 --- a/src/library/scala/xml/include/sax/XIncluder.scala +++ b/src/library/scala/xml/include/sax/XIncluder.scala @@ -16,13 +16,10 @@ import org.xml.sax.{ ContentHandler, XMLReader, Locator, Attributes } import org.xml.sax.ext.LexicalHandler import java.io.{ File, OutputStream, OutputStreamWriter, Writer, IOException } -/** XIncluder is a SAX <code>ContentHandler</code> - * that writes its XML document onto an output stream after resolving - * all <code>xinclude:include</code> elements. +/** XIncluder is a SAX `ContentHandler` that writes its XML document onto + * an output stream after resolving all `xinclude:include` elements. * - * <p> - * based on Eliotte Rusty Harold's SAXXIncluder - * </p> + * Based on Eliotte Rusty Harold's SAXXIncluder. */ class XIncluder(outs: OutputStream, encoding: String) extends ContentHandler with LexicalHandler { @@ -100,7 +97,7 @@ class XIncluder(outs: OutputStream, encoding: String) extends ContentHandler wit // (The end CDATA section delimiter) else if (c == '>') out.write(">"); else out.write(c); - i = i+1; + i += 1 } } catch { diff --git a/src/library/scala/xml/parsing/ConstructingParser.scala b/src/library/scala/xml/parsing/ConstructingParser.scala index 8ea3fc839d..5571c9844d 100644 --- a/src/library/scala/xml/parsing/ConstructingParser.scala +++ b/src/library/scala/xml/parsing/ConstructingParser.scala @@ -36,7 +36,7 @@ object ConstructingParser { * val doc = cpa.document() * * // let's see what it is - * val ppr = new scala.xml.PrettyPrinter(80,5) + * val ppr = new scala.xml.PrettyPrinter(80, 5) * val ele = doc.docElem * println("finished parsing") * val out = ppr.format(ele) diff --git a/src/library/scala/xml/parsing/FactoryAdapter.scala b/src/library/scala/xml/parsing/FactoryAdapter.scala index 67e06ff5ca..5aad0e7ce1 100644 --- a/src/library/scala/xml/parsing/FactoryAdapter.scala +++ b/src/library/scala/xml/parsing/FactoryAdapter.scala @@ -49,7 +49,7 @@ abstract class FactoryAdapter extends DefaultHandler with factory.XMLLoader[Node // abstract methods /** Tests if an XML element contains text. - * @return true if element named <code>localName</code> contains text. + * @return true if element named `localName` contains text. */ def nodeContainsText(localName: String): Boolean // abstract diff --git a/src/library/scala/xml/parsing/MarkupParser.scala b/src/library/scala/xml/parsing/MarkupParser.scala index f6cdb1d679..39fb70904e 100644 --- a/src/library/scala/xml/parsing/MarkupParser.scala +++ b/src/library/scala/xml/parsing/MarkupParser.scala @@ -16,10 +16,9 @@ import Utility.Escapes.{ pairs => unescape } /** * An XML parser. * - * Parses XML 1.0, invokes callback methods of a MarkupHandler - * and returns whatever the markup handler returns. Use - * <code>ConstructingParser</code> if you just want to parse XML to - * construct instances of <code>scala.xml.Node</code>. + * Parses XML 1.0, invokes callback methods of a `MarkupHandler` and returns + * whatever the markup handler returns. Use `ConstructingParser` if you just + * want to parse XML to construct instances of `scala.xml.Node`. * * While XML elements are returned, DTD declarations - if handled - are * collected using side-effects. @@ -72,7 +71,8 @@ trait MarkupParser extends MarkupParserCommon with TokenTests } def lookahead(): BufferedIterator[Char] = curInput match { - case curInputWLA:WithLookAhead => curInputWLA.lookahead() + case curInputWLA:WithLookAhead => + curInputWLA.lookahead() case _ => val newInput = new WithLookAhead(curInput) curInput = newInput @@ -133,8 +133,9 @@ trait MarkupParser extends MarkupParserCommon with TokenTests // methods // - /** <? prolog ::= xml S ... ?> - */ + /** {{{ + * <? prolog ::= xml S ... ?> + * }}} */ def xmlProcInstr(): MetaData = { xToken("xml") xSpace @@ -160,14 +161,14 @@ trait MarkupParser extends MarkupParserCommon with TokenTests xSpaceOpt m("version") match { - case null => ; + case null => case Text("1.0") => info_ver = Some("1.0"); n += 1 case _ => reportSyntaxError("cannot deal with versions != 1.0") } m("encoding") match { - case null => ; - case Text(enc) => + case null => + case Text(enc) => if (!isValidIANAEncoding(enc)) reportSyntaxError("\"" + enc + "\" is not a valid encoding") else { @@ -178,7 +179,7 @@ trait MarkupParser extends MarkupParserCommon with TokenTests if (isProlog) { m("standalone") match { - case null => ; + case null => case Text("yes") => info_stdl = Some(true); n += 1 case Text("no") => info_stdl = Some(false); n += 1 case _ => reportSyntaxError("either 'yes' or 'no' expected") @@ -193,9 +194,10 @@ trait MarkupParser extends MarkupParserCommon with TokenTests (info_ver, info_enc, info_stdl) } - /** <? prolog ::= xml S? + /** {{{ + * <? prolog ::= xml S? * // this is a bit more lenient than necessary... - */ + * }}} */ def prolog(): (Option[String], Option[String], Option[Boolean]) = prologOrTextDecl(true) @@ -203,20 +205,19 @@ trait MarkupParser extends MarkupParserCommon with TokenTests def textDecl(): (Option[String], Option[String]) = prologOrTextDecl(false) match { case (x1, x2, _) => (x1, x2) } - /** - *[22] prolog ::= XMLDecl? Misc* (doctypedecl Misc*)? - *[23] XMLDecl ::= '<?xml' VersionInfo EncodingDecl? SDDecl? S? '?>' - *[24] VersionInfo ::= S 'version' Eq ("'" VersionNum "'" | '"' VersionNum '"') - *[25] Eq ::= S? '=' S? - *[26] VersionNum ::= '1.0' - *[27] Misc ::= Comment | PI | S - */ - + /** {{{ + * [22] prolog ::= XMLDecl? Misc* (doctypedecl Misc*)? + * [23] XMLDecl ::= '<?xml' VersionInfo EncodingDecl? SDDecl? S? '?>' + * [24] VersionInfo ::= S 'version' Eq ("'" VersionNum "'" | '"' VersionNum '"') + * [25] Eq ::= S? '=' S? + * [26] VersionNum ::= '1.0' + * [27] Misc ::= Comment | PI | S + * }}} */ def document(): Document = { doc = new Document() this.dtd = null - var info_prolog: Tuple3[Option[String], Option[String], Option[Boolean]] = Tuple3(None, None, None); + var info_prolog: (Option[String], Option[String], Option[Boolean]) = (None, None, None) if ('<' != ch) { reportSyntaxError("< expected") return null @@ -225,7 +226,7 @@ trait MarkupParser extends MarkupParserCommon with TokenTests nextch // is prolog ? var children: NodeSeq = null if ('?' == ch) { - nextch; + nextch info_prolog = prolog() doc.version = info_prolog._1 doc.encoding = info_prolog._2 @@ -234,25 +235,25 @@ trait MarkupParser extends MarkupParserCommon with TokenTests children = content(TopScope) // DTD handled as side effect } else { - val ts = new NodeBuffer(); - content1(TopScope, ts); // DTD handled as side effect - ts &+ content(TopScope); - children = NodeSeq.fromSeq(ts); - } - //Console.println("[MarkupParser::document] children now: "+children.toList); - var elemCount = 0; - var theNode: Node = null; + val ts = new NodeBuffer() + content1(TopScope, ts) // DTD handled as side effect + ts &+ content(TopScope) + children = NodeSeq.fromSeq(ts) + } + //println("[MarkupParser::document] children now: "+children.toList) + var elemCount = 0 + var theNode: Node = null for (c <- children) c match { - case _:ProcInstr => ; - case _:Comment => ; + case _:ProcInstr => + case _:Comment => case _:EntityRef => // todo: fix entities, shouldn't be "special" reportSyntaxError("no entity references allowed here"); case s:SpecialNode => if (s.toString().trim().length > 0) //non-empty text nodes not allowed - elemCount = elemCount + 2; + elemCount += 2 case m:Node => - elemCount = elemCount + 1; - theNode = m; + elemCount += 1 + theNode = m } if (1 != elemCount) { reportSyntaxError("document must contain exactly one element") @@ -293,9 +294,11 @@ trait MarkupParser extends MarkupParserCommon with TokenTests } /** parse attribute and create namespace scope, metadata + * {{{ * [41] Attributes ::= { S Name Eq AttValue } + * }}} */ - def xAttributes(pscope:NamespaceBinding): (MetaData,NamespaceBinding) = { + def xAttributes(pscope: NamespaceBinding): (MetaData, NamespaceBinding) = { var scope: NamespaceBinding = pscope var aMap: MetaData = Null while (isNameStart(ch)) { @@ -307,22 +310,22 @@ trait MarkupParser extends MarkupParserCommon with TokenTests Utility.prefix(qname) match { case Some("xmlns") => - val prefix = qname.substring(6 /*xmlns:*/ , qname.length); - scope = new NamespaceBinding(prefix, value, scope); + val prefix = qname.substring(6 /*xmlns:*/ , qname.length) + scope = new NamespaceBinding(prefix, value, scope) - case Some(prefix) => - val key = qname.substring(prefix.length+1, qname.length); - aMap = new PrefixedAttribute(prefix, key, Text(value), aMap); + case Some(prefix) => + val key = qname.substring(prefix.length+1, qname.length) + aMap = new PrefixedAttribute(prefix, key, Text(value), aMap) - case _ => + case _ => if( qname == "xmlns" ) - scope = new NamespaceBinding(null, value, scope); + scope = new NamespaceBinding(null, value, scope) else - aMap = new UnprefixedAttribute(qname, Text(value), aMap); + aMap = new UnprefixedAttribute(qname, Text(value), aMap) } if ((ch != '/') && (ch != '>') && ('?' != ch)) - xSpace; + xSpace } if(!aMap.wellformed(scope)) @@ -332,8 +335,10 @@ trait MarkupParser extends MarkupParserCommon with TokenTests } /** entity value, terminated by either ' or ". value may not contain <. + * {{{ * AttValue ::= `'` { _ } `'` * | `"` { _ } `"` + * }}} */ def xEntityValue(): String = { val endch = ch @@ -348,10 +353,11 @@ trait MarkupParser extends MarkupParserCommon with TokenTests str } - /** '<! CharData ::= [CDATA[ ( {char} - {char}"]]>"{char} ) ']]>' + /** {{{ + * '<! CharData ::= [CDATA[ ( {char} - {char}"]]>"{char} ) ']]>' * - * see [15] - */ + * see [15] + * }}} */ def xCharData: NodeSeq = { xToken("[CDATA[") def mkResult(pos: Int, s: String): NodeSeq = { @@ -361,10 +367,11 @@ trait MarkupParser extends MarkupParserCommon with TokenTests xTakeUntil(mkResult, () => pos, "]]>") } - /** Comment ::= '<!--' ((Char - '-') | ('-' (Char - '-')))* '-->' + /** {{{ + * Comment ::= '<!--' ((Char - '-') | ('-' (Char - '-')))* '-->' * * see [15] - */ + * }}} */ def xComment: NodeSeq = { val sb: StringBuilder = new StringBuilder() xToken("--") @@ -390,8 +397,10 @@ trait MarkupParser extends MarkupParserCommon with TokenTests } } - /** '<' content1 ::= ... */ - def content1(pscope: NamespaceBinding, ts: NodeBuffer): Unit = + /** {{{ + * '<' content1 ::= ... + * }}} */ + def content1(pscope: NamespaceBinding, ts: NodeBuffer) { ch match { case '!' => nextch @@ -407,8 +416,11 @@ trait MarkupParser extends MarkupParserCommon with TokenTests case _ => ts &+ element1(pscope) // child } + } - /** content1 ::= '<' content1 | '&' charref ... */ + /** {{{ + * content1 ::= '<' content1 | '&' charref ... + * }}} */ def content(pscope: NamespaceBinding): NodeSeq = { var ts = new NodeBuffer var exit = eof @@ -447,16 +459,16 @@ trait MarkupParser extends MarkupParserCommon with TokenTests } else push(n) } case _ => // text content - appendText(tmppos, ts, xText); + appendText(tmppos, ts, xText) } } done } // content(NamespaceBinding) - /** externalID ::= SYSTEM S syslit + /** {{{ + * externalID ::= SYSTEM S syslit * PUBLIC S pubid S syslit - */ - + * }}} */ def externalID(): ExternalID = ch match { case 'S' => nextch @@ -476,14 +488,13 @@ trait MarkupParser extends MarkupParserCommon with TokenTests /** parses document type declaration and assigns it to instance variable * dtd. - * + * {{{ * <! parseDTD ::= DOCTYPE name ... > - */ - def parseDTD(): Unit = { // dirty but fast - //Console.println("(DEBUG) parseDTD"); + * }}} */ + def parseDTD() { // dirty but fast var extID: ExternalID = null if (this.dtd ne null) - reportSyntaxError("unexpected character (DOCTYPE already defined"); + reportSyntaxError("unexpected character (DOCTYPE already defined") xToken("DOCTYPE") xSpace val n = xName @@ -532,9 +543,10 @@ trait MarkupParser extends MarkupParserCommon with TokenTests element1(pscope) } - /** '<' element ::= xmlTag1 '>' { xmlExpr | '{' simpleExpr '}' } ETag + /** {{{ + * '<' element ::= xmlTag1 '>' { xmlExpr | '{' simpleExpr '}' } ETag * | xmlTag1 '/' '>' - */ + * }}} */ def element1(pscope: NamespaceBinding): NodeSeq = { val pos = this.pos val (qname, (aMap, scope)) = xTag(pscope) @@ -561,8 +573,9 @@ trait MarkupParser extends MarkupParserCommon with TokenTests res } - /** parse character data. - * precondition: xEmbeddedBlock == false (we are not in a scala block) + /** Parse character data. + * + * precondition: `xEmbeddedBlock == false` (we are not in a scala block) */ def xText: String = { var exit = false; @@ -579,9 +592,10 @@ trait MarkupParser extends MarkupParserCommon with TokenTests } /** attribute value, terminated by either ' or ". value may not contain <. + * {{{ * AttValue ::= `'` { _ } `'` * | `"` { _ } `"` - */ + * }}} */ def systemLiteral(): String = { val endch = ch if (ch != '\'' && ch != '"') @@ -597,7 +611,9 @@ trait MarkupParser extends MarkupParserCommon with TokenTests str } - /* [12] PubidLiteral ::= '"' PubidChar* '"' | "'" (PubidChar - "'")* "'" */ + /** {{{ + * [12] PubidLiteral ::= '"' PubidChar* '"' | "'" (PubidChar - "'")* "'" + * }}} */ def pubidLiteral(): String = { val endch = ch if (ch!='\'' && ch != '"') @@ -605,9 +621,9 @@ trait MarkupParser extends MarkupParserCommon with TokenTests nextch while (ch != endch && !eof) { putChar(ch) - //Console.println("hello '"+ch+"'"+isPubIDChar(ch)); + //println("hello '"+ch+"'"+isPubIDChar(ch)) if (!isPubIDChar(ch)) - reportSyntaxError("char '"+ch+"' is not allowed in public id"); + reportSyntaxError("char '"+ch+"' is not allowed in public id") nextch } nextch @@ -621,10 +637,10 @@ trait MarkupParser extends MarkupParserCommon with TokenTests // def extSubset(): Unit = { - var textdecl:Tuple2[Option[String],Option[String]] = null; - if (ch=='<') { + var textdecl: (Option[String],Option[String]) = null + if (ch == '<') { nextch - if (ch=='?') { + if (ch == '?') { nextch textdecl = textDecl() } else @@ -683,8 +699,8 @@ trait MarkupParser extends MarkupParserCommon with TokenTests stmt match { // parameter entity - case "INCLUDE" => doInclude() - case "IGNORE" => doIgnore() + case "INCLUDE" => doInclude() + case "IGNORE" => doIgnore() } case 'I' => nextch @@ -760,8 +776,9 @@ trait MarkupParser extends MarkupParserCommon with TokenTests handle.elemDecl(n, cmstr) } - /** <! attlist := ATTLIST - */ + /** {{{ + * <! attlist := ATTLIST + * }}} */ def attrDecl() = { xToken("TTLIST") xSpace @@ -776,8 +793,8 @@ trait MarkupParser extends MarkupParserCommon with TokenTests // could be enumeration (foo,bar) parse this later :-/ while ('"' != ch && '\'' != ch && '#' != ch && '<' != ch) { if (!isSpace(ch)) - cbuf.append(ch); - nextch; + cbuf.append(ch) + nextch } val atpe = cbuf.toString() cbuf.length = 0 @@ -805,10 +822,10 @@ trait MarkupParser extends MarkupParserCommon with TokenTests handle.attListDecl(n, attList.reverse) } - /** <! element := ELEMENT - */ + /** {{{ + * <! element := ELEMENT + * }}} */ def entityDecl() = { - //Console.println("entityDecl()") var isParameterEntity = false var entdef: EntityDef = null xToken("NTITY") @@ -854,8 +871,9 @@ trait MarkupParser extends MarkupParserCommon with TokenTests {} } // entityDecl - /** 'N' notationDecl ::= "OTATION" - */ + /** {{{ + * 'N' notationDecl ::= "OTATION" + * }}} */ def notationDecl() { xToken("OTATION") xSpace @@ -885,9 +903,9 @@ trait MarkupParser extends MarkupParserCommon with TokenTests handle.notationDecl(notat, extID) } - def reportSyntaxError(pos: Int, str: String): Unit = curInput.reportError(pos, str) - def reportSyntaxError(str: String): Unit = reportSyntaxError(pos, str) - def reportValidationError(pos: Int, str: String): Unit = reportSyntaxError(pos, str) + def reportSyntaxError(pos: Int, str: String) { curInput.reportError(pos, str) } + def reportSyntaxError(str: String) { reportSyntaxError(pos, str) } + def reportValidationError(pos: Int, str: String) { reportSyntaxError(pos, str) } def push(entityName: String) { if (!eof) diff --git a/src/library/scala/xml/parsing/TokenTests.scala b/src/library/scala/xml/parsing/TokenTests.scala index 4cf0c640b3..d49aa418a0 100644 --- a/src/library/scala/xml/parsing/TokenTests.scala +++ b/src/library/scala/xml/parsing/TokenTests.scala @@ -1,13 +1,11 @@ /* __ *\ ** ________ ___ / / ___ Scala API ** ** / __/ __// _ | / / / _ | (c) 2003-2011, LAMP/EPFL ** -** __\ \/ /__/ __ |/ /__/ __ | ** +** __\ \/ /__/ __ |/ /__/ __ | http://scala-lang.org/ ** ** /____/\___/_/ |_/____/_/ | | ** ** |/ ** \* */ - - package scala.xml package parsing @@ -16,22 +14,27 @@ package parsing */ trait TokenTests { - /** (#x20 | #x9 | #xD | #xA) */ + /** {{{ + * (#x20 | #x9 | #xD | #xA) + * }}} */ final def isSpace(ch: Char): Boolean = ch match { case '\u0009' | '\u000A' | '\u000D' | '\u0020' => true case _ => false } - /** (#x20 | #x9 | #xD | #xA)+ */ + /** {{{ + * (#x20 | #x9 | #xD | #xA)+ + * }}} */ final def isSpace(cs: Seq[Char]): Boolean = cs.nonEmpty && (cs forall isSpace) /** These are 99% sure to be redundant but refactoring on the safe side. */ def isAlpha(c: Char) = (c >= 'A' && c <= 'Z') || (c >= 'a' && c <= 'z') def isAlphaDigit(c: Char) = isAlpha(c) || (c >= '0' && c <= '9') - /** NameChar ::= Letter | Digit | '.' | '-' | '_' | ':' + /** {{{ + * NameChar ::= Letter | Digit | '.' | '-' | '_' | ':' * | CombiningChar | Extender - * - * see [4] and Appendix B of XML 1.0 specification + * }}} + * See [4] and Appendix B of XML 1.0 specification. */ def isNameChar(ch: Char) = { import java.lang.Character._ @@ -40,17 +43,19 @@ trait TokenTests { isNameStart(ch) || (getType(ch).toByte match { case COMBINING_SPACING_MARK | ENCLOSING_MARK | NON_SPACING_MARK | - MODIFIER_LETTER | DECIMAL_DIGIT_NUMBER => true - case _ => ".-:" contains ch + MODIFIER_LETTER | DECIMAL_DIGIT_NUMBER => true + case _ => ".-:" contains ch }) } - /** NameStart ::= ( Letter | '_' ) + /** {{{ + * NameStart ::= ( Letter | '_' ) + * }}} * where Letter means in one of the Unicode general - * categories { Ll, Lu, Lo, Lt, Nl } + * categories `{ Ll, Lu, Lo, Lt, Nl }`. * - * We do not allow a name to start with ':'. - * see [3] and Appendix B of XML 1.0 specification + * We do not allow a name to start with `:`. + * See [3] and Appendix B of XML 1.0 specification */ def isNameStart(ch: Char) = { import java.lang.Character._ @@ -58,14 +63,15 @@ trait TokenTests { getType(ch).toByte match { case LOWERCASE_LETTER | UPPERCASE_LETTER | OTHER_LETTER | - TITLECASE_LETTER | LETTER_NUMBER => true - case _ => ch == '_' + TITLECASE_LETTER | LETTER_NUMBER => true + case _ => ch == '_' } } - /** Name ::= ( Letter | '_' ) (NameChar)* - * - * see [5] of XML 1.0 specification + /** {{{ + * Name ::= ( Letter | '_' ) (NameChar)* + * }}} + * See [5] of XML 1.0 specification. */ def isName(s: String) = s.nonEmpty && isNameStart(s.head) && (s.tail forall isNameChar) @@ -75,7 +81,7 @@ trait TokenTests { ("""-\()+,./:=?;!*#@$_%""" contains ch) /** - * Returns true if the encoding name is a valid IANA encoding. + * Returns `true` if the encoding name is a valid IANA encoding. * This method does not verify that there is a decoder available * for this encoding, only that the characters are valid for an * IANA encoding name. diff --git a/src/library/scala/xml/parsing/XhtmlEntities.scala b/src/library/scala/xml/parsing/XhtmlEntities.scala index 8ab229affd..53a4a32613 100644 --- a/src/library/scala/xml/parsing/XhtmlEntities.scala +++ b/src/library/scala/xml/parsing/XhtmlEntities.scala @@ -6,15 +6,14 @@ ** |/ ** \* */ - package scala.xml package parsing import scala.xml.dtd.{ IntDef, ParsedEntityDecl } -/** <p> - * (c) David Pollak 2007 WorldWide Conferencing, LLC. - * </p> +/** + * @author (c) David Pollak 2007 WorldWide Conferencing, LLC. + * */ object XhtmlEntities { val entList = List(("quot",34), ("amp",38), ("lt",60), ("gt",62), ("nbsp",160), ("iexcl",161), ("cent",162), ("pound",163), ("curren",164), ("yen",165), diff --git a/src/library/scala/xml/parsing/XhtmlParser.scala b/src/library/scala/xml/parsing/XhtmlParser.scala index fb61376321..de9a3f2243 100644 --- a/src/library/scala/xml/parsing/XhtmlParser.scala +++ b/src/library/scala/xml/parsing/XhtmlParser.scala @@ -6,30 +6,24 @@ ** |/ ** \* */ - package scala.xml package parsing import scala.io.Source -/** <p> - * An XML Parser that preserves CDATA blocks and knows about HtmlEntities. - * </p> - * <p> - * (c) David Pollak, 2007 WorldWide Conferencing, LLC. - * </p> +/** An XML Parser that preserves `CDATA` blocks and knows about + * [[scala.xml.parsing.HtmlEntities]]. + * + * @author (c) David Pollak, 2007 WorldWide Conferencing, LLC. */ class XhtmlParser(val input: Source) extends ConstructingHandler with MarkupParser with ExternalSources { val preserveWS = true ent ++= XhtmlEntities() } -/** <p> - * Convenience method that instantiates, initializes and runs an XhtmlParser. - * </p> - * <p> - * (c) Burak Emir - * </p> +/** Convenience method that instantiates, initializes and runs an `XhtmlParser`. + * + * @author Burak Emir */ object XhtmlParser { def apply(source: Source): NodeSeq = new XhtmlParser(source).initialize.document diff --git a/src/library/scala/xml/persistent/CachedFileStorage.scala b/src/library/scala/xml/persistent/CachedFileStorage.scala index bcdd1a3f2d..68a475ae90 100644 --- a/src/library/scala/xml/persistent/CachedFileStorage.scala +++ b/src/library/scala/xml/persistent/CachedFileStorage.scala @@ -6,7 +6,6 @@ ** |/ ** \* */ - package scala.xml package persistent @@ -17,13 +16,12 @@ import java.lang.Thread import scala.util.logging.Logged import scala.collection.Iterator -/** <p> - * Mutable storage of immutable xml trees. Everything is kept in memory, - * with a thread periodically checking for changes and writing to file. - * To ensure atomicity, two files are used, filename1 and '$'+filename1. - * The implementation switches between the two, deleting the older one - * after a complete dump of the database has been written. - * </p> +/** Mutable storage of immutable xml trees. Everything is kept in memory, + * with a thread periodically checking for changes and writing to file. + * + * To ensure atomicity, two files are used, `filename1` and `'$'+filename1`. + * The implementation switches between the two, deleting the older one + * after a complete dump of the database has been written. * * @author Burak Emir */ @@ -31,7 +29,8 @@ abstract class CachedFileStorage(private val file1: File) extends Thread with Lo private val file2 = new File(file1.getParent, file1.getName+"$") - /** either equals file1 or file2, references the next file in which updates will be stored + /** Either equals `file1` or `file2`, references the next file in which + * updates will be stored. */ private var theFile: File = null @@ -85,10 +84,10 @@ abstract class CachedFileStorage(private val file1: File) extends Thread with Lo /** saves the XML to file */ private def save() = if (this.dirty) { - log("[save]\ndeleting "+theFile); - theFile.delete(); - log("creating new "+theFile); - theFile.createNewFile(); + log("[save]\ndeleting "+theFile) + theFile.delete() + log("creating new "+theFile) + theFile.createNewFile() val fos = new FileOutputStream(theFile) val c = fos.getChannel() @@ -97,7 +96,7 @@ abstract class CachedFileStorage(private val file1: File) extends Thread with Lo val w = Channels.newWriter(c, "utf-8") XML.write(w, storageNode, "utf-8", true, null) - log("writing to "+theFile); + log("writing to "+theFile) w.close c.close @@ -107,19 +106,20 @@ abstract class CachedFileStorage(private val file1: File) extends Thread with Lo log("[save done]") } - /** run method of the thread. remember to use start() to start a thread, not run. */ + /** Run method of the thread. remember to use `start()` to start a thread, + * not `run`. */ override def run = { - log("[run]\nstarting storage thread, checking every "+interval+" ms"); - while(true) { - Thread.sleep( this.interval ); + log("[run]\nstarting storage thread, checking every "+interval+" ms") + while (true) { + Thread.sleep( this.interval ) save } } - /** forces writing of contents to the file, even if there has not been any update. */ + /** Force writing of contents to the file, even if there has not been any + * update. */ def flush() = { - this.dirty = true; + this.dirty = true save } } - |