From e6a60a05a11ca365f3cd58d3ec4de92de1d86cde Mon Sep 17 00:00:00 2001 From: Lukas Rytz Date: Tue, 15 Mar 2011 14:09:47 +0000 Subject: improved documentation for annotations in scala... improved documentation for annotations in scala.annotation.target. closes #4250, no review. --- .../scala/annotation/target/beanGetter.scala | 40 +------------ .../scala/annotation/target/beanSetter.scala | 40 +------------ src/library/scala/annotation/target/field.scala | 40 +------------ src/library/scala/annotation/target/getter.scala | 40 +------------ src/library/scala/annotation/target/package.scala | 68 ++++++++++++++++++++++ src/library/scala/annotation/target/param.scala | 40 +------------ src/library/scala/annotation/target/setter.scala | 40 +------------ 7 files changed, 74 insertions(+), 234 deletions(-) create mode 100644 src/library/scala/annotation/target/package.scala (limited to 'src/library') 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 -- cgit v1.2.3