IntelliJ IDEA 2016.3 Help

Creating Documentation Comments

In this section:

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 Enter.
  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:
    /help/img/idea/2016.3/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 Ctrl+Space, or just wait for Code Completion to display the suggestion list:
    /help/img/idea/2016.3/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 Ctrl+Space after the tag, and select the desired value from the suggestion list. For example, IntelliJ IDEA suggests to select the desired parameter name.
    /help/img/idea/2016.3/code_completion_param.png

Creating and fixing doc comments

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

Press Ctrl+Shift+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 Ctrl+Shift+A, and type the action name:

/help/img/idea/2016.3/fix_doc_comment.png

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 Ctrl+Slash.
  3. Press Ctrl+Space, and choose the desired tag from the suggestion list. Then press Ctrl+Space again, and choose the desired parameter name:
    /help/img/idea/2016.3/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 Alt+Enter, and choose Add @return tag. The documentation comment with the @return tag is created. Specify the return type.
    /help/img/idea/2016.3/ruby_createComment2.png
  • Place the caret at the parameter you want to document, press Alt+Enter, and choose Add @param tag. The documentation comment with the @param tag for the selected parameter is created. Specify the parameter type.
    /help/img/idea/2016.3/ruby_createComment3.png

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 Enter, or Space.
  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 Alt+Enter to show the available intention actions.
  3. Choose Insert documentation string stub:
    /help/img/idea/2016.3/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 Enter 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 Enter 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 Ctrl+Shift+A, in the pop-up frame, type Fill Paragraph, and then press Enter,

Clickable comments

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

To do that, do one of the following:

  • Keep the Ctrl key pressed and hover your mouse pointer over the hyperlink:
    /help/img/idea/2016.3/clickable_link.png
  • Press Ctrl+B.

See Also

Last modified: 21 March 2017