Add documentation to @deprecated

4 files changed, 101 insertions, 21 deletions

diff --git a/src/library/scala/deprecated.scala b/src/library/scala/deprecated.scala
index e940a4bfbe..7338dffb8d 100644
--- a/src/library/scala/deprecated.scala
+++ b/src/library/scala/deprecated.scala
@@ -11,11 +11,52 @@ package scala
 import scala.annotation.meta._
 
 /** An annotation that designates that a definition is deprecated.
- *  Access to the member then generates a deprecated warning.
+ *  A deprecation warning is issued upon usage of the annotated definition.
  *
+ *  Library authors should state the library's deprecation policy in their documentation to give
+ *  developers guidance on how long a deprecated definition will be preserved.
+ *
+ *  Library authors should prepend the name of their library to the version number to help
+ *  developers distinguish deprecations coming from different libraries:
+ *
+ *  {{{
+ *  @deprecated("this method will be removed", "FooLib 12.0")
+ *  def oldMethod(x: Int) = ...
+ *  }}}
+ *
+ *  The compiler will emit deprecation warnings grouped by library and version:
+ *
+ *  {{{
+ *  oldMethod(1)
+ *  oldMethod(2)
+ *  aDeprecatedMethodFromBarLibrary(3, 4)
+ *
+ *  // warning: there were two deprecation warnings (since FooLib 12.0)
+ *  // warning: there was one deprecation warning (since BarLib 3.2)
+ *  // warning: there were three deprecation warnings in total; re-run with -deprecation for details
+ *  }}}
+ *
+ *  A deprecated element of the Scala language or a definition in the Scala standard library will
+ *  be preserved or at least another major version.
+ *
+ *  This means that an element deprecated since 2.12 will be preserved in 2.13 and will very likely
+ *  not be part of 2.14, though sometimes a deprecated element might be kept for more than a major
+ *  release to ease migration and upgrades from older Scala versions.<br/>
+ *  Developers should not rely on this.
+ *
+ *  @note The Scala team has decided to enact a special deprecation policy for the 2.12 release:<br/>
+ *
+ *        As an upgrade from Scala 2.11 to Scala 2.12 also requires upgrading from Java 6 to Java 8,
+ *        no deprecated elements will be removed in this release to ease migration and upgrades
+ *        from older Scala versions.
+ *
+ *  @see    The official documentation on [[http://www.scala-lang.org/news/2.11.0/#binary-compatibility binary compatibility]].
  *  @param  message the message to print during compilation if the definition is accessed
  *  @param  since   a string identifying the first version in which the definition was deprecated
  *  @since  2.3
+ *  @see    [[scala.deprecatedInheritance]]
+ *  @see    [[scala.deprecatedOverriding]]
+ *  @see    [[scala.deprecatedName]]
  */
 @getter @setter @beanGetter @beanSetter
 class deprecated(message: String = "", since: String = "") extends scala.annotation.StaticAnnotation
diff --git a/src/library/scala/deprecatedInheritance.scala b/src/library/scala/deprecatedInheritance.scala
index 7614a96f95..b85d07b0bd 100644
--- a/src/library/scala/deprecatedInheritance.scala
+++ b/src/library/scala/deprecatedInheritance.scala
@@ -11,12 +11,28 @@ package scala
 /** An annotation that designates that inheriting from a class is deprecated.
  *
  *  This is usually done to warn about a non-final class being made final in a future version.
- *  Sub-classing such a class then generates a warning. No warnings are generated if the
- *  subclass is in the same compilation unit.
+ *  Sub-classing such a class then generates a warning.
+ *
+ *  No warnings are generated if the subclass is in the same compilation unit.
+ *
+ *  {{{
+ *  @deprecatedInheritance("this class will be made final", "2.12")
+ *  class Foo
+ *  }}}
+ *
+ *  {{{
+ *  val foo = new Foo     // no deprecation warning
+ *  class Bar extends Foo
+ *  // warning: inheritance from class Foo is deprecated (since 2.12): this class will be made final
+ *  // class Bar extends Foo
+ *  //                   ^
+ *  }}}
  *
  *  @param  message the message to print during compilation if the class was sub-classed
  *  @param  since   a string identifying the first version in which inheritance was deprecated
  *  @since  2.10
+ *  @see    [[scala.deprecated]]
  *  @see    [[scala.deprecatedOverriding]]
+ *  @see    [[scala.deprecatedName]]
  */
 class deprecatedInheritance(message: String = "", since: String = "") extends scala.annotation.StaticAnnotation
