строка документа в классе или конструктор __init__?

Question

Кажется, есть два места, где вы можете поместить строки документации для класса:

1. Прямо под определением класса:

class MyClass(object):
     """ Summary of MyClass

     Body

     ...
     """

2. Прямо под конструктором __init__:

...
    def __init__(self, arg1, arg2):
        """ Summary of MyClass

        Body

        ...
        """

Что предпочтительнее? Или все в порядке?

Answer 1

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

Строка документации для класса должна обобщать его поведение и перечислять открытые методы и переменные экземпляра. Если класс предназначен для подклассов и имеет дополнительный интерфейс для подклассов, этот интерфейс должен быть указан отдельно (в строке документации). Конструктор класса должен быть задокументирован в строке документации для его метода __init__. Отдельные методы должны быть задокументированы их собственной строкой документации.

Акцент мой. Эта ссылка взята из PEP 257 - Соглашения о документах