From e3cbcd5298108b2a0ba66bf70fd9b78664cbf483 Mon Sep 17 00:00:00 2001 From: vsalvis Date: Sat, 6 Jun 2015 10:56:06 +0200 Subject: Improve collections documentation and prefer () to {} - Remove some duplicate method documentation that is now inherited - Whitespace edits - Rewording of method docs - Clearer usage examples - tparam alignment for some usecase tags - Prefer () to { } for do nothing bodies --- .../scala/collection/GenTraversableLike.scala | 12 --- .../scala/collection/GenTraversableOnce.scala | 86 +++++++++++++++------- src/library/scala/collection/TraversableLike.scala | 36 +-------- src/library/scala/collection/package.scala | 38 ++++++---- .../collection/parallel/ParIterableLike.scala | 1 - 5 files changed, 85 insertions(+), 88 deletions(-) (limited to 'src/library') diff --git a/src/library/scala/collection/GenTraversableLike.scala b/src/library/scala/collection/GenTraversableLike.scala index 479a8b5b1b..d730996be2 100644 --- a/src/library/scala/collection/GenTraversableLike.scala +++ b/src/library/scala/collection/GenTraversableLike.scala @@ -158,18 +158,6 @@ trait GenTraversableLike[+A, +Repr] extends Any with GenTraversableOnce[A] with @migration("The behavior of `scanRight` has changed. The previous behavior can be reproduced with scanRight.reverse.", "2.9.0") def scanRight[B, That](z: B)(op: (A, B) => B)(implicit bf: CanBuildFrom[Repr, B, That]): That - /** Applies a function `f` to all elements of this $coll. - * - * @param f the function that is applied for its side-effect to every element. - * The result of function `f` is discarded. - * - * @tparam U the type parameter describing the result of function `f`. - * This result will always be ignored. Typically `U` is `Unit`, - * but this is not necessary. - * - * @usecase def foreach(f: A => Unit): Unit - * @inheritdoc - */ def foreach[U](f: A => U): Unit /** Builds a new collection by applying a function to all elements of this $coll. diff --git a/src/library/scala/collection/GenTraversableOnce.scala b/src/library/scala/collection/GenTraversableOnce.scala index a45ec965f5..244ff26397 100644 --- a/src/library/scala/collection/GenTraversableOnce.scala +++ b/src/library/scala/collection/GenTraversableOnce.scala @@ -49,6 +49,22 @@ import scala.language.higherKinds */ trait GenTraversableOnce[+A] extends Any { + /** Applies a function `f` to all elements of this $coll. + * + * @param f the function that is applied for its side-effect to every element. + * The result of function `f` is discarded. + * + * @tparam U the type parameter describing the result of function `f`. + * This result will always be ignored. Typically `U` is `Unit`, + * but this is not necessary. + * + * @usecase def foreach(f: A => Unit): Unit + * @inheritdoc + * + * Note: this method underlies the implementation of most other bulk operations. + * It's important to implement this method in an efficient way. + * + */ def foreach[U](f: A => U): Unit def hasDefiniteSize: Boolean @@ -110,13 +126,14 @@ trait GenTraversableOnce[+A] extends Any { * binary operator. * * $undefinedorder + * $willNotTerminateInf * * @tparam A1 a type parameter for the binary operator, a supertype of `A`. * @param z a neutral element for the fold operation; may be added to the result * an arbitrary number of times, and must not change the result (e.g., `Nil` for list concatenation, - * 0 for addition, or 1 for multiplication.) - * @param op a binary operator that must be associative - * @return the result of applying fold operator `op` between all the elements and `z` + * 0 for addition, or 1 for multiplication). + * @param op a binary operator that must be associative. + * @return the result of applying the fold operator `op` between all the elements and `z`, or `z` if this $coll is empty. */ def fold[A1 >: A](z: A1)(op: (A1, A1) => A1): A1 @@ -205,6 +222,7 @@ trait GenTraversableOnce[+A] extends Any { * op(...op(z, x_1), x_2, ..., x_n) * }}} * where `x,,1,,, ..., x,,n,,` are the elements of this $coll. + * Returns `z` if this $coll is empty. */ def foldLeft[B](z: B)(op: (B, A) => B): B @@ -222,30 +240,32 @@ trait GenTraversableOnce[+A] extends Any { * op(x_1, op(x_2, ... op(x_n, z)...)) * }}} * where `x,,1,,, ..., x,,n,,` are the elements of this $coll. + * Returns `z` if this $coll is empty. */ def foldRight[B](z: B)(op: (A, B) => B): B /** Aggregates the results of applying an operator to subsequent elements. * - * This is a more general form of `fold` and `reduce`. It has similar - * semantics, but does not require the result to be a supertype of the - * element type. It traverses the elements in different partitions - * sequentially, using `seqop` to update the result, and then applies - * `combop` to results from different partitions. The implementation of - * this operation may operate on an arbitrary number of collection - * partitions, so `combop` may be invoked an arbitrary number of times. - * - * For example, one might want to process some elements and then produce - * a `Set`. In this case, `seqop` would process an element and append it - * to the list, while `combop` would concatenate two lists from different - * partitions together. The initial value `z` would be an empty set. + * This is a more general form of `fold` and `reduce`. It is similar to + * `foldLeft` in that it doesn't require the result to be a supertype of the + * element type. In addition, it allows parallel collections to be processed + * in chunks, and then combines the intermediate results. + * + * `aggregate` splits the $coll into partitions and processes each + * partition by sequentially applying `seqop`, starting with `z` (like + * `foldLeft`). Those intermediate results are then combined by using + * `combop` (like `fold`). The implementation of this operation may operate + * on an arbitrary number of collection partitions (even 1), so `combop` may + * be invoked an arbitrary number of times (even 0). + * + * As an example, consider summing up the integer values of a list of chars. + * The initial value for the sum is 0. First, `seqop` transforms each input + * character to an Int and adds it to the sum (of the partition). Then, + * `combop` just needs to sum up the intermediate results of the partitions: * {{{ - * pc.aggregate(Set[Int]())(_ += process(_), _ ++ _) + * List('a', 'b', 'c').aggregate(0)({ (sum, ch) => sum + ch.toInt }, { (p1, p2) => p1 + p2 }) * }}} * - * Another example is calculating geometric mean from a collection of doubles - * (one would typically require big doubles for this). - * * @tparam B the type of accumulated results * @param z the initial value for the accumulated result of the partition - this * will typically be the neutral element for the `seqop` operator (e.g. @@ -423,13 +443,13 @@ trait GenTraversableOnce[+A] extends Any { */ def find(@deprecatedName('pred) p: A => Boolean): Option[A] - /** Copies values of this $coll to an array. + /** Copies the elements of this $coll to an array. * Fills the given array `xs` with values of this $coll. * Copying will stop once either the end of the current $coll is reached, - * or the end of the array is reached. + * or the end of the target array is reached. * * @param xs the array to fill. - * @tparam B the type of the elements of the array. + * @tparam B the type of the elements of the target array. * * @usecase def copyToArray(xs: Array[A]): Unit * @inheritdoc @@ -438,14 +458,14 @@ trait GenTraversableOnce[+A] extends Any { */ def copyToArray[B >: A](xs: Array[B]): Unit - /** Copies values of this $coll to an array. + /** Copies the elements of this $coll to an array. * Fills the given array `xs` with values of this $coll, beginning at index `start`. * Copying will stop once either the end of the current $coll is reached, - * or the end of the array is reached. + * or the end of the target array is reached. * * @param xs the array to fill. * @param start the starting index. - * @tparam B the type of the elements of the array. + * @tparam B the type of the elements of the target array. * * @usecase def copyToArray(xs: Array[A], start: Int): Unit * @inheritdoc @@ -454,6 +474,22 @@ trait GenTraversableOnce[+A] extends Any { */ def copyToArray[B >: A](xs: Array[B], start: Int): Unit + /** Copies the elements of this $coll to an array. + * Fills the given array `xs` with at most `len` elements of + * this $coll, starting at position `start`. + * Copying will stop once either the end of the current $coll is reached, + * or the end of the target array is reached, or `len` elements have been copied. + * + * @param xs the array to fill. + * @param start the starting index. + * @param len the maximal number of elements to copy. + * @tparam B the type of the elements of the target array. + * + * @usecase def copyToArray(xs: Array[A], start: Int, len: Int): Unit + * @inheritdoc + * + * $willNotTerminateInf + */ def copyToArray[B >: A](xs: Array[B], start: Int, len: Int): Unit /** Displays all elements of this $coll in a string using start, end, and diff --git a/src/library/scala/collection/TraversableLike.scala b/src/library/scala/collection/TraversableLike.scala index 04ae8c8aff..bd1be84e97 100644 --- a/src/library/scala/collection/TraversableLike.scala +++ b/src/library/scala/collection/TraversableLike.scala @@ -340,14 +340,6 @@ trait TraversableLike[+A, +Repr] extends Any b.result } - /** Tests whether a predicate holds for all elements of this $coll. - * - * $mayNotTerminateInf - * - * @param p the predicate used to test elements. - * @return `true` if this $coll is empty, otherwise `true` if the given predicate `p` - * holds for all elements of this $coll, otherwise `false`. - */ def forall(p: A => Boolean): Boolean = { var result = true breakable { @@ -374,15 +366,6 @@ trait TraversableLike[+A, +Repr] extends Any result } - /** Finds the first element of the $coll satisfying a predicate, if any. - * - * $mayNotTerminateInf - * $orderDependent - * - * @param p the predicate used to test elements. - * @return an option value containing the first element in the $coll - * that satisfies `p`, or `None` if none exists. - */ def find(p: A => Boolean): Option[A] = { var result: Option[A] = None breakable { @@ -594,23 +577,6 @@ trait TraversableLike[+A, +Repr] extends Any */ def inits: Iterator[Repr] = iterateUntilEmpty(_.init) - /** Copies elements of this $coll to an array. - * Fills the given array `xs` with at most `len` elements of - * this $coll, starting at position `start`. - * Copying will stop once either the end of the current $coll is reached, - * or the end of the array is reached, or `len` elements have been copied. - * - * @param xs the array to fill. - * @param start the starting index. - * @param len the maximal number of elements to copy. - * @tparam B the type of the elements of the array. - * - * - * @usecase def copyToArray(xs: Array[A], start: Int, len: Int): Unit - * @inheritdoc - * - * $willNotTerminateInf - */ def copyToArray[B >: A](xs: Array[B], start: Int, len: Int) { var i = start val end = (start + len) min xs.length @@ -625,7 +591,7 @@ trait TraversableLike[+A, +Repr] extends Any @deprecatedOverriding("Enforce contract of toTraversable that if it is Traversable it returns itself.", "2.11.0") def toTraversable: Traversable[A] = thisCollection - + def toIterator: Iterator[A] = toStream.iterator def toStream: Stream[A] = toBuffer.toStream // Override to provide size hint. diff --git a/src/library/scala/collection/package.scala b/src/library/scala/collection/package.scala index 13fe7a79c4..856f901b77 100644 --- a/src/library/scala/collection/package.scala +++ b/src/library/scala/collection/package.scala @@ -13,8 +13,11 @@ package scala * * == Guide == * - * A detailed guide for the collections library is available + * A detailed guide for using the collections library is available * at [[http://docs.scala-lang.org/overviews/collections/introduction.html]]. + * Developers looking to extend the collections library can find a description + * of its architecture at + * [[http://docs.scala-lang.org/overviews/core/architecture-of-scala-collections.html]]. * * == Using Collections == * @@ -31,24 +34,25 @@ package scala * array: Array[Int] = Array(1, 2, 3, 4, 5, 6) * * scala> array map { _.toString } - * res0: Array[java.lang.String] = Array(1, 2, 3, 4, 5, 6) + * res0: Array[String] = Array(1, 2, 3, 4, 5, 6) * * scala> val list = List(1,2,3,4,5,6) * list: List[Int] = List(1, 2, 3, 4, 5, 6) * * scala> list map { _.toString } - * res1: List[java.lang.String] = List(1, 2, 3, 4, 5, 6) + * res1: List[String] = List(1, 2, 3, 4, 5, 6) * * }}} * * == Creating Collections == * - * The most common way to create a collection is to use the companion objects as factories. - * Of these, the three most common - * are [[scala.collection.Seq]], [[scala.collection.immutable.Set]], and [[scala.collection.immutable.Map]]. Their - * companion objects are all available - * as type aliases the either the [[scala]] package or in `scala.Predef`, and can be used - * like so: + * The most common way to create a collection is to use its companion object as + * a factory. The three most commonly used collections are + * [[scala.collection.Seq]], [[scala.collection.immutable.Set]], and + * [[scala.collection.immutable.Map]]. + * They can be used directly as shown below since their companion objects are + * all available as type aliases in either the [[scala]] package or in + * `scala.Predef`. New collections are created like this: * {{{ * scala> val seq = Seq(1,2,3,4,1) * seq: Seq[Int] = List(1, 2, 3, 4, 1) @@ -56,12 +60,12 @@ package scala * scala> val set = Set(1,2,3,4,1) * set: scala.collection.immutable.Set[Int] = Set(1, 2, 3, 4) * - * scala> val map = Map(1 -> "one",2 -> "two", 3 -> "three",2 -> "too") - * map: scala.collection.immutable.Map[Int,java.lang.String] = Map((1,one), (2,too), (3,three)) + * scala> val map = Map(1 -> "one", 2 -> "two", 3 -> "three", 2 -> "too") + * map: scala.collection.immutable.Map[Int,String] = Map(1 -> one, 2 -> too, 3 -> three) * }}} * - * It is also typical to use the [[scala.collection.immutable]] collections over those - * in [[scala.collection.mutable]]; The types aliased in + * It is also typical to prefer the [[scala.collection.immutable]] collections + * over those in [[scala.collection.mutable]]; the types aliased in * the `scala.Predef` object are the immutable versions. * * Also note that the collections library was carefully designed to include several implementations of @@ -74,9 +78,13 @@ package scala * * === Converting between Java Collections === * - * The `JavaConversions` object provides implicit defs that will allow mostly seamless integration - * between Java Collections-based APIs and the Scala collections library. + * The [[scala.collection.JavaConversions]] object provides implicit defs that + * will allow mostly seamless integration between APIs using Java Collections + * and the Scala collections library. * + * Alternatively the [[scala.collection.JavaConverters]] object provides a collection + * of decorators that allow converting between Scala and Java collections using `asScala` + * and `asJava` methods. */ package object collection { import scala.collection.generic.CanBuildFrom diff --git a/src/library/scala/collection/parallel/ParIterableLike.scala b/src/library/scala/collection/parallel/ParIterableLike.scala index e7b022b895..8c9b959569 100644 --- a/src/library/scala/collection/parallel/ParIterableLike.scala +++ b/src/library/scala/collection/parallel/ParIterableLike.scala @@ -1499,5 +1499,4 @@ self: ParIterableLike[T, Repr, Sequential] => append(s) } }) - } -- cgit v1.2.3