Zusammenfassung

Benannte Python-Objekte, wie Module, Klassen und Funktionen, haben ein String-Attribut namens __doc__. Wenn der erste Ausdruck innerhalb der Definition ein literaler String ist, wird dieser String dem __doc__-Attribut zugewiesen.

Das __doc__-Attribut wird als Dokumentationsstring oder Docstring bezeichnet. Es wird oft verwendet, um die Schnittstelle eines Moduls, einer Klasse oder einer Funktion zusammenzufassen. Da es jedoch kein gemeinsames Format für Dokumentationsstrings gibt, sind Werkzeuge zur Extraktion von Docstrings und deren Umwandlung in Dokumentation in einem Standardformat (z. B. DocBook) nicht in Hülle und Fülle entstanden, und die, die existieren, sind meist unverwaltet und ungenutzt.

Perl-Dokumentation

In Perl werden die meisten Module in einem Format namens POD – Plain Old Documentation – dokumentiert. Dies ist ein leicht zu tippendes, sehr niedrigschwelliges Format, das gut mit dem Perl-Parser integriert ist. Viele Werkzeuge existieren, um POD-Dokumentation in andere Formate umzuwandeln: Info, HTML und Manpages, unter anderem. In Perl sind die Informationen jedoch nicht zur Laufzeit verfügbar.

Java-Dokumentation

In Java dienen spezielle Kommentare vor Klassen und Funktionen zur Dokumentation des Codes. Ein Programm zur Extraktion dieser Kommentare und deren Umwandlung in HTML-Dokumentation heißt javadoc und ist Teil der Standard-Java-Distribution. Das einzige unterstützte Ausgabeformat ist jedoch HTML, und JavaDoc hat eine sehr enge Beziehung zu HTML.

Python Docstring-Ziele

Python-Dokumentationsstrings sind beim Parsen leicht zu erkennen und auch dem Laufzeitinterpreter zugänglich. Dieser doppelte Zweck ist manchmal etwas problematisch: Zum Beispiel zögern einige, zu lange Docstrings zu haben, weil sie nicht viel Platz im Laufzeitprogramm einnehmen wollen. Darüber hinaus hat sich aufgrund des derzeitigen Mangels an Werkzeugen die Tendenz entwickelt, Objekte durch "print" ihre Docstrings anzeigen zu lassen, sodass sie kurz und frei von Markups gehalten werden. Diese Tendenz behindert das Schreiben besserer Werkzeuge zur Extraktion von Dokumentationen, da Docstrings wenig Informationen enthalten, die schwer zu parsen sind.

Hochrangige Lösungen

Um dem Einwand entgegenzuwirken, dass die Strings Platz im laufenden Programm einnehmen, wird vorgeschlagen, dass Werkzeuge zur Extraktion von Dokumentationen ein maximales Präfix von String-Literalen verketten, die am Anfang einer Definition erscheinen. Das erste dieser Strings wird auch im interaktiven Interpreter verfügbar sein, sollte also einige zusammenfassende Zeilen enthalten.

Ziele des Docstring-Formats

Dies sind die Ziele für das Docstring-Format, wie sie ad nauseam in der Doc-Sig diskutiert wurden.

1. Es muss mit jedem Standard-Texteditor einfach zu tippen sein.
2. Es muss für den zufälligen Betrachter lesbar sein.
3. Es darf keine Informationen enthalten, die durch Parsen des Moduls abgeleitet werden können.
4. Es muss ausreichend Informationen enthalten, damit es in jedes sinnvolle Markup-Format konvertiert werden kann.
5. Es muss möglich sein, die gesamte Dokumentation eines Moduls in Docstrings zu schreiben, ohne sich durch die Markup-Sprache eingeschränkt zu fühlen.

Inhalt von Docstrings

Für Anforderung 5 ist es notwendig festzulegen, was in Docstrings enthalten sein muss.

Mindestens das Folgende muss verfügbar sein

1. Ein Tag, der bedeutet "Dies ist ein Python-etwas, rate mal"

   Beispiel: Im Satz „Die POP3-Klasse“ müssen wir „POP3“ so markieren. Der Parser kann aus dem Inhalt des Moduls poplib erraten, dass es sich um eine Klasse handelt, aber wir müssen ihn dazu bringen, es zu erraten.

2. Tags, die bedeuten „Dies ist eine Python-Klasse/Modul/Klassenvariable/Instanzvariable…“

   Beispiel: Die übliche Python-Idiomatik für eine Singleton-Klasse A besteht darin, _A als Klasse und A als Funktion zu haben, die _A-Objekte zurückgibt. Es ist üblich, die Klasse dennoch als A zu dokumentieren. Dies erfordert die Fähigkeit zu sagen „Die Klasse A“ und A als Klasse zu hyperlinken und zu markieren.

3. Eine einfache Möglichkeit, Python-Quellcode/Python-Interaktiv-Sitzungen einzufügen
4. Betonung/Fett
5. Listen/Tabellen

Grundlegende Struktur von Docstrings

Die Dokumentationsstrings werden in StructuredTextNG (http://www.zope.org/Members/jim/StructuredTextWiki/StructuredTextNG) geschrieben. Da StructuredText noch nicht stark genug ist, um (a) und (b) oben zu handhaben, müssen wir es erweitern. Ich schlage vor, [<optionale Beschreibung>:python Bezeichner] zu verwenden. Z.B.: [Klasse:POP3], [:POP3.list], etc. Wenn die Beschreibung fehlt, wird aus dem Text eine Vermutung angestellt.

Ungelöste Probleme

Gibt es eine Möglichkeit, Zeichen in ST zu escapen? Wenn ja, wie? (Beispiel: * am Zeilenanfang, ohne ein Aufzählungssymbol zu sein)

Ist mein obiger Vorschlag für Python-Symbole mit ST-NG kompatibel? Wie schwierig wäre es, ST-NG zu erweitern, um dies zu unterstützen?

Wie beschreiben wir Eingabe- und Ausgabetypen von Funktionen?

Welche zusätzlichen Einschränkungen legen wir für jeden Docstring fest (Modul/Klasse/Funktion)?

Was sind die Erklärungsregeln?

Abgelehnte Vorschläge

XML – es ist sehr schwer zu tippen und zu unübersichtlich, um es bequem zu lesen.