Heim >Backend-Entwicklung >Python-Tutorial >Schreibstil für mehrzeilige Kommentardokumente in Python
Was ist Docstring?
In der Softwareentwicklung spielt das Codieren tatsächlich eine sehr kleine Rolle, hauptsächlich andere Dinge, wie zum Beispiel das Schreiben von Dokumenten. Dokumente sind Werkzeuge der Kommunikation.
In Python wird dringend empfohlen, Dokumente im Code zu schreiben, was bequemer, einfacher zu warten, intuitiver und konsistenter ist.
Der Code ist geschrieben und die Dokumentation ist verfügbar. Tatsächlich hat Markdown ähnliche Ideen. Nachdem der Text geschrieben wurde, ist auch der Satz abgeschlossen.
Sehen Sie sich die Definition von Docstring in PEP 0257 an:
Ein Docstring ist ein String-Literal, das als erste Anweisung in
einer Modul-, Funktions-, Klassen- oder Methodendefinition wird zum speziellen __doc__-Attribut dieses Objekts.
Einfach ausgedrückt ist die erste Anweisung, die in einem Modul, einer Funktion, einer Klasse oder einer Methode erscheint, der Docstring. Es wird automatisch zum Attribut __doc__.
def foo(): """ This is function foo"""kann über foo.__doc__ aufgerufen werden, um „Dies ist Funktion foo“ zu erhalten.Verschiedene Dokumentzeichenfolgenstile:
Epytext
Dies war einst ein beliebter Stil, ähnlich wie Javadoc.""" This is a javadoc style. @param param1: this is a first param @param param2: this is a second param @return: this is a description of what is returned @raise keyError: raises an exception """
reST
Dies ist jetzt ein beliebter Stil, reST-Stil, das königliche Format von Sphinx. Ich persönlich verwende auch gerne diesen Stil, der kompakter ist.""" This is a reST style. :param param1: this is a first param :param param2: this is a second param :returns: this is a description of what is returned :raises keyError: raises an exception """
Google-Stil
""" This is a groups style docs. Parameters: param1 - this is the first param param2 - this is a second param Returns: This is a description of what is returned Raises: KeyError - raises an exception """
Numpydoc (Numpy-Stil)
""" My numpydoc description of a kind of very exhautive numpydoc format docstring. Parameters ---------- first : array_like the 1st param name `first` second : the 2nd param third : {'value', 'other'}, optional the 3rd param, by default 'value' Returns ------- string a value in a string Raises ------ KeyError when a key error OtherError when an other error """
Docstring-Tool, Bibliothek von Drittanbietern, Pyment
Wird zum Erstellen und Konvertieren von Dokumentzeichenfolgen verwendet.Die Verwendungsmethode besteht darin, mit pyment einen Patch zu generieren und den Patch dann anzuwenden.
$ pyment test.py #生成patch $ patch -p1 < test.py.patch #打patchDetails: https://github.com/dadadel/pymentVerwenden Sie Sphinx's Autodoc, um automatisch API-Dokumentation aus Docstring zu erstellen , es ist nicht nötig, es noch einmal von Hand zu schreiben Ich habe die Dokumentzeichenfolge bereits in den Code geschrieben. Der Inhalt des API-Dokuments ist ähnlich wie folgt: Muss ich es zuerst einzeln kopieren? Natürlich nicht. Sphinx verfügt über eine Autodoc-Funktion.
Bearbeiten Sie zuerst die Datei conf.py,
1. Es müssen die Erweiterungen „sphinx.ext.autodoc“ vorhanden sein.
2 Stellen Sie sicher, dass das Modul, das die Dokumentation automatisch generieren muss, importiert werden kann , es ist im Weg. Beispielsweise benötigen Sie möglicherweise sys.path.insert(0, os.path.abspath('../..'))
xxx_api module --------------------- .. automodule:: xxx_api :members: :undoc-members: :show-inheritance:Geben Sie den Befehl „make html“ ein, um relevante Dokumente aus dem Dokumentstring zu generieren, ohne zuerst von Hand schreiben zu müssen:
Weitere Artikel zum mehrzeiligen Kommentardokument-Schreibstil in Python finden Sie auf der chinesischen PHP-Website!