Docstrings pour les données?

Question

Existe-t-il un moyen de décrire les données du module de la même manière qu’une docstring décrit un module ou une fonction?

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

Answer 1

À ma connaissance, il n'est pas possible d'attribuer des docstrings aux membres de données du module.

PEP 224 suggère cette fonctionnalité, mais le PEP a été rejeté.

Je vous suggère de documenter les données membres d'un module dans la docstring du module:

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

module.data: contains the word "spam"

"""

data = "spam"

Answer 2

Il est possible de documenter les données du module à l'aide de epydoc . syntaxe. Epydoc est l’un des outils de documentation les plus utilisés pour Python.

La syntaxe à utiliser pour la documentation est #: au-dessus de la ligne d'initialisation de la variable, comme suit:

# module.py:

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

Maintenant, lorsque vous générez votre documentation, data sera décrit comme une variable de module avec une description et un type donnés str . Vous pouvez omettre la ligne @type .

Answer 3

Comme l'explique codeape, il n'est pas possible de documenter les membres de données généraux.

Cependant, il est possible de documenter les membres de données propriété :

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

Ceci donnera une docstring à l'attribut foo , évidemment.