Menggunakan javadoc untuk dokumentasi Python [ditutup]

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)

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

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 .

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

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.