Question

经

"""
  Function: myfunc
  Parameters:
    a - First parameter
    b - First parameter
"""

我可以记录一个函数，它会在类摘要中列出。我怎么能用属性做类似的事情？由于我没有在python中声明它们，我希望像

这样的东西

""" ----------------------------------------------------------------------------
  Attributes:
  first - First attribute of the class
  second - Second one
"""

这根本不起作用......

Answer 1

如果你没有明确声明类属性 - 我假设你只是在构造函数中赋值它们 - 你可以将它们的注释与类注释一起放置：

"""
  Class: MyClass
  Describe the class here.

  Attributes:
    attr1 - First attribute of the class
    attr2 - Second one
"""
class MyClass:

    def __init__(self, arg1):
        self.attr1 = arg1
        self.attr2 = "attr2"

你也可以为方法做同样的事情。这是最简单的方法，但你不会在索引中单独列出类成员，这是一个巨大的缺点。如果为每个类成员提供前缀，则文档中的引用将起作用：

"""
  Class: MyClass
  Describe the class here.

  Attribute: attr1
  First attribute of the class

  Attribute: attr2
  Second one
"""
class MyClass:

    # Constructor: __init__
    # Describe the constructor.
    #
    # Parameters:
    #   arg1 - The first argument.
    def __init__(self, arg1):
        self.attr1 = arg1
        self.attr2 = "attr2"

    # Method: method1
    # Describe the method here.
    def method1(self):
        print("method1")

对于通常在实现之前放置注释的方法，注释前缀不是问题。如果你没有明确声明你的属性以便为他们的评论提供自然的位置，那么它会使类评论变得混乱。您还可以将评论拆分为更多部分。请注意，您可以混合使用行和块注释。

两条评论：如果你想使用由"""分隔的块注释而不仅仅是前缀为#的行注释，你必须在NaturalDocs项目中将以下行添加到Languages.txt目录：

Alter Language: Python

   Block Comment: """ """

显然，您喜欢关键字Attribute而非Property，默认情况下，NaturalDocs会识别该关键字。将以下内容添加到NaturalDocs项目目录中的Topics.txt以使其也被识别：

Alter Topic Type: Property

   Add Keywords:
      attribute, attributes

---费达

Answer 2

检查此处所述的 文档字符串 ：http://epydoc.sourceforge.net/manual-docstring.html

变量也可以使用注释文档字符串进行记录。如果变量赋值紧跟一个注释，其注释行以特殊标记'＃：'开头，或者在这一注释的同一行后面，则将其视为该变量的文档字符串： < / p>

#: docstring for x
x = 22
x = 22 #: docstring for x

如何使用NaturalDocs记录类属性

2 个答案: