From 4af770340b64e1124c1ed4623c7d5a734cf602a1 Mon Sep 17 00:00:00 2001 From: Jason Zaugg Date: Sun, 13 May 2012 12:24:24 +0200 Subject: Address doc comment rot in the standard library. - Match @param/@tparam names to the actual parameter name - Use @tparam for type parameters - Whitespace is required between `*` and `@` - Fix incorrect references to @define macros. - Use of monospace `` and {{{}}} (much more needed) - Remove `@param p1 ...` stubs, which appear in the generated docss. - But, retainsed `@param p1` stubs, assuming they will be filtered from the generated docs by SI-5795. - Avoid use of the shorthand `@param doc for the solitary param` (which works, but isn't recognized by the code inspection in IntelliJ I used to sweep through the problems) The remaining warnings from `ant docs` seem spurious, I suspect they are an unintended consequence of documenting extension methods. [scaladoc] /Users/jason/code/scala/src/library/scala/collection/TraversableOnce.scala:181: warning: Variable coll undefined in comment for method reduceOption in class Tuple2Zipped [scaladoc] def reduceOption[A1 >: A](op: (A1, A1) => A1): Option[A1] = reduceLeftOption(op) [scaladoc] ^ --- .../scala/collection/parallel/ParIterableLike.scala | 14 +++++++------- src/library/scala/collection/parallel/ParSeqLike.scala | 6 ++---- .../scala/collection/parallel/RemainsIterator.scala | 7 +++---- .../scala/collection/parallel/mutable/ParHashMap.scala | 3 ++- 4 files changed, 14 insertions(+), 16 deletions(-) (limited to 'src/library/scala/collection/parallel') diff --git a/src/library/scala/collection/parallel/ParIterableLike.scala b/src/library/scala/collection/parallel/ParIterableLike.scala index 4cb229fc0f..321f259f5d 100644 --- a/src/library/scala/collection/parallel/ParIterableLike.scala +++ b/src/library/scala/collection/parallel/ParIterableLike.scala @@ -491,8 +491,8 @@ self: ParIterableLike[T, Repr, Sequential] => * * $abortsignalling * - * @param p a predicate used to test elements - * @return true if `p` holds for all elements, false otherwise + * @param pred a predicate used to test elements + * @return true if `p` holds for all elements, false otherwise */ def forall(pred: T => Boolean): Boolean = { tasksupport.executeAndWaitResult(new Forall(pred, splitter assign new DefaultSignalling with VolatileAbort)) @@ -502,8 +502,8 @@ self: ParIterableLike[T, Repr, Sequential] => * * $abortsignalling * - * @param p a predicate used to test elements - * @return true if `p` holds for some element, false otherwise + * @param pred a predicate used to test elements + * @return true if `p` holds for some element, false otherwise */ def exists(pred: T => Boolean): Boolean = { tasksupport.executeAndWaitResult(new Exists(pred, splitter assign new DefaultSignalling with VolatileAbort)) @@ -517,8 +517,8 @@ self: ParIterableLike[T, Repr, Sequential] => * * $abortsignalling * - * @param p predicate used to test the elements - * @return an option value with the element if such an element exists, or `None` otherwise + * @param pred predicate used to test the elements + * @return an option value with the element if such an element exists, or `None` otherwise */ def find(pred: T => Boolean): Option[T] = { tasksupport.executeAndWaitResult(new Find(pred, splitter assign new DefaultSignalling with VolatileAbort)) @@ -685,7 +685,7 @@ self: ParIterableLike[T, Repr, Sequential] => * @tparam That type of the resulting collection * @param z neutral element for the operator `op` * @param op the associative operator for the scan - * @param cbf combiner factory which provides a combiner + * @param bf $bfinfo * @return a collection containing the prefix scan of the elements in the original collection * * @usecase def scan(z: T)(op: (T, T) => T): $Coll[T] diff --git a/src/library/scala/collection/parallel/ParSeqLike.scala b/src/library/scala/collection/parallel/ParSeqLike.scala index b3c527da84..be5ab03ba7 100644 --- a/src/library/scala/collection/parallel/ParSeqLike.scala +++ b/src/library/scala/collection/parallel/ParSeqLike.scala @@ -162,7 +162,7 @@ self => * * $abortsignalling * - * @tparam U the element type of `that` parallel sequence + * @tparam S the element type of `that` parallel sequence * @param that the parallel sequence this sequence is being searched for * @param offset the starting offset for the search * @return `true` if there is a sequence `that` starting at `offset` in this sequence, `false` otherwise @@ -287,9 +287,7 @@ self => /** Computes the multiset intersection between this $coll and another sequence. * * @param that the sequence of elements to intersect with. - * @tparam B the element type of the returned $coll. - * @tparam That $thatinfo - * @param bf $bfinfo + * @tparam U the element type of `that` parallel sequence * @return a new collection of type `That` which contains all elements of this $coll * which also appear in `that`. * If an element value `x` appears diff --git a/src/library/scala/collection/parallel/RemainsIterator.scala b/src/library/scala/collection/parallel/RemainsIterator.scala index c5910ff2c8..a67a4d8eb7 100644 --- a/src/library/scala/collection/parallel/RemainsIterator.scala +++ b/src/library/scala/collection/parallel/RemainsIterator.scala @@ -39,8 +39,7 @@ private[collection] trait RemainsIterator[+T] extends Iterator[T] { /** Augments iterators with additional methods, mostly transformers, * assuming they iterate an iterable collection. * - * @param T type of the elements iterated. - * @param IterRepr iterator type. + * @tparam T type of the elements iterated. */ private[collection] trait AugmentedIterableIterator[+T] extends RemainsIterator[T] { @@ -377,7 +376,7 @@ private[collection] trait AugmentedSeqIterator[+T] extends AugmentedIterableIter /** Parallel iterators allow splitting and provide a `remaining` method to * obtain the number of elements remaining in the iterator. * - * @param T type of the elements iterated. + * @tparam T type of the elements iterated. */ trait IterableSplitter[+T] extends AugmentedIterableIterator[T] @@ -537,7 +536,7 @@ self => /** Parallel sequence iterators allow splitting into arbitrary subsets. * - * @param T type of the elements iterated. + * @tparam T type of the elements iterated. */ trait SeqSplitter[+T] extends IterableSplitter[T] diff --git a/src/library/scala/collection/parallel/mutable/ParHashMap.scala b/src/library/scala/collection/parallel/mutable/ParHashMap.scala index 05b3f89fa1..8d39d6e0de 100644 --- a/src/library/scala/collection/parallel/mutable/ParHashMap.scala +++ b/src/library/scala/collection/parallel/mutable/ParHashMap.scala @@ -26,7 +26,8 @@ import collection.parallel.Task * `ParHashMap` is a parallel map which internally keeps elements within a hash table. * It uses chaining to resolve collisions. * - * @tparam T type of the elements in the parallel hash map + * @tparam K type of the keys in the parallel hash map + * @tparam V type of the values in the parallel hash map * * @define Coll `ParHashMap` * @define coll parallel hash map -- cgit v1.2.3