Was soll in eine Python-Modul-Dokumentzeichenfolge eingefügt werden? [geschlossen]

Ok, ich habe sowohl PEP 8 als auch PEP 257 gelesen und viele Dokumentzeichenfolgen für Funktionen und Klassen geschrieben, bin mir aber nicht sicher, was in einer Modul-Dokumentzeichenfolge enthalten sein soll. Ich dachte mir, es sollte zumindest die Funktionen und Klassen dokumentieren, die das Modul exportiert, aber ich habe auch einige Module gesehen, in denen Autorennamen, Copyright-Informationen usw. aufgelistet sind. Hat jemand ein Beispiel dafür, wie eine gute Python-Dokumentzeichenfolge funktionieren sollte? strukturiert sein?

Denken Sie an jemanden, der help(yourmodule)an der Eingabeaufforderung des interaktiven Dolmetschers arbeitet - was möchten sie wissen? (Andere Methoden zum Extrahieren und Anzeigen der Informationen entsprechen in etwa helpder Informationsmenge.) Also, wenn Sie in haben x.py:

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

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

dann:

>>> import x; help(x)

zeigt an:

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)

Wie Sie sehen, sind die detaillierten Informationen zu den Klassen (und Funktionen, obwohl ich hier keine zeige) bereits in den Dokumentzeichenfolgen dieser Komponenten enthalten. Die eigene Dokumentzeichenfolge des Moduls sollte sie (wenn überhaupt) sehr kurz beschreiben und sich eher auf eine kurze Zusammenfassung dessen konzentrieren, was das Modul als Ganzes für Sie tun kann, idealerweise mit einigen Beispielen (genau wie Funktionen und Klassen im Idealfall Beispiele haben sollten) ihre Dokumente).

Ich sehe nicht, wie Metadaten wie Autorenname und Copyright / Lizenz dem Benutzer des Moduls helfen - es kann eher in Kommentare eingehen, da es jemandem helfen könnte, zu überlegen, ob das Modul wiederverwendet oder geändert werden soll oder nicht.

Um die Spezifikationen zu zitieren :

Die Dokumentzeichenfolge eines Skripts (ein eigenständiges Programm) sollte als "Verwendungsnachricht" verwendet werden können, die gedruckt wird, wenn das Skript mit falschen oder fehlenden Argumenten aufgerufen wird (oder möglicherweise mit der Option "-h" für "Hilfe"). Eine solche Dokumentzeichenfolge sollte die Funktions- und Befehlszeilensyntax, Umgebungsvariablen und Dateien des Skripts dokumentieren. Verwendungsnachrichten können ziemlich aufwendig sein (mehrere Bildschirme sind voll) und sollten ausreichen, damit ein neuer Benutzer den Befehl ordnungsgemäß verwenden kann, sowie eine vollständige Kurzreferenz zu allen Optionen und Argumenten für den anspruchsvollen Benutzer.

Die Dokumentzeichenfolge für ein Modul sollte im Allgemeinen die Klassen, Ausnahmen und Funktionen (und alle anderen Objekte) auflisten , die vom Modul exportiert werden, mit jeweils einer einzeiligen Zusammenfassung. (Diese Zusammenfassungen enthalten im Allgemeinen weniger Details als die Zusammenfassungszeile in der Dokumentzeichenfolge des Objekts.) Die Dokumentzeichenfolge für ein Paket (dh die Dokumentzeichenfolge des Modulmoduls __init__.py) sollte auch die vom Paket exportierten Module und Unterpakete auflisten.

Die Dokumentzeichenfolge für eine Klasse sollte ihr Verhalten zusammenfassen und die öffentlichen Methoden und Instanzvariablen auflisten . Wenn die Klasse für Unterklassen vorgesehen ist und über eine zusätzliche Schnittstelle für Unterklassen verfügt, sollte diese Schnittstelle separat aufgeführt werden (in der Dokumentzeichenfolge). Der Klassenkonstruktor sollte für seine __init__Methode in der Dokumentzeichenfolge dokumentiert sein . Einzelne Methoden sollten durch eine eigene Dokumentationszeichenfolge dokumentiert werden.

Die Dokumentzeichenfolge einer Funktion oder Methode ist eine Phrase, die mit einem Punkt endet. Es schreibt den Effekt der Funktion oder Methode als Befehl vor ("Do this", "Return that"), nicht als Beschreibung. zB schreibe nicht "Gibt den Pfadnamen zurück ...". Eine mehrzeilige Dokumentzeichenfolge für eine Funktion oder Methode sollte ihr Verhalten zusammenfassen und ihre Argumente, Rückgabewerte, Nebenwirkungen, Ausnahmen und Einschränkungen beim Aufrufen dokumentieren (alle, falls zutreffend). Optionale Argumente sollten angegeben werden. Es sollte dokumentiert werden, ob Schlüsselwortargumente Teil der Schnittstelle sind.