diff options
23 files changed, 512 insertions, 266 deletions
@@ -1604,7 +1604,7 @@ DOCUMENTATION <mkdir dir="${build-docs.dir}/library"/> <scaladoc destdir="${build-docs.dir}/library" - doctitle="Scala Standard Library" + doctitle="Scala Standard Library API (Scaladoc)" docversion="${version.number}" docfooter="epfl" docsourceurl="https://lampsvn.epfl.ch/trac/scala/browser/scala/trunk/src/€{FILE_PATH}.scala#L1" diff --git a/src/compiler/scala/tools/nsc/doc/html/HtmlFactory.scala b/src/compiler/scala/tools/nsc/doc/html/HtmlFactory.scala index 4f05678d85..0116e02e0e 100644 --- a/src/compiler/scala/tools/nsc/doc/html/HtmlFactory.scala +++ b/src/compiler/scala/tools/nsc/doc/html/HtmlFactory.scala @@ -119,7 +119,7 @@ class HtmlFactory(val universe: doc.Universe, index: doc.Index) { def writeTemplate(tpl: DocTemplateEntity) { if (!(written contains tpl)) { - writeForThis(new page.Template(tpl)) + writeForThis(new page.Template(universe, tpl)) written += tpl tpl.templates map writeTemplate } diff --git a/src/compiler/scala/tools/nsc/doc/html/HtmlPage.scala b/src/compiler/scala/tools/nsc/doc/html/HtmlPage.scala index b58c71eaa9..1544dafc69 100644 --- a/src/compiler/scala/tools/nsc/doc/html/HtmlPage.scala +++ b/src/compiler/scala/tools/nsc/doc/html/HtmlPage.scala @@ -22,6 +22,16 @@ abstract class HtmlPage extends Page { thisPage => /** The title of this page. */ protected def title: String + /** The page description */ + protected def description: String = + // unless overwritten, will display the title in a spaced format, keeping - and . + title.replaceAll("[^a-zA-Z0-9\\.\\-]+", " ").replaceAll("\\-+", " - ").replaceAll(" +", " ") + + /** The page keywords */ + protected def keywords: String = + // unless overwritten, same as description, minus the " - " + description.replaceAll(" - ", " ") + /** Additional header elements (links, scripts, meta tags, etc.) required for this page. */ protected def headers: NodeSeq @@ -35,6 +45,8 @@ abstract class HtmlPage extends Page { thisPage => <html> <head> <title>{ title }</title> + <meta name="description" content={ description }/> + <meta name="keywords" content={ keywords }/> <meta http-equiv="content-type" content={ "text/html; charset=" + site.encoding }/> { headers } </head> diff --git a/src/compiler/scala/tools/nsc/doc/html/SyntaxHigh.scala b/src/compiler/scala/tools/nsc/doc/html/SyntaxHigh.scala index f19f449d2c..f67abc58da 100644 --- a/src/compiler/scala/tools/nsc/doc/html/SyntaxHigh.scala +++ b/src/compiler/scala/tools/nsc/doc/html/SyntaxHigh.scala @@ -219,24 +219,24 @@ private[html] object SyntaxHigh { parse(" ", i+1) case '&' => parse("&", i+1) - case '<' => + case '<' if i+1 < buf.length => val ch = buf(i+1).toChar if (ch == '-' || ch == ':' || ch == '%') parse("<span class=\"kw\"><"+ch+"</span>", i+2) else parse("<", i+1) case '>' => - if (buf(i+1) == ':') + if (i+1 < buf.length && buf(i+1) == ':') parse("<span class=\"kw\">>:</span>", i+2) else parse(">", i+1) case '=' => - if (buf(i+1) == '>') + if (i+1 < buf.length && buf(i+1) == '>') parse("<span class=\"kw\">=></span>", i+2) else parse(buf(i).toChar.toString, i+1) case '/' => - if (buf(i+1) == '/' || buf(i+1) == '*') { + if (i+1 < buf.length && (buf(i+1) == '/' || buf(i+1) == '*')) { val c = comment(i+1) parse("<span class=\"cmt\">"+c+"</span>", i+c.length) } else @@ -257,9 +257,9 @@ private[html] object SyntaxHigh { else parse(buf(i).toChar.toString, i+1) case _ => - if (i == 0 || !Character.isJavaIdentifierPart(buf(i-1).toChar)) { + if (i == 0 || (i >= 1 && !Character.isJavaIdentifierPart(buf(i-1).toChar))) { if (Character.isDigit(buf(i)) || - (buf(i) == '.' && Character.isDigit(buf(i+1)))) { + (buf(i) == '.' && i + 1 < buf.length && Character.isDigit(buf(i+1)))) { val s = numlit(i) parse("<span class=\"num\">"+s+"</span>", i+s.length) } else { diff --git a/src/compiler/scala/tools/nsc/doc/html/page/Template.scala b/src/compiler/scala/tools/nsc/doc/html/page/Template.scala index e35286b281..bd5f98bab7 100644 --- a/src/compiler/scala/tools/nsc/doc/html/page/Template.scala +++ b/src/compiler/scala/tools/nsc/doc/html/page/Template.scala @@ -11,13 +11,19 @@ package page import model._ import scala.xml.{ NodeSeq, Text, UnprefixedAttribute } -class Template(tpl: DocTemplateEntity) extends HtmlPage { +class Template(universe: doc.Universe, tpl: DocTemplateEntity) extends HtmlPage { val path = templateToPath(tpl) - val title = - tpl.qualifiedName + def title = { + val s = universe.settings + + tpl.name + + ( if (!s.doctitle.isDefault) " - " + s.doctitle.value else "" ) + + ( if (!s.docversion.isDefault) (" " + s.docversion.value) else "" ) + + " - " + tpl.qualifiedName + } val headers = <xml:group> diff --git a/src/compiler/scala/tools/nsc/doc/model/comment/CommentFactory.scala b/src/compiler/scala/tools/nsc/doc/model/comment/CommentFactory.scala index b088c643cb..bc5cd4a958 100644 --- a/src/compiler/scala/tools/nsc/doc/model/comment/CommentFactory.scala +++ b/src/compiler/scala/tools/nsc/doc/model/comment/CommentFactory.scala @@ -491,7 +491,7 @@ trait CommentFactory { thisFactory: ModelFactory with CommentFactory => else jump("}}}") blockEnded("code block") - Code(getRead) + Code(normalizeIndentation(getRead)) } /** {{{ title ::= ('=' inline '=' | "==" inline "==" | ...) '\n' }}} */ @@ -732,6 +732,64 @@ trait CommentFactory { thisFactory: ModelFactory with CommentFactory => nextChar() } + /** + * Eliminates the (common) leading spaces in all lines, based on the first line + * For indented pieces of code, it reduces the indent to the least whitespace prefix: + * {{{ + * indented example + * another indented line + * if (condition) + * then do something; + * ^ this is the least whitespace prefix + * }}} + */ + def normalizeIndentation(_code: String): String = { + + var code = _code.trim + var maxSkip = Integer.MAX_VALUE + var crtSkip = 0 + var wsArea = true + var index = 0 + var firstLine = true + var emptyLine = true + + while (index < code.length) { + code(index) match { + case ' ' => + if (wsArea) + crtSkip += 1 + case c => + wsArea = (c == '\n') + maxSkip = if (firstLine || emptyLine) maxSkip else if (maxSkip <= crtSkip) maxSkip else crtSkip + crtSkip = if (c == '\n') 0 else crtSkip + firstLine = if (c == '\n') false else firstLine + emptyLine = if (c == '\n') true else false + } + index += 1 + } + + if (maxSkip == 0) + code + else { + index = 0 + val builder = new StringBuilder + while (index < code.length) { + builder.append(code(index)) + if (code(index) == '\n') { + // we want to skip as many spaces are available, if there are less spaces (like on empty lines, do not + // over-consume them) + index += 1 + val limit = index + maxSkip + while ((index < code.length) && (code(index) == ' ') && index < limit) + index += 1 + } + else + index += 1 + } + builder.toString + } + } + def checkParaEnded(): Boolean = { (char == endOfText) || ((char == endOfLine) && { diff --git a/src/library/scala/collection/GenIterableLike.scala b/src/library/scala/collection/GenIterableLike.scala index 7e68733afd..8fa5981969 100644 --- a/src/library/scala/collection/GenIterableLike.scala +++ b/src/library/scala/collection/GenIterableLike.scala @@ -40,17 +40,18 @@ 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. * - * $orderDependent - * $willNotTerminateInf - * * @param that the collection to compare with. * @tparam B 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 + * @inheritdoc * - * @param that the collection to compare with. - * @return `true`, if both collections contain the same elements in the same order, `false` otherwise. + * $orderDependent + * $willNotTerminateInf + * + * @param that the collection to compare with. + * @return `true`, if both collections contain the same elements in the same order, `false` otherwise. */ def sameElements[A1 >: A](that: GenIterable[A1]): Boolean @@ -58,8 +59,6 @@ trait GenIterableLike[+A, +Repr] extends Any with GenTraversableLike[A, Repr] { * by combining corresponding elements in pairs. * If one of the two collections is longer than the other, its remaining elements are ignored. * - * $orderDependent - * * @param that The iterable providing the second half of each result pair * @tparam A1 the type of the first half of the returned pairs (this is always a supertype * of the collection's element type `A`). @@ -71,19 +70,20 @@ trait GenIterableLike[+A, +Repr] extends Any with GenTraversableLike[A, Repr] { * of the returned collection is the minimum of the lengths of this $coll and `that`. * * @usecase def zip[B](that: GenIterable[B]): $Coll[(A, B)] + * @inheritdoc * - * @param that The iterable providing the second half of each result pair - * @tparam B the type of the second half of the returned pairs - * @return a new $coll containing pairs consisting of - * corresponding elements of this $coll and `that`. The length - * of the returned collection is the minimum of the lengths of this $coll and `that`. + * $orderDependent + * + * @param that The iterable providing the second half of each result pair + * @tparam B the type of the second half of the returned pairs + * @return a new $coll containing pairs consisting of + * corresponding elements of this $coll and `that`. The length + * of the returned collection is the minimum of the lengths of this $coll and `that`. */ def zip[A1 >: A, B, That](that: GenIterable[B])(implicit bf: CBF[Repr, (A1, B), That]): That /** Zips this $coll with its indices. * - * $orderDependent - * * @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 @@ -98,11 +98,14 @@ trait GenIterableLike[+A, +Repr] extends Any with GenTraversableLike[A, Repr] { * $coll paired with their index. Indices start at `0`. * * @usecase def zipWithIndex: $Coll[(A, Int)] + * @inheritdoc * - * @return A new $coll containing pairs consisting of all elements of this - * $coll paired with their index. Indices start at `0`. - * @example - * `List("a", "b", "c").zipWithIndex = List(("a", 0), ("b", 1), ("c", 2))` + * $orderDependent + * + * @return A new $coll containing pairs consisting of all elements of this + * $coll paired with their index. Indices start at `0`. + * @example + * `List("a", "b", "c").zipWithIndex = List(("a", 0), ("b", 1), ("c", 2))` * */ def zipWithIndex[A1 >: A, That](implicit bf: CBF[Repr, (A1, Int), That]): That @@ -112,8 +115,6 @@ trait GenIterableLike[+A, +Repr] extends Any with GenTraversableLike[A, Repr] { * If one of the two collections is shorter than the other, * placeholder elements are used to extend the shorter collection to the length of the longer. * - * $orderDependent - * * @param that the iterable providing the second half of each result pair * @param thisElem the element to be used to fill up the result if this $coll is shorter than `that`. * @param thatElem the element to be used to fill up the result if `that` is shorter than this $coll. @@ -124,16 +125,19 @@ trait GenIterableLike[+A, +Repr] extends Any with GenTraversableLike[A, Repr] { * If `that` is shorter than this $coll, `thatElem` values are used to pad the result. * * @usecase def zipAll[B](that: Iterable[B], thisElem: A, thatElem: B): $Coll[(A, B)] - * - * @param that The iterable providing the second half of each result pair - * @param thisElem the element to be used to fill up the result if this $coll is shorter than `that`. - * @param thatElem the element to be used to fill up the result if `that` is shorter than this $coll. - * @tparam B the type of the second half of the returned pairs - * @return a new $coll containing pairs consisting of - * corresponding elements of this $coll and `that`. The length - * of the returned collection is the maximum of the lengths of this $coll and `that`. - * If this $coll is shorter than `that`, `thisElem` values are used to pad the result. - * If `that` is shorter than this $coll, `thatElem` values are used to pad the result. + * @inheritdoc + * + * $orderDependent + * + * @param that The iterable providing the second half of each result pair + * @param thisElem the element to be used to fill up the result if this $coll is shorter than `that`. + * @param thatElem the element to be used to fill up the result if `that` is shorter than this $coll. + * @tparam B the type of the second half of the returned pairs + * @return a new $coll containing pairs consisting of + * corresponding elements of this $coll and `that`. The length + * of the returned collection is the maximum of the lengths of this $coll and `that`. + * If this $coll is shorter than `that`, `thisElem` values are used to pad the result. + * If `that` is shorter than this $coll, `thatElem` values are used to pad the result. */ def zipAll[B, A1 >: A, That](that: GenIterable[B], thisElem: A1, thatElem: B)(implicit bf: CBF[Repr, (A1, B), That]): That diff --git a/src/library/scala/collection/GenMapLike.scala b/src/library/scala/collection/GenMapLike.scala index 12ecbcf140..114169c849 100644 --- a/src/library/scala/collection/GenMapLike.scala +++ b/src/library/scala/collection/GenMapLike.scala @@ -41,6 +41,8 @@ trait GenMapLike[A, +B, +Repr] extends GenIterableLike[(A, B), Repr] with Equals * @return the value associated with `key` if it exists, * 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 diff --git a/src/library/scala/collection/GenSeqLike.scala b/src/library/scala/collection/GenSeqLike.scala index cb0e96fcbb..755abcd2bf 100644 --- a/src/library/scala/collection/GenSeqLike.scala +++ b/src/library/scala/collection/GenSeqLike.scala @@ -115,21 +115,21 @@ trait GenSeqLike[+A, +Repr] extends Any with GenIterableLike[A, Repr] with Equal /** Finds index of first occurrence of some value in this $coll. * - * $mayNotTerminateInf - * * @param elem the element value to search for. * @tparam B the type of the element `elem`. * @return the index of the first element of this $coll that is equal (wrt `==`) * to `elem`, or `-1`, if none exists. * * @usecase def indexOf(elem: A): Int + * @inheritdoc + * + * $mayNotTerminateInf + * */ def indexOf[B >: A](elem: B): Int = indexOf(elem, 0) /** Finds index of first occurrence of some value in this $coll after or at some start index. * - * $mayNotTerminateInf - * * @param elem the element value to search for. * @tparam B the type of the element `elem`. * @param from the start index @@ -137,19 +137,25 @@ trait GenSeqLike[+A, +Repr] extends Any with GenIterableLike[A, Repr] with Equal * to `elem`, or `-1`, if none exists. * * @usecase def indexOf(elem: A, from: Int): Int + * @inheritdoc + * + * $mayNotTerminateInf + * */ def indexOf[B >: A](elem: B, from: Int): Int = indexWhere(elem ==, from) /** Finds index of last occurrence of some value in this $coll. * - * $willNotTerminateInf - * * @param elem the element value to search for. * @tparam B the type of the element `elem`. * @return the index of the last element of this $coll that is equal (wrt `==`) * to `elem`, or `-1`, if none exists. * * @usecase def lastIndexOf(elem: A): Int + * @inheritdoc + * + * $willNotTerminateInf + * */ def lastIndexOf[B >: A](elem: B): Int = lastIndexWhere(elem ==) @@ -162,6 +168,7 @@ trait GenSeqLike[+A, +Repr] extends Any with GenIterableLike[A, Repr] with Equal * to `elem`, or `-1`, if none exists. * * @usecase def lastIndexOf(elem: A, end: Int): Int + * @inheritdoc */ def lastIndexOf[B >: A](elem: B, end: Int): Int = lastIndexWhere(elem ==, end) @@ -195,10 +202,6 @@ trait GenSeqLike[+A, +Repr] extends Any with GenIterableLike[A, Repr] with Equal * Builds a new collection by applying a function to all elements of this $coll and * collecting the results in reversed order. * - * $willNotTerminateInf - * - * Note: `xs.reverseMap(f)` is the same as `xs.reverse.map(f)` but might be more efficient. - * * @param f the function to apply to each element. * @tparam B the element type of the returned collection. * @tparam That $thatinfo @@ -207,10 +210,14 @@ trait GenSeqLike[+A, +Repr] extends Any with GenIterableLike[A, Repr] with Equal * `f` to each element of this $coll and collecting the results in reversed order. * * @usecase def reverseMap[B](f: A => B): $Coll[B] + * @inheritdoc * - * Note: `xs.reverseMap(f)` is the same as `xs.reverse.map(f)` but might be more efficient. - * @return a new $coll resulting from applying the given function - * `f` to each element of this $coll and collecting the results in reversed order. + * $willNotTerminateInf + * + * Note: `xs.reverseMap(f)` is the same as `xs.reverse.map(f)` but might be more efficient. + * + * @return a new $coll resulting from applying the given function + * `f` to each element of this $coll and collecting the results in reversed order. */ def reverseMap[B, That](f: A => B)(implicit bf: CanBuildFrom[Repr, B, That]): That @@ -254,10 +261,13 @@ trait GenSeqLike[+A, +Repr] extends Any with GenIterableLike[A, Repr] with Equal * @return a new $coll consisting of all elements of this $coll * except that `replaced` elements starting from `from` are replaced * by `patch`. + * * @usecase def patch(from: Int, that: GenSeq[A], replaced: Int): $Coll[A] - * @return a new $coll consisting of all elements of this $coll - * except that `replaced` elements starting from `from` are replaced - * by `patch`. + * @inheritdoc + * + * @return a new $coll consisting of all elements of this $coll + * except that `replaced` elements starting from `from` are replaced + * by `patch`. */ def patch[B >: A, That](from: Int, patch: GenSeq[B], replaced: Int)(implicit bf: CanBuildFrom[Repr, B, That]): That @@ -268,20 +278,33 @@ trait GenSeqLike[+A, +Repr] extends Any with GenIterableLike[A, Repr] with Equal * @tparam That $thatinfo * @param bf $bfinfo * @return a new $coll` which is a copy of this $coll with the element at position `index` replaced by `elem`. + * * @usecase def updated(index: Int, elem: A): $Coll[A] - * @return a copy of this $coll with the element at position `index` replaced by `elem`. + * @inheritdoc + * + * @return a copy of this $coll with the element at position `index` replaced by `elem`. */ def updated[B >: A, That](index: Int, elem: B)(implicit bf: CanBuildFrom[Repr, B, That]): That /** A copy of the $coll with an element prepended. * - * Note that :-ending operators are right associative (see example). - * A mnemonic for `+:` vs. `:+` is: the COLon goes on the COLlection side. + * @param elem the prepended element + * @tparam B the element type of the returned $coll. + * @tparam That $thatinfo + * @param bf $bfinfo + * @return a new collection of type `That` consisting of `elem` followed + * by all elements of this $coll. + * + * @usecase def +:(elem: A): $Coll[A] + * @inheritdoc + * + * Note that :-ending operators are right associative (see example). + * A mnemonic for `+:` vs. `:+` is: the COLon goes on the COLlection side. * - * Also, the original $coll is not modified, so you will want to capture the result. + * Also, the original $coll is not modified, so you will want to capture the result. * - * Example: - * {{{ + * Example: + * {{{ * scala> val x = LinkedList(1) * x: scala.collection.mutable.LinkedList[Int] = LinkedList(1) * @@ -290,17 +313,10 @@ trait GenSeqLike[+A, +Repr] extends Any with GenIterableLike[A, Repr] with Equal * * scala> println(x) * LinkedList(1) - * }}} + * }}} * - * @param elem the prepended element - * @tparam B the element type of the returned $coll. - * @tparam That $thatinfo - * @param bf $bfinfo - * @return a new collection of type `That` consisting of `elem` followed - * by all elements of this $coll. - * @usecase def +:(elem: A): $Coll[A] - * @return a new $coll consisting of `elem` followed - * by all elements of this $coll. + * @return a new $coll consisting of `elem` followed + * by all elements of this $coll. */ def +:[B >: A, That](elem: B)(implicit bf: CanBuildFrom[Repr, B, That]): That @@ -308,18 +324,20 @@ trait GenSeqLike[+A, +Repr] extends Any with GenIterableLike[A, Repr] with Equal * * A mnemonic for `+:` vs. `:+` is: the COLon goes on the COLlection side. * - * $willNotTerminateInf * @param elem the appended element * @tparam B the element type of the returned $coll. * @tparam That $thatinfo * @param bf $bfinfo * @return a new collection of type `That` consisting of * all elements of this $coll followed by `elem`. + * * @usecase def :+(elem: A): $Coll[A] - * @return a new $coll consisting of - * all elements of this $coll followed by `elem`. - * @example - * {{{ + * @inheritdoc + * + * $willNotTerminateInf + * + * Example: + * {{{ * scala> import scala.collection.mutable.LinkedList * import scala.collection.mutable.LinkedList * @@ -331,7 +349,10 @@ trait GenSeqLike[+A, +Repr] extends Any with GenIterableLike[A, Repr] with Equal * * scala> println(a) * LinkedList(1) - * }}} + * }}} + * + * @return a new $coll consisting of + * all elements of this $coll followed by `elem`. */ def :+[B >: A, That](elem: B)(implicit bf: CanBuildFrom[Repr, B, That]): That @@ -346,9 +367,11 @@ trait GenSeqLike[+A, +Repr] extends Any with GenIterableLike[A, Repr] with Equal * all elements of this $coll followed by the minimal number of occurrences of `elem` so * that the resulting collection has a length of at least `len`. * @usecase def padTo(len: Int, elem: A): $Coll[A] - * @return a new $coll consisting of - * all elements of this $coll followed by the minimal number of occurrences of `elem` so - * that the resulting $coll has a length of at least `len`. + * @inheritdoc + * + * @return a new $coll consisting of + * all elements of this $coll followed by the minimal number of occurrences of `elem` so + * that the resulting $coll has a length of at least `len`. */ def padTo[B >: A, That](len: Int, elem: B)(implicit bf: CanBuildFrom[Repr, B, That]): That @@ -368,13 +391,6 @@ trait GenSeqLike[+A, +Repr] extends Any with GenIterableLike[A, Repr] with Equal /** Produces a new sequence which contains all elements of this $coll and also all elements of * a given sequence. `xs union ys` is equivalent to `xs ++ ys`. - * $willNotTerminateInf - * - * Another way to express this - * is that `xs union ys` computes the order-presevring multi-set union of `xs` and `ys`. - * `union` is hence a counter-part of `diff` and `intersect` which also work on multi-sets. - * - * $willNotTerminateInf * * @param that the sequence to add. * @tparam B the element type of the returned $coll. @@ -382,9 +398,18 @@ trait GenSeqLike[+A, +Repr] extends Any with GenIterableLike[A, Repr] with Equal * @param bf $bfinfo * @return a new collection of type `That` which contains all elements of this $coll * followed by all elements of `that`. + * * @usecase def union(that: GenSeq[A]): $Coll[A] - * @return a new $coll which contains all elements of this $coll - * followed by all elements of `that`. + * @inheritdoc + * + * Another way to express this + * is that `xs union ys` computes the order-presevring multi-set union of `xs` and `ys`. + * `union` is hence a counter-part of `diff` and `intersect` which also work on multi-sets. + * + * $willNotTerminateInf + * + * @return a new $coll which contains all elements of this $coll + * followed by all elements of `that`. */ def union[B >: A, That](that: GenSeq[B])(implicit bf: CanBuildFrom[Repr, B, That]): That = this ++ that @@ -393,7 +418,6 @@ trait GenSeqLike[+A, +Repr] extends Any with GenIterableLike[A, Repr] with Equal union(that: GenSeq[B])(bf) /** Computes the multiset difference between this $coll and another sequence. - * $willNotTerminateInf * * @param that the sequence of elements to remove * @tparam B the element type of the returned $coll. @@ -404,17 +428,21 @@ trait GenSeqLike[+A, +Repr] extends Any with GenIterableLike[A, Repr] with Equal * If an element value `x` appears * ''n'' times in `that`, then the first ''n'' occurrences of `x` will not form * part of the result, but any following occurrences will. + * * @usecase def diff(that: GenSeq[A]): $Coll[A] - * @return a new $coll which contains all elements of this $coll - * except some of occurrences of elements that also appear in `that`. - * If an element value `x` appears - * ''n'' times in `that`, then the first ''n'' occurrences of `x` will not form - * part of the result, but any following occurrences will. + * @inheritdoc + * + * $willNotTerminateInf + * + * @return a new $coll which contains all elements of this $coll + * except some of occurrences of elements that also appear in `that`. + * If an element value `x` appears + * ''n'' times in `that`, then the first ''n'' occurrences of `x` will not form + * part of the result, but any following occurrences will. */ def diff[B >: A](that: GenSeq[B]): Repr /** Computes the multiset intersection between this $coll and another sequence. - * $mayNotTerminateInf * * @param that the sequence of elements to intersect with. * @tparam B the element type of the returned $coll. @@ -425,12 +453,17 @@ trait GenSeqLike[+A, +Repr] extends Any with GenIterableLike[A, Repr] with Equal * If an element value `x` appears * ''n'' times in `that`, then the first ''n'' occurrences of `x` will be retained * in the result, but any following occurrences will be omitted. + * * @usecase def intersect(that: GenSeq[A]): $Coll[A] - * @return a new $coll which contains all elements of this $coll - * which also appear in `that`. - * If an element value `x` appears - * ''n'' times in `that`, then the first ''n'' occurrences of `x` will be retained - * in the result, but any following occurrences will be omitted. + * @inheritdoc + * + * $mayNotTerminateInf + * + * @return a new $coll which contains all elements of this $coll + * which also appear in `that`. + * If an element value `x` appears + * ''n'' times in `that`, then the first ''n'' occurrences of `x` will be retained + * in the result, but any following occurrences will be omitted. */ def intersect[B >: A](that: GenSeq[B]): Repr diff --git a/src/library/scala/collection/GenTraversableLike.scala b/src/library/scala/collection/GenTraversableLike.scala index dd5f602c41..fd03e0f446 100644 --- a/src/library/scala/collection/GenTraversableLike.scala +++ b/src/library/scala/collection/GenTraversableLike.scala @@ -136,6 +136,7 @@ trait GenTraversableLike[+A, +Repr] extends Any with GenTraversableOnce[A] with * but this is not necessary. * * @usecase def foreach(f: A => Unit): Unit + * @inheritdoc */ def foreach[U](f: A => U): Unit @@ -149,17 +150,15 @@ trait GenTraversableLike[+A, +Repr] extends Any with GenTraversableOnce[A] with * `f` to each element of this $coll and collecting the results. * * @usecase def map[B](f: A => B): $Coll[B] - * - * @return a new $coll resulting from applying the given function - * `f` to each element of this $coll and collecting the results. + * @inheritdoc + * @return a new $coll resulting from applying the given function + * `f` to each element of this $coll and collecting the results. */ def map[B, That](f: A => B)(implicit bf: CanBuildFrom[Repr, B, That]): That /** Builds a new collection by applying a partial function to all elements of this $coll * on which the function is defined. * - * $collectExample - * * @param pf the partial function which filters and maps the $coll. * @tparam B the element type of the returned collection. * @tparam That $thatinfo @@ -169,36 +168,18 @@ trait GenTraversableLike[+A, +Repr] extends Any with GenTraversableOnce[A] with * The order of the elements is preserved. * * @usecase def collect[B](pf: PartialFunction[A, B]): $Coll[B] + * @inheritdoc * - * @return a new $coll resulting from applying the given partial function - * `pf` to each element on which it is defined and collecting the results. - * The order of the elements is preserved. + * $collectExample + * + * @return a new $coll resulting from applying the given partial function + * `pf` to each element on which it is defined and collecting the results. + * The order of the elements is preserved. */ def collect[B, That](pf: PartialFunction[A, B])(implicit bf: CanBuildFrom[Repr, B, That]): That /** Builds a new collection by applying a function to all elements of this $coll - * and using the elements of the resulting collections. For example: - * - * {{{ - * def getWords(lines: Seq[String]): Seq[String] = lines flatMap (line => line split "\\W+") - * }}} - * - * The type of the resulting collection is guided by the static type of $coll. This might - * cause unexpected results sometimes. For example: - * - * {{{ - * // lettersOf will return a Seq[Char] of likely repeated letters, instead of a Set - * def lettersOf(words: Seq[String]) = words flatMap (word => word.toSet) - * - * // lettersOf will return a Set[Char], not a Seq - * def lettersOf(words: Seq[String]) = words.toSet flatMap (word => word.toSeq) - * - * // xs will be a an Iterable[Int] - * val xs = Map("a" -> List(11,111), "b" -> List(22,222)).flatMap(_._2) - * - * // ys will be a Map[Int, Int] - * val ys = Map("a" -> List(1 -> 11,1 -> 111), "b" -> List(2 -> 22,2 -> 222)).flatMap(_._2) - * }}} + * and using the elements of the resulting collections. * * @param f the function to apply to each element. * @tparam B the element type of the returned collection. @@ -208,33 +189,39 @@ trait GenTraversableLike[+A, +Repr] extends Any with GenTraversableOnce[A] with * `f` to each element of this $coll and concatenating the results. * * @usecase def flatMap[B](f: A => GenTraversableOnce[B]): $Coll[B] + * @inheritdoc * - * @return a new $coll resulting from applying the given collection-valued function - * `f` to each element of this $coll and concatenating the results. - */ - def flatMap[B, That](f: A => GenTraversableOnce[B])(implicit bf: CanBuildFrom[Repr, B, That]): That - - /** Returns a new $coll containing the elements from the left hand operand followed by the elements from the - * right hand operand. The element type of the $coll is the most specific superclass encompassing - * the element types of the two operands (see example). + * For example: * - * Example: - * {{{ - * scala> val a = LinkedList(1) - * a: scala.collection.mutable.LinkedList[Int] = LinkedList(1) + * {{{ + * def getWords(lines: Seq[String]): Seq[String] = lines flatMap (line => line split "\\W+") + * }}} * - * scala> val b = LinkedList(2) - * b: scala.collection.mutable.LinkedList[Int] = LinkedList(2) + * The type of the resulting collection is guided by the static type of $coll. This might + * cause unexpected results sometimes. For example: * - * scala> val c = a ++ b - * c: scala.collection.mutable.LinkedList[Int] = LinkedList(1, 2) + * {{{ + * // lettersOf will return a Seq[Char] of likely repeated letters, instead of a Set + * def lettersOf(words: Seq[String]) = words flatMap (word => word.toSet) * - * scala> val d = LinkedList('a') - * d: scala.collection.mutable.LinkedList[Char] = LinkedList(a) + * // lettersOf will return a Set[Char], not a Seq + * def lettersOf(words: Seq[String]) = words.toSet flatMap (word => word.toSeq) * - * scala> val e = c ++ d - * e: scala.collection.mutable.LinkedList[AnyVal] = LinkedList(1, 2, a) - * }}} + * // xs will be a an Iterable[Int] + * val xs = Map("a" -> List(11,111), "b" -> List(22,222)).flatMap(_._2) + * + * // ys will be a Map[Int, Int] + * val ys = Map("a" -> List(1 -> 11,1 -> 111), "b" -> List(2 -> 22,2 -> 222)).flatMap(_._2) + * }}} + * + * @return a new $coll resulting from applying the given collection-valued function + * `f` to each element of this $coll and concatenating the results. + */ + def flatMap[B, That](f: A => GenTraversableOnce[B])(implicit bf: CanBuildFrom[Repr, B, That]): That + + /** Returns a new $coll containing the elements from the left hand operand followed by the elements from the + * right hand operand. The element type of the $coll is the most specific superclass encompassing + * the element types of the two operands. * * @param that the traversable to append. * @tparam B the element type of the returned collection. @@ -244,9 +231,28 @@ trait GenTraversableLike[+A, +Repr] extends Any with GenTraversableOnce[A] with * of this $coll followed by all elements of `that`. * * @usecase def ++[B](that: GenTraversableOnce[B]): $Coll[B] + * @inheritdoc + * + * Example: + * {{{ + * scala> val a = LinkedList(1) + * a: scala.collection.mutable.LinkedList[Int] = LinkedList(1) + * + * scala> val b = LinkedList(2) + * b: scala.collection.mutable.LinkedList[Int] = LinkedList(2) + * + * scala> val c = a ++ b + * c: scala.collection.mutable.LinkedList[Int] = LinkedList(1, 2) + * + * scala> val d = LinkedList('a') + * d: scala.collection.mutable.LinkedList[Char] = LinkedList(a) + * + * scala> val e = c ++ d + * e: scala.collection.mutable.LinkedList[AnyVal] = LinkedList(1, 2, a) + * }}} * - * @return a new $coll which contains all elements of this $coll - * followed by all elements of `that`. + * @return a new $coll which contains all elements of this $coll + * followed by all elements of `that`. */ def ++[B >: A, That](that: GenTraversableOnce[B])(implicit bf: CanBuildFrom[Repr, B, That]): That diff --git a/src/library/scala/collection/GenTraversableOnce.scala b/src/library/scala/collection/GenTraversableOnce.scala index 67ea4cdb00..f18e2ab6bb 100644 --- a/src/library/scala/collection/GenTraversableOnce.scala +++ b/src/library/scala/collection/GenTraversableOnce.scala @@ -316,11 +316,12 @@ trait GenTraversableOnce[+A] extends Any { * @return the sum of all elements of this $coll with respect to the `+` operator in `num`. * * @usecase def sum: A + * @inheritdoc * - * @return the sum of all elements in this $coll of numbers of type `Int`. - * Instead of `Int`, any other type `T` with an implicit `Numeric[T]` implementation - * can be used as element type of the $coll and as result type of `sum`. - * Examples of such types are: `Long`, `Float`, `Double`, `BigInt`. + * @return the sum of all elements in this $coll of numbers of type `Int`. + * Instead of `Int`, any other type `T` with an implicit `Numeric[T]` implementation + * can be used as element type of the $coll and as result type of `sum`. + * Examples of such types are: `Long`, `Float`, `Double`, `BigInt`. * */ def sum[A1 >: A](implicit num: Numeric[A1]): A1 @@ -333,11 +334,12 @@ trait GenTraversableOnce[+A] extends Any { * @return the product of all elements of this $coll with respect to the `*` operator in `num`. * * @usecase def product: A + * @inheritdoc * - * @return the product of all elements in this $coll of numbers of type `Int`. - * Instead of `Int`, any other type `T` with an implicit `Numeric[T]` implementation - * can be used as element type of the $coll and as result type of `product`. - * Examples of such types are: `Long`, `Float`, `Double`, `BigInt`. + * @return the product of all elements in this $coll of numbers of type `Int`. + * Instead of `Int`, any other type `T` with an implicit `Numeric[T]` implementation + * can be used as element type of the $coll and as result type of `product`. + * Examples of such types are: `Long`, `Float`, `Double`, `BigInt`. */ def product[A1 >: A](implicit num: Numeric[A1]): A1 @@ -348,7 +350,9 @@ trait GenTraversableOnce[+A] extends Any { * @return the smallest element of this $coll with respect to the ordering `cmp`. * * @usecase def min: A - * @return the smallest element of this $coll + * @inheritdoc + * + * @return the smallest element of this $coll */ def min[A1 >: A](implicit ord: Ordering[A1]): A @@ -359,7 +363,9 @@ trait GenTraversableOnce[+A] extends Any { * @return the largest element of this $coll with respect to the ordering `cmp`. * * @usecase def max: A - * @return the largest element of this $coll. + * @inheritdoc + * + * @return the largest element of this $coll. */ def max[A1 >: A](implicit ord: Ordering[A1]): A @@ -387,12 +393,13 @@ trait GenTraversableOnce[+A] extends Any { * Copying will stop once either the end of the current $coll is reached, * or the end of the array is reached. * - * $willNotTerminateInf - * * @param xs the array to fill. * @tparam B the type of the elements of the array. * * @usecase def copyToArray(xs: Array[A]): Unit + * @inheritdoc + * + * $willNotTerminateInf */ def copyToArray[B >: A](xs: Array[B]): Unit @@ -401,13 +408,14 @@ trait GenTraversableOnce[+A] extends Any { * Copying will stop once either the end of the current $coll is reached, * or the end of the array is reached. * - * $willNotTerminateInf - * * @param xs the array to fill. * @param start the starting index. * @tparam B the type of the elements of the array. * * @usecase def copyToArray(xs: Array[A], start: Int): Unit + * @inheritdoc + * + * $willNotTerminateInf */ def copyToArray[B >: A](xs: Array[B], start: Int): Unit @@ -450,15 +458,18 @@ trait GenTraversableOnce[+A] extends Any { def mkString: String /** Converts this $coll to an array. - * $willNotTerminateInf * * @tparam B the type of the elements of the array. A `ClassManifest` for * this type must be available. * @return an array containing all elements of this $coll. * * @usecase def toArray: Array[A] - * @return an array containing all elements of this $coll. - * A `ClassManifest` must be available for the element type of this $coll. + * @inheritdoc + * + * $willNotTerminateInf + * + * @return an array containing all elements of this $coll. + * A `ClassManifest` must be available for the element type of this $coll. */ def toArray[A1 >: A: ClassManifest]: Array[A1] @@ -530,11 +541,13 @@ trait GenTraversableOnce[+A] extends Any { * pair in the map. Duplicate keys will be overwritten by later keys: * if this is an unordered collection, which key is in the resulting map * is undefined. - * $willNotTerminateInf * @return a map containing all elements of this $coll. + * * @usecase def toMap[T, U]: Map[T, U] - * @return a map of type `immutable.Map[T, U]` - * containing all key/value pairs of type `(T, U)` of this $coll. + * @inheritdoc + * $willNotTerminateInf + * @return a map of type `immutable.Map[T, U]` + * containing all key/value pairs of type `(T, U)` of this $coll. */ def toMap[K, V](implicit ev: A <:< (K, V)): GenMap[K, V] } diff --git a/src/library/scala/collection/IterableLike.scala b/src/library/scala/collection/IterableLike.scala index 73d4efe125..fb6d154952 100644 --- a/src/library/scala/collection/IterableLike.scala +++ b/src/library/scala/collection/IterableLike.scala @@ -67,6 +67,7 @@ self => * Subclasses should re-implement this method if a more efficient implementation exists. * * @usecase def foreach(f: A => Unit): Unit + * @inheritdoc */ def foreach[U](f: A => U): Unit = iterator.foreach(f) diff --git a/src/library/scala/collection/Iterator.scala b/src/library/scala/collection/Iterator.scala index d46d215e0c..7b57a91c41 100644 --- a/src/library/scala/collection/Iterator.scala +++ b/src/library/scala/collection/Iterator.scala @@ -322,7 +322,9 @@ trait Iterator[+A] extends TraversableOnce[A] { * @return a new iterator that first yields the values produced by this * iterator followed by the values produced by iterator `that`. * @note Reuse: $consumesTwoAndProducesOneIterator + * * @usecase def ++(that: => Iterator[A]): Iterator[A] + * @inheritdoc */ def ++[B >: A](that: => GenTraversableOnce[B]): Iterator[B] = new AbstractIterator[B] { // optimize a little bit to prevent n log n behavior. @@ -609,7 +611,9 @@ trait Iterator[+A] extends TraversableOnce[A] { * followed by the minimal number of occurrences of `elem` so * that the number of produced values is at least `len`. * @note Reuse: $consumesAndProducesIterator + * * @usecase def padTo(len: Int, elem: A): Iterator[A] + * @inheritdoc */ def padTo[A1 >: A](len: Int, elem: A1): Iterator[A1] = new AbstractIterator[A1] { private var count = 0 @@ -658,7 +662,9 @@ trait Iterator[+A] extends TraversableOnce[A] { * If this iterator is shorter than `that`, `thisElem` values are used to pad the result. * If `that` is shorter than this iterator, `thatElem` values are used to pad the result. * @note Reuse: $consumesTwoAndProducesOneIterator + * * @usecase def zipAll[B](that: Iterator[B], thisElem: A, thatElem: B): Iterator[(A, B)] + * @inheritdoc */ def zipAll[B, A1 >: A, B1 >: B](that: Iterator[B], thisElem: A1, thatElem: B1): Iterator[(A1, B1)] = new AbstractIterator[(A1, B1)] { def hasNext = self.hasNext || that.hasNext @@ -682,7 +688,9 @@ trait Iterator[+A] extends TraversableOnce[A] { * but this is not necessary. * * @note Reuse: $consumesIterator + * * @usecase def foreach(f: A => Unit): Unit + * @inheritdoc */ def foreach[U](f: A => U) { while (hasNext) f(next()) } @@ -1057,15 +1065,17 @@ trait Iterator[+A] extends TraversableOnce[A] { * Copying will stop once either the end of the current iterator is reached, * or the end of the array is reached, or `len` elements have been copied. * - * $willNotTerminateInf - * * @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. * * @note Reuse: $consumesIterator + * * @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 = { var i = start diff --git a/src/library/scala/collection/MapLike.scala b/src/library/scala/collection/MapLike.scala index 07116e99dd..8f88e62791 100644 --- a/src/library/scala/collection/MapLike.scala +++ b/src/library/scala/collection/MapLike.scala @@ -91,14 +91,18 @@ self => * @param kv the key/value pair * @tparam B1 the type of the value in the key/value pair. * @return a new map with the new binding added to this map + * * @usecase def + (kv: (A, B)): Map[A, B] + * @inheritdoc */ def + [B1 >: B] (kv: (A, B1)): Map[A, B1] /** Removes a key from this map, returning a new map. * @param key the key to be removed * @return a new map without a binding for `key` + * * @usecase def - (key: A): Map[A, B] + * @inheritdoc */ def - (key: A): This @@ -115,7 +119,9 @@ self => * @tparam B1 the result type of the default computation. * @return the value associated with `key` if it exists, * otherwise the result of the `default` computation. + * * @usecase def getOrElse(key: A, default: => B): B + * @inheritdoc */ def getOrElse[B1 >: B](key: A, default: => B1): B1 = get(key) match { case Some(v) => v @@ -255,7 +261,9 @@ self => * @param value the value * @tparam B1 the type of the added value * @return A new map with the new key/value mapping added to this map. + * * @usecase def updated(key: A, value: B): Map[A, B] + * @inheritdoc */ def updated [B1 >: B](key: A, value: B1): Map[A, B1] = this + ((key, value)) @@ -269,8 +277,10 @@ self => * @param kvs the remaining key/value pairs * @tparam B1 the type of the added values * @return a new map with the given bindings added to this map + * * @usecase def + (kvs: (A, B)*): Map[A, B] - * @param the key/value pairs + * @inheritdoc + * @param the key/value pairs */ def + [B1 >: B] (kv1: (A, B1), kv2: (A, B1), kvs: (A, B1) *): Map[A, B1] = this + kv1 + kv2 ++ kvs @@ -280,7 +290,9 @@ self => * @param kvs the collection containing the added key/value pairs * @tparam B1 the type of the added values * @return a new map with the given bindings added to this map + * * @usecase def ++ (xs: Traversable[(A, B)]): Map[A, B] + * @inheritdoc */ def ++[B1 >: B](xs: GenTraversableOnce[(A, B1)]): Map[A, B1] = ((repr: Map[A, B1]) /: xs.seq) (_ + _) diff --git a/src/library/scala/collection/SeqLike.scala b/src/library/scala/collection/SeqLike.scala index 526ea7e240..fd1d42d7e9 100644 --- a/src/library/scala/collection/SeqLike.scala +++ b/src/library/scala/collection/SeqLike.scala @@ -410,13 +410,6 @@ trait SeqLike[+A, +Repr] extends Any with IterableLike[A, Repr] with GenSeqLike[ /** Produces a new sequence which contains all elements of this $coll and also all elements of * a given sequence. `xs union ys` is equivalent to `xs ++ ys`. - * $willNotTerminateInf - * - * Another way to express this - * is that `xs union ys` computes the order-presevring multi-set union of `xs` and `ys`. - * `union` is hence a counter-part of `diff` and `intersect` which also work on multi-sets. - * - * $willNotTerminateInf * * @param that the sequence to add. * @tparam B the element type of the returned $coll. @@ -425,14 +418,21 @@ trait SeqLike[+A, +Repr] extends Any with IterableLike[A, Repr] with GenSeqLike[ * @return a new collection of type `That` which contains all elements of this $coll * followed by all elements of `that`. * @usecase def union(that: Seq[A]): $Coll[A] - * @return a new $coll which contains all elements of this $coll - * followed by all elements of `that`. + * @inheritdoc + * + * Another way to express this + * is that `xs union ys` computes the order-presevring multi-set union of `xs` and `ys`. + * `union` is hence a counter-part of `diff` and `intersect` which also work on multi-sets. + * + * $willNotTerminateInf + * + * @return a new $coll which contains all elements of this $coll + * followed by all elements of `that`. */ override def union[B >: A, That](that: GenSeq[B])(implicit bf: CanBuildFrom[Repr, B, That]): That = this ++ that /** Computes the multiset difference between this $coll and another sequence. - * $willNotTerminateInf * * @param that the sequence of elements to remove * @tparam B the element type of the returned $coll. @@ -444,11 +444,15 @@ trait SeqLike[+A, +Repr] extends Any with IterableLike[A, Repr] with GenSeqLike[ * ''n'' times in `that`, then the first ''n'' occurrences of `x` will not form * part of the result, but any following occurrences will. * @usecase def diff(that: Seq[A]): $Coll[A] - * @return a new $coll which contains all elements of this $coll - * except some of occurrences of elements that also appear in `that`. - * If an element value `x` appears - * ''n'' times in `that`, then the first ''n'' occurrences of `x` will not form - * part of the result, but any following occurrences will. + * @inheritdoc + * + * $willNotTerminateInf + * + * @return a new $coll which contains all elements of this $coll + * except some of occurrences of elements that also appear in `that`. + * If an element value `x` appears + * ''n'' times in `that`, then the first ''n'' occurrences of `x` will not form + * part of the result, but any following occurrences will. */ def diff[B >: A](that: GenSeq[B]): Repr = { val occ = occCounts(that.seq) @@ -463,7 +467,6 @@ trait SeqLike[+A, +Repr] extends Any with IterableLike[A, Repr] with GenSeqLike[ def diff[B >: A](that: Seq[B]): Repr = diff(that: GenSeq[B]) /** Computes the multiset intersection between this $coll and another sequence. - * $mayNotTerminateInf * * @param that the sequence of elements to intersect with. * @tparam B the element type of the returned $coll. @@ -475,11 +478,15 @@ trait SeqLike[+A, +Repr] extends Any with IterableLike[A, Repr] with GenSeqLike[ * ''n'' times in `that`, then the first ''n'' occurrences of `x` will be retained * in the result, but any following occurrences will be omitted. * @usecase def intersect(that: Seq[A]): $Coll[A] - * @return a new $coll which contains all elements of this $coll - * which also appear in `that`. - * If an element value `x` appears - * ''n'' times in `that`, then the first ''n'' occurrences of `x` will be retained - * in the result, but any following occurrences will be omitted. + * @inheritdoc + * + * $mayNotTerminateInf + * + * @return a new $coll which contains all elements of this $coll + * which also appear in `that`. + * If an element value `x` appears + * ''n'' times in `that`, then the first ''n'' occurrences of `x` will be retained + * in the result, but any following occurrences will be omitted. */ def intersect[B >: A](that: GenSeq[B]): Repr = { val occ = occCounts(that.seq) diff --git a/src/library/scala/collection/TraversableLike.scala b/src/library/scala/collection/TraversableLike.scala index 0da1cfb913..1f5beb5109 100644 --- a/src/library/scala/collection/TraversableLike.scala +++ b/src/library/scala/collection/TraversableLike.scala @@ -103,10 +103,6 @@ trait TraversableLike[+A, +Repr] extends Any /** Applies a function `f` to all elements of this $coll. * - * Note: this method underlies the implementation of most other bulk operations. - * It's important to implement this method in an efficient way. - * - * * @param f the function that is applied for its side-effect to every element. * The result of function `f` is discarded. * @@ -115,6 +111,11 @@ trait TraversableLike[+A, +Repr] extends Any * 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 @@ -165,17 +166,6 @@ trait TraversableLike[+A, +Repr] extends Any * the resulting collection rather than the left one. * Mnemonic: the COLon is on the side of the new COLlection type. * - * Example: - * {{{ - * scala> val x = List(1) - * x: List[Int] = List(1) - * - * scala> val y = LinkedList(2) - * y: scala.collection.mutable.LinkedList[Int] = LinkedList(2) - * - * scala> val z = x ++: y - * z: scala.collection.mutable.LinkedList[Int] = LinkedList(1, 2) - * }}} * @param that the traversable to append. * @tparam B the element type of the returned collection. * @tparam That $thatinfo @@ -184,9 +174,22 @@ trait TraversableLike[+A, +Repr] extends Any * of this $coll followed by all elements of `that`. * * @usecase def ++:[B](that: TraversableOnce[B]): $Coll[B] - * - * @return a new $coll which contains all elements of this $coll - * followed by all elements of `that`. + * @inheritdoc + * + * Example: + * {{{ + * scala> val x = List(1) + * x: List[Int] = List(1) + * + * scala> val y = LinkedList(2) + * y: scala.collection.mutable.LinkedList[Int] = LinkedList(2) + * + * scala> val z = x ++: y + * z: scala.collection.mutable.LinkedList[Int] = LinkedList(1, 2) + * }}} + * + * @return a new $coll which contains all elements of this $coll + * followed by all elements of `that`. */ def ++:[B >: A, That](that: TraversableOnce[B])(implicit bf: CanBuildFrom[Repr, B, That]): That = { val b = bf(repr) @@ -284,11 +287,12 @@ trait TraversableLike[+A, +Repr] extends Any * The order of the elements is preserved. * * @usecase def filterMap[B](f: A => Option[B]): $Coll[B] + * @inheritdoc * - * @param pf the partial function which filters and maps the $coll. - * @return a new $coll resulting from applying the given option-valued function - * `f` to each element and collecting all defined results. - * The order of the elements is preserved. + * @param pf the partial function which filters and maps the $coll. + * @return a new $coll resulting from applying the given option-valued function + * `f` to each element and collecting all defined results. + * The order of the elements is preserved. def filterMap[B, That](f: A => Option[B])(implicit bf: CanBuildFrom[Repr, B, That]): That = { val b = bf(repr) for (x <- this) @@ -588,8 +592,6 @@ trait TraversableLike[+A, +Repr] extends Any * 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. * - * $willNotTerminateInf - * * @param xs the array to fill. * @param start the starting index. * @param len the maximal number of elements to copy. @@ -597,6 +599,9 @@ trait TraversableLike[+A, +Repr] extends Any * * * @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 @@ -694,10 +699,11 @@ trait TraversableLike[+A, +Repr] extends Any * that satisfies predicate `p` and collecting the results. * * @usecase def map[B](f: A => B): $Coll[B] + * @inheritdoc * - * @return a new $coll resulting from applying the given function - * `f` to each element of the outer $coll that satisfies - * predicate `p` and collecting the results. + * @return a new $coll resulting from applying the given function + * `f` to each element of the outer $coll that satisfies + * predicate `p` and collecting the results. */ def map[B, That](f: A => B)(implicit bf: CanBuildFrom[Repr, B, That]): That = { val b = bf(repr) @@ -710,9 +716,6 @@ trait TraversableLike[+A, +Repr] extends Any * outer $coll containing this `WithFilter` instance that satisfy * predicate `p` and concatenating the results. * - * The type of the resulting collection will be guided by the static type - * of the outer $coll. - * * @param f the function to apply to each element. * @tparam B the element type of the returned collection. * @tparam That $thatinfo @@ -723,11 +726,15 @@ trait TraversableLike[+A, +Repr] extends Any * concatenating the results. * * @usecase def flatMap[B](f: A => TraversableOnce[B]): $Coll[B] + * @inheritdoc + * + * The type of the resulting collection will be guided by the static type + * of the outer $coll. * - * @return a new $coll resulting from applying the given - * collection-valued function `f` to each element of the - * outer $coll that satisfies predicate `p` and concatenating - * the results. + * @return a new $coll resulting from applying the given + * collection-valued function `f` to each element of the + * outer $coll that satisfies predicate `p` and concatenating + * the results. */ def flatMap[B, That](f: A => GenTraversableOnce[B])(implicit bf: CanBuildFrom[Repr, B, That]): That = { val b = bf(repr) @@ -747,6 +754,7 @@ trait TraversableLike[+A, +Repr] extends Any * but this is not necessary. * * @usecase def foreach(f: A => Unit): Unit + * @inheritdoc */ def foreach[U](f: A => U): Unit = for (x <- self) diff --git a/src/library/scala/collection/generic/GenericTraversableTemplate.scala b/src/library/scala/collection/generic/GenericTraversableTemplate.scala index 7333074778..6586434924 100644 --- a/src/library/scala/collection/generic/GenericTraversableTemplate.scala +++ b/src/library/scala/collection/generic/GenericTraversableTemplate.scala @@ -119,22 +119,25 @@ trait GenericTraversableTemplate[+A, +CC[X] <: GenTraversable[X]] extends HasNew * a $coll formed by the elements of these traversable * collections. * - * The resulting collection's type will be guided by the - * static type of $coll. For example: - * - * {{{ - * val xs = List(Set(1, 2, 3), Set(1, 2, 3)) - * // xs == List(1, 2, 3, 1, 2, 3) - * - * val ys = Set(List(1, 2, 3), List(3, 2, 1)) - * // ys == Set(1, 2, 3) - * }}} - * * @tparam B the type of the elements of each traversable collection. * @param asTraversable an implicit conversion which asserts that the element * type of this $coll is a `GenTraversable`. * @return a new $coll resulting from concatenating all element ${coll}s. + * * @usecase def flatten[B]: $Coll[B] + * + * @inheritdoc + * + * The resulting collection's type will be guided by the + * static type of $coll. For example: + * + * {{{ + * val xs = List(Set(1, 2, 3), Set(1, 2, 3)) + * // xs == List(1, 2, 3, 1, 2, 3) + * + * val ys = Set(List(1, 2, 3), List(3, 2, 1)) + * // ys == Set(1, 2, 3) + * }}} */ def flatten[B](implicit asTraversable: A => /*<:<!!!*/ GenTraversableOnce[B]): CC[B] = { val b = genericBuilder[B] diff --git a/src/library/scala/collection/immutable/List.scala b/src/library/scala/collection/immutable/List.scala index 381fcf3117..870c179b2d 100644 --- a/src/library/scala/collection/immutable/List.scala +++ b/src/library/scala/collection/immutable/List.scala @@ -93,8 +93,12 @@ sealed abstract class List[+A] extends AbstractSeq[A] * @param x the element to prepend. * @return a list which contains `x` as first element and * which continues with this list. - * @example `1 :: List(2, 3) = List(2, 3).::(1) = List(1, 2, 3)` + * * @usecase def ::(x: A): List[A] + * @inheritdoc + * + * Example: + * {{{1 :: List(2, 3) = List(2, 3).::(1) = List(1, 2, 3)}}} */ def ::[B >: A] (x: B): List[B] = new scala.collection.immutable.::(x, this) @@ -103,8 +107,12 @@ sealed abstract class List[+A] extends AbstractSeq[A] * @param prefix The list elements to prepend. * @return a list resulting from the concatenation of the given * list `prefix` and this list. - * @example `List(1, 2) ::: List(3, 4) = List(3, 4).:::(List(1, 2)) = List(1, 2, 3, 4)` + * * @usecase def :::(prefix: List[A]): List[A] + * @inheritdoc + * + * Example: + * {{{List(1, 2) ::: List(3, 4) = List(3, 4).:::(List(1, 2)) = List(1, 2, 3, 4)}}} */ def :::[B >: A](prefix: List[B]): List[B] = if (isEmpty) prefix @@ -117,7 +125,9 @@ sealed abstract class List[+A] extends AbstractSeq[A] * * @param prefix the prefix to reverse and then prepend * @return the concatenation of the reversed prefix and the current list. + * * @usecase def reverse_:::(prefix: List[A]): List[A] + * @inheritdoc */ def reverse_:::[B >: A](prefix: List[B]): List[B] = { var these: List[B] = this @@ -137,7 +147,9 @@ sealed abstract class List[+A] extends AbstractSeq[A] * @tparam B the element type of the returned collection. * @return a list resulting from applying the given function * `f` to each element of this list and collecting the results. + * * @usecase def mapConserve(f: A => A): List[A] + * @inheritdoc */ def mapConserve[B >: A <: AnyRef](f: A => B): List[B] = { @tailrec diff --git a/src/library/scala/collection/parallel/ParIterableLike.scala b/src/library/scala/collection/parallel/ParIterableLike.scala index 7e0fa366ab..5551c04ce2 100644 --- a/src/library/scala/collection/parallel/ParIterableLike.scala +++ b/src/library/scala/collection/parallel/ParIterableLike.scala @@ -668,8 +668,9 @@ self: ParIterableLike[T, Repr, Sequential] => * @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] + * @inheritdoc * - * @return a new $coll containing the prefix scan of the elements in this $coll + * @return a new $coll containing the prefix scan of the elements in this $coll */ def scan[U >: T, That](z: U)(op: (U, U) => U)(implicit bf: CanBuildFrom[Repr, U, That]): That = if (bf(repr).isCombiner) { if (tasksupport.parallelismLevel > 1) { diff --git a/src/library/scala/collection/parallel/ParSeqLike.scala b/src/library/scala/collection/parallel/ParSeqLike.scala index 9f28a286ca..b3c527da84 100644 --- a/src/library/scala/collection/parallel/ParSeqLike.scala +++ b/src/library/scala/collection/parallel/ParSeqLike.scala @@ -285,7 +285,6 @@ self => } /** Computes the multiset intersection between this $coll and another sequence. - * $mayNotTerminateInf * * @param that the sequence of elements to intersect with. * @tparam B the element type of the returned $coll. @@ -296,12 +295,17 @@ self => * If an element value `x` appears * ''n'' times in `that`, then the first ''n'' occurrences of `x` will be retained * in the result, but any following occurrences will be omitted. + * * @usecase def intersect(that: Seq[T]): $Coll[T] - * @return a new $coll which contains all elements of this $coll - * which also appear in `that`. - * If an element value `x` appears - * ''n'' times in `that`, then the first ''n'' occurrences of `x` will be retained - * in the result, but any following occurrences will be omitted. + * @inheritdoc + * + * $mayNotTerminateInf + * + * @return a new $coll which contains all elements of this $coll + * which also appear in `that`. + * If an element value `x` appears + * ''n'' times in `that`, then the first ''n'' occurrences of `x` will be retained + * in the result, but any following occurrences will be omitted. */ def intersect[U >: T](that: GenSeq[U]) = sequentially { _ intersect that diff --git a/src/library/scala/xml/parsing/MarkupParser.scala b/src/library/scala/xml/parsing/MarkupParser.scala index 32feaa2209..af9b5f47cf 100755 --- a/src/library/scala/xml/parsing/MarkupParser.scala +++ b/src/library/scala/xml/parsing/MarkupParser.scala @@ -134,7 +134,7 @@ trait MarkupParser extends MarkupParserCommon with TokenTests // /** {{{ - * <? prolog ::= xml S ... ?> + * <? prolog ::= xml S ... ?> * }}} */ def xmlProcInstr(): MetaData = { xToken("xml") @@ -195,7 +195,7 @@ trait MarkupParser extends MarkupParserCommon with TokenTests } /** {{{ - * <? prolog ::= xml S? + * <? prolog ::= xml S? * // this is a bit more lenient than necessary... * }}} */ def prolog(): (Option[String], Option[String], Option[Boolean]) = @@ -355,7 +355,7 @@ trait MarkupParser extends MarkupParserCommon with TokenTests } /** {{{ - * '<! CharData ::= [CDATA[ ( {char} - {char}"]]>"{char} ) ']]>' + * '<! CharData ::= [CDATA[ ( {char} - {char}"]]>"{char} ) ']]>' * * see [15] * }}} */ @@ -369,7 +369,7 @@ trait MarkupParser extends MarkupParserCommon with TokenTests } /** {{{ - * Comment ::= '<!--' ((Char - '-') | ('-' (Char - '-')))* '-->' + * Comment ::= '<!--' ((Char - '-') | ('-' (Char - '-')))* '-->' * * see [15] * }}} */ @@ -399,7 +399,7 @@ trait MarkupParser extends MarkupParserCommon with TokenTests } /** {{{ - * '<' content1 ::= ... + * '<' content1 ::= ... * }}} */ def content1(pscope: NamespaceBinding, ts: NodeBuffer) { ch match { @@ -420,7 +420,7 @@ trait MarkupParser extends MarkupParserCommon with TokenTests } /** {{{ - * content1 ::= '<' content1 | '&' charref ... + * content1 ::= '<' content1 | '&' charref ... * }}} */ def content(pscope: NamespaceBinding): NodeSeq = { var ts = new NodeBuffer @@ -490,7 +490,7 @@ trait MarkupParser extends MarkupParserCommon with TokenTests /** parses document type declaration and assigns it to instance variable * dtd. * {{{ - * <! parseDTD ::= DOCTYPE name ... > + * <! parseDTD ::= DOCTYPE name ... > * }}} */ def parseDTD() { // dirty but fast var extID: ExternalID = null @@ -545,8 +545,8 @@ trait MarkupParser extends MarkupParserCommon with TokenTests } /** {{{ - * '<' element ::= xmlTag1 '>' { xmlExpr | '{' simpleExpr '}' } ETag - * | xmlTag1 '/' '>' + * '<' element ::= xmlTag1 '>' { xmlExpr | '{' simpleExpr '}' } ETag + * | xmlTag1 '/' '>' * }}} */ def element1(pscope: NamespaceBinding): NodeSeq = { val pos = this.pos @@ -778,7 +778,7 @@ trait MarkupParser extends MarkupParserCommon with TokenTests } /** {{{ - * <! attlist := ATTLIST + * <! attlist := ATTLIST * }}} */ def attrDecl() = { xToken("TTLIST") @@ -824,7 +824,7 @@ trait MarkupParser extends MarkupParserCommon with TokenTests } /** {{{ - * <! element := ELEMENT + * <! element := ELEMENT * }}} */ def entityDecl() = { var isParameterEntity = false diff --git a/test/scaladoc/resources/code-indent.scala b/test/scaladoc/resources/code-indent.scala new file mode 100644 index 0000000000..88946ffc7f --- /dev/null +++ b/test/scaladoc/resources/code-indent.scala @@ -0,0 +1,37 @@ +/** + * This is an example of indented comments: + * {{{ + * a typicial indented + * comment on multiple + * comment lines + * }}} + * {{{ one liner }}} + * {{{ two lines, one useful + * }}} + * {{{ + * line1 + * line2 + * line3 + * line4}}} + * {{{ + * a ragged example + * a (condition) + * the t h e n branch + * an alternative + * the e l s e branch + * }}} + * NB: Trailing spaces are necessary for this test! + * {{{ + * l1 + * + * l2 + * + * l3 + * + * l4 + * + * l5 + * }}} + + */ +class C diff --git a/test/scaladoc/scala/html/HtmlFactoryTest.scala b/test/scaladoc/scala/html/HtmlFactoryTest.scala index 67358e6e70..7550faa536 100644 --- a/test/scaladoc/scala/html/HtmlFactoryTest.scala +++ b/test/scaladoc/scala/html/HtmlFactoryTest.scala @@ -671,6 +671,23 @@ object Test extends Properties("HtmlFactory") { // traits E, F and H shouldn't crash scaladoc but we don't need to check the output ) + property("Indentation normalization for code blocks") = { + val files = createTemplates("code-indent.scala") + + files("C.html") match { + case node: scala.xml.Node => { + val s = node.toString + s.contains("<pre>a typicial indented\ncomment on multiple\ncomment lines</pre>") && + s.contains("<pre>one liner</pre>") && + s.contains("<pre>two lines, one useful</pre>") && + s.contains("<pre>line1\nline2\nline3\nline4</pre>") && + s.contains("<pre>a ragged example\na (condition)\n the t h e n branch\nan alternative\n the e l s e branch</pre>") && + s.contains("<pre>l1\n\nl2\n\nl3\n\nl4\n\nl5</pre>") + } + case _ => false + } + } + { val files = createTemplates("basic.scala") //println(files) |