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

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)

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
"""

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 .

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 '')
    """

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.