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

162

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)
JF Dion
źródło
6
Istnieje również wiele innych odpowiedzi na to pytanie, na które jest to poprzednie pytanie .
Alex Dupuy

Odpowiedzi:

227

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
"""
Steven
źródło
7
co zrobisz, jeśli chcesz przerwać linię na długi opis? Jak by to wyglądało?
Skylar Saveland
6
Zobacz odniesienie do reStructuredText, aw szczególności listy pól: docutils.sourceforge.net/docs/ref/rst/…
Steven
6
Zwróć uwagę, że sposób wyrażenia tutaj nie jest zgodny z PEP 257 . Powinno to być Replace template place holder with values.zamiast replaces template place holder with values- Zwróć uwagę na zdanie, wielką literę na początku i kropkę (.) Na końcu.
kratenko
1
Od wersji 1.3 Sphinx obsługuje również nieco ładniejszy format poprzez sphinx.ext.napoleonrozszerzenie.
Petri,
3
Czy ktoś mógłby mi wskazać najlepszą dokumentację określającą te specjalne ciągi dokumentacyjne, takie jak „: param ____:” i „: return:”? Taki dokument wydaje się w tej chwili raczej trudny do znalezienia.
krumpelstiltskin
75

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 .

zdezorientowany00
źródło
20
dla wszystkich ludzi, którzy czytają dokumenty
Waylon Flinn
1
Zaktualizowano link do przewodnika po stylu Google Python
zdezorientowany 00
@ confused00 Jak mogę udokumentować, że moja metoda zwraca tablicę obiektów?
Cito,
1
Teraz jestem zmieszany ! argumenty czy parametry? stackoverflow.com/questions/1788923/parameter-vs-argument
shuva
25

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 '')
    """
srgerg
źródło
17
PEP257 nie mówi nic o faktycznym formatowaniu części argumentowej. Po prostu stwierdza, że ​​powinno być napisane i podaje przykład. Ale to tylko przykład. Dlatego zdecydowanie radziłbym używać konwencji Sphinx, ponieważ nie łamiesz PEP257 i używasz formatowania, które może zostać przeanalizowane przez sfinksa.
vaab
7
Z wyjątkiem tego, że pierwsza przedstawiona powyżej dokumentacja jest brzydka i zawiera wiele zbędnych informacji dla ludzi. Wolę używać konwencji sprawia, że mój kod źródłowy przyjemne czytać bez analizowany jest pierwszy
confused00
1

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.

David Cain
źródło