如何使用 docstring 为 Pycharm 记录 python 中的返回元组

Question

我在互联网上看到过这个问题，但似乎没有有效的答案。

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

    :return: a thing
    """
    return one

当您将鼠标悬停在函数上时，在 Pycharm 中看起来像这样：

但是您如何记录返回元组？

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

在 python 3.5 Python 中添加 type hinting。在 Python 3.5 存在之前，有一个关于如何输入提示的公开对话，并且是在评论中完成的。 PyCharm 都支持类型提示。出于几个原因，我建议使用 python 方式，但这取决于您。

"""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

Python 方法的主要优点是..如果您连接了错误的类型，您的代码将开始为您提供类型提示并显示警告。如果您输入了整个代码库，那么您可以运行检查以确保一切都正确连接。有人喜欢，有人不喜欢。

请注意，我以前做过 documentation_nightmare 但我讨厌它。现在我用完全真实的打字来做，它节省了我更多的时间而不是花费我，但是很多人不喜欢它。

来自所以 post:

可以找到完整的字段名称列表here

param, parameter, arg, argument, key, keyword: 参数说明。
type：参数的类型。如果可能，创建一个 link。
raises, raise, except, exception: 那个（以及什么时候）一个特定的异常被引发了。
var, ivar, cvar: 变量描述。
vartype ：变量的类型。如果可能，创建一个 link。
returns，return：return值的说明。
rtype: Return类型。如果可能，创建一个 link。
meta：将元数据添加到 python 对象的描述中。元数据不会显示在输出文档中。例如，:meta private: 表示 python 对象是私有成员。它在 sphinx.ext.autodoc 中用于过滤成员。

如何使用 docstring 为 Pycharm 记录 python 中的返回元组

How to document returning tuples in python for Pycharm with docstring

docstring

pycharm

python-3.x