Documenting code

Add Javadoc comments

For documentation comments, IntelliJ IDEA provides completion that is enabled by default. Once you type /** before a declaration and press Enter, the IDE auto-completes the doc comment for you. For method comments, the new comment stub contains the required tags (@param tags for each method parameter, @return, or @throws).

If you want to disable completion, in the Settings/Preferences dialog Ctrl+Alt+S, go to Editor | General | Smart Keys, and clear the Insert documentation comment stub checkbox.

Add comments using the Fix doc comment action

Place the caret within a class, method, function, or a field, and press Ctrl+Shift+A.
Type fix doc comment and press Enter.

IntelliJ IDEA adds the missing documentation stub with the corresponding tags.

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

For tags in doc comments, IntelliJ IDEA also provides code completion. Press Ctrl+Space after the @ tag, and select the necessary tag from the suggestion list. If a certain tag has several values, you can select the necessary value from the suggestion list.

Generate a Javadoc reference

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

From the main menu, select Tools | Generate JavaDoc.
In the dialog that opens, select a scope — a set of files or directories for which you want to generate the reference, and set the output directory where the generated documentation will be placed.

The Output directory is a mandatory field: you cannot generate a JavaDoc file as long it is empty.
Use the slider to define the visibility level of members that will be included in the generated documentation. Select one of the following options:
- Private: to include all classes and members to the reference.
- Package: to include all classes and members except the private ones.
- Protected: to include public and protected classes and members.
- Public: to include only public classes and members.
You can specify a locale (for example en_US.UTF-8), command line arguments, and the maximum heap size.
Click OK to generate the reference.

The Specify Generate JavaDoc Scope dialog

The Tools | Generate JavaDoc dialog invokes the JavaDoc utility. The controls of the dialog correspond to the options and tags of this utility.

Item	Description
Generate JavaDoc scope	Use this area to specify the subset of files, folders, and packages for which JavaDoc should be generated. This scope can be the whole project, uncommitted files (when VCS is enabled), current file, custom scope, and so on.
Include test sources	Include documentation comments for test to the generated JavaDoc.
Include JDK and library sources in `-sourcepath`	If this checkbox is selected, then paths to the JDK and library sources will be passed to the JavaDoc utility. Refer to documentation for details.
Include link to JDK documentation	If this checkbox is selected, the references to the classes and packages from JDK will turn into links, which corresponds to using the -link option of the JavaDoc utiity. This checkbox is only enabled when a link to the online documentation is specified in the Documentation Paths tab of the SDK settings. Refer to JavaDoc documentation for details.
Output directory	Specify the fully qualified path to the directory where the generated documentation will be stored. Type the path manually or click and select the location in the dialog. The specified value is passed to the `-d` parameter of the JavaDoc utility. If the specified directory does not exist in your system, you will be prompted to create it. Note that unless the output directory is specified, the OK button is disabled.
Slider	Specify the visibility level of members that you want to include in the generated documentation: Private: select this level to have all classes and members included. The level corresponds to the `-private` JavaDoc parameter. Package: select this level to have all classes and members except private ones included. The level corresponds to the `-package` JavaDoc parameter. Protected: select this level to have only public and protected classes and members included. The level corresponds to the `-protected` JavaDoc parameter. Public: select this level to have only public classes and members included. The level corresponds to the `-public` JavaDoc parameter.
Generate hierarchy tree	Generate the class hierarchy. If this checkbox is cleared, the `-notree` parameter is passed to JavaDoc.
Generate navigator bar	Generate the navigator bar. If this checkbox is cleared, the `-nonavbar` parameter is passed to JavaDoc.
Generate index	Generate the documentation index. If this checkbox is cleared, the `-noindex` parameter is passed to JavaDoc.
Separate index per letter	Generate a separate index file for each letter. If this checkbox is cleared, the `-splitindex` parameter is passed to JavaDoc. The checkbox is available only if the Generate index checkbox is selected.
@use	Document the use of the class and the package. When selected, the checkbox corresponds to the `-use` JavaDoc parameter.
@author	Include the `@author` paragraphs. When selected, the checkbox corresponds to the `-author` JavaDoc parameter.
@version	Include the `@version` paragraphs. When selected, the checkbox corresponds to the `-version` JavaDoc parameter.
@deprecated	Include the `@deprecated` information. When the checkbox is cleared, the `-nodeprecated` parameter is passed to JavaDoc.
deprecated list	Generate the deprecated list. When the checkbox is cleared, the `-nodeprecatedlist` parameter is passed to JavaDoc. The checkbox is available only if the @deprecated checkbox is selected.
Locale	Type the desired locale.
Other command line arguments	Type additional arguments to be passed to JavaDoc. Use the command line syntax.
Maximum heap size (Mb)	Type the maximum heap size in Mb to be used by Java VM for running JavaDoc.
Open generated documentation in browser	Automatically open the generated JavaDoc in a browser.

Last modified: 17 October 2019