23.2. Umieszczanie adnotacji w kodzie

Plik AnnotatedCode.scala zawiera przykład kodu, który został oznakowany różnymi adnotacjami zdefiniowanymi w pliku CodeAnnotations.scala.

Plik AnnotatedCode.scala:
@author(AnnotatedCode.authorName) 
@version(major=1,minor=0) 
object AnnotatedCode {
  final val authorName = "Grzegorz Balcerek" 
  private[this] val commentText = "needs to be a var"
  @todo @fixme @comment(commentText) val num1 = 2 
  val num2 = num1*2 : @comment("is this value correct?") 
  def hello(@fixme("unnecessary parameter") x: Int = 3) = "hello!" 
  val size: Int @fixme("change to Long") = commentText.length 
}

Adnotacje umieszczamy w kodzie poprzedzając ich nazwę znakiem @. Po tym znaku umieszczamy nazwę adnotacji. Opcjonalnie, możemy po nazwie adnotacji umieścić parametry w nawiasach okrągłych. Adnotacje mogą być umieszczane przy definicjach, deklaracjach, typach i wyrażeniach. Adnotacje umieszcza się przed definicjami i deklaracjami (jak w wierszach , , i ), natomiast za typami i wyrażeniami (jak w wierszach i ), przy czym w przypadku wyrażeń dodatkowo oddziela się je od wyrażenia znakiem dwukropka (wiersz ). W każdym ze wspomnianych przypadków można w kodzie umieścić więcej, niż jedną adnotację, przy czym ich kolejność nie ma znaczenia.

W przypadku adnotacji dziedziczących z ClassfileAnnotation, podając wartości argumentów adnotacji należy korzystać z notacji dotyczącej parametrów nazwanych. Jednak w przypadku adnotacji z jednym parametrem, którego nazwą jest value, wartość tego parametru można podać za pomocą argumentu pozycyjnego (nazwę parametru można pominąć). W taki sposób podana jest wartość adnotacji author z wiersza . Argumenty adnotacji dziedziczących z ClassfileAnnotation muszą być wyrażeniami stałymi.

Stałe są opisane w punkcie 5.15.

Wszystkie umieszczone w pliku AnnotatedCode.scala adnotacje są prawidłowe składniowo i umieszczone w miejscach dozwolonych przez kompilator. Program kompiluje się bez błędów i ostrzeżeń.

$ scalac AnnotatedCode.scala

$

Program z pliku WronglyAnnotatedCode.scala nie kompiluje się. Powodem jest nieprawidłowe użycie kilku adnotacji.

Plik WronglyAnnotatedCode.scala:
@version(1,2)  
@version(major = WronglyAnnotatedCode.m1, minor = WronglyAnnotatedCode.m2)  
object WronglyAnnotatedCode {
  final val m1 = 1
  val m2 = 2
  @comment def f() {}  
}

Adnotacja version z wiersza ma argumenty pozycyjne zamiast nazwanych. Adnotacja z wiersza ma argument, który nie jest stałą. Adnotacja comment z wiersza jest użyta bez wymaganego argumentu.

$ scalac WronglyAnnotatedCode.scala
WronglyAnnotatedCode.scala:1: error: classfile annotation arguments have to be supplied as named arguments
@version(1,2)
         ^
WronglyAnnotatedCode.scala:1: error: classfile annotation arguments have to be supplied as named arguments
@version(1,2)
           ^
WronglyAnnotatedCode.scala:1: error: annotation version is missing argument major
@version(1,2)
 ^
WronglyAnnotatedCode.scala:2: error: annotation argument needs to be a constant; found: WronglyAnnotatedCode.m2
@version(major = WronglyAnnotatedCode.m1, minor = WronglyAnnotatedCode.m2)
                                                                       ^
WronglyAnnotatedCode.scala:6: error: not enough arguments for constructor comment: (comment: String)comment.
Unspecified value parameter comment.
  @comment def f() {}
   ^
5 errors found

Specyfikacja języka Scala opisuje adnotacje w rozdziale 11, typy oznaczone adnotacją w punkcie 3.2.6, a wyrażenia oznaczone adnotacją w punkcie 6.14.