idea使用帮助文档5（注释）

注释＃ 

IntelliJ IDEA允许您查看任何两个文件，文件夹，文本源或数据库对象之间的差异，以及本地文件与其存储库版本之间的差异。

在Java中，有一组内置注释。最重要的是，IntelliJ IDEA提供了一组注释，可作为 单独的项目使用。您可以将它们添加到类路径中并在代码中使用。

将org.jetbrains.annotations添加到Gradle或Maven项目＃ 

1. 要将带注释的库添加到Gradle项目，请将compile 'org.jetbrains:annotations:16.0.2'依赖项添加 到build.gradle文件。

2. 对于Maven项目，将org.jetbrains:annotations:16.0.2依赖项添加到pom.xml。

将org.jetbrains.annotations添加到其他项目＃ 

1. 1. 打开“ 项目结构”对话框（Ctrl+Shift+Alt+S）并选择“ 库”。

2. 2. 单击，然后选择From Maven。

3. 3. 在搜索字段中，键入org.jetbrains:annotations:16.0.2是否使用JDK 1.8或更高版本。对于JDK 1.5,1.6或1.7，请键入org.jetbrains:annotations-java5:16.0.2。

4. 4. 单击确定。

在编辑器中添加org.jetbrains.annotations ＃ 

您还可以使用意图操作启用注释。

1. 1. 例如，在编辑器中键入注释，@NotNull然后按Alt+Enter：

   

    

2. 2. 从列表中，选择“ 添加'注释”到类路径。

   IDE将提示您从Maven下载带有注释的库。

该annotations神器需要JDK 1.8或更高版本。如果使用JDK 1.5,1.6或1.7编译项目，请改用annotations-java5 工件。

JetBrains注释＃ 

有关JetBrains注释的更多信息，请参阅GitHub上的 JetBrains注释页面

• - 所述@Nls注释指示一个注释的代码元素是需要本地化字符串。

• - 该@NonNls注解表明一个注释的代码元素是一个字符串，它是用户不可见，它并不需要本地化，并且它不包含需要本地化的字符串。当您使用注释元素时@NonNls，本地化工具将跳过此元素和其中的字符串。

• - 该@PropertyKey注释表明，方法参数接受参数必须是在一个特定的资源包有效的属性键。当字符串文字不是包中的属性键作为参数传递时，IntelliJ IDEA会将其突出显示为错误。注释还用于在作为参数传递的字符串文字中提供完成。

• - 所述@TestOnly注释指示的方法或构造必须从只测试代码被调用。

• - 该@Contract批注，可以指定一组规则（合同），一个方法必须遵循。如果违反合同，IntelliJ IDEA会报告问题。

• - 所述@Nullable注释指示的变量，参数，或返回值，该值可以为空。

• - 所述@NotNull注释指示的变量，参数，或回不能为空值。

@Nullable和@NotNull ＃ 

@Nullable和@NotNull注释允许您检查变量，参数或返回值的可为空性。它们可以帮助您控制整个方法层次结构中的合同，如果IntelliJ IDEA发现合同被违反，它将报告检测到的问题，并指向NullPointerException可能出现的代码。

例如，如果您创建一个参数具有@NotNull注释的方法，然后使用可能为null的参数调用此方法，IntelliJ IDEA将动态突出显示该问题。

 

检查由Constant条件和例外以及 @NotNull / @Nullable问题检查完成。您可以在“ 设置/首选项” （Ctrl+Alt+S）对话框中配置这些检查的工作方式。转到编辑| 检查| Java | 可能的错误。

编译项目时，IDE会将断言添加到使用注释注释的所有方法和参数 @NotNull。如果在@NotNull预期的代码中传递null，则断言将失败。您可以在“ 设置/首选项”对话框中禁用此选项并配置注释列表 Ctrl+Alt+S。转到 构建，执行，部署| 编译器。

 

@Nullable ＃ 

该@Nullable注释帮助您检测：

• 可以返回null的方法调用

• 变量（字段，局部变量和参数），可以为null

@Nullable在父 方法中使用注释的方法可以在子类方法中具有注释@Nullable 或@NotNull注释。

该@Nullable父方法参数的注释需要 @Nullable在子类中的方法参数注解。

@NotNull ＃ 

该@NotNull注释是，实际上，一个明确的合同，宣布：

• 方法不应返回null

• 变量（字段，局部变量和参数）不能包含空值

如果违反这些合同，IntelliJ IDEA会发出警告。

