相关疑难解决方法(0)

我很快就开始了一个开源Python项目,我正在尝试提前决定如何编写我的文档字符串.显而易见的答案是使用reStructuredText和Sphinx与autodoc,因为我真的喜欢简单地在我的文档字符串中正确记录我的代码然后让Sphinx为我自动构建API文档.

问题是它使用的reStructuredText语法 - 我认为它在呈现之前是完全不可读的.例如:

:param path: The path of the file to wrap
:type path: str
:param field_storage: The :class:`FileStorage` instance to wrap
:type field_storage: FileStorage
:param temporary: Whether or not to delete the file when the File instance
    is destructed
:type temporary: bool

你必须真正放慢脚步,花一点时间才能理解这种语法混乱.我更喜欢谷歌方式(谷歌Python风格指南),与上面的对应方式如下:

Args:
    path (str): The path of the file to wrap
    field_storage (FileStorage): The FileStorage instance to wrap
    temporary (bool): Whether or not to delete the file when the File …

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

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

• str(或使用String或string？)
• int
• list
• dict
• 功能()
• tuple
• 类的对象实例 MyClass

第二,如何指定可以是多种类型的参数,比如可以处理单个参数的函数,int或者可以是str？

请使用以下示例演示使用您提出的解决方案记录此文档所需的语法.请注意,希望能够从文档内部超链接对"Image"类的引用.

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中记录参数类型有一些支持.一般.下面的代码可以工作但是会给param名称添加一个烦人的$(因为它最初是为php制作的).

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