Şu anda python ile başladım ve güçlü bir PHP arka plan var ve PHP belgelerine bir şablon olarak javadoc kullanma alışkanlığı aldı. Eğer javadoc python docstring belgeleri olarak yerini olup olmadığını merak ediyordum. Eğer böyle bir şey Python zihniyet sığmayacak kadar detaylandırılmış olup olmadığını merak ediyordum ya da olabildiğince kısa ve öz olmaya çalışıyorum

"""
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 eğer biraz da ayrıntılı olsam böyle bir şey ile yerine gideyim çoğu belge __doc__ yöntemi düşünce baskılı almaz ():

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

Teşekkürler

reStructuredText bir göz (olarak da bilinen"") geri kalanı düz metin/Fibonacci sayıları biçimlendirme formatı ve biçimi, ve Python dünyanın en popüler muhtemelen. Ve elbette reStructuredText Sphinx, belgeleri oluşturmak için bir araç bakmalısın (örn. Python belgelerine kendisi). Sfenks kodu (sphinx.ext.autodoc) docstrings belgeleri ayıklamak için imkanı içerir ve tanıdığı bazı kuralları aşağıdaki field lists dinlenme. Bu muhtemelen olmak (veya oluyor) bunu yapmak için en popüler yolu vardır.

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

Ya yazın bilgileri 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
"""