From 406e54b7e59671462c4057894776f04d8f77b80e Mon Sep 17 00:00:00 2001 From: Aleksandar Pokopec Date: Mon, 12 Apr 2010 21:53:30 +0000 Subject: Documentation for mutable collections. No review. --- .../scala/collection/mutable/ListBuffer.scala | 2 +- src/library/scala/collection/mutable/Map.scala | 9 ++-- .../scala/collection/mutable/MapBuilder.scala | 4 ++ .../scala/collection/mutable/MapProxy.scala | 15 +++--- .../scala/collection/mutable/MutableList.scala | 9 ++-- .../collection/mutable/ObservableBuffer.scala | 6 +-- .../scala/collection/mutable/ObservableMap.scala | 6 +-- .../scala/collection/mutable/ObservableSet.scala | 6 +-- .../scala/collection/mutable/OpenHashMap.scala | 61 ++++++++++++++-------- .../scala/collection/mutable/PriorityQueue.scala | 40 +++++++++----- .../collection/mutable/PriorityQueueProxy.scala | 3 +- .../scala/collection/mutable/Publisher.scala | 8 +-- src/library/scala/collection/mutable/Queue.scala | 9 +++- .../scala/collection/mutable/QueueProxy.scala | 4 +- .../scala/collection/mutable/ResizableArray.scala | 2 + .../collection/mutable/RevertibleHistory.scala | 11 ++-- src/library/scala/collection/mutable/Seq.scala | 24 +++++---- src/library/scala/collection/mutable/Set.scala | 14 +++-- .../scala/collection/mutable/SetBuilder.scala | 2 + src/library/scala/collection/mutable/Stack.scala | 8 +++ .../scala/collection/mutable/StackProxy.scala | 3 ++ .../scala/collection/mutable/StringBuilder.scala | 7 +-- .../collection/mutable/SynchronizedBuffer.scala | 6 ++- .../scala/collection/mutable/SynchronizedMap.scala | 7 ++- .../mutable/SynchronizedPriorityQueue.scala | 8 ++- .../collection/mutable/SynchronizedQueue.scala | 6 ++- .../scala/collection/mutable/SynchronizedSet.scala | 6 ++- .../collection/mutable/SynchronizedStack.scala | 6 ++- .../scala/collection/mutable/Traversable.scala | 7 ++- .../scala/collection/mutable/Undoable.scala | 4 +- .../scala/collection/mutable/WeakHashMap.scala | 22 +++++++- .../scala/collection/mutable/WrappedArray.scala | 12 ++++- .../collection/mutable/WrappedArrayBuilder.scala | 5 +- 33 files changed, 233 insertions(+), 109 deletions(-) (limited to 'src/library') diff --git a/src/library/scala/collection/mutable/ListBuffer.scala b/src/library/scala/collection/mutable/ListBuffer.scala index a2611a8c0f..7ebbf7b4da 100644 --- a/src/library/scala/collection/mutable/ListBuffer.scala +++ b/src/library/scala/collection/mutable/ListBuffer.scala @@ -246,7 +246,7 @@ final class ListBuffer[A] // Overrides of methods in Buffer /** Removes the element on a given index position. May take time linear in - * the buffer size + * the buffer size. * * @param n the index which refers to the element to delete. * @return n the element that was formerly at position `n`. diff --git a/src/library/scala/collection/mutable/Map.scala b/src/library/scala/collection/mutable/Map.scala index 73688e3bee..d26f6a7e30 100644 --- a/src/library/scala/collection/mutable/Map.scala +++ b/src/library/scala/collection/mutable/Map.scala @@ -17,6 +17,8 @@ import generic._ /** This trait represents mutable maps. * All implementations od mutable maps inherit from it. * + * $mapnote + * * @tparam A the type of the keys of the map. * @tparam B the type of associated values. */ @@ -27,7 +29,7 @@ trait Map[A, B] override def empty: Map[A, B] = Map.empty - /** Return a read-only projection of this map. !!! or just use an (immutable) MapProxy? + /* Return a read-only projection of this map. !!! or just use an (immutable) MapProxy? def readOnly : scala.collection.Map[A, B] = new scala.collection.Map[A, B] { override def size = self.size override def update(key: A, value: B) = self.update(key, value) @@ -40,8 +42,9 @@ trait Map[A, B] */ } -/* The standard factory for mutable maps. - * Currently this uses `HashMap` as the implementation class. +/** $factoryInfo + * @define Coll Map + * @define coll map */ object Map extends MutableMapFactory[Map] { implicit def canBuildFrom[A, B]: CanBuildFrom[Coll, (A, B), Map[A, B]] = new MapCanBuildFrom[A, B] diff --git a/src/library/scala/collection/mutable/MapBuilder.scala b/src/library/scala/collection/mutable/MapBuilder.scala index 9ce3524d9e..75fb48abd6 100644 --- a/src/library/scala/collection/mutable/MapBuilder.scala +++ b/src/library/scala/collection/mutable/MapBuilder.scala @@ -14,6 +14,10 @@ package mutable /** The canonical builder for immutable maps, working with the map's `+` method * to add new elements. * Collections are built from their `empty` element using this + method. + * + * @tparam A Type of the keys for the map this builder creates. + * @tparam B Type of the values for the map this builder creates. + * @tparam Coll The type of the actual collection this builder builds. * @param empty The empty element of the collection. * * @since 2.8 diff --git a/src/library/scala/collection/mutable/MapProxy.scala b/src/library/scala/collection/mutable/MapProxy.scala index cb768f6778..7fbb016a57 100644 --- a/src/library/scala/collection/mutable/MapProxy.scala +++ b/src/library/scala/collection/mutable/MapProxy.scala @@ -12,20 +12,17 @@ package scala.collection package mutable -/**

