pycharm """:return:""" in a Python documentation string

Question

When you use Pycharm to edit a py file, it inserts a template like this.

def check_caller_log():
    """
    xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    :return: 
    """

What's the purpose of :return: here?

python automatic documentation? like https://docs.python.org/3/library/pydoc.html#module-pydoc — Jean-François Fabre, May 10 '17 at 08:48
Possible duplicate of [What is the standard Python docstring format?](http://stackoverflow.com/questions/3898572/what-is-the-standard-python-docstring-format) — tripleee, May 10 '17 at 08:58

score 5 · Accepted Answer · edited Apr 30 '18 at 21:19

It describes the type of what your function returns (for example if it returns a string, you write return: str). Also you can add a comment about what this return value contains or what its purpose is.

def my_function():
    """
    Some good explanation of what this function does

    :return: str
    """

Note: If your function doesn't return anything, it actually returns None and you can write it down: return: None

def my_function():
    """
    Some good explanation of what this function does

    :return: None
    """

Pont · Answer 2 · 2020-06-18T13:23:11.440

As stefan.stt's answer says, the :return: field lets you provide a description of the fuction's return value. However, stefan.stt's example shows the :return: being used to document the return type rather than to describe the value. To document the type, it's more usual to use the :rtype: field, thus:

def user_name():
    """
    Description of the function goes here.

    :return: the name of the currently active user
    :rtype: str
    """

The field names are not fully standardized, and :returns: is also widely used to document the return value; it's my impression that :returns: is the more commonly used of the two synonyms, but PyCharm's "Python Integrated Tools" has standardized on :return:. The widely used Python documentation generator Sphinx supports both variants, but other documentation tools may not.

It's also worth noting that there are several different syntaxes in use to document parameters, return values, etc. in Python docstrings. The most common ones are documented in this answer.

pycharm """:return:""" in a Python documentation string

2 Answers2