improved documentation for annotations in scala...

improved documentation for annotations in scala.annotation.target.
closes #4250, no review.

7 files changed, 74 insertions, 234 deletions

diff --git a/src/library/scala/annotation/target/beanGetter.scala b/src/library/scala/annotation/target/beanGetter.scala
index 24697dcc7e..1707a9d258 100644
--- a/src/library/scala/annotation/target/beanGetter.scala
+++ b/src/library/scala/annotation/target/beanGetter.scala
@@ -8,44 +8,6 @@
 package scala.annotation.target
 
 /**
- * For every field of a class, the Scala compiler generates up to four
- * synthetic accessors: getter, setter, bean getter and bean setter.
- * The meta-annotations in package {{{scala.annotation.target}}} are
- * used to control to which of the above members the annotations on
- * the field are copied. By default, field annotations are only added
- * to the actual field, but not to any of the accessors. By annotating
- * the annotation type or the annotation class with one or several of
- * the meta-annotations this behavior can be changed.
- *
- * In the following example, the annotation {{{@Id}}} will be added
- * only to the bean getter {{{getX}}}. In order to annotate the field
- * as well, the meta-annotation {{{@field}}} would need to be added.
- *
- * {{{
- * import javax.persistence.Id
- * class A {
- *   @(Id @beanGetter) @BeanProperty val x = 0
- * }
- * }}}
- *
- * 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
- * }
- * }}}
- *
- * For annotations defined in Scala, a default target can be specified
- * in the annotation class itself, for example
- *
- * {{{
- * @getter
- * class myAnnotation extends Annotation
- * }}}
+ * Consult the documentation in package [[scala.annotation.target]].
  */
 final class beanGetter extends annotation.StaticAnnotation
diff --git a/src/library/scala/annotation/target/beanSetter.scala b/src/library/scala/annotation/target/beanSetter.scala
index 9bb47fcd96..11e95db3cb 100644
--- a/src/library/scala/annotation/target/beanSetter.scala
+++ b/src/library/scala/annotation/target/beanSetter.scala
@@ -8,44 +8,6 @@
 package scala.annotation.target
 
 /**
- * For every field of a class, the Scala compiler generates up to four
- * synthetic accessors: getter, setter, bean getter and bean setter.
- * The meta-annotations in package {{{scala.annotation.target}}} are
- * used to control to which of the above members the annotations on
- * the field are copied. By default, field annotations are only added
- * to the actual field, but not to any of the accessors. By annotating
- * the annotation type or the annotation class with one or several of
- * the meta-annotations this behavior can be changed.
- *
- * In the following example, the annotation {{{@Id}}} will be added
- * only to the bean getter {{{getX}}}. In order to annotate the field
- * as well, the meta-annotation {{{@field}}} would need to be added.
- *
- * {{{
- * import javax.persistence.Id
- * class A {
- *   @(Id @beanGetter) @BeanProperty val x = 0
- * }
- * }}}
- *
- * 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
- * }
- * }}}
- *
- * For annotations defined in Scala, a default target can be specified
- * in the annotation class itself, for example
- *
- * {{{
- * @getter
- * class myAnnotation extends Annotation
- * }}}
+ * Consult the documentation in package [[scala.annotation.target]].
  */
 final class beanSetter extends annotation.StaticAnnotation
diff --git a/src/library/scala/annotation/target/field.scala b/src/library/scala/annotation/target/field.scala
index 3c748ebd23..cd0e5a58b3 100644
--- a/src/library/scala/annotation/target/field.scala
+++ b/src/library/scala/annotation/target/field.scala
@@ -8,44 +8,6 @@
 package scala.annotation.target
 
 /**
- * For every field of a class, the Scala compiler generates up to four
- * synthetic accessors: getter, setter, bean getter and bean setter.
- * The meta-annotations in package {{{scala.annotation.target}}} are
- * used to control to which of the above members the annotations on
- * the field are copied. By default, field annotations are only added
- * to the actual field, but not to any of the accessors. By annotating
- * the annotation type or the annotation class with one or several of
- * the meta-annotations this behavior can be changed.
- *
- * In the following example, the annotation {{{@Id}}} will be added
- * only to the bean getter {{{getX}}}. In order to annotate the field
- * as well, the meta-annotation {{{@field}}} would need to be added.
- *
- * {{{
- * import javax.persistence.Id
- * class A {
- *   @(Id @beanGetter) @BeanProperty val x = 0
- * }
- * }}}
- *
- * 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
- * }
- * }}}
- *
- * For annotations defined in Scala, a default target can be specified
- * in the annotation class itself, for example
- *
- * {{{
- * @getter
- * class myAnnotation extends Annotation
- * }}}
+ * Consult the documentation in package [[scala.annotation.target]].
  */
 final class field extends annotation.StaticAnnotation