- * This is a simple wrapper class for scala.collection.mutable.Map. - *

- *

- * It is most useful for assembling customized map abstractions - * dynamically using object composition and forwarding. - *

+/** + * This trait implements a proxy for scala.collection.mutable.Map. + * + * It is most useful for assembling customized map abstractions + * dynamically using object composition and forwarding. * * @author Matthias Zenger, Martin Odersky * @version 2.0, 31/12/2006 * @since 1 */ - trait MapProxy[A, B] extends Map[A, B] with MapProxyLike[A, B, Map[A, B]] { private def newProxy[B1 >: B](newSelf: Map[A, B1]): MapProxy[A, B1] = diff --git a/src/library/scala/collection/mutable/MutableList.scala b/src/library/scala/collection/mutable/MutableList.scala index 4324fa7ef9..4b6d727c34 100644 --- a/src/library/scala/collection/mutable/MutableList.scala +++ b/src/library/scala/collection/mutable/MutableList.scala @@ -16,11 +16,10 @@ 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. - *

+/** + * This class is used internally to represent mutable lists. It is the + * basis for the implementation of the classes + * `Stack`, and `Queue`. * * @author Matthias Zenger * @author Martin Odersky diff --git a/src/library/scala/collection/mutable/ObservableBuffer.scala b/src/library/scala/collection/mutable/ObservableBuffer.scala index d3bf49a5b4..8881e78ebc 100644 --- a/src/library/scala/collection/mutable/ObservableBuffer.scala +++ b/src/library/scala/collection/mutable/ObservableBuffer.scala @@ -15,9 +15,9 @@ package mutable import script._ /** This class is typically used as a mixin. It adds a subscription - * mechanism to the Buffer class into which this abstract - * class is mixed in. Class ObservableBuffer publishes - * events of the type Message. + * mechanism to the `Buffer` class into which this abstract + * class is mixed in. Class `ObservableBuffer` publishes + * events of the type `Message`. * * @author Matthias Zenger * @version 1.0, 08/07/2003 diff --git a/src/library/scala/collection/mutable/ObservableMap.scala b/src/library/scala/collection/mutable/ObservableMap.scala index b15b2e54e9..0cde1b2288 100644 --- a/src/library/scala/collection/mutable/ObservableMap.scala +++ b/src/library/scala/collection/mutable/ObservableMap.scala @@ -16,9 +16,9 @@ import script._ /** This class is typically used as a mixin. It adds a subscription - * mechanism to the Map class into which this abstract - * class is mixed in. Class ObservableMap publishes - * events of the type Message. + * mechanism to the `Map` class into which this abstract + * class is mixed in. Class `ObservableMap` publishes + * events of the type `Message`. * * @author Matthias Zenger * @author Martin Odersky diff --git a/src/library/scala/collection/mutable/ObservableSet.scala b/src/library/scala/collection/mutable/ObservableSet.scala index 024c2415ce..1f2f1789f9 100644 --- a/src/library/scala/collection/mutable/ObservableSet.scala +++ b/src/library/scala/collection/mutable/ObservableSet.scala @@ -15,9 +15,9 @@ package mutable import script._ /** This class is typically used as a mixin. It adds a subscription - * mechanism to the Set class into which this abstract - * class is mixed in. Class ObservableSet publishes - * events of the type Message. + * mechanism to the `Set` class into which this abstract + * class is mixed in. Class `ObservableSet` publishes + * events of the type `Message`. * * @author Matthias Zenger * @version 1.0, 08/07/2003 diff --git a/src/library/scala/collection/mutable/OpenHashMap.scala b/src/library/scala/collection/mutable/OpenHashMap.scala index cbcc19c3e8..4ecfe0e762 100644 --- a/src/library/scala/collection/mutable/OpenHashMap.scala +++ b/src/library/scala/collection/mutable/OpenHashMap.scala @@ -12,8 +12,12 @@ package scala.collection package mutable + /** - * @since 2.7 + * @define Coll OpenHashMap + * @define coll open hash map + * + * @since 2.7 */ object OpenHashMap { def apply[K, V](elems : (K, V)*) = { @@ -42,17 +46,26 @@ object OpenHashMap { private[mutable] def nextPowerOfTwo(i : Int) = highestOneBit(i) << 1; } -/** - * A mutable hash map based on an open hashing scheme. The precise scheme is undefined, - * but it should make a reasonable effort to ensure that an insert with consecutive hash - * codes is not unneccessarily penalised. In particular, mappings of consecutive integer - * keys should work without significant performance loss. +/** A mutable hash map based on an open hashing scheme. The precise scheme is undefined, + * but it should make a reasonable effort to ensure that an insert with consecutive hash + * codes is not unneccessarily penalised. In particular, mappings of consecutive integer + * keys should work without significant performance loss. + * + * @tparam Key type of the keys in this map. + * @tparam Value type of the values in this map. + * @param initialSize the initial size of the internal hash table. * - * @author David MacIver - * @since 2.7 + * @author David MacIver + * @since 2.7 + * + * @define Coll OpenHashMap + * @define coll open hash map + * @define mayNotTerminateInf + * @define willNotTerminateInf */ -class OpenHashMap[Key, Value](initialSize : Int) extends Map[Key, Value] - with MapLike[Key, Value, OpenHashMap[Key, Value]] { +class OpenHashMap[Key, Value](initialSize : Int) +extends Map[Key, Value] + with MapLike[Key, Value, OpenHashMap[Key, Value]] { import OpenHashMap.OpenEntry type Entry = OpenEntry[Key, Value] @@ -77,6 +90,7 @@ class OpenHashMap[Key, Value](initialSize : Int) extends Map[Key, Value] override def size = _size; private[this] def size_=(s : Int) = _size = s; + /** Returns a mangled hash code of the provided key. */ protected def hashOf(key : Key) = { var h = key.hashCode; h ^= ((h >>> 20) ^ (h >>> 12)); @@ -173,9 +187,10 @@ class OpenHashMap[Key, Value](initialSize : Int) extends Map[Key, Value] None; } - /** - * An iterator over the elements of this map. Use of this iterator follows the same - * contract for concurrent modification as the foreach method. + /** An iterator over the elements of this map. Use of this iterator follows the same + * contract for concurrent modification as the foreach method. + * + * @return the iterator */ def iterator = new Iterator[(Key, Value)]{ var index = 0; @@ -203,19 +218,20 @@ class OpenHashMap[Key, Value](initialSize : Int) extends Map[Key, Value] } /** - * Loop over the key, value mappings of this map. + * Loop over the key, value mappings of this map. * - * The behaviour of modifying the map during an iteration is as follows: + * The behaviour of modifying the map during an iteration is as follows: * - * + * * - * @param f The function to apply to each key, value mapping. + * @tparam U The return type of the specified function `f`, return result of which is ignored. + * @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") @@ -226,6 +242,7 @@ class OpenHashMap[Key, Value](initialSize : Int) extends Map[Key, Value] private[this] def foreachUndeletedEntry(f : Entry => Unit){ table.foreach(entry => if (entry != null && entry.value != None) f(entry)); } + override def transform(f : (Key, Value) => Value) = { foreachUndeletedEntry(entry => entry.value = Some(f(entry.key, entry.value.get))); this diff --git a/src/library/scala/collection/mutable/PriorityQueue.scala b/src/library/scala/collection/mutable/PriorityQueue.scala index eade376abe..37e1b0ccae 100644 --- a/src/library/scala/collection/mutable/PriorityQueue.scala +++ b/src/library/scala/collection/mutable/PriorityQueue.scala @@ -19,11 +19,20 @@ import annotation.migration * To prioritize elements of type T there must be an implicit * Ordering[T] available at creation. * + * @tparam A type of the elements in this priority queue. + * @param ord implicit ordering used to compare the elements of type `A`. + * * @author Matthias Zenger * @version 1.0, 03/05/2004 * @since 1 + * + * @define Coll PriorityQueue + * @define coll priority queue + * @define orderDependent + * @define orderDependentFold + * @define mayNotTerminateInf + * @define willNotTerminateInf */ - @serializable @cloneable class PriorityQueue[A](implicit ord: Ordering[A]) extends Seq[A] @@ -98,6 +107,7 @@ class PriorityQueue[A](implicit ord: Ordering[A]) k = k / 2 } } + protected def fixDown(as: Array[AnyRef], m: Int, n: Int): Unit = { var k: Int = m while (n >= 2 * k) { @@ -134,7 +144,8 @@ class PriorityQueue[A](implicit ord: Ordering[A]) /** Inserts a single element into the priority queue. * - * @param elem the element to insert + * @param elem the element to insert. + * @return this $coll. */ def +=(elem: A): this.type = { resarr.p_ensureSize(resarr.p_size0 + 1) @@ -147,7 +158,8 @@ class PriorityQueue[A](implicit ord: Ordering[A]) /** Adds all elements provided by a `TraversableOnce` object * into the priority queue. * - * @param xs an iterable object + * @param xs a traversable object. + * @return a new priority queue containing elements of both `xs` and `this`. */ def ++(xs: TraversableOnce[A]) = { this.clone() ++= xs } @@ -203,19 +215,19 @@ 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'', - * assuming the original ordering abides its contract. + + /** 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'', + * 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 - * will be subsequent, but their corresponding subinterval may be inappropriately - * reversed. However, due to the compare-equals contract, they will also be equal. + * Note that the order of the elements will be reversed unless the + * `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. + * @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 3f1ee5d217..f99755128f 100644 --- a/src/library/scala/collection/mutable/PriorityQueueProxy.scala +++ b/src/library/scala/collection/mutable/PriorityQueueProxy.scala @@ -13,7 +13,7 @@ package mutable /** 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. + * `Ordered[T]` class. * * @author Matthias Zenger * @version 1.0, 03/05/2004 @@ -22,7 +22,6 @@ package mutable abstract class PriorityQueueProxy[A](implicit ord: Ordering[A]) extends PriorityQueue[A] with Proxy { - def self: PriorityQueue[A] /** Creates a new iterator over all elements contained in this diff --git a/src/library/scala/collection/mutable/Publisher.scala b/src/library/scala/collection/mutable/Publisher.scala index 58e4394ef7..f91864f974 100644 --- a/src/library/scala/collection/mutable/Publisher.scala +++ b/src/library/scala/collection/mutable/Publisher.scala @@ -13,12 +13,14 @@ package scala.collection package mutable -/** Publisher[A,This] objects publish events of type A +/** `Publisher[A,This]` objects publish events of type `A` * to all registered subscribers. When subscribing, a subscriber may specify * a filter which can be used to constrain the number of events sent to the * subscriber. Subscribers may suspend their subscription, or reactivate a - * suspended subscription. Class Publisher is typically used - * as a mixin. The abstract type Pub models the type of the publisher itself. + * suspended subscription. Class `Publisher` is typically used + * as a mixin. The abstract type `Pub` models the type of the publisher itself. + * + * @tparam Evt type of the published event. * * @author Matthias Zenger * @author Martin Odersky diff --git a/src/library/scala/collection/mutable/Queue.scala b/src/library/scala/collection/mutable/Queue.scala index 3754dbc3f2..ef5583ab23 100644 --- a/src/library/scala/collection/mutable/Queue.scala +++ b/src/library/scala/collection/mutable/Queue.scala @@ -14,13 +14,20 @@ package mutable import generic._ -/** Queue objects implement data structures that allow to +/** `Queue` objects implement data structures that allow to * insert and retrieve elements in a first-in-first-out (FIFO) manner. * * @author Matthias Zenger * @author Martin Odersky * @version 2.8 * @since 1 + * + * @define Coll Queue + * @define coll queue + * @define orderDependent + * @define orderDependentFold + * @define mayNotTerminateInf + * @define willNotTerminateInf */ @serializable @cloneable class Queue[A] extends MutableList[A] with Cloneable[Queue[A]] { diff --git a/src/library/scala/collection/mutable/QueueProxy.scala b/src/library/scala/collection/mutable/QueueProxy.scala index b2548b26cc..6adb3d490b 100644 --- a/src/library/scala/collection/mutable/QueueProxy.scala +++ b/src/library/scala/collection/mutable/QueueProxy.scala @@ -12,9 +12,11 @@ package scala.collection package mutable -/** Queue objects implement data structures that allow to +/** `Queue` objects implement data structures that allow to * insert and retrieve elements in a first-in-first-out (FIFO) manner. * + * @tparam A type of the elements in this queue proxy. + * * @author Matthias Zenger * @version 1.1, 03/05/2004 * @since 1 diff --git a/src/library/scala/collection/mutable/ResizableArray.scala b/src/library/scala/collection/mutable/ResizableArray.scala index 80ab1cd559..96d24136cf 100644 --- a/src/library/scala/collection/mutable/ResizableArray.scala +++ b/src/library/scala/collection/mutable/ResizableArray.scala @@ -17,6 +17,8 @@ import generic._ /** This class is used internally to implement data structures that * are based on resizable arrays. * + * @tparam A type of the elements contained in this resizeable array. + * * @author Matthias Zenger, Burak Emir * @author Martin Odersky * @version 2.8 diff --git a/src/library/scala/collection/mutable/RevertibleHistory.scala b/src/library/scala/collection/mutable/RevertibleHistory.scala index 62e1efba2f..b16577486a 100644 --- a/src/library/scala/collection/mutable/RevertibleHistory.scala +++ b/src/library/scala/collection/mutable/RevertibleHistory.scala @@ -13,10 +13,13 @@ package scala.collection package mutable -/** A revertible history is a History object which supports - * an undo operation. Type variable A refers to the type - * of the published events, B denotes the publisher type. - * Type B is typically a subtype of Publisher. +/** A revertible history is a `History` object which supports + * an undo operation. Type variable `Evt` refers to the type + * of the published events, `Pub` denotes the publisher type. + * Type `Pub` is typically a subtype of `Publisher`. + * + * @tparam Evt type of the events + * @tparam Pub type of the publisher * * @author Matthias Zenger * @version 1.0, 08/07/2003 diff --git a/src/library/scala/collection/mutable/Seq.scala b/src/library/scala/collection/mutable/Seq.scala index 8d11e14063..832e949931 100644 --- a/src/library/scala/collection/mutable/Seq.scala +++ b/src/library/scala/collection/mutable/Seq.scala @@ -14,17 +14,21 @@ package mutable import generic._ -/** A subtrait of collection.Seq which represents sequences + +/** A subtrait of `collection.Seq` which represents sequences * that can be mutated. * * $seqInfo * - * The class adds an update method to collection.Seq. + * The class adds an `update` method to `collection.Seq`. + * + * @define Coll mutable.Seq + * @define coll mutable sequence */ trait Seq[A] extends Iterable[A] - with scala.collection.Seq[A] - with GenericTraversableTemplate[A, Seq] - with SeqLike[A, Seq[A]] { + with scala.collection.Seq[A] + with GenericTraversableTemplate[A, Seq] + with SeqLike[A, Seq[A]] { override def companion: GenericCompanion[Seq] = Seq /** Replaces element at given index with a new value. @@ -36,13 +40,13 @@ trait Seq[A] extends Iterable[A] def update(idx: Int, elem: A) } -/** A factory object for the trait Seq. - * - * @author Martin Odersky - * @version 2.8 - * @since 2.8 + +/** $factoryInfo + * @define coll sequence + * @define Coll Seq */ object Seq extends SeqFactory[Seq] { + /** $genericCanBuildFromInfo */ implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, Seq[A]] = new GenericCanBuildFrom[A] def newBuilder[A]: Builder[A, Seq[A]] = new ArrayBuffer } diff --git a/src/library/scala/collection/mutable/Set.scala b/src/library/scala/collection/mutable/Set.scala index cca592b5a0..a816816846 100644 --- a/src/library/scala/collection/mutable/Set.scala +++ b/src/library/scala/collection/mutable/Set.scala @@ -17,14 +17,18 @@ import generic._ /** A generic trait for mutable sets. Concrete set implementations * have to provide functionality for the abstract methods in Set: * + * {{{ * def contains(elem: A): Boolean * def iterator: Iterator[A] * def += (elem: A): this.type * def -= (elem: A): this.type + * }}} + * + * $setnote + * + * @tparam A type of the elements contained in this set. * * @author Matthias Zenger - * @author Martin Odersky - * @version 2.8 * @since 1 */ trait Set[A] extends Iterable[A] @@ -34,10 +38,12 @@ trait Set[A] extends Iterable[A] override def companion: GenericCompanion[Set] = Set } -/** The canonical factory methods for mutable sets. - * Currently this returns a HashSet. +/** $factoryInfo + * @define coll set + * @define Coll Set */ object Set extends SetFactory[Set] { + /** $setCanBuildFromInfo */ implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, Set[A]] = setCanBuildFrom[A] override def empty[A]: Set[A] = HashSet.empty[A] } diff --git a/src/library/scala/collection/mutable/SetBuilder.scala b/src/library/scala/collection/mutable/SetBuilder.scala index 450d76463c..b8903372bd 100644 --- a/src/library/scala/collection/mutable/SetBuilder.scala +++ b/src/library/scala/collection/mutable/SetBuilder.scala @@ -15,6 +15,8 @@ import generic._ /** The canonical builder for mutable Sets. * + * @tparam A The type of the elements that will be contained in this set. + * @tparam Coll The type of the actual collection this set builds. * @param empty The empty element of the collection. * @since 2.8 */ diff --git a/src/library/scala/collection/mutable/Stack.scala b/src/library/scala/collection/mutable/Stack.scala index c224c030a4..72e2f928c8 100644 --- a/src/library/scala/collection/mutable/Stack.scala +++ b/src/library/scala/collection/mutable/Stack.scala @@ -20,10 +20,18 @@ import annotation.migration /** A stack implements a data structure which allows to store and retrieve * objects in a last-in-first-out (LIFO) fashion. * + * @tparam A type of the elements contained in this stack. + * * @author Matthias Zenger * @author Martin Odersky * @version 2.8 * @since 1 + * @define Coll Stack + * @define coll stack + * @define orderDependent + * @define orderDependentFold + * @define mayNotTerminateInf + * @define willNotTerminateInf */ @serializable @cloneable class Stack[A] private (var elems: List[A]) extends scala.collection.Seq[A] with Cloneable[Stack[A]] { diff --git a/src/library/scala/collection/mutable/StackProxy.scala b/src/library/scala/collection/mutable/StackProxy.scala index d3810dd158..740afdfd7d 100644 --- a/src/library/scala/collection/mutable/StackProxy.scala +++ b/src/library/scala/collection/mutable/StackProxy.scala @@ -12,9 +12,12 @@ package scala.collection package mutable + /** A stack implements a data structure which allows to store and retrieve * objects in a last-in-first-out (LIFO) fashion. * + * @tparam A type of the elements in this stack proxy. + * * @author Matthias Zenger * @version 1.0, 10/05/2004 * @since 1 diff --git a/src/library/scala/collection/mutable/StringBuilder.scala b/src/library/scala/collection/mutable/StringBuilder.scala index d622d15056..40e7e991ee 100644 --- a/src/library/scala/collection/mutable/StringBuilder.scala +++ b/src/library/scala/collection/mutable/StringBuilder.scala @@ -16,11 +16,8 @@ import generic._ import compat.Platform.arraycopy import scala.reflect.Manifest -/**

- * A mutable sequence of characters. This class provides an API compatible - * with - * java.lang.StringBuilder. - *

generic/ +/** A builder for mutable sequence of characters. This class provides an API compatible + * with `java.lang.StringBuilder`. * * @author Stephane Micheloud * @author Martin Odersky diff --git a/src/library/scala/collection/mutable/SynchronizedBuffer.scala b/src/library/scala/collection/mutable/SynchronizedBuffer.scala index 0fef1a6635..7bdbd5e520 100644 --- a/src/library/scala/collection/mutable/SynchronizedBuffer.scala +++ b/src/library/scala/collection/mutable/SynchronizedBuffer.scala @@ -14,12 +14,16 @@ package mutable import script._ -/** This class should be used as a mixin. It synchronizes the Buffer +/** This class should be used as a mixin. It synchronizes the `Buffer` * methods of the class into which it is mixed in. * + * @tparam A type of the elements contained in this buffer. + * * @author Matthias Zenger * @version 1.0, 08/07/2003 * @since 1 + * @define Coll SynchronizedBuffer + * @define coll synchronized buffer */ trait SynchronizedBuffer[A] extends Buffer[A] { diff --git a/src/library/scala/collection/mutable/SynchronizedMap.scala b/src/library/scala/collection/mutable/SynchronizedMap.scala index dabcaa7e1c..08c370ce90 100644 --- a/src/library/scala/collection/mutable/SynchronizedMap.scala +++ b/src/library/scala/collection/mutable/SynchronizedMap.scala @@ -14,12 +14,17 @@ package mutable import annotation.migration -/** This class should be used as a mixin. It synchronizes the Map +/** This class should be used as a mixin. It synchronizes the `Map` * functions of the class into which it is mixed in. * + * @tparam A type of the keys contained in this map. + * @tparam B type of the values associated with keys. + * * @author Matthias Zenger, Martin Odersky * @version 2.0, 31/12/2006 * @since 1 + * @define Coll SynchronizedMap + * @define coll synchronized map */ trait SynchronizedMap[A, B] extends Map[A, B] { diff --git a/src/library/scala/collection/mutable/SynchronizedPriorityQueue.scala b/src/library/scala/collection/mutable/SynchronizedPriorityQueue.scala index 933b3b41a4..bc70e35993 100644 --- a/src/library/scala/collection/mutable/SynchronizedPriorityQueue.scala +++ b/src/library/scala/collection/mutable/SynchronizedPriorityQueue.scala @@ -13,12 +13,16 @@ package scala.collection package mutable /** 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. + * The elements of the queue have to be ordered in terms of the `Ordered[T]` class. + * + * @tparam A type of the elements contained in this synchronized priority queue + * @param ord implicit ordering used to compared elements of type `A` * * @author Matthias Zenger * @version 1.0, 03/05/2004 * @since 1 + * @define Coll SynchronizedPriorityQueue + * @define coll synchronized priority queue */ class SynchronizedPriorityQueue[A](implicit ord: Ordering[A]) extends PriorityQueue[A] { diff --git a/src/library/scala/collection/mutable/SynchronizedQueue.scala b/src/library/scala/collection/mutable/SynchronizedQueue.scala index b09687a78e..7a0f9f5f6f 100644 --- a/src/library/scala/collection/mutable/SynchronizedQueue.scala +++ b/src/library/scala/collection/mutable/SynchronizedQueue.scala @@ -13,13 +13,17 @@ package scala.collection package mutable -/** This is a synchronized version of the Queue[T] class. It +/** This is a synchronized version of the `Queue[T]` class. It * implements a data structure that allows one to insert and retrieve * elements in a first-in-first-out (FIFO) manner. * + * @tparam A type of elements contained in this synchronized queue. + * * @author Matthias Zenger * @version 1.0, 03/05/2004 * @since 1 + * @define Coll SynchronizedQueue + * @define coll synchronized queue */ class SynchronizedQueue[A] extends Queue[A] { import scala.collection.Traversable diff --git a/src/library/scala/collection/mutable/SynchronizedSet.scala b/src/library/scala/collection/mutable/SynchronizedSet.scala index d3023b9136..904da541c2 100644 --- a/src/library/scala/collection/mutable/SynchronizedSet.scala +++ b/src/library/scala/collection/mutable/SynchronizedSet.scala @@ -13,12 +13,16 @@ package mutable import script._ -/** This class should be used as a mixin. It synchronizes the Set +/** This class should be used as a mixin. It synchronizes the `Set` * functions of the class into which it is mixed in. * + * @tparam A type of the elements contained in this synchronized set. + * * @author Matthias Zenger * @version 1.0, 08/07/2003 * @since 1 + * @define Coll SynchronizedSet + * @define coll synchronized set */ trait SynchronizedSet[A] extends Set[A] { import scala.collection.Traversable diff --git a/src/library/scala/collection/mutable/SynchronizedStack.scala b/src/library/scala/collection/mutable/SynchronizedStack.scala index 4940884302..9109d2ef5d 100644 --- a/src/library/scala/collection/mutable/SynchronizedStack.scala +++ b/src/library/scala/collection/mutable/SynchronizedStack.scala @@ -13,13 +13,17 @@ package scala.collection package mutable -/** This is a synchronized version of the Stack[T] class. It +/** This is a synchronized version of the `Stack[T]` class. It * implements a data structure which allows to store and retrieve * objects in a last-in-first-out (LIFO) fashion. * + * @tparam A type of the elements contained in this stack. + * * @author Matthias Zenger * @version 1.0, 03/05/2004 * @since 1 + * @define Coll SynchronizedStack + * @define coll synchronized stack */ class SynchronizedStack[A] extends Stack[A] { import scala.collection.Traversable diff --git a/src/library/scala/collection/mutable/Traversable.scala b/src/library/scala/collection/mutable/Traversable.scala index 89c8868314..9a7153235a 100644 --- a/src/library/scala/collection/mutable/Traversable.scala +++ b/src/library/scala/collection/mutable/Traversable.scala @@ -25,10 +25,9 @@ trait Traversable[A] extends scala.collection.Traversable[A] override def companion: GenericCompanion[Traversable] = Traversable } -/** A factory object for the trait Traversable. - * - * @author Martin Odersky - * @version 2.8 +/** $factoryInfo + * @define Coll mutable.Traversable + * @define coll mutable traversable */ object Traversable extends TraversableFactory[Traversable] { implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, Traversable[A]] = new GenericCanBuildFrom[A] diff --git a/src/library/scala/collection/mutable/Undoable.scala b/src/library/scala/collection/mutable/Undoable.scala index 782e407843..45d3121bd3 100644 --- a/src/library/scala/collection/mutable/Undoable.scala +++ b/src/library/scala/collection/mutable/Undoable.scala @@ -13,8 +13,8 @@ package scala.collection package mutable -/** Classes that mix in the Undoable class provide an operation - * undo which can be used to undo the last operation. +/** Classes that mix in the `Undoable` class provide an operation + * `undo` which can be used to undo the last operation. * * @author Matthias Zenger * @version 1.0, 08/07/2003 diff --git a/src/library/scala/collection/mutable/WeakHashMap.scala b/src/library/scala/collection/mutable/WeakHashMap.scala index 8f496add1e..929c3f8fed 100644 --- a/src/library/scala/collection/mutable/WeakHashMap.scala +++ b/src/library/scala/collection/mutable/WeakHashMap.scala @@ -16,15 +16,35 @@ import JavaConversions._ import generic._ -/** A hash map with weak references to entries which are weakly reachable. +/** A hash map with references to entries which are weakly reachable. + * + * @tparam A type of keys contained in this map + * @tparam B type of values associated with the keys * * @since 2.8 + * @define Coll WeakHashMap + * @define coll weak hash map + * @define thatinfo the class of the returned collection. In the standard library configuration, + * `That` is always `WeakHashMap[A, B]` if the elements contained in the resulting collection are + * pairs of type `(A, B)`. This is because an implicit of type `CanBuildFrom[WeakHashMap, (A, B), WeakHashMap[A, B]]` + * is defined in object `WeakHashMap`. 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 `WeakHashMap`. + * @define mayNotTerminateInf + * @define willNotTerminateInf */ class WeakHashMap[A, B] extends JMapWrapper[A, B](new java.util.WeakHashMap) with JMapWrapperLike[A, B, WeakHashMap[A, B]] { override def empty = new WeakHashMap[A, B] } +/** $factoryInfo + * @define Coll WeakHashMap + * @define coll weak hash map + */ object WeakHashMap extends MutableMapFactory[WeakHashMap] { implicit def canBuildFrom[A, B]: CanBuildFrom[Coll, (A, B), WeakHashMap[A, B]] = new MapCanBuildFrom[A, B] def empty[A, B]: WeakHashMap[A, B] = new WeakHashMap[A, B] diff --git a/src/library/scala/collection/mutable/WrappedArray.scala b/src/library/scala/collection/mutable/WrappedArray.scala index 10117a1086..b9e803d8dc 100644 --- a/src/library/scala/collection/mutable/WrappedArray.scala +++ b/src/library/scala/collection/mutable/WrappedArray.scala @@ -16,11 +16,19 @@ import scala.reflect.ClassManifest import scala.collection.generic._ /** - *

A class representing Array[T]

+ * A class representing `Array[T]`. + * + * @tparam T type of the elements in this wrapped array. * * @author Martin Odersky, Stephane Micheloud * @version 1.0 * @since 2.8 + * @define Coll WrappedArray + * @define coll wrapped array + * @define orderDependent + * @define orderDependentFold + * @define mayNotTerminateInf + * @define willNotTerminateInf */ abstract class WrappedArray[T] extends IndexedSeq[T] with ArrayLike[T, WrappedArray[T]] { @@ -59,6 +67,8 @@ abstract class WrappedArray[T] extends IndexedSeq[T] with ArrayLike[T, WrappedAr new WrappedArrayBuilder[T](elemManifest) } +/** A companion object used to create instances of `WrappedArray`. + */ object WrappedArray { def make[T](x: AnyRef): WrappedArray[T] = x match { case x: Array[AnyRef] => wrapRefArray[AnyRef](x).asInstanceOf[WrappedArray[T]] diff --git a/src/library/scala/collection/mutable/WrappedArrayBuilder.scala b/src/library/scala/collection/mutable/WrappedArrayBuilder.scala index 7f1e4b3254..012a0be862 100644 --- a/src/library/scala/collection/mutable/WrappedArrayBuilder.scala +++ b/src/library/scala/collection/mutable/WrappedArrayBuilder.scala @@ -15,7 +15,10 @@ package mutable import generic._ import scala.reflect.ClassManifest -/** A builder class for arrays +/** A builder class for arrays. + * + * @tparam A type of elements that can be added to this builder. + * @param manifest class manifest for objects of type `A`. * * @since 2.8 */ -- cgit v1.2.3