Skip to end of metadata
Go to start of metadata

In Kotlin, one can attach metadata to declarations in the form of annotations. To declare an annotation, put the annotation annotation (no pun intended ) in front of a normal class:

annotation class fancy {}

(Note that, by convention, annotation classes are named with the lowercase fitst letter; the reason will be clear from the examples below.)
Now we can annotate a declaration or an expression with the new fancy annotation. In general, one puts square brackets around the annotation name:

[fancy] class Foo { 
  [fancy] fun baz([fancy] foo : Int) : Int { 
    return [fancy] 1 
  } 
}
Annotations are under development

When annotating a declaration (e.g. a function or a class), the square brackets may be omitted:

fancy class Foo() { 
  fancy fun baz(fancy foo: Int) { 
    return [fancy] 1 
  } 
}

Note that square brackets are required for expressions.

Annotation classes may have constructors that take parameters. For example:

annotation class special(val why : String) 
 
special("example") class Foo {}

As you can see, to pass arguments to an annotation one simply calls its constructor.

On the JVM one can re-use Java annotations:

import org.junit.Test 
import org.junit.Assert.* 
 
class Tests { 
  Test fun simple() { 
    assertEquals(42, getTheAnswer()) 
  } 
}

If you want your Java annotations to look like modifiers, you can rename them on import:

import org.junit.Test as test 
 
class Tests { 
  test fun simple() { 
    ... 
  } 
}
Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.

14 Comments

comments.show.hide

  1. Apr 07, 2012

    Richard Kettelerij

    Are the square brackets necessary? I would prefer one style: brackets are either required or omitted altogether. IMHO having two separate styles makes the code look inconsistent en complices things. Consider the following snippet. The nested/local function(s) require brackets while the member function doesn't. Also notice the difference between properties and expressions.

    annotation class foo { 
    } 
     
    foo class AnnotationTest { 
     
        foo val a : String = "a" 
        foo var b : Int = 1 + 2 
     
        foo fun test(s: String) { 
            [foo] val a : String = "a" 
            [foo] var b : Int = 1 + 2 
     
            [foo] fun testNested() { 
                [foo] fun testNested2() { 
                } 
            } 
     
            [foo] 
            println(s) 
        } 
    }
    Out of curiosity: what's the reason of not adopting the Java/Scala annotation syntax e.g. @foo @bar? Not a big issue, I'm just curious.

    1. Apr 08, 2012

      Andrey Breslav

      > Out of curiosity: what's the reason of not adopting the Java/Scala annotation syntax e.g. @foo @bar? Not a big issue, I'm just curious.
      Reason 1: It's ugly )
      Reason 2 (the real one): we use "@" for something else (qualified this expressions)

      1. Apr 09, 2012

        Richard Kettelerij

        I thought you were planning on dropping the '@' for qualified this expressions. Which brings us back to reason 1 ;-)

  2. Apr 28, 2012

    Mark Platvoet

    Will the Kotlin annotations be interoperable with Java?

    If that's the case I'm curious why there is a preference for a lowercase convention. The reason for preferring the lowercase variant from the examples above isn't that apparent to me.

    1. Apr 28, 2012

      Andrey Breslav

      Yes they will. The convention is motivated by unification with modifiers.

  3. May 02, 2012

    Andy Selvig

    I'm trying to use reflection to retrieve Kotlin annotations on methods at runtime, and running into some issues. Is this feature not yet implemented, or should I file a bug report?

    1. May 02, 2012

      Andrey Breslav

      Please, file a bug report.

      1. May 03, 2012

        Andy Selvig

        Thanks, Andrey. I submitted a bug for the specific issue I saw, but I have some more general questions about how to effectively reflect on annotations. Where's the best place for a discussion like that?

        1. May 03, 2012

          Andrey Breslav

          Our forum (http://devnet.jetbrains.com/community/kotlin) is the best fit

  4. Apr 21, 2013

    Mohammad Shamsi

    Hi,

    can someone give me good example for kotlin annotation usage? 

    - how can i check if an expression (or method call) is annotated by a specific annotation, within my code?

    1. Apr 21, 2013

      Andrey Breslav

      Annotations on expressions are not retained at runtime, they are only good for prospective static checking tools

      1. Apr 21, 2013

        Mohammad Shamsi

        how about classes? 

        given:

        is there any way, i can find if b (or its class) is annotated by foo?  (java version:  isAnnotationPresent(Ann.class) )

        1. Apr 21, 2013

          Hadi Hariri

          Make sure you set the retention policy to runtime:

          Retention(RetentionPolicy.RUNTIME) annotation class ignore

          where ignore is your annotation.

          Then you can use reflection to see if the class has the annotation.

          1. Apr 21, 2013

            Mohammad Shamsi

            so the approach is exactly same as java. no big difference.