IntelliJ IDEA
 
2025.1
Shortcuts: Windows
Get IntelliJ IDEA
  1. Write and edit source code
  2. Javadocs

Javadocs

Last modified: 04 April 2025

Javadoc comments are special comments used to provide a description of the code element located below them. They begin with /** and end with */ and can contain tags marked with @ with specific metadata.

Example of a Javadoc comment

Javadoc is a tool provided by Java to generate HTML documentation from Javadoc comments. You can generate an API reference for your project using the Javadoc tool that comes with your JDK. IntelliJ IDEA provides integration with the tool and allows you to build reference guides right from the IDE.

Learn more about the correct format of Javadocs, style guide, terms and conventions from How to Write Doc Comments for the Javadoc Tool.

tip

Documentation comments are also available in JavaScript, Python, Ruby, PHP, and Kotlin.

Render Javadocs

IntelliJ IDEA allows you to render Javadoc comments in the editor. Rendered comments are easier to read, and they do not overload your code with extra tags.

Click the Toggle Rendered View icon in the gutter next to the necessary documentation comment (or press CtrlAlt0Q) to toggle the rendered view; click the Toggle Rendered View icon to edit the comment.

Javadocs in the editing mode

Rendered Javadoc comments allow you to click links to go to the referenced web pages or view quick documentation for the referenced topics.

To change the font size, right-click a Javadoc comment in the editor and select Adjust Font Size from the context menu. Note that the rendered comments use the same font size as the quick documentation popup.

Render Javadocs by default

You can configure the IDE to always render Javadocs in the editor.

  • Right-click the (the Toggle Rendered View icon icon in the gutter or the Toggle Rendered View icon) and enable the Render All option.

    Alternatively, in the Settings dialog CtrlAlt0S, select Editor | General | Appearance and enable the Render documentation comments option.

To edit rendered Javadocs, click the the Toggle Rendered View icon icon in the gutter next to the comment.

Write Javadoc comments

Add Javadoc comments

Add a Javadoc using automatic comments