该@NotNull父方法的注释需要@NotNull的子类方法的注释。

与方法@NotNull在父类的方法参数的注释可以有 @Nullable或@NotNull注释（或没有人）在子类方法的参数。

@Contract ＃ 

该@Contract注解用于定义一个方法必须满足的合同。这使IDE可以在调用已注释方法的方法中发现问题。您不仅可以使用此批注来注释自己的代码，还可以用于其他现有库。

该@Contract批注有两个属性- value和pure。该value属性包含描述参数与返回值之间的因果关系的子句。

该pure属性适用于不更改其对象状态但只返回新值的方法。如果未使用其返回值，则删除其调用不会影响程序状态或更改语义，除非方法调用抛出异常（异常不被视为副作用）。

如果方法本身不产生副作用，则不应将其标记为纯，但可以使用该方法在另一个线程中的事件之间建立事先发生的关系，以便在另一个线程中执行的更改在当前可见调用此方法后的线程。另一方面，一些同步方法可以标记为纯，因为这里同步的目的是保持集合内部完整性而不是等待另一个线程中的事件。允许不会影响重要程序语义的“不可见”副作用（例如日志记录）。

合同是一组描述输入和输出的子句。它们用->符号分隔 ："A -> B"。这形成了一个契约意味着当你向一个方法提供A时，你将总是得到B.合同中的条款必须用;（分号）符号分隔。例如：

@Contract("_, null -> null")	null如果第二个参数是，则返回该方法null。
@Contract("_, null -> null; _, !null -> !null")	null如果第二个参数是null，则返回该方法，否则返回null。
@Contract("true -> fail")	传递给它assertFalse()的异常抛出异常的典型方法true。
@Contract("_ -> this")	该方法始终返回其限定符（例如StringBuilder.append）。
@Contract("null -> fail; _ -> param1")	如果第一个参数为null，则该方法抛出异常，否则返回第一个参数（例如，Objects.requireNonNull）。
@Contract("!null, _ -> param1; null, !null -> param2; null, null -> fail")	该方法返回第一个非null参数，如果两个参数都为null，则抛出异常（例如，Objects.requireNonNullElse在Java 9中）。

定义Contract＃ 

1. 按Alt+Enter方法，然后选择 添加方法合同或编辑方法合同。

2. 配置合同并应用更改。

   

    

语法＃ 

该@Contract标注值的语法如下：

contract ::= (clause ‘;’)* clause
clause ::= args ‘->’ effect
args ::= ((arg ‘,’)* arg )?
arg ::= value-constraint
value-constraint ::= ‘_’ | ‘null’ | ‘!null’ | ‘false’ | ‘true’
effect ::= ‘_’ | ‘null’ | ‘!null’ | ‘false’ | ‘true’ | ‘fail’ | ‘new’ | ‘this’ | ‘param’ number
number ::= [1-9] [0-9]*

限制是：

_	任何价值
null	空值
!null	静态证明值不为空
true	真布尔值
false	假布尔值
fail	如果参数满足参数约束，则该方法抛出异常
new	每次执行该方法时，它都会返回一个非null的新对象，该对象与方法执行之前存在于堆中的其他对象不同。如果方法是纯的，则新对象不存储在任何字段或数组中，如果未使用方法返回值，则会丢失该对象。
this	该方法返回非null this引用
param1 (param2, param3, and so on)	该方法返回其第一个（第二个，第三个，等等）参数

@ParametersAreNonnullByDefault ＃ 

该@ParametersAreNonnullByDefault注释可以帮助你定义一个类或包中的所有方法的参数有@NotNull语义，除非明确与注解 @Nullable注释。

所述@ParametersAreNonnullByDefault注释可以与一个包，类，或方法中。

要使用注释，请将jsr305库添加到模块依赖项：

1. 打开Project Structure对话框（Ctrl+Shift+Alt+S），然后转到Modules | 依赖性。

2. 单击添加， 然后选择库| Java。

3. 在IntelliJ IDEA主目录中，选择lib \ jsr305.jar。

4. （可选）在下一个对话框中，您可以修改库名称和级别。

5. 应用更改并关闭对话框。

将JAR添加到项目后，即可开始使用@ParametersAreNonnullByDefault注释。例如，请考虑以下代码：

 

public static <T extends Comparable<T>> List<T> sort(List<T> list)
{
if(list != null){
List<T> copy = new ArrayList<T>(list);
sort(copy);
return copy;
}
else {
return null;
}
}

