diff options
author | Simon Ochsenreither <simon@ochsenreither.de> | 2016-05-19 18:46:49 +0200 |
---|---|---|
committer | Simon Ochsenreither <simon@ochsenreither.de> | 2016-05-29 06:04:46 +0200 |
commit | 85057d542c7e201191544415ff454afb243aa104 (patch) | |
tree | c146668d5998f03d37a594c9a7ab374fd81272e5 | |
parent | be38ebba3f32816a150012727d3351570718bcf6 (diff) | |
download | scala-85057d542c7e201191544415ff454afb243aa104.tar.gz scala-85057d542c7e201191544415ff454afb243aa104.tar.bz2 scala-85057d542c7e201191544415ff454afb243aa104.zip |
Add documentation to @deprecated
-rw-r--r-- | src/library/scala/deprecated.scala | 43 | ||||
-rw-r--r-- | src/library/scala/deprecatedInheritance.scala | 20 | ||||
-rw-r--r-- | src/library/scala/deprecatedName.scala | 40 | ||||
-rw-r--r-- | src/library/scala/deprecatedOverriding.scala | 19 |
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 |