Документация класса должна включать общедоступные компоненты объекта. Параметры __init__ могут быть общедоступными, а могут и не быть, поэтому то, будут ли они включены в строку документации класса или нет, зависит от конструкции объекта.
Полный абзац в PEP 257 гласит:
Строка документации для класса должна обобщать его поведение и перечислять общедоступные методы и переменные экземпляра. Если класс предназначен для создания подклассов и имеет дополнительный интерфейс для подклассов, этот интерфейс должен быть указан отдельно (в строке документации). Конструктор класса должен быть задокументирован в строке документации для его метода __init__. Отдельные методы должны быть задокументированы их собственной строкой документации.
А в руководстве по стилю Google говорится:
Классы должны иметь строку документации под определением класса, описывающим класс. Если у вашего класса есть общедоступные атрибуты, они должны быть задокументированы здесь в разделе «Атрибуты» и иметь такое же форматирование, как и раздел «Аргументы» функции.
Таким образом, определение документации зависит от того, являются ли параметры для __init__ общедоступными. Если целью объекта является создание пользователями собственных экземпляров, параметры __init__ должны быть задокументированы в строке документации класса. Однако, если объект создается внутри, а затем возвращается пользователю, документация класса должна ссылаться только на общедоступные аспекты объекта.
Таким образом, следующий пример из Google предполагает, что параметр likes_spam из __init__ является общедоступным:
class SampleClass(object):
"""Summary of class here.
Longer class information....
Longer class information....
Attributes:
likes_spam: A boolean indicating if we like SPAM or not.
eggs: An integer count of the eggs we have laid.
"""
def __init__(self, likes_spam=False):
"""Inits SampleClass with blah."""
self.likes_spam = likes_spam
self.eggs = 0
def public_method(self):
"""Performs operation blah."""
Однако ниже общедоступный атрибут likes_spam определяется во время __init__ на основе двух внутренних параметров spam_count и like_threshold. Таким образом, likes_spam задокументировано в строке документации класса, а spam_count и like_threshold — в строке документации __init__.
class SampleClass(object):
"""Summary of class here.
Longer class information....
Longer class information....
Attributes:
likes_spam: A boolean indicating if we like SPAM or not.
eggs: An integer count of the eggs we have laid.
"""
def __init__(self, spam_count, like_threshold=1):
"""Inits SampleClass.
Args:
spam_count: The amount of SPAM consumed.
like_threshold: The threshold consumed that indicates
whether we like SPAM.
"""
self.likes_spam = spam_count > like_threshold
self.eggs = 0
def public_method(self):
"""Performs operation blah."""
person
dshanahan
schedule
25.05.2020
