使用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议。
