Docstrings per i dati?

Question

C'è un modo per descrivere i dati del modulo in un modo simile a quello che un docstring descrive un modulo o una funzione?

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

Answer 1

Per quanto ne so, non è possibile assegnare docstring ai membri dei dati del modulo.

PEP 224 suggerisce questa funzione, ma il PEP è stato respinto.

Ti suggerisco di documentare i membri dei dati di un modulo nella documentazione del modulo:

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

module.data: contains the word "spam"

"""

data = "spam"

Answer 2

È possibile fare la documentazione dei dati del modulo, usando epydoc sintassi. Epydoc è uno degli strumenti di documentazione più utilizzati per Python.

La sintassi per la documentazione è #: sopra la riga di inizializzazione variabile, in questo modo:

# module.py:

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

Ora, quando genererai la tua documentazione, i dati saranno descritti come variabili del modulo con una descrizione e un tipo str . Puoi omettere la riga @type .

Answer 3

Come spiega codeape, non è possibile documentare membri di dati generali.

Tuttavia, è possibile documentare i membri dei dati proprietà :

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

Ciò fornirà una spiegazione all'attributo foo , ovviamente.