如何记录python函数参数类型？答案

【问题标题】：How to document python function parameter types?如何记录python函数参数类型？
【发布时间】：2011-12-03 03:55:30
【问题描述】：

我知道参数可以是任何对象，但对于文档而言，指定您所期望的非常重要。

首先是如何指定像下面这样的参数类型？

str（或使用String或string？）
int
list
dict
函数()
tuple
类MyClass的对象实例

其次，如何指定可以是多种类型的参数，例如可以处理单个参数而不是int或str的函数？

请使用以下示例来演示使用您提出的解决方案记录此内容所需的语法。请注意，希望能够从文档内部超链接对“图像”类的引用。

def myMethod(self, name, image):
    """
    Does something ...

    name String: name of the image
    image Image: instance of Image Class or a string indicating the filename.

    Return True if operation succeeded or False.
    """
    return True

注意，只要能够满足要求，欢迎您建议使用任何文档工具（sphinx、oxygen、...）。

更新：

一般来说，似乎对在 doxygen 中记录参数类型有某种支持。下面的代码有效，但在参数名称中添加了一个烦人的 $（因为它最初是为 php 制作的）。

    @param str $arg description
    @param str|int $arg description

【问题讨论】：

您可以为输入和输出提供的最佳文档是一套通过单元测试，使用unittest framework。
@Johnsyweb 您的链接已损坏docs.python.org/2/library/unittest.html
7 年多以后 docs.python.org/2/library/unittest.html 或 docs.python.org/3/library/unittest.html 应该可以工作了。

标签： python doxygen

【解决方案1】：

有更好的方法。我们使用

def my_method(x, y):
    """
    my_method description

    @type x: int
    @param x: An integer

    @type y: int|string
    @param y: An integer or string

    @rtype: string
    @return: Returns a sentence with your variables in it
    """

    return "Hello World! %s, %s" % (x,y)

就是这样。在 PyCharm IDE 中，这很有帮助。它就像一个魅力;-)

【讨论】：

这似乎不起作用。当我添加一个“！”在开场引号之后，它起作用了。
1) 要创建函数文档，请在函数标题中按 alt+Enter 并选择“插入文档字符串存根”jetbrains.com/pycharm/webhelp/… 2) PyCharm 中文档字符串的默认格式是“重组文本”。您可以在 File->Settings->Python Integrate Tools->Dostring Format 将其更改为 Epytext（如上面的 Tony Melony 列表）。请参阅 epydoc 参考 epydoc.sourceforge.net/epytext.html

【解决方案2】：

您需要在 Python 文档字符串的开头添加一个感叹号，以便 Doxygen 正确解析它。

def myMethod(self, name, image):
    """!
    Does something ...

    @param name String: name of the image
    @param image Image: instance of Image Class or a string indicating the filename.

    @return Return True if operation succeeded or False.
    """
    return True

【讨论】：

【解决方案3】：

如果使用 Python 3，可以使用PEP 3107 中描述的函数注解。

def compile(
   source: "something compilable",
   filename: "where the compilable thing comes from",
   mode: "is this a single statement or a suite?"):

另见function definitions。

【讨论】：

但是目前还没有任何文档处理器支持这一点，是吗？好像sphinx doesn't，我也找不到任何关于 doxygen 支持的信息。
三年前我以为现在应该是了。

【解决方案4】：

Doxygen 非常适合 C++，但如果您主要使用 python 代码，您应该尝试sphinx。如果您选择 sphinx，那么您只需关注pep8。

【讨论】：

主要原因是项目已经使用了doxygen，其次sphinx无法记录参数类型。
而且 sphinx 不会自动记录代码。默认情况下它不识别新功能等。您必须明确添加它们。考虑到这一点的所有狮身人面像插件都可能不起作用。

【解决方案5】：

我想我会在这里发布这个小花絮，因为 IDEA 向我展示了这是可能的，我从来没有被告知或阅读过这个。

>>> def test( arg: bool = False ) -> None: print( arg )

>>> test(10)
10

当您输入 test( 时，IDLE 的文档提示会显示为 (arg: bool=False) -> None，我以为只有 Visual Studio 才会这样做。

它并不完全是 doxygen 材料，但它有助于为使用您的代码的人记录参数类型。

【讨论】：

【解决方案6】：

是的，@docu 是对的——这是（恕我直言）或多或少无缝结合两种文档方案的（恕我直言）方式。另一方面，如果您还想做一些事情，例如将文本放在 doxygen 生成的索引页面上，您可以添加

##
# @mainpage (Sub)Heading for the doxygen-generated index page
# Text that goes right onto the doxygen-generated index page

在 Python 代码开头的某个位置。

换句话说，在 doxygen 不期望 Python cmets 的地方，使用## 提醒它有标签。在需要 Python cmets 的地方（例如，在函数或类的开头），使用 """!。

【讨论】：