Permalink
Browse files

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]       ^
  • Loading branch information...
retronym committed May 13, 2012
1 parent 4cd0253 commit 4af770340b64e1124c1ed4623c7d5a734cf602a1
Showing with 204 additions and 370 deletions.
  1. +2 −2 src/library/scala/Array.scala
  2. +0 −1 src/library/scala/Console.scala
  3. +4 −4 src/library/scala/Either.scala
  4. +0 −4 src/library/scala/Function.scala
  5. +1 −1 src/library/scala/Option.scala
  6. +9 −9 src/library/scala/Predef.scala
  7. +1 −1 src/library/scala/Product.scala
  8. +0 −6 src/library/scala/Responder.scala
  9. +1 −1 src/library/scala/StringContext.scala
  10. +6 −2 src/library/scala/annotation/elidable.scala
  11. +4 −4 src/library/scala/collection/BitSetLike.scala
  12. +8 −8 src/library/scala/collection/GenIterableLike.scala
  13. +0 −1 src/library/scala/collection/GenMapLike.scala
  14. +0 −4 src/library/scala/collection/GenSeqLike.scala
  15. +12 −12 src/library/scala/collection/GenTraversableLike.scala
  16. +12 −12 src/library/scala/collection/GenTraversableOnce.scala
  17. +11 −1 src/library/scala/collection/IterableLike.scala
  18. +2 −2 src/library/scala/collection/MapLike.scala
  19. +0 −4 src/library/scala/collection/SeqLike.scala
  20. +0 −2 src/library/scala/collection/TraversableOnce.scala
  21. +6 −6 src/library/scala/collection/convert/DecorateAsScala.scala
  22. +10 −10 src/library/scala/collection/convert/WrapAsJava.scala
  23. +6 −6 src/library/scala/collection/convert/WrapAsScala.scala
  24. +2 −2 src/library/scala/collection/generic/GenTraversableFactory.scala
  25. +5 −5 src/library/scala/collection/generic/GenericTraversableTemplate.scala
  26. +1 −1 src/library/scala/collection/generic/Growable.scala
  27. +1 −1 src/library/scala/collection/generic/Shrinkable.scala
  28. +0 −2 src/library/scala/collection/generic/Sorted.scala
  29. +1 −1 src/library/scala/collection/generic/Subtractable.scala
  30. +3 −3 src/library/scala/collection/immutable/List.scala
  31. +2 −8 src/library/scala/collection/immutable/ListMap.scala
  32. +1 −1 src/library/scala/collection/immutable/ListSet.scala
  33. +3 −3 src/library/scala/collection/immutable/MapLike.scala
  34. +1 −1 src/library/scala/collection/immutable/Stack.scala
  35. +2 −2 src/library/scala/collection/immutable/Stream.scala
  36. +1 −1 src/library/scala/collection/immutable/StringLike.scala
  37. +1 −1 src/library/scala/collection/mutable/ArrayOps.scala
  38. +1 −1 src/library/scala/collection/mutable/ArrayStack.scala
  39. +1 −1 src/library/scala/collection/mutable/BufferProxy.scala
  40. +1 −1 src/library/scala/collection/mutable/IndexedSeqLike.scala
  41. +3 −3 src/library/scala/collection/mutable/ListBuffer.scala
  42. +1 −1 src/library/scala/collection/mutable/QueueProxy.scala
  43. +2 −2 src/library/scala/collection/mutable/SeqLike.scala
  44. +2 −2 src/library/scala/collection/mutable/SynchronizedBuffer.scala
  45. +7 −7 src/library/scala/collection/parallel/ParIterableLike.scala
  46. +2 −4 src/library/scala/collection/parallel/ParSeqLike.scala
  47. +3 −4 src/library/scala/collection/parallel/RemainsIterator.scala
  48. +2 −1 src/library/scala/collection/parallel/mutable/ParHashMap.scala
  49. +0 −1 src/library/scala/concurrent/Channel.scala
  50. +2 −2 src/library/scala/concurrent/Future.scala
  51. +4 −4 src/library/scala/concurrent/Promise.scala
  52. +1 −1 src/library/scala/concurrent/Scheduler.scala
  53. +0 −2 src/library/scala/io/Source.scala
  54. +1 −9 src/library/scala/math/BigInt.scala
  55. +2 −1 src/library/scala/parallel/Future.scala
  56. +1 −1 src/library/scala/reflect/api/Trees.scala
  57. +2 −4 src/library/scala/reflect/api/Types.scala
  58. +7 −1 src/library/scala/reflect/api/Universe.scala
  59. +0 −2 src/library/scala/runtime/RichDouble.scala
  60. +0 −2 src/library/scala/runtime/RichFloat.scala
  61. +1 −1 src/library/scala/sys/Prop.scala
  62. +2 −2 src/library/scala/sys/package.scala
  63. +0 −3 src/library/scala/testing/Benchmark.scala
  64. +0 −3 src/library/scala/text/Document.scala
  65. +1 −2 src/library/scala/util/Random.scala
  66. +0 −9 src/library/scala/util/automata/BaseBerrySethi.scala
  67. +0 −3 src/library/scala/util/automata/Inclusion.scala
  68. +0 −1 src/library/scala/util/automata/WordBerrySethi.scala
  69. +3 −3 src/library/scala/util/parsing/ast/Binders.scala
  70. +1 −3 src/library/scala/util/parsing/input/CharArrayReader.scala
  71. +3 −4 src/library/scala/util/parsing/input/OffsetPosition.scala
  72. +1 −1 src/library/scala/util/parsing/input/PagedSeqReader.scala
  73. +1 −4 src/library/scala/util/parsing/input/Position.scala
  74. +5 −3 src/library/scala/util/parsing/input/StreamReader.scala
  75. +0 −3 src/library/scala/xml/Atom.scala
  76. +1 −1 src/library/scala/xml/Comment.scala
  77. +1 −1 src/library/scala/xml/EntityRef.scala
  78. +2 −24 src/library/scala/xml/MetaData.scala
  79. +1 −5 src/library/scala/xml/Node.scala
  80. +0 −6 src/library/scala/xml/NodeSeq.scala
  81. +3 −3 src/library/scala/xml/PrefixedAttribute.scala
  82. +3 −17 src/library/scala/xml/PrettyPrinter.scala
  83. +2 −2 src/library/scala/xml/ProcInstr.scala
  84. +0 −3 src/library/scala/xml/TextBuffer.scala
  85. +0 −50 src/library/scala/xml/Utility.scala
  86. +1 −1 src/library/scala/xml/dtd/DocType.scala
  87. +3 −3 src/library/scala/xml/dtd/ExternalID.scala
  88. +1 −1 src/library/scala/xml/include/sax/XIncludeFilter.scala
  89. +0 −5 src/library/scala/xml/parsing/ExternalSources.scala
  90. +1 −1 src/library/scala/xml/parsing/FactoryAdapter.scala
  91. +0 −2 src/library/scala/xml/parsing/MarkupHandler.scala
  92. +2 −2 src/library/scala/xml/parsing/MarkupParserCommon.scala
  93. +1 −1 src/library/scala/xml/pull/XMLEvent.scala
  94. +0 −5 src/library/scala/xml/transform/BasicTransformer.scala
