Docstrings für Daten?

Question

Gibt es eine Möglichkeit, die Daten des Moduls so zu beschreiben, dass ein Docstring ein Modul oder eine Funktion beschreibt?

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

Answer 1

Nach meinem Wissen ist es nicht möglich, den Moduldatenmitgliedern Docstrings zuzuweisen.

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

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

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

module.data: contains the word "spam" 

""" 

data = "spam" 

Answer 2

Es möglich Dokumentation von Moduldaten zu machen, mit der Nutzung der epydoc Syntax. Epydoc ist eines der am häufigsten verwendeten Dokumentationswerkzeuge 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" 

Nun, wenn Sie Ihre Dokumentation generieren, wird data mit gegebenen Beschreibung als Modulvariable beschrieben und str eingeben. Sie können die Zeile @type weglassen.

Answer 3

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

Aber es 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''') 

Dieses eine docstring dem Attribut foo geben wird, offensichtlich.