Javadoc'u Python belgeleri için kullanma [kapalı]

Şu anda Python ile başlıyorum ve güçlü bir PHP arka planım var ve PHP'de javadocbir belge şablonu olarak kullanma alışkanlığını aldım .

Python'da belge javadocolarak yeri olup olmadığını merak ediyordum docstring. Buradaki yerleşik sözleşmeler ve / veya resmi guildeline'lar nelerdir?

Bunun gibi bir şey Python zihniyetine sığmayacak kadar ayrıntılı mı yoksa mümkün olduğunca özlü olmaya çalışmalı mıyım?

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

Ve biraz fazla kapsamlı olursam, bunun gibi bir şeyle gitmeliyim (belgelerin çoğunun __doc__yöntemle yazdırılmadığı yer )?

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

Düz metin / docstring biçimlendirme biçimi olan ve muhtemelen Python dünyasında en popüler olan reStructuredText ("reST" olarak da bilinir) biçimine bir göz atın . Ve kesinlikle bakmak gerekir Sfenks , reStructuredText gelen belgeleri oluşturmak için bir araç (örn için de kullanılır. Python belgelerine kendisi). Sfenks, kodunuzdaki docstrings'den doküman çıkarma imkanına sahiptir (bkz. Sphinx.ext.autodoc ) ve belirli kuralları izleyerek reST alan listelerini tanır . Bu muhtemelen bunu yapmanın en popüler yolu haline gelmiştir (ya da haline gelmektedir).

Örneğiniz aşağıdaki gibi görünebilir:

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

Veya tür bilgisi ile genişletilmiş:

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

Google Python Stil Kılavuzunu izleyin . Sphinx'in bu formatı Sphinx 1.3 ile birlikte gelen Napolean uzantısını kullanarak da ayrıştırabileceğini unutmayın (bu aynı zamanda PEP257 ile de uyumludur ):

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

Örnek, yukarıda bağlantılı Napolean belgelerinden alınmıştır.

Burada her tür öğretiye kapsamlı bir örnek .

Python belge dizeleri standardı Python Geliştirme Önerisi 257'de açıklanmıştır .

Metodunuz için uygun yorum,

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

Dokümanlama Python'una bir göz atın , bir sayfa "yazarlar ve Python belgelerine potansiyel yazarlar amaçlayan".

Kısacası, reStructuredText , Python'un kendisini belgelemek için kullanılan şeydir. Geliştirici kılavuzunda bir reST primeri, stil kılavuzu ve iyi dokümantasyon yazmak için genel tavsiyeler bulunur.