Reduce deprecations and warnings

1 files changed, 8 insertions, 2 deletions

diff --git a/src/library/scala/deprecatedOverriding.scala b/src/library/scala/deprecatedOverriding.scala
index ee887db220..46639986c0 100644
--- a/src/library/scala/deprecatedOverriding.scala
+++ b/src/library/scala/deprecatedOverriding.scala
@@ -12,9 +12,15 @@ package scala
  *
  *  Overriding such a member in  a sub-class then generates a warning.
  *
+ *  Library authors should state the library's deprecation policy in their documentation to give
+ *  developers guidance on when a method annotated with `@deprecatedOverriding` will be `final`ized.
+ *
+ *  Library authors should prepend the name of their library to the version number to help
+ *  developers distinguish deprecations coming from different libraries:
+ *
  *  {{{
  *  class Foo {
- *    @deprecatedOverriding("this method will be made final", "2.12")
+ *    @deprecatedOverriding("this method will be made final", "FooLib 12.0")
  *    def add(x: Int, y: Int) = x + y
  *  }
  *  }}}
@@ -24,7 +30,7 @@ package scala
  *  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
+ *  // warning: overriding method add in class Foo is deprecated (since FooLib 12.0): this method will be made final
  *  // override def add(x: Int, y: Int) = x - y
  *  //              ^
  *  }}}