Co umieścić w docstring modułu Pythona? [Zamknięte]

Ok, więc przeczytałem zarówno PEP 8, jak i PEP 257 i napisałem wiele dokumentów dla funkcji i klas, ale nie jestem pewien, co powinno znaleźć się w dokumentacji modułu. Pomyślałem, że powinien przynajmniej udokumentować funkcje i klasy eksportowane przez moduł, ale widziałem też kilka modułów, które zawierają nazwiska autorów, informacje o prawach autorskich itp. Czy ktoś ma przykład, jak dobry dokument w Pythonie powinien mieć strukturę?

Pomyśl o kimś, kto robi to help(yourmodule)na polecenie interaktywnego tłumacza - co chce wiedzieć? (Inne metody wyodrębniania i wyświetlania informacji są z grubsza równoważne helppod względem ilości informacji). Więc jeśli masz w x.py:

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

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

następnie:

>>> import x; help(x)

przedstawia:

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)

Jak widać, szczegółowe informacje o klasach (a także funkcjach, chociaż ich tu nie pokazuję) są już zawarte w dokumentacjach tych składników; własna dokumentacja modułu powinna opisywać je bardzo krótko (jeśli w ogóle) i raczej koncentrować się na zwięzłym podsumowaniu tego, co moduł jako całość może dla ciebie zrobić, najlepiej z kilkoma udokumentowanymi przykładami (tak jak funkcje i klasy najlepiej powinny mieć udokumentowane przykłady w ich dokumenty).

Nie widzę, w jaki sposób metadane, takie jak nazwisko autora i prawa autorskie / licencja, pomagają użytkownikowi modułu - mogą raczej zostać umieszczone w komentarzach, ponieważ mogą pomóc komuś w rozważeniu ponownego wykorzystania lub modyfikacji modułu.

Aby zacytować specyfikacje :

Dokumentacja skryptu (samodzielnego programu) powinna nadawać się do użytku jako jego komunikat o użyciu, drukowany, gdy skrypt jest wywoływany z niepoprawnymi lub brakującymi argumentami (lub być może z opcją „-h” dla „pomocy”). Taki ciąg dokumentów powinien dokumentować funkcję skryptu i składnię wiersza poleceń, zmienne środowiskowe i pliki. Komunikaty użycia mogą być dość rozbudowane (kilka ekranów pełnych) i powinny wystarczyć nowemu użytkownikowi do prawidłowego użycia polecenia, a także pełne szybkie odniesienie do wszystkich opcji i argumentów dla wyrafinowanego użytkownika.

Dokumentacja modułu powinna generalnie zawierać listę klas, wyjątków i funkcji (oraz wszelkich innych obiektów), które są eksportowane przez moduł, wraz z jednowierszowym podsumowaniem każdej z nich. (Te podsumowania generalnie zawierają mniej szczegółów niż wiersz podsumowania w dokumentacji obiektu). Dokumentacja pakietu (tj. Dokumentacja __init__.pymodułu pakietu ) powinna również zawierać listę modułów i podpakietów wyeksportowanych przez pakiet.

Dokumentacja klasy powinna podsumowywać jej zachowanie i zawierać listę publicznych metod i zmiennych instancji. Jeśli klasa ma być podklasą i ma dodatkowy interfejs dla podklas, ten interfejs powinien być wymieniony osobno (w dokumentacji). Konstruktor klasy powinien być udokumentowany w dokumentacji dla jego __init__metody. Poszczególne metody powinny być udokumentowane w ich własnej dokumentacji.

Dokumentacja funkcji lub metody to fraza kończąca się kropką. Przepisuje działanie funkcji lub metody jako polecenie („Zrób to”, „Zwróć to”), a nie jako opis; np. nie pisz „Zwraca ścieżkę…”. Wielowierszowy opis funkcji lub metody powinien podsumowywać jej zachowanie i dokumentować jej argumenty, zwracane wartości, skutki uboczne, zgłoszone wyjątki i ograniczenia dotyczące tego, kiedy można ją wywołać (wszystkie, jeśli mają zastosowanie). Należy wskazać argumenty opcjonalne. Należy udokumentować, czy argumenty słów kluczowych są częścią interfejsu.