Używanie javadoc do dokumentacji Pythona [zamknięte]

Obecnie zaczynam od Pythona i mam solidne podstawy PHP, aw PHP przyzwyczaiłem się używać javadocjako szablonu dokumentacji.

Zastanawiałem się, czy javadocma swoje miejsce jako docstringdokumentacja w Pythonie. Jakie są tutaj ustalone konwencje i / lub oficjalne gildie?

Np. Czy coś takiego jest zbyt skomplikowane, aby pasowało do sposobu myślenia Pythona, czy powinienem starać się być tak zwięzły, jak to tylko możliwe?

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

A jeśli jestem trochę zbyt wyczerpujący, powinienem zamiast tego wybrać coś takiego (gdzie większość dokumentacji nie jest drukowana za pomocą tej __doc__metody)?

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

Przyjrzyj się formatowi reStructuredText (znanemu również jako „reST”), który jest formatem znaczników zwykłego tekstu / dokumentu i prawdopodobnie najpopularniejszym w świecie Pythona. I na pewno powinieneś spojrzeć na Sphinx , narzędzie do generowania dokumentacji z reStructuredText (używane np. Do samej dokumentacji Pythona). Sphinx zawiera możliwość wyodrębnienia dokumentacji z dokumentów w Twoim kodzie (zobacz sphinx.ext.autodoc ) i rozpoznaje listy pól reST zgodnie z określonymi konwencjami. Prawdopodobnie stało się to (lub staje się) najpopularniejszym sposobem na zrobienie tego.

Twój przykład mógłby wyglądać następująco:

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

Lub rozszerzone o informacje o typie:

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

Postępuj zgodnie z przewodnikiem Google Python Style Guide . Zauważ, że Sphinx może również analizować ten format przy użyciu rozszerzenia Napolean , które będzie dostarczane z Sphinx 1.3 (jest również kompatybilne z 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

Przykład zaczerpnięty z dokumentacji napolskiej, do której link podano powyżej.

Obszerny przykład na wszystkich typach docstrings tutaj .

Standard ciągów dokumentacji w języku Python opisano w propozycji ulepszeń języka Python 257 .

Odpowiednim komentarzem do twojej metody byłoby coś w stylu

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

Spójrz na Documenting Python , stronę „skierowaną do autorów i potencjalnych autorów dokumentacji dla Pythona”.

Krótko mówiąc, reStructuredText służy do dokumentowania samego Pythona. Przewodnik programisty zawiera elementarz reST, przewodnik po stylach i ogólne porady dotyczące pisania dobrej dokumentacji.