标签归档:javadoc

将javadoc用于Python文档[关闭]

问题:将javadoc用于Python文档[关闭]

我目前从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)

I am currently beginning with Python and I have a strong PHP background and in PHP I have took the habit of using javadoc as a documentation template.

I was wondering if javadoc has its place as docstring documentation in Python. What are the established conventions and/or official guildelines here?

E.g. is something like this too elaborate to fit in the Python mindset or should I try to be as concise as possible?

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

And if I am a bit too exhaustive should I go with something like this instead (where most of the documentation doesn’t get printed through the __doc__ method)?

# 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)

回答 0

看一下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
"""

Have a look at the reStructuredText (also known as “reST”) format, which is a plaintext/docstring markup format, and probably the most popular in the Python world. And you should certainly look at Sphinx, a tool to generate documentation from reStructuredText (used for eg. the Python documentation itself). Sphinx includes the possibility to extract documentation from the docstrings in your code (see sphinx.ext.autodoc), and recognizes reST field lists following certain conventions. This has probably become (or is becoming) the most popular way to do it.

Your example could look as follows:

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

Or extended with type information:

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

回答 1

遵循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文档。

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

Follow Google Python Style Guide. Note that Sphinx can also parse this format using the Napolean extension, which will come packaged with Sphinx 1.3 (this is also compatible with 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

Example taken from the Napolean documentation linked above.

A comprehensive example on all types of docstrings here.


回答 2

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

The standard for python documentation strings is described in Python Enhancement Proposal 257.

The appropriate comment for your method would be something like

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

回答 3

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

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

Take a look at Documenting Python, a page “aimed at authors and potential authors of documentation for Python.”

In short, reStructuredText is what’s used for documenting Python itself. The developer’s guide contains a reST primer, style guide, and general advice for writing good documentation.