How to document returning tuples in python for Pycharm with docstring

Question

I have seen this question asked all over the internet, but with no answers that seem to work.

def testing_return_documentation(one, two):
    """
    tests documentation of arguments and returns
    :param one: testing
    :param two: another test

    :return: a thing
    """
    return one

Looks like this in Pycharm when you hover over the function:

But how do you document returning a tuple?

def testing_return_documentation(one, two):
    """
    tests documentation of arguments and returns
    :param one: testing
    :param two: another test
    :return: how do you make good things happen here?
    """
    return one, two

Answer 1

In python 3.5 Python added type hinting. Before Python 3.5 existed, there was an open conversation around how to type hint, and it was done in comments. PyCharm supports type hinting in either. I'd recommend doing it the python way for a couple reasons, but it's up to you.

"""These should work"""
from Typing import Tuple

class Foo:
    pass

def foo(a: int, b: float, c: Foo) -> Tuple[int, float, Foo]:
    return a, b, c

def bar(a, b, c) -> Tuple[int, float, Foo]:
    return a, b, c

def that(a, b, c):
    """
    :rtype: Tuple[int, float, Foo]
    """
    return a, b, c

def thing(a, b, c):
    """
    :rtype: (int, float, Foo)
    """
    return a, b, c

"""This should fail because Tuple is not imported, but no warning"""
def that(a, b, c):
    """ 
    :rtype: Tuple[int, float, Foo]
    """
    return a, b, c

"""
This only partially works because 'Foo' isn't in scope. 
This can easily happen if someone refactored the name of 'Foo', 
but the comments wouldn't be updated.
"""
def thing(a, b, c):
    """
    :rtype: (int, float, Foo)
    """
    return a, b, c

def documentation_nightmare(a, b, c):
   """ ​
   There are no checks, and everything seems fine, but the documentation is all wrong and hard to maintain. 
   :param a: A
   :type a: float
   :param b: B
   :type b: Bar
   :param c: C
   :type c: int
   ​:rtype: Tuple[int, float, Foo]
   ​"""
   ​return a, b, c

The main pro of the Python way is.. your code will start to give you type hints and show warnings if you have the wrong types hooked up. If your whole code base is typed then you can run checks to make sure everything is hooked up right. Some people like this, some people don't.

Note, I have done documentation_nightmare before and I hated it. Now I do it with full real typing, and it saves me more time than it costs me, but many people dislike it.

From this SO post:

The complete list of field name can be found here

• param, parameter, arg, argument, key, keyword: Description of a parameter.
• type: Type of a parameter. Creates a link if possible.
• raises, raise, except, exception: That (and when) a specific exception is raised.
• var, ivar, cvar: Description of a variable.
• vartype : Type of a variable. Creates a link if possible.
• returns, return: Description of the return value.
• rtype: Return type. Creates a link if possible.
• meta: Add metadata to description of the python object. The metadata will not be shown on output document. For example, :meta private: indicates the python object is private member. It is used in sphinx.ext.autodoc for filtering members.