1 files changed, 28 insertions, 19 deletions
diff --git a/src/library/scala/deprecatedName.scala b/src/library/scala/deprecatedName.scala
index 07c5c8925c..f8c6bd32ad 100644
--- a/src/library/scala/deprecatedName.scala
+++ b/src/library/scala/deprecatedName.scala
@@ -10,23 +10,32 @@ 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.
+  *
+  *  Library authors should state the library's deprecation policy in their documentation to give
+  *  developers guidance on how long a deprecated name 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:
+  *
+  *  {{{
+  *  def inc(x: Int, @deprecatedName('y, "FooLib 12.0") n: Int): Int = x + n
+  *  inc(1, y = 2)
+  *  }}}
+  *  will produce the following warning:
+  *  {{{
+  *  warning: the parameter name y is deprecated (since FooLib 12.0): 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) extends scala.annotation.StaticAnnotation
+class deprecatedName(name: Symbol = Symbol("<none>"), since: String = "") extends scala.annotation.StaticAnnotation