IntelliJ IDEA 2018.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 simply 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 icons gutter extAnnotation gutter icon and are highlighted with grey. By default, IntelliJ IDEA displays external annotations in the editor.

external annotations

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 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, place the cursor on it and press Alt+Enter (or click the intention action icons actions intentionBulb 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 icons actions intentionBulb icon).

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

    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 icons gutter extAnnotation icon in the gutter marks their presence in code.

Last modified: 25 October 2018

See Also