如何在Python中记录字段和属性？ [英] How to document fields and properties in Python?

问题描述

在Python中记录一个类或方法很容易：

It's easy to document a class or method in Python:

class Something:
  """ Description of the class. """

  def do_it(self):
    """ Description of the method. """
    pass

  class_variable = 1 # How to comment?

  @property
  def give_me_some_special_dict(self):
    """ doesn't work! Doc of general dict will be shown. """
    return {}

但是如何记录一个字段或属性以用于API文档或帮助？

But how to document a field or property for usage in API docs or help?

推荐答案

Python有一个PEP（ 257 ）定义了Docstring约定。关于属性的文档，它指出：

Python has a PEP (257) that defines Docstring Conventions. Regarding documentation of attributes, it states:

在顶部
级别的简单分配之后立即发生的字符串文字
一个模块，类或 __ init __
方法称为属性
docstrings。

String literals occurring immediately after a simple assignment at the top level of a module, class, or __init__ method are called "attribute docstrings".

所以以下被认为是文档属性：

So the following are considered documented attributes:

class Foo(object):
  velocity = 1  
  """Foo's initial velocity"""

  def __init__(self, args):
    self.location = 0.0 
    """Foo's initial location"""   

（编辑：修正第二个docstring）

( Fixed second docstring)

这篇关于如何在Python中记录字段和属性？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！