Migration von Javadoc zu Python-Dokumentation

Question

So etwas verwendet, ich habe zu Javadoc Stil Dokumentation bekommen. Beim Blick durch verschiedene Beispiele für Python-Code, ich finde, dass auf den ersten Blick, die Dokumentation scheint zu viele Informationen fehlen.

Die gute: variieren selten tun Sie selbstverständlich Bits Dokumentation. Docstrings ist in der Regel ein Absatz oder weniger Englisch Markup dass integriert statt stehend auf separate Zeilen.

Die schlechte: in Verbindung mit Python Ente-Typisierung, finde ich, dass viele Funktionen unklar sind über die Parameter, die sie erwarten. Es gibt keine Art Hinting (Ente-Hinting?) Und oft wäre es schön, eine Idee zu haben, dass der Parameter sein sollte Liste artig, schnurartige, Strom-like.

Natürlich Javadoc wurde für eine untergeordnete Sprache entworfen, ohne große Selbstbeobachtung Fähigkeiten von Python, die für die weniger ausführliche Dokumentation Philosophie erklären könnte.

Jede Beratung über Python Dokumentationsstandards und Best Practices?

Answer 1

Das reStructuredText Format wurde als Reaktion auf die Notwendigkeit für Python-Dokumentation entwickelt, die in eingebettet werden könnten Docstrings, so das beste, was zu ist lernen reST und Ihre Docstrings Format mit diesem Format . Vielleicht finden Sie, wie ich, dass Sie dann auf Format gehen nur über jeder Dokumentation in Ruhe, aber das ist ein Nebenpunkt: -)

Für Ihren Python-Code speziell zu dokumentieren, das Sphinx System ist eine Reihe von Erweiterungen des reST Format und ein Build-System für Dokumente zu machen. Da es zu dokumentieren Python selbst entwickelt wurde, einschließlich der Standard-Bibliothek, Sphinx für sehr gut strukturierte Dokumentation des Quellcodes ermöglicht , darunter natürlich auch die Besonderheiten der Funktionssignaturen wie Sie fragen. Es ermöglicht eine umfassende Dokumentation Suite sowohl Auto-extrahierte und von Hand geschrieben, die alle mit dem gleichen Formatierungssystem aufgebaut, werden.

Wenn Sie nur wollen Dokumentation erzeugt aus dem Quellcode, dann Epydoc wird die API-Dokumentation aus dem Quellcode extrahiert ; Auch er liest reST für die Textformatierung.