Docstrings für Daten?

Question

Gibt es eine Möglichkeit der Moduldaten in einer ähnlichen Art und Weise zu beschreiben, dass ein docstring ein Modul oder eine funcion beschreibt?

class MyClass(object):
    def my_function():
        """This docstring works!"""
        return True
    my_list = []
    """This docstring does not work!"""

Answer 1

Mein Wissen ist es nicht möglich Docstrings zuweisen Datenelemente Modul.

PEP 224 schlägt vor, diese Funktion, aber der PEP abgelehnt wurde.

Ich schlage vor, Sie die Datenelemente eines Moduls in der Modul docstring dokumentieren:

# module.py:
"""About the module.

module.data: contains the word "spam"

"""

data = "spam"

Answer 2

Es ist möglich Dokumentation von Moduldaten zu machen, mit der Nutzung der epydoc Syntax. Epydoc ist eines der am häufigsten verwendeten Dokumentationstool für Python.

Die Syntax für die Dokumentation ist über der Variableninitialisierung Linie #:, wie folgt aus:

# module.py:

#: Very important data.
#: Use with caution.
#: @type: C{str}
data = "important data"

Wenn Sie nun Ihre Dokumentation generieren, data wird als Modulvariable mit gegebener Beschreibung und Typ str beschrieben. Sie können die @type Linie weglassen.

Answer 3

Wie codeape erklärt, ist es nicht möglich, allgemeine Datenelemente zu dokumentieren.

Es ist jedoch ist möglich property Datenelemente zu dokumentieren:

class Foo:
  def get_foo(self): ...

  def set_foo(self, val): ...

  def del_foo(self): ...

  foo = property(get_foo, set_foo, del_foo, '''Doc string here''')

Dies wird eine docstring zum foo Attribute geben, natürlich.