Merge pull request #3947 from lrytz/backports

Backporting from 2.12.x to 2.11.x

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({