Строки документации
Возможно, вы заметили в наших многочисленных примерах с dir() один атрибут среди множества других - __doc__. Этот атрибут - строка, которая содержит комментарии, описывающие объект. Python называет ее строкой документации, или docstring, и вот, как она работает. Если первая директива определения модуля, класса, метода или функции - строка, то эта строка оказывается связанной с объектом в качестве его атрибута __doc__. Посмотрите, например, на строку документации для объекта __builtins__. Воспользуемся Питоновской директивой print, чтобы выходные данные было легче читать, поскольку строки документации часто содержат встроенные разделители строк (\n):
Листинг 24. Строка документации модуля
>>> print __builtins__.__doc__ # Модуль докстроки Built-in functions, exceptions, and other objects.
Noteworthy: None is the `nil' object; Ellipsis represents `...' in slices.
И вновь, Python поддерживает даже строки документации для классов и методов, которые определены интерактивно в оболочке Python. Давайте рассмотрим строки документации для нашего класса Person и его метода intro:
Листинг 25. Строки документации класса и метода
>>> Person.__doc__ # Докстрока класса 'Person class.' >>> Person.intro.__doc__ # Докстрока метода класса 'Return an introduction.'
Поскольку строки документации предоставляют такую ценную информацию, многие среды разработки Python включают способы автоматического отображения строк документации для объектов. Давайте рассмотрим еще одну строку документации - для функции dir():
Листинг 26. Строка документации функции
>>> print dir.__doc__ # Function docstring dir([object]) -> list of strings
Return an alphabetized list of names comprising (some of) the attributes of the given object, and of attributes reachable from it:
No argument: the names in the current scope. Module object: the module attributes. Type or class object: its attributes, and recursively the attributes of its bases. Otherwise: its attributes, its class's attributes, and recursively the attributes of its class's base classes.
