Verwenden von Javadoc für die Python-Dokumentation [geschlossen]

162

Ich beginne derzeit mit Python und habe einen starken PHP-Hintergrund. In PHP habe ich mir angewöhnt, javadocals Dokumentationsvorlage zu verwenden.

Ich habe mich gefragt, ob javadoces seinen Platz als docstringDokumentation 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)
JF Dion
quelle
6
Es gibt auch viele weitere Antworten auf diese Frage, bei der es sich um ein Duplikat handelt.
Alex Dupuy

Antworten:

227

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:

"""Replaces template placeholder with values.

:param timestamp: formatted date to display
:param priority: priority number
:param priority_name: priority name
:param message: message to display
:returns: formatted string
"""

Oder erweitert mit Typinformationen:

"""Replaces template placeholder with values.

:param timestamp: formatted date to display
:type timestamp: str or unicode
:param priority: priority number
:type priority: str or unicode
:param priority_name: priority name
:type priority_name: str or unicode
:param message: message to display
:type message: str or unicode
:returns: formatted string
:rtype: str or unicode
"""
Steven
quelle
7
Was tun Sie, wenn Sie für eine lange Beschreibung eine Zeile unterbrechen müssen? Wie würde das aussehen?
Skylar Saveland
6
Siehe reStructuredText-Referenz und insbesondere Feldlisten
Steven
6
Beachten Sie, dass die Art und Weise, wie die Sätze hier sind, nicht PEP 257 entspricht . Es sollte Replace template place holder with values.statt replaces template place holder with values- Beachten Sie den Satz, den Großbuchstaben am Anfang und den Punkt (.) Am Ende.
Kratenko
1
Ab Version 1.3 unterstützt Sphinx über die sphinx.ext.napoleonErweiterung auch ein etwas besseres Format .
Petri
3
Könnte mich bitte jemand auf die beste Dokumentation verweisen, in der diese speziellen Dokumentzeichenfolgen wie ": param ____:" und ": return:" angegeben sind? Ein solches Dokument scheint im Moment ziemlich schwer zu finden.
Krumpelstilzchen
75

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 ):

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Args:
        arg1 (int): Description of arg1
        arg2 (str): Description of arg2

    Returns:
        bool: Description of return value

    """
    return True

Beispiel aus der oben verlinkten napoleonischen Dokumentation.

Ein umfassendes Beispiel für alle Arten von Dokumentzeichenfolgen hier .

verwirrt00
quelle
20
für alle Menschen da draußen, die Docstrings lesen
Waylon Flinn
1
Aktualisiert den Google Python Style Guide Link
confused00
@used00 Wie kann ich dokumentieren, dass meine Methode ein Array von Objekten zurückgibt?
Cito
1
Jetzt bin ich verwirrt ! Argumente oder Parameter? stackoverflow.com/questions/1788923/parameter-vs-argument
shuva
25

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

def format(...):
    """Return timestamp string with place holders replaced with values.

    Keyword arguments:
    timestamp     -- the format string (default '')
    priority      -- priority number (default '')
    priority_name -- priority name (default '')
    message       -- message to display (default '')
    """
srgerg
quelle
17
PEP257 sagt nichts über die tatsächliche Formatierung des Argumentteils aus. Es heißt nur, dass es geschrieben werden sollte, und gibt ein Beispiel. Dies ist jedoch nur ein Beispiel. Daher würde ich definitiv empfehlen, die Sphinx-Konvention zu verwenden, da Sie PEP257 nicht brechen und eine Formatierung verwenden, die von Sphinx analysiert werden könnte.
Vaab
7
Außer dass die erste oben dargestellte Dokumentation hässlich ist und viele redundante Informationen für Menschen enthält. Ich würde eher eine Konvention verwenden, meine macht Quellcode angenehm , ohne zu lesen , zuerst analysiert werden
confused00
1

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.

David Cain
quelle