Using External Annotations

If you had worked with IntelliJ IDEA for a while, you're most likely aware of @Nullable, @NotNull annotations which allow you to formally specify method contracts and validate whether these contracts are met, and @NonNls annotation which is helpful when you want to exclude strings from the internationalization process. (Read more about contract annotations in IntelliJ IDEA)

However, there're several cases when direct annotating code is not advisable: for example, project is shared between team members that use different IDEs, or you work with library classes. That does not mean you can't make use of these annotations, though – with IntelliJ IDEA you can store annotations outside of the source code.

Let's have a look at how it works. First, we need to open the Settings dialog (Ctrl + Alt + S) and go to Code Style (F), then check the option Use external annotations at the Code Generation tab. Now, add the annotations.jar library to either module or project. You can find it under INTELLIJ_IDEA_HOME/lib folder.

[img_assist|nid=1145|title=|desc=|link=none|align=left|width=494|height=261]

After that, open your current inspection profile and make sure Constant conditions& exceptions inspection is enabled and Suggest @Nullable annotation for methods that may possibly return null option is selected.

At this moment we can enjoy externally annotating methods, fields, parameters, etc. For example, we work on a module that contains a method that might return null.

[img_assist|nid=1146|title=|desc=|link=none|align=left|width=496|height=138]

Let's add annotation – just click the light bulb. IntelliJ IDEA asks whether we want to add annotation in code directly, or store it externally. Select the second option and specify the external annotation root for the current module.

Note: You only select the location for external annotations once, so each next external annotation within this module will be stored in the same folder. Alternatively, you can specify annotations root at any time: open Project Settings dialog and go to the Modules page, then select the needed module and open its Paths tab. There you can find External annotations area, where you can manage external annotations attached to the module.

Now, this method is annotated without placing anything to the source code directly. You can press Ctrl + Q to view the attached annotation.

[img_assist|nid=1147|title=|desc=|link=none|align=left|width=397|height=147]

With external annotations you can even annotate methods within JDK classes.

[img_assist|nid=1148|title=|desc=|link=none|align=left|width=338|height=151]

Just like when you add external annotation on the module level, you can specify the storage location right when you add the annotation, or using Project Settings dialog. In the latter case, open Project Settings dialog, go to JDKs and specify the path in the Annotations tab.