Що поставити в docstring модуля python? [зачинено]

Гаразд, тому я прочитав і PEP 8, і PEP 257 , і написав безліч доктрингів для функцій і класів, але я трохи не впевнений у тому, що слід містити в модулі docstring. Я подумав, як мінімум, він повинен задокументувати функції та класи, які експортує модуль, але я також побачив декілька модулів, у яких перелічені імена авторів, інформація про авторські права тощо. бути структурованим?

Подумайте про те, що хтось робить help(yourmodule)за запитом інтерактивного перекладача - що вони хочуть знати? (Інші методи вилучення та відображення інформації приблизно helpза рівнем інформації еквівалентні ). Тож якщо у вас є x.py:

"""This module does blah blah."""

class Blah(object):
  """This class does blah blah."""

тоді:

>>> import x; help(x)

показує:

Help on module x:

NAME
    x - This module does blah blah.

FILE
    /tmp/x.py

CLASSES
    __builtin__.object
        Blah

    class Blah(__builtin__.object)
     |  This class does blah blah.
     |  
     |  Data and other attributes defined here:
     |  
     |  __dict__ = <dictproxy object>
     |      dictionary for instance variables (if defined)
     |  
     |  __weakref__ = <attribute '__weakref__' of 'Blah' objects>
     |      list of weak references to the object (if defined)

Як бачите, детальна інформація про класи (і функції теж, хоча я їх тут не показую) вже включена в документації цих компонентів; власний docstring модуля повинен описувати їх дуже коротко (якщо взагалі є) та скоріше зосередитись на стислому резюме того, що може зробити модуль у цілому для вас, в ідеалі - з деякими тестованими прикладами (так само, як функції та класи в ідеалі повинні мати дотестовані приклади в їхні доктрини).

Я не бачу, як метадані, такі як ім’я автора та авторські права / ліцензія, допомагають користувачу модуля - він може скоріше піти в коментарі, оскільки це може допомогти комусь розглянути питання про повторне використання чи модифікацію модуля.

Для цитування специфікацій :

Докстринг сценарію (автономна програма) має бути використаний як повідомлення про його використання, надруковане, коли сценарій викликається неправильними або відсутніми аргументами (або, можливо, з опцією "-h" для "довідки"). Такий docstring повинен документувати синтаксис функції та синтаксису командного рядка, змінні середовища та файли. Повідомлення про використання можуть бути досить складними (на кількох екранах) і повинні бути достатніми для того, щоб новий користувач міг правильно використовувати команду, а також повне швидке посилання на всі параметри та аргументи для складного користувача.

Докстринг для модуля повинен, як правило, перелічувати класи, винятки та функції (та будь-які інші об'єкти), які експортуються модулем, з однорядним підсумком кожного. (Ці підсумки зазвичай дають менше деталей, ніж рядки підсумків в docstring об'єкта.) Документальна смуга для пакету (тобто docstring __init__.pyмодуля пакета ) також повинна перелічувати модулі та підпакети, експортовані пакетом.

Докстринг для класу повинен узагальнити його поведінку та перелічити загальнодоступні методи та змінні екземплярів. Якщо клас призначений для підкласу та має додатковий інтерфейс для підкласів, цей інтерфейс повинен бути вказаний окремо (у документі). Конструктор класу повинен бути задокументований у docstring для його __init__методу. Індивідуальні методи повинні бути задокументовані власним докстрингом.

Докстринг функції або методу - це фраза, що закінчується періодом. Він визначає ефект функції чи методу як команди ("Зробіть це", "Поверніть це"), а не як опис; наприклад, не пишіть "Повертає ім'я шляху ...". Багаторядковий докстринг для функції або методу повинен узагальнювати свою поведінку і документувати її аргументи, повертаються значення (і), побічні ефекти, порушені винятки та обмеження на те, коли її можна викликати (усі, якщо це застосовується). Необхідно вказати необов'язкові аргументи Слід задокументувати, чи є аргументи ключових слів частиною інтерфейсу.