将javadoc用于Python文档[关闭]


162

我目前从Python开始,我有很强的PHP背景,在PHP中,我习惯于javadoc用作文档模板。

我想知道它是否在Python文档中javadoc占有一席之地docstring这里有哪些既定的公约和/或官方指南?

例如,类似这样的内容太复杂,无法适应Python的思维方式,还是我应该尽量简洁一些?

"""
replaces template place holder with values

@param string timestamp     formatted date to display
@param string priority      priority number
@param string priority_name priority name
@param string message       message to display

@return string formatted string
"""

而且,如果我有点过于详尽,我应该改用类似的东西(大多数文档都无法通过该__doc__方法打印)吗?

# replaces template place holder with values
#    
# @param string timestamp     formatted date to display
# @param string priority      priority number
# @param string priority_name priority name
# @param string message       message to display
#    
# @return string formatted string

def format(self, timestamp = '', priority = '', priority_name = '', message = ''):
    """
    replaces template place holder with values
    """
    values = {'%timestamp%' : timestamp,
              '%priorityName%' : priority_name,
              '%priority%' : priority,
              '%message%' : message}

    return self.__pattern.format(**values)

6
Thera在前面的问题中也有很多答案,这是重复的。
Alex Dupuy 2014年

Answers:


227

看一下reStructuredText(也称为“ reST”)格式,它是纯文本/文档字符串标记格式,可能是Python世界中最流行的格式。而且,您当然应该看一下Sphinx,它是一种从reStructuredText生成文档的工具(例如用于Python文档本身)。Sphinx允许从代码中的文档字符串中提取文档(请参见sphinx.ext.autodoc),并按照某些约定识别reST 字段列表。这可能已经成为(或正在成为)最流行的方法。

您的示例如下所示:

"""Replaces template placeholder with values.

:param timestamp: formatted date to display
:param priority: priority number
:param priority_name: priority name
:param message: message to display
:returns: formatted string
"""

或扩展了类型信息:

"""Replaces template placeholder with values.

:param timestamp: formatted date to display
:type timestamp: str or unicode
:param priority: priority number
:type priority: str or unicode
:param priority_name: priority name
:type priority_name: str or unicode
:param message: message to display
:type message: str or unicode
:returns: formatted string
:rtype: str or unicode
"""

7
如果您需要换行以进行详细描述,该怎么办?看起来怎么样?
Skylar Saveland

6
请参阅reStructuredText参考,尤其是字段列表:docutils.sourceforge.net/docs/ref/rst/…– 2012
史蒂芬

6
请注意,此处的短语不符合PEP 257的方式。应该使用- Replace template place holder with values.而不是replaces template place holder with values-请注意句子,开头的大写字母和结尾的句号(。)。
kratenko 2014年

1
从版本1.3开始,Sphinx还通过sphinx.ext.napoleon扩展名支持更好的格式。
Petri

3
有人可以给我指出指定这些特殊文档字符串的最佳文档,例如“:param ____:”和“:returns:”吗?目前似乎很难找到这样的文件。
krumpelstiltskin

75

遵循Google Python样式指南。请注意,Sphinx还可以使用Napolean扩展来解析此格式,该扩展将与Sphinx 1.3打包在一起(这也与PEP257兼容):

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Args:
        arg1 (int): Description of arg1
        arg2 (str): Description of arg2

    Returns:
        bool: Description of return value

    """
    return True

示例取自上面链接的Napolean文档。

这里是有关所有类型的文档字符串的综合示例。


20
对于所有阅读文档字符串的人类
Waylon Flinn 2015年

1
更新了Google Python样式指南链接
confused00

@ confused00如何记录我的方法正在返回对象数组?
Cito

1
现在我很困惑!参数或参数?stackoverflow.com/questions/1788923/parameter-vs-argument
舒瓦

25

Python增强建议257中描述了python文档字符串的标准。

适用于您的方法的注释应类似于

def format(...):
    """Return timestamp string with place holders replaced with values.

    Keyword arguments:
    timestamp     -- the format string (default '')
    priority      -- priority number (default '')
    priority_name -- priority name (default '')
    message       -- message to display (default '')
    """

17
PEP257并没有说明参数部分的实际格式。它只是说应该写,并举了一个例子。但这只是一个例子。因此,我绝对建议您使用Sphinx约定,因为您不会破坏PEP257,并且使用的格式可以由sphinx解析。
vaab 2013年

7
除了上面介绍的第一个文档很丑陋之外,还有很多对人类有用的冗余信息。我宁愿使用一种约定,使我的源代码易于阅读而无需首先进行解析
confused00

1

看一下Documenting Python,这是“针对Python文档的作者和潜在作者的页面”。

简而言之,reStructuredText是用于记录Python本身的东西。开发人员指南包含reST入门,样式指南以及有关编写良好文档的一般建议。

By using our site, you acknowledge that you have read and understand our Cookie Policy and Privacy Policy.
Licensed under cc by-sa 3.0 with attribution required.