想要改进这个问题？ 更新问题，以便editing this post 提供事实和引用来回答它.
关闭 4 年前。
我目前从 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”)格式，这是一种纯文本/文档字符串标记格式，可能是 Python 世界中最流行的格式。你当然应该看看Sphinx ，一个从 reStructuredText 生成文档的工具(用于例如 Python 文档本身)。 Sphinx 包括从代码中的文档字符串中提取文档的可能性(参见 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
"""
https://stackoverflow.com/questions/5334531/