it-swarm.com.de

Wie dokumentiere ich eine Methode mit Parametern?

Wie werden Methoden mit Parametern mithilfe von Pythons Dokumentationszeichenfolgen dokumentiert?

EDIT: PEP 257 gibt dieses Beispiel an:

def complex(real=0.0, imag=0.0):
    """Form a complex number.

    Keyword arguments:
    real -- the real part (default 0.0)
    imag -- the imaginary part (default 0.0)

    """
    if imag == 0.0 and real == 0.0: return complex_zero
    ...

Wird diese Konvention von den meisten Python Entwicklern verwendet?

Keyword arguments:
<parameter name> -- Definition (default value if any)

Ich hatte etwas etwas Formaleres erwartet wie

def complex(real=0.0, imag=0.0):
    """Form a complex number.

    @param: real The real part (default 0.0)
    @param: imag The imaginary part (default 0.0)

    """
    if imag == 0.0 and real == 0.0: return complex_zero
    ...

Umgebung : Python 2.7.1

119

Nach meiner Erfahrung sind die Numpy Docstring Conventions (PEP257 Superset) die am weitesten verbreiteten befolgten Konventionen, die ebenfalls unterstützt werden durch Werkzeuge wie Sphinx .

Ein Beispiel:

Parameters
----------
x : type
    Description of parameter `x`.
76

Da es sich bei Docstrings um Freiform handelt, hängt es wirklich davon ab, wie Sie den Code zum Generieren der API-Dokumentation analysieren.

Ich würde empfehlen, sich mit dem Sphinx-Markup vertraut zu machen, da es weit verbreitet ist und zum De-facto-Standard für die Dokumentation von Python) - Projekten wird readthedocs.org service. To mschreiben eines Beispiels from the Sphinx documentation as Python snippet:

def send_message(sender, recipient, message_body, priority=1):
   '''
   Send a message to a recipient

   :param str sender: The person sending the message
   :param str recipient: The recipient of the message
   :param str message_body: The body of the message
   :param priority: The priority of the message, can be a number 1-5
   :type priority: integer or None
   :return: the message id
   :rtype: int
   :raises ValueError: if the message_body exceeds 160 characters
   :raises TypeError: if the message_body is not a basestring
   '''

Dieses Markup unterstützt Querverweise zwischen Dokumenten und mehr. Beachten Sie, dass in der Sphinx-Dokumentation (z. B.) :py:attr: Verwendet wird, während Sie beim Dokumentieren aus dem Quellcode nur :attr: Verwenden können.

Natürlich gibt es auch andere Tools, um APIs zu dokumentieren. Es gibt den klassischeren Doxygen , der \paramBefehle verwendet, aber diese sind nicht speziell dafür ausgelegt, Python Code wie Sphinx zu dokumentieren .

Beachten Sie, dass es hier eine ähnliche Frage mit einer ähnliche Antwort gibt ...

87
anarcat

Konventionen:

Werkzeuge:


Update: Seit Python 3.5 können Sie Tippfehler verwenden, eine kompakte, maschinenlesbare Syntax:

from typing import Dict, Union

def foo(i: int, d: Dict[str, Union[str, int]]) -> int:
    """
    Explanation: this function takes two arguments: `i` and `d`.
    `i` is annotated simply as `int`. `d` is a dictionary with `str` keys
    and values that can be either `str` or `int`.

    The return type is `int`.

    """

Der Hauptvorteil dieser Syntax besteht darin, dass sie durch die Sprache definiert und eindeutig ist, sodass Tools wie PyCharm leicht davon profitieren können.

32
Jakub

python-Doc-Strings sind Freiform, Sie können es auf jede beliebige Weise dokumentieren.

Beispiele:

def mymethod(self, foo, bars):
    """
    Does neat stuff!
    Parameters:
      foo - a foo of type FooType to bar with.
      bars - The list of bars
    """

Nun gibt es einige Konventionen, aber python erzwingt keine von ihnen. Einige Projekte haben ihre eigenen Konventionen. Einige Tools für die Arbeit mit Dokumentzeichenfolgen folgen auch bestimmten Konventionen.

10
nosklo

Wenn Sie vorhaben, Ihren Code mit Sphinx zu dokumentieren, können Sie gut formatierte HTML-Dokumente für Ihre Parameter mit der Funktion "Signaturen" erstellen. http://sphinx-doc.org/domains.html#signatures

