Menggunakan javadoc untuk dokumentasi Python [ditutup]

162

Saya saat ini mulai dengan Python dan saya memiliki latar belakang PHP yang kuat dan dalam PHP saya telah terbiasa menggunakan javadoctemplate dokumentasi.

Saya bertanya-tanya apakah javadoctempatnya sebagai docstringdokumentasi dalam Python. Apa konvensi dan / atau guildeline resmi yang ada di sini?

Misalnya apakah sesuatu seperti ini terlalu rumit untuk dimasukkan ke dalam pola pikir Python atau haruskah saya mencoba untuk sesingkat mungkin?

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

Dan jika saya sedikit terlalu lengkap haruskah saya pergi dengan sesuatu seperti ini sebagai gantinya (di mana sebagian besar dokumentasi tidak bisa dicetak melalui __doc__metode ini)?

# 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
sumber
6
Thera juga banyak lagi jawaban untuk ini di pertanyaan sebelumnya yang merupakan duplikat.
Alex Dupuy
Kemungkinan rangkap dari Apa format dokumentasi standar Python?
zvone

Jawaban:

227

Lihatlah format reStructuredText (juga dikenal sebagai "reST"), yang merupakan format markup plaintext / docstring, dan mungkin yang paling populer di dunia Python. Dan Anda tentu harus melihat Sphinx , alat untuk menghasilkan dokumentasi dari reStructuredText (digunakan untuk misalnya dokumentasi Python itu sendiri). Sphinx mencakup kemungkinan untuk mengekstrak dokumentasi dari dokumen dalam kode Anda (lihat sphinx.ext.autodoc ), dan mengenali daftar bidang reST mengikuti konvensi tertentu. Ini mungkin menjadi (atau menjadi) cara paling populer untuk melakukannya.

Contoh Anda dapat terlihat sebagai berikut:

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

Atau diperluas dengan informasi jenis:

"""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
sumber
7
apa yang Anda lakukan jika Anda perlu memutuskan garis untuk deskripsi panjang? Bagaimana kelihatannya?
Skylar Saveland
6
Lihat referensi reStructuredText, dan daftar bidang khususnya: docutils.sourceforge.net/docs/ref/rst/…
Steven
6
Perhatikan bahwa cara frasa di sini tidak sesuai dengan PEP 257 . Seharusnya Replace template place holder with values.bukan replaces template place holder with values- Perhatikan kalimat, huruf besar di awal, dan berhenti penuh (.) Di akhir.
kratenko
1
Dari versi 1.3, Sphinx juga mendukung format yang sedikit lebih baik melalui sphinx.ext.napoleonekstensi.
Petri
3
Dapatkah seseorang tolong tunjukkan saya pada dokumentasi terbaik yang menetapkan dokumen khusus ini seperti ": param ____:" dan ": returns:"? Dokumen semacam itu tampaknya agak sulit ditemukan saat ini.
krumpelstiltskin
75

Ikuti Google Python Style Guide . Perhatikan bahwa Sphinx juga dapat mem-parsing format ini menggunakan ekstensi Napolean , yang akan dikemas dengan Sphinx 1.3 (ini juga kompatibel dengan PEP257 ):

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

Contoh diambil dari dokumentasi Napolean yang ditautkan di atas.

Contoh komprehensif tentang semua jenis dokumen di sini .

Bingung00
sumber
20
untuk semua manusia di luar sana yang membaca dokumen
Waylon Flinn
1
Diperbarui tautan Google Python Style Guide
confused00
@ Bingung00 bagaimana saya bisa mendokumentasikan bahwa metode saya mengembalikan array objek?
Cito
1
Sekarang saya bingung! args atau params? stackoverflow.com/questions/1788923/parameter-vs-argument
shuva
25

Standar untuk string dokumentasi python dijelaskan dalam Python Enhancement Proposal 257 .

Komentar yang sesuai untuk metode Anda akan seperti

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
sumber
17
PEP257 tidak memberi tahu apa-apa tentang pemformatan bagian argumen yang sebenarnya. Itu hanya menyatakan bahwa itu harus ditulis, dan memberikan contoh. Tapi ini hanya sebuah contoh. Oleh karena itu, saya akan menyarankan menggunakan konvensi Sphinx, karena Anda tidak melanggar PEP257 dan Anda menggunakan format yang dapat diuraikan oleh sphinx.
vaab
7
Kecuali dokumentasi pertama yang disajikan di atas jelek dan memiliki banyak informasi yang berlebihan bagi manusia. Saya lebih suka menggunakan konvensi yang membuat kode sumber saya menyenangkan untuk dibaca tanpa diuraikan terlebih dahulu
confused00
1

Lihatlah Documenting Python , halaman "yang ditujukan untuk penulis dan penulis potensial dokumentasi untuk Python."

Singkatnya, reStructuredText adalah apa yang digunakan untuk mendokumentasikan Python itu sendiri. Panduan pengembang berisi primer REST, panduan gaya, dan saran umum untuk menulis dokumentasi yang baik.

David Cain
sumber