PyCharm 2017.3 Help

Creating Documentation Comments

Creating documentation comments for a method or function

Please note the following:

  • PyCharm 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:
    javadoc smart enter

Creating tags

To create tags in a documentation comment block

  1. In a comment block, select the desired empty line and type @ or: character.
  2. Press Ctrl+Space, or just wait for Code Completion to display the suggestion list:
    py doc comment tags
  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, PyCharm suggests to select the desired parameter name.
    py param completion

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:

function loadDocs(myParam1, myParam2){}

Type the opening documentation comment and press Enter to generate the documentation comment stub:

/** * @param myParam1 * @param myParam2 */

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

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

For Python, PyCharm suggests an inspection Ignore unresolved reference:

py fix doc comment

For JavaScript, PyCharm suggests an intention action UpdateJSDoc comment. You can also press Ctrl+Shift+A, and type the action name:

fix doc comment js

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:
    docstring example 2

    PyCharm 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. PyCharm generates documentation comment stub:

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

Then select reStructuredText, type the opening triple quotes and press Enter or Space. PyCharm generates documentation comment stub:

''' :param self: :param myParam1: :param myParam2: :return: '''
Last modified: 28 March 2018

See Also