IntelliJ IDEA 2019.2 Help

External annotations

Storing annotations in the source code is not always convenient. For example, if you work on a project in a team where everybody uses different IDEs, if you work with library classes, or if you want to keep your code free from annotations. This is when you can use external annotations.

External annotations are regular annotations that are stored outside your source code in an XML file called annotations.xml.

In code, external annotations are marked with the External annotation icon gutter icon and are highlighted with grey. By default, IntelliJ IDEA displays external annotations in the editor.

External annotations in the editor

Enable external annotations

To use external annotations, you need to enable this option in the settings. If you skip this step, you will be able to annotate library code externally, but you will not be able to use external annotation with your source code.

  1. Press Ctrl+Alt+S to open the Settings/Preferences dialog.

  2. Go to Editor | Code Style | Java | Code Generation and select the Use external annotations checkbox.

  3. Apply the changes and close the dialog.

Make an annotation external

  • To quickly convert a regular annotation to an external annotation, position the caret at it and press Alt+Enter (or click the intention action Intention action icon icon), and select Annotate externally.

Add a new annotation

  1. Press Alt+Enter on the element you want to annotate (or click the intention action Intention action icon icon).

  2. Select Annotate <element> <element name> (for example, Annotate field 'out'), and select an annotation.

    Adding a new external annotation

    If there is only one annotation you can use, select the Annotate <element> <element name> as @<Annotation> option (for example, Annotate class 'String' as @Deprecated).

  3. In the next dialog, click Add externally.

  4. Specify a directory where you want to store the file with external annotations (external annotations root).

    Each next external annotation within this module will be stored in the same folder. If you have multiple annotation roots, IntelliJ IDEA will ask you which one to use.

Configure annotations root directory

The annotations root directory is a folder where you store external annotations used in the current module of your project. You can change, remove and add a new root:

  1. Press Ctrl+Shift+Alt+S to open the Project Structure dialog.

  2. Go to Modules | Paths.

  3. Locate the External Annotations area, where you can manage external annotations attached to the module.

Annotations can be configured on the project level as well. While in the Project Structure dialog, click SDKs | Annotations.

Hide external annotations

External annotations are displayed in the editor by default. You can hide them from your code:

  1. Press Ctrl+Alt+S and select Editor | General | Appearance.

  2. Clear the Show external annotations inline checkbox.

  3. Apply the changes and close the dialog.

When external annotations are hidden, only the External annotation icon icon in the gutter marks their presence in code.

Download external annotations from Maven

  • You can store external annotations as Maven artifacts and download them together with a library. To do so, select the Annotations checkbox in the Download library from Maven Repository dialog.

Downloading a library from Maven

IntelliJ IDEA will search for all artifacts with the annotations classifier and download them if they are available in the repository.

Last modified: 17 October 2019