Ich beginne derzeit mit Python und habe einen starken PHP-Hintergrund. In PHP habe ich mir angewöhnt, javadoc
als Dokumentationsvorlage zu verwenden.
Ich habe mich gefragt, ob javadoc
es seinen Platz als docstring
Dokumentation in Python hat. Was sind die etablierten Konventionen und / oder offiziellen Gildenlinien hier?
Ist so etwas beispielsweise zu aufwendig, um in die Python-Denkweise zu passen, oder sollte ich versuchen, so präzise wie möglich zu sein?
"""
replaces template place holder with values
@param string timestamp formatted date to display
@param string priority priority number
@param string priority_name priority name
@param string message message to display
@return string formatted string
"""
Und wenn ich etwas zu erschöpfend bin, sollte ich stattdessen so etwas wählen (wo der größte Teil der Dokumentation nicht über die __doc__
Methode gedruckt wird)?
# replaces template place holder with values
#
# @param string timestamp formatted date to display
# @param string priority priority number
# @param string priority_name priority name
# @param string message message to display
#
# @return string formatted string
def format(self, timestamp = '', priority = '', priority_name = '', message = ''):
"""
replaces template place holder with values
"""
values = {'%timestamp%' : timestamp,
'%priorityName%' : priority_name,
'%priority%' : priority,
'%message%' : message}
return self.__pattern.format(**values)
python
documentation
javadoc
docstring
JF Dion
quelle
quelle
Antworten:
Schauen Sie sich das Format reStructuredText (auch als "reST" bekannt) an, ein Klartext- / Docstring-Markup-Format, das wahrscheinlich das beliebteste in der Python-Welt ist. Und Sie sollten sich unbedingt Sphinx ansehen , ein Tool zum Generieren von Dokumentation aus reStructuredText (das z. B. für die Python-Dokumentation selbst verwendet wird). Sphinx schließt die Möglichkeit zu extrahieren Dokumentation aus den Docstrings in Ihrem Code (siehe sphinx.ext.autodoc ) und erkennt reST Feldlisten nach bestimmten Konventionen. Dies ist wahrscheinlich der beliebteste Weg, dies zu tun (oder wird es auch).
Ihr Beispiel könnte wie folgt aussehen:
Oder erweitert mit Typinformationen:
quelle
Replace template place holder with values.
stattreplaces template place holder with values
- Beachten Sie den Satz, den Großbuchstaben am Anfang und den Punkt (.) Am Ende.sphinx.ext.napoleon
Erweiterung auch ein etwas besseres Format .Folgen Sie dem Google Python Style Guide . Beachten Sie, dass Sphinx dieses Format auch mit der Napolean- Erweiterung analysieren kann , die mit Sphinx 1.3 geliefert wird (dies ist auch mit PEP257 kompatibel ):
Beispiel aus der oben verlinkten napoleonischen Dokumentation.
Ein umfassendes Beispiel für alle Arten von Dokumentzeichenfolgen hier .
quelle
Der Standard für Python-Dokumentationszeichenfolgen ist in Python Enhancement Proposal 257 beschrieben .
Der passende Kommentar für Ihre Methode wäre so etwas wie
quelle
Schauen Sie sich Documenting Python an , eine Seite "für Autoren und potenzielle Autoren von Python-Dokumentationen".
Kurz gesagt, reStructuredText wird zur Dokumentation von Python selbst verwendet. Das Entwicklerhandbuch enthält einen reST-Primer, einen Styleguide und allgemeine Hinweise zum Schreiben einer guten Dokumentation.
quelle