Baza wiedzyCentrum egzaminacyjne
PLPolski
Wybierz język13

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

docstring 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.

Źródła