diff options
22 files changed, 84 insertions, 42 deletions
diff --git a/src/compiler/scala/tools/cmd/gen/AnyVals.scala b/src/compiler/scala/tools/cmd/gen/AnyVals.scala index 842851b4f6..e78589908c 100644 --- a/src/compiler/scala/tools/cmd/gen/AnyVals.scala +++ b/src/compiler/scala/tools/cmd/gen/AnyVals.scala @@ -111,8 +111,8 @@ import scala.language.implicitConversions""" " */"), Op(">>", "/**\n" + - " * Returns this value bit-shifted left by the specified number of bits,\n" + - " * filling in the right bits with the same value as the left-most bit of this.\n" + + " * Returns this value bit-shifted right by the specified number of bits,\n" + + " * filling in the left bits with the same value as the left-most bit of this.\n" + " * The effect of this is to retain the sign of the value.\n" + " * @example {{{\n" + " * -21 >> 3 == -3\n" + diff --git a/src/compiler/scala/tools/nsc/ast/DocComments.scala b/src/compiler/scala/tools/nsc/ast/DocComments.scala index 6d9b41ec45..02a199f7ac 100755 --- a/src/compiler/scala/tools/nsc/ast/DocComments.scala +++ b/src/compiler/scala/tools/nsc/ast/DocComments.scala @@ -59,14 +59,21 @@ trait DocComments { self: Global => comment.defineVariables(sym) } + + def replaceInheritDocToInheritdoc(docStr: String):String = { + docStr.replaceAll("""\{@inheritDoc\p{Zs}*\}""", "@inheritdoc") + } + /** The raw doc comment of symbol `sym`, minus usecase and define sections, augmented by * missing sections of an inherited doc comment. * If a symbol does not have a doc comment but some overridden version of it does, * the doc comment of the overridden version is copied instead. */ def cookedDocComment(sym: Symbol, docStr: String = ""): String = cookedDocComments.getOrElseUpdate(sym, { - val ownComment = if (docStr.length == 0) docComments get sym map (_.template) getOrElse "" + var ownComment = if (docStr.length == 0) docComments get sym map (_.template) getOrElse "" else DocComment(docStr).template + ownComment = replaceInheritDocToInheritdoc(ownComment) + superComment(sym) match { case None => if (ownComment.indexOf("@inheritdoc") != -1) diff --git a/src/library/scala/Option.scala b/src/library/scala/Option.scala index 905e925f57..66900e7258 100644 --- a/src/library/scala/Option.scala +++ b/src/library/scala/Option.scala @@ -211,6 +211,17 @@ sealed abstract class Option[+A] extends Product with Serializable { /** Tests whether the option contains a given value as an element. * + * @example {{{ + * // Returns true because Some instance contains string "something" which equals "something". + * Some("something") contains "something" + * + * // Returns false because "something" != "anything". + * Some("something") contains "anything" + * + * // Returns false when method called on None. + * None contains "anything" + * }}} + * * @param elem the element to test. * @return `true` if the option has an element that is equal (as * determined by `==`) to `elem`, `false` otherwise. @@ -251,6 +262,17 @@ sealed abstract class Option[+A] extends Product with Serializable { * nonempty '''and''' `pf` is defined for that value. * Returns $none otherwise. * + * @example {{{ + * // Returns Some(HTTP) because the partial function covers the case. + * Some("http") collect {case "http" => "HTTP"} + * + * // Returns None because the partial function doesn't cover the case. + * Some("ftp") collect {case "http" => "HTTP"} + * + * // Returns None because None is passed to the collect method. + * None collect {case value => value} + * }}} + * * @param pf the partial function. * @return the result of applying `pf` to this $option's * value (if possible), or $none. diff --git a/src/library/scala/PartialFunction.scala b/src/library/scala/PartialFunction.scala index 7f4a9dc45d..fba759eb32 100644 --- a/src/library/scala/PartialFunction.scala +++ b/src/library/scala/PartialFunction.scala @@ -20,6 +20,11 @@ package scala * {{{ * val f: PartialFunction[Int, Any] = { case _ => 1/0 } * }}} + * + * It is the responsibility of the caller to call `isDefinedAt` before + * calling `apply`, because if `isDefinedAt` is false, it is not guaranteed + * `apply` will throw an exception to indicate an error condition. If an + * exception is not thrown, evaluation may result in an arbitrary value. * * The main distinction between `PartialFunction` and [[scala.Function1]] is * that the user of a `PartialFunction` may choose to do something different diff --git a/src/library/scala/Predef.scala b/src/library/scala/Predef.scala index faeb1dcbe2..7f717aa6e4 100644 --- a/src/library/scala/Predef.scala +++ b/src/library/scala/Predef.scala @@ -303,7 +303,7 @@ object Predef extends LowPriorityImplicits with DeprecatedPredef { @inline implicit def augmentString(x: String): StringOps = new StringOps(x) @inline implicit def unaugmentString(x: StringOps): String = x.repr - // printing and reading ----------------------------------------------- + // printing ----------------------------------------------------------- def print(x: Any) = Console.print(x) def println() = Console.println() diff --git a/src/library/scala/StringContext.scala b/src/library/scala/StringContext.scala index 20a328ec8f..2632994a34 100644 --- a/src/library/scala/StringContext.scala +++ b/src/library/scala/StringContext.scala @@ -38,7 +38,7 @@ import scala.annotation.tailrec * To provide your own string interpolator, create an implicit class * which adds a method to `StringContext`. Here's an example: * {{{ - * implicit class JsonHelper(val sc: StringContext) extends AnyVal { + * implicit class JsonHelper(private val sc: StringContext) extends AnyVal { * def json(args: Any*): JSONObject = ... * } * val x: JSONObject = json"{ a: $a }" diff --git a/src/library/scala/collection/GenMapLike.scala b/src/library/scala/collection/GenMapLike.scala index 4e7d359251..bce9740522 100644 --- a/src/library/scala/collection/GenMapLike.scala +++ b/src/library/scala/collection/GenMapLike.scala @@ -102,7 +102,7 @@ trait GenMapLike[A, +B, +Repr] extends GenIterableLike[(A, B), Repr] with Equals */ def mapValues[C](f: B => C): GenMap[A, C] - /** Compares two maps structurally; i.e. checks if all mappings + /** Compares two maps structurally; i.e., checks if all mappings * contained in this map are also contained in the other map, * and vice versa. * diff --git a/src/library/scala/collection/TraversableOnce.scala b/src/library/scala/collection/TraversableOnce.scala index a8c4e047ab..13cd99d910 100644 --- a/src/library/scala/collection/TraversableOnce.scala +++ b/src/library/scala/collection/TraversableOnce.scala @@ -75,7 +75,7 @@ trait TraversableOnce[+A] extends Any with GenTraversableOnce[A] { // at least indirectly. Currently, these are `ArrayOps` and `StringOps`. // It is also implemented in `TraversableOnce[A]`. /** A version of this collection with all - * of the operations implemented sequentially (i.e. in a single-threaded manner). + * of the operations implemented sequentially (i.e., in a single-threaded manner). * * This method returns a reference to this collection. In parallel collections, * it is redefined to return a sequential implementation of this collection. In diff --git a/src/library/scala/collection/immutable/Stream.scala b/src/library/scala/collection/immutable/Stream.scala index d3ff5e8abf..37a0b373da 100644 --- a/src/library/scala/collection/immutable/Stream.scala +++ b/src/library/scala/collection/immutable/Stream.scala @@ -469,7 +469,7 @@ self => else super.flatMap(f)(bf) /** Returns all the elements of this `Stream` that satisfy the predicate `p` - * in a new `Stream` - i.e. it is still a lazy data structure. The order of + * in a new `Stream` - i.e., it is still a lazy data structure. The order of * the elements is preserved * * @param p the predicate used to filter the stream. diff --git a/src/library/scala/collection/immutable/StringLike.scala b/src/library/scala/collection/immutable/StringLike.scala index 8e1d950d00..738b294ce6 100644 --- a/src/library/scala/collection/immutable/StringLike.scala +++ b/src/library/scala/collection/immutable/StringLike.scala @@ -121,14 +121,14 @@ self => } /** Return all lines in this string in an iterator, excluding trailing line - * end characters, i.e. apply `.stripLineEnd` to all lines + * end characters, i.e., apply `.stripLineEnd` to all lines * returned by `linesWithSeparators`. */ def lines: Iterator[String] = linesWithSeparators map (line => new WrappedString(line).stripLineEnd) /** Return all lines in this string in an iterator, excluding trailing line - * end characters, i.e. apply `.stripLineEnd` to all lines + * end characters, i.e., apply `.stripLineEnd` to all lines * returned by `linesWithSeparators`. */ @deprecated("Use `lines` instead.","2.11.0") diff --git a/src/library/scala/concurrent/Future.scala b/src/library/scala/concurrent/Future.scala index 4ed0687334..e93a3284dc 100644 --- a/src/library/scala/concurrent/Future.scala +++ b/src/library/scala/concurrent/Future.scala @@ -102,7 +102,7 @@ trait Future[+T] extends Awaitable[T] { /* Callbacks */ - /** When this future is completed successfully (i.e. with a value), + /** When this future is completed successfully (i.e., with a value), * apply the provided partial function to the value if the partial function * is defined at that value. * @@ -118,7 +118,7 @@ trait Future[+T] extends Awaitable[T] { case _ => } - /** When this future is completed with a failure (i.e. with a throwable), + /** When this future is completed with a failure (i.e., with a throwable), * apply the provided callback to the throwable. * * $caughtThrowables diff --git a/src/library/scala/concurrent/duration/Deadline.scala b/src/library/scala/concurrent/duration/Deadline.scala index 61cbe47530..a25a478602 100644 --- a/src/library/scala/concurrent/duration/Deadline.scala +++ b/src/library/scala/concurrent/duration/Deadline.scala @@ -25,15 +25,15 @@ package scala.concurrent.duration */ case class Deadline private (time: FiniteDuration) extends Ordered[Deadline] { /** - * Return a deadline advanced (i.e. moved into the future) by the given duration. + * Return a deadline advanced (i.e., moved into the future) by the given duration. */ def +(other: FiniteDuration): Deadline = copy(time = time + other) /** - * Return a deadline moved backwards (i.e. towards the past) by the given duration. + * Return a deadline moved backwards (i.e., towards the past) by the given duration. */ def -(other: FiniteDuration): Deadline = copy(time = time - other) /** - * Calculate time difference between this and the other deadline, where the result is directed (i.e. may be negative). + * Calculate time difference between this and the other deadline, where the result is directed (i.e., may be negative). */ def -(other: Deadline): FiniteDuration = time - other.time /** diff --git a/src/library/scala/math/BigDecimal.scala b/src/library/scala/math/BigDecimal.scala index bcbed645a7..5a81710986 100644 --- a/src/library/scala/math/BigDecimal.scala +++ b/src/library/scala/math/BigDecimal.scala @@ -617,10 +617,10 @@ extends ScalaNumber with ScalaNumericConversions with Serializable { */ def abs: BigDecimal = if (signum < 0) unary_- else this - /** Returns the sign of this BigDecimal, i.e. + /** Returns the sign of this BigDecimal; * -1 if it is less than 0, - * +1 if it is greater than 0 - * 0 if it is equal to 0 + * +1 if it is greater than 0, + * 0 if it is equal to 0. */ def signum: Int = this.bigDecimal.signum() diff --git a/src/library/scala/math/BigInt.scala b/src/library/scala/math/BigInt.scala index 689fc0c3e1..abc7371d9f 100644 --- a/src/library/scala/math/BigInt.scala +++ b/src/library/scala/math/BigInt.scala @@ -282,10 +282,10 @@ final class BigInt(val bigInteger: BigInteger) extends ScalaNumber with ScalaNum */ def abs: BigInt = new BigInt(this.bigInteger.abs()) - /** Returns the sign of this BigInt, i.e. + /** Returns the sign of this BigInt; * -1 if it is less than 0, - * +1 if it is greater than 0 - * 0 if it is equal to 0 + * +1 if it is greater than 0, + * 0 if it is equal to 0. */ def signum: Int = this.bigInteger.signum() diff --git a/src/library/scala/math/Ordering.scala b/src/library/scala/math/Ordering.scala index d1a4e7c35c..0d7ea8bce2 100644 --- a/src/library/scala/math/Ordering.scala +++ b/src/library/scala/math/Ordering.scala @@ -26,7 +26,7 @@ import scala.language.{implicitConversions, higherKinds} * val pairs = Array(("a", 5, 2), ("c", 3, 1), ("b", 1, 3)) * * // sort by 2nd element - * Sorting.quickSort(pairs)(Ordering.by[(String, Int, Int), Int](_._2) + * Sorting.quickSort(pairs)(Ordering.by[(String, Int, Int), Int](_._2)) * * // sort by the 3rd element, then 1st * Sorting.quickSort(pairs)(Ordering[(Int, String)].on(x => (x._3, x._1))) diff --git a/src/library/scala/math/PartialOrdering.scala b/src/library/scala/math/PartialOrdering.scala index 9e35381528..8d7fc32535 100644 --- a/src/library/scala/math/PartialOrdering.scala +++ b/src/library/scala/math/PartialOrdering.scala @@ -15,17 +15,24 @@ package math * latter. * * A [[http://en.wikipedia.org/wiki/Partial_order partial ordering]] is a - * binary relation on a type `T` that is also an equivalence relation on - * values of type `T`. This relation is exposed as the `lteq` method of - * the `PartialOrdering` trait. This relation must be: + * binary relation on a type `T`, exposed as the `lteq` method of this trait. + * This relation must be: * * - reflexive: `lteq(x, x) == '''true'''`, for any `x` of type `T`. - * - anti-symmetric: `lteq(x, y) == '''true'''` and `lteq(y, x) == true` - * then `equiv(x, y)`, for any `x` and `y` of type `T`. + * - anti-symmetric: if `lteq(x, y) == '''true'''` and + * `lteq(y, x) == '''true'''` + * then `equiv(x, y) == '''true'''`, for any `x` and `y` of type `T`. * - transitive: if `lteq(x, y) == '''true'''` and * `lteq(y, z) == '''true'''` then `lteq(x, z) == '''true'''`, * for any `x`, `y`, and `z` of type `T`. * + * Additionally, a partial ordering induces an + * [[http://en.wikipedia.org/wiki/Equivalence_relation equivalence relation]] + * on a type `T`: `x` and `y` of type `T` are equivalent if and only if + * `lteq(x, y) && lteq(y, x) == '''true'''`. This equivalence relation is + * exposed as the `equiv` method, inherited from the + * [[scala.math.Equiv Equiv]] trait. + * * @author Geoffrey Washburn * @version 1.0, 2008-04-0-3 * @since 2.7 diff --git a/src/library/scala/runtime/ScalaRunTime.scala b/src/library/scala/runtime/ScalaRunTime.scala index 5fb24f2a36..f50059ce54 100644 --- a/src/library/scala/runtime/ScalaRunTime.scala +++ b/src/library/scala/runtime/ScalaRunTime.scala @@ -62,7 +62,7 @@ object ScalaRunTime { } /** Return the class object representing an unboxed value type, - * e.g. classOf[int], not classOf[java.lang.Integer]. The compiler + * e.g., classOf[int], not classOf[java.lang.Integer]. The compiler * rewrites expressions like 5.getClass to come here. */ def anyValClass[T <: AnyVal : ClassTag](value: T): jClass[T] = diff --git a/src/library/scala/sys/Prop.scala b/src/library/scala/sys/Prop.scala index 04c7b5108c..17ae8cb69c 100644 --- a/src/library/scala/sys/Prop.scala +++ b/src/library/scala/sys/Prop.scala @@ -20,7 +20,7 @@ package sys * @since 2.9 */ trait Prop[+T] { - /** The full name of the property, e.g. "java.awt.headless". + /** The full name of the property, e.g., "java.awt.headless". */ def key: String diff --git a/src/library/scala/util/Properties.scala b/src/library/scala/util/Properties.scala index 2daa4de9a6..8835730d95 100644 --- a/src/library/scala/util/Properties.scala +++ b/src/library/scala/util/Properties.scala @@ -107,7 +107,7 @@ private[scala] trait PropertiesTrait { val versionString = "version " + scalaPropOrElse("version.number", "(unknown)") val copyrightString = scalaPropOrElse("copyright.string", "Copyright 2002-2013, LAMP/EPFL") - /** This is the encoding to use reading in source files, overridden with -encoding + /** This is the encoding to use reading in source files, overridden with -encoding. * Note that it uses "prop" i.e. looks in the scala jar, not the system properties. */ def sourceEncoding = scalaPropOrElse("file.encoding", "UTF-8") diff --git a/src/scaladoc/scala/tools/nsc/doc/ScaladocGlobal.scala b/src/scaladoc/scala/tools/nsc/doc/ScaladocGlobal.scala index 2ea3a0eb7c..4b40d25c17 100644 --- a/src/scaladoc/scala/tools/nsc/doc/ScaladocGlobal.scala +++ b/src/scaladoc/scala/tools/nsc/doc/ScaladocGlobal.scala @@ -11,6 +11,7 @@ import reporters.Reporter import typechecker.Analyzer import scala.reflect.internal.util.{ BatchSourceFile, RangePosition } + trait ScaladocGlobalTrait extends Global { outer => diff --git a/src/scaladoc/scala/tools/nsc/doc/Settings.scala b/src/scaladoc/scala/tools/nsc/doc/Settings.scala index a8e1dee4a0..44683f1755 100644 --- a/src/scaladoc/scala/tools/nsc/doc/Settings.scala +++ b/src/scaladoc/scala/tools/nsc/doc/Settings.scala @@ -66,7 +66,7 @@ class Settings(error: String => Unit, val printMsg: String => Unit = println(_)) val docsourceurl = StringSetting ( "-doc-source-url", "url", - "A URL pattern used to build links to template sources; use variables, for example: ?{TPL_NAME} ('Seq'), ?{TPL_OWNER} ('scala.collection'), ?{FILE_PATH} ('scala/collection/Seq')", + s"A URL pattern used to link to the source file; the following variables are available: €{TPL_NAME}, €{TPL_OWNER} and respectively €{FILE_PATH}. For example, for `scala.collection.Seq`, the variables will be expanded to `Seq`, `scala.collection` and respectively `scala/collection/Seq` (without the backquotes). To obtain a relative path for €{FILE_PATH} instead of an absolute one, use the ${sourcepath.name} setting.", "" ) diff --git a/src/scaladoc/scala/tools/nsc/doc/base/CommentFactoryBase.scala b/src/scaladoc/scala/tools/nsc/doc/base/CommentFactoryBase.scala index 19cc27b40b..d5e2f9a2c4 100755 --- a/src/scaladoc/scala/tools/nsc/doc/base/CommentFactoryBase.scala +++ b/src/scaladoc/scala/tools/nsc/doc/base/CommentFactoryBase.scala @@ -131,18 +131,19 @@ trait CommentFactoryBase { this: MemberLookupBase => /** Javadoc tags that should be replaced by something useful, such as wiki * syntax, or that should be dropped. */ private val JavadocTags = - new Regex("""\{\@(code|docRoot|inheritDoc|link|linkplain|literal|value)([^}]*)\}""") + new Regex("""\{\@(code|docRoot|linkplain|link|literal|value)\p{Zs}*([^}]*)\}""") /** Maps a javadoc tag to a useful wiki replacement, or an empty string if it cannot be salvaged. */ - private def javadocReplacement(mtch: Regex.Match): String = mtch.group(1) match { - case "code" => "`" + mtch.group(2) + "`" - case "docRoot" => "" - case "inheritDoc" => "" - case "link" => "`" + mtch.group(2) + "`" - case "linkplain" => "`" + mtch.group(2) + "`" - case "literal" => mtch.group(2) - case "value" => "`" + mtch.group(2) + "`" - case _ => "" + private def javadocReplacement(mtch: Regex.Match): String = { + mtch.group(1) match { + case "code" => "<code>" + mtch.group(2) + "</code>" + case "docRoot" => "" + case "link" => "`[[" + mtch.group(2) + "]]`" + case "linkplain" => "[[" + mtch.group(2) + "]]" + case "literal" => "`" + mtch.group(2) + "`" + case "value" => "`" + mtch.group(2) + "`" + case _ => "" + } } /** Safe HTML tags that can be kept. */ @@ -680,7 +681,6 @@ trait CommentFactoryBase { this: MemberLookupBase => jump("[[") val parens = 2 + repeatJump('[') val stop = "]" * parens - //println("link with " + parens + " matching parens") val target = readUntil { check(stop) || check(" ") } val title = if (!check(stop)) Some({ |