Javadocs
Javadoc comments are usually placed above classes, methods, or fields in your source code. A Javadoc provides a description of the code element located under it and contains block tags marked with @
with specific metadata.
You can generate an API reference for your project in HTML by 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.
For documentation comments, IntelliJ IDEA provides completion that is 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.
Place the caret at the declaration in the editor, press AltEnter, and select Add Javadoc from the list.
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.
If a method signature has been changed, IntelliJ IDEA highlights the tag that does not match the method signature and suggests a quick-fix.
Place the caret at the tag, press AltEnter, and select an action. You can change the tag or delete it.
You can also update an existing Javadoc comment to account for the changes in the declaration using the Fix doc comment action:
Place the caret at the class, method, function, or a field, and press CtrlShift0A.
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.
IntelliJ IDEA allows you to render Javadocs in the editor. Rendered comments are easier to read, and they do not overload your code with extra tags.
Click in the gutter next to the necessary documentation comment (or press CtrlAlt0Q) to toggle the rendered view; click to edit the comment.
Rendered Javadocs 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 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.
You can configure the IDE to always render Javadocs in the editor.
Right-click the ( icon in the gutter or ) 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 icon in the gutter next to the comment.
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.
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.
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.
To include your custom tags in an HTML Javadoc reference, add them as command-line arguments.
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 usea
to allow the tag in all places. Learn more about block tags in Javadocs from the Oracle documentation.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.
IntelliJ IDEA provides a utility that enables you to generate a Javadoc reference for your project.
In the main menu, go to 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.
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.
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.
You can specify a locale (for example
en_US.UTF-8
), command line arguments, and the maximum heap size.Click Generate to generate the reference.
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 |
---|---|
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, recently modified files, 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. For more information, refer to documentation. |
Link to JDK documentation (use -link option) | 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 utility. This checkbox is only enabled when a link to the online documentation is specified in the Documentation Paths tab of the SDK settings. For more information, refer to the Javadoc documentation. |
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
|
Visibility level | Specify the visibility level of members that you want to include in the generated documentation:
|
Generate hierarchy tree | Generate the class hierarchy. If this checkbox is cleared, the |
Generate navigator bar | Generate the navigator bar. If this checkbox is cleared, the |
Generate index | Generate the documentation index. If this checkbox is cleared, the |
Separate index per letter | Generate a separate index file for each letter. If this checkbox is cleared, the 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 |
@author | Include the |
@version | Include the |
@deprecated | Include the |
Deprecated list | Generate the deprecated list. When the checkbox is cleared, the The checkbox is available only if the @deprecated checkbox is selected. |
Locale | Type the required locale. |
Command line arguments | Type additional arguments to be passed to a Javadoc. Use the command line syntax. |
Maximum heap size | 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. |
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.
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.
|
Blank lines | Define where blank lines should be inserted in Javadoc comments.
|
Invalid tags | In this area, define whether invalid tags should be preserved or not.
|
Other | In this area, specify additional formatting options for Javadoc comments.
|
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
Thanks for your feedback!