@@ -362,8 +362,8 @@ object Array extends FallbackArrayBuilding {
/** Returns an array containing a sequence of increasing integers in a range.
*
- * @param from the start value of the array
- * @param end the end value of the array, exclusive (in other words, this is the first value '''not''' returned)
+ * @param start the start value of the array
+ * @param end the end value of the array, exclusive (in other words, this is the first value '''not''' returned)
* @return the array with values in range `start, start + 1, ..., end - 1`
* up to, but excluding, `end`.
*/
@@ -186,7 +186,6 @@ object Console {
* }
* }}}
*
- * @param in the new input stream.
* @param thunk the code to execute with
* the new input stream active
*
@@ -297,7 +297,7 @@ object Either {
* Left(12).left.foreach(x => println(x)) // prints "12"
* Right(12).left.foreach(x => println(x)) // doesn't print
* }}}
- * @param e The side-effecting function to execute.
+ * @param f The side-effecting function to execute.
*/
def foreach[U](f: A => U) = e match {
case Left(a) => f(a)
@@ -358,7 +358,7 @@ object Either {
* Left(12).left.flatMap(x => Left("scala")) // Left("scala")
* Right(12).left.flatMap(x => Left("scala") // Right(12)
* }}}
- * @param The function to bind across `Left`.
+ * @param f The function to bind across `Left`.
*/
def flatMap[BB >: B, X](f: A => Either[X, BB]) = e match {
case Left(a) => f(a)
@@ -462,7 +462,7 @@ object Either {
* Right(12).right.foreach(x => println(x)) // prints "12"
* Left(12).right.foreach(x => println(x)) // doesn't print
* }}}
- * @param e The side-effecting function to execute.
+ * @param f The side-effecting function to execute.
*/
def foreach[U](f: B => U) = e match {
case Left(_) => {}
@@ -516,7 +516,7 @@ object Either {
/**
* Binds the given function across `Right`.
*
- * @param The function to bind across `Right`.
+ * @param f The function to bind across `Right`.
*/
def flatMap[AA >: A, Y](f: B => Either[AA, Y]) = e match {
case Left(a) => Left(a)
@@ -20,7 +20,6 @@ object Function {
* function `f,,1,, andThen ... andThen f,,n,,`.
*
* @param fs The given sequence of functions
- * @return ...
*/
def chain[a](fs: Seq[a => a]): a => a = { x => (x /: fs) ((x, f) => f(x)) }
@@ -72,9 +71,6 @@ object Function {
*
* @note These functions are slotted for deprecation, but it is on
* hold pending superior type inference for tupling anonymous functions.
- *
- * @param f ...
- * @return ...
*/
// @deprecated("Use `f.tupled` instead")
def tupled[a1, a2, b](f: (a1, a2) => b): Tuple2[a1, a2] => b = {
@@ -146,7 +146,7 @@ sealed abstract class Option[+A] extends Product with Serializable {
/** Returns the result of applying $f to this $option's
* value if the $option is nonempty. Otherwise, evaluates
- * expression $ifEmpty.
+ * expression `ifEmpty`.
*
* @note This is equivalent to `$option map f getOrElse ifEmpty`.
*
@@ -160,7 +160,7 @@ object Predef extends LowPriorityImplicits {
* is at least `ASSERTION`.
*
* @see elidable
- * @param p the expression to test
+ * @param assertion the expression to test
*/
@elidable(ASSERTION)
def assert(assertion: Boolean) {
@@ -173,8 +173,8 @@ object Predef extends LowPriorityImplicits {
* is at least `ASSERTION`.
*
* @see elidable
- * @param p the expression to test
- * @param msg a String to include in the failure message
+ * @param assertion the expression to test
+ * @param message a String to include in the failure message
*/
@elidable(ASSERTION) @inline
final def assert(assertion: Boolean, message: => Any) {
@@ -189,7 +189,7 @@ object Predef extends LowPriorityImplicits {
* will not be generated if `-Xelide-below` is at least `ASSERTION`.
*
* @see elidable
- * @param p the expression to test
+ * @param assumption the expression to test
*/
@elidable(ASSERTION)
def assume(assumption: Boolean) {
@@ -204,8 +204,8 @@ object Predef extends LowPriorityImplicits {
* will not be generated if `-Xelide-below` is at least `ASSERTION`.
*
* @see elidable
- * @param p the expression to test
- * @param msg a String to include in the failure message
+ * @param assumption the expression to test
+ * @param message a String to include in the failure message
*/
@elidable(ASSERTION) @inline
final def assume(assumption: Boolean, message: => Any) {
@@ -217,7 +217,7 @@ object Predef extends LowPriorityImplicits {
* This method is similar to `assert`, but blames the caller of the method
* for violating the condition.
*
- * @param p the expression to test
+ * @param requirement the expression to test
*/
def require(requirement: Boolean) {
if (!requirement)
@@ -228,8 +228,8 @@ object Predef extends LowPriorityImplicits {
* This method is similar to `assert`, but blames the caller of the method
* for violating the condition.
*
- * @param p the expression to test
- * @param msg a String to include in the failure message
+ * @param requirement the expression to test
+ * @param message a String to include in the failure message
*/
@inline final def require(requirement: Boolean, message: => Any) {
if (!requirement)
@@ -19,7 +19,7 @@ package scala
*/
trait Product extends Any with Equals {
/** The n^th^ element of this product, 0-based. In other words, for a
- * product `A(x,,1,,, ..., x,,k,,)`, returns `x,,(n+1),, where `0 < n < k`.
+ * product `A(x,,1,,, ..., x,,k,,)`, returns `x,,(n+1),,` where `0 < n < k`.
*
* @param n the index of the element to return
* @throws `IndexOutOfBoundsException`
@@ -21,19 +21,13 @@ package scala
object Responder {
/** Creates a responder that answer continuations with the constant `a`.
- *
- * @param x ...
- * @return ...
*/
def constant[A](x: A) = new Responder[A] {
def respond(k: A => Unit) = k(x)
}
/** Executes `x` and returns `'''true'''`, useful as syntactic
* convenience in for comprehensions.
- *
- * @param x ...
- * @return ...
*/
def exec[A](x: => Unit): Boolean = { x; true }
@@ -132,7 +132,7 @@ object StringContext {
* escape: `\\`, `\"`, `\'`
* octal: `\d` `\dd` `\ddd` where `d` is an octal digit between `0` and `7`.
*
- * @param A string that may contain escape sequences
+ * @param str A string that may contain escape sequences
* @return The string with all escape sequences expanded.
*/
def treatEscapes(str: String): String = {
@@ -18,18 +18,22 @@ import java.util.logging.Level
* be omitted from generated code if the priority given the annotation
* is lower than that given on the command line.
*
+ * {{{
* @elidable(123) // annotation priority
* scalac -Xelide-below 456 // command line priority
- *
+ * }}}
+ *
* The method call will be replaced with an expression which depends on
* the type of the elided expression. In decreasing order of precedence:
*
+ * {{{
* Unit ()
* Boolean false
* T <: AnyVal 0
* T >: Null null
* T >: Nothing Predef.???
- *
+ * }}}
+ *
* Complete example:
{{{
import annotation._, elidable._
@@ -137,7 +137,7 @@ trait BitSetLike[+This <: BitSetLike[This] with SortedSet[Int]] extends SortedSe
/** Computes the intersection between this bitset and another bitset by performing
* a bitwise "and".
- * @param that the bitset to intersect with.
+ * @param other the bitset to intersect with.
* @return a new bitset consisting of all elements that are both in this
* bitset and in the given bitset `other`.
*/
@@ -152,7 +152,7 @@ trait BitSetLike[+This <: BitSetLike[This] with SortedSet[Int]] extends SortedSe
/** Computes the difference of this bitset and another bitset by performing
* a bitwise "and-not".
*
- * @param that the set of bits to exclude.
+ * @param other the set of bits to exclude.
* @return a bitset containing those bits of this
* bitset that are not also contained in the given bitset `other`.
*/
@@ -167,7 +167,7 @@ trait BitSetLike[+This <: BitSetLike[This] with SortedSet[Int]] extends SortedSe
/** Computes the symmetric difference of this bitset and another bitset by performing
* a bitwise "exclusive-or".
*
- * @param that the other bitset to take part in the symmetric difference.
+ * @param other the other bitset to take part in the symmetric difference.
* @return a bitset containing those bits of this
* bitset or the other bitset that are not contained in both bitsets.
*/
@@ -184,7 +184,7 @@ trait BitSetLike[+This <: BitSetLike[This] with SortedSet[Int]] extends SortedSe
/** Tests whether this bitset is a subset of another bitset.
*
- * @param that the bitset to test.
+ * @param other the bitset to test.
* @return `true` if this bitset is a subset of `other`, i.e. if
* every bit of this set is also an element in `other`.
*/
@@ -41,7 +41,7 @@ trait GenIterableLike[+A, +Repr] extends Any with GenTraversableLike[A, Repr] {
/** Checks if the other iterable collection contains the same elements in the same order as this $coll.
*
* @param that the collection to compare with.
- * @tparam B the type of the elements of collection `that`.
+ * @tparam A1 the type of the elements of collection `that`.
* @return `true`, if both collections contain the same elements in the same order, `false` otherwise.
*
* @usecase def sameElements(that: GenIterable[A]): Boolean
@@ -87,13 +87,13 @@ trait GenIterableLike[+A, +Repr] extends Any with GenTraversableLike[A, Repr] {
* @tparam A1 the type of the first half of the returned pairs (this is always a supertype
* of the collection's element type `A`).
* @tparam That the class of the returned collection. Where possible, `That` is
- * the same class as the current collection class `Repr`, but this
- * depends on the element type `(A1, Int)` being admissible for that class,
- * which means that an implicit instance of type `CanBuildFrom[Repr, (A1, Int), That]`.
- * is found.
- * @tparam bf an implicit value of class `CanBuildFrom` which determines the
- * result class `That` from the current representation type `Repr`
- * and the new element type `(A1, Int)`.
+ * the same class as the current collection class `Repr`, but this
+ * depends on the element type `(A1, Int)` being admissible for that class,
+ * which means that an implicit instance of type `CanBuildFrom[Repr, (A1, Int), That]`.
+ * is found.
+ * @param bf an implicit value of class `CanBuildFrom` which determines the
+ * result class `That` from the current representation type `Repr`
+ * and the new element type `(A1, Int)`.
* @return A new collection of type `That` containing pairs consisting of all elements of this
* $coll paired with their index. Indices start at `0`.
*
@@ -42,7 +42,6 @@ trait GenMapLike[A, +B, +Repr] extends GenIterableLike[(A, B), Repr] with Equals
* otherwise the result of the `default` computation.
* @usecase def getOrElse(key: A, default: => B): B
* @inheritdoc
- * @tparam B the result type of the default computation.
*/
def getOrElse[B1 >: B](key: A, default: => B1): B1
@@ -413,8 +413,6 @@ trait GenSeqLike[+A, +Repr] extends Any with GenIterableLike[A, Repr] with Equal
*
* @param that the sequence of elements to remove
* @tparam B the element type of the returned $coll.
- * @tparam That $thatinfo
- * @param bf $bfinfo
* @return a new collection of type `That` which contains all elements of this $coll
* except some of occurrences of elements that also appear in `that`.
* If an element value `x` appears
@@ -438,8 +436,6 @@ trait GenSeqLike[+A, +Repr] extends Any with GenIterableLike[A, Repr] with Equal
*
* @param that the sequence of elements to intersect with.
* @tparam B the element type of the returned $coll.
- * @tparam That $thatinfo
- * @param bf $bfinfo
* @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
@@ -289,27 +289,27 @@ trait GenTraversableLike[+A, +Repr] extends Any with GenTraversableOnce[A] with
/** Selects all elements of this $coll which satisfy a predicate.
*
- * @param p the predicate used to test elements.
+ * @param pred the predicate used to test elements.
* @return a new $coll consisting of all elements of this $coll that satisfy the given
* predicate `p`. Their order may not be preserved.
*/
def filter(pred: A => Boolean): Repr
/** Selects all elements of this $coll which do not satisfy a predicate.
*
- * @param p the predicate used to test elements.
+ * @param pred the predicate used to test elements.
* @return a new $coll consisting of all elements of this $coll that do not satisfy the given
* predicate `p`. Their order may not be preserved.
*/
def filterNot(pred: A => Boolean): Repr
/** Partitions this $coll in two ${coll}s according to a predicate.
*
- * @param p the predicate on which to partition.
- * @return a pair of ${coll}s: the first $coll consists of all elements that
- * satisfy the predicate `p` and the second $coll consists of all elements
- * that don't. The relative order of the elements in the resulting ${coll}s
- * may not be preserved.
+ * @param pred the predicate on which to partition.
+ * @return a pair of ${coll}s: the first $coll consists of all elements that
+ * satisfy the predicate `p` and the second $coll consists of all elements
+ * that don't. The relative order of the elements in the resulting ${coll}s
+ * may not be preserved.
*/
def partition(pred: A => Boolean): (Repr, Repr)
@@ -354,8 +354,8 @@ trait GenTraversableLike[+A, +Repr] extends Any with GenTraversableOnce[A] with
* }}}
* $orderDependent
*
- * @param from the lowest index to include from this $coll.
- * @param until the lowest index to EXCLUDE from this $coll.
+ * @param unc_from the lowest index to include from this $coll.
+ * @param unc_until the lowest index to EXCLUDE from this $coll.
* @return a $coll containing the elements greater than or equal to
* index `from` extending up to (but not including) index `until`
* of this $coll.
@@ -375,7 +375,7 @@ trait GenTraversableLike[+A, +Repr] extends Any with GenTraversableOnce[A] with
/** Takes longest prefix of elements that satisfy a predicate.
* $orderDependent
- * @param p The predicate used to test elements.
+ * @param pred The predicate used to test elements.
* @return the longest prefix of this $coll whose elements all satisfy
* the predicate `p`.
*/
@@ -388,15 +388,15 @@ trait GenTraversableLike[+A, +Repr] extends Any with GenTraversableOnce[A] with
* predicate `p` does not cause any side-effects.
* $orderDependent
*
- * @param p the test predicate
+ * @param pred the test predicate
* @return a pair consisting of the longest prefix of this $coll whose
* elements all satisfy `p`, and the rest of this $coll.
*/
def span(pred: A => Boolean): (Repr, Repr)
/** Drops longest prefix of elements that satisfy a predicate.
* $orderDependent
- * @param p The predicate used to test elements.
+ * @param pred The predicate used to test elements.
* @return the longest suffix of this $coll whose first element
* does not satisfy the predicate `p`.
*/
Oops, something went wrong.

0 comments on commit 4af7703

Please sign in to comment.