什麼是此結構化評論以及什麼是「更新」字段？

我正在使用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字段？

來源

2015-02-17 CrabMan

這種形式的大多數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。

來源

2015-02-17 22:14:22

我不會說「最」的文檔是這種格式。我一直在編程Python多年，從來沒有使用它，幾乎從來沒有在圖書館遇到它。 – 2015-02-17 22:31:56

這是非常真實的。我想我應該寫「大多數文檔（以這種形式）都遵循Epydoc標準」 – 2015-02-17 22:32:57

什麼是此結構化評論以及什麼是「更新」字段？

回答

相關問題