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.

I contacted PyCharm support, and this is what they said:

For tuple please use (<type_1>, <type_2>, <type_3>, e t.c.) syntax.

E.g.:

"""
:rtype: (string, int, int)
"""

This is confirmed in PyCharm's documentation:

Type Syntax

Type syntax in Python docstrings is not defined by any standard. Thus, PyCharm suggests the following notation:

...

• (Foo, Bar) # Tuple of Foo and Bar

Here is how I'd do it:

from typing import Tuple

def func() -> Tuple[int, str]:
    """ (...)

    Returns:
        A tuple containing, respectively, an int (<meaning of the
        returned int>) and a string (<meaning of the returned string>).
    """

PyCharm (and Sphinx, if you're using it to parse your docstrings) will correctly know the return type of your function and you'll have a clean and nice description of the function's return value.

The result is a tuple every times in this case. Write it down like this:

:rtype: (float, numpy.array(float))

If function return value is annotated as tuple[int, dict[string, int]], its documentation is rendered correctly, but there is an issue with inferring type for function()[1]["key"]. Feel free to file an issue in public PyCharm tracker https://youtrack.jetbrains.com/issues/PY.

In Python 3, no wrapper is needed, as the __doc__ attributes of types is writable.

from collections import namedtuple

Point = namedtuple('Point', 'x y')
Point.__doc__ = '''\
A 2-dimensional coordinate

x - the abscissa
y - the ordinate'''

This closely corresponds to a standard class definition, where the docstring follows the header.

class Point():
    '''A 2-dimensional coordinate

    x - the abscissa
    y - the ordinate'''
    <class code>

This does not work in Python 2.

AttributeError: attribute '__doc__' of 'type' objects is not writable.