0

通过

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

我可以记录一个函数，它会在类摘要中列出。我怎样才能对属性做类似的事情？因为我没有在 python 中声明它们，所以我希望像

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

那根本行不通...

4

2 回答 2

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

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

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

Alter Language: Python

   Block Comment: """ """

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

Alter Topic Type: Property

   Add Keywords:
      attribute, attributes

--- 费尔达

于 2012-04-09T10:33:39.493 回答
0

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

变量也可以使用注释文档字符串记录。如果变量赋值的前面有一个注释，其行以特殊标记“#:”开头，或者在同一行后面跟着这样的注释，那么它被视为该变量的文档字符串：

#: docstring for x
x = 22
x = 22 #: docstring for x
于 2012-04-04T11:30:15.877 回答