SI-6380 #1 Add @throws[Exception]

This change allows an additional notation of the @throws annotation:

  Old-style: @throws(classOf[Exception])
  New-style: @throws[Exception]

The optional String argument moves @throws in line with @deprecated,
@migration, etc. and prevents confusion caused by the default inheritance
of ScalaDoc comments and the non-inheritance of annotations.

  Before: /** This method does ...
            * @throws IllegalArgumentException if `a` is less than 0. */
          @throws(classOf[IllegalArgumentException])
          def foo(a: Int) = ...

  Now:    /** This method does ... */
          @throws[IllegalArgumentException]("if `a` is less than 0")
          def foo(a: Int) = ...

ScalaDoc @throws tags remain supported for cases where documentation of
thrown exceptions is needed, but are not supposed to be added to the
exception attribute of the class file.

In this commit the necessary compiler support is added.
The code to extract exceptions from annotations is now shared instead
of being duplicated all over the place.

The change is completely source and binary compatible, except that the code
is now enforcing that the type thrown is a subtype of Throwable as mandated
by the JVM spec  instead of allowing something like @throws(classOf[String]).

Not in this commit:
  - ScalaDoc support to add the String argument to ScalaDoc's exception list
  - Adaption of the library

2 files changed, 27 insertions, 0 deletions

diff --git a/test/files/run/t6380.check b/test/files/run/t6380.check
new file mode 100644
index 0000000000..912525ed66
--- /dev/null
+++ b/test/files/run/t6380.check
@@ -0,0 +1,7 @@
+List(class java.lang.Exception)
+List(class java.lang.Throwable)
+List(class java.lang.RuntimeException)
+List(class java.lang.IllegalArgumentException, class java.util.NoSuchElementException)
+List(class java.lang.IndexOutOfBoundsException, class java.lang.IndexOutOfBoundsException)
+List(class java.lang.IllegalStateException, class java.lang.IllegalStateException)
+List(class java.lang.NullPointerException, class java.lang.NullPointerException)
diff --git a/test/files/run/t6380.scala b/test/files/run/t6380.scala
new file mode 100644
index 0000000000..0e264d9175
--- /dev/null
+++ b/test/files/run/t6380.scala
@@ -0,0 +1,20 @@
+object Test extends App {
+  classOf[Foo].getDeclaredMethods().sortBy(_.getName).map(_.getExceptionTypes.sortBy(_.getName).toList).toList.foreach(println)
+}
+
+class Foo {
+  @throws[Exception]
+  def bar1 = ???
+  @throws[Throwable]("always")
+  def bar2 = ???
+  @throws(classOf[RuntimeException])
+  def bar3 = ???
+  @throws[IllegalArgumentException] @throws[NoSuchElementException]
+  def bar4 = ???
+  @throws(classOf[IndexOutOfBoundsException]) @throws(classOf[IndexOutOfBoundsException])
+  def bar5 = ???
+  @throws[IllegalStateException]("Cause") @throws[IllegalStateException]
+  def bar6 = ???
+  @throws[NullPointerException]("Cause A") @throws[NullPointerException]("Cause B")
+  def bar7 = ???
+}
\ No newline at end of file