8
Kyle Mede

Der Mainstream ist, wie andere Antworten hier bereits gezeigt haben, wahrscheinlich der Sphinx-Weg , damit Sie diese ausgefallenen Dokumente später mit Sphinx generieren können.

Abgesehen davon, ich persönlich gehe gelegentlich mit Inline-Kommentar-Stil.

def complex(  # Form a complex number
        real=0.0,  # the real part (default 0.0)
        imag=0.0  # the imaginary part (default 0.0)
        ):  # Returns a complex number.
    """Form a complex number.

    I may still use the mainstream docstring notation,
    if I foresee a need to use some other tools
    to generate an HTML online doc later
    """
    if imag == 0.0 and real == 0.0:
        return complex_zero
    other_code()

Ein weiteres Beispiel hier, mit ein paar kleinen Details, die inline dokumentiert sind:

def foo(  # Note that how I use the parenthesis rather than backslash "\"
          # to natually break the function definition into multiple lines.
        a_very_long_parameter_name,
            # The "inline" text does not really have to be at same line,
            # when your parameter name is very long.
            # Besides, you can use this way to have multiple lines doc too.
            # The one extra level indentation here natually matches the
            # original Python indentation style.
            #
            # This parameter represents blah blah
            # blah blah
            # blah blah
        param_b,  # Some description about parameter B.
            # Some more description about parameter B.
            # As you probably noticed, the vertical alignment of pound sign
            # is less a concern IMHO, as long as your docs are intuitively
            # readable.
        last_param,  # As a side note, you can use an optional comma for
                     # your last parameter, as you can do in multi-line list
                     # or dict declaration.
        ):  # So this ending parenthesis occupying its own line provides a
            # perfect chance to use inline doc to document the return value,
            # despite of its unhappy face appearance. :)
    pass

Die Vorteile (auf die @ mark-horvath bereits in einem anderen Kommentar hingewiesen hat) sind:

  • Am wichtigsten ist, dass die Parameter und ihr Dokument immer zusammen bleiben, was die folgenden Vorteile mit sich bringt:
  • Weniger Tippen (keine Notwendigkeit, den Variablennamen zu wiederholen)
  • Einfachere Wartung beim Ändern/Entfernen von Variablen. Nachdem Sie einen Parameter umbenannt haben, wird es niemals einen Orphan-Parameter-Doc-Absatz geben.
  • und leichter zu fehlenden Kommentar zu finden.

Nun mögen einige denken, dieser Stil sieht "hässlich" aus. Aber ich würde sagen "hässlich" ist ein subjektives Wort. Eine eher neutrale Art zu sagen ist, dass dieser Stil kein Mainstream ist, so dass er für Sie weniger vertraut und daher weniger bequem erscheint. Auch hier ist "gemütlich" ein subjektives Wort. Der springende Punkt ist jedoch, dass alle oben beschriebenen Vorteile objektiv sind. Sie können sie nicht erreichen, wenn Sie dem Standard folgen.

Hoffentlich wird es eines Tages ein Dokumentgenerator-Tool geben, das auch einen solchen Inline-Stil verwenden kann. Das wird die Annahme vorantreiben.

PS: Diese Antwort ergibt sich aus meiner Präferenz, Inline-Kommentare zu verwenden, wann immer ich es für richtig halte. Ich benutze auch den gleichen Inline-Stil, um ein Wörterbuch zu dokumentieren .

2
RayLuo

Dokumentzeichenfolgen sind nur in interaktiven Umgebungen nützlich, z. the Python Shell. Wenn Sie Objekte dokumentieren, die nicht interaktiv verwendet werden sollen (z. B. interne Objekte, Framework-Rückrufe), können Sie auch reguläre Kommentare verwenden Aus Elemente, jedes in einer eigenen Zeile, damit Sie wissen, dass der Kommentar gilt für:

def Recomputate \
  (
    TheRotaryGyrator,
      # the rotary gyrator to operate on
    Computrons,
      # the computrons to perform the recomputation with
    Forthwith,
      # whether to recomputate forthwith or at one's leisure
  ) :
  # recomputates the specified rotary gyrator with
  # the desired computrons.
  ...
#end Recomputate

Mit Docstrings können Sie so etwas nicht machen.

0