diff --git a/src/library/scala/annotation/target/getter.scala b/src/library/scala/annotation/target/getter.scala
index 1697a2a9ce..9363401d35 100644
--- a/src/library/scala/annotation/target/getter.scala
+++ b/src/library/scala/annotation/target/getter.scala
@@ -8,44 +8,6 @@
 package scala.annotation.target
 
 /**
- * For every field of a class, the Scala compiler generates up to four
- * synthetic accessors: getter, setter, bean getter and bean setter.
- * The meta-annotations in package {{{scala.annotation.target}}} are
- * used to control to which of the above members the annotations on
- * the field are copied. By default, field annotations are only added
- * to the actual field, but not to any of the accessors. By annotating
- * the annotation type or the annotation class with one or several of
- * the meta-annotations this behavior can be changed.
- *
- * In the following example, the annotation {{{@Id}}} will be added
- * only to the bean getter {{{getX}}}. In order to annotate the field
- * as well, the meta-annotation {{{@field}}} would need to be added.
- *
- * {{{
- * import javax.persistence.Id
- * class A {
- *   @(Id @beanGetter) @BeanProperty val x = 0
- * }
- * }}}
- *
- * 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
- * }
- * }}}
- *
- * For annotations defined in Scala, a default target can be specified
- * in the annotation class itself, for example
- *
- * {{{
- * @getter
- * class myAnnotation extends Annotation
- * }}}
+ * Consult the documentation in package [[scala.annotation.target]].
  */
 final class getter extends annotation.StaticAnnotation
diff --git a/src/library/scala/annotation/target/package.scala b/src/library/scala/annotation/target/package.scala
new file mode 100644
index 0000000000..454ce46e5c
--- /dev/null
+++ b/src/library/scala/annotation/target/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.target` 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 target
diff --git a/src/library/scala/annotation/target/param.scala b/src/library/scala/annotation/target/param.scala
index 1d5d3791ad..5b917b883f 100644
--- a/src/library/scala/annotation/target/param.scala
+++ b/src/library/scala/annotation/target/param.scala
@@ -8,44 +8,6 @@
 package scala.annotation.target
 
 /**
- * For every field of a class, the Scala compiler generates up to four
- * synthetic accessors: getter, setter, bean getter and bean setter.
- * The meta-annotations in package {{{scala.annotation.target}}} are
- * used to control to which of the above members the annotations on
- * the field are copied. By default, field annotations are only added
- * to the actual field, but not to any of the accessors. By annotating
- * the annotation type or the annotation class with one or several of
- * the meta-annotations this behavior can be changed.
- *
- * In the following example, the annotation {{{@Id}}} will be added
- * only to the bean getter {{{getX}}}. In order to annotate the field
- * as well, the meta-annotation {{{@field}}} would need to be added.
- *
- * {{{
- * import javax.persistence.Id
- * class A {
- *   @(Id @beanGetter) @BeanProperty val x = 0
- * }
- * }}}
- *
- * 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
- * }
- * }}}
- *
- * For annotations defined in Scala, a default target can be specified
- * in the annotation class itself, for example
- *
- * {{{
- * @getter
- * class myAnnotation extends Annotation
- * }}}
+ * Consult the documentation in package [[scala.annotation.target]].
  */
 final class param extends annotation.StaticAnnotation
diff --git a/src/library/scala/annotation/target/setter.scala b/src/library/scala/annotation/target/setter.scala
index 95a882d88a..1c13a796a0 100644
--- a/src/library/scala/annotation/target/setter.scala
+++ b/src/library/scala/annotation/target/setter.scala
@@ -8,44 +8,6 @@
 package scala.annotation.target
 
 /**
- * For every field of a class, the Scala compiler generates up to four
- * synthetic accessors: getter, setter, bean getter and bean setter.
- * The meta-annotations in package {{{scala.annotation.target}}} are
- * used to control to which of the above members the annotations on
- * the field are copied. By default, field annotations are only added
- * to the actual field, but not to any of the accessors. By annotating
- * the annotation type or the annotation class with one or several of
- * the meta-annotations this behavior can be changed.
- *
- * In the following example, the annotation {{{@Id}}} will be added
- * only to the bean getter {{{getX}}}. In order to annotate the field
- * as well, the meta-annotation {{{@field}}} would need to be added.
- *
- * {{{
- * import javax.persistence.Id
- * class A {
- *   @(Id @beanGetter) @BeanProperty val x = 0
- * }
- * }}}
- *
- * 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
- * }
- * }}}
- *
- * For annotations defined in Scala, a default target can be specified
- * in the annotation class itself, for example
- *
- * {{{
- * @getter
- * class myAnnotation extends Annotation
- * }}}
+ * Consult the documentation in package [[scala.annotation.target]].
  */
 final class setter extends annotation.StaticAnnotation