如果使用注释sort()方法@ParametersAreNonnullByDefault，IntelliJ IDEA会立即识别该if语句是无关紧要的，并报告始终为真的条件。

但是，如果将方法的参数注释sort()为可为空，则不会显示任何检查消息。

 

推断无效＃ 

IntelliJ IDEA中的可空性分析可以扫描您的代码并 为您的代码添加@Nullable和@NotNull注释。该分析可帮助您检测代码中的合同违规，并尽可能建议进行空检查。

运行可空性分析＃ 

1. 从主菜单中，选择Analyze | 推断无效。

   如果您尚未将带注释的库添加到类路径，IntelliJ IDEA将提示您从Maven下载它。

2. 在Specify Infer Nullity Scope对话框中，选择分析范围。如果要包含测试源并注释局部变量，请选中相应的复选框。

3. 单击确定。

   如果需要，IntelliJ IDEA会为注释添加import语句，并注释参数和变量。

推断注释＃ 

IntelliJ IDEA扫描SDK和库中的字节码，@Nullable并@NotNull自动推断和 注释。您可以稍后使用这些注释来分析源代码，以找出忽略null的位置。

默认情况下启用推断注释。

在编辑器中，推断的注释用 阴沟图标标记。

 

显示内联的推断注释＃ 

您可以将IDE配置为在代码中显示推断的注释。

1. 按Ctrl+Alt+S打开“ 设置/首选项”对话框，然后转到“ 编辑器”| 一般| 外观。

2. 选中“在线显示推断的注释”复选框。

3. 应用更改并关闭对话框。

   

外部注释＃ 

在源代码中存储注释并不总是方便的。例如，如果您在团队中处理项目，其中每个人都使用不同的IDE，如果您使用库类，或者您只是想让代码免于注释。这是您可以使用外部注释的时候。

外部注释是常规注释，存储在源代码之外的名为annotations.xml的XML文件中。

在代码中，外部注释使用装订线图标标记，并以灰色突出显示。默认情况下，IntelliJ IDEA在编辑器中显示外部注释。

 

启用外部注释＃ 

要使用外部注释，您需要在设置中启用此选项。如果跳过此步骤，则可以在外部注释库代码，但是您将无法在源代码中使用外部注释。

1. 按下Ctrl+Alt+S打开“ 设置/首选项”对话框。

2. 转到编辑| 代码风格| Java | 代码生成并选择 使用外部注释复选框。

3. 应用更改并关闭对话框。

在外部做一个注释＃ 

• 要将常规注释快速转换为外部注释，请将光标放在其上并按 Alt+Enter（或单击意图操作 图标），然后选择 外部注释。

添加新注释＃ 

1. 按下Alt+Enter要注释的元素（或单击意图操作 图标）。

2. 选择Annotate  （例如，Annotate field 'out'），然后选择注释。

   

   如果只能使用一个注释，请选择Annotate 作为@ 选项（例如，Annotate class 'String' as @Deprecated）。

3. 在下一个对话框中，单击“ 外部添加”。

4. 指定要使用外部注释存储文件的目录（外部注释根目录）。

   此模块中的每个下一个外部注释都将存储在同一文件夹中。如果您有多个注释根，IntelliJ IDEA将询问您使用哪一个。

配置注释根目录＃ 

注释根目录是一个文件夹，用于存储项目当前模块中使用的外部注释。您可以更改，删除和添加新根：

1. 按Ctrl+Shift+Alt+S以打开“ 项目结构”对话框。

2. 转到模块| 路径。

3. 找到“ 外部注释”区域，您可以在其中管理附加到模块的外部注释。

也可以在项目级别配置注释。在“ 项目结构”对话框中，单击“ SDK”| 注释。

隐藏外部注释＃ 

默认情况下，外部注释显示在编辑器中。您可以在代码中隐藏它们：

1. 按，Ctrl+Alt+S然后选择编辑器| 一般| 外观。

2. 清除“ 显示内联外部注释”复选框。

3. 应用更改并关闭对话框。

隐藏外部注释时，只有 装订线中的图标标记它们在代码中的存在。

从Maven下载外部注释＃ 

• 您可以将外部注释存储为Maven工件，并将它们与库一起下载。为此，请从Maven Repository对话框的“ 下载库”中选择“ 注释”复选框。

IntelliJ IDEA将使用annotations分类器搜索所有工件，并在存储库中可用时下载它们。