Если посмотреть библиотечный Python код, то там можно увидеть вот такое:
class IntervalArray(IntervalMixin, ExtensionArray):
"""
Pandas array for interval data that are closed on the same side.
Или такое:
@classmethod
def _validate(cls, left, right, dtype: IntervalDtype) -> None:
"""
Verify that the IntervalArray is valid.
Что-то к так с документацией, да?)
Зачем питонисты решили сделать все наоборот - комменты после кода???
До кода же логичнее - вначале читаешь доки, потом если надо смотришь код?
Не от балды, нет.
Интерпретатор при загрузке модуля читает первое выражение в теле класса/функции/метода и, если это строковый литерал, помещает его в атрибут ___doc___ соответствующего объекта. Работает принцип convention over configuration.
Также документация выводится с помощью метода help(obj) - если надо прямо в коде. Или через рефлексию - inspect. Или с помощью CLI утилиты pydoc.
Описывается формат документации стандартом PEP 257. Т.е. все продумано.
Причём поля класса документируются точно также для единообразия. Хотя на них стройная система, описанная выше рушится.
И появляется интересный нюанс - если по привычке писать документацию к полям в JavaDoc стиле, то она сопоставится с другим полем)
Мне конечно привычнее JavaDoc стиль, но признаю красоту идеи с автоматическим обогащением метаданных сущности документацией, причём средствами языка.
P. S. Как я обратил на это внимание? Один агент написал документацию в формате JavaDoc, другой на ревью заметил, что это не по стандарту Python)
#lang #python #java #conv_over_conf
