Create documentation comments

Last modified: 28 September 2023

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 .

  3. Add meaningful description of parameters and return values.

tip

Mind the following:

  • Generation of docstrings on pressing 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, PyCharm will correspondingly update the tag in documentation comment.

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 to show the available intention actions.

  3. Choose Insert documentation string stub:

    Intention action: Insert documentation stub

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

Example of a Python documentation comment

Consider the following function:

def handle(self, myParam1, myParam2):

Open settings and navigate to Tools | Python Integrated Tools.

In the Docstring format dropdown, select Epytext:

Changing the type of docstrings

Then type the opening triple double-quotes and press or . PyCharm generates a documentation comment stub in Epytext format:

"""

@param self:
@param myParam1:
@param myParam2:
@return:
"""

Go back to the Python Integrated Tools page in settings () and switch Docstring format to reStructuredText. Then type the opening triple double-quotes and press or . PyCharm generates a documentation comment stub in reStructuredText format:

"""

:param self:
:param myParam1:
:param myParam2:
:return:
"""

You can use markup for text formatting, as well as substitutions, bulleted lists, links, code blocks, and tables:

Example of text formatting in a function docstring

See also

Procedures

Reference

External Links