Add documentation to @deprecated

1 files changed, 19 insertions, 0 deletions

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