如何解决将 javadoc 用于 Python 文档
看看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
"""
解决方法
我目前是从 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)
版权声明:本文内容由互联网用户自发贡献,该文观点与技术仅代表作者本人。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如发现本站有涉嫌侵权/违法违规的内容, 请发送邮件至 dio@foxmail.com 举报,一经查实,本站将立刻删除。