diff options
author | Aleksandar Pokopec <aleksandar.prokopec@epfl.ch> | 2010-04-13 15:50:39 +0000 |
---|---|---|
committer | Aleksandar Pokopec <aleksandar.prokopec@epfl.ch> | 2010-04-13 15:50:39 +0000 |
commit | bf0921a072c4761824365105c785dd5f2cf97588 (patch) | |
tree | 3bc5c6bb1346a4ebe4355108ac4345272b221540 /src | |
parent | 1973a1f7d3bbc052464ad0c8f43dda10b063f443 (diff) | |
download | scala-bf0921a072c4761824365105c785dd5f2cf97588.tar.gz scala-bf0921a072c4761824365105c785dd5f2cf97588.tar.bz2 scala-bf0921a072c4761824365105c785dd5f2cf97588.zip |
Docs. no review
Diffstat (limited to 'src')
12 files changed, 144 insertions, 50 deletions
diff --git a/src/library/scala/collection/generic/ImmutableMapFactory.scala b/src/library/scala/collection/generic/ImmutableMapFactory.scala index e61da8c1d0..6096a3184d 100644 --- a/src/library/scala/collection/generic/ImmutableMapFactory.scala +++ b/src/library/scala/collection/generic/ImmutableMapFactory.scala @@ -11,14 +11,14 @@ package scala.collection package generic -/** A template for companion objects of `immutable.Map` and +/** A template for companion objects of `Map` and * subclasses thereof. * * @since 2.8 - * @define Coll immutable.Map - * @define coll immutable map + * @define Coll Map + * @define coll map * @define factoryInfo - * This object provides a set of operations needed to create immutable maps of type `$Coll`. + * This object provides a set of operations needed to create maps of type `$Coll`. * @author Martin Odersky * @version 2.8 * @define mapCanBuildFromInfo diff --git a/src/library/scala/collection/generic/ImmutableSortedMapFactory.scala b/src/library/scala/collection/generic/ImmutableSortedMapFactory.scala index d5c372ba74..d30f57f0ce 100644 --- a/src/library/scala/collection/generic/ImmutableSortedMapFactory.scala +++ b/src/library/scala/collection/generic/ImmutableSortedMapFactory.scala @@ -12,8 +12,16 @@ package scala.collection package generic -/** A template for companion objects of immutable.Map and subclasses thereof. +/** A template for companion objects of `SortedMap` and subclasses thereof. * * @since 2.8 + * @define Coll SortedMap + * @define coll sorted map + * @define factoryInfo + * This object provides a set of operations needed to create sorted maps of type `$Coll`. + * @author Martin Odersky + * @version 2.8 + * @define sortedMapCanBuildFromInfo + * The standard `CanBuildFrom` instance for sorted maps */ abstract class ImmutableSortedMapFactory[CC[A, B] <: immutable.SortedMap[A, B] with SortedMapLike[A, B, CC[A, B]]] extends SortedMapFactory[CC] diff --git a/src/library/scala/collection/generic/ImmutableSortedSetFactory.scala b/src/library/scala/collection/generic/ImmutableSortedSetFactory.scala index df5c2c7959..684e7c41f1 100644 --- a/src/library/scala/collection/generic/ImmutableSortedSetFactory.scala +++ b/src/library/scala/collection/generic/ImmutableSortedSetFactory.scala @@ -12,8 +12,16 @@ package scala.collection package generic -/** A template for companion objects of mutable.Map and subclasses thereof. +/** A template for companion objects of `SortedSet` and subclasses thereof. * * @since 2.8 + * @define Coll immutable.SortedSet + * @define coll immutable sorted + * @define factoryInfo + * This object provides a set of operations needed to create sorted sets of type `$Coll`. + * @author Martin Odersky + * @version 2.8 + * @define sortedSetCanBuildFromInfo + * The standard `CanBuildFrom` instance for sorted sets */ abstract class ImmutableSortedSetFactory[CC[A] <: immutable.SortedSet[A] with SortedSetLike[A, CC[A]]] extends SortedSetFactory[CC]
\ No newline at end of file diff --git a/src/library/scala/collection/immutable/Queue.scala b/src/library/scala/collection/immutable/Queue.scala index 575d84c878..7a903cb201 100644 --- a/src/library/scala/collection/immutable/Queue.scala +++ b/src/library/scala/collection/immutable/Queue.scala @@ -23,6 +23,8 @@ import mutable.{ Builder, ListBuffer } * @since 1 * @define Coll immutable.Queue * @define coll immutable queue + * @define mayNotTerminateInf + * @define willNotTerminateInf */ @serializable @SerialVersionUID(-7622936493364270175L) diff --git a/src/library/scala/collection/immutable/Range.scala b/src/library/scala/collection/immutable/Range.scala index 5424a7afcb..8f1f7d58a6 100644 --- a/src/library/scala/collection/immutable/Range.scala +++ b/src/library/scala/collection/immutable/Range.scala @@ -10,20 +10,31 @@ package scala.collection.immutable -/** <p> - * The <code>Range</code> class represents integer values in range - * <code>[start;end)</code> with non-zero step value <code>step</code>. - * It's a special case of an indexed sequence. - * For example: - * </p><pre> - * <b>val</b> r1 = 0 until 10 - * <b>val</b> r2 = r1.start until r1.end by r1.step + 1 +/** The `Range` class represents integer values in range + * ''[start;end)'' with non-zero step value `step`. + * It's a special case of an indexed sequence. + * For example: + * + * {{{ + * val r1 = 0 until 10 + * val r2 = r1.start until r1.end by r1.step + 1 * println(r2.length) // = 5 - * </pre> + * }}} + * + * @param start the start of this range. + * @param end the exclusive end of the range. + * @param step the step for the range. * * @author Martin Odersky * @version 2.8 * @since 2.5 + * @define Coll Range + * @define coll range + * @define mayNotTerminateInf + * @define willNotTerminateInf + * @define doesNotUseBuilders + * '''Note:''' this method does not use builders to construct a new range, + * and its complexity is O(1). */ @serializable @SerialVersionUID(7618862778670199309L) class Range(val start: Int, val end: Int, val step: Int) extends IndexedSeq[Int] { @@ -33,7 +44,9 @@ 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 - * a new <code>step</code>. + * a new `step`. + * + * @return a new range with a different step */ def by(step: Int): Range = copy(start, end, step) @@ -84,18 +97,46 @@ class Range(val start: Int, val end: Int, val step: Int) extends IndexedSeq[Int] start } + /** Creates a new range containing the first `n` elements of this range. + * + * $doesNotUseBuilders + * + * @param n the number of elements to take. + * @return a new range consisting of `n` first elements. + */ final override def take(n: Int): Range = if (n > 0 && length > 0) { Range(start, locationAfterN(n - 1), step).inclusive } else { Range(start, start, step) } + /** Creates a new range containing all the elements of this range except the first `n` elements. + * + * $doesNotUseBuilders + * + * @param n the number of elements to drop. + * @return a new range consisting of all the elements of this range except `n` first elements. + */ final override def drop(n: Int): Range = copy(locationAfterN(n), end, step) + /** Creates a new range containing all the elements of this range except the last one. + * + * $doesNotUseBuilders + * + * @return a new range consisting of all the elements of this range except the last one. + */ final override def init: Range = take(length - 1) + /** Creates a new range contained in the specified slice of this range. + * + * $doesNotUseBuilders + * + * @param from the start of the slice. + * @param until the end of the slice. + * @return a new range consisting of all the elements of this range contained in the specified slice. + */ final override def slice(from: Int, until: Int): Range = drop(from).take(until - from) @@ -117,12 +158,29 @@ class Range(val start: Int, val end: Int, val step: Int) extends IndexedSeq[Int] (Range(start, split, step), copy(split, end, step)) } + /** Creates a pair of new ranges, first consisting of elements before `n`, and the second + * of elements after `n`. + * + * $doesNotUseBuilders + */ final override def splitAt(n: Int) = (take(n), drop(n)) + /** Creates a new range consisting of the `length - n` last elements of the range. + * + * $doesNotUseBuilders + */ final override def takeRight(n: Int): Range = drop(length - n) + /** Creates a new range consisting of the initial `length - n` elements of the range. + * + * $doesNotUseBuilders + */ final override def dropRight(n: Int): Range = take(length - n) + /** Returns the reverse of this range. + * + * $doesNotUseBuilders + */ final override def reverse: Range = if (length > 0) new Range.Inclusive(last, start, -step) else this /** Make range inclusive. @@ -156,6 +214,8 @@ class Range(val start: Int, val end: Int, val step: Int) extends IndexedSeq[Int] } } +/** A companion object for the `Range` class. + */ object Range { private[immutable] val MAX_PRINT = 512 // some arbitrary value diff --git a/src/library/scala/collection/immutable/RedBlack.scala b/src/library/scala/collection/immutable/RedBlack.scala index ffa6194838..98a7d67d48 100644 --- a/src/library/scala/collection/immutable/RedBlack.scala +++ b/src/library/scala/collection/immutable/RedBlack.scala @@ -12,9 +12,9 @@ package scala.collection package immutable -/** A base class containing the implementations for TreeMaps and TreeSets +/** A base class containing the implementations for `TreeMaps` and `TreeSets`. * - * @since 2.3 + * @since 2.3 */ @serializable @SerialVersionUID(8691885935445612921L) abstract class RedBlack[A] { diff --git a/src/library/scala/collection/immutable/Seq.scala b/src/library/scala/collection/immutable/Seq.scala index de7804a95c..7e41ff7b94 100644 --- a/src/library/scala/collection/immutable/Seq.scala +++ b/src/library/scala/collection/immutable/Seq.scala @@ -19,6 +19,8 @@ import mutable.Builder * that are guaranteed immutable. * * $seqInfo + * @define Coll immutable.Seq + * @define coll immutable sequence */ trait Seq[+A] extends Iterable[A] with scala.collection.Seq[A] @@ -27,10 +29,12 @@ trait Seq[+A] extends Iterable[A] override def companion: GenericCompanion[Seq] = Seq } -/** - * @since 2.8 +/** $factoryInfo + * @define Coll immutable.Seq + * @define coll immutable sequence */ 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 mutable.ListBuffer } diff --git a/src/library/scala/collection/immutable/Set.scala b/src/library/scala/collection/immutable/Set.scala index 77f16c0d14..769ee37f6b 100644 --- a/src/library/scala/collection/immutable/Set.scala +++ b/src/library/scala/collection/immutable/Set.scala @@ -14,23 +14,16 @@ package immutable import generic._ -/** <p> - * A generic trait for immutable sets. Concrete set implementations have - * to provide functionality for the abstract methods in <code>Set</code>: - * </p> - * <pre> - * <b>def</b> contains(elem: A): Boolean - * <b>def</b> iterator: Iterator[A] - * <b>def</b> + (elem: A): Self - * <b>def</b> - (elem: A): Self</pre> - * <p> - * where <code>Self</code> is the type of the set. - * </p> +/** A generic trait for immutable sets. + * + * $setnote * * @author Matthias Zenger * @author Martin Odersky * @version 2.8 * @since 1 + * @define Coll immutable.Set + * @define coll immutable set */ trait Set[A] extends Iterable[A] with scala.collection.Set[A] @@ -39,10 +32,12 @@ trait Set[A] extends Iterable[A] override def companion: GenericCompanion[Set] = Set } -/** - * A companion object for immutable sets. +/** $factoryInfo + * @define Coll immutable.Set + * @define coll immutable set */ object Set extends SetFactory[Set] { + /** $setCanBuildFromInfo */ 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/SetProxy.scala b/src/library/scala/collection/immutable/SetProxy.scala index 73c95652b3..d45b2059ff 100644 --- a/src/library/scala/collection/immutable/SetProxy.scala +++ b/src/library/scala/collection/immutable/SetProxy.scala @@ -12,14 +12,13 @@ package scala.collection package immutable -/** <p> - * This is a simple wrapper class for <a href="Set.html" - * target="contentFrame"><code>scala.collection.immutable.Set</code></a>. - * </p> - * <p> - * It is most useful for assembling customized set abstractions - * dynamically using object composition and forwarding. - * </p> +/** This is a simple wrapper class for <a href="Set.html" + * target="contentFrame">`scala.collection.immutable.Set`</a>. + * + * It is most useful for assembling customized set abstractions + * dynamically using object composition and forwarding. + * + * @tparam A type of the elements contained in this set proxy. * * @since 2.8 */ diff --git a/src/library/scala/collection/immutable/SortedMap.scala b/src/library/scala/collection/immutable/SortedMap.scala index 919b529a49..243636e107 100644 --- a/src/library/scala/collection/immutable/SortedMap.scala +++ b/src/library/scala/collection/immutable/SortedMap.scala @@ -18,10 +18,15 @@ import annotation.unchecked.uncheckedVariance /** A map whose keys are sorted. * + * @tparam A the type of the keys contained in this sorted map. + * @tparam B the type of the values associated with the keys. + * * @author Sean McDirmid * @author Martin Odersky * @version 2.8 * @since 2.4 + * @define Coll immutable.SortedMap + * @define coll immutable sorted map */ trait SortedMap[A, +B] extends Map[A, B] with scala.collection.SortedMap[A, B] @@ -62,10 +67,12 @@ trait SortedMap[A, +B] extends Map[A, B] ((repr: SortedMap[A, B1]) /: xs) (_ + _) } -/** - * @since 2.4 +/** $factoryInfo + * @define Coll immutable.SortedMap + * @define coll immutable sorted map */ object SortedMap extends ImmutableSortedMapFactory[SortedMap] { + /** $sortedMapCanBuildFromInfo */ implicit def canBuildFrom[A, B](implicit ord: Ordering[A]): CanBuildFrom[Coll, (A, B), SortedMap[A, B]] = new SortedMapCanBuildFrom[A, B] def empty[A, B](implicit ord: Ordering[A]): SortedMap[A, B] = TreeMap.empty[A, B] } diff --git a/src/library/scala/collection/immutable/SortedSet.scala b/src/library/scala/collection/immutable/SortedSet.scala index 10ff466ff8..6c9433c30c 100644 --- a/src/library/scala/collection/immutable/SortedSet.scala +++ b/src/library/scala/collection/immutable/SortedSet.scala @@ -22,18 +22,20 @@ import mutable.Builder * @author Martin Odersky * @version 2.8 * @since 2.4 + * @define Coll immutable.SortedSet + * @define coll immutable sorted set */ trait SortedSet[A] extends Set[A] with scala.collection.SortedSet[A] with SortedSetLike[A, SortedSet[A]] { /** Needs to be overridden in subclasses. */ override def empty: SortedSet[A] = SortedSet.empty[A] } -/** - * A companion object for immutable sorted sets. - * - * @since 2.4 +/** $factoryInfo + * @define Coll immutable.SortedSet + * @define coll immutable sorted set */ object SortedSet extends ImmutableSortedSetFactory[SortedSet] { + /** $sortedSetCanBuildFromInfo */ implicit def canBuildFrom[A](implicit ord: Ordering[A]): CanBuildFrom[Coll, A, SortedSet[A]] = new SortedSetCanBuildFrom[A] def empty[A](implicit ord: Ordering[A]): SortedSet[A] = TreeSet.empty[A] } diff --git a/src/library/scala/collection/immutable/Stack.scala b/src/library/scala/collection/immutable/Stack.scala index 7d3c8c040b..aa7ee908d6 100644 --- a/src/library/scala/collection/immutable/Stack.scala +++ b/src/library/scala/collection/immutable/Stack.scala @@ -15,7 +15,12 @@ package immutable import generic._ import mutable.{ ArrayBuffer, Builder } +/** $factoryInfo + * @define Coll immutable.Stack + * @define coll immutable stack + */ object Stack extends SeqFactory[Stack] { + /** $genericCanBuildFromInfo */ implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, Stack[A]] = new GenericCanBuildFrom[A] def newBuilder[A]: Builder[A, Stack[A]] = new ArrayBuffer[A] mapResult (buf => new Stack(buf.toList)) @@ -26,13 +31,17 @@ object Stack extends SeqFactory[Stack] { /** This class implements immutable stacks using a list-based data * structure. * - * @note This class exists only for historical reason and as an - * analogue of mutable stacks + * '''Note:''' This class exists only for historical reason and as an + * analogue of mutable stacks. * Instead of an immutable stack you can just use a list. * + * @tparam A the type of the elements contained in this stack. + * * @author Matthias Zenger * @version 1.0, 10/07/2003 * @since 1 + * @define Coll immutable.Stack + * @define coll immutable stack */ @serializable @SerialVersionUID(1976480595012942526L) class Stack[+A] protected (protected val elems: List[A]) extends LinearSeq[A] |