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

1 files changed, 4 insertions, 2 deletions

diff --git a/src/library/scala/throws.scala b/src/library/scala/throws.scala
index 0aa0d31c9f..02dffb00b0 100644
--- a/src/library/scala/throws.scala
+++ b/src/library/scala/throws.scala
@@ -14,7 +14,7 @@ package scala
  * {{{
  * class Reader(fname: String) {
  *   private val in = new BufferedReader(new FileReader(fname))
- *   @throws(classOf[IOException])
+ *   @throws[IOException]("if the file doesn't exist")
  *   def read() = in.read()
  * }
  * }}}
@@ -23,4 +23,6 @@ package scala
  * @version 1.0, 19/05/2006
  * @since   2.1
  */
-class throws(clazz: Class[_]) extends scala.annotation.StaticAnnotation
+class throws[T <: Throwable](cause: String = "") extends scala.annotation.StaticAnnotation {
+  def this(clazz: Class[T]) = this()
+}