Obecnie zaczynam od Pythona i mam solidne podstawy PHP, aw PHP przyzwyczaiłem się używać javadoc
jako szablonu dokumentacji.
Zastanawiałem się, czy javadoc
ma swoje miejsce jako docstring
dokumentacja 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)
python
documentation
javadoc
docstring
JF Dion
źródło
źródło
Odpowiedzi:
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:
Lub rozszerzone o informacje o typie:
źródło
Replace template place holder with values.
zamiastreplaces template place holder with values
- Zwróć uwagę na zdanie, wielką literę na początku i kropkę (.) Na końcu.sphinx.ext.napoleon
rozszerzenie.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 ):
Przykład zaczerpnięty z dokumentacji napolskiej, do której link podano powyżej.
Obszerny przykład na wszystkich typach docstrings tutaj .
źródło
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
źródło
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.
źródło