java 注解 document,注解基础 · Java 8 Document Translation · 看云

注解的格式

-

以最简单的形式，注解如下所示：

```java

@Entity

```

符号字符(`@`)向编译器表明后面的内容是一个注解。在以下示例中，注解的名称是`Override`：

```java

@Override

void mySuperMethod() { ... }

```

注解可以包含可以命名或未命名的元素，以及这些元素的值：

```java

@Author(

name = "Benjamin Franklin",

date = "3/27/2003"

)

class MyClass() { ... }

```

或

```java

@SuppressWarnings(value = "unchecked")

void myMethod() { ... }

```

如果只有一个名为`value`的元素，则名称可以省略，如下所示：

```java

@SuppressWarings("unchecked")

void myMethod() { ... }

```

如果注解没有元素，那么可以省略括号，如前面的`@Override`示例所示。

也可以在同一个声明中使用多个注解：

```java

@Author(name = "Jane Doe")

@EBook

class MyClass { ... }

```

如果注解具有相同的类型，则称为重复注解：

```java

@Author(name = "Jane Doe")

@Author(name = "John Smith")

class MyClass { ... }

```

从Java SE 8发行版开始支持重复注解。有关更多信息，请参阅[`重复注解`]()。

注解类型可以是在Java SE API的`java.lang`或`java.lang.annotation`包中定义的类型之一。在前面的示例中，`Override`和`SuppressWarnings`是[`预定义的Java注解`]()。也可以定义您自己的注解类型。上例中的`Author `和`Ebook `注解是自定义注解类型。

可以使用注释的地方

-

注解可以应用于声明：类，字段，方法和其他程序元素的声明。在声明中使用时，每个注解通常按照惯例出现在其自己的行上。

从Java SE 8发行版开始，注解也可以应用于类型的使用。这里有些例子：

* 类实例创建表达式：

```java

new @Interned MyObject();

```

* 类型转换：

```java

myString = (@NonNull String) str;

···

* `implements`子句

```java

class UnmodifiableList implements

@Readonly List { ... }

```

* 抛出的异常声明：

```java

void monitorTemperature() throws

@Critical TemperatureException { ... }

```

这种形式的注释称为类型注释。有关更多信息，请参阅[`类型注解和可插拔类型系统`]()。