使用javadoc for Python文档

问题:

我目前从Python开始,我拥有强大的PHP背景,在PHP中,我习惯使用javadoc作为文档模板。
我想知道javadoc是否有Python的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)

回答:

看看reStructuredText(也称为“reST”)格式,这是一个明文/ docstring标记格式,可能是Python世界中最流行的。你一定要看看Sphinx,一个从reStructuredText生成文档的工具(用于例如Python文档本身)。 Sphinx包括从代码中的docstrings中提取文档的可能性(参见sphinx.ext.autodoc),并根据某些约定识别reST field lists。这可能已经成为(或正在成为)最受欢迎的方法。
你的例子可能如下:

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

 
 
Code问答: http://codewenda.com/topics/python/
Stackoverflow: Using javadoc for Python documentation

*转载请注明本文链接以及stackoverflow的英文链接

发表评论

电子邮件地址不会被公开。 必填项已用*标注

− 6 = 2