diff --git a/src/library/scala/deprecatedName.scala b/src/library/scala/deprecatedName.scala
index da8b76efc9..e2322f0363 100644
--- a/src/library/scala/deprecatedName.scala
+++ b/src/library/scala/deprecatedName.scala
@@ -10,23 +10,27 @@ package scala
 
 import scala.annotation.meta._
 
-/**
- * An annotation that designates the name of the parameter to which it is
- * applied as deprecated. Using that name in a named argument generates
- * a deprecation warning.
- *
- * For instance, evaluating the code below in the Scala interpreter
- * {{{
- *   def inc(x: Int, @deprecatedName('y) n: Int): Int = x + n
- *   inc(1, y = 2)
- * }}}
- * will produce the following output:
- * {{{
- * warning: there were 1 deprecation warnings; re-run with -deprecation for details
- * res0: Int = 3
- * }}}
- *
- * @since 2.8.1
- */
+
+ /** An annotation that designates that the name of a parameter is deprecated.
+  *
+  *  Using this name in a named argument generates a deprecation warning.
+  *
+  *  For instance, evaluating the code below in the Scala interpreter (with `-deprecation`)
+  *  {{{
+  *  def inc(x: Int, @deprecatedName('y, "2.12") n: Int): Int = x + n
+  *  inc(1, y = 2)
+  *  }}}
+  *  will produce the following warning:
+  *  {{{
+  *  warning: the parameter name y is deprecated (since 2.12): use n instead
+  *  inc(1, y = 2)
+  *           ^
+  *  }}}
+  *
+  *  @since  2.8.1
+  *  @see    [[scala.deprecated]]
+  *  @see    [[scala.deprecatedInheritance]]
+  *  @see    [[scala.deprecatedOverriding]]
+  */
 @param
 class deprecatedName(name: Symbol = Symbol("<none>"), since: String = "") extends scala.annotation.StaticAnnotation
diff --git a/src/library/scala/deprecatedOverriding.scala b/src/library/scala/deprecatedOverriding.scala
index 26a9d9ee7d..ee887db220 100644
--- a/src/library/scala/deprecatedOverriding.scala
+++ b/src/library/scala/deprecatedOverriding.scala
@@ -12,9 +12,28 @@ package scala
  *
  *  Overriding such a member in  a sub-class then generates a warning.
  *
+ *  {{{
+ *  class Foo {
+ *    @deprecatedOverriding("this method will be made final", "2.12")
+ *    def add(x: Int, y: Int) = x + y
+ *  }
+ *  }}}
+ *
+ *  {{{
+ *  class Bar extends Foo // no deprecation warning
+ *  class Baz extends Foo {
+ *    override def add(x: Int, y: Int) = x - y
+ *  }
+ *  // warning: overriding method add in class Foo is deprecated (since 2.12): this method will be made final
+ *  // override def add(x: Int, y: Int) = x - y
+ *  //              ^
+ *  }}}
+ *
  *  @param  message the message to print during compilation if the member was overridden
  *  @param  since   a string identifying the first version in which overriding was deprecated
  *  @since  2.10
+ *  @see    [[scala.deprecated]]
  *  @see    [[scala.deprecatedInheritance]]
+ *  @see    [[scala.deprecatedName]]
  */
 class deprecatedOverriding(message: String = "", since: String = "") extends scala.annotation.StaticAnnotation