使用javadoc的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”)格式,它是一种纯文本/文档string标记格式,可能是Python世界中最stream行的格式。 你应该看看Sphinx ,一个从reStructuredText生成文档的工具(用于例如Python文档本身)。 狮身人面像包括从代码中的文档string中提取文档的可能性(请参见sphinx.ext.autodoc ),并遵循特定的约定来识别reST 字段列表 。 这可能已经成为(或正在成为)最stream行的做法。

你的例子可能如下所示:

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

或者用types信息扩展:

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

遵循Google Python风格指南 。 请注意,狮身人面像也可以使用Napolean扩展来parsing这种格式,它将与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文档取得的例子。

这里是所有types文档的全面示例。

python文档string的标准在Python Enhancement Proposal 257中有描述。

你的方法的适当的评论会是这样的

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

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

简而言之, reStructuredText是用于loggingPython本身的东西。 开发人员指南包含一份重新入门书,风格指南以及编写良好文档的一般build议。