Bagaimana cara mendokumentasikan metode dengan parameter?

Bagaimana cara mendokumentasikan metode dengan parameter menggunakan string dokumentasi Python?

EDIT: PEP 257 memberikan contoh ini:

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

Apakah ini konvensi yang digunakan oleh sebagian besar pengembang Python?

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

Saya mengharapkan sesuatu yang sedikit lebih formal seperti

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

Lingkungan : Python 2.7.1

Berdasarkan pengalaman saya, konvensi docstring numpy (superset PEP257) adalah konvensi yang diikuti paling banyak tersebar yang juga didukung oleh alat, seperti Sphinx .

Satu contoh:

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

Karena docstring adalah bentuk bebas, itu sangat bergantung pada apa yang Anda gunakan untuk mengurai kode untuk menghasilkan dokumentasi API.

Saya akan merekomendasikan untuk terbiasa dengan markup Sphinx , karena ini banyak digunakan dan menjadi standar de-facto untuk mendokumentasikan proyek Python, sebagian karena layanan readthedocs.org yang sangat baik . Untuk memparafrasekan contoh dari dokumentasi Sphinx sebagai cuplikan Python:

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

Markup ini mendukung referensi silang antar dokumen dan lainnya. Perhatikan bahwa dokumentasi Sphinx menggunakan (mis.) :py:attr:Sedangkan Anda hanya dapat menggunakannya :attr:saat mendokumentasikan dari kode sumber.

Secara alami, ada alat lain untuk mendokumentasikan API. Ada Doxygen yang lebih klasik yang menggunakan \param perintah tetapi tidak dirancang khusus untuk mendokumentasikan kode Python seperti Sphinx.

Perhatikan bahwa ada pertanyaan serupa dengan jawaban serupa di sini ...

Konvensi:

• PEP 257 Konvensi Docstring
• PEP 287 Format Docstring reStructuredText

Alat:

• Epydoc: Pembuatan Dokumentasi API Otomatis untuk Python
• sphinx.ext.autodoc - Sertakan dokumentasi dari docstrings
• PyCharm memiliki beberapa dukungan bagus untuk docstrings

Pembaruan: Sejak Python 3.5 Anda dapat menggunakan petunjuk tipe yang merupakan sintaks yang ringkas dan dapat dibaca mesin:

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`.

    """

Keuntungan utama dari sintaks ini adalah bahwa ia ditentukan oleh bahasa dan tidak ambigu, jadi alat seperti PyCharm dapat dengan mudah memanfaatkannya.

string doc python adalah bentuk bebas , Anda dapat mendokumentasikannya sesuka Anda.

Contoh:

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

Sekarang, ada beberapa konvensi, tapi python tidak memberlakukan satupun. Beberapa proyek memiliki konvensi sendiri. Beberapa alat untuk bekerja dengan docstrings juga mengikuti konvensi tertentu.

Jika Anda berencana menggunakan Sphinx untuk mendokumentasikan kode Anda, Sphinx mampu menghasilkan dokumen HTML yang diformat dengan baik untuk parameter Anda dengan fitur 'tanda tangan' mereka. http://sphinx-doc.org/domains.html#signatures

Yang utama adalah, seperti jawaban lain yang telah ditunjukkan di sini, mungkin menggunakan cara Sphinx sehingga Anda dapat menggunakan Sphinx untuk menghasilkan dokumen mewah itu nanti.

Karena itu, saya secara pribadi menggunakan gaya komentar sebaris kadang-kadang.

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

Satu contoh lagi di sini, dengan beberapa detail kecil yang didokumentasikan secara inline:

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

Manfaatnya (seperti yang telah ditunjukkan @ mark-horvath di komentar lain) adalah:

• Yang terpenting, parameter dan dokumennya selalu bersama, yang memberikan manfaat berikut:
• Lebih sedikit mengetik (tidak perlu mengulang nama variabel)
• Perawatan lebih mudah setelah mengubah / menghapus variabel. Tidak akan pernah ada beberapa paragraf doc parameter yatim setelah Anda mengganti nama beberapa parameter.
• dan lebih mudah menemukan komentar yang hilang.

Sekarang, beberapa mungkin berpikir gaya ini terlihat "jelek". Tapi saya akan mengatakan "jelek" adalah kata subjektif. Cara yang lebih netral adalah mengatakan, gaya ini tidak mainstream sehingga mungkin terlihat kurang familiar bagi Anda, sehingga kurang nyaman. Sekali lagi, "nyaman" juga merupakan kata subjektif. Tetapi intinya adalah, semua manfaat yang dijelaskan di atas bersifat obyektif. Anda tidak dapat mencapainya jika Anda mengikuti cara standar.

Mudah-mudahan suatu saat nanti akan ada tool doc generator yang juga bisa menggunakan inline style seperti itu. Itu akan mendorong adopsi.

PS: Jawaban ini berasal dari preferensi saya sendiri untuk menggunakan komentar sebaris kapan pun saya mau. Saya menggunakan gaya sebaris yang sama untuk mendokumentasikan kamus juga.

Berdasarkan jawaban petunjuk tipe ( https://stackoverflow.com/a/9195565/2418922 ), yang menyediakan cara terstruktur yang lebih baik untuk mendokumentasikan jenis parameter, terdapat juga cara terstruktur untuk mendokumentasikan jenis dan deskripsi parameter:

def copy_net(
    infile: (str, 'The name of the file to send'),
    host: (str, 'The host to send the file to'),
    port: (int, 'The port to connect to')):

    pass

contoh diadopsi dari: https://pypi.org/project/autocommand/

Docstring hanya berguna dalam lingkungan interaktif, misalnya shell Python. Saat mendokumentasikan objek yang tidak akan digunakan secara interaktif (misalnya objek internal, callback kerangka kerja), Anda mungkin juga menggunakan komentar biasa. Berikut adalah gaya yang saya gunakan untuk menggantungkan komentar yang menjorok ke luar item, masing-masing di barisnya sendiri, sehingga Anda tahu bahwa komentar tersebut berlaku untuk:

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

Anda tidak dapat melakukan hal semacam ini dengan docstrings.