IntelliJ IDEA 2016.3 Help

Documenting Source Code in IntelliJ IDEA

In this part:

Basics

IntelliJ IDEA provides convenient features for creating documentation comments.

Documentation comments in your source code are available for the Quick Documentation Lookup and open for review on pressing Ctrl+Q.

In Java files, IntelliJ IDEA creates stubs of documentation comments on typing the opening tag and pressing Enter.

If this feature applies to the methods, @param tags are created for each parameter declared in the method signature, @return tag is created if the method is not void, and @throws tags are created for each exception statement.

When you create additional tags, IntelliJ IDEA provides code completion that suggests the possible tag names.

If a certain tag has multiple values, the same code completion provides the list of available values. Smart type code completion suggests the list of classes that are appropriate for the specific exception.

Python documentation

The following features are only supported, when Python plugin is installed!

Documentation comments can be created in accordance with the syntax, selected in the Python Integrated Tools page of the Settings/Preferences dialog, for example, reStructuredText or epytext.
If this feature applies to a function, IntelliJ IDEA generates tags, depending on the selected docstring format, for example:

  • For reStructuredText: :param tags for each parameter declared in the function signature, and :return tag.
  • For epytext: @param tags for each parameter declared in the function signature, and @return tag.

So doing, the tags in reStructuredText and epytext markup are highlighted accordingly.

If configured, the documentation comment stubs can be generated with type and rtype tags.

In the Python files, IntelliJ IDEA recognizes the documentation comments represented as Python docstrings.

Before you start, make sure that the required docstring format, for example, epytext or reStructuredText, is selected in the Python Integrated Tools page of the Settings/Preferences dialog.

Also note that IntelliJ IDEA captures custom roles from conf.py. When configuring the directory that contains *.rst files, point to the directory with conf.py (Python Integrated Tools | Path to the directory with *.rst files).

The following features are only supported, when Ruby plugin is installed!

RDoc support

RDoc tags are completed:

/help/img/idea/2016.3/rm_doc_comment_tags.png

RDoc highlighting in documentation comments can be enabled or disabled. To enable it, select the check box Highlight RDoc and ruby syntax in comments in the Appearance page of the editor settings.

YARD support

YARD tags are completed:

/help/img/idea/2016.3/rm_doc_comment_tags_yard.png
  • YARD directives complete in places where methods could be defined;
  • Type annotations complete where applicable (assignments, before block vars);
  • param/return/etc. tags complete before methods, inside directive docstrings, before attr_reader/writer/accessor

HEREDOC support

Besides documentation comments in the RDoc and YARD formats, IntelliJ IDEA supports HEREDOCS. This is especially useful, if you are writing large blocks of text.

For example, consider the following:

/help/img/idea/2016.3/rm_heredoc.png

If you perform run, the lines between <<-HEREDOC and HEREDOC appear in the Run tool window.

See Also

Last modified: 7 December 2016