On this page:

Creating documentation comments for a method or function

To create a documentation comment for a method or function
  1. Place the caret before the declaration.
  2. Type the opening block comment /**, and press ⏎⏎⏎⏎⏎.
  3. Add meaningful description of parameters and return values.

Please note the following:

  • IntelliJ IDEA checks syntax in the documentation comments and treats it according to the Error settings.
  • If the entered text contains HTML tags, the closing tag will be automatically added after typing >, provided that this behavior is enabled in the editor settings.
  • When typing in a documentation comment, the caret automatically moves to an expected position. For example:

    ../../Shared/javadoc_smart_enter.png

Creating tags

To create tags in a documentation comment block
  1. In a comment block, select the desired empty line and type @ or (for Python and Ruby languages) : character.
  2. Press ⌃Space⌃Space⌃Space⌃Space⌥/, or just wait for Code Completion to display the suggestion list:

    ../../Shared/doc_comment_tags.png

  3. Select a tag from the suggestion list. For example, you can specify the parameters type, or return type.
  4. If a certain tag has several values, press ⌃Space⌃Space⌃Space⌃Space⌥/ after the tag, and select the desired value from the suggestion list. For example, IntelliJ IDEA suggests to select the desired parameter name.

    ../../Shared/code_completion_param.png

Creating and fixing doc comments

Note that this section refers to JavaScript, Java, Python and the other languages that have special beginning of documentation comments.

This section does not refer to Ruby.

Documentation comment can be created with the dedicated action Fix Doc Comment. It can be invoked by means of Find Action command.

Press ⇧⌘A⇧⌘A⌘3⌃⇧A⌃⇧A, with the caret somewhere within a class, method, function, or field, which should be documented, and enter the action name Fix Doc String. The missing documentation stub with the corresponding tags is added. For example: 

/**
*
* @param userInput
* @return
*/
static boolean processRepeatConversion (@NotNull String userInput) {
boolean repeatConversion = false;
if (((userInput.equals("y")) || (userInput.equals("Y")))) {
repeatConversion = true;
}
return repeatConversion;

}

The next case lays with fixing problems in the existing documentation comments.

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

For JavaScript, IntelliJ IDEA suggests an intention action UpdateJSDoc comment. You can also press ⇧⌘A⇧⌘A⌘3⌃⇧A⌃⇧A, and type the action name:

The action Fix doc comment has no keyboard shortcut bound with it. You can configure keyboard shortcut of your own.

../../Shared/fix_doc_comment.png

The following is only valid when Ruby Plugin is installed and enabled!

Creating documentation comments for Ruby methods

To create documentation comments for a ruby method
  1. Place the caret on an empty line before the declaration of the method you want to document.
  2. Type the beginning of a doc comment (#), or just press ⌘/⌘/⌘/⌃/⌥;.
  3. Press ⌃Space⌃Space⌃Space⌃Space⌥/, and choose the desired tag from the suggestion list. Then press ⌃Space⌃Space⌃Space⌃Space⌥/ again, and choose the desired parameter name:

    ../../Shared/ruby_createComment1.png

To create documentation comments for a Ruby method using intention action, do one of the following
  • Place the caret anywhere within the method you want to document, press ⌥⏎⌥⏎⌘1⌥⏎⌥⏎, and choose Add @return tag. The documentation comment with the @return tag is created. Specify the return type.

    ../../Shared/ruby_createComment2.png

  • Place the caret at the parameter you want to document, press ⌥⏎⌥⏎⌘1⌥⏎⌥⏎, and choose Add @param tag. The documentation comment with the @param tag for the selected parameter is created. Specify the parameter type.

    ../../Shared/ruby_createComment3.png

The following is only valid when Python Plugin is installed and enabled!

Creating documentation comments for Python functions

To create documentation comment for a Python function
  1. Place the caret after the declaration of a function you want to document.
  2. Type opening triple quotes, and press ⏎⏎⏎⏎⏎, or Space.

    Mind the following:

    • Generation of docstrings on pressing Space after typing opening triple quotes only works when the checkbox Insert pair quote is cleared in the page Smart Keys of the editor settings.
    • If you rename a parameter of a function, IntelliJ IDEA will correspondingly update the tag in documentation comment.
  3. Add meaningful description of parameters and return values.
To create documentation comment for a Python function using intention action
  1. Place the caret somewhere within the function you want to document.
  2. Press ⌥⏎⌥⏎⌘1⌥⏎⌥⏎ to show the available intention actions.
  3. Choose Insert documentation string stub:

    ../../Shared/docstring_example_2.png

    IntelliJ IDEA generates documentation comment stub according to docstring format, selected in the Python Integrated Tools page.

Example of Python comment

Consider the following function:

def handle(self, myParam1, myParam2):

In the Python Integrated Tools page, select Epytext. Then type the opening triple quotes and press ⏎⏎⏎⏎⏎ or Space. IntelliJ IDEA generates documentation comment stub:

'''
@param self:
@param myParam1:
@param myParam2:
@return:
'''

Then select reStructuredText, type the opening triple quotes and press ⏎⏎⏎⏎⏎ or Space. IntelliJ IDEA generates documentation comment stub:

'''
:param self:
:param myParam1:
:param myParam2:
:return:
'''

Fill Paragraph action

Fill Paragraph action is supported for Java comments. This action creates soft wraps in comments. To make use of this action, follow these steps:

  1. Place the caret somewhere inside a comment in a class.
  2. Do one of the following:
    • On the main menu, choose Edit | Fill Paragraph
    • Press ⇧⌘A⇧⌘A⌘3⌃⇧A⌃⇧A, in the pop-up frame, type Fill Paragraph, and then press ⏎⏎⏎⏎⏎,

Clickable comments

If a documentation comment contains a hyperlink, you can make it clickable.

To do that, do one of the following:

  • Keep the ^ key pressed and hover your mouse pointer over the hyperlink:

    ../../Shared/clickable_link.png

  • Press ⌘B⌘BF3F12⌃⌥G.