Moved meta annotations to annotation.meta, plus.

It took me a long time to find a trivial error while adjusting the
annotation packages, so I spent even longer trying to make sure next
time it would take me less time. It's the usual business of eliminating
duplication and unnecessary indirection.

Behavioral note: there was no consistency or deducible reasoning
regarding when annotation checks would be performed against the
typeSymbol directly (thus excluding annotation subclasses) or when they
would do a subclass check. I saw no reason it shouldn't always be a
subclass check; if the annotation isn't supposed to be subclassed it
should be final, and if it is, then the subclasses had probably better
not stop exhibiting the behavior of the base class.

Example: this now draws deprecated warnings, but did not before.

  class bippy extends deprecated("hi mom", "burma shave")

  @bippy def f = 5

(The deprecation message isn't printed so we're not there yet, but
closer.)

There is some new internal documentation on annotations, sadly lacking
in my famous ascii diagrams, and some new conveniences. Review by rytz.

1 files changed, 68 insertions, 0 deletions

diff --git a/src/library/scala/annotation/meta/package.scala b/src/library/scala/annotation/meta/package.scala
new file mode 100644
index 0000000000..2d18ae5dd7
--- /dev/null
+++ b/src/library/scala/annotation/meta/package.scala
@@ -0,0 +1,68 @@
+package scala.annotation
+
+/**
+ * When defining a field, the Scala compiler creates up to four accessors
+ * for it: a getter, a setter, and if the field is annotated with
+ * `@BeanProperty`, a bean getter and a bean setter.
+ *
+ * For instance in the following class definition
+ *
+ * {{{
+ * class C(@myAnnot @BeanProperty var c: Int)
+ * }}}
+ *
+ * there are six entities which can carry the annotation `@myAnnot`: the
+ * constructor parameter, the generated field and the four accessors.
+ *
+ * By default, annotations on (`val`-, `var`- or plain) constructor parameters
+ * end up on the parameter, not on any other entity. Annotations on fields
+ * by default only end up on the field.
+ *
+ * The meta-annotations in package `scala.annotation.meta` are used
+ * to control where annotations on fields and class parameters are copied.
+ * This is done by annotating either the annotation type or the annotation
+ * class with one or several of the meta-annotations in this package.
+ *
+ * ==Annotating the annotation type==
+ *
+ * The target meta-annotations can be put on the annotation type when
+ * instantiating the annotation. In the following example, the annotation
+ * `@Id` will be added only to the bean getter `getX`.
+ *
+ * {{{
+ * import javax.persistence.Id
+ * class A {
+ *   @(Id @beanGetter) @BeanProperty val x = 0
+ * }
+ * }}}
+ *
+ * In order to annotate the field as well, the meta-annotation `@field`
+ * would need to be added.
+ *
+ * The syntax can be improved using a type alias:
+ *
+ * {{{
+ * object ScalaJPA {
+ *   type Id = javax.persistence.Id @beanGetter
+ * }
+ * import ScalaJPA.Id
+ * class A {
+ *   @Id @BeanProperty val x = 0
+ * }
+ * }}}
+ *
+ * ==Annotating the annotation class==
+ *
+ * For annotations defined in Scala, a default target can be specified
+ * in the annotation class itself, for example
+ *
+ * {{{
+ * @getter
+ * class myAnnotation extends Annotation
+ * }}}
+ *
+ * This only changes the default target for the annotation `myAnnotation`.
+ * When instantiating the annotation, the target can still be specified
+ * as described in the last section.
+ */
+package object meta