CKTIS / Python
docstring — tekst dokumentacyjny
Docstring to zwykły literał tekstowy (nie f-string ani t-string), użyty jako pierwsza instrukcja modułu, klasy lub funkcji. Dokumentuje przeznaczenie obiektu i jest dostępny przez __doc__; nie jest komentarzem rozpoczynającym się od #.
Wersja: Python 3.14; repository image, production runtime not attested
Składnia
def function_name():
"""Describe the function's purpose."""
passdocstring to zwykły literał tekstowy (nie f-string ani t-string), użyty jako pierwsza instrukcja modułu, klasy lub funkcji, także metody. Python udostępnia go jako atrybut __doc__ obiektu. Narzędzia mogą wykorzystywać tę treść do prezentowania dokumentacji.
Ani formatowany literał tekstowy (f-string), ani szablonowy literał tekstowy (t-string) nie tworzy docstringa, nawet jeśli nie zawiera pól podstawienia i jest pierwszą instrukcją. Jeśli pierwszą instrukcją funkcji jest f"""Description.""", jej atrybut __doc__ ma wartość None.
Komentarz zaczynający się od # nie tworzy docstring. Samodzielny literał tekstowy umieszczony po innej instrukcji również nie staje się głównym docstring obiektu. Potrójne cudzysłowy """...""" są wygodnym zapisem, szczególnie dla wielu wierszy, ale same nie wystarczą: liczą się zarówno rodzaj literału, jak i jego położenie.
Zgodnie z konwencją pierwszy wiersz powinien krótko opisywać przeznaczenie obiektu, zaczynać się wielką literą i kończyć kropką. Dalszy opis oddziel pustym wierszem; w razie potrzeby wyjaśnij argumenty, wynik i skutki uboczne. Są to zalecenia dotyczące treści, a nie wymagania składni.
W przykładzie square.__doc__ udostępnia opis, a square(5) oblicza wynik niezależnie od dokumentacji. Opcja -OO usuwa docstringi, dlatego kod aplikacji nie powinien polegać na ich obecności.
Przykłady
def square(number):
"""Return the square of number."""
return number * number
print(square.__doc__)
print(square(5))
Wynik
Return the square of number. 25
Wyświetlony kod i zadeklarowany wynik zweryfikowano w odizolowanym środowisku metodą zapisaną w dowodzie weryfikacji tej dokładnej wersji.