将 javadoc 用于 Python 文档 [英] Using javadoc for Python documentation

问题描述

我目前开始使用 Python，我有很强的 PHP 背景，并且在 PHP 中我养成了使用 javadoc 作为文档模板的习惯.

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.

我想知道 javadoc 在 Python 中是否有其作为 docstring 文档的位置.这里有哪些既定的惯例和/或官方准则?

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

例如像这样的东西是否过于复杂而无法适应 Python 的思维方式，还是我应该尽量简洁?

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

如果我过于详尽，我是否应该使用类似的方法(其中大部分文档不会通过 __doc__ 方法打印)?

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)

推荐答案

查看 reStructuredText(也称为作为reST")格式，这是一种纯文本/文档字符串标记格式，可能是 Python 世界中最流行的.您当然应该看看 Sphinx，这是一种从 reStructuredText 生成文档的工具(用于例如 Python 文档本身).Sphinx 包括从代码中的文档字符串中提取文档的可能性(参见 sphinx.ext.autodoc)，并识别遵循某些约定，保留 字段列表.这可能已成为(或正在成为)最流行的方式.

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

或者用类型信息扩展:

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

这篇关于将 javadoc 用于 Python 文档的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！