Annotating a class, method, type, class variable, or argument

Gosu annotations are a syntax to provide metadata about a Gosu class, constructor, method, property, field, or parameter. An annotation can control the behavior of the type, the documentation for the type, or the behavior of the code editor.

For example, annotations can indicate what a method returns or what kinds of exceptions the method might throw. You can add custom annotations and read this information at run time.

To add an annotation, type the at sign (@), followed by the annotation name immediately before the declaration of the item to annotate.

For example, the following example declares that a class is deprecated:

@Deprecated
class MyServiceAPI {
  public function myRemoteMethod() {}
}

You can use both annotations that are defined natively in Gosu and also Java annotations.

In your annotation usage, you can use either the fully qualified name of the annotation class or just the name. If you do not use the fully qualified name, add a uses line for that annotation class at the top of the file. For example, the following line shows the uses line for the @Deprecated annotation:

uses java.lang.Deprecated

In some cases, you follow the annotation name with an argument list within parentheses. The following example uses arguments to the annotation to specify that a function might throw a specific exception:

class MyClass{

  @Throws(java.text.ParseException, "If text is invalid format, throws ParseException")
  public function myMethod() {}
}

The annotation may not require any arguments, or the arguments may be optional. If you do not provide arguments to an annotation, you can omit the parentheses. For example, suppose you add an annotation called MyAnnotation that takes no arguments. You could use MyAnnotation in the following, verbose syntax:

@MyAnnotation()

Because there are no arguments, you can optionally omit the parentheses:

@MyAnnotation

Gosu requires argument lists to be in the same format as regular function or method argument lists:

// Standard Gosu argument lists
@Param("str", "The String value to parse")

Gosu annotations optionally support the named arguments calling convention, which includes a colon before the argument name, and commas between arguments:

@Param(:FieldName = "str", :FieldDescription = "The String value to parse")

To get parameter annotations at run time for a Gosu class, get the Java backing class for the Gosu class and use the native Java reflection APIs. For example, the following class defines an add method:

package doc.example

uses doc.example.annotations.MyAnnotation

class MyClass {
  function add (@MyAnnotation a : Integer, b : Integer) : Integer {
    return a + b
  }
}

The following example retrieves the first annotation of the first parameter of the add method:

// Get a reference to an object of that class
var c = new MyClass()

// Get the Java backing class for the Gosu class, using reflection (not type safe)
var cls = c.getClass()

// Get a reference to the method using reflection (not type safe)
var refToMethod = cls.getMethod( "add", {Integer, Integer} )

// Using the native Java API for annotations, get the annotations list
var paramAnnotations = refToMethod.getParameterAnnotations()

// Get the first annotation of the first parameter
var firstAnnotationOnFirstParameter = paramAnnotations[0][0]
print("First annotation on first parameter: " + firstAnnotationOnFirstParameter)