使用javadoc进行Python文档 [英] Using javadoc for Python documentation

问题描述

我目前从Python开始，我有一个强大的PHP背景，在PHP中我习惯了使用 javadoc 作为文档模板。

我想知道如果 javadoc 在Python中具有 docstring 文档的位置。这样的东西太复杂了，以适应Python的心态，还是应该尽可能的简洁一些？

  
用值替换模板占位符
 
 @param string timestamp格式化日期显示
 @param string优先级优先级号
 @param string priority_name优先级名称
 @param字符串消息显示
 
 @return字符串格式化字符串

  

如果我有点太穷了，我应该用这样的东西，而不是通过 __ doc __ 方法打印大部分文档）？

 ＃用值替换模板占位符
＃
＃@param string timestamp格式化日期到显示
＃@param string priority priority number 
＃@param string priority_name优先级名称
＃@param string消息显示
＃
＃@return string form atted string 
 
 def format（self，timestamp =''，priority =''，priority_name =''，message =''）：

替换模板地持有人

 values = {'％timestamp％'：timestamp，
'％priorityName％'：priority_name，
'％priority％'：优先，
'％message％'：message} 
 
 return self .__ pattern.format（** values）
  

解决方案

查看 reStructuredText （也称为reST）格式，这是一个明文/ docstring标记格式，可能是Python世界中最受欢迎的。而您应该看看 Sphinx ，这是一个从reStructuredText生成文档的工具（用于例如Python文档本身）。狮身人面像包括从您的代码中的文档字符串中提取文档的可能性（请参阅 sphinx.ext.autodoc ），并识别按照某些约定，重新字段列表。这可能已经成为（或正在成为）最受欢迎的方式。

您的示例可能如下所示：

pre> 用值替换模板占位符

：param timestamp：格式化的日期显示
：param priority：优先级数
：param priority_name：优先级名称
：param message：要显示的消息
：返回：格式化的字符串



或扩展类型信息：

 替换模板占位符值为
 
：param timestamp：格式化的日期显示
：类型时间戳：str或unicode 
：param优先级：优先级数
：类型优先级：str或unicode 
：param priority_name：优先级名称
：type priority_name：str或unicode 
：param message：要显示的消息
：键入消息：str或unicode 
：返回：格式化字符串
：rtype：str或unicode 

  

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.

I was wondering if javadoc has its place as docstring documentation in Python. 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
"""

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)

解决方案

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

Or extended with type information:

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