Docstring для переменной

Ответ 1

Нет, и это было бы бесполезно, если бы вы могли.

docstring всегда является атрибутом объекта (модуля, класса или функции), не привязанного к определенной переменной.

Это означает, что вы могли:

t = 42
t.__doc__ = "something"

вы бы установили документацию для целого числа 42 не для переменной t. Как только вы перепроверьте t, вы потеряете докшрин. Неизменяемые объекты, такие как числа строк, иногда имеют один объект, разделяемый между разными пользователями, поэтому в этом примере вы, вероятно, фактически установили docstring для всех вхождений 42 в вашей программе.

print(42 .__doc__) # would print "something" if the above worked!

Для изменяемых объектов это не обязательно будет вредно, но все равно будет ограниченным использованием, если вы переустановите объект.

Если вы хотите документировать атрибут класса, используйте для этого описание класса docstring.

Ответ 2

Epydoc позволяет docstrings по переменным:

Пока язык не обеспечивает их напрямую, поддержка Epydoc переменные docstrings: если оператор присваивания переменных сразу за которым следует голой строковый литерал, тогда это присвоение рассматривается как docstring для этой переменной.

Пример:

class A:
    x = 22
    """Docstring for class variable A.x"""

    def __init__(self, a):
        self.y = a
        """Docstring for instance variable A.y

Ответ 3

В некоторых сценариях документации python есть обозначения, которые могут использоваться в модуле/классах docstring для документирования var.

например. для spinx, вы можете использовать: var и: ivar. См. Этот документ (примерно на полпути вниз).

Ответ 4

Ну, хотя Python не обрабатывает строки, определенные сразу после глобального определения как docstring для переменной, sphinx делает, и это, конечно, не плохая практика, чтобы включать их.

debug = False
'''Set to True to turn on debugging mode. This enables opening IPython on 
exceptions.
'''

Вот некоторый код, который сканирует модуль и вытаскивает имена определений глобальных переменных, значения и следующей строки.

def GetVarDocs(fname):
    '''Read the module referenced in fname (often <module>.__file__) and return a
    dict with global variables, their value and the "docstring" that follows
    the definition of the variable
    '''
    import ast,os
    fname = os.path.splitext(fname)[0]+'.py' # convert .pyc to .py
    with open(fname, 'r') as f:
        fstr = f.read()
    d = {}
    key = None
    for node in ast.walk(ast.parse(fstr)):
        if isinstance(node,ast.Assign):
            key = node.targets[0].id
            d[key] = [node.value.id,'']
            continue
        elif isinstance(node,ast.Expr) and key:
            d[key][1] = node.value.s.strip()
        key = None
    return d

Ответ 5

Нет, вы можете сделать это только для модулей, (лямбда и "нормальных" ) функций и классов, насколько я знаю. Другие объекты, даже изменчивые, наследуют докстроны своего класса и поднимают AttributeError, если вы попытаетесь изменить это:

>>> a = {}
>>> a.__doc__ = "hello"
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
AttributeError: 'dict' object attribute '__doc__' is read-only

(Ваш второй пример действителен Python, но строка """l""" ничего не делает. Она генерируется, вычисляется и отбрасывается.)

Ответ 6

Чтобы добавить к ответу ford о Epydoc, обратите внимание, что PyCharm также будет использовать строковый литерал в качестве документации для переменной в классе:

class Fields_Obj:
    DefaultValue=None
    """Get/set the default value of the data field"""

Ответ 7

Sphinx имеет встроенный синтаксис для документирования атрибутов (т.е. НЕ значения, описанные в описании @duncan). Примеры:

#: This is module attribute
x = 42

class MyClass:

    #: This is a class attribute
    y = 43

Вы можете прочитать больше в документах Sphinx: http://www.sphinx-doc.org/en/1.4.8/ext/autodoc.html#directive-autoattribute

... или в этом другом вопросе: Как документировать константу модуля в Python?