From 628b2edf7363265748e0d345298d6e3663d8133b Mon Sep 17 00:00:00 2001 From: Aleksandar Pokopec Date: Tue, 13 Apr 2010 10:29:58 +0000 Subject: docs for immutable.A-L*. no review --- .../collection/generic/ImmutableMapFactory.scala | 8 +++- .../scala/collection/immutable/BitSet.scala | 6 ++- .../scala/collection/immutable/DefaultMap.scala | 44 ++++++++++++++-------- .../scala/collection/immutable/HashMap.scala | 21 +++++++---- .../scala/collection/immutable/HashSet.scala | 22 +++++++---- .../scala/collection/immutable/IndexedSeq.scala | 2 +- .../scala/collection/immutable/IntMap.scala | 24 +++++++----- .../scala/collection/immutable/Iterable.scala | 12 +++--- .../scala/collection/immutable/LinearSeq.scala | 2 +- .../scala/collection/immutable/ListMap.scala | 18 ++++++--- .../scala/collection/immutable/ListSet.scala | 16 ++++++-- .../scala/collection/immutable/LongMap.scala | 26 ++++++++----- .../scala/collection/mutable/IndexedSeq.scala | 1 - src/library/scala/collection/mutable/ListMap.scala | 4 +- 14 files changed, 133 insertions(+), 73 deletions(-) (limited to 'src') diff --git a/src/library/scala/collection/generic/ImmutableMapFactory.scala b/src/library/scala/collection/generic/ImmutableMapFactory.scala index 2fd22e7f02..494036467f 100644 --- a/src/library/scala/collection/generic/ImmutableMapFactory.scala +++ b/src/library/scala/collection/generic/ImmutableMapFactory.scala @@ -11,9 +11,15 @@ package scala.collection package generic -/** A template for companion objects of immutable.Map and +/** A template for companion objects of `immutable.Map` and * subclasses thereof. * * @since 2.8 + * @define Coll immutable.Map + * @define coll immutable map + * @define factoryInfo + * This object provides a set of operations needed to create immutable maps of type `$Coll`. + * @author Martin Odersky + * @version 2.8 */ abstract class ImmutableMapFactory[CC[A, +B] <: immutable.Map[A, B] with immutable.MapLike[A, B, CC[A, B]]] extends MapFactory[CC] diff --git a/src/library/scala/collection/immutable/BitSet.scala b/src/library/scala/collection/immutable/BitSet.scala index 857b537904..4c90a89104 100644 --- a/src/library/scala/collection/immutable/BitSet.scala +++ b/src/library/scala/collection/immutable/BitSet.scala @@ -17,6 +17,8 @@ import BitSetLike.{LogWL, updateArray} /** A class for immutable bitsets. * $bitsetinfo + * @define Coll immutable.BitSet + * @define coll immutable bitset */ @serializable @SerialVersionUID(1611436763290191562L) abstract class BitSet extends Set[Int] @@ -53,12 +55,14 @@ abstract class BitSet extends Set[Int] } } -/** A factory object for bitsets */ +/** $factoryInfo + */ object BitSet extends BitSetFactory[BitSet] { /** The empty bitset */ val empty: BitSet = new BitSet1(0L) + /** $bitsetCanBuildFrom */ implicit def canBuildFrom: CanBuildFrom[BitSet, Int, BitSet] = bitsetCanBuildFrom /** A bitset containing all the bits in an array */ diff --git a/src/library/scala/collection/immutable/DefaultMap.scala b/src/library/scala/collection/immutable/DefaultMap.scala index a19b35aff0..667d86d352 100755 --- a/src/library/scala/collection/immutable/DefaultMap.scala +++ b/src/library/scala/collection/immutable/DefaultMap.scala @@ -14,22 +14,24 @@ package immutable import generic._ -/**

- * A default map which implements the updated and - - * 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)]
- *

- * It refers back to the original map. - *

- *

- * It might also be advisable to override foreach or - * size if efficient implementations can be found. - *

+/** A default map which implements the `+` and `-` + * methods of maps. It does so using the default builder for + * maps defined in the `Map` object. + * Instances that inherit from `DefaultMap[A, B]` still have to + * define: + * + * {{{ + * def get(key: A): Option[B] + * def iterator: Iterator[(A, B)] + * }}} + * + * It refers back to the original map. + * + * It might also be advisable to override `foreach` or + * `size` if efficient implementations can be found. + * + * @tparam A the type of the keys contained in this map. + * @tparam B the type of the values associated with the keys. * * @since 2.8 */ @@ -52,3 +54,13 @@ trait DefaultMap[A, +B] extends Map[A, B] { self => b.result } } + + + + + + + + + + diff --git a/src/library/scala/collection/immutable/HashMap.scala b/src/library/scala/collection/immutable/HashMap.scala index e0f801546c..c83a5ffcb8 100644 --- a/src/library/scala/collection/immutable/HashMap.scala +++ b/src/library/scala/collection/immutable/HashMap.scala @@ -15,17 +15,22 @@ package immutable import generic._ import annotation.unchecked.uncheckedVariance -/**

- * This class implements immutable maps using a hash trie. - *

+/** This class implements immutable maps using a hash trie. * - * @note the builder of a hash map returns specialized representations EmptyMap,Map1,..., Map4 - * for maps of size <= 4. + * Note: the builder of a hash map returns specialized representations EmptyMap,Map1,..., Map4 + * for maps of size <= 4. + * + * @tparam A the type of the keys contained in this hash map. + * @tparam B the type of the values associated with the keys. * * @author Martin Odersky * @author Tiark Rompf * @version 2.8 * @since 2.3 + * @define Coll immutable.HashMap + * @define coll immutable hash map + * @define mayNotTerminateInf + * @define willNotTerminateInf */ @serializable @SerialVersionUID(2L) class HashMap[A, +B] extends Map[A,B] with MapLike[A, B, HashMap[A, B]] { @@ -76,11 +81,11 @@ class HashMap[A, +B] extends Map[A,B] with MapLike[A, B, HashMap[A, B]] { } -/** A factory object for immutable HashMaps. +/** $factoryInfo + * @define Coll immutable.HashMap + * @define coll immutable hash map * - * @author Martin Odersky * @author Tiark Rompf - * @version 2.8 * @since 2.3 */ object HashMap extends ImmutableMapFactory[HashMap] { diff --git a/src/library/scala/collection/immutable/HashSet.scala b/src/library/scala/collection/immutable/HashSet.scala index e79b456a2f..4779702ea7 100644 --- a/src/library/scala/collection/immutable/HashSet.scala +++ b/src/library/scala/collection/immutable/HashSet.scala @@ -15,16 +15,19 @@ 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`. + * + * @tparam A the type of the elements contained in this hash set. * * @author Martin Odersky * @author Tiark Rompf * @version 2.8 * @since 2.3 + * @define Coll immutable.HashSet + * @define coll immutable hash set */ @serializable @SerialVersionUID(2L) class HashSet[A] extends Set[A] @@ -83,14 +86,19 @@ object HashSet extends SetFactory[HashSet] { */ -/** A factory object for immutable HashSets. +/** $factoryInfo + * @define Coll immutable.HashSet + * @define coll immutable hash set * - * @author Martin Odersky * @author Tiark Rompf - * @version 2.8 * @since 2.3 + * @define Coll immutable.HashSet + * @define coll immutable hash set + * @define mayNotTerminateInf + * @define willNotTerminateInf */ object HashSet extends SetFactory[HashSet] { + /** $setCanBuildFromInfo */ implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, HashSet[A]] = setCanBuildFrom[A] override def empty[A]: HashSet[A] = EmptyHashSet.asInstanceOf[HashSet[A]] diff --git a/src/library/scala/collection/immutable/IndexedSeq.scala b/src/library/scala/collection/immutable/IndexedSeq.scala index 268bd56a85..4064e9e3a9 100644 --- a/src/library/scala/collection/immutable/IndexedSeq.scala +++ b/src/library/scala/collection/immutable/IndexedSeq.scala @@ -14,7 +14,7 @@ package immutable import generic._ import mutable.{ArrayBuffer, Builder} -/** A subtrait of collection.IndexedSeq which represents indexed sequences +/** A subtrait of `collection.IndexedSeq` which represents indexed sequences * that are guaranteed immutable. * $indexedSeqInfo */ diff --git a/src/library/scala/collection/immutable/IntMap.scala b/src/library/scala/collection/immutable/IntMap.scala index 75a25e0223..90dfa541e3 100644 --- a/src/library/scala/collection/immutable/IntMap.scala +++ b/src/library/scala/collection/immutable/IntMap.scala @@ -12,8 +12,8 @@ package scala.collection package immutable; -/** - * @author David MacIver +/** Utility class for integer maps. + * @author David MacIver */ private[immutable] object IntMapUtils { def zero(i : Int, mask : Int) = (i & mask) == 0; @@ -50,8 +50,8 @@ private[immutable] object IntMapUtils { import IntMapUtils._ -/** - * @since 2.7 +/** A companion object for integer maps. + * @since 2.7 */ object IntMap { def empty[T] : IntMap[T] = IntMap.Nil; @@ -146,15 +146,19 @@ private[immutable] class IntMapKeyIterator[V](it : IntMap[V]) extends IntMapIter import IntMap._ -/** - * Specialised immutable map structure for integer keys, based on - * Fast Mergeable Integer Maps - * by Okasaki and Gill. Essentially a trie based on binary digits of the the integers. +/** Specialised immutable map structure for integer keys, based on + * Fast Mergeable Integer Maps + * by Okasaki and Gill. Essentially a trie based on binary digits of the the integers. * - * Note: This class is as of 2.8 largely superseded by HashMap. + * Note: This class is as of 2.8 largely superseded by HashMap. * - * @since 2.7 + * @tparam T type of the values associated with integer keys. * + * @since 2.7 + * @define Coll immutable.IntMap + * @define coll immutable integer map + * @define mayNotTerminateInf + * @define willNotTerminateInf */ sealed abstract class IntMap[+T] extends Map[Int, T] with MapLike[Int, T, IntMap[T]] { override def empty: IntMap[T] = IntMap.Nil; diff --git a/src/library/scala/collection/immutable/Iterable.scala b/src/library/scala/collection/immutable/Iterable.scala index 795fc2fa92..e0ef5ffcc1 100644 --- a/src/library/scala/collection/immutable/Iterable.scala +++ b/src/library/scala/collection/immutable/Iterable.scala @@ -17,6 +17,9 @@ import mutable.Builder /** A base trait for iterable collections that are guaranteed immutable. * $iterableInfo + * + * @define Coll immutable.Iterable + * @define coll immutable iterable collection */ trait Iterable[+A] extends Traversable[A] with scala.collection.Iterable[A] @@ -25,14 +28,11 @@ 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 - * @since 2.8 +/** $factoryInfo + * @define Coll immutable.Iterable + * @define coll immutable iterable collection */ object Iterable extends TraversableFactory[Iterable] { implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, Iterable[A]] = new GenericCanBuildFrom[A] def newBuilder[A]: Builder[A, Iterable[A]] = new mutable.ListBuffer } - diff --git a/src/library/scala/collection/immutable/LinearSeq.scala b/src/library/scala/collection/immutable/LinearSeq.scala index 9cb35dced5..1ffe96310e 100644 --- a/src/library/scala/collection/immutable/LinearSeq.scala +++ b/src/library/scala/collection/immutable/LinearSeq.scala @@ -15,7 +15,7 @@ package immutable import generic._ import mutable.Builder -/** A subtrait of collection.LinearSeq which represents sequences that +/** A subtrait of `collection.LinearSeq` which represents sequences that * are guaranteed immutable. * $linearSeqInfo */ diff --git a/src/library/scala/collection/immutable/ListMap.scala b/src/library/scala/collection/immutable/ListMap.scala index 4342e54a9d..13d5bbe2ac 100644 --- a/src/library/scala/collection/immutable/ListMap.scala +++ b/src/library/scala/collection/immutable/ListMap.scala @@ -14,9 +14,10 @@ package immutable import generic._ -/** The canonical factory of ListMap's. - * +/** $factoryInfo * @since 1 + * @define Coll immutable.ListMap + * @define coll immutable list map */ object ListMap extends ImmutableMapFactory[ListMap] { implicit def canBuildFrom[A, B]: CanBuildFrom[Coll, (A, B), ListMap[A, B]] = @@ -25,14 +26,21 @@ object ListMap extends ImmutableMapFactory[ListMap] { } /** This class implements immutable maps using a list-based data - * structure. Instances of ListMap represent + * structure. Instances of `ListMap` represent * empty maps; they can be either created by calling the constructor - * directly, or by applying the function ListMap.empty. + * directly, or by applying the function `ListMap.empty`. + * + * @tparam A the type of the keys in this list map. + * @tparam B the type of the values associated with the keys. * * @author Matthias Zenger * @author Martin Odersky * @version 2.0, 01/01/2007 * @since 1 + * @define Coll immutable.ListMap + * @define coll immutable list map + * @define mayNotTerminateInf + * @define willNotTerminateInf */ @serializable @SerialVersionUID(301002838095710379L) class ListMap[A, +B] extends Map[A, B] with MapLike[A, B, ListMap[A, B]] { @@ -45,7 +53,7 @@ class ListMap[A, +B] extends Map[A, B] with MapLike[A, B, ListMap[A, B]] { */ override def size: Int = 0 - /** Checks if this map maps key to a value and return the + /** Checks if this map maps `key` to a value and return the * value if it exists. * * @param key the key of the mapping of interest diff --git a/src/library/scala/collection/immutable/ListSet.scala b/src/library/scala/collection/immutable/ListSet.scala index f7b76d2317..2a202df9ef 100644 --- a/src/library/scala/collection/immutable/ListSet.scala +++ b/src/library/scala/collection/immutable/ListSet.scala @@ -14,24 +14,32 @@ package immutable import generic._ -/** The canonical factory of ListSet's - * +/** $factoryInfo + * @define Coll immutable.ListSet + * @define coll immutable list set * @since 1 */ object ListSet extends SetFactory[ListSet] { + /** setCanBuildFromInfo */ implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, ListSet[A]] = setCanBuildFrom[A] override def empty[A] = new ListSet[A] } /** This class implements immutable sets using a list-based data - * structure. Instances of ListSet represent + * structure. Instances of `ListSet` represent * empty sets; they can be either created by calling the constructor - * directly, or by applying the function ListSet.empty. + * directly, or by applying the function `ListSet.empty`. + * + * @tparam A the type of the elements contained in this list set. * * @author Matthias Zenger * @version 1.0, 09/07/2003 * @since 1 + * @define Coll immutable.ListSet + * @define coll immutable list set + * @define mayNotTerminateInf + * @define willNotTerminateInf */ @serializable class ListSet[A] extends Set[A] diff --git a/src/library/scala/collection/immutable/LongMap.scala b/src/library/scala/collection/immutable/LongMap.scala index 24afb65b99..f31089d24c 100644 --- a/src/library/scala/collection/immutable/LongMap.scala +++ b/src/library/scala/collection/immutable/LongMap.scala @@ -1,8 +1,8 @@ package scala.collection package immutable -/** - * @author David MacIver +/** Utility class for long maps. + * @author David MacIver */ private[immutable] object LongMapUtils{ def zero(i : Long, mask : Long) = (i & mask) == 0L; @@ -40,8 +40,8 @@ private[immutable] object LongMapUtils{ import LongMapUtils._ -/** - * @since 2.7 +/** A companion object for long maps. + * @since 2.7 */ object LongMap{ def empty[T] : LongMap[T] = LongMap.Nil; @@ -134,13 +134,19 @@ private[immutable] class LongMapKeyIterator[V](it : LongMap[V]) extends LongMapI import LongMap._; /** - * Specialised immutable map structure for long keys, based on - * Fast Mergeable Long Maps - * by Okasaki and Gill. Essentially a trie based on binary digits of the the integers. + * Specialised immutable map structure for long keys, based on + * Fast Mergeable Long Maps + * by Okasaki and Gill. Essentially a trie based on binary digits of the the integers. + * + * Note: This class is as of 2.8 largely superseded by HashMap. * - * Note: This class is as of 2.8 largely superseded by HashMap. + * @tparam T type of the values associated with the long keys. * - * @since 2.7 + * @since 2.7 + * @define Coll immutable.LongMap + * @define coll immutable long integer map + * @define mayNotTerminateInf + * @define willNotTerminateInf */ sealed abstract class LongMap[+T] extends Map[Long, T] with MapLike[Long, T, LongMap[T]] { override def empty: LongMap[T] = LongMap.Nil; @@ -185,7 +191,7 @@ sealed abstract class LongMap[+T] extends Map[Long, T] with MapLike[Long, T, Lon case LongMap.Bin(_, _, left, right) => {left.foreachKey(f); right.foreachKey(f); } case LongMap.Tip(key, _) => f(key); case LongMap.Nil => {} - } + override def valuesIterator : Iterator[T] = this match { case LongMap.Nil => Iterator.empty; diff --git a/src/library/scala/collection/mutable/IndexedSeq.scala b/src/library/scala/collection/mutable/IndexedSeq.scala index 14ee5afc9b..a0b90f63df 100644 --- a/src/library/scala/collection/mutable/IndexedSeq.scala +++ b/src/library/scala/collection/mutable/IndexedSeq.scala @@ -16,7 +16,6 @@ import generic._ /** A subtrait of `collection.IndexedSeq` which represents sequences * that can be mutated. - * * $indexedSeqInfo */ trait IndexedSeq[A] extends Seq[A] diff --git a/src/library/scala/collection/mutable/ListMap.scala b/src/library/scala/collection/mutable/ListMap.scala index a4321d3818..09b0c6459b 100644 --- a/src/library/scala/collection/mutable/ListMap.scala +++ b/src/library/scala/collection/mutable/ListMap.scala @@ -59,8 +59,8 @@ class ListMap[A, B] extends Map[A, B] with MapLike[A, B, ListMap[A, B]] { } /** $factoryInfo - * @define Coll ListMap - * @define coll list map + * @define Coll mutable.ListMap + * @define coll mutable list map */ object ListMap extends MutableMapFactory[ListMap] { implicit def canBuildFrom[A, B]: CanBuildFrom[Coll, (A, B), ListMap[A, B]] = new MapCanBuildFrom[A, B] -- cgit v1.2.3