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 help
der 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.
help()
Methode im Interpreter verwenden, als Benutzer, die einfach den Code lesen.Um die Spezifikationen zu zitieren :
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.
quelle