如何记录python函数参数类型？ [英] How to document python function parameter types?

问题描述

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

I know that the parameters can be any object but for the documentation it is quite important to specify what you would expect.

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

First is how to specify a parameter types like these below?

• str （或使用 String 或 string ？）


• int


• list


• dict


• function（）


• tuple


• 对象 MyClass

• str (or use String or string?)
• int
• list
• dict
• function()
• tuple
• object instance of class MyClass

的实例第二，如何指定可以为$ b是 int 或 str 可以处理单个参数的多种类型？

Second, how to specify params that can be of multiple types like a function that can handle a single parameter than can be int or str?

请使用下面的示例演示用建议的解决方案进行记录所需的语法。请注意，希望能够从文档内部超链接到 Image类的引用。

Please use the below example to demonstrate the syntax needed for documenting this with your proposed solution. Mind that it is desired to be able to hyperlink reference to the "Image" class from inside the documentation.

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

注意，欢迎您提出用法任何能够满足要求的文档工具（狮身人面像，氧气等）。

Note, you are welcome to suggest the usage of any documentation tool (sphinx, oxygen, ...) as long it is able to deal with the requirements.

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

It seams that there is some kind of support for documenting parameter types in doxygen in. general. The code below works but adds an annoying $ to the param name (because it was initially made for php).

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

推荐答案

有一个更好的方法。我们使用

There is a better way. We use

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中，这很有帮助。它就像一种魅力；-）

That's it. In the PyCharm IDE this helps a lot. It works like a charm ;-)

这篇关于如何记录python函数参数类型？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！