For documentation comments, IntelliJ IDEA provides completion enabled by default.

  • Type /** before a declaration and press Enter. The IDE auto-completes the doc comment for you.

You can disable automatic insertion of Javadoc comments: in the Settings dialog CtrlAlt0S, go to Editor | General | Smart Keys, and clear the Insert documentation comment stub checkbox.

Add a Javadoc comment using context actions

  • Place the caret at the declaration in the editor, press AltEnter, and select Add Javadoc from the list.

    Adding a Javadoc using the 'Add Javadoc' context action

note

For method comments, the new comment stub contains the required tags (@param tags for each method parameter, @return, or @throws).

In Kotlin, the @param and other tags are not generated because the recommended style requires incorporating the description of parameters and return values directly into the documentation comment.

tip

For more information about documenting Kotlin code, refer to Kotlin documentation.

Formatting in Javadoc comments

Javadocs support HTML tags and special tags for formatting. Learn more from How to Write Doc Comments for the Javadoc Tool (oracle.com).

Here are some HTML tags:

  • Use <p> for paragraphs.

  • Use <h1>, <h2> and so on for headings.

  • Use <img> to add images, for example: <img src="jb_logo.png"/>.

  • Use <pre> to preserve whitespaces.

  • For lists, use <ul> (unordered), <ol> (ordered), <li> for items in ordered and unordered lists.

Inline Javadoc tags:

  • Use {@code text} to format inline text as code.

  • Use {@literal text} to display special characters like < and >.

  • Use {@link ClassName} to insert a hyperlink to another class or method.

Block Javadoc tags:

  • Use @param name description to describe a method parameter.

  • Use @deprecated reason to mark a method or class as deprecated.

  • Use @author name to specify the author of a class.

Get the complete list of available tags from How to Write Doc Comments for the Javadoc Tool (oracle.com).

Example of a Javadoc comment formatting

Fix Javadocs

If a method signature has been changed, IntelliJ IDEA highlights the tag that does not match the method signature and suggests a quick-fix.

Fix using context actions

  • Place the caret at the tag, press AltEnter, and select an action. You can change the tag or delete it.

    Fix a Javadoc using context actions

Fix using the Fix doc comment action

You can also update an existing Javadoc comment to account for the changes in the declaration using the Fix doc comment action:

  1. Place the caret at the class, method, function, or a field, and press CtrlShift0A.

  2. Type fix doc comment and press Enter.

tip

You can use the Fix doc comment action to add missing documentation stub with the corresponding tags: place the caret within a class, method, or function and invoke the action.

Use custom tags in Javadocs

In Javadocs comments, you can use custom tags on top of the predefined ones. Later on you can include them in your API reference guide.

Recognize custom tags

When you use a custom tag for the first time, the Javadoc declaration problems inspection highlights it in the editor as a wrong tag. To avoid that, add the tag to the list of recognized tags.

  • Place the caret at your custom tag, press AltEnter, and select Add '@tagname' to custom tags.

    Recognize custom tags using context action

  • Alternatively, press CtrlAlt0S to open the IDE settings, select Editor | Inspections. Locate the Javadoc declaration problems inspection in the list and add your tag to the Additional Javadoc tags list.

    Recognize custom tags in settings

Include custom tags in a Javadoc reference

To include your custom tags in an HTML Javadoc reference, add them as command-line arguments.

  1. Go to Tools | Generate JavaDoc and in the Command line arguments field, specify -tag tagname:Xaoptcmf:"taghead".

    Example: -tag location:a:"Development Location:"

    Xaoptcmf determines where in the source code the tag is allowed to be placed. You can use a to allow the tag in all places. Learn more about block tags in Javadocs from the Oracle documentation.

  2. Configure other options as described in Generate a Javadoc reference and generate the reference guide.

    The information from the tag is displayed on the corresponding pages.

    Javadoc reference with custom tags

Generate a Javadoc reference

IntelliJ IDEA provides a utility that enables you to generate a Javadoc reference for your project.

  1. In the main menu, go to Tools | Generate JavaDoc.

  2. In the dialog that opens, select a scope: a set of files or directories for which you want to generate the reference.

  3. In the Output directory, specify the folder to which the generated documentation will be placed.

    note

    The Output directory is a mandatory field: you cannot generate a Javadoc file as long it is empty.

  4. From the Visibility level list, select the visibility level of members that will be included in the generated documentation:

    • Private: include all classes and members. The level corresponds to the -private Javadoc parameter.

    • Package: include all classes and members except the private ones. The level corresponds to the -package Javadoc parameter.

    • Protected: include only public and protected classes and members. The level corresponds to the -protected Javadoc parameter.

    • Public: include only public classes and members. The level corresponds to the -public Javadoc parameter.

  5. You can specify a locale (for example en_US.UTF-8), command line arguments, and the maximum heap size.

  6. Click Generate to generate the reference.

Troubleshoot

javadoc: error – Malformed locale name: en_US.UTF-8

Clear the Locale field. In the Other command line arguments field, add -encoding utf8 -docencoding utf8 -charset utf8.

-encoding specifies the encoding of the source files. -docencoding specifies the encoding of the output HTML files and -charset is the charset specified in the HTML head section of the output files.

Reference: Javadoc code style

You can configure code style for your Javadocs. Press CtrlAlt0S to open settings and then select Editor | Code Style | Java | Javadocs. Configure the options as necessary and use the right part of the dialog to preview the changes.

Learn how to reformat your code from Reformat code.

Item

Description

Alignment

Define the way Javadoc comments should be aligned.

  • Align parameter descriptions: align parameter descriptions against the longest parameter name. Otherwise, the description is separated from the corresponding parameter name by a single space.

  • Align thrown exception descriptions: align thrown exception descriptions against the longest exception name. Otherwise, the description is separated from the exception name by a single space.

Blank lines

Define where blank lines should be inserted in Javadoc comments.

  • After description: automatically insert a blank line after the description section of a Javadoc comment.

  • After parameter descriptions: automatically insert a blank line after the group of @param tags.

  • After return tag :automatically insert a blank line after the @return tag.

Invalid tags

In this area, define whether invalid tags should be preserved or not.

  • Keep invalid tags: preserve the @invalidTag.

  • Keep empty @param tags: preserve the @param tags without the description.

  • Keep empty @return tags: preserve the @return tags without the description.

  • Keep empty @throws tags: preserve the @throws tags without the description.

Other

In this area, specify additional formatting options for Javadoc comments.

  • Enable leading asterisks: start each line of a Javadoc comment with an asterisk.

  • Use @throws rather than @exception: use the @throws tag.

  • Wrap at right margin: wrap the text that exceeds the right margin to the next line.

  • Generate "<p>" on empty lines: automatically insert the </p> tag on an empty line.

  • Keep empty lines: select this checkbox to have manually added empty lines preserved.

  • Do not wrap one line comments: keep short comments on one line with the opening and closing tags.

  • Preserve line feeds: if this checkbox is not selected (by default), line feeds are not preserved on reformatting. This is convenient when comments should be formatted within the boundaries of a paragraph, to occupy minimum space.

    If this checkbox is selected, line feeds will be preserved.

  • Parameter descriptions on new line: place the description of a Javadoc parameter (if any) to a new line. It uses the indent based on the continuation indent value.

  • Indent continuation lines: indent subsequent lines in multiline comments.

Productivity tips

View Javadocs in the editor

In IntelliJ IDEA, you can view external Javadocs for any symbol or method signature right from the editor. To be able to do that, configure library documentation paths or add downloaded documentation to the IDE.

  • Hover over the necessary symbol in the editor.

  • Place the caret at the symbol and press Ctrl0Q (View | Quick Documentation).

    Press Ctrl0Q again to open this documentation in the Documentation tool window.

Learn more from Quick Documentation

See also

Procedures