From f31eaf606f2f1f524621dacd280abfccb9110f59 Mon Sep 17 00:00:00 2001
From: Antonio Cunei
- * This method never returns. Therefore, the rest of the computation
- * has to be contained in the actions of the partial function.
- *
- * @param f a partial function with message patterns and actions
- */
def react(f: PartialFunction[Msg, Unit]): Nothing = {
val C = this.asInstanceOf[Channel[Any]]
receiver.react {
@@ -121,16 +83,6 @@ class Channel[Msg](val receiver: Actor) extends InputChannel[Msg] with OutputCha
}
}
- /**
- * Receives a message from this
- * This method never returns. Therefore, the rest of the computation
- * has to be contained in the actions of the partial function.
- *
- * @param msec the time span before timeout
- * @param f a partial function with message patterns and actions
- */
def reactWithin(msec: Long)(f: PartialFunction[Any, Unit]): Nothing = {
val C = this.asInstanceOf[Channel[Any]]
val recvActor = receiver.asInstanceOf[Actor]
@@ -140,13 +92,6 @@ class Channel[Msg](val receiver: Actor) extends InputChannel[Msg] with OutputCha
}
}
- /**
- * Sends a message to this
+ * Receives a message from this $channel.
+ *
* This method never returns. Therefore, the rest of the computation
* has to be contained in the actions of the partial function.
*
@@ -47,9 +49,9 @@ trait InputChannel[+Msg] {
def react(f: PartialFunction[Msg, Unit]): Nothing
/**
- * Receives a message from this
+ *
* This method never returns. Therefore, the rest of the computation
* has to be contained in the actions of the partial function.
*
@@ -59,7 +61,7 @@ trait InputChannel[+Msg] {
def reactWithin(msec: Long)(f: PartialFunction[Any, Unit]): Nothing
/**
- * Receives the next message from this
+ * Receives a message from this $actor's mailbox.
+ *
* This method never returns. Therefore, the rest of the computation
* has to be contained in the actions of the partial function.
*
@@ -208,7 +202,7 @@ trait Reactor[Msg >: Null] extends OutputChannel[Msg] with Combinators {
}
/* This method is guaranteed to be executed from inside
- * an actors act method.
+ * an $actor's act method.
*
* assume handler != null
*
@@ -218,6 +212,9 @@ trait Reactor[Msg >: Null] extends OutputChannel[Msg] with Combinators {
scheduler executeFromActor makeReaction(null, handler, msg)
}
+ /**
+ * Starts this $actor.
+ */
def start(): Reactor[Msg] = synchronized {
if (_state == Actor.State.New) {
_state = Actor.State.Runnable
@@ -228,7 +225,7 @@ trait Reactor[Msg >: Null] extends OutputChannel[Msg] with Combinators {
this
}
- /** Returns the execution state of this actor.
+ /** Returns the execution state of this $actor.
*
* @return the execution state
*/
diff --git a/src/actors/scala/actors/ReactorCanReply.scala b/src/actors/scala/actors/ReactorCanReply.scala
index c53e3a78e1..9002a55b87 100644
--- a/src/actors/scala/actors/ReactorCanReply.scala
+++ b/src/actors/scala/actors/ReactorCanReply.scala
@@ -19,25 +19,9 @@ package scala.actors
private[actors] trait ReactorCanReply extends CanReply[Any, Any] {
_: ReplyReactor =>
- /**
- * Sends
+ *
* This method never returns. Therefore, the rest of the computation
* has to be contained in the actions of the partial function.
*
diff --git a/src/actors/scala/actors/scheduler/ForkJoinScheduler.scala b/src/actors/scala/actors/scheduler/ForkJoinScheduler.scala
index ab4fca04ca..4aaef16661 100644
--- a/src/actors/scala/actors/scheduler/ForkJoinScheduler.scala
+++ b/src/actors/scala/actors/scheduler/ForkJoinScheduler.scala
@@ -3,7 +3,6 @@ package scheduler
import java.util.{Collection, ArrayList}
import scala.concurrent.forkjoin._
-import scala.util.Random
/** The
- * A base class for views of
- * A template trait for views of AbstractActor
trait.
*
* @author Philipp Haller
+ *
+ * @define actor actor
*/
trait AbstractActor extends OutputChannel[Any] with CanReply[Any, Any] {
diff --git a/src/actors/scala/actors/Actor.scala b/src/actors/scala/actors/Actor.scala
index 491c1eb075..ccd60f666c 100644
--- a/src/actors/scala/actors/Actor.scala
+++ b/src/actors/scala/actors/Actor.scala
@@ -382,9 +382,12 @@ object Actor extends Combinators {
*
*
* @author Philipp Haller
+ *
+ * @define actor actor
+ * @define channel actor's mailbox
*/
@serializable @SerialVersionUID(-781154067877019505L)
-trait Actor extends AbstractActor with ReplyReactor with ActorCanReply {
+trait Actor extends AbstractActor with ReplyReactor with ActorCanReply with InputChannel[Any] {
/* The following two fields are only used when the actor
* suspends by blocking its underlying thread, for example,
@@ -413,12 +416,6 @@ trait Actor extends AbstractActor with ReplyReactor with ActorCanReply {
private[actors] override def makeReaction(fun: () => Unit, handler: PartialFunction[Any, Any], msg: Any): Runnable =
new ActorTask(this, fun, handler, msg)
- /**
- * Receives a message from this actor's mailbox.
- *
- * @param f a partial function with message patterns and actions
- * @return result of processing the received value
- */
def receive[R](f: PartialFunction[Any, R]): R = {
assert(Actor.self(scheduler) == this, "receive from channel belonging to other actor")
@@ -462,14 +459,6 @@ trait Actor extends AbstractActor with ReplyReactor with ActorCanReply {
result
}
- /**
- * Receives a message from this actor's mailbox within a certain
- * time span.
- *
- * @param msec the time span before timeout
- * @param f a partial function with message patterns and actions
- * @return result of processing the received value
- */
def receiveWithin[R](msec: Long)(f: PartialFunction[Any, R]): R = {
assert(Actor.self(scheduler) == this, "receive from channel belonging to other actor")
@@ -556,9 +545,6 @@ trait Actor extends AbstractActor with ReplyReactor with ActorCanReply {
super.reactWithin(msec)(handler)
}
- /**
- * Receives the next message from this actor's mailbox.
- */
def ? : Any = receive {
case x => x
}
@@ -605,9 +591,6 @@ trait Actor extends AbstractActor with ReplyReactor with ActorCanReply {
_state == Actor.State.Terminated
}
- /**
- * Starts this actor.
- */
override def start(): Actor = synchronized {
if (_state == Actor.State.New) {
_state = Actor.State.Runnable
diff --git a/src/actors/scala/actors/ActorCanReply.scala b/src/actors/scala/actors/ActorCanReply.scala
index 8cba425b4c..fdc3833ec4 100644
--- a/src/actors/scala/actors/ActorCanReply.scala
+++ b/src/actors/scala/actors/ActorCanReply.scala
@@ -13,7 +13,7 @@ package scala.actors
import java.util.concurrent.ExecutionException
/**
- * The ActorCanReply trait provides message send operations that
+ * The `ActorCanReply` trait provides message send operations that
* may result in a response from the receiver.
*
* @author Philipp Haller
@@ -21,13 +21,6 @@ import java.util.concurrent.ExecutionException
private[actors] trait ActorCanReply extends ReactorCanReply {
thiz: AbstractActor with ReplyReactor =>
- /**
- * Sends msg
to this actor and awaits reply
- * (synchronous).
- *
- * @param msg the message to be sent
- * @return the reply
- */
override def !?(msg: Any): Any = {
val replyCh = new Channel[Any](Actor.self(thiz.scheduler))
thiz.send(msg, replyCh)
@@ -36,15 +29,6 @@ private[actors] trait ActorCanReply extends ReactorCanReply {
}
}
- /**
- * Sends msg
to this actor and awaits reply
- * (synchronous) within msec
milliseconds.
- *
- * @param msec the time span before timeout
- * @param msg the message to be sent
- * @return None
in case of timeout, otherwise
- * Some(x)
where x
is the reply
- */
override def !?(msec: Long, msg: Any): Option[Any] = {
val replyCh = new Channel[Any](Actor.self(thiz.scheduler))
thiz.send(msg, replyCh)
@@ -54,13 +38,6 @@ private[actors] trait ActorCanReply extends ReactorCanReply {
}
}
- /**
- * Sends msg
to this actor and immediately
- * returns a future representing the reply value.
- * The reply is post-processed using the partial function
- * handler
. This also allows to recover a more
- * precise type for the reply value.
- */
override def !![A](msg: Any, handler: PartialFunction[Any, A]): Future[A] = {
val ftch = new Channel[A](Actor.self(thiz.scheduler))
thiz.send(msg, new OutputChannel[Any] {
@@ -76,10 +53,6 @@ private[actors] trait ActorCanReply extends ReactorCanReply {
Futures.fromInputChannel(ftch)
}
- /**
- * Sends msg
to this actor and immediately
- * returns a future representing the reply value.
- */
override def !!(msg: Any): Future[Any] = {
val ftch = new Channel[Any](Actor.self(thiz.scheduler))
val linkedChannel = new AbstractActor {
diff --git a/src/actors/scala/actors/CanReply.scala b/src/actors/scala/actors/CanReply.scala
index 23f0a5319b..99e1169900 100644
--- a/src/actors/scala/actors/CanReply.scala
+++ b/src/actors/scala/actors/CanReply.scala
@@ -14,11 +14,13 @@ package scala.actors
* The CanReply
trait defines result-bearing message send operations.
*
* @author Philipp Haller
+ *
+ * @define actor `CanReply`
*/
trait CanReply[-T, +R] {
/**
- * Sends msg
to this CanReply
and
+ * Sends msg
to this $actor and
* awaits reply (synchronous).
*
* @param msg the message to be sent
@@ -27,7 +29,7 @@ trait CanReply[-T, +R] {
def !?(msg: T): R
/**
- * Sends msg
to this CanReply
and
+ * Sends msg
to this $actor and
* awaits reply (synchronous) within msec
* milliseconds.
*
@@ -39,7 +41,7 @@ trait CanReply[-T, +R] {
def !?(msec: Long, msg: T): Option[R]
/**
- * Sends msg
to this CanReply
and
+ * Sends msg
to this $actor and
* immediately returns a future representing the reply value.
*
* @param msg the message to be sent
@@ -49,7 +51,7 @@ trait CanReply[-T, +R] {
() => this !? msg
/**
- * Sends msg
to this CanReply
and
+ * Sends msg
to this $actor and
* immediately returns a future representing the reply value.
* The reply is post-processed using the partial function
* handler
. This also allows to recover a more
diff --git a/src/actors/scala/actors/Channel.scala b/src/actors/scala/actors/Channel.scala
index 4c37de7665..e40a804e4a 100644
--- a/src/actors/scala/actors/Channel.scala
+++ b/src/actors/scala/actors/Channel.scala
@@ -35,45 +35,26 @@ case class ! [a](ch: Channel[a], msg: a)
* Channel
may receive from it.
*
* @author Philipp Haller
+ *
+ * @define actor channel
+ * @define channel channel
*/
-class Channel[Msg](val receiver: Actor) extends InputChannel[Msg] with OutputChannel[Msg] {
+class Channel[Msg](val receiver: Actor) extends InputChannel[Msg] with OutputChannel[Msg] with CanReply[Msg, Any] {
def this() = this(Actor.self)
- /**
- * Sends a message to this Channel
.
- *
- * @param msg the message to be sent
- */
def !(msg: Msg) {
receiver ! scala.actors.!(this, msg)
}
- /**
- * Sends a message to this Channel
- * (asynchronous) supplying explicit reply destination.
- *
- * @param msg the message to send
- * @param replyTo the reply destination
- */
def send(msg: Msg, replyTo: OutputChannel[Any]) {
receiver.send(scala.actors.!(this, msg), replyTo)
}
- /**
- * Forwards msg
to this
keeping the
- * last sender as sender instead of self
.
- */
def forward(msg: Msg) {
receiver forward scala.actors.!(this, msg)
}
- /**
- * Receives a message from this Channel
.
- *
- * @param f a partial function with message patterns and actions
- * @return result of processing the received value
- */
def receive[R](f: PartialFunction[Msg, R]): R = {
val C = this.asInstanceOf[Channel[Any]]
val recvActor = receiver.asInstanceOf[Actor]
@@ -82,21 +63,10 @@ class Channel[Msg](val receiver: Actor) extends InputChannel[Msg] with OutputCha
}
}
- /**
- * Receives the next message from this Channel
.
- */
def ? : Msg = receive {
case x => x
}
- /**
- * Receives a message from this Channel
within a certain
- * time span.
- *
- * @param msec the time span before timeout
- * @param f a partial function with message patterns and actions
- * @return result of processing the received value
- */
def receiveWithin[R](msec: Long)(f: PartialFunction[Any, R]): R = {
val C = this.asInstanceOf[Channel[Any]]
val recvActor = receiver.asInstanceOf[Actor]
@@ -106,14 +76,6 @@ class Channel[Msg](val receiver: Actor) extends InputChannel[Msg] with OutputCha
}
}
- /**
- * Receives a message from this Channel
.
- * Channel
within a certain
- * time span.
- * Channel
and
- * awaits reply.
- *
- * @param msg the message to be sent
- * @return the reply
- */
def !?(msg: Msg): Any = {
val replyCh = new Channel[Any](Actor.self(receiver.scheduler))
receiver.send(scala.actors.!(this, msg), replyCh)
@@ -155,15 +100,6 @@ class Channel[Msg](val receiver: Actor) extends InputChannel[Msg] with OutputCha
}
}
- /**
- * Sends a message to this Channel
and
- * awaits reply within a certain time span.
- *
- * @param msec the time span before timeout
- * @param msg the message to be sent
- * @return None
in case of timeout, otherwise
- * Some(x)
where x
is the reply
- */
def !?(msec: Long, msg: Msg): Option[Any] = {
val replyCh = new Channel[Any](Actor.self(receiver.scheduler))
receiver.send(scala.actors.!(this, msg), replyCh)
diff --git a/src/actors/scala/actors/Combinators.scala b/src/actors/scala/actors/Combinators.scala
index 3c0be7ed15..6082f92323 100644
--- a/src/actors/scala/actors/Combinators.scala
+++ b/src/actors/scala/actors/Combinators.scala
@@ -12,28 +12,35 @@ package scala.actors
private[actors] trait Combinators {
+ /**
+ * Enables the composition of suspendable closures using `andThen`,
+ * `loop`, `loopWhile`, etc.
+ */
implicit def mkBody[a](body: => a): Actor.Body[a]
/**
- * Causes self
to repeatedly execute
- * body
.
+ * Repeatedly executes `body`.
*
- * @param body the code block to be executed
+ * @param body the block to be executed
*/
def loop(body: => Unit): Unit = body andThen loop(body)
/**
- * Causes self
to repeatedly execute
- * body
while the condition
- * cond
is true
.
+ * Repeatedly executes `body` while the condition `cond` is `true`.
*
* @param cond the condition to test
- * @param body the code block to be executed
+ * @param body the block to be executed
*/
def loopWhile(cond: => Boolean)(body: => Unit): Unit =
if (cond) { body andThen loopWhile(cond)(body) }
else continue
+ /**
+ * Continues with the execution of the closure registered as
+ * continuation following `andThen`. Continues with the execution
+ * of the next loop iteration when invoked inside the body of `loop`
+ * or `loopWhile`.
+ */
def continue: Unit = throw new KillActorControl
}
diff --git a/src/actors/scala/actors/InputChannel.scala b/src/actors/scala/actors/InputChannel.scala
index fa2fad43c6..dfe26b3462 100644
--- a/src/actors/scala/actors/InputChannel.scala
+++ b/src/actors/scala/actors/InputChannel.scala
@@ -15,11 +15,13 @@ package scala.actors
* for all channels from which values can be received.
*
* @author Philipp Haller
+ *
+ * @define channel `InputChannel`
*/
trait InputChannel[+Msg] {
/**
- * Receives a message from this InputChannel
.
+ * Receives a message from this $channel.
*
* @param f a partial function with message patterns and actions
* @return result of processing the received value
@@ -27,7 +29,7 @@ trait InputChannel[+Msg] {
def receive[R](f: PartialFunction[Msg, R]): R
/**
- * Receives a message from this InputChannel
within
+ * Receives a message from this $channel within
* a certain time span.
*
* @param msec the time span before timeout
@@ -37,8 +39,8 @@ trait InputChannel[+Msg] {
def receiveWithin[R](msec: Long)(f: PartialFunction[Any, R]): R
/**
- * Receives a message from this InputChannel
.
- * InputChannel
within
+ * Receives a message from this $channel within
* a certain time span.
- * Channel
.
+ * Receives the next message from this $channel.
*/
def ? : Msg
}
diff --git a/src/actors/scala/actors/OutputChannel.scala b/src/actors/scala/actors/OutputChannel.scala
index 514c445944..8bf92b448e 100644
--- a/src/actors/scala/actors/OutputChannel.scala
+++ b/src/actors/scala/actors/OutputChannel.scala
@@ -15,18 +15,18 @@ package scala.actors
* for all channels to which values can be sent.
*
* @author Philipp Haller
+ *
+ * @define actor `OutputChannel`
*/
trait OutputChannel[-Msg] extends AbstractReactor[Msg] {
/**
- * Sends msg
to this
- * OutputChannel
(asynchronous).
+ * Sends msg
to this $actor (asynchronous).
*/
def !(msg: Msg): Unit
/**
- * Sends msg
to this
- * OutputChannel
(asynchronous) supplying
+ * Sends msg
to this $actor (asynchronous) supplying
* explicit reply destination.
*
* @param msg the message to send
@@ -35,14 +35,12 @@ trait OutputChannel[-Msg] extends AbstractReactor[Msg] {
def send(msg: Msg, replyTo: OutputChannel[Any]): Unit
/**
- * Forwards msg
to this
- * OutputChannel
(asynchronous).
+ * Forwards msg
to this $actor (asynchronous).
*/
def forward(msg: Msg): Unit
/**
- * Returns the Actor
that is
- * receiving from this OutputChannel
.
+ * Returns the Actor
that is receiving from this $actor.
*/
def receiver: Actor
}
diff --git a/src/actors/scala/actors/Reactor.scala b/src/actors/scala/actors/Reactor.scala
index db43921056..a5bdcf1dd9 100644
--- a/src/actors/scala/actors/Reactor.scala
+++ b/src/actors/scala/actors/Reactor.scala
@@ -50,23 +50,25 @@ private[actors] object Reactor {
* The Reactor trait provides lightweight actors.
*
* @author Philipp Haller
+ *
+ * @define actor reactor
*/
trait Reactor[Msg >: Null] extends OutputChannel[Msg] with Combinators {
- /* The actor's mailbox. */
+ /* The $actor's mailbox. */
private[actors] val mailbox = new MQueue[Msg]("Reactor")
// guarded by this
private[actors] val sendBuffer = new MQueue[Msg]("SendBuffer")
- /* Whenever this actor executes on some thread, `waitingFor` is
+ /* Whenever this $actor executes on some thread, `waitingFor` is
* guaranteed to be equal to `Reactor.waitingForNone`.
*
* In other words, whenever `waitingFor` is not equal to
- * `Reactor.waitingForNone`, this actor is guaranteed not to execute
+ * `Reactor.waitingForNone`, this $actor is guaranteed not to execute
* on some thread.
*
- * If the actor waits in a `react`, `waitingFor` holds the
+ * If the $actor waits in a `react`, `waitingFor` holds the
* message handler that `react` was called with.
*
* guarded by this
@@ -78,8 +80,7 @@ trait Reactor[Msg >: Null] extends OutputChannel[Msg] with Combinators {
private[actors] var _state: Actor.State.Value = Actor.State.New
/**
- * The behavior of a Reactor
is specified by implementing
- * this method.
+ * The $actor's behavior is specified by implementing this method.
*/
def act(): Unit
@@ -92,13 +93,6 @@ trait Reactor[Msg >: Null] extends OutputChannel[Msg] with Combinators {
protected[actors] def mailboxSize: Int =
mailbox.size
- /**
- * Sends msg
to this actor (asynchronous) supplying
- * explicit reply destination.
- *
- * @param msg the message to send
- * @param replyTo the reply destination
- */
def send(msg: Msg, replyTo: OutputChannel[Any]) {
val todo = synchronized {
if (waitingFor ne Reactor.waitingForNone) {
@@ -194,8 +188,8 @@ trait Reactor[Msg >: Null] extends OutputChannel[Msg] with Combinators {
}
/**
- * Receives a message from this actor's mailbox.
- * msg
to this actor and awaits reply
- * (synchronous).
- *
- * @param msg the message to be sent
- * @return the reply
- */
def !?(msg: Any): Any =
(this !! msg)()
- /**
- * Sends msg
to this actor and awaits reply
- * (synchronous) within msec
milliseconds.
- *
- * @param msec the time span before timeout
- * @param msg the message to be sent
- * @return None
in case of timeout, otherwise
- * Some(x)
where x
is the reply
- */
def !?(msec: Long, msg: Any): Option[Any] = {
val myself = Actor.rawSelf(this.scheduler)
val res = new scala.concurrent.SyncVar[Any]
@@ -55,20 +39,9 @@ private[actors] trait ReactorCanReply extends CanReply[Any, Any] {
res.get(msec)
}
- /**
- * Sends msg
to this actor and immediately
- * returns a future representing the reply value.
- */
override def !!(msg: Any): Future[Any] =
this !! (msg, { case x => x })
- /**
- * Sends msg
to this actor and immediately
- * returns a future representing the reply value.
- * The reply is post-processed using the partial function
- * handler
. This also allows to recover a more
- * precise type for the reply value.
- */
override def !![A](msg: Any, handler: PartialFunction[Any, A]): Future[A] = {
val myself = Actor.rawSelf(this.scheduler)
val ftch = new ReactChannel[A](myself)
diff --git a/src/actors/scala/actors/ReplyReactor.scala b/src/actors/scala/actors/ReplyReactor.scala
index 26057ab9cb..665ed3091f 100644
--- a/src/actors/scala/actors/ReplyReactor.scala
+++ b/src/actors/scala/actors/ReplyReactor.scala
@@ -20,6 +20,8 @@ import java.util.{Timer, TimerTask}
* msg
to this actor (asynchronous).
- */
override def !(msg: Any) {
send(msg, Actor.rawSelf(scheduler))
}
- /**
- * Forwards msg
to this actor (asynchronous).
- */
override def forward(msg: Any) {
send(msg, Actor.sender)
}
@@ -115,9 +111,9 @@ trait ReplyReactor extends Reactor[Any] with ReactorCanReply {
}
/**
- * Receives a message from this actor's mailbox within a certain
+ * Receives a message from this $actor's mailbox within a certain
* time span.
- * ForkJoinScheduler
is backed by a lightweight
* fork-join task execution framework.
@@ -23,12 +22,19 @@ class ForkJoinScheduler(val initCoreSize: Int, val maxSize: Int, daemon: Boolean
protected val CHECK_FREQ = 10
+ // this random number generator is only used in fair mode
+ private lazy val random = new java.util.Random // guarded by random
+
+ def this(d: Boolean, f: Boolean) {
+ this(ThreadPoolConfig.corePoolSize, ThreadPoolConfig.maxPoolSize, d, f)
+ }
+
def this(d: Boolean) {
- this(ThreadPoolConfig.corePoolSize, ThreadPoolConfig.maxPoolSize, d, true)
+ this(d, true) // default is fair
}
def this() {
- this(false)
+ this(false) // default is non-daemon
}
private def makeNewPool(): DrainableForkJoinPool = {
@@ -109,7 +115,7 @@ class ForkJoinScheduler(val initCoreSize: Int, val maxSize: Int, daemon: Boolean
override def executeFromActor(task: Runnable) {
// in fair mode: 2% chance of submitting to global task queue
- if (fair && Random.nextInt(50) == 1)
+ if (fair && random.synchronized { random.nextInt(50) == 1 })
pool.execute(task)
else
task.asInstanceOf[RecursiveAction].fork()
diff --git a/src/build/pack.xml b/src/build/pack.xml
index 5c5c8fbd8d..fa6c4ade20 100644
--- a/src/build/pack.xml
+++ b/src/build/pack.xml
@@ -102,6 +102,8 @@ MAIN DISTRIBUTION SBAZ
dir="${dist.dir}/bin"
includes="scala,scala.bat,scalac,scalac.bat,scaladoc,scaladoc.bat,fsc,fsc.bat"/>
A
.
+/** A template trait for sequences of type `Seq[A]`
* $seqInfo
*
- * @tparam A the element type of the collection
- * @tparam Repr the type of the actual collection containing the elements.
- *
* @define seqInfo
* Sequences are special cases of iterable collections of class `Iterable`.
* Unlike iterables, sequences always have a defined order of elements.
@@ -121,11 +117,14 @@ object SeqLike {
* Sequences can be accessed in reverse order of their elements, using methods
* `reverse` and `reverseIterator`.
*
- * Sequences have two principle subtraits, `IndexedSeq` and `LinearSeq`, which give different guarantees for performance.
+ * Sequences have two principal subtraits, `IndexedSeq` and `LinearSeq`, which give different guarantees for performance.
* An `IndexedSeq` provides fast random-access of elements and a fast `length` operation.
* A `LinearSeq` provides fast access only to the first element via `head`, but also
* has a fast `tail` operation.
*
+ * @tparam A the element type of the collection
+ * @tparam Repr the type of the actual collection containing the elements.
+ *
* @author Martin Odersky
* @author Matthias Zenger
* @version 1.0, 16/07/2003
diff --git a/src/library/scala/collection/SeqView.scala b/src/library/scala/collection/SeqView.scala
index 79d50f1de6..9a0025bd81 100644
--- a/src/library/scala/collection/SeqView.scala
+++ b/src/library/scala/collection/SeqView.scala
@@ -22,6 +22,8 @@ import TraversableView.NoBuilder
trait SeqView[+A, +Coll] extends SeqViewLike[A, Coll, SeqView[A, Coll]]
/** $factoryInfo
+ * @define coll sequence view
+ * @define Coll SeqView
*/
object SeqView {
type Coll = TraversableView[_, C] forSome {type C <: Traversable[_]}
diff --git a/src/library/scala/collection/Traversable.scala b/src/library/scala/collection/Traversable.scala
index 1cecec5227..4a1cd01af1 100644
--- a/src/library/scala/collection/Traversable.scala
+++ b/src/library/scala/collection/Traversable.scala
@@ -15,10 +15,8 @@ import generic._
import mutable.{Builder, Buffer, ArrayBuffer, ListBuffer}
import scala.util.control.Breaks
-/** A template trait for traversable collections.
- * $traversableinfo
- *
- * @tparam A The element type of the collection
+/** A trait for traversable collections.
+ * $traversableInfo
*/
trait Traversable[+A] extends TraversableLike[A, Traversable[A]]
with GenericTraversableTemplate[A, Traversable] {
@@ -84,7 +82,8 @@ trait Traversable[+A] extends TraversableLike[A, Traversable[A]]
*/
}
-/** $factoryInfo */
+/** $factoryInfo
+ */
object Traversable extends TraversableFactory[Traversable] { self =>
/** Provides break functionality separate from client code */
diff --git a/src/library/scala/collection/TraversableLike.scala b/src/library/scala/collection/TraversableLike.scala
index c5db41005e..4c8d34622e 100644
--- a/src/library/scala/collection/TraversableLike.scala
+++ b/src/library/scala/collection/TraversableLike.scala
@@ -17,18 +17,15 @@ import mutable.{Builder, StringBuilder, Buffer, ArrayBuffer, ListBuffer}
import immutable.{List, Stream, Nil, ::}
/** A template trait for traversable collections of type `Traversable[A]`.
- * $traversableinfo
- *
- * @tparam A the element type of the collection
- * @tparam Repr the type of the actual collection containing the elements.
- *
- * @define traversableinfo
- * This is a base trait of all kinds of Scala collections. It implements
+ * $traversableInfo
+ * @define mutability
+ * @define traversableInfo
+ * This is a base trait of all kinds of $mutability Scala collections. It implements
* the behavior common to all collections, in terms of a method
* `foreach` with signature:
- * {{{
- * def foreach[U](f: Elem => U): Unit
- * }}}
+ * {{{
+ * def foreach[U](f: Elem => U): Unit
+ * }}}
* Collection classes mixing in this trait provide a concrete
* `foreach` method which traverses all the
* elements contained in the collection, applying a given function to each.
@@ -63,7 +60,9 @@ import immutable.{List, Stream, Nil, ::}
* @author Martin Odersky
* @version 2.8
* @since 2.8
-
+ * @tparam A the element type of the collection
+ * @tparam Repr the type of the actual collection containing the elements.
+ *
* @define Coll Traversable
* @define coll traversable collection
* @define thatinfo the class of the returned collection. Where possible, `That` is
@@ -178,10 +177,10 @@ trait TraversableLike[+A, +Repr] extends HasNewBuilder[A, Repr] with Traversable
* @return a new $coll which contains all elements of this $coll
* followed by all elements of `that`.
*/
- def ++[B >: A, That](xs: TraversableOnce[B])(implicit bf: CanBuildFrom[Repr, B, That]): That = {
+ def ++[B >: A, That](that: TraversableOnce[B])(implicit bf: CanBuildFrom[Repr, B, That]): That = {
val b = bf(repr)
b ++= thisCollection
- b ++= xs
+ b ++= that
b.result
}
diff --git a/src/library/scala/collection/TraversableOnce.scala b/src/library/scala/collection/TraversableOnce.scala
index ad3a8c6198..54efa62ef3 100644
--- a/src/library/scala/collection/TraversableOnce.scala
+++ b/src/library/scala/collection/TraversableOnce.scala
@@ -10,8 +10,8 @@ package scala.collection
import mutable.{ Buffer, ListBuffer, ArrayBuffer }
-/** A template trait for collections which can be traversed one
- * or more times.
+/** A template trait for collections which can be traversed either once only
+ * or one or more times.
* $traversableonceinfo
*
* @tparam A the element type of the collection
diff --git a/src/library/scala/collection/TraversableView.scala b/src/library/scala/collection/TraversableView.scala
index e9332097e7..ccc33a495d 100644
--- a/src/library/scala/collection/TraversableView.scala
+++ b/src/library/scala/collection/TraversableView.scala
@@ -15,15 +15,7 @@ import generic._
import mutable.Builder
import TraversableView.NoBuilder
-/** Traversable
.
- * Every subclass has to implement the foreach
method.
- * Traversable
.
- * Every subclass has to implement the foreach
method.
- * mutable.Map
and
- * subclasses thereof.
+/** A template for companion objects of `Map` and subclasses thereof.
*
- * @since 2.8
+ * @define coll map
+ * @define Coll Map
+ * @define factoryInfo
+ * This object provides a set of operations needed to create `$Coll` values.
+ * @author Martin Odersky
+ * @version 2.8
+ * @define canBuildFromInfo
+ * The standard `CanBuildFrom` instance for `$Coll` objects.
+ * @see CanBuildFrom
+ * @define mapCanBuildFromInfo
+ * The standard `CanBuildFrom` instance for `$Coll` objects.
+ * The created value is an instance of class `MapCanBuildFrom`.
+ * @see CanBuildFrom
+ * @see GenericCanBuildFrom
*/
abstract class MapFactory[CC[A, B] <: Map[A, B] with MapLike[A, B, CC[A, B]]] {
diff --git a/src/library/scala/collection/generic/MutableMapFactory.scala b/src/library/scala/collection/generic/MutableMapFactory.scala
index 4ad9fb59e4..0f1608ee71 100644
--- a/src/library/scala/collection/generic/MutableMapFactory.scala
+++ b/src/library/scala/collection/generic/MutableMapFactory.scala
@@ -14,7 +14,7 @@ package generic
import mutable.MapBuilder
-/** A template for companion objects of mutable.Map and subclasses thereof.
+/** A template for companion objects of `mutable.Map` and subclasses thereof.
*
* @since 2.8
*/
diff --git a/src/library/scala/collection/generic/SetFactory.scala b/src/library/scala/collection/generic/SetFactory.scala
index de2baaa222..6a237d453c 100644
--- a/src/library/scala/collection/generic/SetFactory.scala
+++ b/src/library/scala/collection/generic/SetFactory.scala
@@ -17,7 +17,19 @@ import mutable.{Builder, AddingBuilder}
/** A template for companion objects of Set
and subclasses
* thereof.
*
- * @since 2.8
+ * @define coll set
+ * @define Coll Set
+ * @define factoryInfo
+ * This object provides a set of operations needed to create `$Coll` values.
+ * @author Martin Odersky
+ * @version 2.8
+ * @define canBuildFromInfo
+ * The standard `CanBuildFrom` instance for `$Coll` objects.
+ * @see CanBuildFrom
+ * @define setCanBuildFromInfo
+ * The standard `CanBuildFrom` instance for `$Coll` objects.
+ * @see CanBuildFrom
+ * @see GenericCanBuildFrom
*/
abstract class SetFactory[CC[X] <: Set[X] with SetLike[X, CC[X]]]
extends GenericCompanion[CC] {
diff --git a/src/library/scala/collection/generic/TraversableFactory.scala b/src/library/scala/collection/generic/TraversableFactory.scala
index c2668b48a2..b7fda70922 100644
--- a/src/library/scala/collection/generic/TraversableFactory.scala
+++ b/src/library/scala/collection/generic/TraversableFactory.scala
@@ -17,8 +17,8 @@ package generic
*
* @since 2.8
*
- * @define $coll collection
- * @define @Coll Traversable
+ * @define coll collection
+ * @define Coll Traversable
* @define factoryInfo
* This object provides a set of operations to create `$Coll` values.
* @author Martin Odersky
diff --git a/src/library/scala/collection/immutable/BitSet.scala b/src/library/scala/collection/immutable/BitSet.scala
index e06218ff92..857b537904 100644
--- a/src/library/scala/collection/immutable/BitSet.scala
+++ b/src/library/scala/collection/immutable/BitSet.scala
@@ -15,12 +15,8 @@ package immutable
import generic._
import BitSetLike.{LogWL, updateArray}
-/** A base class for immutable bit sets.
+/** A class for immutable bitsets.
* $bitsetinfo
- *
- * @author Martin Odersky
- * @version 2.8
- * @since 1
*/
@serializable @SerialVersionUID(1611436763290191562L)
abstract class BitSet extends Set[Int]
diff --git a/src/library/scala/collection/immutable/DefaultMap.scala b/src/library/scala/collection/immutable/DefaultMap.scala
index 7ee8197150..a19b35aff0 100755
--- a/src/library/scala/collection/immutable/DefaultMap.scala
+++ b/src/library/scala/collection/immutable/DefaultMap.scala
@@ -19,7 +19,8 @@ import generic._
* methods of maps.
* Instances that inherit from DefaultMap[A, B]
still have to
* define:
- *
+ *
* def get(key: A): Option[B] * def iterator: Iterator[(A, B)]*
diff --git a/src/library/scala/collection/immutable/HashSet.scala b/src/library/scala/collection/immutable/HashSet.scala index 16d4473de1..e79b456a2f 100644 --- a/src/library/scala/collection/immutable/HashSet.scala +++ b/src/library/scala/collection/immutable/HashSet.scala @@ -15,12 +15,11 @@ package immutable import generic._ import annotation.unchecked.uncheckedVariance -/**
- * This class implements immutable sets using a hash trie. - *
+/** + * This class implements immutable sets using a hash trie. * - * @note the builder of a hash set returns specialized representations EmptySet,Set1,..., Set4 - * for sets of size <= 4. + * @note the builder of a hash set returns specialized representations `EmptySet`,`Set1`,..., `Set4` + * for sets of `size <= 4`. * * @author Martin Odersky * @author Tiark Rompf diff --git a/src/library/scala/collection/immutable/IndexedSeq.scala b/src/library/scala/collection/immutable/IndexedSeq.scala index 3f29052808..268bd56a85 100644 --- a/src/library/scala/collection/immutable/IndexedSeq.scala +++ b/src/library/scala/collection/immutable/IndexedSeq.scala @@ -15,10 +15,8 @@ import generic._ import mutable.{ArrayBuffer, Builder} /** A subtrait ofcollection.IndexedSeq
which represents indexed sequences
- * that cannot be mutated.
+ * that are guaranteed immutable.
* $indexedSeqInfo
- *
- * @since 2.8
*/
trait IndexedSeq[+A] extends Seq[A]
with scala.collection.IndexedSeq[A]
@@ -27,8 +25,9 @@ trait IndexedSeq[+A] extends Seq[A]
override def companion: GenericCompanion[IndexedSeq] = IndexedSeq
}
-/**
- * @since 2.8
+/** $factoryInfo
+ * @define coll indexed sequence
+ * @define Coll IndexedSeq
*/
object IndexedSeq extends SeqFactory[IndexedSeq] {
@serializable
diff --git a/src/library/scala/collection/immutable/IntMap.scala b/src/library/scala/collection/immutable/IntMap.scala
index 62309a9f48..75a25e0223 100644
--- a/src/library/scala/collection/immutable/IntMap.scala
+++ b/src/library/scala/collection/immutable/IntMap.scala
@@ -167,6 +167,8 @@ sealed abstract class IntMap[+T] extends Map[Int, T] with MapLike[Int, T, IntMap
/**
* Iterator over key, value pairs of the map in unsigned order of the keys.
+ *
+ * @return an iterator over pairs of integer keys and corresponding values.
*/
def iterator : Iterator[(Int, T)] = this match {
case IntMap.Nil => Iterator.empty;
@@ -278,15 +280,20 @@ sealed abstract class IntMap[+T] extends Map[Int, T] with MapLike[Int, T, IntMap
/**
* Updates the map, using the provided function to resolve conflicts if the key is already present.
- * Equivalent to
- * this.get(key) match { - * case None => this.update(key, value); - * case Some(oldvalue) => this.update(key, f(oldvalue, value) } - ** - * @param key The key to update - * @param value The value to use if there is no conflict - * @param f The function used to resolve conflicts. + * Equivalent to: + * {{{ + * this.get(key) match { + * case None => this.update(key, value); + * case Some(oldvalue) => this.update(key, f(oldvalue, value) + * } + * }}} + * + * @tparam S The supertype of values in this `LongMap`. + * @param key The key to update + * @param value The value to use if there is no conflict + * @param f The function used to resolve conflicts. + * @return The updated map. */ def updateWith[S >: T](key : Int, value : S, f : (T, S) => S) : IntMap[S] = this match { case IntMap.Bin(prefix, mask, left, right) => if (!hasMatch(key, prefix, mask)) join(key, IntMap.Tip(key, value), prefix, this); @@ -312,7 +319,9 @@ sealed abstract class IntMap[+T] extends Map[Int, T] with MapLike[Int, T, IntMap * A combined transform and filter function. Returns an IntMap such that for each (key, value) mapping * in this map, if f(key, value) == None the map contains no mapping for key, and if
f(key, value)
*
- * @param f The transforming function.
+ * @tparam S The type of the values in the resulting `LongMap`.
+ * @param f The transforming function.
+ * @return The modified map.
*/
def modifyOrRemove[S](f : (Int, T) => Option[S]) : IntMap[S] = this match {
case IntMap.Bin(prefix, mask, left, right) => {
@@ -335,8 +344,10 @@ sealed abstract class IntMap[+T] extends Map[Int, T] with MapLike[Int, T, IntMap
/**
* Forms a union map with that map, using the combining function to resolve conflicts.
*
- * @param that the map to form a union with.
- * @param f the function used to resolve conflicts between two mappings.
+ * @tparam S The type of values in `that`, a supertype of values in `this`.
+ * @param that The map to form a union with.
+ * @param f The function used to resolve conflicts between two mappings.
+ * @return Union of `this` and `that`, with identical key conflicts resolved using the function `f`.
*/
def unionWith[S >: T](that : IntMap[S], f : (Int, S, S) => S) : IntMap[S] = (this, that) match{
case (IntMap.Bin(p1, m1, l1, r1), that@(IntMap.Bin(p2, m2, l2, r2))) =>
@@ -364,8 +375,11 @@ sealed abstract class IntMap[+T] extends Map[Int, T] with MapLike[Int, T, IntMap
* a map that has only keys present in both maps and has values produced from the original mappings
* by combining them with f.
*
- * @param that The map to intersect with.
- * @param f The combining function.
+ * @tparam S The type of values in `that`.
+ * @tparam R The type of values in the resulting `LongMap`.
+ * @param that The map to intersect with.
+ * @param f The combining function.
+ * @return Intersection of `this` and `that`, with values for identical keys produced by function `f`.
*/
def intersectionWith[S, R](that : IntMap[S], f : (Int, T, S) => R) : IntMap[R] = (this, that) match {
case (IntMap.Bin(p1, m1, l1, r1), that@IntMap.Bin(p2, m2, l2, r2)) =>
@@ -394,7 +408,9 @@ sealed abstract class IntMap[+T] extends Map[Int, T] with MapLike[Int, T, IntMap
* Left biased intersection. Returns the map that has all the same mappings as this but only for keys
* which are present in the other map.
*
- * @param that The map to intersect with.
+ * @tparam R The type of values in `that`.
+ * @param that The map to intersect with.
+ * @return A map with all the keys both in `this` and `that`, mapped to corresponding values from `this`.
*/
def intersection[R](that : IntMap[R]) : IntMap[T] = this.intersectionWith(that, (key : Int, value : T, value2 : R) => value);
diff --git a/src/library/scala/collection/immutable/Iterable.scala b/src/library/scala/collection/immutable/Iterable.scala
index 77e16a6509..795fc2fa92 100644
--- a/src/library/scala/collection/immutable/Iterable.scala
+++ b/src/library/scala/collection/immutable/Iterable.scala
@@ -15,13 +15,8 @@ package immutable
import generic._
import mutable.Builder
-/** A subtrait of scala.collection.Iterable which represents iterables
- * that cannot be mutated.
- *
- * @author Matthias Zenger
- * @author Martin Odersky
- * @version 2.8
- * @since 2.8
+/** A base trait for iterable collections that are guaranteed immutable.
+ * $iterableInfo
*/
trait Iterable[+A] extends Traversable[A]
with scala.collection.Iterable[A]
diff --git a/src/library/scala/collection/immutable/LinearSeq.scala b/src/library/scala/collection/immutable/LinearSeq.scala
index 016afd4508..9cb35dced5 100644
--- a/src/library/scala/collection/immutable/LinearSeq.scala
+++ b/src/library/scala/collection/immutable/LinearSeq.scala
@@ -15,10 +15,9 @@ package immutable
import generic._
import mutable.Builder
-/** A subtrait of collection.LinearSeq
which represents sequences
- * that cannot be mutated.
+/** A subtrait of collection.LinearSeq
which represents sequences that
+ * are guaranteed immutable.
* $linearSeqInfo
- * @since 2.8
*/
trait LinearSeq[+A] extends Seq[A]
with scala.collection.LinearSeq[A]
@@ -27,8 +26,9 @@ trait LinearSeq[+A] extends Seq[A]
override def companion: GenericCompanion[LinearSeq] = LinearSeq
}
-/**
- * @since 2.8
+/** $factoryInfo
+ * @define coll linear sequence
+ * @define Coll LinearSeq
*/
object LinearSeq extends SeqFactory[LinearSeq] {
implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, LinearSeq[A]] = new GenericCanBuildFrom[A]
diff --git a/src/library/scala/collection/immutable/List.scala b/src/library/scala/collection/immutable/List.scala
index 2b91ab8852..4ce441ca55 100644
--- a/src/library/scala/collection/immutable/List.scala
+++ b/src/library/scala/collection/immutable/List.scala
@@ -433,7 +433,10 @@ final case class ::[B](private var hd: B, private[scala] var tl: List[B]) extend
}
}
-/** $factoryInfo */
+/** $factoryInfo
+ * @define coll list
+ * @define Coll List
+ */
object List extends SeqFactory[List] {
import scala.collection.{Iterable, Seq, IndexedSeq}
diff --git a/src/library/scala/collection/immutable/ListMap.scala b/src/library/scala/collection/immutable/ListMap.scala
index d8e3e0856b..4342e54a9d 100644
--- a/src/library/scala/collection/immutable/ListMap.scala
+++ b/src/library/scala/collection/immutable/ListMap.scala
@@ -104,6 +104,8 @@ class ListMap[A, +B] extends Map[A, B] with MapLike[A, B, ListMap[A, B]] {
protected def value: B = throw new NoSuchElementException("empty map")
protected def next: ListMap[A, B] = throw new NoSuchElementException("empty map")
+ /** This class represents an entry in the `ListMap`.
+ */
@serializable @SerialVersionUID(-6453056603889598734L)
protected class Node[B1 >: B](override protected val key: A,
override protected val value: B1) extends ListMap[A, B1] {
diff --git a/src/library/scala/collection/immutable/ListSet.scala b/src/library/scala/collection/immutable/ListSet.scala
index 3863c16591..f7b76d2317 100644
--- a/src/library/scala/collection/immutable/ListSet.scala
+++ b/src/library/scala/collection/immutable/ListSet.scala
@@ -85,6 +85,8 @@ class ListSet[A] extends Set[A]
*/
protected def next: ListSet[A] = throw new NoSuchElementException("Next of an empty set");
+ /** Represents an entry in the `ListSet`.
+ */
@serializable
protected class Node(override protected val elem: A) extends ListSet[A] {
diff --git a/src/library/scala/collection/immutable/LongMap.scala b/src/library/scala/collection/immutable/LongMap.scala
index 0d74e41cec..24afb65b99 100644
--- a/src/library/scala/collection/immutable/LongMap.scala
+++ b/src/library/scala/collection/immutable/LongMap.scala
@@ -153,6 +153,8 @@ sealed abstract class LongMap[+T] extends Map[Long, T] with MapLike[Long, T, Lon
/**
* Iterator over key, value pairs of the map in unsigned order of the keys.
+ *
+ * @return an iterator over pairs of long keys and corresponding values.
*/
def iterator: Iterator[(Long, T)] = this match {
case LongMap.Nil => Iterator.empty;
@@ -264,15 +266,20 @@ sealed abstract class LongMap[+T] extends Map[Long, T] with MapLike[Long, T, Lon
/**
* Updates the map, using the provided function to resolve conflicts if the key is already present.
+ *
* Equivalent to
- * this.get(key) match {
- * case None => this.update(key, value);
- * case Some(oldvalue) => this.update(key, f(oldvalue, value) }
- *
+ * {{{
+ * this.get(key) match {
+ * case None => this.update(key, value);
+ * case Some(oldvalue) => this.update(key, f(oldvalue, value)
+ * }
+ * }}}
*
- * @param key The key to update
- * @param value The value to use if there is no conflict
- * @param f The function used to resolve conflicts.
+ * @tparam S The supertype of values in this `LongMap`.
+ * @param key The key to update.
+ * @param value The value to use if there is no conflict.
+ * @param f The function used to resolve conflicts.
+ * @return The updated map.
*/
def updateWith[S >: T](key : Long, value : S, f : (T, S) => S) : LongMap[S] = this match {
case LongMap.Bin(prefix, mask, left, right) => if (!hasMatch(key, prefix, mask)) join(key, LongMap.Tip(key, value), prefix, this);
@@ -298,7 +305,9 @@ sealed abstract class LongMap[+T] extends Map[Long, T] with MapLike[Long, T, Lon
* A combined transform and filter function. Returns an LongMap such that for each (key, value) mapping
* in this map, if f(key, value) == None the map contains no mapping for key, and if f(key, value)
*
- * @param f The transforming function.
+ * @tparam S The type of the values in the resulting `LongMap`.
+ * @param f The transforming function.
+ * @return The modified map.
*/
def modifyOrRemove[S](f : (Long, T) => Option[S]) : LongMap[S] = this match {
case LongMap.Bin(prefix, mask, left, right) => {
@@ -321,8 +330,10 @@ sealed abstract class LongMap[+T] extends Map[Long, T] with MapLike[Long, T, Lon
/**
* Forms a union map with that map, using the combining function to resolve conflicts.
*
- * @param that the map to form a union with.
- * @param f the function used to resolve conflicts between two mappings.
+ * @tparam S The type of values in `that`, a supertype of values in `this`.
+ * @param that The map to form a union with.
+ * @param f The function used to resolve conflicts between two mappings.
+ * @return Union of `this` and `that`, with identical key conflicts resolved using the function `f`.
*/
def unionWith[S >: T](that : LongMap[S], f : (Long, S, S) => S) : LongMap[S] = (this, that) match{
case (LongMap.Bin(p1, m1, l1, r1), that@(LongMap.Bin(p2, m2, l2, r2))) =>
@@ -350,8 +361,11 @@ sealed abstract class LongMap[+T] extends Map[Long, T] with MapLike[Long, T, Lon
* a map that has only keys present in both maps and has values produced from the original mappings
* by combining them with f.
*
- * @param that The map to intersect with.
- * @param f The combining function.
+ * @tparam S The type of values in `that`.
+ * @tparam R The type of values in the resulting `LongMap`.
+ * @param that The map to intersect with.
+ * @param f The combining function.
+ * @return Intersection of `this` and `that`, with values for identical keys produced by function `f`.
*/
def intersectionWith[S, R](that : LongMap[S], f : (Long, T, S) => R) : LongMap[R] = (this, that) match {
case (LongMap.Bin(p1, m1, l1, r1), that@LongMap.Bin(p2, m2, l2, r2)) =>
@@ -380,7 +394,9 @@ sealed abstract class LongMap[+T] extends Map[Long, T] with MapLike[Long, T, Lon
* Left biased intersection. Returns the map that has all the same mappings as this but only for keys
* which are present in the other map.
*
- * @param that The map to intersect with.
+ * @tparam R The type of values in `that`.
+ * @param that The map to intersect with.
+ * @return A map with all the keys both in `this` and `that`, mapped to corresponding values from `this`.
*/
def intersection[R](that : LongMap[R]) : LongMap[T] = this.intersectionWith(that, (key : Long, value : T, value2 : R) => value);
diff --git a/src/library/scala/collection/immutable/Map.scala b/src/library/scala/collection/immutable/Map.scala
index b5a852683a..e3469099b8 100644
--- a/src/library/scala/collection/immutable/Map.scala
+++ b/src/library/scala/collection/immutable/Map.scala
@@ -15,6 +15,16 @@ package immutable
import generic._
/**
+ * A generic trait for immutable maps. Concrete classes have to provide
+ * functionality for the abstract methods in `Map`:
+ *
+ * {{{
+ * def get(key: A): Option[B]
+ * def iterator: Iterator[(A, B)]
+ * def + [B1 >: B](kv: (A, B1)): Map[A, B1]
+ * def -(key: A): Map[A, B]
+ * }}}
+ *
* @since 1
*/
trait Map[A, +B] extends Iterable[(A, B)]
@@ -39,6 +49,8 @@ trait Map[A, +B] extends Iterable[(A, B)]
}
/**
+ * A companion object for immutable maps.
+ *
* @since 1
*/
object Map extends ImmutableMapFactory[Map] {
diff --git a/src/library/scala/collection/immutable/MapLike.scala b/src/library/scala/collection/immutable/MapLike.scala
index 662321bb0c..6f816ffa52 100644
--- a/src/library/scala/collection/immutable/MapLike.scala
+++ b/src/library/scala/collection/immutable/MapLike.scala
@@ -91,13 +91,10 @@ trait MapLike[A, +B, +This <: MapLike[A, B, This] with Map[A, B]]
}
/** Transforms this map by applying a function to every retrieved value.
- * @param d the function used to transform values of this map.
- * @return an immutable map which maps every key of this map
+ * @param f the function used to transform values of this map.
+ * @return a map view which maps every key of this map
* to `f(this(key))`. The resulting map wraps the original map without copying any elements.
*/
- /** A map view resulting from applying a given function `f` to each value
- * associated with a key in this map.
- */
override def mapValues[C](f: B => C): Map[A, C] = new DefaultMap[A, C] {
override def foreach[D](g: ((A, C)) => D): Unit = for ((k, v) <- self) g((k, f(v)))
def iterator = for ((k, v) <- self.iterator) yield (k, f(v))
diff --git a/src/library/scala/collection/immutable/NumericRange.scala b/src/library/scala/collection/immutable/NumericRange.scala
index d3e4558884..645c5fed24 100644
--- a/src/library/scala/collection/immutable/NumericRange.scala
+++ b/src/library/scala/collection/immutable/NumericRange.scala
@@ -17,12 +17,12 @@ import generic._
/**
* NumericRange
is a more generic version of the
* Range
class which works with arbitrary types.
- * It must be supplied with an Integral implementation of the
+ * It must be supplied with an `Integral` implementation of the
* range type.
*
- * Factories for likely types include Range.BigInt, Range.Long,
- * and Range.BigDecimal. Range.Int exists for completeness, but
- * the Int-based scala.Range should be more performant.
+ * Factories for likely types include `Range.BigInt`, `Range.Long`,
+ * and `Range.BigDecimal`. `Range.Int` exists for completeness, but
+ * the `Int`-based `scala.Range` should be more performant.
*
* val r1 = new Range(0, 100, 1)
* val veryBig = Int.MaxValue.toLong + 1
diff --git a/src/library/scala/collection/immutable/Range.scala b/src/library/scala/collection/immutable/Range.scala
index 43b11b67be..5424a7afcb 100644
--- a/src/library/scala/collection/immutable/Range.scala
+++ b/src/library/scala/collection/immutable/Range.scala
@@ -32,14 +32,14 @@ class Range(val start: Int, val end: Int, val step: Int) extends IndexedSeq[Int]
protected def copy(start: Int, end: Int, step: Int): Range = new Range(start, end, step)
- /** Create a new range with the start and end values of this range and
+ /** Create a new range with the `start` and `end` values of this range and
* a new step
.
*/
def by(step: Int): Range = copy(start, end, step)
def isInclusive = false
- override def foreach[U](f: Int => U) {
+ override def foreach[@specialized(Unit) U](f: Int => U) {
if (fullLength > 0) {
val last = this.last
var i = start
@@ -191,7 +191,7 @@ object Range {
def inclusive(start: Int, end: Int): Range.Inclusive with ByOne = new Inclusive(start, end, 1) with ByOne
trait ByOne extends Range {
- override final def foreach[U](f: Int => U) {
+ override final def foreach[@specialized(Unit) U](f: Int => U) {
if (length > 0) {
val last = this.last
var i = start
diff --git a/src/library/scala/collection/immutable/RedBlack.scala b/src/library/scala/collection/immutable/RedBlack.scala
index e7b4f3c978..ffa6194838 100644
--- a/src/library/scala/collection/immutable/RedBlack.scala
+++ b/src/library/scala/collection/immutable/RedBlack.scala
@@ -12,7 +12,7 @@
package scala.collection
package immutable
-/** An base class containing the implementations for TreeMaps and TreeSets
+/** A base class containing the implementations for TreeMaps and TreeSets
*
* @since 2.3
*/
diff --git a/src/library/scala/collection/immutable/Seq.scala b/src/library/scala/collection/immutable/Seq.scala
index 9bd7084675..de7804a95c 100644
--- a/src/library/scala/collection/immutable/Seq.scala
+++ b/src/library/scala/collection/immutable/Seq.scala
@@ -15,10 +15,10 @@ package immutable
import generic._
import mutable.Builder
-/** A subtrait of collection.Seq which represents sequences
- * that cannot be mutated.
+/** A subtrait of `collection.Seq` which represents sequences
+ * that are guaranteed immutable.
*
- * @since 2.8
+ * $seqInfo
*/
trait Seq[+A] extends Iterable[A]
with scala.collection.Seq[A]
diff --git a/src/library/scala/collection/immutable/Set.scala b/src/library/scala/collection/immutable/Set.scala
index 1bec1b9a48..77f16c0d14 100644
--- a/src/library/scala/collection/immutable/Set.scala
+++ b/src/library/scala/collection/immutable/Set.scala
@@ -39,6 +39,9 @@ trait Set[A] extends Iterable[A]
override def companion: GenericCompanion[Set] = Set
}
+/**
+ * A companion object for immutable sets.
+ */
object Set extends SetFactory[Set] {
implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, Set[A]] = setCanBuildFrom[A]
override def empty[A]: Set[A] = EmptySet.asInstanceOf[Set[A]]
diff --git a/src/library/scala/collection/immutable/SortedSet.scala b/src/library/scala/collection/immutable/SortedSet.scala
index 9d0b1882fa..10ff466ff8 100644
--- a/src/library/scala/collection/immutable/SortedSet.scala
+++ b/src/library/scala/collection/immutable/SortedSet.scala
@@ -15,7 +15,8 @@ package immutable
import generic._
import mutable.Builder
-/** A sorted set.
+/** A subtrait of `collection.SortedSet` which represents sorted sets
+ * which cannot be mutated.
*
* @author Sean McDirmid
* @author Martin Odersky
@@ -28,6 +29,8 @@ trait SortedSet[A] extends Set[A] with scala.collection.SortedSet[A] with Sorted
}
/**
+ * A companion object for immutable sorted sets.
+ *
* @since 2.4
*/
object SortedSet extends ImmutableSortedSetFactory[SortedSet] {
diff --git a/src/library/scala/collection/immutable/Stack.scala b/src/library/scala/collection/immutable/Stack.scala
index 640fb39af5..7d3c8c040b 100644
--- a/src/library/scala/collection/immutable/Stack.scala
+++ b/src/library/scala/collection/immutable/Stack.scala
@@ -67,8 +67,8 @@ class Stack[+A] protected (protected val elems: List[A]) extends LinearSeq[A]
def push[B >: A](elem1: B, elem2: B, elems: B*): Stack[B] =
this.push(elem1).push(elem2).pushAll(elems)
- /** Push all elements provided by the given iterator object onto
- * the stack. The last element returned by the iterable object
+ /** Push all elements provided by the given traversable object onto
+ * the stack. The last element returned by the traversable object
* will be on top of the new stack.
*
* @param elems the iterator object.
diff --git a/src/library/scala/collection/immutable/StringLike.scala b/src/library/scala/collection/immutable/StringLike.scala
index 5b5a627cfe..8068267dd2 100644
--- a/src/library/scala/collection/immutable/StringLike.scala
+++ b/src/library/scala/collection/immutable/StringLike.scala
@@ -49,7 +49,7 @@ self =>
override def mkString = toString
- /** return n times the current string
+ /** Return the current string concatenated `n` times.
*/
def * (n: Int): String = {
val buf = new StringBuilder
@@ -61,18 +61,16 @@ self =>
private def isLineBreak(c: Char) = c == LF || c == FF
- /**
+ /**
* Strip trailing line end character from this string if it has one.
+ *
* A line end character is one of
- *
- *
- * - LF - line feed (0x0A hex)
- * - FF - form feed (0x0C hex)
- *
- *
+ *
+ * - LF - line feed (0x0A hex)
+ * - FF - form feed (0x0C hex)
+ *
* If a line feed character LF is preceded by a carriage return CR
* (0x0D hex), the CR character is also stripped (Windows convention).
- *
*/
def stripLineEnd: String = {
val len = toString.length
@@ -86,19 +84,18 @@ self =>
}
}
- /**
+ /**
* Return all lines in this string in an iterator, including trailing
* line end characters.
- *
- *
+ *
* The number of strings returned is one greater than the number of line
* end characters in this string. For an empty string, a single empty
* line is returned. A line end character is one of
- *
- *
- * - LF - line feed (0x0A hex)
- * - FF - form feed (0x0C hex)
- *
+ *
+ *
+ * - LF - line feed (0x0A hex)
+ * - FF - form feed (0x0C hex)
+ *
*/
def linesWithSeparators: Iterator[String] = new Iterator[String] {
val str = self.toString
@@ -148,13 +145,13 @@ self =>
if (toString.endsWith(suffix)) toString.substring(0, toString.length() - suffix.length)
else toString
- /**
+ /**
* For every line in this string:
- *
- *
- * Strip a leading prefix consisting of blanks or control characters
- * followed by marginChar
from the line.
- *
+ *
+ *
+ * Strip a leading prefix consisting of blanks or control characters
+ * followed by marginChar
from the line.
+ *
*/
def stripMargin(marginChar: Char): String = {
val buf = new StringBuilder
@@ -168,13 +165,13 @@ self =>
buf.toString
}
- /**
+ /**
* For every line in this string:
- *
- *
- * Strip a leading prefix consisting of blanks or control characters
- * followed by |
from the line.
- *
+ *
+ *
+ * Strip a leading prefix consisting of blanks or control characters
+ * followed by |
from the line.
+ *
*/
def stripMargin: String = stripMargin('|')
@@ -226,19 +223,18 @@ self =>
case x => x.asInstanceOf[AnyRef]
}
- /**
+ /**
* Uses the underlying string as a pattern (in a fashion similar to
* printf in C), and uses the supplied arguments to fill in the
* holes.
- *
- *
+ *
* The interpretation of the formatting patterns is described in
*
* java.util.Formatter
, with the addition that
- * classes deriving from ScalaNumber (such as scala.BigInt and
- * scala.BigDecimal) are unwrapped to pass a type which Formatter
+ * classes deriving from `ScalaNumber` (such as `scala.BigInt` and
+ * `scala.BigDecimal`) are unwrapped to pass a type which `Formatter`
* understands.
- *
+ *
*
* @param args the arguments used to instantiating the pattern.
* @throws java.lang.IllegalArgumentException
@@ -246,20 +242,20 @@ self =>
def format(args : Any*): String =
java.lang.String.format(toString, args map unwrapArg: _*)
- /**
- * Like format(args*) but takes an initial Locale parameter
- * which influences formatting as in java.lang.String's format.
- *
- *
+ /**
+ * Like `format(args*)` but takes an initial `Locale` parameter
+ * which influences formatting as in `java.lang.String`'s format.
+ *
+ *
* The interpretation of the formatting patterns is described in
*
* java.util.Formatter
, with the addition that
- * classes deriving from ScalaNumber (such as scala.BigInt and
- * scala.BigDecimal) are unwrapped to pass a type which Formatter
+ * classes deriving from `ScalaNumber` (such as `scala.BigInt` and
+ * `scala.BigDecimal`) are unwrapped to pass a type which `Formatter`
* understands.
- *
*
- * @param locale an instance of java.util.Locale
+ *
+ * @param locale an instance of `java.util.Locale`
* @param args the arguments used to instantiating the pattern.
* @throws java.lang.IllegalArgumentException
*/
diff --git a/src/library/scala/collection/immutable/StringOps.scala b/src/library/scala/collection/immutable/StringOps.scala
index 95509ab9d6..4949eb7056 100644
--- a/src/library/scala/collection/immutable/StringOps.scala
+++ b/src/library/scala/collection/immutable/StringOps.scala
@@ -15,6 +15,14 @@ package immutable
import mutable.StringBuilder
/**
+ * This class serves as a wrapper providing `String`s with all the operations
+ * found in indexed sequences. Where needed, instances of `String` object
+ * are implicitly converted into this class.
+ *
+ * The difference between this class and `WrappedString` is that calling transformer
+ * methods such as `filter` and `map` will yield a `String` object, whereas a
+ * `WrappedString` will remain a `WrappedString`.
+ *
* @since 2.8
*/
final class StringOps(override val repr: String) extends StringLike[String] {
diff --git a/src/library/scala/collection/immutable/Traversable.scala b/src/library/scala/collection/immutable/Traversable.scala
index b0934ece85..af7f6979c9 100644
--- a/src/library/scala/collection/immutable/Traversable.scala
+++ b/src/library/scala/collection/immutable/Traversable.scala
@@ -15,13 +15,9 @@ package immutable
import generic._
import mutable.Builder
-/** A subtrait of collection.Traversable
which represents
- * traversables that cannot be mutated.
- *
- * @author Matthias Zenger
- * @author Martin Odersky
- * @version 2.8
- * @since 2.8
+/** A trait for traversable collections that are guaranteed immutable.
+ * $traversableInfo
+ * @define mutability immutable
*/
trait Traversable[+A] extends scala.collection.Traversable[A]
with GenericTraversableTemplate[A, Traversable]
diff --git a/src/library/scala/collection/immutable/WrappedString.scala b/src/library/scala/collection/immutable/WrappedString.scala
index e10b3ab0ee..cefbd96b5c 100644
--- a/src/library/scala/collection/immutable/WrappedString.scala
+++ b/src/library/scala/collection/immutable/WrappedString.scala
@@ -17,6 +17,13 @@ import mutable.{Builder, StringBuilder}
import scala.util.matching.Regex
/**
+ * This class serves as a wrapper augmenting `String`s with all the operations
+ * found in indexed sequences.
+ *
+ * The difference between this class and `StringOps` is that calling transformer
+ * methods such as `filter` and `map` will yield an object of type `WrappedString`
+ * rather than a `String`.
+ *
* @since 2.8
*/
class WrappedString(override val self: String) extends IndexedSeq[Char] with StringLike[WrappedString] with Proxy {
diff --git a/src/library/scala/collection/mutable/AddingBuilder.scala b/src/library/scala/collection/mutable/AddingBuilder.scala
index d16a4a71f3..14636c9feb 100644
--- a/src/library/scala/collection/mutable/AddingBuilder.scala
+++ b/src/library/scala/collection/mutable/AddingBuilder.scala
@@ -15,6 +15,7 @@ import generic._
/** 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.
* @tparam Elem the type of elements that get added to the builder.
diff --git a/src/library/scala/collection/mutable/ArrayBuffer.scala b/src/library/scala/collection/mutable/ArrayBuffer.scala
index 0c6aa9ce0c..bee531221f 100644
--- a/src/library/scala/collection/mutable/ArrayBuffer.scala
+++ b/src/library/scala/collection/mutable/ArrayBuffer.scala
@@ -14,7 +14,7 @@ package mutable
import generic._
-/** An implementation of the Buffer
class using an array to
+/** An implementation of the `Buffer` class using an array to
* represent the assembled sequence internally. Append, update and random
* access take constant time (amortized time). Prepends and removes are
* linear in the buffer size.
@@ -23,6 +23,22 @@ import generic._
* @author Martin Odersky
* @version 2.8
* @since 1
+ *
+ * @tparam A the type of this arraybuffer's elements.
+ *
+ * @define Coll ArrayBuffer
+ * @define coll arraybuffer
+ * @define thatinfo the class of the returned collection. In the standard library configuration,
+ * `That` is always `ArrayBuffer[B]` because an implicit of type `CanBuildFrom[ArrayBuffer, B, ArrayBuffer[B]]`
+ * is defined in object `ArrayBuffer`.
+ * @define $bfinfo an implicit value of class `CanBuildFrom` which determines the
+ * result class `That` from the current representation type `Repr`
+ * and the new element type `B`. This is usually the `canBuildFrom` value
+ * defined in object `ArrayBuffer`.
+ * @define orderDependent
+ * @define orderDependentFold
+ * @define mayNotTerminateInf
+ * @define willNotTerminateInf
*/
@serializable @SerialVersionUID(1529165946227428979L)
class ArrayBuffer[A](override protected val initialSize: Int)
@@ -50,9 +66,10 @@ class ArrayBuffer[A](override protected val initialSize: Int)
}
/** Appends a single element to this buffer and returns
- * the identity of the buffer. It takes constant time.
+ * the identity of the buffer. It takes constant amortized time.
*
* @param elem the element to append.
+ * @return the updated buffer.
*/
def +=(elem: A): this.type = {
ensureSize(size0 + 1)
@@ -61,11 +78,10 @@ class ArrayBuffer[A](override protected val initialSize: Int)
this
}
- /** Appends a number of elements provided by an iterable object
- * via its iterator
method. The identity of the
- * buffer is returned.
+ /** Appends a number of elements provided by a traversable object.
+ * The identity of the buffer is returned.
*
- * @param iter the iterable object.
+ * @param xs the traversable object.
* @return the updated buffer.
*/
override def ++=(xs: TraversableOnce[A]): this.type = xs match {
@@ -79,7 +95,7 @@ class ArrayBuffer[A](override protected val initialSize: Int)
super.++=(xs)
}
- /** Prepends a single element to this buffer and return
+ /** Prepends a single element to this buffer and returns
* the identity of the buffer. It takes time linear in
* the buffer size.
*
@@ -94,22 +110,21 @@ class ArrayBuffer[A](override protected val initialSize: Int)
this
}
- /** Prepends a number of elements provided by an iterable object
- * via its iterator
method. The identity of the
- * buffer is returned.
+ /** Prepends a number of elements provided by a traversable object.
+ * The identity of the buffer is returned.
*
- * @param iter the iterable object.
+ * @param xs the traversable object.
* @return the updated buffer.
*/
override def ++=:(xs: TraversableOnce[A]): this.type = { insertAll(0, xs.toTraversable); this }
- /** Inserts new elements at the index n
. Opposed to method
- * update
, this method will not replace an element with a
- * one. Instead, it will insert a new element at index n
.
+ /** Inserts new elements at the index `n`. Opposed to method
+ * `update`, this method will not replace an element with a
+ * one. Instead, it will insert a new element at index `n`.
*
* @param n the index where a new element will be inserted.
- * @param iter the iterable object providing all elements to insert.
- * @throws Predef.IndexOutOfBoundsException if n
is out of bounds.
+ * @param seq the traversable object providing all elements to insert.
+ * @throws Predef.IndexOutOfBoundsException if `n` is out of bounds.
*/
def insertAll(n: Int, seq: Traversable[A]) {
if (n < 0 || n > size0) throw new IndexOutOfBoundsException(n.toString)
@@ -124,9 +139,9 @@ class ArrayBuffer[A](override protected val initialSize: Int)
/** Removes the element on a given index position. It takes time linear in
* the buffer size.
*
- * @param n the index which refers to the first element to delete.
+ * @param n the index which refers to the first element to delete.
* @param count the number of elements to delete
- * @throws Predef.IndexOutOfBoundsException if n
is out of bounds.
+ * @throws Predef.IndexOutOfBoundsException if `n` is out of bounds.
*/
override def remove(n: Int, count: Int) {
require(count >= 0, "removing negative number of elements")
@@ -135,10 +150,10 @@ class ArrayBuffer[A](override protected val initialSize: Int)
reduceToSize(size0 - count)
}
- /** Removes the element on a given index position
+ /** Removes the element at a given index position.
*
* @param n the index which refers to the element to delete.
- * @return The element that was formerly at position `n`
+ * @return the element that was formerly at position `n`.
*/
def remove(n: Int): A = {
val result = apply(n)
@@ -148,7 +163,7 @@ class ArrayBuffer[A](override protected val initialSize: Int)
/** Return a clone of this buffer.
*
- * @return an ArrayBuffer
with the same elements.
+ * @return an `ArrayBuffer` with the same elements.
*/
override def clone(): ArrayBuffer[A] = new ArrayBuffer[A] ++= this
@@ -159,13 +174,14 @@ class ArrayBuffer[A](override protected val initialSize: Int)
override def stringPrefix: String = "ArrayBuffer"
}
-/** Factory object for ArrayBuffer
class.
+/** Factory object for the `ArrayBuffer` class.
*
- * @author Martin Odersky
- * @version 2.8
- * @since 2.8
+ * $factoryInfo
+ * @define coll list
+ * @define Coll List
*/
object ArrayBuffer extends SeqFactory[ArrayBuffer] {
+ /** $genericCanBuildFromInfo */
implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, ArrayBuffer[A]] = new GenericCanBuildFrom[A]
def newBuilder[A]: Builder[A, ArrayBuffer[A]] = new ArrayBuffer[A]
}
diff --git a/src/library/scala/collection/mutable/ArrayBuilder.scala b/src/library/scala/collection/mutable/ArrayBuilder.scala
index 7e4bab353b..0ddd089852 100644
--- a/src/library/scala/collection/mutable/ArrayBuilder.scala
+++ b/src/library/scala/collection/mutable/ArrayBuilder.scala
@@ -15,21 +15,33 @@ package mutable
import generic._
import scala.reflect.ClassManifest
-/** A builder class for arrays
+/** A builder class for arrays.
*
- * @since 2.8
+ * @since 2.8
+ *
+ * @tparam T the type of the elements for the builder.
*/
@serializable
abstract class ArrayBuilder[T] extends Builder[T, Array[T]]
-/**
- * @since 2.8
+/** A companion object for array builders.
+ *
+ * @since 2.8
*/
object ArrayBuilder {
+ /** Creates a new arraybuilder of type `T`.
+ *
+ * @tparam T type of the elements for the array builder, with a `ClassManifest` context bound.
+ * @return a new empty array builder.
+ */
def make[T: ClassManifest](): ArrayBuilder[T] =
implicitly[ClassManifest[T]].newArrayBuilder()
+ /** A class for array builders for arrays of reference types.
+ *
+ * @tparam T type of elements for the array builder, subtype of `AnyRef` with a `ClassManifest` context bound.
+ */
class ofRef[T <: AnyRef : ClassManifest] extends ArrayBuilder[T] {
private var elems: Array[T] = _
@@ -94,6 +106,7 @@ object ArrayBuilder {
override def toString = "ArrayBuilder.ofRef"
}
+ /** A class for array builders for arrays of `byte`s. */
class ofByte extends ArrayBuilder[Byte] {
private var elems: Array[Byte] = _
@@ -158,6 +171,7 @@ object ArrayBuilder {
override def toString = "ArrayBuilder.ofByte"
}
+ /** A class for array builders for arrays of `short`s. */
class ofShort extends ArrayBuilder[Short] {
private var elems: Array[Short] = _
@@ -222,6 +236,7 @@ object ArrayBuilder {
override def toString = "ArrayBuilder.ofShort"
}
+ /** A class for array builders for arrays of `char`s. */
class ofChar extends ArrayBuilder[Char] {
private var elems: Array[Char] = _
@@ -286,6 +301,7 @@ object ArrayBuilder {
override def toString = "ArrayBuilder.ofChar"
}
+ /** A class for array builders for arrays of `int`s. */
class ofInt extends ArrayBuilder[Int] {
private var elems: Array[Int] = _
@@ -350,6 +366,7 @@ object ArrayBuilder {
override def toString = "ArrayBuilder.ofInt"
}
+ /** A class for array builders for arrays of `long`s. */
class ofLong extends ArrayBuilder[Long] {
private var elems: Array[Long] = _
@@ -414,6 +431,7 @@ object ArrayBuilder {
override def toString = "ArrayBuilder.ofLong"
}
+ /** A class for array builders for arrays of `float`s. */
class ofFloat extends ArrayBuilder[Float] {
private var elems: Array[Float] = _
@@ -478,6 +496,7 @@ object ArrayBuilder {
override def toString = "ArrayBuilder.ofFloat"
}
+ /** A class for array builders for arrays of `double`s. */
class ofDouble extends ArrayBuilder[Double] {
private var elems: Array[Double] = _
@@ -542,6 +561,7 @@ object ArrayBuilder {
override def toString = "ArrayBuilder.ofDouble"
}
+ /** A class for array builders for arrays of `boolean`s. */
class ofBoolean extends ArrayBuilder[Boolean] {
private var elems: Array[Boolean] = _
@@ -606,6 +626,7 @@ object ArrayBuilder {
override def toString = "ArrayBuilder.ofBoolean"
}
+ /** A class for array builders for arrays of `Unit` type. */
class ofUnit extends ArrayBuilder[Unit] {
private var elems: Array[Unit] = _
diff --git a/src/library/scala/collection/mutable/ArrayLike.scala b/src/library/scala/collection/mutable/ArrayLike.scala
index 0b64f1255e..b3bd0fbe25 100644
--- a/src/library/scala/collection/mutable/ArrayLike.scala
+++ b/src/library/scala/collection/mutable/ArrayLike.scala
@@ -13,21 +13,31 @@ package scala.collection
package mutable
import generic._
-/** A subtrait of collection.IndexedSeq which represents sequences
+/** A subtrait of `collection.IndexedSeq` which represents sequences
* that can be mutated.
*
* @since 2.8
+ *
+ * @tparam A type of the elements contained in the array like object.
+ * @tparam Repr the type of the actual collection containing the elements.
+ *
+ * @define Coll ArrayLike
*/
trait ArrayLike[A, +Repr] extends IndexedSeqOptimized[A, Repr] { self =>
- /** Creates a possible nested IndexedSeq which consists of all the elements
- * of this array. If the elements are arrays themselves, the `deep' transformation
- * is applied recursively to them. The stringPrefix of the IndexedSeq is
- * "Array", hence the IndexedSeq prints like an array with all its
+ /** Creates a possible nested `IndexedSeq` which consists of all the elements
+ * of this array. If the elements are arrays themselves, the `deep` transformation
+ * is applied recursively to them. The `stringPrefix` of the `IndexedSeq` is
+ * "Array", hence the `IndexedSeq` prints like an array with all its
* elements shown, and the same recursively for any subarrays.
*
- * Example: Array(Array(1, 2), Array(3, 4)).deep.toString
- * prints: Array(Array(1, 2), Array(3, 4))
+ * Example:
+ * {{{
+ * Array(Array(1, 2), Array(3, 4)).deep.toString
+ * }}}
+ * prints: `Array(Array(1, 2), Array(3, 4))`
+ *
+ * @return An possibly nested indexed sequence of consisting of all the elements of the array.
*/
def deep: scala.collection.IndexedSeq[Any] = new scala.collection.IndexedSeq[Any] {
def length = self.length
diff --git a/src/library/scala/collection/mutable/ArrayOps.scala b/src/library/scala/collection/mutable/ArrayOps.scala
index 553461c805..971709ed67 100644
--- a/src/library/scala/collection/mutable/ArrayOps.scala
+++ b/src/library/scala/collection/mutable/ArrayOps.scala
@@ -14,8 +14,23 @@ package mutable
import scala.reflect.ClassManifest
-/**
- * @since 2.8
+/** This class serves as a wrapper for `Array`s with all the operations found in
+ * indexed sequences. Where needed, instances of arrays are implicitly converted
+ * into this class.
+ *
+ * The difference between this class and `WrappedArray` is that calling transformer
+ * methods such as `filter` and `map` will yield an array, whereas a `WrappedArray`
+ * will remain a `WrappedArray`.
+ *
+ * @since 2.8
+ *
+ * @tparam T type of the elements contained in this array.
+ *
+ * @define Coll ArrayOps
+ * @define orderDependent
+ * @define orderDependentFold
+ * @define mayNotTerminateInf
+ * @define willNotTerminateInf
*/
abstract class ArrayOps[T] extends ArrayLike[T, Array[T]] {
@@ -31,7 +46,11 @@ abstract class ArrayOps[T] extends ArrayLike[T, Array[T]] {
super.toArray[U]
/** Flattens a two-dimensional array by concatenating all its rows
- * into a single array
+ * into a single array.
+ *
+ * @tparam U Type of row elements.
+ * @param asArray A function that converts elements of this array to rows - arrays of type `U`.
+ * @return An array obtained by concatenating rows of this array.
*/
def flatten[U](implicit asArray: T => /*<: Array[U]): Array[Array[U]] = {
val bs = asArray(head) map (_ => rowBuilder[U])
@@ -60,10 +83,13 @@ abstract class ArrayOps[T] extends ArrayLike[T, Array[T]] {
}
/**
+ * A companion object for `ArrayOps`.
+ *
* @since 2.8
*/
object ArrayOps {
+ /** A class of `ArrayOps` for arrays containing reference types. */
class ofRef[T <: AnyRef](override val repr: Array[T]) extends ArrayOps[T] with ArrayLike[T, Array[T]] {
override protected[this] def thisCollection: WrappedArray[T] = new WrappedArray.ofRef[T](repr)
@@ -76,6 +102,7 @@ object ArrayOps {
def update(index: Int, elem: T) { repr(index) = elem }
}
+ /** A class of `ArrayOps` for arrays containing `byte`s. */
class ofByte(override val repr: Array[Byte]) extends ArrayOps[Byte] with ArrayLike[Byte, Array[Byte]] {
override protected[this] def thisCollection: WrappedArray[Byte] = new WrappedArray.ofByte(repr)
@@ -87,6 +114,7 @@ object ArrayOps {
def update(index: Int, elem: Byte) { repr(index) = elem }
}
+ /** A class of `ArrayOps` for arrays containing `short`s. */
class ofShort(override val repr: Array[Short]) extends ArrayOps[Short] with ArrayLike[Short, Array[Short]] {
override protected[this] def thisCollection: WrappedArray[Short] = new WrappedArray.ofShort(repr)
@@ -98,6 +126,7 @@ object ArrayOps {
def update(index: Int, elem: Short) { repr(index) = elem }
}
+ /** A class of `ArrayOps` for arrays containing `char`s. */
class ofChar(override val repr: Array[Char]) extends ArrayOps[Char] with ArrayLike[Char, Array[Char]] {
override protected[this] def thisCollection: WrappedArray[Char] = new WrappedArray.ofChar(repr)
@@ -109,6 +138,7 @@ object ArrayOps {
def update(index: Int, elem: Char) { repr(index) = elem }
}
+ /** A class of `ArrayOps` for arrays containing `int`s. */
class ofInt(override val repr: Array[Int]) extends ArrayOps[Int] with ArrayLike[Int, Array[Int]] {
override protected[this] def thisCollection: WrappedArray[Int] = new WrappedArray.ofInt(repr)
@@ -120,6 +150,7 @@ object ArrayOps {
def update(index: Int, elem: Int) { repr(index) = elem }
}
+ /** A class of `ArrayOps` for arrays containing `long`s. */
class ofLong(override val repr: Array[Long]) extends ArrayOps[Long] with ArrayLike[Long, Array[Long]] {
override protected[this] def thisCollection: WrappedArray[Long] = new WrappedArray.ofLong(repr)
@@ -131,6 +162,7 @@ object ArrayOps {
def update(index: Int, elem: Long) { repr(index) = elem }
}
+ /** A class of `ArrayOps` for arrays containing `float`s. */
class ofFloat(override val repr: Array[Float]) extends ArrayOps[Float] with ArrayLike[Float, Array[Float]] {
override protected[this] def thisCollection: WrappedArray[Float] = new WrappedArray.ofFloat(repr)
@@ -142,6 +174,7 @@ object ArrayOps {
def update(index: Int, elem: Float) { repr(index) = elem }
}
+ /** A class of `ArrayOps` for arrays containing `double`s. */
class ofDouble(override val repr: Array[Double]) extends ArrayOps[Double] with ArrayLike[Double, Array[Double]] {
override protected[this] def thisCollection: WrappedArray[Double] = new WrappedArray.ofDouble(repr)
@@ -153,6 +186,7 @@ object ArrayOps {
def update(index: Int, elem: Double) { repr(index) = elem }
}
+ /** A class of `ArrayOps` for arrays containing `boolean`s. */
class ofBoolean(override val repr: Array[Boolean]) extends ArrayOps[Boolean] with ArrayLike[Boolean, Array[Boolean]] {
override protected[this] def thisCollection: WrappedArray[Boolean] = new WrappedArray.ofBoolean(repr)
@@ -164,6 +198,7 @@ object ArrayOps {
def update(index: Int, elem: Boolean) { repr(index) = elem }
}
+ /** A class of `ArrayOps` for arrays of `Unit` types. */
class ofUnit(override val repr: Array[Unit]) extends ArrayOps[Unit] with ArrayLike[Unit, Array[Unit]] {
override protected[this] def thisCollection: WrappedArray[Unit] = new WrappedArray.ofUnit(repr)
diff --git a/src/library/scala/collection/mutable/ArraySeq.scala b/src/library/scala/collection/mutable/ArraySeq.scala
index f6f958601d..d59cf684b2 100644
--- a/src/library/scala/collection/mutable/ArraySeq.scala
+++ b/src/library/scala/collection/mutable/ArraySeq.scala
@@ -21,6 +21,23 @@ import generic._
* @author Martin Odersky
* @version 2.8
* @since 2.8
+ *
+ * @tparam A type of the elements contained in this array sequence.
+ * @param length the length of the underlying array.
+ *
+ * @define Coll ArraySeq
+ * @define coll array sequence
+ * @define thatinfo the class of the returned collection. In the standard library configuration,
+ * `That` is always `ArraySeq[B]` because an implicit of type `CanBuildFrom[ArraySeq, B, ArraySeq[B]]`
+ * is defined in object `ArraySeq`.
+ * @define $bfinfo an implicit value of class `CanBuildFrom` which determines the
+ * result class `That` from the current representation type `Repr`
+ * and the new element type `B`. This is usually the `canBuildFrom` value
+ * defined in object `ArraySeq`.
+ * @define orderDependent
+ * @define orderDependentFold
+ * @define mayNotTerminateInf
+ * @define willNotTerminateInf
*/
class ArraySeq[A](override val length: Int)
extends IndexedSeq[A]
@@ -49,7 +66,7 @@ extends IndexedSeq[A]
}
}
- /** Fills the given array xs
with at most `len` elements of
+ /** 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.
@@ -64,7 +81,12 @@ extends IndexedSeq[A]
}
}
+/** $factoryInfo
+ * @define coll array sequence
+ * @define Coll ArraySeq
+ */
object ArraySeq extends SeqFactory[ArraySeq] {
+ /** $genericCanBuildFromInfo */
implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, ArraySeq[A]] = new GenericCanBuildFrom[A]
def newBuilder[A]: Builder[A, ArraySeq[A]] =
new ArrayBuffer[A] mapResult { buf =>
diff --git a/src/library/scala/collection/mutable/ArrayStack.scala b/src/library/scala/collection/mutable/ArrayStack.scala
index 8f9d1bfc88..0c6dc7a0e1 100644
--- a/src/library/scala/collection/mutable/ArrayStack.scala
+++ b/src/library/scala/collection/mutable/ArrayStack.scala
@@ -28,12 +28,20 @@ private object Utils {
}
}
-/**
- * Simple stack class backed by an array. Should be significantly faster
- * than the standard mutable stack.
+/** Simple stack class backed by an array. Should be significantly faster
+ * than the standard mutable stack.
*
- * @author David MacIver
- * @since 2.7
+ * @author David MacIver
+ * @since 2.7
+ *
+ * @tparam T type of the elements contained in this array stack.
+ *
+ * @define Coll ArrayStack
+ * @define coll array stack
+ * @define orderDependent
+ * @define orderDependentFold
+ * @define mayNotTerminateInf
+ * @define willNotTerminateInf
*/
@cloneable @serializable @SerialVersionUID(8565219180626620510L)
class ArrayStack[T] private(private var table : Array[AnyRef],
@@ -47,10 +55,9 @@ class ArrayStack[T] private(private var table : Array[AnyRef],
/** The number of elements in the stack */
def length = index
- /**
- * Push an element onto the stack.
+ /** Push an element onto the stack.
*
- * @param x The element to push
+ * @param x The element to push
*/
def push(x: T) {
if (index == table.length) table = Utils.growArray(table)
@@ -58,8 +65,9 @@ class ArrayStack[T] private(private var table : Array[AnyRef],
index += 1
}
- /**
- * Pop the top element off the stack.
+ /** Pop the top element off the stack.
+ *
+ * @return the element on top of the stack
*/
def pop: T = {
if (index == 0) error("Stack empty")
@@ -73,68 +81,73 @@ class ArrayStack[T] private(private var table : Array[AnyRef],
@deprecated("use top instead")
def peek = top
- /**
- * View the top element of the stack.
+ /** View the top element of the stack.
+ *
+ * Does not remove the element on the top. If the stack is empty,
+ * an exception is thrown.
+ *
+ * @return the element on top of the stack.
*/
def top: T = table(index - 1).asInstanceOf[T]
- /**
- * Duplicate the top element of the stack.
+ /** Duplicate the top element of the stack.
+ *
+ * After calling this method, the stack will have an additional element at
+ * the top equal to the element that was previously at the top.
+ * If the stack is empty, an exception is thrown.
*/
def dup = push(top)
- /**
- * Empties the stack.
- */
+ /** Empties the stack. */
def clear {
index = 0
table = new Array(1)
}
- /**
- * Empties the stack, passing all elements on it in FIFO order to the
- * provided function.
+ /** Empties the stack, passing all elements on it in LIFO order to the
+ * provided function.
*
- * @param f The function to drain to.
+ * @param f The function to drain to.
*/
def drain(f: T => Unit) = while (!isEmpty) f(pop)
- /**
- * Pushes all the provided elements onto the stack.
+ /** Pushes all the provided elements in the traversable object onto the stack.
*
- * @param x The source of elements to push
+ * @param x The source of elements to push.
+ * @return A reference to this stack.
*/
def ++=(xs: TraversableOnce[T]): this.type = { xs foreach += ; this }
- /**
- * Alias for push.
+ /** Does the same as `push`, but returns the updated stack.
*
- * @param x The element to push
+ * @param x The element to push.
+ * @return A reference to this stack.
*/
def +=(x: T): this.type = { push(x); this }
- /**
- * Pop the top two elements off the stack, apply f to them and push the result
- * back on to the stack.
+ /** Pop the top two elements off the stack, apply `f` to them and push the result
+ * back on to the stack.
*
- * @param f The combining function
+ * This function will throw an exception if stack contains fewer than 2 elements.
+ *
+ * @param f The function to apply to the top two elements.
*/
- def combine(f: (T, T) => T) = push(f(pop, pop));
+ def combine(f: (T, T) => T): Unit = push(f(pop, pop))
- /**
- * Repeatedly combine the top elements of the stack until the stack contains only
- * one element.
+ /** Repeatedly combine the top elements of the stack until the stack contains only
+ * one element.
+ *
+ * @param f The function to apply repeatedly to topmost elements.
*/
- def reduceWith(f: (T, T) => T) = while(size > 1) combine(f)
+ def reduceWith(f: (T, T) => T): Unit = while(size > 1) combine(f)
override def size = index
- /**
- * Evaluates the expression, preserving the contents of the stack so that
- * any changes the evaluation makes to the stack contents will be undone after
- * it completes.
+ /** Evaluates the expression, preserving the contents of the stack so that
+ * any changes the evaluation makes to the stack contents will be undone after
+ * it completes.
*
- * @param action The action to run.
+ * @param action The action to run.
*/
def preserving[T](action: => T) = {
val oldIndex = index
@@ -150,8 +163,8 @@ class ArrayStack[T] private(private var table : Array[AnyRef],
override def isEmpty: Boolean = index == 0
- /**
- * Iterates over the stack in LIFO order.
+ /** Creates and iterator over the stack in LIFO order.
+ * @return an iterator over the elements of the stack.
*/
def iterator: Iterator[T] = new Iterator[T] {
var currentIndex = index
diff --git a/src/library/scala/collection/mutable/BitSet.scala b/src/library/scala/collection/mutable/BitSet.scala
index 92dad18956..5d0f5863ca 100644
--- a/src/library/scala/collection/mutable/BitSet.scala
+++ b/src/library/scala/collection/mutable/BitSet.scala
@@ -16,11 +16,22 @@ import generic._
import BitSetLike.{LogWL, updateArray}
/** A class for mutable bitsets.
+ *
* $bitsetinfo
*
- * @author Martin Odersky
- * @version 2.8
- * @since 1
+ * @define Coll BitSet
+ * @define coll bitset
+ * @define thatinfo the class of the returned collection. In the standard library configuration,
+ * `That` is always `BitSet[B]` because an implicit of type `CanBuildFrom[BitSet, B, BitSet]`
+ * is defined in object `BitSet`.
+ * @define $bfinfo an implicit value of class `CanBuildFrom` which determines the
+ * result class `That` from the current representation type `Repr`
+ * and the new element type `B`. This is usually the `canBuildFrom` value
+ * defined in object `BitSet`.
+ * @define orderDependent
+ * @define orderDependentFold
+ * @define mayNotTerminateInf
+ * @define willNotTerminateInf
*/
@serializable @SerialVersionUID(8483111450368547763L)
class BitSet(protected var elems: Array[Long]) extends Set[Int]
@@ -30,6 +41,10 @@ class BitSet(protected var elems: Array[Long]) extends Set[Int]
override def empty = BitSet.empty
+ /** Creates the bitset of a certain initial size.
+ *
+ * @param initSize initial size of the bitset.
+ */
def this(initSize: Int) = this(new Array[Long]((initSize + 63) >> 6 max 1))
def this() = this(0)
@@ -79,7 +94,10 @@ class BitSet(protected var elems: Array[Long]) extends Set[Int]
/** Wraps this bitset as an immutable bitset backed by the array of bits
* of this bitset.
+ *
* @note Subsequent changes in this bitset will be reflected in the returned immutable bitset.
+ *
+ * @return an immutable set containing all the elements of this set.
*/
def toImmutable = immutable.BitSet.fromArray(elems)
@@ -90,8 +108,12 @@ class BitSet(protected var elems: Array[Long]) extends Set[Int]
}
}
+/** $factoryInfo
+ * @define coll bitset
+ * @define Coll BitSet
+ */
object BitSet extends BitSetFactory[BitSet] {
def empty: BitSet = new BitSet
- /** $canBuildFromInfo */
+ /** $bitsetCanBuildFrom */
implicit def canBuildFrom: CanBuildFrom[BitSet, Int, BitSet] = bitsetCanBuildFrom
}
diff --git a/src/library/scala/collection/mutable/Buffer.scala b/src/library/scala/collection/mutable/Buffer.scala
index 1c8aeb6b7a..fbc52ae322 100644
--- a/src/library/scala/collection/mutable/Buffer.scala
+++ b/src/library/scala/collection/mutable/Buffer.scala
@@ -18,12 +18,17 @@ import generic._
* appending, prepending, or inserting new elements. It is also
* possible to access and modify elements in a random access fashion
* via the index of the element in the current sequence.
- *
+ *
* @author Matthias Zenger
* @author Martin Odersky
* @version 2.8
* @since 1
- */
+ *
+ * @tparam A type of the elements contained in this buffer.
+ *
+ * @define Coll Buffer
+ * @define coll buffer
+ */
@cloneable
trait Buffer[A] extends Seq[A]
with GenericTraversableTemplate[A, Buffer]
@@ -31,7 +36,9 @@ trait Buffer[A] extends Seq[A]
override def companion: GenericCompanion[Buffer] = Buffer
}
-/** Factory object for Buffer
trait.
+/** $factoryInfo
+ * @define coll buffer
+ * @define Coll Buffer
*/
object Buffer extends SeqFactory[Buffer] {
implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, Buffer[A]] = new GenericCanBuildFrom[A]
diff --git a/src/library/scala/collection/mutable/BufferLike.scala b/src/library/scala/collection/mutable/BufferLike.scala
index 0fb34cc8e0..15e96b2019 100644
--- a/src/library/scala/collection/mutable/BufferLike.scala
+++ b/src/library/scala/collection/mutable/BufferLike.scala
@@ -144,8 +144,8 @@ trait BufferLike[A, +This <: BufferLike[A, This] with Buffer[A]]
*/
def append(elems: A*) { appendAll(elems) }
- /** Appends the elements contained in a traversable collection to this buffer.
- * @param elems the collection containing the elements to append.
+ /** Appends the elements contained in a traversable object to this buffer.
+ * @param xs the traversable object containing the elements to append.
*/
def appendAll(xs: TraversableOnce[A]) { this ++= xs }
@@ -154,7 +154,7 @@ trait BufferLike[A, +This <: BufferLike[A, This] with Buffer[A]]
*/
def prepend(elems: A*) { prependAll(elems) }
- /** Prepends the elements contained in a traversable collection to this buffer.
+ /** Prepends the elements contained in a traversable object to this buffer.
* @param elems the collection containing the elements to prepend.
*/
def prependAll(xs: TraversableOnce[A]) { xs ++=: this }
@@ -272,7 +272,7 @@ trait BufferLike[A, +This <: BufferLike[A, This] with Buffer[A]]
/** Adds a number of elements provided by a traversable object and returns
* either the collection itself.
*
- * @param iter the iterable object.
+ * @param xs the traversable object.
*/
@migration(2, 8,
"As of 2.8, ++ always creates a new collection, even on Buffers.\n"+
diff --git a/src/library/scala/collection/mutable/BufferProxy.scala b/src/library/scala/collection/mutable/BufferProxy.scala
index d4444dab67..983572452b 100644
--- a/src/library/scala/collection/mutable/BufferProxy.scala
+++ b/src/library/scala/collection/mutable/BufferProxy.scala
@@ -16,13 +16,18 @@ import generic._
import script._
/** This is a simple proxy class for scala.collection.mutable.Buffer
.
+ * target="contentFrame">`scala.collection.mutable.Buffer`.
* It is most useful for assembling customized set abstractions
* dynamically using object composition and forwarding.
*
* @author Matthias Zenger
* @version 1.0, 16/04/2004
* @since 1
+ *
+ * @tparam A type of the elements the buffer proxy contains.
+ *
+ * @define Coll BufferProxy
+ * @define coll buffer proxy
*/
trait BufferProxy[A] extends Buffer[A] with Proxy {
@@ -52,21 +57,21 @@ trait BufferProxy[A] extends Buffer[A] with Proxy {
override def readOnly = self.readOnly
- /** Appends a number of elements provided by an iterable object
- * via its iterator
method. The identity of the
+ /** Appends a number of elements provided by a traversable object
+ * via its foreach
method. The identity of the
* buffer is returned.
*
- * @param iter the iterable object.
+ * @param iter the traversable object.
* @return the updated buffer.
*/
@deprecated("Use ++= instead if you intend to add by side effect to an existing collection.\n"+
"Use `clone() ++=` if you intend to create a new collection.")
override def ++(xs: TraversableOnce[A]): Buffer[A] = self.++(xs)
- /** Appends a number of elements provided by an iterable object
- * via its iterator
method.
+ /** Appends a number of elements provided by a traversable object.
*
- * @param iter the iterable object.
+ * @param xs the traversable object.
+ * @return a reference to this $coll.
*/
override def ++=(xs: TraversableOnce[A]): this.type = { self.++=(xs); this }
@@ -76,10 +81,9 @@ trait BufferProxy[A] extends Buffer[A] with Proxy {
*/
override def append(elems: A*) { self.++=(elems) }
- /** Appends a number of elements provided by an iterable object
- * via its iterator
method.
+ /** Appends a number of elements provided by a traversable object.
*
- * @param iter the iterable object.
+ * @param xs the traversable object.
*/
override def appendAll(xs: TraversableOnce[A]) { self.appendAll(xs) }
@@ -87,6 +91,7 @@ trait BufferProxy[A] extends Buffer[A] with Proxy {
* the identity of the buffer.
*
* @param elem the element to append.
+ * @return a reference to this $coll.
*/
def +=:(elem: A): this.type = { self.+=:(elem); this }
@@ -98,26 +103,25 @@ trait BufferProxy[A] extends Buffer[A] with Proxy {
*/
override def prepend(elems: A*) { self.prependAll(elems) }
- /** Prepends a number of elements provided by an iterable object
- * via its iterator
method. The identity of the
- * buffer is returned.
+ /** Prepends a number of elements provided by a traversable object.
+ * The identity of the buffer is returned.
*
- * @param iter the iterable object.
+ * @param xs the traversable object.
*/
override def prependAll(xs: TraversableOnce[A]) { self.prependAll(xs) }
- /** Inserts new elements at the index n
. Opposed to method
- * update
, this method will not replace an element with a
- * one. Instead, it will insert the new elements at index n
.
+ /** Inserts new elements at the index `n`. Opposed to method
+ * `update`, this method will not replace an element with a
+ * one. Instead, it will insert the new elements at index `n`.
*
* @param n the index where a new element will be inserted.
* @param elems the new elements to insert.
*/
override def insert(n: Int, elems: A*) { self.insertAll(n, elems) }
- /** Inserts new elements at the index n
. Opposed to method
- * update
, this method will not replace an element with a
- * one. Instead, it will insert a new element at index n
.
+ /** Inserts new elements at the index `n`. Opposed to method
+ * `update`, this method will not replace an element with a
+ * one. Instead, it will insert a new element at index `n`.
*
* @param n the index where a new element will be inserted.
* @param iter the iterable object providing all elements to insert.
@@ -126,8 +130,7 @@ trait BufferProxy[A] extends Buffer[A] with Proxy {
override def insertAll(n: Int, iter: scala.collection.Traversable[A]): Unit = self.insertAll(n, iter)
- /** Replace element at index n
with the new element
- * newelem
.
+ /** Replace element at index `n` with the new element `newelem`.
*
* @param n the index of the element to replace.
* @param newelem the new element.
@@ -152,7 +155,7 @@ trait BufferProxy[A] extends Buffer[A] with Proxy {
/** Return a clone of this buffer.
*
- * @return a Buffer
with the same elements.
+ * @return a `Buffer` with the same elements.
*/
override def clone(): Buffer[A] = new BufferProxy[A] {
def self = BufferProxy.this.self.clone()
diff --git a/src/library/scala/collection/mutable/Builder.scala b/src/library/scala/collection/mutable/Builder.scala
index 2e6a9149bc..a930c29948 100644
--- a/src/library/scala/collection/mutable/Builder.scala
+++ b/src/library/scala/collection/mutable/Builder.scala
@@ -15,7 +15,7 @@ import generic._
/** The base trait of all builders.
* A builder lets one construct a collection incrementally, by adding
- * elements to the builder with += and then converting to the required
+ * elements to the builder with `+=` and then converting to the required
* collection type with `result`.
*
* @tparam Elem the type of elements that get added to the builder.
diff --git a/src/library/scala/collection/mutable/Cloneable.scala b/src/library/scala/collection/mutable/Cloneable.scala
index 34e0548cb8..099c6a68b4 100644
--- a/src/library/scala/collection/mutable/Cloneable.scala
+++ b/src/library/scala/collection/mutable/Cloneable.scala
@@ -14,7 +14,9 @@ package mutable
/** A trait for cloneable collections.
*
- * @since 2.8
+ * @since 2.8
+ *
+ * @tparam A Type of the elements contained in the collection, covariant and with reference types as upperbound.
*/
@cloneable
trait Cloneable[+A <: AnyRef] {
diff --git a/src/library/scala/collection/mutable/CloneableCollection.scala b/src/library/scala/collection/mutable/CloneableCollection.scala
index f859b9e82b..a88d85965f 100644
--- a/src/library/scala/collection/mutable/CloneableCollection.scala
+++ b/src/library/scala/collection/mutable/CloneableCollection.scala
@@ -12,8 +12,8 @@
package scala.collection
package mutable
-/** The J2ME version of the library defined this trait with a clone
- * method to substitute for the lack of Object.clone
there.
+/** The J2ME version of the library defined this trait with a `clone`
+ * method to substitute for the lack of `Object.clone` there.
*
* @since 2.6
*/
diff --git a/src/library/scala/collection/mutable/ConcurrentMap.scala b/src/library/scala/collection/mutable/ConcurrentMap.scala
index 2cfa4f8ae2..f9505f694b 100644
--- a/src/library/scala/collection/mutable/ConcurrentMap.scala
+++ b/src/library/scala/collection/mutable/ConcurrentMap.scala
@@ -1,23 +1,26 @@
package scala.collection
package mutable
-/**
- * A template trait for mutable maps that allow concurrent access.
- * $concurrentmapinfo
+
+/** A template trait for mutable maps that allow concurrent access.
+ *
+ * $concurrentmapinfo
*
- * @tparam A the key type of the map
- * @tparam B the value type of the map
+ * @since 2.8
*
- * @define concurrentmapinfo
- * 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.
+ * @tparam A the key type of the map
+ * @tparam B the value type of the map
*
- * @define atomicop
- * This is done atomically.
+ * @define Coll ConcurrentMap
+ * @define coll concurrent map
+ * @define concurrentmapinfo
+ * 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.
*
- * @since 2.8
+ * @define atomicop
+ * This is done atomically.
*/
trait ConcurrentMap[A, B] extends Map[A, B] {
diff --git a/src/library/scala/collection/mutable/DefaultEntry.scala b/src/library/scala/collection/mutable/DefaultEntry.scala
index 6071efcb9a..553fb3c678 100644
--- a/src/library/scala/collection/mutable/DefaultEntry.scala
+++ b/src/library/scala/collection/mutable/DefaultEntry.scala
@@ -12,8 +12,10 @@
package scala.collection
package mutable
-/**
- * @since 2.3
+
+
+/** Class used internally for default map model.
+ * @since 2.3
*/
@serializable
final class DefaultEntry[A, B](val key: A, var value: B)
diff --git a/src/library/scala/collection/mutable/DefaultMapModel.scala b/src/library/scala/collection/mutable/DefaultMapModel.scala
index fbe46e2a72..d22b20e10c 100644
--- a/src/library/scala/collection/mutable/DefaultMapModel.scala
+++ b/src/library/scala/collection/mutable/DefaultMapModel.scala
@@ -12,9 +12,8 @@
package scala.collection
package mutable
-/** This class is used internally. It implements the mutable Map
- * class in terms of three functions: findEntry
,
- * addEntry
, and entries
.
+/** This class is used internally. It implements the mutable `Map`
+ * class in terms of three functions: `findEntry`, `addEntry`, and `entries`.
*
* @author Matthias Zenger
* @version 1.0, 08/07/2003
diff --git a/src/library/scala/collection/mutable/DoubleLinkedList.scala b/src/library/scala/collection/mutable/DoubleLinkedList.scala
index 718d6aa35d..d8b8278c74 100644
--- a/src/library/scala/collection/mutable/DoubleLinkedList.scala
+++ b/src/library/scala/collection/mutable/DoubleLinkedList.scala
@@ -14,13 +14,29 @@ package mutable
import generic._
-/** This class implements double linked lists where both the head (elem
)
- * and the tail (next
) are mutable.
+/** This class implements double linked lists where both the head (`elem`),
+ * the tail (`next`) and a reference to the previous node (`prev`) are mutable.
*
* @author Matthias Zenger
* @author Martin Odersky
* @version 2.8
* @since 1
+ *
+ * @tparam A the type of the elements contained in this double linked list.
+ *
+ * @define Coll DoubleLinkedList
+ * @define coll double linked list
+ * @define thatinfo the class of the returned collection. In the standard library configuration,
+ * `That` is always `DoubleLinkedList[B]` because an implicit of type `CanBuildFrom[DoubleLinkedList, B, DoubleLinkedList[B]]`
+ * is defined in object `DoubleLinkedList`.
+ * @define $bfinfo an implicit value of class `CanBuildFrom` which determines the
+ * result class `That` from the current representation type `Repr`
+ * and the new element type `B`. This is usually the `canBuildFrom` value
+ * defined in object `DoubleLinkedList`.
+ * @define orderDependent
+ * @define orderDependentFold
+ * @define mayNotTerminateInf
+ * @define willNotTerminateInf
*/
@serializable @SerialVersionUID(-8144992287952814767L)
class DoubleLinkedList[A]() extends LinearSeq[A]
@@ -28,6 +44,11 @@ class DoubleLinkedList[A]() extends LinearSeq[A]
with DoubleLinkedListLike[A, DoubleLinkedList[A]] {
next = this
+ /** Creates a node for the double linked list.
+ *
+ * @param elem the element this node contains.
+ * @param next the next node in the double linked list.
+ */
def this(elem: A, next: DoubleLinkedList[A]) {
this()
if (next != null) {
@@ -39,7 +60,12 @@ class DoubleLinkedList[A]() extends LinearSeq[A]
override def companion: GenericCompanion[DoubleLinkedList] = DoubleLinkedList
}
+/** $factoryInfo
+ * @define coll double linked list
+ * @define Coll DoubleLinkedList
+ */
object DoubleLinkedList extends SeqFactory[DoubleLinkedList] {
+ /** $genericCanBuildFrom */
implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, DoubleLinkedList[A]] = new GenericCanBuildFrom[A]
def newBuilder[A]: Builder[A, DoubleLinkedList[A]] =
new Builder[A, DoubleLinkedList[A]] {
diff --git a/src/library/scala/collection/mutable/DoubleLinkedListLike.scala b/src/library/scala/collection/mutable/DoubleLinkedListLike.scala
index 269d1997d0..b908a1802b 100644
--- a/src/library/scala/collection/mutable/DoubleLinkedListLike.scala
+++ b/src/library/scala/collection/mutable/DoubleLinkedListLike.scala
@@ -13,16 +13,23 @@ package scala.collection
package mutable
/** This extensible class may be used as a basis for implementing double
- * linked lists. Type variable A
refers to the element type
- * of the list, type variable This
is used to model self
+ * linked lists. Type variable `A` refers to the element type
+ * of the list, type variable `This` is used to model self
* types of linked lists.
*
* @author Matthias Zenger
* @version 1.0, 08/07/2003
* @since 2.8
+ *
+ * @tparam A type of the elements contained in the double linked list
+ * @tparam This the type of the actual linked list holding the elements
+ *
+ * @define Coll DoubleLinkedList
+ * @define coll double linked list
*/
trait DoubleLinkedListLike[A, This <: Seq[A] with DoubleLinkedListLike[A, This]] extends LinkedListLike[A, This] { self =>
+ /** A reference to the node in the linked list preceeding the current node. */
var prev: This = _
override def append(that: This): This =
diff --git a/src/library/scala/collection/mutable/FlatHashTable.scala b/src/library/scala/collection/mutable/FlatHashTable.scala
index ea4033d405..05eafbc811 100644
--- a/src/library/scala/collection/mutable/FlatHashTable.scala
+++ b/src/library/scala/collection/mutable/FlatHashTable.scala
@@ -11,8 +11,15 @@
package scala.collection
package mutable
-/** An implementation class backing a HashSet.
- * @since 2.3
+
+/** An implementation class backing a `HashSet`.
+ *
+ * This trait is used internally. It can be mixed in with various collections relying on
+ * hash table as an implementation.
+ *
+ * @since 2.3
+ *
+ * @tparam A the type of the elements contained in the flat hash table.
*/
trait FlatHashTable[A] {
@@ -85,6 +92,7 @@ trait FlatHashTable[A] {
iterator.foreach(out.writeObject)
}
+ /** Finds an entry in the hash table if such an element exists. */
def findEntry(elem: A): Option[A] = {
var h = index(elemHashCode(elem))
var entry = table(h)
@@ -95,6 +103,7 @@ trait FlatHashTable[A] {
if (null == entry) None else Some(entry.asInstanceOf[A])
}
+ /** Checks whether an element is contained in the hash table. */
def containsEntry(elem: A): Boolean = {
var h = index(elemHashCode(elem))
var entry = table(h)
@@ -105,8 +114,8 @@ trait FlatHashTable[A] {
null != entry
}
- /** Add entry if not yet in table
- * Return whether a new entry was added
+ /** Add entry if not yet in table.
+ * @return Returns `true` if a new entry was added, `false` otherwise.
*/
def addEntry(elem: A) : Boolean = {
var h = index(elemHashCode(elem))
@@ -122,6 +131,7 @@ trait FlatHashTable[A] {
true
}
+ /** Removes an entry from the hash table, returning an option value with the element, or `None` if it didn't exist. */
def removeEntry(elem: A) : Option[A] = {
if (tableDebug) checkConsistent()
def precedes(i: Int, j: Int) = {
diff --git a/src/library/scala/collection/mutable/GrowingBuilder.scala b/src/library/scala/collection/mutable/GrowingBuilder.scala
index 445e9d4f3e..cd1c8bec8c 100644
--- a/src/library/scala/collection/mutable/GrowingBuilder.scala
+++ b/src/library/scala/collection/mutable/GrowingBuilder.scala
@@ -13,14 +13,17 @@ import generic._
/** The canonical builder for collections that are growable, i.e. that support an
* efficient `+=` method which adds an element to the collection. It is
- * almost identical to AddingBuilder, but necessitated by the existence of
- * classes which are Growable but not Addable, which is a result of covariance
- * interacting surprisingly with any2stringadd thus driving '+' out of the Seq
+ * almost identical to `AddingBuilder`, but necessitated by the existence of
+ * classes which are `Growable` but not `Addable`, which is a result of covariance
+ * interacting surprisingly with any2stringadd thus driving '+' out of the `Seq`
* hierarchy. The tendrils of original sin should never be underestimated.
*
* @author Paul Phillips
* @version 2.8
* @since 2.8
+ *
+ * @define Coll GrowingBuilder
+ * @define coll growing builder
*/
class GrowingBuilder[Elem, To <: Growable[Elem]](empty: To) extends Builder[Elem, To] {
protected var elems: To = empty
diff --git a/src/library/scala/collection/mutable/HashEntry.scala b/src/library/scala/collection/mutable/HashEntry.scala
index 3373913412..7c62dc6281 100644
--- a/src/library/scala/collection/mutable/HashEntry.scala
+++ b/src/library/scala/collection/mutable/HashEntry.scala
@@ -8,8 +8,8 @@
package scala.collection
package mutable
-/**
- * @since 2.8
+/** Class used internally.
+ * @since 2.8
*/
trait HashEntry [A, E] {
val key: A
diff --git a/src/library/scala/collection/mutable/HashMap.scala b/src/library/scala/collection/mutable/HashMap.scala
index 2b5cad37d8..215e0323b3 100644
--- a/src/library/scala/collection/mutable/HashMap.scala
+++ b/src/library/scala/collection/mutable/HashMap.scala
@@ -14,8 +14,27 @@ package mutable
import generic._
-/**
- * @since 1
+
+/** This class implements mutable maps using a hashtable.
+ *
+ * @since 1
+ *
+ * @tparam A the type of the keys contained in this hash map.
+ * @tparam B the type of the values assigned to keys in this hash map.
+ *
+ * @define Coll mutable.HashMap
+ * @define coll mutable hash map
+ * @define thatinfo the class of the returned collection. In the standard library configuration,
+ * `That` is always `HashMap[A, B]` if the elements contained in the resulting collection are
+ * pairs of type `(A, B)`. This is because an implicit of type `CanBuildFrom[HashMap, (A, B), HashMap[A, B]]`
+ * is defined in object `HashMap`. Otherwise, `That` resolves to the most specific type that doesn't have
+ * to contain pairs of type `(A, B)`, which is `Iterable`.
+ * @define $bfinfo an implicit value of class `CanBuildFrom` which determines the
+ * result class `That` from the current representation type `Repr`
+ * and the new element type `B`. This is usually the `canBuildFrom` value
+ * defined in object `HashMap`.
+ * @define mayNotTerminateInf
+ * @define willNotTerminateInf
*/
@serializable @SerialVersionUID(1L)
class HashMap[A, B] extends Map[A, B]
@@ -94,11 +113,9 @@ class HashMap[A, B] extends Map[A, B]
}
}
-/** This class implements mutable maps using a hashtable.
- *
- * @author Matthias Zenger
- * @author Martin Odersky
- * @version 2.8
+/** $factoryInfo
+ * @define Coll mutable.HashMap
+ * @define coll mutable hash map
*/
object HashMap extends MutableMapFactory[HashMap] {
implicit def canBuildFrom[A, B]: CanBuildFrom[Coll, (A, B), HashMap[A, B]] = new MapCanBuildFrom[A, B]
diff --git a/src/library/scala/collection/mutable/HashSet.scala b/src/library/scala/collection/mutable/HashSet.scala
index e985e717b0..3d9dc3e55d 100644
--- a/src/library/scala/collection/mutable/HashSet.scala
+++ b/src/library/scala/collection/mutable/HashSet.scala
@@ -20,6 +20,20 @@ import generic._
* @author Martin Odersky
* @version 2.0, 31/12/2006
* @since 1
+ *
+ * @tparam A the type of the elements contained in this set.
+ *
+ * @define Coll mutable.HashSet
+ * @define coll mutable hash set
+ * @define thatinfo the class of the returned collection. In the standard library configuration,
+ * `That` is always `HashSet[B]` because an implicit of type `CanBuildFrom[HashSet, B, HashSet[B]]`
+ * is defined in object `HashSet`.
+ * @define $bfinfo an implicit value of class `CanBuildFrom` which determines the
+ * result class `That` from the current representation type `Repr`
+ * and the new element type `B`. This is usually the `canBuildFrom` value
+ * defined in object `HashSet`.
+ * @define mayNotTerminateInf
+ * @define willNotTerminateInf
*/
@serializable @SerialVersionUID(1L)
class HashSet[A] extends Set[A]
@@ -61,7 +75,10 @@ class HashSet[A] extends Set[A]
}
}
-/** Factory object for `HashSet` class */
+/** $factoryInfo
+ * @define Coll mutable.HashSet
+ * @define coll mutable hash set
+ */
object HashSet extends SetFactory[HashSet] {
implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, HashSet[A]] = setCanBuildFrom[A]
override def empty[A]: HashSet[A] = new HashSet[A]
diff --git a/src/library/scala/collection/mutable/HashTable.scala b/src/library/scala/collection/mutable/HashTable.scala
index 14f1720a4c..04b5e5e3a1 100644
--- a/src/library/scala/collection/mutable/HashTable.scala
+++ b/src/library/scala/collection/mutable/HashTable.scala
@@ -13,22 +13,24 @@ package scala.collection
package mutable
/** This class can be used to construct data structures that are based
- * on hashtables. Class HashTable[A]
implements a hashtable
- * that maps keys of type A
to values of the fully abstract
- * member type Entry
. Classes that make use of HashTable
- * have to provide an implementation for Entry
+ * on hashtables. Class `HashTable[A]` implements a hashtable
+ * that maps keys of type `A` to values of the fully abstract
+ * member type `Entry`. Classes that make use of `HashTable`
+ * have to provide an implementation for `Entry`.
*
* There are mainly two parameters that affect the performance of a hashtable:
* the initial size and the load factor. The size
* refers to the number of buckets in the hashtable, and the load
* factor is a measure of how full the hashtable is allowed to get before
* its size is automatically doubled. Both parameters may be changed by
- * overriding the corresponding values in class HashTable
.
+ * overriding the corresponding values in class `HashTable`.
*
* @author Matthias Zenger
* @author Martin Odersky
* @version 2.0, 31/12/2006
* @since 1
+ *
+ * @tparam A type of the elements contained in this hash table.
*/
trait HashTable[A] {
import HashTable._
@@ -108,7 +110,7 @@ trait HashTable[A] {
private def capacity(expectedSize: Int) = if (expectedSize == 0) 1 else powerOfTwo(expectedSize)
- /** Find entry with given key in table, null if not found
+ /** Find entry with given key in table, null if not found.
*/
protected def findEntry(key: A): Entry = {
val h = index(elemHashCode(key))
@@ -129,7 +131,7 @@ trait HashTable[A] {
resize(2 * table.length)
}
- /** Remove entry from table if present
+ /** Remove entry from table if present.
*/
protected def removeEntry(key: A) : Entry = {
val h = index(elemHashCode(key))
@@ -155,7 +157,7 @@ trait HashTable[A] {
null
}
- /** An iterator returning all entries
+ /** An iterator returning all entries.
*/
protected def entriesIterator: Iterator[Entry] = new Iterator[Entry] {
val iterTable = table
diff --git a/src/library/scala/collection/mutable/History.scala b/src/library/scala/collection/mutable/History.scala
index 40ebfe5fa5..ffa3d6481a 100644
--- a/src/library/scala/collection/mutable/History.scala
+++ b/src/library/scala/collection/mutable/History.scala
@@ -13,14 +13,17 @@ package scala.collection
package mutable
-/** History[A, B]
objects may subscribe to events of
- * type A
published by an object of type B
.
+/** `History[A, B]` objects may subscribe to events of
+ * type `A` published by an object of type `B`.
* The history subscriber object records all published events
- * up to maximum number of maxHistory
events.
+ * up to maximum number of `maxHistory` events.
*
* @author Matthias Zenger
* @version 1.0, 08/07/2003
* @since 1
+ *
+ * @tparam Evt Type of events.
+ * @tparam Pub Type of publishers.
*/
@serializable
@SerialVersionUID(5219213543849892588L)
@@ -29,9 +32,10 @@ class History[Evt, Pub] extends Subscriber[Evt, Pub] with Iterable[(Pub, Evt)]
protected val log: Queue[(Pub, Evt)] = new Queue
val maxHistory: Int = 1000
- /**
- * @param pub ...
- * @param event ...
+ /** Notifies this listener with an event by enqueuing it in the log.
+ *
+ * @param pub the publisher.
+ * @param event the event.
*/
def notify(pub: Pub, event: Evt) {
if (log.length >= maxHistory)
diff --git a/src/library/scala/collection/mutable/ImmutableMapAdaptor.scala b/src/library/scala/collection/mutable/ImmutableMapAdaptor.scala
index fba28e7c2a..c2b7cfd2b8 100644
--- a/src/library/scala/collection/mutable/ImmutableMapAdaptor.scala
+++ b/src/library/scala/collection/mutable/ImmutableMapAdaptor.scala
@@ -15,9 +15,9 @@ package mutable
import annotation.migration
/** This class can be used as an adaptor to create mutable maps from
- * immutable map implementations. Only method empty
has
+ * immutable map implementations. Only method `empty` has
* to be redefined if the immutable map on which this mutable map is
- * originally based is not empty. empty
is supposed to
+ * originally based is not empty. `empty` is supposed to
* return the representation of an empty map.
*
* @author Matthias Zenger
diff --git a/src/library/scala/collection/mutable/ImmutableSetAdaptor.scala b/src/library/scala/collection/mutable/ImmutableSetAdaptor.scala
index 5b0ed17788..a56f65e379 100644
--- a/src/library/scala/collection/mutable/ImmutableSetAdaptor.scala
+++ b/src/library/scala/collection/mutable/ImmutableSetAdaptor.scala
@@ -14,9 +14,9 @@ package mutable
/** This class can be used as an adaptor to create mutable sets from
- * immutable set implementations. Only method empty
has
+ * immutable set implementations. Only method `empty` has
* to be redefined if the immutable set on which this mutable set is
- * originally based is not empty. empty
is supposed to
+ * originally based is not empty. `empty` is supposed to
* return the representation of an empty set.
*
* @author Matthias Zenger
diff --git a/src/library/scala/collection/mutable/IndexedSeq.scala b/src/library/scala/collection/mutable/IndexedSeq.scala
index 0a173395e0..14ee5afc9b 100644
--- a/src/library/scala/collection/mutable/IndexedSeq.scala
+++ b/src/library/scala/collection/mutable/IndexedSeq.scala
@@ -14,11 +14,10 @@ package mutable
import generic._
-/** A subtrait of collection.IndexedSeq
which represents sequences
+/** A subtrait of `collection.IndexedSeq` which represents sequences
* that can be mutated.
- * $indexedSeqInfo
*
- * @since 2.8
+ * $indexedSeqInfo
*/
trait IndexedSeq[A] extends Seq[A]
with scala.collection.IndexedSeq[A]
@@ -27,6 +26,10 @@ trait IndexedSeq[A] extends Seq[A]
override def companion: GenericCompanion[IndexedSeq] = IndexedSeq
}
+/** $factoryInfo
+ * @define coll indexed sequence
+ * @define Coll IndexedSeq
+ */
object IndexedSeq extends SeqFactory[IndexedSeq] {
implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, IndexedSeq[A]] = new GenericCanBuildFrom[A]
def newBuilder[A]: Builder[A, IndexedSeq[A]] = new ArrayBuffer[A]
diff --git a/src/library/scala/collection/mutable/IndexedSeqLike.scala b/src/library/scala/collection/mutable/IndexedSeqLike.scala
index a0f9205da2..0c2d3f17bb 100644
--- a/src/library/scala/collection/mutable/IndexedSeqLike.scala
+++ b/src/library/scala/collection/mutable/IndexedSeqLike.scala
@@ -16,7 +16,26 @@ import generic._
/** A subtrait of scala.collection.IndexedSeq which represents sequences
* that can be mutated.
*
- * @since 2.8
+ * It declares a method `update` which allows updating an element
+ * at a specific index in the sequence.
+ *
+ * This trait just implements `iterator` in terms of `apply` and `length`.
+ * However, see `IndexedSeqOptimized` for an implementation trait that overrides operations
+ * to make them run faster under the assumption of fast random access with `apply`.
+ *
+ * $indexedSeqInfo
+ *
+ * @tparam A the element type of the $coll
+ * @tparam Repr the type of the actual $coll containing the elements.
+ *
+ * @define Coll IndexedSeq
+ * @define coll mutable indexed sequence
+ * @define indexedSeqInfo
+ * @author Martin Odersky
+ * @version 2.8
+ * @since 2.8
+ * @define willNotTerminateInf
+ * @define mayNotTerminateInf
*/
trait IndexedSeqLike[A, +Repr] extends scala.collection.IndexedSeqLike[A, Repr] { self =>
diff --git a/src/library/scala/collection/mutable/IndexedSeqView.scala b/src/library/scala/collection/mutable/IndexedSeqView.scala
index d870b762d3..9a0e7a4010 100644
--- a/src/library/scala/collection/mutable/IndexedSeqView.scala
+++ b/src/library/scala/collection/mutable/IndexedSeqView.scala
@@ -92,6 +92,8 @@ self =>
}
/** $factoryInfo
+ * @define coll indexed sequence view
+ * @define Coll IndexedSeqView
* Note that the canBuildFrom factories yield SeqViews, not IndexedSewqViews.
* This is intentional, because not all operations yield again a mutable.IndexedSeqView.
* For instance, map just gives a SeqView, which reflects the fact that
diff --git a/src/library/scala/collection/mutable/Iterable.scala b/src/library/scala/collection/mutable/Iterable.scala
index 347ee3c8ac..85c6df6fb0 100644
--- a/src/library/scala/collection/mutable/Iterable.scala
+++ b/src/library/scala/collection/mutable/Iterable.scala
@@ -10,15 +10,8 @@ package mutable
import generic._
-/**
- * A subtrait of
- * collection.Iterable
which represents iterables
- * that can be mutated.
- *
- *
- * @author Martin Odersky
- * @version 2.8
- * @since 2.8
+/** A base trait for iterable collections that can be mutated.
+ * $iterableInfo
*/
trait Iterable[A] extends Traversable[A]
with scala.collection.Iterable[A]
@@ -27,13 +20,9 @@ trait Iterable[A] extends Traversable[A]
override def companion: GenericCompanion[Iterable] = Iterable
}
-/**
- * A factory object for the trait Iterable
.
- *
- *
- * @author Martin Odersky
- * @version 2.8
+/** $factoryInfo
+ * @define coll indexed sequence
+ * @define Coll IndexedSeq
*/
object Iterable extends TraversableFactory[Iterable] {
implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, Iterable[A]] = new GenericCanBuildFrom[A]
diff --git a/src/library/scala/collection/mutable/LazyBuilder.scala b/src/library/scala/collection/mutable/LazyBuilder.scala
index 7714d29f08..91cf8f2ad9 100644
--- a/src/library/scala/collection/mutable/LazyBuilder.scala
+++ b/src/library/scala/collection/mutable/LazyBuilder.scala
@@ -17,6 +17,9 @@ import immutable.{List, Nil}
* be added to this builder with `++=` are not evaluated until `result` is called.
*
* @since 2.8
+ *
+ * @tparam Elem type of the elements for this builder.
+ * @tparam To type of the collection this builder builds.
*/
abstract class LazyBuilder[Elem, +To] extends Builder[Elem, To] {
/** The different segments of elements to be added to the builder, represented as iterators */
diff --git a/src/library/scala/collection/mutable/LinearSeq.scala b/src/library/scala/collection/mutable/LinearSeq.scala
index 9abaef5aff..185b8c97a3 100644
--- a/src/library/scala/collection/mutable/LinearSeq.scala
+++ b/src/library/scala/collection/mutable/LinearSeq.scala
@@ -14,11 +14,12 @@ package mutable
import generic._
-/** A subtrait of collection.LinearSeq
which represents sequences
+/** A subtrait of `collection.LinearSeq` which represents sequences
* that can be mutated.
* $linearSeqInfo
*
- * @since 2.8
+ * @define Coll LinearSeq
+ * @define coll linear sequence
*/
trait LinearSeq[A] extends Seq[A]
with scala.collection.LinearSeq[A]
@@ -27,6 +28,10 @@ trait LinearSeq[A] extends Seq[A]
override def companion: GenericCompanion[LinearSeq] = LinearSeq
}
+/** $factoryInfo
+ * @define coll linear sequence
+ * @define Coll LinearSeq
+ */
object LinearSeq extends SeqFactory[LinearSeq] {
implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, LinearSeq[A]] = new GenericCanBuildFrom[A]
def newBuilder[A]: Builder[A, LinearSeq[A]] = new MutableList[A]
diff --git a/src/library/scala/collection/mutable/LinkedEntry.scala b/src/library/scala/collection/mutable/LinkedEntry.scala
index 46db4cdf09..5d591058e8 100644
--- a/src/library/scala/collection/mutable/LinkedEntry.scala
+++ b/src/library/scala/collection/mutable/LinkedEntry.scala
@@ -12,8 +12,8 @@
package scala.collection
package mutable
-/**
- * @since 2.8
+/** Class for the linked hash map entry, used internally.
+ * @since 2.8
*/
@serializable
final class LinkedEntry[A, B](val key: A, var value: B)
diff --git a/src/library/scala/collection/mutable/LinkedHashMap.scala b/src/library/scala/collection/mutable/LinkedHashMap.scala
index 2636219727..97961ccd9c 100644
--- a/src/library/scala/collection/mutable/LinkedHashMap.scala
+++ b/src/library/scala/collection/mutable/LinkedHashMap.scala
@@ -14,20 +14,36 @@ package mutable
import generic._
-/** This class implements mutable maps using a hashtable.
- * The iterator and all traversal methods of this class visit elements in the order they were inserted.
- *
- * @author Martin Odersky
- * @version 2.8
- * @since 2.7
+/** $factoryInfo
+ * @define Coll LinkedHashMap
+ * @define coll linked hash map
*/
object LinkedHashMap extends MutableMapFactory[LinkedHashMap] {
implicit def canBuildFrom[A, B]: CanBuildFrom[Coll, (A, B), LinkedHashMap[A, B]] = new MapCanBuildFrom[A, B]
def empty[A, B] = new LinkedHashMap[A, B]
}
-/**
- * @since 2.7
+/** This class implements mutable maps using a hashtable.
+ * The iterator and all traversal methods of this class visit elements in the order they were inserted.
+ *
+ * @tparam A the type of the keys contained in this hash map.
+ * @tparam B the type of the values assigned to keys in this hash map.
+ *
+ * @define Coll LinkedHashMap
+ * @define coll linked hash map
+ * @define thatinfo the class of the returned collection. In the standard library configuration,
+ * `That` is always `LinkedHashMap[A, B]` if the elements contained in the resulting collection are
+ * pairs of type `(A, B)`. This is because an implicit of type `CanBuildFrom[LinkedHashMap, (A, B), LinkedHashMap[A, B]]`
+ * is defined in object `LinkedHashMap`. Otherwise, `That` resolves to the most specific type that doesn't have
+ * to contain pairs of type `(A, B)`, which is `Iterable`.
+ * @define $bfinfo an implicit value of class `CanBuildFrom` which determines the
+ * result class `That` from the current representation type `Repr`
+ * and the new element type `B`. This is usually the `canBuildFrom` value
+ * defined in object `LinkedHashMap`.
+ * @define mayNotTerminateInf
+ * @define willNotTerminateInf
+ * @define orderDependent
+ * @define orderDependentFold
*/
@serializable @SerialVersionUID(1L)
class LinkedHashMap[A, B] extends Map[A, B]
diff --git a/src/library/scala/collection/mutable/LinkedHashSet.scala b/src/library/scala/collection/mutable/LinkedHashSet.scala
index 54338f61c9..7ecb71e23b 100644
--- a/src/library/scala/collection/mutable/LinkedHashSet.scala
+++ b/src/library/scala/collection/mutable/LinkedHashSet.scala
@@ -13,9 +13,29 @@ package mutable
import generic._
-/** Todo: this has O(n) cost for element removal.
- * Should be rewritten to be more efficient.
- * @since 2.2
+/** This class implements mutable sets using a hashtable.
+ * The iterator and all traversal methods of this class visit elements in the order they were inserted.
+ *
+ * @author Matthias Zenger
+ * @author Martin Odersky
+ * @version 2.0, 31/12/2006
+ * @since 1
+ *
+ * @tparam A the type of the elements contained in this set.
+ *
+ * @define Coll LinkedHashSet
+ * @define coll linked hash set
+ * @define thatinfo the class of the returned collection. In the standard library configuration,
+ * `That` is always `LinkedHashSet[B]` because an implicit of type `CanBuildFrom[LinkedHashSet, B, LinkedHashSet[B]]`
+ * is defined in object `LinkedHashSet`.
+ * @define $bfinfo an implicit value of class `CanBuildFrom` which determines the
+ * result class `That` from the current representation type `Repr`
+ * and the new element type `B`. This is usually the `canBuildFrom` value
+ * defined in object `LinkedHashSet`.
+ * @define mayNotTerminateInf
+ * @define willNotTerminateInf
+ * @define orderDependent
+ * @define orderDependentFold
*/
@serializable @SerialVersionUID(1L)
class LinkedHashSet[A] extends Set[A]
@@ -63,7 +83,10 @@ class LinkedHashSet[A] extends Set[A]
}
}
-/** Factory object for `LinkedHashSet` class */
+/** $factoryInfo
+ * @define Coll LinkedHashSet
+ * @define coll linked hash set
+ */
object LinkedHashSet extends SetFactory[LinkedHashSet] {
implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, LinkedHashSet[A]] = setCanBuildFrom[A]
override def empty[A]: LinkedHashSet[A] = new LinkedHashSet[A]
diff --git a/src/library/scala/collection/mutable/LinkedList.scala b/src/library/scala/collection/mutable/LinkedList.scala
index 5570e80b22..a72acf1438 100644
--- a/src/library/scala/collection/mutable/LinkedList.scala
+++ b/src/library/scala/collection/mutable/LinkedList.scala
@@ -14,13 +14,29 @@ package mutable
import generic._
-/** This class implements single linked lists where both the head (elem
)
- * and the tail (next
) are mutable.
+/** This class implements single linked lists where both the head (`elem`)
+ * and the tail (`next`) are mutable.
*
* @author Matthias Zenger
* @author Martin Odersky
* @version 2.8
* @since 1
+ *
+ * @tparam A the type of the elements contained in this linked list.
+ *
+ * @define Coll LinkedList
+ * @define coll linked list
+ * @define thatinfo the class of the returned collection. In the standard library configuration,
+ * `That` is always `LinkedList[B]` because an implicit of type `CanBuildFrom[LinkedList, B, LinkedList[B]]`
+ * is defined in object `LinkedList`.
+ * @define $bfinfo an implicit value of class `CanBuildFrom` which determines the
+ * result class `That` from the current representation type `Repr`
+ * and the new element type `B`. This is usually the `canBuildFrom` value
+ * defined in object `LinkedList`.
+ * @define orderDependent
+ * @define orderDependentFold
+ * @define mayNotTerminateInf
+ * @define willNotTerminateInf
*/
@serializable @SerialVersionUID(-7308240733518833071L)
class LinkedList[A]() extends LinearSeq[A]
@@ -39,6 +55,10 @@ class LinkedList[A]() extends LinearSeq[A]
override def companion: GenericCompanion[LinkedList] = LinkedList
}
+/** $factoryInfo
+ * @define Coll LinkedList
+ * @define coll linked list
+ */
object LinkedList extends SeqFactory[LinkedList] {
override def empty[A]: LinkedList[A] = new LinkedList[A]
diff --git a/src/library/scala/collection/mutable/LinkedListLike.scala b/src/library/scala/collection/mutable/LinkedListLike.scala
index 2523ece370..4f1a878e02 100644
--- a/src/library/scala/collection/mutable/LinkedListLike.scala
+++ b/src/library/scala/collection/mutable/LinkedListLike.scala
@@ -16,13 +16,20 @@ import generic._
import annotation.tailrec
/** This extensible class may be used as a basis for implementing linked
- * list. Type variable A
refers to the element type of the
- * list, type variable This
is used to model self types of
+ * list. Type variable `A` refers to the element type of the
+ * list, type variable `This` is used to model self types of
* linked lists.
+ *
* @author Matthias Zenger
* @author Martin Odersky
- * @version 2.8
+ * @version 1.0, 08/07/2003
* @since 2.8
+ *
+ * @tparam A type of the elements contained in the linked list
+ * @tparam This the type of the actual linked list holding the elements
+ *
+ * @define Coll LinkedList
+ * @define coll linked list
*/
trait LinkedListLike[A, This <: Seq[A] with LinkedListLike[A, This]] extends SeqLike[A, This] { self =>
diff --git a/src/library/scala/collection/mutable/ListBuffer.scala b/src/library/scala/collection/mutable/ListBuffer.scala
index b8e5aeb262..a2611a8c0f 100644
--- a/src/library/scala/collection/mutable/ListBuffer.scala
+++ b/src/library/scala/collection/mutable/ListBuffer.scala
@@ -15,13 +15,29 @@ package mutable
import generic._
import immutable.{List, Nil, ::}
-/** A Buffer implementation back up by a list. It provides constant time
+/** A `Buffer` implementation back up by a list. It provides constant time
* prepend and append. Most other operations are linear.
*
* @author Matthias Zenger
* @author Martin Odersky
* @version 2.8
* @since 1
+ *
+ * @tparam A the type of this list buffer's elements.
+ *
+ * @define Coll ListBuffer
+ * @define coll list buffer
+ * @define thatinfo the class of the returned collection. In the standard library configuration,
+ * `That` is always `ListBuffer[B]` because an implicit of type `CanBuildFrom[ListBuffer, B, ListBuffer[B]]`
+ * is defined in object `ListBuffer`.
+ * @define $bfinfo an implicit value of class `CanBuildFrom` which determines the
+ * result class `That` from the current representation type `Repr`
+ * and the new element type `B`. This is usually the `canBuildFrom` value
+ * defined in object `ListBuffer`.
+ * @define orderDependent
+ * @define orderDependentFold
+ * @define mayNotTerminateInf
+ * @define willNotTerminateInf
*/
@serializable @SerialVersionUID(3419063961353022661L)
final class ListBuffer[A]
@@ -42,7 +58,9 @@ final class ListBuffer[A]
protected def underlying: immutable.Seq[A] = start
- /** The current length of the buffer
+ /** The current length of the buffer.
+ *
+ * This operation takes constant time.
*/
override def length = len
@@ -52,13 +70,13 @@ final class ListBuffer[A]
if (n < 0 || n >= len) throw new IndexOutOfBoundsException(n.toString())
else super.apply(n)
- /** Replaces element at index n
with the new element
- * newelem
. Takes time linear in the buffer size. (except the
+ /** Replaces element at index `n` with the new element
+ * `newelem`. Takes time linear in the buffer size. (except the
* first element, which is updated in constant time).
*
* @param n the index of the element to replace.
* @param x the new element.
- * @throws Predef.IndexOutOfBoundsException if n
is out of bounds.
+ * @throws Predef.IndexOutOfBoundsException if `n` is out of bounds.
*/
def update(n: Int, x: A) {
try {
@@ -90,6 +108,7 @@ final class ListBuffer[A]
/** Appends a single element to this buffer. This operation takes constant time.
*
* @param x the element to append.
+ * @return this $coll.
*/
def += (x: A): this.type = {
if (exported) copy()
@@ -117,7 +136,7 @@ final class ListBuffer[A]
* time.
*
* @param x the element to prepend.
- * @return this buffer.
+ * @return this $coll.
*/
def +=: (x: A): this.type = {
if (exported) copy()
@@ -128,13 +147,13 @@ final class ListBuffer[A]
this
}
- /** Inserts new elements at the index n
. Opposed to method
- * update
, this method will not replace an element with a new
- * one. Instead, it will insert a new element at index n
.
+ /** Inserts new elements at the index `n`. Opposed to method
+ * `update`, this method will not replace an element with a new
+ * one. Instead, it will insert a new element at index `n`.
*
* @param n the index where a new element will be inserted.
* @param iter the iterable object providing all elements to insert.
- * @throws Predef.IndexOutOfBoundsException if n
is out of bounds.
+ * @throws Predef.IndexOutOfBoundsException if `n` is out of bounds.
*/
def insertAll(n: Int, seq: Traversable[A]) {
try {
@@ -230,9 +249,9 @@ final class ListBuffer[A]
* the buffer size
*
* @param n the index which refers to the element to delete.
- * @return n the element that was formerly at position n
.
- * @note an element must exists at position n
- * @throws Predef.IndexOutOfBoundsException if n
is out of bounds.
+ * @return n the element that was formerly at position `n`.
+ * @note an element must exists at position `n`.
+ * @throws Predef.IndexOutOfBoundsException if `n` is out of bounds.
*/
def remove(n: Int): A = {
if (n < 0 || n >= len) throw new IndexOutOfBoundsException(n.toString())
@@ -259,6 +278,7 @@ final class ListBuffer[A]
* buffer size.
*
* @param x the element to remove.
+ * @return this $coll.
*/
override def -= (elem: A): this.type = {
if (exported) copy()
@@ -328,10 +348,9 @@ final class ListBuffer[A]
override def stringPrefix: String = "ListBuffer"
}
-/** Factory object for ListBuffer
class.
- *
- * @author Martin Odersky
- * @version 2.8
+/** $factoryInfo
+ * @define Coll ListBuffer
+ * @define coll list buffer
*/
object ListBuffer extends SeqFactory[ListBuffer] {
implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, ListBuffer[A]] = new GenericCanBuildFrom[A]
diff --git a/src/library/scala/collection/mutable/ListMap.scala b/src/library/scala/collection/mutable/ListMap.scala
index c96873c81d..a4321d3818 100644
--- a/src/library/scala/collection/mutable/ListMap.scala
+++ b/src/library/scala/collection/mutable/ListMap.scala
@@ -14,8 +14,26 @@ package mutable
import generic._
-/** A simple map backed by a list.
- * @since 2.8
+/** A simple mutable map backed by a list.
+ *
+ * @tparam A the type of the keys contained in this list map.
+ * @tparam B the type of the values assigned to keys in this list map.
+ *
+ * @define Coll mutable.ListMap
+ * @define coll mutable list map
+ * @define thatinfo the class of the returned collection. In the standard library configuration,
+ * `That` is always `ListMap[A, B]` if the elements contained in the resulting collection are
+ * pairs of type `(A, B)`. This is because an implicit of type `CanBuildFrom[ListMap, (A, B), ListMap[A, B]]`
+ * is defined in object `ListMap`. Otherwise, `That` resolves to the most specific type that doesn't have
+ * to contain pairs of type `(A, B)`, which is `Iterable`.
+ * @define $bfinfo an implicit value of class `CanBuildFrom` which determines the
+ * result class `That` from the current representation type `Repr`
+ * and the new element type `B`. This is usually the `canBuildFrom` value
+ * defined in object `ListMap`.
+ * @define mayNotTerminateInf
+ * @define willNotTerminateInf
+ * @define orderDependent
+ * @define orderDependentFold
*/
@serializable
class ListMap[A, B] extends Map[A, B] with MapLike[A, B, ListMap[A, B]] {
@@ -40,10 +58,9 @@ class ListMap[A, B] extends Map[A, B] with MapLike[A, B, ListMap[A, B]] {
override def size: Int = siz
}
-/** This class implements mutable maps using a list.
- *
- * @author Martin Odersky
- * @version 2.8
+/** $factoryInfo
+ * @define Coll ListMap
+ * @define coll list map
*/
object ListMap extends MutableMapFactory[ListMap] {
implicit def canBuildFrom[A, B]: CanBuildFrom[Coll, (A, B), ListMap[A, B]] = new MapCanBuildFrom[A, B]
diff --git a/src/library/scala/collection/mutable/MapLike.scala b/src/library/scala/collection/mutable/MapLike.scala
index 9c3c1c0e5f..19e67a6731 100644
--- a/src/library/scala/collection/mutable/MapLike.scala
+++ b/src/library/scala/collection/mutable/MapLike.scala
@@ -40,7 +40,7 @@ import annotation.migration
* `drop`, `filter` return the same kind of map, you
* should also override:
* {{{
- * def> empty: This
+ * def empty: This
* }}}
* If you wish to avoid the unnecessary construction of an `Option`
* object, you could also override `apply`, `update`,
@@ -187,7 +187,8 @@ trait MapLike[A, B, +This <: MapLike[A, B, This] with Map[A, B]]
*/
def clear() { keysIterator foreach -= }
- /** If given key is already in this map, returns associated value
+ /** If given key is already in this map, returns associated value.
+ *
* Otherwise, computes value from given expression `op`, stores with key
* in map and returns that value.
* @param key the key to test
diff --git a/src/library/scala/collection/mutable/MultiMap.scala b/src/library/scala/collection/mutable/MultiMap.scala
index 01ddea070c..39c51ef5ad 100644
--- a/src/library/scala/collection/mutable/MultiMap.scala
+++ b/src/library/scala/collection/mutable/MultiMap.scala
@@ -13,21 +13,42 @@ package scala.collection
package mutable
-/** This class is typically used as a mixin. It turns maps which map A
- * to Set[B]
objects into multi maps which map A
to
- * B
objects.
+/** A trait for mutable maps with multiple values assigned to a key.
*
+ * This class is typically used as a mixin. It turns maps which map `A`
+ * to `Set[B]` objects into multi maps which map `A` to
+ * `B` objects.
+ *
+ * @define coll multimap
+ * @define Coll MultiMap
* @author Matthias Zenger
* @author Martin Odersky
* @version 2.8
* @since 1
*/
trait MultiMap[A, B] extends Map[A, Set[B]] {
+ /** Creates a new set.
+ *
+ * Classes that use this trait as a mixin can override this method
+ * to have the desired implementation of sets assigned to new keys.
+ * By default this is `HashSet`.
+ *
+ * @return An empty set of values of type `B`.
+ */
protected def makeSet: Set[B] = new HashSet[B]
@deprecated("use addBinding instead")
def add(key: A, value: B): this.type = addBinding(key, value)
+ /** Assigns the specified `value` to a specified `key`, replacing
+ * the existing value assigned to that `key` if it is equal to
+ * the specified value. Otherwise, simply adds another binding to
+ * the `key`.
+ *
+ * @param key The key to which to bind the new value.
+ * @param value The value to bind to the key.
+ * @return A reference to this multimap.
+ */
def addBinding(key: A, value: B): this.type = {
get(key) match {
case None =>
@@ -40,6 +61,15 @@ trait MultiMap[A, B] extends Map[A, Set[B]] {
this
}
+ /** Removes the binding of `value` to `key` if it exists.
+ *
+ * If this was the last value assigned to the specified key, the
+ * set assigned to that key will be removed as well.
+ *
+ * @param key The key of the binding.
+ * @param value The value to remove.
+ * @return A reference to this multimap.
+ */
def removeBinding(key: A, value: B): this.type = {
get(key) match {
case None =>
@@ -50,6 +80,12 @@ trait MultiMap[A, B] extends Map[A, Set[B]] {
this
}
+ /** Checks if there exists a binding to `key` such that it satisfies the predicate `p`.
+ *
+ * @param key The key for which the predicate is checked.
+ * @param p The predicate which a value assigned to the key must satisfy.
+ * @return A boolean if such a binding exists
+ */
def entryExists(key: A, p: B => Boolean): Boolean = get(key) match {
case None => false
case Some(set) => set exists p
diff --git a/src/library/scala/collection/mutable/MutableList.scala b/src/library/scala/collection/mutable/MutableList.scala
index 7784927c87..4324fa7ef9 100644
--- a/src/library/scala/collection/mutable/MutableList.scala
+++ b/src/library/scala/collection/mutable/MutableList.scala
@@ -15,12 +15,12 @@ package mutable
import generic._
import immutable.{List, Nil}
+// !!! todo: convert to LinkedListBuffer?
/**
* This class is used internally to represent mutable lists. It is the
* basis for the implementation of the classes
* Stack
, and Queue
.
*
- * !!! todo: convert to LinkedListBuffer?
*
* @author Matthias Zenger
* @author Martin Odersky
diff --git a/src/library/scala/collection/mutable/OpenHashMap.scala b/src/library/scala/collection/mutable/OpenHashMap.scala
index 79bb96a0bf..cbcc19c3e8 100644
--- a/src/library/scala/collection/mutable/OpenHashMap.scala
+++ b/src/library/scala/collection/mutable/OpenHashMap.scala
@@ -57,6 +57,9 @@ class OpenHashMap[Key, Value](initialSize : Int) extends Map[Key, Value]
import OpenHashMap.OpenEntry
type Entry = OpenEntry[Key, Value]
+ /**
+ * A default constructor creates a hashmap with initial size 8.
+ */
def this() = this(8);
override def empty: OpenHashMap[Key, Value] = OpenHashMap.empty[Key, Value]
@@ -212,7 +215,7 @@ class OpenHashMap[Key, Value](initialSize : Int) extends Map[Key, Value]
*
* @param f The function to apply to each key, value mapping.
*/
- override def foreach[U](f : ((Key, Value)) => U){
+ override def foreach[U](f : ((Key, Value)) => U) {
val startModCount = modCount;
foreachUndeletedEntry(entry => {
if (modCount != startModCount) error("Concurrent Modification")
diff --git a/src/library/scala/collection/mutable/PriorityQueue.scala b/src/library/scala/collection/mutable/PriorityQueue.scala
index 4d74a2ee74..eade376abe 100644
--- a/src/library/scala/collection/mutable/PriorityQueue.scala
+++ b/src/library/scala/collection/mutable/PriorityQueue.scala
@@ -144,10 +144,10 @@ class PriorityQueue[A](implicit ord: Ordering[A])
this
}
- /** Adds all elements provided by an Iterable
object
+ /** Adds all elements provided by a `TraversableOnce` object
* into the priority queue.
*
- * @param iter an iterable object
+ * @param xs an iterable object
*/
def ++(xs: TraversableOnce[A]) = { this.clone() ++= xs }
@@ -206,14 +206,16 @@ class PriorityQueue[A](implicit ord: Ordering[A])
/**
* Returns the reverse of this queue. The priority queue that gets
* returned will have an inversed ordering - if for some elements
- * x
and y
the original queue's ordering
- * had compare
returning an integer w, the new one will return -w,
+ * `x` and `y` the original queue's ordering
+ * had `compare` returning an integer ''w'', the new one will return ''-w'',
* assuming the original ordering abides its contract.
*
* Note that the order of the elements will be reversed unless the
- * compare
method returns 0. In this case, such elements
+ * `compare` method returns 0. In this case, such elements
* will be subsequent, but their corresponding subinterval may be inappropriately
* reversed. However, due to the compare-equals contract, they will also be equal.
+ *
+ * @return A reversed priority queue.
*/
override def reverse = {
val revq = new PriorityQueue[A]()(new math.Ordering[A] {
diff --git a/src/library/scala/collection/mutable/PriorityQueueProxy.scala b/src/library/scala/collection/mutable/PriorityQueueProxy.scala
index 427ffe478a..3f1ee5d217 100644
--- a/src/library/scala/collection/mutable/PriorityQueueProxy.scala
+++ b/src/library/scala/collection/mutable/PriorityQueueProxy.scala
@@ -11,7 +11,7 @@
package scala.collection
package mutable
-/** This class implements priority queues using a heap. The
+/** This class servers as a proxy for priority queues. The
* elements of the queue have to be ordered in terms of the
* Ordered[T]
class.
*
diff --git a/src/library/scala/collection/mutable/Seq.scala b/src/library/scala/collection/mutable/Seq.scala
index a57d397275..8d11e14063 100644
--- a/src/library/scala/collection/mutable/Seq.scala
+++ b/src/library/scala/collection/mutable/Seq.scala
@@ -16,9 +16,10 @@ import generic._
/** A subtrait of collection.Seq
which represents sequences
* that can be mutated.
- * The class adds an update
method to collection.Seq
.
*
- * @since 2.8
+ * $seqInfo
+ *
+ * The class adds an update
method to collection.Seq
.
*/
trait Seq[A] extends Iterable[A]
with scala.collection.Seq[A]
diff --git a/src/library/scala/collection/mutable/SetLike.scala b/src/library/scala/collection/mutable/SetLike.scala
index 7004e52b8e..9dbfaf6d5e 100644
--- a/src/library/scala/collection/mutable/SetLike.scala
+++ b/src/library/scala/collection/mutable/SetLike.scala
@@ -26,7 +26,8 @@ import scala.annotation.migration
* @version 2.8
* @since 2.8
*
- * @define setnote @note
+ * @define setnote
+ * @note
* This trait provides most of the operations of a `mutable.Set` independently of its representation.
* It is typically inherited by concrete implementations of sets.
*
@@ -108,6 +109,7 @@ trait SetLike[A, +This <: SetLike[A, This] with Set[A]]
// abstract methods from Growable/Shrinkable
+ /** Adds a single element to the set. */
def +=(elem: A): this.type
def -=(elem: A): this.type
diff --git a/src/library/scala/collection/mutable/Stack.scala b/src/library/scala/collection/mutable/Stack.scala
index 45e9fa24b2..c224c030a4 100644
--- a/src/library/scala/collection/mutable/Stack.scala
+++ b/src/library/scala/collection/mutable/Stack.scala
@@ -57,11 +57,11 @@ class Stack[A] private (var elems: List[A]) extends scala.collection.Seq[A] with
*/
def push(elem1: A, elem2: A, elems: A*): this.type = this.push(elem1).push(elem2).pushAll(elems)
- /** Push all elements provided by the given iterator object onto
- * the stack. The last element returned by the iterator
+ /** 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 elems the iterator object.
+ * @param xs the traversable object.
* @return the stack with the new elements on top.
*/
def pushAll(xs: TraversableOnce[A]): this.type = { xs foreach push ; this }
diff --git a/src/library/scala/collection/mutable/SynchronizedBuffer.scala b/src/library/scala/collection/mutable/SynchronizedBuffer.scala
index 1c9a77c46a..0fef1a6635 100644
--- a/src/library/scala/collection/mutable/SynchronizedBuffer.scala
+++ b/src/library/scala/collection/mutable/SynchronizedBuffer.scala
@@ -54,18 +54,18 @@ trait SynchronizedBuffer[A] extends Buffer[A] {
super.+=(elem)
}
- /** Appends a number of elements provided by an iterable object
- * via its iterator
method. The identity of the
- * buffer is returned.
+ /** Appends a number of elements provided by a traversable object via
+ * its `foreach` method.
+ * The identity of the buffer is returned.
*
- * @param iter the iterable object.
+ * @param xs the traversable object.
*/
override def ++(xs: TraversableOnce[A]): Self = synchronized {
super.++(xs)
}
- /** Appends a number of elements provided by an iterable object
- * via its iterator
method.
+ /** Appends a number of elements provided by a traversable object
+ * via its `foreach` method.
*
* @param iter the iterable object.
*/
@@ -81,10 +81,10 @@ trait SynchronizedBuffer[A] extends Buffer[A] {
super.++=(elems)
}
- /** Appends a number of elements provided by an iterable object
- * via its iterator
method.
+ /** Appends a number of elements provided by a traversable object
+ * via its foreach
method.
*
- * @param iter the iterable object.
+ * @param xs the traversable object.
*/
override def appendAll(xs: TraversableOnce[A]): Unit = synchronized {
super.appendAll(xs)
@@ -99,11 +99,11 @@ trait SynchronizedBuffer[A] extends Buffer[A] {
super.+=:(elem)
}
- /** Prepends a number of elements provided by an iterable object
- * via its iterator
method. The identity of the
+ /** Prepends a number of elements provided by a traversable object
+ * via its foreach
method. The identity of the
* buffer is returned.
*
- * @param iter the iterable object.
+ * @param xs the traversable object.
*/
override def ++=:(xs: TraversableOnce[A]): this.type = synchronized[this.type] { super.++=:(xs) }
@@ -113,11 +113,11 @@ trait SynchronizedBuffer[A] extends Buffer[A] {
*/
override def prepend(elems: A*): Unit = prependAll(elems)
- /** Prepends a number of elements provided by an iterable object
- * via its iterator
method. The identity of the
+ /** Prepends a number of elements provided by a traversable object
+ * via its foreach
method. The identity of the
* buffer is returned.
*
- * @param iter the iterable object.
+ * @param xs the traversable object.
*/
override def prependAll(xs: TraversableOnce[A]): Unit = synchronized {
super.prependAll(xs)
@@ -139,10 +139,10 @@ trait SynchronizedBuffer[A] extends Buffer[A] {
* one. Instead, it will insert a new element at index n
.
*
* @param n the index where a new element will be inserted.
- * @param iter the iterable object providing all elements to insert.
+ * @param xs the traversable object providing all elements to insert.
*/
- abstract override def insertAll(n: Int, iter: Traversable[A]): Unit = synchronized {
- super.insertAll(n, iter)
+ abstract override def insertAll(n: Int, xs: Traversable[A]): Unit = synchronized {
+ super.insertAll(n, xs)
}
/** Replace element at index n
with the new element
diff --git a/src/library/scala/collection/mutable/SynchronizedPriorityQueue.scala b/src/library/scala/collection/mutable/SynchronizedPriorityQueue.scala
index 9d18846252..933b3b41a4 100644
--- a/src/library/scala/collection/mutable/SynchronizedPriorityQueue.scala
+++ b/src/library/scala/collection/mutable/SynchronizedPriorityQueue.scala
@@ -12,7 +12,7 @@
package scala.collection
package mutable
-/** This class implements synchronized priority queues using a heap.
+/** This class implements synchronized priority queues using a binary heap.
* The elements of the queue have to be ordered in terms of the
* Ordered[T]
class.
*
@@ -39,13 +39,13 @@ class SynchronizedPriorityQueue[A](implicit ord: Ordering[A]) extends PriorityQu
this
}
- /** Adds all elements provided by an iterator into the priority queue.
+ /** Adds all elements of a traversable object into the priority queue.
*
- * @param it an iterator
+ * @param xs a traversable object
*/
- override def ++=(it: TraversableOnce[A]): this.type = {
+ override def ++=(xs: TraversableOnce[A]): this.type = {
synchronized {
- super.++=(it)
+ super.++=(xs)
}
this
}
diff --git a/src/library/scala/collection/mutable/SynchronizedQueue.scala b/src/library/scala/collection/mutable/SynchronizedQueue.scala
index e7630cee06..b09687a78e 100644
--- a/src/library/scala/collection/mutable/SynchronizedQueue.scala
+++ b/src/library/scala/collection/mutable/SynchronizedQueue.scala
@@ -36,11 +36,11 @@ class SynchronizedQueue[A] extends Queue[A] {
*/
override def +=(elem: A): this.type = synchronized[this.type] { super.+=(elem) }
- /** Adds all elements provided by an Iterable
object
+ /** Adds all elements provided by a `TraversableOnce` object
* 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
+ * @param xs a traversable object
*/
override def ++=(xs: TraversableOnce[A]): this.type = synchronized[this.type] { super.++=(xs) }
diff --git a/src/library/scala/collection/mutable/SynchronizedStack.scala b/src/library/scala/collection/mutable/SynchronizedStack.scala
index 4394d307eb..4940884302 100644
--- a/src/library/scala/collection/mutable/SynchronizedStack.scala
+++ b/src/library/scala/collection/mutable/SynchronizedStack.scala
@@ -39,16 +39,18 @@ class SynchronizedStack[A] extends Stack[A] {
/** Push two or more elements onto the stack. The last element
* of the sequence will be on top of the new stack.
*
- * @param elems the element sequence.
- * @return the stack with the new elements on top.
+ * @param elem1 the first element to push.
+ * @param elem2 the second element to push.
+ * @param elems the element sequence that will be pushed.
+ * @return the stack with the new elements on top.
*/
override def push(elem1: A, elem2: A, elems: A*): this.type = synchronized[this.type] { super.push(elem1, elem2, elems: _*) }
- /** Pushes all elements provided by an iterator
- * on top of the stack. The elements are pushed in the order they
- * are given out by the iterator.
+ /** Pushes all elements provided by a traversable object
+ * on top of the stack. The elements are pushed in the order the
+ * traversable object is traversed.
*
- * @param elems an iterator
+ * @param xs a traversable object
*/
override def pushAll(xs: TraversableOnce[A]): this.type = synchronized[this.type] { super.pushAll(elems) }
diff --git a/src/library/scala/collection/mutable/Traversable.scala b/src/library/scala/collection/mutable/Traversable.scala
index bdbcb9d97e..89c8868314 100644
--- a/src/library/scala/collection/mutable/Traversable.scala
+++ b/src/library/scala/collection/mutable/Traversable.scala
@@ -14,12 +14,9 @@ package mutable
import generic._
-/** A subtrait of collection.Traversable
which represents
- * traversables that can be mutated.
- *
- * @author Martin Odersky
- * @version 2.8
- * @since 2.8
+/** A trait for traversable collections that can be mutated.
+ * $traversableInfo
+ * @define mutability mutable
*/
trait Traversable[A] extends scala.collection.Traversable[A]
with GenericTraversableTemplate[A, Traversable]
diff --git a/src/library/scala/collection/mutable/WeakHashMap.scala b/src/library/scala/collection/mutable/WeakHashMap.scala
index cad4dc2e43..8f496add1e 100644
--- a/src/library/scala/collection/mutable/WeakHashMap.scala
+++ b/src/library/scala/collection/mutable/WeakHashMap.scala
@@ -16,8 +16,9 @@ import JavaConversions._
import generic._
-/**
- * @since 2.8
+/** A hash map with weak references to entries which are weakly reachable.
+ *
+ * @since 2.8
*/
class WeakHashMap[A, B] extends JMapWrapper[A, B](new java.util.WeakHashMap)
with JMapWrapperLike[A, B, WeakHashMap[A, B]] {
diff --git a/src/library/scala/runtime/AbstractFunction0.scala b/src/library/scala/runtime/AbstractFunction0.scala
index 1022a056f9..2d7d613132 100644
--- a/src/library/scala/runtime/AbstractFunction0.scala
+++ b/src/library/scala/runtime/AbstractFunction0.scala
@@ -8,9 +8,12 @@
package scala.runtime
-abstract class AbstractFunction0[+R] extends Function0[R] { }
-abstract class AbstractFunction1[-T1, +R] extends Function1[T1, R] { }
-abstract class AbstractFunction2[-T1, -T2, +R] extends Function2[T1, T2, R] { }
+abstract class AbstractFunction0[@specialized(Unit, Int, Long, Double) +R] extends Function0[R] { }
+abstract class AbstractFunction1[@specialized(Int, Long, Double) -T1,
+ @specialized(Unit, Int, Long, Double) +R] extends Function1[T1, R] { }
+abstract class AbstractFunction2[@specialized(Int, Long, Double) -T1,
+ @specialized(Int, Long, Double) -T2,
+ @specialized(Unit, Int, Long, Double) +R] extends Function2[T1, T2, R] { }
abstract class AbstractFunction3[-T1, -T2, -T3, +R] extends Function3[T1, T2, T3, R] { }
abstract class AbstractFunction4[-T1, -T2, -T3, -T4, +R] extends Function4[T1, T2, T3, T4, R] { }
abstract class AbstractFunction5[-T1, -T2, -T3, -T4, -T5, +R] extends Function5[T1, T2, T3, T4, T5, R] { }
diff --git a/src/library/scala/runtime/AnyValCompanion.scala b/src/library/scala/runtime/AnyValCompanion.scala
new file mode 100644
index 0000000000..0a6f93805a
--- /dev/null
+++ b/src/library/scala/runtime/AnyValCompanion.scala
@@ -0,0 +1,86 @@
+/* __ *\
+** ________ ___ / / ___ Scala API **
+** / __/ __// _ | / / / _ | (c) 2002-2010, LAMP/EPFL **
+** __\ \/ /__/ __ |/ /__/ __ | http://scala-lang.org/ **
+** /____/\___/_/ |_/____/_/ | | **
+** |/ **
+\* */
+
+// $Id$
+
+package scala.runtime
+
+/** A common supertype for companion classes of primitive types.
+ *
+ * A common trait for /companion/ objects of primitive types comes handy
+ * when parameterizing code on types. For instance, the specialized
+ * annotation is passed a sequence of types on which to specialize:
+ * {{{
+ * class Tuple1[@specialized(Unit, Int, Double) T]
+ * }}}
+ *
+ */
+sealed trait AnyValCompanion
+
+/** A object representing 'object scala.Unit'. It should never be used
+ * directly.
+ */
+object Unit extends AnyValCompanion {
+ override def toString = "object scala.Unit"
+}
+
+/** A object representing 'object scala.Boolean'. It should never be used
+ * directly.
+ */
+object Boolean extends AnyValCompanion {
+ override def toString = "object scala.Boolean"
+}
+
+/** A object representing 'object scala.Byte'. It should never be used
+ * directly.
+ */
+object Byte extends AnyValCompanion {
+ override def toString = "object scala.Byte"
+}
+
+/** A object representing 'object scala.Short'. It should never be used
+ * directly.
+ */
+object Short extends AnyValCompanion {
+ override def toString = "object scala.Short"
+}
+
+/** A object representing 'object scala.Char'. It should never be used
+ * directly.
+ */
+object Char extends AnyValCompanion {
+ override def toString = "object scala.Char"
+}
+
+/** A object representing 'object scala.Int'. It should never be used
+ * directly.
+ */
+object Int extends AnyValCompanion {
+ override def toString = "object scala.Int"
+}
+
+/** A object representing 'object scala.Long'. It should never be used
+ * directly.
+ */
+object Long extends AnyValCompanion {
+ override def toString = "object scala.Long"
+}
+
+/** A object representing 'object scala.Float'. It should never be used
+ * directly.
+ */
+object Float extends AnyValCompanion {
+ override def toString = "object scala.Float"
+}
+
+/** A object representing 'object scala.Double'. It should never be used
+ * directly.
+ */
+object Double extends AnyValCompanion {
+ override def toString = "object scala.Double"
+}
diff --git a/src/library/scala/specialized.scala b/src/library/scala/specialized.scala
index 5ad2b0501f..4ac3037328 100644
--- a/src/library/scala/specialized.scala
+++ b/src/library/scala/specialized.scala
@@ -18,20 +18,17 @@ package scala
*
*
* Type T can be specialized on a subset of the primitive types by
- * specifying a comma-separated string argument:
+ * specifying a list of primitive types to specialize at:
*
*
- * class MyList[@specialized("Int, Double, Boolean") T] ..
+ * class MyList[@specialized(Int, Double, Boolean) T] ..
*
- * Only primitive types are supported and no name resolution is currently
- * done on the string arguments (meaning imports and type aliases are
- * not resolved).
*
* @since 2.8
*/
-class specialized(types: String) extends StaticAnnotation {
+class specialized(types: runtime.AnyValCompanion*) extends StaticAnnotation {
def this() {
- this("Boolean, Byte, Short, Char, Int, Long, Float, Double")
+ this(Unit, Boolean, Byte, Short, Char, Int, Long, Float, Double)
}
}
diff --git a/src/library/scala/util/Properties.scala b/src/library/scala/util/Properties.scala
index b781e46be5..3a08fa0482 100644
--- a/src/library/scala/util/Properties.scala
+++ b/src/library/scala/util/Properties.scala
@@ -54,6 +54,7 @@ private[scala] trait PropertiesTrait
def clearProp(name: String) = System.clearProperty(name)
def envOrElse(name: String, alt: String) = Option(System getenv name) getOrElse alt
+ def envOrNone(name: String) = Option(System getenv name)
// for values based on propFilename
def scalaPropOrElse(name: String, alt: String): String = scalaProps.getProperty(name, alt)
diff --git a/src/partest/scala/tools/partest/Actions.scala b/src/partest/scala/tools/partest/Actions.scala
index 3e745714cb..48b80cface 100644
--- a/src/partest/scala/tools/partest/Actions.scala
+++ b/src/partest/scala/tools/partest/Actions.scala
@@ -136,7 +136,7 @@ trait Actions {
/** The default cleanup normalizes paths relative to sourcesDir.
*/
- def diffCleanup(f: File) = safeLines(f) map normalizePaths mkString "\n"
+ def diffCleanup(f: File) = safeLines(f) map normalizePaths mkString ("", "\n", "\n")
/** If optional is true, a missing check file is considered
* a successful diff. Necessary since many categories use
@@ -146,19 +146,23 @@ trait Actions {
def arg1 = tracePath(check)
def arg2 = tracePath(log)
def noCheck = !check.exists && returning(true)(_ => trace("diff %s %s [unchecked]".format(arg1, arg2)))
+ def output = diffCleanup(log)
+ def matches = safeSlurp(check).trim == output.trim
+
+ def traceMsg =
+ if (isDryRun) "diff %s %s".format(arg1, arg2)
+ else "diff %s %s [%s]".format(arg1, arg2, (if (matches) "passed" else "failed"))
noCheck || {
- def result = safeSlurp(check).trim == diffCleanup(log).trim
- def msg = if (result) "passed" else "failed"
+ trace(traceMsg)
- if (isDryRun) {
- trace("diff %s %s".format(arg1, arg2))
+ isDryRun || matches || (isUpdateCheck && {
+ normal("** diff %s %s failed:\n".format(arg1, arg2))
+ normal(diffOutput())
+ normal("** updating %s and marking as passed.\n".format(arg1))
+ check writeAll output
true
- }
- else {
- trace("diff %s %s [%s]".format(arg1, arg2, msg))
- result
- }
+ })
}
}
diff --git a/src/partest/scala/tools/partest/Compilable.scala b/src/partest/scala/tools/partest/Compilable.scala
index a1d987ad6d..c11532f278 100644
--- a/src/partest/scala/tools/partest/Compilable.scala
+++ b/src/partest/scala/tools/partest/Compilable.scala
@@ -27,8 +27,10 @@ trait PartestCompilation {
// }
def javac(args: List[String]): Boolean = {
+ val allArgString = fromArgs(javacpArg :: javacOpts :: args)
+
// javac -d outdir -classpath
- val cmd = "%s -d %s %s %s".format(javacCmd, outDir, javacpArg, fromArgs(args))
+ val cmd = "%s -d %s %s".format(javacCmd, outDir, allArgString)
def traceMsg =
if (isVerbose) cmd
else "%s -d %s %s".format(tracePath(Path(javacCmd)), tracePath(outDir), fromArgs(args))
diff --git a/src/partest/scala/tools/partest/Config.scala b/src/partest/scala/tools/partest/Config.scala
index 7d8bb80835..288a3034e9 100644
--- a/src/partest/scala/tools/partest/Config.scala
+++ b/src/partest/scala/tools/partest/Config.scala
@@ -23,8 +23,6 @@ trait Config {
* run we only allocate one worker so the output isn't interspersed.
*/
def workerTimeout = 3600 // 1 hour, probably overly generous
- def testTimeout = testTimeout_ flatMap safeToInt getOrElse 900 // test timeout
- def testWarning = testWarning_ flatMap safeToInt getOrElse (testTimeout / 10) // test warning
def numWorkers = if (isDryRun) 1 else propOrElse("partest.actors", "8").toInt
def expectedErrors = propOrElse("partest.errors", "0").toInt
def poolSize = (wrapAccessControl(propOrNone("actors.corePoolSize")) getOrElse "16").toInt
@@ -121,6 +119,7 @@ trait Config {
"Java binaries in: " + javaBin,
"Java runtime is: " + javaInfoString,
"Java runtime options: " + (Process.javaVmArguments mkString " "),
+ "Javac options are: " + universe.javacOpts,
"Java options are: " + universe.javaOpts,
"Source directory is: " + src,
"Selected categories: " + (selectedCategories mkString " "),
diff --git a/src/partest/scala/tools/partest/Partest.scala b/src/partest/scala/tools/partest/Partest.scala
index 019ed270e5..d6adcc6053 100644
--- a/src/partest/scala/tools/partest/Partest.scala
+++ b/src/partest/scala/tools/partest/Partest.scala
@@ -6,7 +6,7 @@ package scala.tools
package partest
import nsc.io._
-import nsc.util.CommandLine
+import nsc.util._
import category.AllCategories
/** Global object for a Partest run. It is completely configured by the list
@@ -15,10 +15,15 @@ import category.AllCategories
* for the complete list.
*/
class Partest(args: List[String]) extends {
- val parsed = PartestSpecReference(args: _*)
-} with Universe with PartestSpec with AllCategories {
+ val parsed = PartestSpec(args: _*)
+} with Universe with PartestSpec with cmd.Instance with AllCategories {
- debug("Partest object created with args: " + (args mkString " "))
+ if (parsed.propertyArgs.nonEmpty)
+ debug("Partest property args: " + fromArgs(parsed.propertyArgs))
+
+ debug("Partest created with args: " + fromArgs(args))
+
+ def helpMsg = PartestSpec.helpMsg
// The abstract values from Universe.
lazy val testBuildDir = searchForDir(buildDir)
@@ -30,7 +35,6 @@ class Partest(args: List[String]) extends {
// Coarse validation of partest directory: holds a file called partest.
(partestDir / "partest").isFile || error("'%s' is not a valid partest directory." format partestDir)
- def runSets = toArgs(parsed.getOrElse("--runsets", ""))
def specifiedTests = parsed.residualArgs map (x => Path(x).normalize)
def specifiedKinds = testKinds filter (x => isSet(x) || (runSets contains x))
def specifiedCats = specifiedKinds flatMap (x => allCategories find (_.kind == x))
diff --git a/src/partest/scala/tools/partest/PartestSpec.scala b/src/partest/scala/tools/partest/PartestSpec.scala
index a8a1d9b0cb..50c82fb783 100644
--- a/src/partest/scala/tools/partest/PartestSpec.scala
+++ b/src/partest/scala/tools/partest/PartestSpec.scala
@@ -6,9 +6,8 @@
package scala.tools
package partest
-import Properties._
import nsc.io._
-import nsc.util.{ CommandLine, CommandLineSpec, CommandLineReferenceSpec }
+import cmd._
/** This takes advantage of bits of scala goodness to fully define a command
* line program with a minimum of duplicated code. When the specification object
@@ -16,93 +15,91 @@ import nsc.util.{ CommandLine, CommandLineSpec, CommandLineReferenceSpec }
* a private accumulator. What emerges is a full list of the valid unary
* and binary arguments, as well as autogenerated help.
*/
-trait PartestSpec extends CommandLineSpec {
- override def isPassthroughProperty(key: String) = key == "partest.options"
- override def isSysPropOption(key: String) = {
- val segments = (key split '.').toList
- if (segments.size == 2 && segments.head == "partest") Some(segments.last)
- else None
- }
-
- private var _testKinds: List[String] = Nil
- private def kind(s: String) = returning(s)(_testKinds +:= _)
+trait PartestSpec extends Spec with Meta.StdOpts with Interpolation {
+ def referenceSpec = PartestSpec
+ def programInfo = Spec.Names("partest", "scala.tools.partest.Runner")
+ private val kind = new Spec.Accumulator[String]()
+ protected def testKinds = kind.get
- def testKinds = _testKinds
- def versionMsg = Properties.versionMsg
+ private implicit val tokenizeString = FromString.ArgumentsFromString // String => List[String]
help("""
+ |# Pro Tip! Instant bash completion: `partest --bash` (note backticks)
|Usage: partest [] [ ...]
| : a path to a test designator, typically a .scala file or a directory.
- | Examples: files/pos/test1.scala, files/res/bug785""")
-
- heading ("Test categories:")
- val isAll = ("all" / "run all tests (default, unless no options given)" ?)
- (kind("pos") / "Compile files that are expected to build" ?)
- (kind("neg") / "Compile files that are expected to fail" ?)
- (kind("run") / "Test JVM backend" ?)
- (kind("jvm") / "Test JVM backend" ?)
- (kind("res") / "Run resident compiler scenarii" ?)
- (kind("buildmanager") / "Run Build Manager scenarii" ?)
- (kind("scalacheck") / "Run Scalacheck tests" ?)
- (kind("script") / "Run script files" ?)
- (kind("shootout") / "Run shootout tests" ?)
- (kind("scalap") / "Run scalap tests" ?)
+ | Examples: files/pos/test1.scala, files/res/bug785
+ |
+ | Test categories:""".stripMargin)
+
+ val isAll = ("all" / "run all tests (default, unless no options given)" --?)
+ (kind("pos") / "Compile files that are expected to build" --?)
+ (kind("neg") / "Compile files that are expected to fail" --?)
+ (kind("run") / "Test JVM backend" --?)
+ (kind("jvm") / "Test JVM backend" --?)
+ (kind("res") / "Run resident compiler scenarii" --?)
+ (kind("buildmanager") / "Run Build Manager scenarii" --?)
+ (kind("scalacheck") / "Run Scalacheck tests" --?)
+ (kind("script") / "Run script files" --?)
+ (kind("shootout") / "Run shootout tests" --?)
+ (kind("scalap") / "Run scalap tests" --?)
heading ("""Test "smart" categories:""")
- val grepExpr = "grep" / "run all tests with a source file containing " >>
- val isFailed = "failed" / "run all tests which failed on the last run" ?
+ val grepExpr = "grep" / "run all tests with a source file containing " --|
+ val isFailed = "failed" / "run all tests which failed on the last run" --?
heading ("Specifying paths and additional flags, ~ means repository root:")
- val rootDir = "rootdir" / "path from ~ to partest (default: test)" |> "test"
- val buildDir = "builddir" / "path from ~ to test build (default: build/pack)" |> "build/pack"
- val srcDir = "srcdir" / "path from --rootdir to sources (default: files)" |> "files"
- val javaOpts = "javaopts" / "flags to java on all runs (overrides JAVA_OPTS)" |> envOrElse("JAVA_OPTS", "")
- val scalacOpts = "scalacopts" / "flags to scalac on all tests (overrides SCALAC_OPTS)" |> envOrElse("SCALAC_OPTS", "")
- ("pack" / "alias for --builddir build/pack") ?+> List("--builddir", "build/pack")
- ("quick" / "alias for --builddir build/quick") ?+> List("--builddir", "build/quick")
+ val rootDir = "rootdir" / "path from ~ to partest" defaultTo "test"
+ val buildDir = "builddir" / "path from ~ to test build" defaultTo "build/pack"
+ val srcDir = "srcdir" / "path from --rootdir to sources" defaultTo "files"
+ val javaOpts = "javaopts" / "flags to java on all runs" defaultToEnv "JAVA_OPTS"
+ val javacOpts = "javacopts" / "flags to javac on all runs" defaultToEnv "JAVAC_OPTS"
+ val scalacOpts = "scalacopts" / "flags to scalac on all tests" defaultToEnv "SCALAC_OPTS"
+
+ "pack" / "" expandTo ("--builddir", "build/pack")
+ "quick" / "" expandTo ("--builddir", "build/quick")
heading ("Options influencing output:")
- val isTrace = "trace" / "show the individual steps taken by each test" ?
- val isShowDiff = "show-diff" / "show diff between log and check file" ?
- val isShowLog = "show-log" / "show log on failures" ?
- val isDryRun = "dry-run" / "do not run tests, only show their traces." ?
- val isTerse = "terse" / "be less verbose (almost silent except for failures)" ?
- val isVerbose = "verbose" / "be more verbose (additive with --trace)" ?
- val isDebug = "debug" / "maximum debugging output" ?
- val isAnsi = "ansi" / "print output in color" ?
+ val isTrace = "trace" / "show the individual steps taken by each test" --?
+ val isShowDiff = "show-diff" / "show diff between log and check file" --?
+ val isShowLog = "show-log" / "show log on failures" --?
+ val isDryRun = "dry-run" / "do not run tests, only show their traces." --?
+ val isTerse = "terse" / "be less verbose (almost silent except for failures)" --?
+ val isVerbose = "verbose" / "be more verbose (additive with --trace)" --?
+ val isDebug = "debug" / "maximum debugging output" --?
+ val isAnsi = "ansi" / "print output in color" --?
heading ("Other options:")
- val timeout_ = "timeout" / "Overall timeout in seconds" |> "14400"
- val testWarning_ = "test-warning" / "Test warning in seconds" >> ; // defaults to testTimeout / 10
- val testTimeout_ = "test-timeout" / "Test timeout in seconds" >> ; // defaults to 900
- val isCleanup = "cleanup" / "delete all stale files and dirs before run" ?
- val isNoCleanup = "nocleanup" / "do not delete any logfiles or object dirs" ?
- val isStats = "stats" / "collect and print statistics about the tests" ?
- val isValidate = "validate" / "examine test filesystem for inconsistencies" ?
- val isVersion = "version" / "print version" ?
+ val timeout = "timeout" / "Overall timeout in seconds" defaultTo 14400
+ val testWarning = "test-warning" / "Test warning in seconds" defaultTo 90
+ val testTimeout = "test-timeout" / "Test timeout in seconds" defaultTo 900
+ val isCleanup = "cleanup" / "delete all stale files and dirs before run" --?
+ val isNoCleanup = "nocleanup" / "do not delete any logfiles or object dirs" --?
+ val isStats = "stats" / "collect and print statistics about the tests" --?
+ val isValidate = "validate" / "examine test filesystem for inconsistencies" --?
+ val isUpdateCheck = "update-check" / "overwrite checkFile if diff fails" --?
+
+ "version" / "print version" --> runAndExit(println(Properties.versionMsg))
// no help for anything below this line - secret options
// mostly intended for property configuration.
- val runsets = "runsets" |> ""
- val isNoAlarms = ("noalarms" ?)
- val isInsideAnt = ("is-in-ant" ?)
+ val runSets = ("runsets" --^) getOrElse Nil
+ val isNoAlarms = "noalarms" --?
+ val isInsideAnt = "is-in-ant" --?
}
-object PartestSpecReference extends PartestSpec with CommandLineReferenceSpec {
- import CommandLineSpec._
+object PartestSpec extends PartestSpec with Property {
+ lazy val propMapper = new PropertyMapper(PartestSpec) {
+ override def isPassThrough(key: String) = key == "partest.options"
+ }
- def parsed: CommandLine = null
- override def creator(args: List[String]) =
- new ThisCommandLine(args) {
- override def onlyKnownOptions = true
- override def errorFn(msg: String) = printAndExit("Error: " + msg)
- }
+ type ThisCommandLine = PartestCommandLine
+ class PartestCommandLine(args: List[String]) extends SpecCommandLine(args) {
+ override def onlyKnownOptions = true
+ override def errorFn(msg: String) = printAndExit("Error: " + msg)
- def main(args: Array[String]): Unit = println(bashCompletion("partest"))
+ def propertyArgs = PartestSpec.propertyArgs
+ }
- /** Append bash completion for partest to the given file.
- */
- def appendCompletionTo(f: File) = f appendAll bashCompletion("partest")
+ override def creator(args: List[String]): PartestCommandLine = new PartestCommandLine(args)
}
-
diff --git a/src/partest/scala/tools/partest/Runner.scala b/src/partest/scala/tools/partest/Runner.scala
index 7f67c93478..1a28e60896 100644
--- a/src/partest/scala/tools/partest/Runner.scala
+++ b/src/partest/scala/tools/partest/Runner.scala
@@ -9,13 +9,10 @@ package partest
import nsc.io._
object Runner {
- def main(mainArgs: Array[String]) {
- val propArgs = PartestSpecReference.sysPropsAsOptions()
- val args = (propArgs ++ mainArgs).toList
+ def main(args: Array[String]) {
val runner = Partest(args: _*)
import runner._
- if (isVersion) return println(versionMsg)
if (args.isEmpty) return println(helpMsg)
if (isValidate) return validateAll()
diff --git a/src/partest/scala/tools/partest/ant/JavaTask.scala b/src/partest/scala/tools/partest/ant/JavaTask.scala
index 0bebf91368..6740554dd8 100644
--- a/src/partest/scala/tools/partest/ant/JavaTask.scala
+++ b/src/partest/scala/tools/partest/ant/JavaTask.scala
@@ -12,19 +12,21 @@ package ant
import org.apache.tools.ant.Task
import org.apache.tools.ant.taskdefs.Java
-import org.apache.tools.ant.types.{ EnumeratedAttribute, Commandline, Environment, PropertySet }
+import org.apache.tools.ant.types.Environment
import scala.tools.nsc.io._
-import scala.tools.nsc.util.{ ClassPath, CommandLineSpec }
-import CommandLineSpec._
+import scala.tools.nsc.util.ClassPath
+import cmd.Spec._
class JavaTask extends Java {
override def getTaskName() = "partest"
private val scalaRunnerClass = "scala.tools.nsc.MainGenericRunner"
+ private val partestRunnerClass = "scala.tools.partest.Runner"
+ def defaultJvmArgs = "-Xms64M -Xmx768M -Xss768K -XX:MaxPermSize=96M"
protected def rootDir = prop("partest.rootdir") getOrElse (baseDir / "test").path
- protected def partestJVMArgs = prop("partest.jvm.args") getOrElse "-Xms64M -Xmx768M -Xss768K -XX:MaxPermSize=96M"
- protected def runnerArgs = List("-usejavacp", "scala.tools.partest.Runner", "--javaopts", partestJVMArgs)
+ protected def partestJVMArgs = prop("partest.jvm.args") getOrElse defaultJvmArgs
+ protected def runnerArgs = List("-usejavacp", partestRunnerClass, "--javaopts", partestJVMArgs)
private def baseDir = Directory(getProject.getBaseDir)
private def prop(s: String) = Option(getProject getProperty s)
diff --git a/src/partest/scala/tools/partest/ant/PartestTask.scala b/src/partest/scala/tools/partest/ant/PartestTask.scala
deleted file mode 100644
index 65848fabb0..0000000000
--- a/src/partest/scala/tools/partest/ant/PartestTask.scala
+++ /dev/null
@@ -1,90 +0,0 @@
-/* __ *\
-** ________ ___ / / ___ Scala Parallel Testing **
-** / __/ __// _ | / / / _ | (c) 2007-2010, LAMP/EPFL **
-** __\ \/ /__/ __ |/ /__/ __ | http://scala-lang.org/ **
-** /____/\___/_/ |_/____/_/ | | **
-** |/ **
-\* */
-
-/**** Note -- this isn't used anymore, but I left it in for the moment. ****/
-
-package scala.tools
-package partest
-package ant
-
-import java.io.{ File => JFile }
-
-import org.apache.tools.ant.Task
-import org.apache.tools.ant.types.{ Reference, FileSet}
-
-import scala.reflect.BeanProperty
-import scala.tools.ant.sabbus.CompilationPathProperty
-import scala.tools.nsc.io
-import scala.tools.nsc.util.CommandLineSpec._
-
-class PartestTask extends Task with CompilationPathProperty {
- /** Used only in ant task */
- @BeanProperty protected var errorOnFailed: Boolean = _
- @BeanProperty protected var jUnitReportDir: JFile = _
-
- /** Propagated to partest run via system properties */
- @BeanProperty protected var debug: Boolean = _
- @BeanProperty protected var javaOpts: String = _
- @BeanProperty protected var partestOpts: String = _
- @BeanProperty protected var runSets: String = _
- @BeanProperty protected var scalacOpts: String = _
- @BeanProperty protected var showDiff: Boolean = _
- @BeanProperty protected var showLog: Boolean = _
- @BeanProperty protected var srcDir: String = _
- @BeanProperty protected var timeout: Int = _
-
- /** Translating ant information into command line arguments. */
- private def notEmpty(s: String) = s != null && s.length > 0
- private def quoted(s: String) = if (s exists (_.isWhitespace)) "\"" + s.trim + "\"" else s
- private def optionCollection = List[(Boolean, () => List[String])](
- debug -> (() => List("--debug")),
- showLog -> (() => List("--show-log")),
- showDiff -> (() => List("--show-diff")),
- (timeout > 0) -> (() => List("--timeout", timeout.toString)),
- notEmpty(javaOpts) -> (() => List("--javaopts", javaOpts)),
- notEmpty(scalacOpts) -> (() => List("--scalacopts", scalacOpts)),
- notEmpty(srcDir) -> (() => List("--srcdir", srcDir)),
- notEmpty(partestOpts) -> (() => toArgs(partestOpts))
- )
-
- private def antPropOrNone(name: String) = Option(getProject getProperty name)
- private def antPropsToCommandLine() = {
- setProp("partest.isInAnt", "true")
- val partestDir = antPropOrNone("partest.dir") getOrElse error("Mandatory attribute 'partest.dir' is not set.")
-
- val root = List("--rootdir", io.Path(partestDir).path)
- val opts = optionCollection collect { case (true, f) => f() } flatten
- val sets = Option(runSets).toList flatMap toArgs map toOpt
-
- root ++ opts ++ sets
- }
- private def antRunTests() = {
- val args = antPropsToCommandLine()
- val runner = Partest(args: _*)
- import runner._
-
- normal("Ant options translate to command line: partest " + fromArgs(args))
- printConfigBanner()
-
- val result = launchTestSuite()
- val msg = result.toString
-
- if (result.hasFailures && errorOnFailed) error(msg)
- else log(msg)
- }
-
- override def execute() {
- try antRunTests()
- catch {
- case x =>
- System.err.println("Uncaught exception %s in partest ant ask: aborting." format x)
- x.printStackTrace()
- throw x
- }
- }
-}
diff --git a/src/partest/scala/tools/partest/package.scala b/src/partest/scala/tools/partest/package.scala
index 3ef4db7cd8..f6d216e379 100644
--- a/src/partest/scala/tools/partest/package.scala
+++ b/src/partest/scala/tools/partest/package.scala
@@ -5,7 +5,6 @@
package scala.tools
import nsc.io.{ File, Path, Process, Directory }
-import nsc.util.CommandLineSpec
import java.nio.charset.CharacterCodingException
package object partest {
@@ -18,13 +17,12 @@ package object partest {
private[partest] def safeLines(f: File) = safeSlurp(f) split """\r\n|\r|\n""" toList
private[partest] def safeArgs(f: File) = toArgs(safeSlurp(f))
- private[partest] def safeToInt(s: String) = try Some(s.toInt) catch { case _: NumberFormatException => None }
private[partest] def isJava(f: Path) = f.isFile && (f hasExtension "java")
private[partest] def isScala(f: Path) = f.isFile && (f hasExtension "scala")
private[partest] def isJavaOrScala(f: Path) = isJava(f) || isScala(f)
- private[partest] def toArgs(line: String) = CommandLineSpec toArgs line
- private[partest] def fromArgs(args: List[String]) = CommandLineSpec fromArgs args
+ private[partest] def toArgs(line: String) = cmd toArgs line
+ private[partest] def fromArgs(args: List[String]) = cmd fromArgs args
/** Strings, argument lists, etc. */
diff --git a/src/scalap/scala/tools/scalap/scalax/rules/scalasig/ScalaSigPrinter.scala b/src/scalap/scala/tools/scalap/scalax/rules/scalasig/ScalaSigPrinter.scala
index 26b01634f5..3cb70ec04e 100644
--- a/src/scalap/scala/tools/scalap/scalax/rules/scalasig/ScalaSigPrinter.scala
+++ b/src/scalap/scala/tools/scalap/scalax/rules/scalasig/ScalaSigPrinter.scala
@@ -290,7 +290,12 @@ class ScalaSigPrinter(stream: PrintStream, printPrivates: Boolean) {
val value = attrib.value.get
val stringVal = value.isInstanceOf[String]
if (stringVal) buffer.append("\"")
+ val stringValue = valueToString(value)
+ val isMultiline = stringVal && (stringValue.contains("\n")
+ || stringValue.contains("\r"))
+ if (isMultiline) buffer.append("\"\"")
buffer.append(valueToString(value))
+ if (isMultiline) buffer.append("\"\"")
if (stringVal) buffer.append("\"")
buffer.append(")")
}
--
cgit v1.2.3