这个结构化评论是什么？"updated" 字段有什么用？

Question

我正在使用 Eclipse + PyDev 开发 Python。当我从 "Module: CLI (argparse)" 模板创建新模块时，Eclipse 在文件开头创建以下注释块。

#!/usr/local/bin/python2.7
# encoding: utf-8
'''
packagename.newfile -- shortdesc

packagename.newfile is a description

It defines classes_and_methods

@author:     user_name

@copyright:  2015 organization_name. All rights reserved.

@license:    license

@contact:    user_email
@deffield    updated: Updated
'''

它似乎有某种结构，我猜它被某种东西解析了？我有几个问题：

这种类型的注释结构是如何调用的，它被哪些程序使用？
如何在 @license 下包含多行 Apache 许可证 2.0 通知？
什么是 updated 字段？

Answer 1

大多数 Python 这种形式的文档都遵循 Epydoc 标准。

http://epydoc.sourceforge.net/manual-fields.html 显示您在上面列出的所有字段的详细信息。这个文件然后可以被 Epydoc 解析，并从中创建文档。

以下示例显示允许多行文档：

def example():
    """
    @param x: This is a description of
        the parameter x to a function.
        Note that the description is
        indented four spaces.
    @type x: This is a description of
        x's type.
    @return: This is a description of
        the function's return value.

        It contains two paragraphs.
    """
    #[...]

本文来自 http://epydoc.sourceforge.net/epydoc.html#fields

updated 部分展示了添加任何@style 注释的能力。参见 http://epydoc.sourceforge.net/epydoc.html#adding-new-fields。

所以@deffield updated: Updated意味着有一个新注释@updated。这将按如下方式使用

"""
@updated 17/02/2015
"""

这将被渲染到从 Epydoc 创建的 HTML 中。

这个结构化评论是什么？"updated" 字段有什么用？

What is this structured comment and what is "updated" field for?

python

eclipse

pydev